Mailboxes
SPDX-License-Identifier: Apache-2.0
The Zephyr RTOS shall provide a mechanism to define and initialize a mailbox at run time.
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.
The Zephyr RTOS shall provide a mechanism to statically define and initialize a mailbox object at compile time.
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.
The Zephyr RTOS shall support messages containing zero or more bytes of data.
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.
The Zephyr RTOS shall handle the data transfer between mailbox objects of the sending and receiving threads.
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.
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.
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.
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.
The Zephyr RTOS shall provide a mechanism for a thread to send a message through a mailbox without waiting for it to be processed.
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 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.
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.
The Zephyr RTOS shall provide a mechanism for a thread to receive a message via a mailbox object with a timeout parameter.
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.
The Zephyr RTOS shall provide a mechanism for a thread to retrieve message data via a mailbox object.
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.
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.
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.
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.
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.
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.
When multiple threads are waiting on an empty mailbox object, the Zephyr RTOS shall deliver the next message to the highest priority thread.
As a Zephyr RTOS developer, I want message delivery to respect thread priorities so that higher priority tasks receive messages before lower priority ones.
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.
The Zephyr RTOS shall support an arbitrary number of mailbox objects, limited only by available RAM in the system.
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.
The Zephyr RTOS shall handle invalid parameters by returning error codes rather than causing system failures.
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.