Zephyr Project Requirements
Mailboxes

SPDX-License-Identifier: Apache-2.0
ZEP-SRS-25-1
1. Mailbox Initialization At Run Time UID: ZEP-SRS-25-1 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-2
2. Mailbox Initialization At Compile Time UID: ZEP-SRS-25-2 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-3
3. Message Size Support UID: ZEP-SRS-25-3 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-4
4. Mailbox Data Transfer UID: ZEP-SRS-25-4 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): STATEMENT:

The Zephyr RTOS shall handle the data transfer between mailbox objects of the sending and receiving threads.
ZEP-SRS-25-5
5. Synchronous Message Sending UID: ZEP-SRS-25-5 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-6
6. Synchronous Send Timeout Handling UID: ZEP-SRS-25-6 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-7
7. Asynchronous Message Sending UID: ZEP-SRS-25-7 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-8
8. Asynchronous Completion Signaling UID: ZEP-SRS-25-8 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-9
9. Message Reception UID: ZEP-SRS-25-9 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-10
10. Message Data Retrieval UID: ZEP-SRS-25-10 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-11
11. Message Reception Blocking UID: ZEP-SRS-25-11 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-12
12. Message Reception Timeout Handling UID: ZEP-SRS-25-12 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-13
13. Non-Anonymous Messaging UID: ZEP-SRS-25-13 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-14
14. Priority-Based Message Delivery UID: ZEP-SRS-25-14 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-15
15. Priority-Based Message Delivery UID: ZEP-SRS-25-15 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-16
16. Mailbox Quantity Support UID: ZEP-SRS-25-16 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.
ZEP-SRS-25-17
17. Invalid Parameter Handling UID: ZEP-SRS-25-17 STATUS: Draft TYPE: Functional COMPONENT: Mailboxes RELATIONS (Parent): 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.