Software requirements: Semaphore: collected all requirements so far #58
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -644,3 +644,6 @@ RELATIONS: | |
|
|
||
| [DOCUMENT_FROM_FILE] | ||
| FILE: tracing.sdoc | ||
|
|
||
| [DOCUMENT_FROM_FILE] | ||
| FILE: semaphore.sdoc | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,354 @@ | ||
| [DOCUMENT] | ||
| TITLE: Semaphore | ||
| REQ_PREFIX: ZEP- | ||
|
|
||
| [GRAMMAR] | ||
| IMPORT_FROM_FILE: software_requirements.sgra | ||
|
|
||
| [SECTION] | ||
| TITLE: Interface requirements | ||
|
|
||
| [SECTION] | ||
| TITLE: Initialize semaphore | ||
|
There was a problem hiding this comment. This is a good example of following INCOSE GtWR R41 - Related Needs and Requirements: "Group related needs and requirements together." |
||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-134 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Build-Time Allocation and Initialization | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism to define and initialize a semaphore at compile time. | ||
|
There was a problem hiding this comment. INCOSE GtWR R4 - Defined Terms: This statement needs to use the value of the COMPONENT: attribute. |
||
|
|
||
| ---- | ||
|
|
||
| The Zephyr RTOS shall expose an interface for a Counting Semaphore to accomplish all of the following at build-time: | ||
|
|
||
| - statically allocating the Counting Semaphore; | ||
| - statically initialize the Counting Semaphore with the provided count limit and initial count. | ||
|
There was a problem hiding this comment. INCOSE GtWR R11 - Separate Clauses: "allocating" and "initialize" are separate actions. They should be in separate clauses. INCOSE GtWR R19 - Combinators: "count limit and initial count". Please either justify the high coupling of these parameters or state them in different clauses. There was a problem hiding this comment. I do not agree with Greg's comment, as this requirement focuses on the need to have an interfacing functionality and what this interface functionality must look like - even if it is not atomic at the first glance, it does not make sense to me to split it up - So for me this requirement is ok as is. |
||
| <<< | ||
|
There was a problem hiding this comment. INCOSE GtWR R4 - Defined Terms:
There was a problem hiding this comment. Yes, these terms need to be added to the glossary, but this does not block merging. There was a problem hiding this comment. INCOSE GtWR R5 - Definite Articles: Both statements use "a"/"an". The GtWR rule is to use "the" rather than "a". There was a problem hiding this comment. The requirement asks for an interface - "the" would be misleading here, as there is no interface existing that can be addressed as "the interface". So it is ok as it is here with the "an interface". There was a problem hiding this comment. Agreed, since both must happen at build time in this case. Run-time is a different matter. There was a problem hiding this comment. INCOSE GtWR R33 - Tolerance: "initial count", "count limit", and the "count" implicit in "Counting Semaphore" are quantities. Per R33 " Define each quantity with a range of values appropriate to the entity to which the quantity applies and against which the entity will be verified or validated." There was a problem hiding this comment. Yes, but for me that are additional requirements. |
||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-135 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Dynamic Initialization | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism to define and initialize a semaphore at runtime. | ||
|
|
||
| ---- | ||
|
|
||
| The Zephyr RTOS shall expose an interface to dynamically initialize a Counting Semaphore which requires the following information: | ||
|
|
||
| - initial count of the Counting Semaphore; | ||
| - count limit of the Counting Semaphore. | ||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-003 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
There was a problem hiding this comment. The COMPONENT changes between Counting Semaphore and Semaphore - is this intentionally? Otherwise I'd like to stick to one of them. |
||
| TITLE: Maximum limit of a semaphore | ||
| STATEMENT: >>> | ||
| When a semaphore is used for counting purposes and when the semaphore does not have an explicit | ||
|
There was a problem hiding this comment. issue: What other purposes are Counting Semaphores use for than counting? Also I am pretty sure that the maximum limit cannot be avoided as per our current implementation. |
||
| maximum limit, the Zephyr RTOS shall define the maximum limit of a semaphore to | ||
| be used when the semaphore is initialized. | ||
| <<< | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Take semaphore | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-005 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
There was a problem hiding this comment. nitpick: Should probably read Counting Semaphore |
||
| TITLE: Semaphore acquisition | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism allowing threads to take (acquire) a semaphore, ensuring atomic and thread-safe operations for | ||
|
There was a problem hiding this comment. note: Not only threads are allowed to take semaphores. We either include ISRs here or we need additional RQTs for take/give semaphores from ISR contexts. |
||
| semaphore acquisition. | ||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-007 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Semaphore Timeout | ||
| STATEMENT: >>> | ||
| When attempting to take (acquire) a semaphore, the Zephyr RTOS shall accept options that specify timeout periods, allowing threads to set a maximum wait time for semaphore acquisition. | ||
|
There was a problem hiding this comment. suggestion: strictly speaking semaphores could also be taken from ISRs when they K_NO_WAIT, so it's not solely about threads. That's why I was proposing a more generic term such as task or control flow entity to cover such corner cases. For now it's probably fine to leave as is and we can revisit later. |
||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Give semaphore | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-010 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Semaphore release | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism allowing threads to give (release) a semaphore, ensuring atomic and thread-safe operations for | ||
|
There was a problem hiding this comment. note: Semaphores can also be given from ISRs. Either include ISRs in addition to threads here or create another RQTs to cover ISR context. |
||
| semaphore release. | ||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Functional requirements | ||
|
|
||
| [SECTION] | ||
| TITLE: Initialize semaphore | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-004 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Initialialization with inital semaphore value | ||
| STATEMENT: >>> | ||
| When initializing a counting semaphore, the initial semaphore value shall be set. | ||
|
There was a problem hiding this comment. suggestion: be set to what? "shall be set to the initial value provided by the user. |
||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-016 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Initialialization with maximum count value | ||
| STATEMENT: >>> | ||
| When initializing a counting semaphore, the maximum permitted count a semaphore | ||
| can have shall be set. | ||
|
There was a problem hiding this comment. suggestion: be set to what? "shall be set to the limit value provided by the user." |
||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-017 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Semaphore Initialization Option Validation | ||
| STATEMENT: >>> | ||
| When initializing a counting semaphore, where the maximum permitted count of a semaphore is invalid, | ||
| the Zephyr RTOS shall return an error indicating invalid values. | ||
|
There was a problem hiding this comment. nitpick: return an 'invalid value' error. We probably need to add to the glossary the possible error values at some later time. There was a problem hiding this comment. FYI, this PR provides a glossary document skeleton and some definitions from standards. |
||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Take semaphore | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-129 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Take while Available | ||
| STATEMENT: >>> | ||
| While a Counting Semaphore count is > 0, | ||
|
|
||
| When a takes that Counting Semaphore, | ||
|
There was a problem hiding this comment. typo: When a thread or ISR takes ... |
||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - decrement by 1 the count of that Counting Semaphore; | ||
| - indicate SUCCESS to the taking thread. | ||
|
|
||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-131 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Take w/o blocking when not Available | ||
| STATEMENT: >>> | ||
| While a Counting Semaphore count is 0, | ||
|
|
||
| When a thread takes that Counting Semaphore without allowing blocking, | ||
|
|
||
|
|
||
| the Zephyr RTOS shall indicate NOT AVAILABLE to the taking thread. | ||
|
|
||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-130 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Take with TIMEOUT > 0 blocks if not Available | ||
| STATEMENT: >>> | ||
| While a Counting Semaphore count is 0, | ||
|
|
||
| When a thread takes that Counting Semaphore with a waiting TIMEOUT > 0, | ||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - block the taking thread waiting for the availability of that Counting Semaphore; | ||
|
There was a problem hiding this comment. suggestion: the wording sounds somewhat complicated. What happens is that Zephyr deschedules the running thread and puts it into the semaphore's waiting list (where other threads may already happily sit and wait). To start with the "for the ..." can be removed. Perhaps starth with "- pause the running thread and add it to the list of threads waiting for this semaphore" |
||
| - enter the waiting period with a duration TIMEOUT. | ||
|
There was a problem hiding this comment. suggestion: "start a waiting period with the provided duration" |
||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-132 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Take Unblocked by Giving Thread | ||
|
There was a problem hiding this comment. suggestion: This all sounds again somewhat odd. The condition on why a waiting thread is unblocked is missing. Actually, what happens is that when the semaphore count becomes larger than zero again the highest priority thread from the semaphore;s waiting list becomes runnable again. Doesn't mean it will run though since its priority might not be high enough. Yet, for me that's the behaviour I'd like to see specified as this is what make the RTOS an RTOS. |
||
| STATEMENT: >>> | ||
| When the waiting thread is unblocked by a giving thread, | ||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - deactivate the waiting period; | ||
| - indicate SUCCESS to the waiting thread; | ||
| - reschedule the waiting thread. | ||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-133 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Take Unblocked by Waiting Period Timeout | ||
| STATEMENT: >>> | ||
| When the waiting thread is unblocked by the expiration of the waiting period, | ||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - resume the waiting thread; | ||
|
There was a problem hiding this comment. note: it's marked runnable again, doesn't mean it will run automatically though. |
||
| - indicate TIMEDOUT to the waiting thread; | ||
| - reschedule the waiting thread. | ||
|
|
||
|
There was a problem hiding this comment. thought: there is an interesting question here: what happens if by means of a timeout a waiting thread becomes runnable again but can't run for some more time in which the semaphore now is given ... shall it then return TIMEOUT or SUCCESS? |
||
| ---- | ||
|
|
||
| When attempting to take (acquire) a semaphore, where the semaphore is not acquired within the specified time, the Zephyr RTOS shall return an error indicating a timeout. | ||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-009 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Semaphore no wait error handling | ||
| STATEMENT: >>> | ||
| When attempting to take (acquire) a semaphore, where the current count is zero and no waiting time was provided, the Zephyr RTOS | ||
| shall return an error indicating the semaphore is busy. | ||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Give semaphore | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-128 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Give without Waiting Threads | ||
| STATEMENT: >>> | ||
| While no thread is waiting for a Counting Semaphore, | ||
|
|
||
| When a thread gives that Counting Semaphore, | ||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - increase the Semaphore Count by 1; | ||
| - indicate SUCCESS to the giving thread. | ||
| <<< | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-127 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Semaphore Give while Thread Waiting | ||
|
There was a problem hiding this comment. suggestion: while threads are waiting |
||
| STATEMENT: >>> | ||
| While a thread is waiting for a Counting Semaphore, | ||
|
There was a problem hiding this comment. suggestion: there can be one more more threads waiting for the semaphore |
||
|
|
||
| When a thread gives that Counting Semaphore, | ||
|
|
||
| the Zephyr RTOS shall accomplish all of the following: | ||
|
|
||
| - unblock the highest priority thread waiting for that Counting Semaphore; | ||
| - indicate SUCCESS to the giving thread. | ||
| <<< | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Get semaphore count | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-136 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Counting Semaphore | ||
| TITLE: Current Count | ||
| STATEMENT: >>> | ||
| When the Counting Semaphore current count is requested, | ||
|
|
||
| the Zephyr RTOS shall report the current count of the Counting Semaphore. | ||
| <<< | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [/SECTION] | ||
|
|
||
| [SECTION] | ||
| TITLE: Safety requirements | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-011 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
| TITLE: Prevent overflows/underflows of semaphore count | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall prevent overflows or underflows of the semaphore count. | ||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [REQUIREMENT] | ||
| UID: ZEP-SEMAPHORE-006 | ||
| STATUS: Draft | ||
| TYPE: Functional | ||
| COMPONENT: Semaphore | ||
|
|
||
| TITLE: Semaphore Counting | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall track resource usage of a semaphore. | ||
| <<< | ||
| RELATIONS: | ||
| - TYPE: Parent | ||
| VALUE: ZEP-99 | ||
|
|
||
| [/SECTION] | ||
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.
This is a good example of following INCOSE GtWR R42 - Structured Sets: "Conform to a defined structure or template for organizing sets of needs and requirements."