-
Notifications
You must be signed in to change notification settings - Fork 15
Mailbox requirements #83
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jkey-eng
wants to merge
8
commits into
zephyrproject-rtos:main
Choose a base branch
from
jkey-eng:mailbox-requirements
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
0857c4e
software: Add Mailbox Requirements created by Perplexity
jkey-eng 7fc3c3d
software: Manual review and cleanup of generated reqts
jkey-eng 5f41310
system: Add Mailboxes Requirement
jkey-eng 4855705
software: trace software to system req
jkey-eng 8788a50
mailbox-requirements: Update Requirements after Initial Feedback
jkey-eng 04fe679
mailbox-requirements: Updates from latest feedback
jkey-eng f80d1a2
mailbox-requirements: Merge Cleanup
jkey-eng cfa4e79
mailbox-requirements: Remove proposed FIFO messaging requirement
jkey-eng File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -78,3 +78,6 @@ FILE: lifos.sdoc | |
|
|
||
| [DOCUMENT_FROM_FILE] | ||
| FILE: fifos.sdoc | ||
|
|
||
| [DOCUMENT_FROM_FILE] | ||
| FILE: mailboxes.sdoc | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the receiving thread will always know the sending thread, but with K_ANY the sending thread cannot tell which thread received the message via a mailbox
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm struggling to understand what update (if any) to make based on this feedback.
From the docs:
Are you suggesting the current behavior is out of spec, or maybe that this requirement would be a should statement where it would be a wanted feature but not mandatory?