From 0857c4e098f1c126bb2810d4f2dec231de425c3e Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 12 Mar 2025 16:24:35 -0400 Subject: [PATCH 1/8] software: Add Mailbox Requirements created by Perplexity Used Perplexity to automatically create requirements for the mailbox module and added them to a new sdoc signed-off-by: Joel Key --- docs/software_requirements/index.sdoc | 3 + docs/software_requirements/mailbox.sdoc | 353 ++++++++++++++++++++++++ 2 files changed, 356 insertions(+) create mode 100644 docs/software_requirements/mailbox.sdoc diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index 4aae44eb..c27f367f 100644 --- a/docs/software_requirements/index.sdoc +++ b/docs/software_requirements/index.sdoc @@ -78,3 +78,6 @@ FILE: lifos.sdoc [DOCUMENT_FROM_FILE] FILE: fifos.sdoc + +[DOCUMENT_FROM_FILE] +FILE: mailbox.sdoc diff --git a/docs/software_requirements/mailbox.sdoc b/docs/software_requirements/mailbox.sdoc new file mode 100644 index 00000000..a9729f87 --- /dev/null +++ b/docs/software_requirements/mailbox.sdoc @@ -0,0 +1,353 @@ +[DOCUMENT] +TITLE: Mailbox +REQ_PREFIX: ZEP-SRS-MBOX- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-1 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Mailbox Initialization +STATEMENT: >>> +The Mailbox module shall provide a function k_mbox_init to initialize a mailbox before it can be used. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to initialize a mailbox instance so that it is ready to be used for message exchange between threads. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-2 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Queue Initialization +STATEMENT: >>> +When k_mbox_init is called on a mailbox, the Mailbox module shall set both the send queue and receive queue of that mailbox to empty. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-3 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Static Mailbox Definition +STATEMENT: >>> +The Mailbox module shall provide a macro K_MBOX_DEFINE to statically define and initialize a mailbox. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to statically define and initialize a mailbox at compile time so that it is available immediately without runtime initialization. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-4 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Size Support +STATEMENT: >>> +The Mailbox module shall support message data containing zero or more bytes. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-5 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Variable Message Size +STATEMENT: >>> +The Mailbox module shall support messages of any size that the application requires. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to send messages of different sizes using the same mailbox so that I can efficiently communicate different types of information between threads. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-6 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Descriptor Usage +STATEMENT: >>> +The Mailbox module shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-7 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Descriptor Updates +STATEMENT: >>> +The Mailbox module shall update message descriptor fields during the exchange to allow both threads to know what has occurred during the message exchange process. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-8 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Buffer Data Transfer +STATEMENT: >>> +Where message data is in a buffer, the Mailbox module shall correctly handle the data transfer between the sending and receiving threads. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-9 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Empty Message Support +STATEMENT: >>> +Where message data is non-existent (i.e., an empty message), the Mailbox module shall correctly handle the message exchange without requiring buffer allocation. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to send signals or notifications that don't carry data so that I can trigger actions in other threads without the overhead of data transfer. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-10 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Synchronous Message Sending +STATEMENT: >>> +The Mailbox module shall provide a function k_mbox_put for a thread to send a message in a synchronous manner with a timeout parameter. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to send a message and wait for it to be processed so that I can be sure the message was received before continuing execution. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-11 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Asynchronous Message Sending +STATEMENT: >>> +The Mailbox module shall provide a function k_mbox_async_put for a thread to send a message in an asynchronous manner. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-12 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Synchronous Sending Behavior +STATEMENT: >>> +When k_mbox_put is called, the Mailbox module shall block the sending thread until a receiver processes the message or the timeout expires. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-13 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Asynchronous Sending Behavior +STATEMENT: >>> +When k_mbox_async_put is called, the Mailbox module shall not wait for a receiver to process the message before returning to the caller. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-14 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Asynchronous Completion Signaling +STATEMENT: >>> +Where a semaphore is provided to k_mbox_async_put, the Mailbox module shall give the semaphore when the message has been both received and completely processed by the receiver. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-15 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Synchronous Send Timeout Handling +STATEMENT: >>> +If the synchronous message send operation times out before a receiver processes the message, the Mailbox module shall return an appropriate timeout error code to the sending thread. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-16 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Reception +STATEMENT: >>> +The Mailbox module shall provide a function k_mbox_get for a thread to receive a message with a timeout parameter. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to receive messages from other threads with control over how long to wait for a message to arrive. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-17 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Data Retrieval +STATEMENT: >>> +The Mailbox module shall provide a function k_mbox_data_get for a thread to retrieve mailbox message data into a buffer and complete the message processing. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to extract message data into my buffer after message reception so that I can process the information contained in the message. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-18 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Reception Blocking +STATEMENT: >>> +When k_mbox_get is called and no message is available, the Mailbox module shall block the receiving thread until a message is available or the timeout expires. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-19 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Message Reception Timeout Handling +STATEMENT: >>> +If the message receive operation times out before a message becomes available, the Mailbox module shall return an appropriate timeout error code to the receiving thread. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to arrive so that I can implement fallback behavior if communication takes too long. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-20 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Thread-Only Message Exchange +STATEMENT: >>> +The Mailbox module shall allow only threads, not ISRs, to exchange messages using the mailbox functions. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-21 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Single-Receiver Message Delivery +STATEMENT: >>> +The Mailbox module shall ensure that each message may be received by only one thread (i.e., point-to-multipoint and broadcast messaging is not supported). +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-22 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Non-Anonymous Messaging +STATEMENT: >>> +The Mailbox module shall handle messages non-anonymously, allowing both the sending and receiving threads to know the identity of the other thread. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to identify the source or destination of messages so that I can implement thread-specific handling of message content. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-23 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Receiver Thread Queuing +STATEMENT: >>> +While a thread is waiting to receive a message, the Mailbox module shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-24 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Priority-Based Message Delivery +STATEMENT: >>> +When multiple threads are waiting on an empty mailbox, the Mailbox module shall deliver the next message to the highest priority thread that has waited longest. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want message delivery to respect thread priorities so that higher priority tasks receive messages before lower priority ones. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-25 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: FIFO Message Delivery +STATEMENT: >>> +When multiple messages are available in the send queue, the Mailbox module shall deliver them in FIFO (First In, First Out) order to waiting threads. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-26 +STATUS: Draft +TYPE: Non-Functional +COMPONENT: Mailbox +TITLE: Mailbox Quantity Support +STATEMENT: >>> +The Mailbox module shall support an arbitrary number of mailboxes, limited only by available RAM in the system. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my application needs without arbitrary limitations so that I can design my communication architecture freely. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-27 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Resource Cleanup +STATEMENT: >>> +The Mailbox module shall ensure proper cleanup of message resources when operations are canceled or time out to prevent resource leaks. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want the system to automatically clean up resources when operations fail or time out so that my application doesn't experience memory leaks. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-28 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Error Reporting +STATEMENT: >>> +If an error occurs during any mailbox operation, the Mailbox module shall return an appropriate error code indicating the type of failure. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to receive specific error codes when mailbox operations fail so that I can implement appropriate error handling and recovery. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-MBOX-29 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailbox +TITLE: Invalid Parameter Handling +STATEMENT: >>> +The Mailbox module shall handle invalid parameters by returning appropriate error codes rather than causing system failures. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want the system to validate my inputs and return errors rather than crash when I provide invalid parameters so that I can develop more robust applications. +<<< + From 7fc3c3d62f67565ec28582466f5dbbc207673b4b Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 12 Mar 2025 16:24:45 -0400 Subject: [PATCH 2/8] software: Manual review and cleanup of generated reqts Performed a manual review and cleanup of the generated requirements. Compared the requirements to the Mailboxes documentation page for functionality. Generalized the requirements to remove function names. signed-off-by: Joel Key --- docs/software_requirements/index.sdoc | 3 + .../{mailbox.sdoc => mailboxes.sdoc} | 181 +++++++++--------- 2 files changed, 93 insertions(+), 91 deletions(-) rename docs/software_requirements/{mailbox.sdoc => mailboxes.sdoc} (77%) diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index c27f367f..466c722f 100644 --- a/docs/software_requirements/index.sdoc +++ b/docs/software_requirements/index.sdoc @@ -81,3 +81,6 @@ FILE: fifos.sdoc [DOCUMENT_FROM_FILE] FILE: mailbox.sdoc + +[DOCUMENT_FROM_FILE] +FILE: mailboxes.sdoc diff --git a/docs/software_requirements/mailbox.sdoc b/docs/software_requirements/mailboxes.sdoc similarity index 77% rename from docs/software_requirements/mailbox.sdoc rename to docs/software_requirements/mailboxes.sdoc index a9729f87..4e04f871 100644 --- a/docs/software_requirements/mailbox.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -1,6 +1,6 @@ [DOCUMENT] -TITLE: Mailbox -REQ_PREFIX: ZEP-SRS-MBOX- +TITLE: Mailboxes +REQ_PREFIX: ZEP-SRS-22- [GRAMMAR] IMPORT_FROM_FILE: software_requirements.sgra @@ -11,56 +11,56 @@ SPDX-License-Identifier: Apache-2.0 <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-1 +UID: ZEP-SRS-22-1 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Mailbox Initialization +COMPONENT: Mailboxes +TITLE: Mailbox Initialization - Run Time STATEMENT: >>> -The Mailbox module shall provide a function k_mbox_init to initialize a mailbox before it can be used. +The Mailbox module shall provide a mechanism to define and initialize a mailbox at run time. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to initialize a mailbox instance so that it is ready to be used for message exchange between threads. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-2 +UID: ZEP-SRS-22-2 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Queue Initialization +COMPONENT: Mailboxes +TITLE: Mailbox Initialization - Compile Time STATEMENT: >>> -When k_mbox_init is called on a mailbox, the Mailbox module shall set both the send queue and receive queue of that mailbox to empty. +The Mailbox module shall provide a mechanism to statically define and initialize a mailbox at compile time. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to statically define and initialize a mailbox at compile time so that it is available immediately without runtime initialization. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-3 +UID: ZEP-SRS-22-3 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Static Mailbox Definition +COMPONENT: Mailboxes +TITLE: Queue Initialization STATEMENT: >>> -The Mailbox module shall provide a macro K_MBOX_DEFINE to statically define and initialize a mailbox. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want to be able to statically define and initialize a mailbox at compile time so that it is available immediately without runtime initialization. +When a mailbox is initialized, the Mailbox module shall set both the send queue and receive queue of that mailbox to empty. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-4 +UID: ZEP-SRS-22-4 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Size Support STATEMENT: >>> The Mailbox module shall support message data containing zero or more bytes. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-5 +UID: ZEP-SRS-22-5 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Variable Message Size STATEMENT: >>> The Mailbox module shall support messages of any size that the application requires. @@ -70,40 +70,40 @@ As a Zephyr RTOS developer, I want to be able to send messages of different size <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-6 +UID: ZEP-SRS-22-6 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Descriptor Usage STATEMENT: >>> The Mailbox module shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-7 +UID: ZEP-SRS-22-7 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Descriptor Updates STATEMENT: >>> The Mailbox module shall update message descriptor fields during the exchange to allow both threads to know what has occurred during the message exchange process. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-8 +UID: ZEP-SRS-22-8 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Buffer Data Transfer STATEMENT: >>> Where message data is in a buffer, the Mailbox module shall correctly handle the data transfer between the sending and receiving threads. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-9 +UID: ZEP-SRS-22-9 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Empty Message Support STATEMENT: >>> Where message data is non-existent (i.e., an empty message), the Mailbox module shall correctly handle the message exchange without requiring buffer allocation. @@ -113,118 +113,118 @@ As a Zephyr RTOS developer, I want to be able to send signals or notifications t <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-10 +UID: ZEP-SRS-22-10 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Synchronous Message Sending STATEMENT: >>> -The Mailbox module shall provide a function k_mbox_put for a thread to send a message in a synchronous manner with a timeout parameter. +The Mailbox module shall provide a mechanism for a thread to send a message in a synchronous manner with a timeout parameter. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message and wait for it to be processed so that I can be sure the message was received before continuing execution. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-11 +UID: ZEP-SRS-22-11 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Asynchronous Message Sending +COMPONENT: Mailboxes +TITLE: Synchronous Sending Behavior STATEMENT: >>> -The Mailbox module shall provide a function k_mbox_async_put for a thread to send a message in an asynchronous manner. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. +When k_mbox_put is called, the Mailbox module shall block the sending thread until a receiver processes the message or the timeout expires. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-12 +UID: ZEP-SRS-22-12 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Synchronous Sending Behavior +COMPONENT: Mailboxes +TITLE: Synchronous Send Timeout Handling STATEMENT: >>> -When k_mbox_put is called, the Mailbox module shall block the sending thread until a receiver processes the message or the timeout expires. +If the synchronous message send operation times out before a receiver processes the message, the Mailbox module shall return an appropriate timeout error code to the sending thread. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-13 +UID: ZEP-SRS-22-13 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Asynchronous Sending Behavior +COMPONENT: Mailboxes +TITLE: Asynchronous Message Sending STATEMENT: >>> -When k_mbox_async_put is called, the Mailbox module shall not wait for a receiver to process the message before returning to the caller. +The Mailbox module shall provide a mechanism for a thread to send a message in an asynchronous manner. +<<< +USER_STORY: >>> +As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-14 +UID: ZEP-SRS-22-14 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Asynchronous Completion Signaling +COMPONENT: Mailboxes +TITLE: Asynchronous Sending Behavior STATEMENT: >>> -Where a semaphore is provided to k_mbox_async_put, the Mailbox module shall give the semaphore when the message has been both received and completely processed by the receiver. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. +When an asynchronous message is sent, the Mailbox module shall not wait for a receiver to process the message before returning to the caller. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-15 +UID: ZEP-SRS-22-15 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox -TITLE: Synchronous Send Timeout Handling +COMPONENT: Mailboxes +TITLE: Asynchronous Completion Signaling STATEMENT: >>> -If the synchronous message send operation times out before a receiver processes the message, the Mailbox module shall return an appropriate timeout error code to the sending thread. +When an asynchronous send command receives a semaphore, the Mailbox module shall give the semaphore when the message has been both received and completely processed by the receiver. <<< USER_STORY: >>> -As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. +As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-16 +UID: ZEP-SRS-22-16 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Reception STATEMENT: >>> -The Mailbox module shall provide a function k_mbox_get for a thread to receive a message with a timeout parameter. +The Mailbox module shall provide a mechanism for a thread to receive a message with a timeout parameter. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to receive messages from other threads with control over how long to wait for a message to arrive. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-17 +UID: ZEP-SRS-22-17 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Data Retrieval STATEMENT: >>> -The Mailbox module shall provide a function k_mbox_data_get for a thread to retrieve mailbox message data into a buffer and complete the message processing. +The Mailbox module shall provide a mechanism for a thread to retrieve mailbox message data into a buffer and complete the message processing. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to extract message data into my buffer after message reception so that I can process the information contained in the message. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-18 +UID: ZEP-SRS-22-18 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Reception Blocking STATEMENT: >>> -When k_mbox_get is called and no message is available, the Mailbox module shall block the receiving thread until a message is available or the timeout expires. +When message reception is requested and no message is available, the Mailbox module shall block the receiving thread until a message is available or the timeout expires. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-19 +UID: ZEP-SRS-22-19 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Message Reception Timeout Handling STATEMENT: >>> If the message receive operation times out before a message becomes available, the Mailbox module shall return an appropriate timeout error code to the receiving thread. @@ -234,30 +234,30 @@ As a Zephyr RTOS developer, I want to be able to limit how long my thread waits <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-20 +UID: ZEP-SRS-22-20 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Thread-Only Message Exchange STATEMENT: >>> The Mailbox module shall allow only threads, not ISRs, to exchange messages using the mailbox functions. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-21 +UID: ZEP-SRS-22-21 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Single-Receiver Message Delivery STATEMENT: >>> The Mailbox module shall ensure that each message may be received by only one thread (i.e., point-to-multipoint and broadcast messaging is not supported). <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-22 +UID: ZEP-SRS-22-22 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Non-Anonymous Messaging STATEMENT: >>> The Mailbox module shall handle messages non-anonymously, allowing both the sending and receiving threads to know the identity of the other thread. @@ -267,20 +267,20 @@ As a Zephyr RTOS developer, I want to be able to identify the source or destinat <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-23 +UID: ZEP-SRS-22-23 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Receiver Thread Queuing STATEMENT: >>> While a thread is waiting to receive a message, the Mailbox module shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-24 +UID: ZEP-SRS-22-24 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Priority-Based Message Delivery STATEMENT: >>> When multiple threads are waiting on an empty mailbox, the Mailbox module shall deliver the next message to the highest priority thread that has waited longest. @@ -290,20 +290,20 @@ As a Zephyr RTOS developer, I want message delivery to respect thread priorities <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-25 +UID: ZEP-SRS-22-25 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: FIFO Message Delivery STATEMENT: >>> When multiple messages are available in the send queue, the Mailbox module shall deliver them in FIFO (First In, First Out) order to waiting threads. <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-26 +UID: ZEP-SRS-22-26 STATUS: Draft TYPE: Non-Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Mailbox Quantity Support STATEMENT: >>> The Mailbox module shall support an arbitrary number of mailboxes, limited only by available RAM in the system. @@ -313,10 +313,10 @@ As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-27 +UID: ZEP-SRS-22-27 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Resource Cleanup STATEMENT: >>> The Mailbox module shall ensure proper cleanup of message resources when operations are canceled or time out to prevent resource leaks. @@ -326,10 +326,10 @@ As a Zephyr RTOS developer, I want the system to automatically clean up resource <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-28 +UID: ZEP-SRS-22-28 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Error Reporting STATEMENT: >>> If an error occurs during any mailbox operation, the Mailbox module shall return an appropriate error code indicating the type of failure. @@ -339,10 +339,10 @@ As a Zephyr RTOS developer, I want to receive specific error codes when mailbox <<< [REQUIREMENT] -UID: ZEP-SRS-MBOX-29 +UID: ZEP-SRS-22-29 STATUS: Draft TYPE: Functional -COMPONENT: Mailbox +COMPONENT: Mailboxes TITLE: Invalid Parameter Handling STATEMENT: >>> The Mailbox module shall handle invalid parameters by returning appropriate error codes rather than causing system failures. @@ -350,4 +350,3 @@ The Mailbox module shall handle invalid parameters by returning appropriate erro USER_STORY: >>> As a Zephyr RTOS developer, I want the system to validate my inputs and return errors rather than crash when I provide invalid parameters so that I can develop more robust applications. <<< - From 5f41310ff04d0a73ef228daa5d63899730157b98 Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 12 Mar 2025 16:24:54 -0400 Subject: [PATCH 3/8] system: Add Mailboxes Requirement Added a basic System Requirement for the Mailboxes functionality. signed-off-by: Joel Key --- docs/system_requirements/index.sdoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/system_requirements/index.sdoc b/docs/system_requirements/index.sdoc index cafa9b89..2b3323b5 100644 --- a/docs/system_requirements/index.sdoc +++ b/docs/system_requirements/index.sdoc @@ -353,3 +353,14 @@ The Zephyr RTOS shall implement FIFOs which can be used to pass data between thr <<< [[/SECTION]] +[/SECTION] + +[SECTION] +TITLE: Mailboxes +COMPONENT: Mailboxes +TITLE: Mailboxes +STATEMENT: >>> +The Zephyr RTOS shall provide a framework to pass messages between threads. +<<< + +[/SECTION] From 485570584d317f7ca02b588adcb054a197c5b734 Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 12 Mar 2025 16:25:17 -0400 Subject: [PATCH 4/8] software: trace software to system req Linked the newly created Mailboxes Software Requirements to the Generic System Requirement. signed-off-by: Joel Key --- docs/software_requirements/mailboxes.sdoc | 87 +++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc index 4e04f871..f3fc2e4d 100644 --- a/docs/software_requirements/mailboxes.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -22,6 +22,9 @@ The Mailbox module shall provide a mechanism to define and initialize a mailbox USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to initialize a mailbox instance so that it is ready to be used for message exchange between threads. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-2 @@ -35,6 +38,9 @@ The Mailbox module shall provide a mechanism to statically define and initialize USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to statically define and initialize a mailbox at compile time so that it is available immediately without runtime initialization. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-3 @@ -45,6 +51,9 @@ TITLE: Queue Initialization STATEMENT: >>> When a mailbox is initialized, the Mailbox module shall set both the send queue and receive queue of that mailbox to empty. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-4 @@ -55,6 +64,9 @@ TITLE: Message Size Support STATEMENT: >>> The Mailbox module shall support message data containing zero or more bytes. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-5 @@ -68,6 +80,9 @@ The Mailbox module shall support messages of any size that the application requi USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send messages of different sizes using the same mailbox so that I can efficiently communicate different types of information between threads. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-6 @@ -78,6 +93,9 @@ TITLE: Message Descriptor Usage STATEMENT: >>> The Mailbox module shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-7 @@ -88,6 +106,9 @@ TITLE: Message Descriptor Updates STATEMENT: >>> The Mailbox module shall update message descriptor fields during the exchange to allow both threads to know what has occurred during the message exchange process. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-8 @@ -98,6 +119,9 @@ TITLE: Buffer Data Transfer STATEMENT: >>> Where message data is in a buffer, the Mailbox module shall correctly handle the data transfer between the sending and receiving threads. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-9 @@ -111,6 +135,9 @@ Where message data is non-existent (i.e., an empty message), the Mailbox module USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send signals or notifications that don't carry data so that I can trigger actions in other threads without the overhead of data transfer. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-10 @@ -124,6 +151,9 @@ The Mailbox module shall provide a mechanism for a thread to send a message in a USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message and wait for it to be processed so that I can be sure the message was received before continuing execution. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-11 @@ -134,6 +164,9 @@ TITLE: Synchronous Sending Behavior STATEMENT: >>> When k_mbox_put is called, the Mailbox module shall block the sending thread until a receiver processes the message or the timeout expires. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-12 @@ -147,6 +180,9 @@ If the synchronous message send operation times out before a receiver processes USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-13 @@ -160,6 +196,9 @@ The Mailbox module shall provide a mechanism for a thread to send a message in a USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-14 @@ -170,6 +209,9 @@ TITLE: Asynchronous Sending Behavior STATEMENT: >>> When an asynchronous message is sent, the Mailbox module shall not wait for a receiver to process the message before returning to the caller. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-15 @@ -183,6 +225,9 @@ When an asynchronous send command receives a semaphore, the Mailbox module shall USER_STORY: >>> As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-16 @@ -196,6 +241,9 @@ The Mailbox module shall provide a mechanism for a thread to receive a message w USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to receive messages from other threads with control over how long to wait for a message to arrive. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-17 @@ -209,6 +257,9 @@ The Mailbox module shall provide a mechanism for a thread to retrieve mailbox me USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to extract message data into my buffer after message reception so that I can process the information contained in the message. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-18 @@ -219,6 +270,9 @@ TITLE: Message Reception Blocking STATEMENT: >>> When message reception is requested and no message is available, the Mailbox module shall block the receiving thread until a message is available or the timeout expires. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-19 @@ -232,6 +286,9 @@ If the message receive operation times out before a message becomes available, t USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to arrive so that I can implement fallback behavior if communication takes too long. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-20 @@ -242,6 +299,9 @@ TITLE: Thread-Only Message Exchange STATEMENT: >>> The Mailbox module shall allow only threads, not ISRs, to exchange messages using the mailbox functions. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-21 @@ -252,6 +312,9 @@ TITLE: Single-Receiver Message Delivery STATEMENT: >>> The Mailbox module shall ensure that each message may be received by only one thread (i.e., point-to-multipoint and broadcast messaging is not supported). <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-22 @@ -265,6 +328,9 @@ The Mailbox module shall handle messages non-anonymously, allowing both the send USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to identify the source or destination of messages so that I can implement thread-specific handling of message content. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-23 @@ -275,6 +341,9 @@ TITLE: Receiver Thread Queuing STATEMENT: >>> While a thread is waiting to receive a message, the Mailbox module shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-24 @@ -288,6 +357,9 @@ When multiple threads are waiting on an empty mailbox, the Mailbox module shall USER_STORY: >>> As a Zephyr RTOS developer, I want message delivery to respect thread priorities so that higher priority tasks receive messages before lower priority ones. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-25 @@ -298,6 +370,9 @@ TITLE: FIFO Message Delivery STATEMENT: >>> When multiple messages are available in the send queue, the Mailbox module shall deliver them in FIFO (First In, First Out) order to waiting threads. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-26 @@ -311,6 +386,9 @@ The Mailbox module shall support an arbitrary number of mailboxes, limited only USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my application needs without arbitrary limitations so that I can design my communication architecture freely. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-27 @@ -324,6 +402,9 @@ The Mailbox module shall ensure proper cleanup of message resources when operati USER_STORY: >>> As a Zephyr RTOS developer, I want the system to automatically clean up resources when operations fail or time out so that my application doesn't experience memory leaks. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-28 @@ -337,6 +418,9 @@ If an error occurs during any mailbox operation, the Mailbox module shall return USER_STORY: >>> As a Zephyr RTOS developer, I want to receive specific error codes when mailbox operations fail so that I can implement appropriate error handling and recovery. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 [REQUIREMENT] UID: ZEP-SRS-22-29 @@ -350,3 +434,6 @@ The Mailbox module shall handle invalid parameters by returning appropriate erro USER_STORY: >>> As a Zephyr RTOS developer, I want the system to validate my inputs and return errors rather than crash when I provide invalid parameters so that I can develop more robust applications. <<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-22 From 8788a500e1ae993e4b3266c4d3b12254ac3b1f1e Mon Sep 17 00:00:00 2001 From: Joel Key Date: Mon, 17 Mar 2025 13:40:34 -0400 Subject: [PATCH 5/8] mailbox-requirements: Update Requirements after Initial Feedback Updated requirements based on the feedback after the initial requirement review. signed-off-by: Joel Key --- docs/software_requirements/mailboxes.sdoc | 173 +++++++--------------- docs/system_requirements/index.sdoc | 2 +- 2 files changed, 52 insertions(+), 123 deletions(-) diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc index f3fc2e4d..9575766f 100644 --- a/docs/software_requirements/mailboxes.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -15,9 +15,9 @@ UID: ZEP-SRS-22-1 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: Mailbox Initialization - Run Time +TITLE: Mailbox Initialization At Run Time STATEMENT: >>> -The Mailbox module shall provide a mechanism to define and initialize a mailbox at run time. +The Zephyr RTOS shall provide a mechanism to define and initialize a mailbox at run time. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to initialize a mailbox instance so that it is ready to be used for message exchange between threads. @@ -31,9 +31,9 @@ UID: ZEP-SRS-22-2 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: Mailbox Initialization - Compile Time +TITLE: Mailbox Initialization At Compile Time STATEMENT: >>> -The Mailbox module shall provide a mechanism to statically define and initialize a mailbox at compile time. +The Zephyr RTOS shall provide a mechanism to statically define and initialize a mailbox object at compile time. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to statically define and initialize a mailbox at compile time so that it is available immediately without runtime initialization. @@ -49,7 +49,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Queue Initialization STATEMENT: >>> -When a mailbox is initialized, the Mailbox module shall set both the send queue and receive queue of that mailbox to empty. +When a mailbox is initialized, the Zephyr RTOS shall set both the send queue and receive queue of that mailbox to empty. <<< RELATIONS: - TYPE: Parent @@ -62,20 +62,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Message Size Support STATEMENT: >>> -The Mailbox module shall support message data containing zero or more bytes. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - -[REQUIREMENT] -UID: ZEP-SRS-22-5 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Variable Message Size -STATEMENT: >>> -The Mailbox module shall support messages of any size that the application requires. +The Zephyr RTOS shall support messages containing zero or more bytes of data. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send messages of different sizes using the same mailbox so that I can efficiently communicate different types of information between threads. @@ -85,52 +72,39 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-6 +UID: ZEP-SRS-22-5 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Message Descriptor Usage STATEMENT: >>> -The Mailbox module shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. +The Zephyr RTOS shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-7 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Message Descriptor Updates -STATEMENT: >>> -The Mailbox module shall update message descriptor fields during the exchange to allow both threads to know what has occurred during the message exchange process. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - -[REQUIREMENT] -UID: ZEP-SRS-22-8 +UID: ZEP-SRS-22-6 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: Buffer Data Transfer +TITLE: Mailbox Data Transfer STATEMENT: >>> -Where message data is in a buffer, the Mailbox module shall correctly handle the data transfer between the sending and receiving threads. +The Zephyr RTOS shall handle the data transfer between mailbox objects of the sending and receiving threads. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-9 +UID: ZEP-SRS-22-7 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Empty Message Support STATEMENT: >>> -Where message data is non-existent (i.e., an empty message), the Mailbox module shall correctly handle the message exchange without requiring buffer allocation. +Where message data is non-existent (i.e., an empty message), the Zephyr RTOS shall correctly handle the message exchange without requiring buffer allocation. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send signals or notifications that don't carry data so that I can trigger actions in other threads without the overhead of data transfer. @@ -140,13 +114,13 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-10 +UID: ZEP-SRS-22-8 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Synchronous Message Sending STATEMENT: >>> -The Mailbox module shall provide a mechanism for a thread to send a message in a synchronous manner with a timeout parameter. +The Zephyr RTOS shall provide a mechanism for a thread to send message via a mailbox object in a synchronous manner with a timeout parameter. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message and wait for it to be processed so that I can be sure the message was received before continuing execution. @@ -156,26 +130,26 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-11 +UID: ZEP-SRS-22-9 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Synchronous Sending Behavior STATEMENT: >>> -When k_mbox_put is called, the Mailbox module shall block the sending thread until a receiver processes the message or the timeout expires. +When a synchronous message is sent, the Zephyr RTOS shall block the sending thread until a receiver processes the message or the timeout expires. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-12 +UID: ZEP-SRS-22-10 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Synchronous Send Timeout Handling STATEMENT: >>> -If the synchronous message send operation times out before a receiver processes the message, the Mailbox module shall return an appropriate timeout error code to the sending thread. +If the synchronous message send operation times out before a receiver processes the message, the Zephyr RTOS shall return an appropriate timeout error code to the sending thread. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. @@ -185,13 +159,13 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-13 +UID: ZEP-SRS-22-11 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Asynchronous Message Sending STATEMENT: >>> -The Mailbox module shall provide a mechanism for a thread to send a message in an asynchronous manner. +The Zephyr RTOS shall provide a mechanism for a thread to send a message in an asynchronous manner. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. @@ -201,26 +175,26 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-14 +UID: ZEP-SRS-22-12 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Asynchronous Sending Behavior STATEMENT: >>> -When an asynchronous message is sent, the Mailbox module shall not wait for a receiver to process the message before returning to the caller. +When an asynchronous message is sent, the Zephyr RTOS shall not wait for a receiver to process the message before returning to the caller. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-15 +UID: ZEP-SRS-22-13 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Asynchronous Completion Signaling STATEMENT: >>> -When an asynchronous send command receives a semaphore, the Mailbox module shall give the semaphore when the message has been both received and completely processed by the receiver. +When a sending thread provides a semaphore during an asynchronous send command using a mailbox object, the Zephyr RTOS shall give the semaphore when the message has been both received and completely processed by the receiver. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. @@ -230,13 +204,13 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-16 +UID: ZEP-SRS-22-14 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Message Reception STATEMENT: >>> -The Mailbox module shall provide a mechanism for a thread to receive a message with a timeout parameter. +The Zephyr RTOS shall provide a mechanism for a thread to receive a message via a mailbox object with a timeout parameter. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to receive messages from other threads with control over how long to wait for a message to arrive. @@ -246,13 +220,13 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-17 +UID: ZEP-SRS-22-15 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Message Data Retrieval STATEMENT: >>> -The Mailbox module shall provide a mechanism for a thread to retrieve mailbox message data into a buffer and complete the message processing. +The Zephyr RTOS shall provide a mechanism for a thread to retrieve message data via a mailbox object into a buffer and complete the message processing. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to extract message data into my buffer after message reception so that I can process the information contained in the message. @@ -262,26 +236,26 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-18 +UID: ZEP-SRS-22-16 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Message Reception Blocking STATEMENT: >>> -When message reception is requested and no message is available, the Mailbox module shall block the receiving thread until a message is available or the timeout expires. +When a receiving thread requests a message via a mailbox object and no message is available, the Zephyr RTOS shall block the receiving thread until a message is available or the timeout expires. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-19 +UID: ZEP-SRS-22-17 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Message Reception Timeout Handling STATEMENT: >>> -If the message receive operation times out before a message becomes available, the Mailbox module shall return an appropriate timeout error code to the receiving thread. +If the message receive operation times out before a message becomes available, the Zephyr RTOS shall return an appropriate timeout error code to the receiving thread. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to arrive so that I can implement fallback behavior if communication takes too long. @@ -291,39 +265,13 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-20 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Thread-Only Message Exchange -STATEMENT: >>> -The Mailbox module shall allow only threads, not ISRs, to exchange messages using the mailbox functions. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - -[REQUIREMENT] -UID: ZEP-SRS-22-21 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Single-Receiver Message Delivery -STATEMENT: >>> -The Mailbox module shall ensure that each message may be received by only one thread (i.e., point-to-multipoint and broadcast messaging is not supported). -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - -[REQUIREMENT] -UID: ZEP-SRS-22-22 +UID: ZEP-SRS-22-18 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Non-Anonymous Messaging STATEMENT: >>> -The Mailbox module shall handle messages non-anonymously, allowing both the sending and receiving threads to know the identity of the other thread. +The Zephyr RTOS shall handle message exchange via a mailbox object non-anonymously, allowing both the sending and receiving threads to know the identity of the other thread. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to identify the source or destination of messages so that I can implement thread-specific handling of message content. @@ -333,26 +281,26 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-23 +UID: ZEP-SRS-22-19 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Receiver Thread Queuing STATEMENT: >>> -While a thread is waiting to receive a message, the Mailbox module shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. +While a thread is waiting to receive a message via a mailbox object, the Zephyr RTOS shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-24 +UID: ZEP-SRS-22-20 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Priority-Based Message Delivery STATEMENT: >>> -When multiple threads are waiting on an empty mailbox, the Mailbox module shall deliver the next message to the highest priority thread that has waited longest. +When multiple threads are waiting on an empty mailbox object, the Zephyr RTOS shall deliver the next message to the highest priority thread. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want message delivery to respect thread priorities so that higher priority tasks receive messages before lower priority ones. @@ -362,74 +310,55 @@ RELATIONS: VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-25 +UID: ZEP-SRS-22-21 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: FIFO Message Delivery -STATEMENT: >>> -When multiple messages are available in the send queue, the Mailbox module shall deliver them in FIFO (First In, First Out) order to waiting threads. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - -[REQUIREMENT] -UID: ZEP-SRS-22-26 -STATUS: Draft -TYPE: Non-Functional -COMPONENT: Mailboxes -TITLE: Mailbox Quantity Support +TITLE: Priority-Based Message Delivery STATEMENT: >>> -The Mailbox module shall support an arbitrary number of mailboxes, limited only by available RAM in the system. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my application needs without arbitrary limitations so that I can design my communication architecture freely. +When multiple threads of equal priority are waiting on an empty mailbox object, the Zephyr RTOS shall deliver the next message to the thread that has waited the longest. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-27 +UID: ZEP-SRS-22-22 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: Resource Cleanup +TITLE: FIFO Message Delivery STATEMENT: >>> -The Mailbox module shall ensure proper cleanup of message resources when operations are canceled or time out to prevent resource leaks. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want the system to automatically clean up resources when operations fail or time out so that my application doesn't experience memory leaks. +When multiple messages are available in the send queue from the same sender, the Zephyr RTOS shall deliver them in FIFO (First In, First Out) order to waiting threads. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-28 +UID: ZEP-SRS-22-23 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: Error Reporting +TITLE: Mailbox Quantity Support STATEMENT: >>> -If an error occurs during any mailbox operation, the Mailbox module shall return an appropriate error code indicating the type of failure. +The Zephyr RTOS shall support an arbitrary number of mailbox objects, limited only by available RAM in the system. <<< USER_STORY: >>> -As a Zephyr RTOS developer, I want to receive specific error codes when mailbox operations fail so that I can implement appropriate error handling and recovery. +As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my application needs without arbitrary limitations so that I can design my communication architecture freely. <<< RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 [REQUIREMENT] -UID: ZEP-SRS-22-29 +UID: ZEP-SRS-22-24 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes TITLE: Invalid Parameter Handling STATEMENT: >>> -The Mailbox module shall handle invalid parameters by returning appropriate error codes rather than causing system failures. +The Zephyr RTOS shall handle invalid parameters by returning appropriate error codes rather than causing system failures. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want the system to validate my inputs and return errors rather than crash when I provide invalid parameters so that I can develop more robust applications. diff --git a/docs/system_requirements/index.sdoc b/docs/system_requirements/index.sdoc index 2b3323b5..0834594a 100644 --- a/docs/system_requirements/index.sdoc +++ b/docs/system_requirements/index.sdoc @@ -360,7 +360,7 @@ TITLE: Mailboxes COMPONENT: Mailboxes TITLE: Mailboxes STATEMENT: >>> -The Zephyr RTOS shall provide a framework to pass messages between threads. +The Zephyr RTOS shall provide a framework to pass messages of arbitrary size between threads. <<< [/SECTION] From 04fe679e9b955220604a4123f6a4c38984360380 Mon Sep 17 00:00:00 2001 From: Joel Key Date: Tue, 24 Jun 2025 15:38:09 -0400 Subject: [PATCH 6/8] mailbox-requirements: Updates from latest feedback Deleted / simplified requirements with implementation details Updated phrasing of synchronous and asynchronous mailbox sends signed-off-by: Joel Key --- docs/software_requirements/mailboxes.sdoc | 93 ++--------------------- 1 file changed, 6 insertions(+), 87 deletions(-) diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc index 9575766f..b767f021 100644 --- a/docs/software_requirements/mailboxes.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -42,19 +42,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-3 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Queue Initialization -STATEMENT: >>> -When a mailbox is initialized, the Zephyr RTOS shall set both the send queue and receive queue of that mailbox to empty. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-4 STATUS: Draft @@ -71,19 +58,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-5 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Message Descriptor Usage -STATEMENT: >>> -The Zephyr RTOS shall use message descriptors to specify where a message's data is located and how the message is to be handled by the mailbox. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-6 STATUS: Draft @@ -97,22 +71,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-7 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Empty Message Support -STATEMENT: >>> -Where message data is non-existent (i.e., an empty message), the Zephyr RTOS shall correctly handle the message exchange without requiring buffer allocation. -<<< -USER_STORY: >>> -As a Zephyr RTOS developer, I want to be able to send signals or notifications that don't carry data so that I can trigger actions in other threads without the overhead of data transfer. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-8 STATUS: Draft @@ -120,7 +78,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Synchronous Message Sending STATEMENT: >>> -The Zephyr RTOS shall provide a mechanism for a thread to send message via a mailbox object in a synchronous manner with a timeout parameter. +The Zephyr RTOS shall provide a mechanism for a thread to send a message through a mailbox and block until the message is processed or a timeout occurs. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message and wait for it to be processed so that I can be sure the message was received before continuing execution. @@ -129,19 +87,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-9 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Synchronous Sending Behavior -STATEMENT: >>> -When a synchronous message is sent, the Zephyr RTOS shall block the sending thread until a receiver processes the message or the timeout expires. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-10 STATUS: Draft @@ -149,7 +94,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Synchronous Send Timeout Handling STATEMENT: >>> -If the synchronous message send operation times out before a receiver processes the message, the Zephyr RTOS shall return an appropriate timeout error code to the sending thread. +If the synchronous message send operation times out before a receiver processes the message, the Zephyr RTOS shall return an timeout error code to the sending thread. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to limit how long my thread waits for a message to be received so that I can implement fallback behavior if communication takes too long. @@ -165,7 +110,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Asynchronous Message Sending STATEMENT: >>> -The Zephyr RTOS shall provide a mechanism for a thread to send a message in an asynchronous manner. +The Zephyr RTOS shall provide a mechanism for a thread to send a message through a mailbox without waiting for it to be processed. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to send a message without waiting for it to be processed so that my thread can continue execution immediately. @@ -174,19 +119,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-12 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Asynchronous Sending Behavior -STATEMENT: >>> -When an asynchronous message is sent, the Zephyr RTOS shall not wait for a receiver to process the message before returning to the caller. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-13 STATUS: Draft @@ -194,7 +126,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Asynchronous Completion Signaling STATEMENT: >>> -When a sending thread provides a semaphore during an asynchronous send command using a mailbox object, the Zephyr RTOS shall give the semaphore when the message has been both received and completely processed by the receiver. +When a sending thread asynchronously sends a message to a mailbox object, the Zephyr RTOS shall provide a mechanism to signal to the sending thread that the message has been both received and completely processed by the receiver. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be notified when my asynchronously sent message has been fully processed so that I can perform follow-up actions without polling. @@ -226,7 +158,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Message Data Retrieval STATEMENT: >>> -The Zephyr RTOS shall provide a mechanism for a thread to retrieve message data via a mailbox object into a buffer and complete the message processing. +The Zephyr RTOS shall provide a mechanism for a thread to retrieve message data via a mailbox object. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want to be able to extract message data into my buffer after message reception so that I can process the information contained in the message. @@ -280,19 +212,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-22 -[REQUIREMENT] -UID: ZEP-SRS-22-19 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes -TITLE: Receiver Thread Queuing -STATEMENT: >>> -While a thread is waiting to receive a message via a mailbox object, the Zephyr RTOS shall keep the thread in the receive queue until a matching message arrives or the waiting period expires. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-22 - [REQUIREMENT] UID: ZEP-SRS-22-20 STATUS: Draft @@ -358,7 +277,7 @@ TYPE: Functional COMPONENT: Mailboxes TITLE: Invalid Parameter Handling STATEMENT: >>> -The Zephyr RTOS shall handle invalid parameters by returning appropriate error codes rather than causing system failures. +The Zephyr RTOS shall handle invalid parameters by returning error codes rather than causing system failures. <<< USER_STORY: >>> As a Zephyr RTOS developer, I want the system to validate my inputs and return errors rather than crash when I provide invalid parameters so that I can develop more robust applications. From f80d1a2a931e553deab03a6248c89f43477abc81 Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 15 Oct 2025 11:10:21 -0400 Subject: [PATCH 7/8] mailbox-requirements: Merge Cleanup Updated to incorporate fix for StrictDoc migration changes (changing [SECTION] to [[SECTION]]) Cleaned up requirement numbering based on external changes. signed-off-by: Joel Key --- docs/software_requirements/index.sdoc | 3 - docs/software_requirements/mailboxes.sdoc | 74 +++++++++++------------ docs/system_requirements/index.sdoc | 10 ++- 3 files changed, 44 insertions(+), 43 deletions(-) diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index 466c722f..19a2b735 100644 --- a/docs/software_requirements/index.sdoc +++ b/docs/software_requirements/index.sdoc @@ -79,8 +79,5 @@ FILE: lifos.sdoc [DOCUMENT_FROM_FILE] FILE: fifos.sdoc -[DOCUMENT_FROM_FILE] -FILE: mailbox.sdoc - [DOCUMENT_FROM_FILE] FILE: mailboxes.sdoc diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc index b767f021..a8e6fd20 100644 --- a/docs/software_requirements/mailboxes.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -1,6 +1,6 @@ [DOCUMENT] TITLE: Mailboxes -REQ_PREFIX: ZEP-SRS-22- +REQ_PREFIX: ZEP-SRS-25- [GRAMMAR] IMPORT_FROM_FILE: software_requirements.sgra @@ -11,7 +11,7 @@ SPDX-License-Identifier: Apache-2.0 <<< [REQUIREMENT] -UID: ZEP-SRS-22-1 +UID: ZEP-SRS-25-1 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -24,10 +24,10 @@ As a Zephyr RTOS developer, I want to be able to initialize a mailbox instance s <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-2 +UID: ZEP-SRS-25-2 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -40,10 +40,10 @@ As a Zephyr RTOS developer, I want to be able to statically define and initializ <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-4 +UID: ZEP-SRS-25-3 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -56,10 +56,10 @@ As a Zephyr RTOS developer, I want to be able to send messages of different size <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-6 +UID: ZEP-SRS-25-4 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -69,10 +69,10 @@ The Zephyr RTOS shall handle the data transfer between mailbox objects of the se <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-8 +UID: ZEP-SRS-25-5 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -85,10 +85,10 @@ As a Zephyr RTOS developer, I want to be able to send a message and wait for it <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-10 +UID: ZEP-SRS-25-6 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -101,10 +101,10 @@ As a Zephyr RTOS developer, I want to be able to limit how long my thread waits <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-11 +UID: ZEP-SRS-25-7 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -117,10 +117,10 @@ As a Zephyr RTOS developer, I want to be able to send a message without waiting <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-13 +UID: ZEP-SRS-25-8 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -133,10 +133,10 @@ As a Zephyr RTOS developer, I want to be notified when my asynchronously sent me <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-14 +UID: ZEP-SRS-25-9 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -149,10 +149,10 @@ As a Zephyr RTOS developer, I want to be able to receive messages from other thr <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-15 +UID: ZEP-SRS-25-10 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -165,10 +165,10 @@ As a Zephyr RTOS developer, I want to be able to extract message data into my bu <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-16 +UID: ZEP-SRS-25-11 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -178,10 +178,10 @@ When a receiving thread requests a message via a mailbox object and no message i <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-17 +UID: ZEP-SRS-25-12 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -194,10 +194,10 @@ As a Zephyr RTOS developer, I want to be able to limit how long my thread waits <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-18 +UID: ZEP-SRS-25-13 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -210,10 +210,10 @@ As a Zephyr RTOS developer, I want to be able to identify the source or destinat <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-20 +UID: ZEP-SRS-25-14 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -226,10 +226,10 @@ As a Zephyr RTOS developer, I want message delivery to respect thread priorities <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-21 +UID: ZEP-SRS-25-15 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -239,10 +239,10 @@ When multiple threads of equal priority are waiting on an empty mailbox object, <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-22 +UID: ZEP-SRS-25-16 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -252,10 +252,10 @@ When multiple messages are available in the send queue from the same sender, the <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-23 +UID: ZEP-SRS-25-17 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -268,10 +268,10 @@ As a Zephyr RTOS developer, I want to be able to create as many mailboxes as my <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-22-24 +UID: ZEP-SRS-25-18 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes @@ -284,4 +284,4 @@ As a Zephyr RTOS developer, I want the system to validate my inputs and return e <<< RELATIONS: - TYPE: Parent - VALUE: ZEP-SYRS-22 + VALUE: ZEP-SYRS-25 diff --git a/docs/system_requirements/index.sdoc b/docs/system_requirements/index.sdoc index 0834594a..4f8b1ce5 100644 --- a/docs/system_requirements/index.sdoc +++ b/docs/system_requirements/index.sdoc @@ -353,14 +353,18 @@ The Zephyr RTOS shall implement FIFOs which can be used to pass data between thr <<< [[/SECTION]] -[/SECTION] -[SECTION] +[[SECTION]] TITLE: Mailboxes + +[REQUIREMENT] +UID: ZEP-SYRS-25 +STATUS: Draft +TYPE: Functional COMPONENT: Mailboxes TITLE: Mailboxes STATEMENT: >>> The Zephyr RTOS shall provide a framework to pass messages of arbitrary size between threads. <<< -[/SECTION] +[[/SECTION]] From cfa4e7970d1d3ad284efaa3a9f83c9fcb022f3ef Mon Sep 17 00:00:00 2001 From: Joel Key Date: Wed, 15 Oct 2025 11:19:55 -0400 Subject: [PATCH 8/8] mailbox-requirements: Remove proposed FIFO messaging requirement Removed the proposed requirement for FIFO message transfer based on review feedback. signed-off-by: Joel Key --- docs/software_requirements/mailboxes.sdoc | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc index a8e6fd20..5618d05a 100644 --- a/docs/software_requirements/mailboxes.sdoc +++ b/docs/software_requirements/mailboxes.sdoc @@ -246,19 +246,6 @@ UID: ZEP-SRS-25-16 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes -TITLE: FIFO Message Delivery -STATEMENT: >>> -When multiple messages are available in the send queue from the same sender, the Zephyr RTOS shall deliver them in FIFO (First In, First Out) order to waiting threads. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-25 - -[REQUIREMENT] -UID: ZEP-SRS-25-17 -STATUS: Draft -TYPE: Functional -COMPONENT: Mailboxes TITLE: Mailbox Quantity Support STATEMENT: >>> The Zephyr RTOS shall support an arbitrary number of mailbox objects, limited only by available RAM in the system. @@ -271,7 +258,7 @@ RELATIONS: VALUE: ZEP-SYRS-25 [REQUIREMENT] -UID: ZEP-SRS-25-18 +UID: ZEP-SRS-25-17 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes