diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index 4aae44e..19a2b73 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: mailboxes.sdoc diff --git a/docs/software_requirements/mailboxes.sdoc b/docs/software_requirements/mailboxes.sdoc new file mode 100644 index 0000000..5618d05 --- /dev/null +++ b/docs/software_requirements/mailboxes.sdoc @@ -0,0 +1,274 @@ +[DOCUMENT] +TITLE: Mailboxes +REQ_PREFIX: ZEP-SRS-25- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[REQUIREMENT] +UID: ZEP-SRS-25-1 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Mailbox Initialization At Run Time +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-2 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Mailbox Initialization At Compile Time +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-3 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Message Size Support +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-4 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Mailbox Data Transfer +STATEMENT: >>> +The Zephyr RTOS shall handle the data transfer between mailbox objects of the sending and receiving threads. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-5 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Synchronous Message Sending +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-6 +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 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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-7 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Asynchronous Message Sending +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-8 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Asynchronous Completion Signaling +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-9 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Message Reception +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-10 +STATUS: Draft +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. +<<< +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-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-11 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Message Reception Blocking +STATEMENT: >>> +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-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-12 +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 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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-13 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Non-Anonymous Messaging +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-14 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Priority-Based Message Delivery +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-15 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Priority-Based Message Delivery +STATEMENT: >>> +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-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-16 +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. +<<< +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-25 + +[REQUIREMENT] +UID: ZEP-SRS-25-17 +STATUS: Draft +TYPE: Functional +COMPONENT: Mailboxes +TITLE: Invalid Parameter Handling +STATEMENT: >>> +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. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-25 diff --git a/docs/system_requirements/index.sdoc b/docs/system_requirements/index.sdoc index cafa9b8..4f8b1ce 100644 --- a/docs/system_requirements/index.sdoc +++ b/docs/system_requirements/index.sdoc @@ -353,3 +353,18 @@ The Zephyr RTOS shall implement FIFOs which can be used to pass data between thr <<< [[/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]]