Rework and enhance thread communications by nashif · Pull Request #144 · zephyrproject-rtos/reqmgmt

nashif · 2026-06-25T22:53:43Z

requirements: convert Thread Communication into an overview document
requirements: add Message Queue system and software requirements
requirements: add Pipe system and software requirements
requirements: add Polling system and software requirements

anobli · 2026-07-09T08:55:07Z

+COMPONENT: Message Queues
+TITLE: Message queue definition at compile time
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to define and initialize a message queue at compile time.


Should we not also talk about arguments as this is done in the next requirements ?

anobli · 2026-07-09T09:08:49Z

+COMPONENT: Message Queues
+TITLE: Message queue buffer dynamic allocation
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to initialize a message queue with a buffer that is dynamically allocated for a requested message size and maximum number of messages.


I found the sentence confusing. When I read the sentence, I am not sure if this the function that does the allocation of buffer, or, if the buffer is given as an argument.
The first option is the more obvious and is confirmed by the title but I think we should update the sentence to make it more obvious.

anobli · 2026-07-09T09:16:40Z

+STATUS: Draft
+TYPE: Functional
+COMPONENT: Message Queues
+TITLE: Message queue buffer dynamic allocation


This let's think that we only allocate a buffer whereas we also initialize the message queue

anobli · 2026-07-09T12:33:08Z

+COMPONENT: Message Queues
+TITLE: Peeking at a message
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to read the message at the front of a message queue without removing it.


I think we should mention that it could be done from ISR or thread

anobli · 2026-07-09T12:33:25Z

+COMPONENT: Message Queues
+TITLE: Peeking at a message by index
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to read a message at a specified index of a message queue without removing it.


parphane

Performed review on changes:

thread_communication update to list communication mechanisms and have 1 file per API. But I would consider removing the thread_comm file altogether
system requirements update to add mqueue, pipe and poll APIs files
software requirements reviewed individually and comments left

parphane · 2026-07-24T13:20:10Z

@@ -55,6 +55,15 @@ FILE: power_management.sdoc
 [DOCUMENT_FROM_FILE]
 FILE: thread_communication.sdoc


Agree with leaving the file to have 1 generic requirement that mentions the type of communications we want.
In the future, we may consider a "generic" RTOS requirements file to compile such requirements, instead of having 1 file with 1 requirement.
However, consider removing the file altogether, as it adds maintenance effort and contains no requirement, just text with inference to mechanisms, which may or may not be ambiguously seen as a requirement

Kept for now, per the agreement in the other thread: it anchors the Thread Communication section and inventories which mechanisms have their own documents, and it contains no requirement that could be ambiguously interpreted (it's a [TEXT] block only).

parphane · 2026-07-24T14:29:00Z

+COMPONENT: Message Queues
+TITLE: Send timeout expiry
+STATEMENT: >>>
+When space does not become available in a message queue within the specified time, the Zephyr RTOS shall return an error indicating that the message was not sent.


Consider reusing verbiage from above requirement, as in, replace "specified time" by "specified maximum time" or something similar. Also consider adding "When sending a message to a message queue" to provide proper context.
Could consider using a bullet point structure for ISRs:
When sending a message to a message queue, the Zephyr RTOS shall return an error indicating that the message was not sent when any of the following conditions is satisfied:

the caller is a thread and space does not become available in the message queue within the specified time

the caller is an ISR and no space is available in the message queue

parphane · 2026-07-24T14:37:07Z

+COMPONENT: Message Queues
+TITLE: Message retrieval order
+STATEMENT: >>>
+When messages are sent to the end of a message queue, the Zephyr RTOS shall return them to receivers in the order in which they were sent (first-in, first-out).


Consider removing req 9 and 18 altogether.
The mechanism is simple here, there is a function to receive the message at the front of the message queue.
Then there are mechanisms to put in front or back.

parphane · 2026-07-24T15:17:55Z

+COMPONENT: Polling
+TITLE: Supported poll event conditions
+STATEMENT: >>>
+The Zephyr RTOS shall support poll events that wait for the availability of a semaphore, a FIFO, a message queue, a pipe, and a poll signal.


If this is for a MAcro/Function please specify "shall provide a mechanism/compile-time mechanism"

deliberately not API-shaped, it constrains which condition types the wait mechanism (33-1) supports.

parphane · 2026-07-24T15:20:48Z

+COMPONENT: Polling
+TITLE: Poll signal object
+STATEMENT: >>>
+The Zephyr RTOS shall provide a poll signal object that a thread can wait on as a poll event.


Are we providing 1 object or a mechanism to initialize objects that threads can wait on as they poll?

parphane · 2026-07-24T15:26:41Z

+COMPONENT: Polling
+TITLE: Persistence of a raised poll signal
+STATEMENT: >>>
+While a poll signal has been raised and not reset, the Zephyr RTOS shall keep the signal in the signaled state.


Consider removing, there are requirements dictating signaled state change already (6 for reset, 7 to decide what value to raise).
If the objective is to prevent a signal to be "reraised", then consider modifying req 7 logic to prevent changing the value if it is in any other state than "unsignaled"

Reworded rather than removed, because the property it carries isn't derivable from 33-6/33-7/33-9: a raised signal is level-triggered: a poll wait that begins after the raise is still reported ready, until the signal is explicitly reset.

parphane · 2026-07-24T15:29:41Z

@@ -0,0 +1,151 @@
+[DOCUMENT]


Macros
5 - #define K_POLL_SIGNAL_INITIALIZER(obj)
#define K_POLL_EVENT_INITIALIZER(_event_type, _event_mode, _event_obj)
#define K_POLL_EVENT_STATIC_INITIALIZER(_event_type, _event_mode, _event_obj, event_tag)

Functions
void k_poll_event_init (struct k_poll_event *event, uint32_t type, int mode, void *obj)
1?, 2?, 3, 4 - int k_poll (struct k_poll_event *events, int num_events, k_timeout_t timeout)
6 - void k_poll_signal_init (struct k_poll_signal *sig)
9 - void k_poll_signal_reset (struct k_poll_signal *sig)
10 - void k_poll_signal_check (struct k_poll_signal *sig, unsigned int *signaled, int *result)
7, 8 - int k_poll_signal_raise (struct k_poll_signal *sig, int result)

It is unclear to me what requirements 1 2 are linked to.
Once clarified, let's check what requirements are covered by K_POLL_EVENT_INITIALIZER, K_POLL_EVENT_STATIC_INITIALIZER, k_poll_event_init

33-2 → the supported event condition types (a constraint on 33-1, not an API)

33-1/33-3/33-4 → k_poll

The Thread Communication document was a grab-bag with two non-requirements left over from the Excel import and one duplicate: - ZEP-SRS-3-1 ("Exchanging data between threads") was a vague umbrella whose user story was a note-to-self placeholder. - ZEP-SRS-3-2 ("Waiting for results during communication") embedded an editorial note in its statement and had "=N73" (a leftover spreadsheet cell reference) as its user story. - ZEP-SRS-3-6 ("Mailbox Kernel Primitive") duplicated the dedicated Mailboxes document. The remaining single-statement requirements for the message queue, pipe, and poll mechanisms (ZEP-SRS-3-3, 3-4, 3-5) are replaced by dedicated documents for each object, consistent with the per-object structure of the repository. Convert this document into overview text pointing to those documents. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Add a System requirement (ZEP-SYRS-31) for the message queue object and a dedicated Message Queues software requirements document (ZEP-SRS-31-*) with 17 atomic, implementation-free requirements covering definition (compile time, run time, dynamic allocation), sending (to back, to front, timeout, timeout expiry), receiving (FIFO order, timeout, timeout expiry), and inspection/management (peek, peek by index, purge, used and free counts, buffer cleanup). This replaces the single high-level message queue statement that previously lived in the Thread Communication document. The requirements reflect the currently implemented k_msgq API behavior following the Route 3s approach and link to the ZEP-SYRS-31 system parent. UIDs were generated with "strictdoc manage auto-uid". Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Add a System requirement (ZEP-SYRS-32) for the pipe object and a dedicated Pipes software requirements document (ZEP-SRS-32-*) with 10 atomic, implementation-free requirements covering definition (compile time, run time), writing and reading byte data, write and read timeouts, reset and close, and the error behavior for operations on a closed pipe or operations interrupted by a reset. This replaces the single high-level pipe statement that previously lived in the Thread Communication document. The requirements reflect the currently implemented k_pipe API behavior following the Route 3s approach and link to the ZEP-SYRS-32 system parent. UIDs were generated with "strictdoc manage auto-uid". Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Add a System requirement (ZEP-SYRS-33) for the polling mechanism and a dedicated Polling software requirements document (ZEP-SRS-33-*) with 10 atomic, implementation-free requirements covering waiting on multiple poll events (supported event conditions, timeout, reporting ready events) and poll signals (signal object, initialization, raising, persistence until reset, reset, and querying state and result). This replaces the single high-level poll statement that previously lived in the Thread Communication document. The requirements reflect the currently implemented k_poll API behavior following the Route 3s approach and link to the ZEP-SYRS-33 system parent. UIDs were generated with "strictdoc manage auto-uid". Signed-off-by: Anas Nashif <anas.nashif@intel.com>

parphane mentioned this pull request Jun 30, 2026

Thread Requirements #24

Open

3 tasks

anobli reviewed Jul 9, 2026

View reviewed changes

nashif force-pushed the topic/req/thread_comm_001 branch from b990034 to 3b9f70e Compare July 9, 2026 23:12

nashif requested review from nicpappler, parphane and tobiaskaestner as code owners July 9, 2026 23:12

This was referenced Jul 24, 2026

Pipes Requirements #62

Open

Message Queue requirements #111

Open

Async Polling Requirements #98

Open

parphane requested changes Jul 24, 2026

View reviewed changes

nashif added 4 commits July 24, 2026 15:58

nashif force-pushed the topic/req/thread_comm_001 branch from 3b9f70e to 35db956 Compare July 24, 2026 20:16

nashif requested a review from parphane July 24, 2026 23:02

		@@ -55,6 +55,15 @@ FILE: power_management.sdoc
		[DOCUMENT_FROM_FILE]
		FILE: thread_communication.sdoc

Uh oh!

Conversation

nashif commented Jun 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

parphane left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants