req: add semaphore requirements

[nashif]

Expand on semaphore requirements.

Signed-off-by: Anas Nashif anas.nashif@intel.com

[nashif]

@stanislaw why is this failing, the syntax is very strict :)

[simhein]

@stanislaw why is this failing, the syntax is very strict :)

I think the exporter don't like the additional line in 1383 and 1439 😃

[nashif]

@stanislaw is it possible to put sections in smaller documents instead of maintaining everything in 1 single document?

[stanislaw]

@stanislaw is it possible to put sections in smaller documents instead of maintaining everything in 1 single document?

@mettta and I have started designing the include-able section fragments feature. For now, you could simply create one more .sdoc document and collect the semaphore requirements there.

cc @romkell

[tobiaskaestner]

suggestion: In the larger context the term system might eventually become misleading, consider using a somewhat more specific term akin to "The Zephyr Library" of the "The Zephyr RTOS"

[tobiaskaestner]

nitpick: In it's most basic usage, a semaphore is a signalling device amongst concurrently/parallel tasks. Coordinating resource sharing is an important but not the only example where such signalling is required. Eg. a compute task signalling to a UI task that some computation has finished to let the UI task turn on an LED. No resource is actually shared ( yet exclusively owned by the respective tasks). IMHO, the rationale could be weakened to simply refer to signalling

[tobiaskaestner]

suggestion: Where possible the and conjunction in requirements should be avoided to ensure atomicity of RQTs. Hence, consider splitting into two RQTs.

issue: If stated as is, deterministic operation and bounded execution time need to be defined somewhere, otherwise this RQTs is untestable.

[tobiaskaestner]

suggestion: The RQT provides a rationale in its statement: "... to regulate the number ...." which could be moved to an "informative" field of the RQT. It also might be misleading as there is no strict connection between a semaphore count and the number of threads interacting with said semaphore.

nitpick: A semaphore is a signalling device not neccesarely tied to the coordination of shared resource access

[tobiaskaestner]

question: What about possible outcomes, success and failure?

thought: To avoid redundancy Error management could be made a cross-cutting requirement for all Kernel API functions, e.g. to follow POSIX convention for error codes. Another such cross-cutting RQT would be the naming convention, e.g. common "k_" prefix and then kernel object specific identifier "sem_" for semaphore.

[tobiaskaestner]

nitpick: it reads a bit awkward.. consider to change enabling to allowing, also following CS text books basic operations for a semaphore are tak and give, so perhaps take (acquire) and give (release)

[tobiaskaestner]

nitpick: Again, unneccessary inclusion of rationale in RQT statement.

[tobiaskaestner]

question: When stated as is, what is the (implicit) implication of When counting semaphores are not in use? What mustn't overflow or or underflow?

[nashif]

the count.

[nashif]

@tobiaskaestner ok, pushed another revision. I am trying to avoid making those turn into interface requirements by not going into the details of the implementation, its not easy and you find yourself specifying APIs instead of descrbing required functionality, i.e. functional requirements.

[gregshue]

Requirement statements must be unambiguous. AFAICT the boundaries of the "Zephyr RTOS" is vague. This noun must be defined accurately and measurably.

"implement" is not behavioral/observable. Therefore it is not measurable.

"tasks" needs to be defined in a glossary. Do you mean threads (e.g., thread.c)? If so, it likewise must be defined in a glossary.

[tobiaskaestner]

The Zephyr RTOS is a much better boundary than "The system" and I could live with it. Note, it's not about the Zephyr RTOS Project, just the Zephyr RTOS itself. We may assume though that this is defined somewhere, so by no means argueing against a glossary

"shall implement" is not so uncommon from other RQTs I have seen, alternatively you may consider "shall provide" ... either way I'd say it is measurable as we can refer to the implementation

Unfortunately, looks like I introduced more confusion than I was hoping with my previous comment related to signalling. I meant to drop the part with shared resources altogether

Suggestion: The Zephyr RTOS shall provide a semaphore signalling primitive for task synchronization and coordination

[gregshue]

I agree that "the system" is extremely vague. AFAICT we have already worked with multiple layers in the project. Here's what I've noticed:

1. Implicit User Needs & Stakeholder Requirements were behind implicit requirements upon the Zephyr Project;
2. Implicit Zephyr Project Requirements were behind zephyrproject.org and the Contributing to Zephyr part of the documentation;
3. Implicit Zephyr Ecosystem Requirements were behind adding external modules into github.com/zephyrproject-rtos/;
4. Implicit Zephyr (extensible) Platform Requirements were behind the zephyr repo;
5. Implicit Zephyr Kernel Requirements were behind the zephyr/kernel/ directory;
6. Implicit Zephyr Counting Semaphore Requirements were behind zephyr/kernel/sem.c;

The big problem I have with "Zephyr RTOS" as a System (sub-)* Element is that the minimal build of Zephyr has no "OS" functionality AFAICT. (No timers; no interrupt controllers; no console; no devices; no threading; no MPU; no syscalls; no signals?;). Calling something a term that it is not is logically contradictory. So I've been exploring "Zephyr Platform" to describe the Zephyr Project-owned portion of the ecosystem consumed by the users.

[gregshue]

See prior comments on "Zephyr RTOS", "provide a mechanism".

"at build time" implies there is another requirement on the Zephyr build system. We need to know where that goes in the requirements doc tree.

[tobiaskaestner]

Good point, when I read it I immediately translated to static initialization with K_SEM_DEFINE... Yet build time isn't strictly correct as there still happens run-time initialization, it;s just being taken care of during system init. So Zephyr provides a way to automatically create(actually initialize) semaphores without the user having to add additional runtime code

[gregshue]

The requirement with this UID is traced from other requirements in the file. When you change the statement like this those traces are all suspect and those requirements must be re-evaluated.

Once a requirement/UID is has an approved meaning then we must assume external requirements trace to it also. We can probably tweak the statement to clarify the meaning but we should not change the meaning.

[gregshue]

"runtime" needs a definition. Does this include before the application starts (e.g., main() is called)? Does it include after? Does this support creating a semaphore from dynamically allocated memory?

[tobiaskaestner]

see above, perhaps change the wording from create to initialize

[romkell]

"runtime" needs a definition. Does this include before the application starts (e.g., main() is called)? Does it include after? Does this support creating a semaphore from dynamically allocated memory?

• runtime: any MCU/MPU executed binary instruction from the reset vector on-wards
• compile time: what the compiler / linker does without executing any binary code
• C init: anything from the reset vector until non-RTOS, C main()
• RTOS init: anything from the first line of RTOS code (I guess after C main) until application execution starts, any application code registered to be executed during RTOS init, belongs to that phase

For the last two I am not familiar enough with the architecture. I assume that static application RAM gets initialized in the C init phase.

[gregshue]

@romkell I have found it very useful to use "start-time" to distinguish reset-vector up to when the entire executable is finished with initialization (entering main()), and reserve "runtime" for after that point.

the first line of RTOS code (I guess after C main)

If you do not count the init sequence itself as RTOS code (which I don't) then the first line of RTOS code happens very early in the init sequence.

until application execution starts

Almost the entire application could be initialized and run through SYSINIT() hooks. That may have some of the application running before the RTOS is fully up. All that may be needed in main() is to announce when the system initialization is done (which really ought to be another SYSINIT() notification) and wait for a signal to return and let the shutdown execute (which might be a better implementation of __weak__ main()).

[gregshue]

FYI, "the Zephyr RTOS shall return an error" implies the Zephyr RTOS is smaller than the executable.

The current phrasing does not cover the cases where only one of them is invalid. It seems to me these are independent criteria so should generate independent requirement statements.

[tobiaskaestner]

Good point again since it highlights our different views. I'd say indeed that the Zephyr RTOS is smaller than the final application since I consider it being a library/framework that I use to build my application upon.

More to the statement itself, I am still not sure to explicitly state for each of the interface requirements that in case of invalid arguments the function call needs to come back with some meaningful error code. This applies to all API functions that take arguments and perhaps simpler to state a single requirement that API function shall validate their arguments and make the design specification refer to it.

[gregshue]

library/framework

"library" makes me think the deliverable is just a CMake buildable archive and interface files. Zephyr is much more than that.

"framework" is essentially what I think of too. Yet it still feels like it falls a bit short so I'm inclined toward "platform".

[gregshue]

"return an error" is vague. What does this error need to indicate?

[tobiaskaestner]

At this level I am fine with error and leave the details to the design specification. Yet, are we on the same page regarding a distinction between requirements and design specification?

[gregshue]

"maximum permitted count" is vague. As stated the RTOS shall accept a negative 128b number. I think you mean "expose a parameter for".

"and" occurring after "shall" indicates this probably is two independent requirements. See INCOSE Guide to Writing Requirements for explanations and reasonable justification for leaving them in a single statement.

[tobiaskaestner]

For me this is a case where a conjuction would be ok, since it's actually describing the function signature.

[romkell]

"maximum permitted count" is vague. As stated the RTOS shall accept a negative 128b number. I think you mean "expose a parameter for".

"option" is fine for me. It is clear enough but generic, not directly describing the interface. Where as "expose a parameter for" is towards an interface spec.

With option one can implement an init/setup function without parameters and two setter or an init/setup function with all parameters.

"and" occurring after "shall" indicates this probably is two independent requirements. See INCOSE Guide to Writing Requirements for explanations and reasonable justification for leaving them in a single statement.

Agree here, suggest:

• When initializing a counting semaphore, the Zephyr RTOS shall provide an option specifying the initial semaphore count value.
• When initializing a counting semaphore, the Zephyr RTOS shall provide an option specifying the maximum permitted count value.

[gregshue]

"option" is fine for me. It is clear enough but generic, not directly describing the interface.

At some level of decomposition the requirements on the interface must be captured. (After all, what do the function signatures link to?) Above that level "option" is fine. Below that level it is not. The big question is what is that decomposition level when these are end-user-facing public interfaces? I find "Zephyr RTOS" too vague. I propose it is Zephyr Platform since this public API is directly used by supplementary subsystems and drivers in other modules.

[gregshue]

The justification ("to regulate") should be removed from the statement. Otherwise, we'll have to determine how to verify that it is used for that purpose.

[romkell]

I feel the requirement could be simplified:

When no explicit maximum count limit option is given during initialization, the Zephyr RTOS shall define the maximum limit.

The requirement should not make assumptions for what purpose the user intends to use the semaphore. It should just describe behavior.

[gregshue]

", ensuring ..." reads like a justification. Justifications need to be dropped from the statement. If "atomic" is a part of the required behavior then it needs to be in the paired-down statement.

[gregshue]

Why is this condition returning an error rather than indicating success and no semaphore available?

[tobiaskaestner]

See comment about how to handle invalid parameters in more general

[tobiaskaestner]

I am sorry, still fighting with the Github UI (Gerrit was/is so much cleaner, I'll keep that for a different time though).
Half of my comments were in limbo for the last couple of days and since then a new push force has arrived on the branch. I'll take a look at this later, just wanted to drop the previous comments first.

[tobiaskaestner]

The Zephyr RTOS is a much better boundary than "The system" and I could live with it. Note, it's not about the Zephyr RTOS Project, just the Zephyr RTOS itself. We may assume though that this is defined somewhere, so by no means argueing against a glossary

"shall implement" is not so uncommon from other RQTs I have seen, alternatively you may consider "shall provide" ... either way I'd say it is measurable as we can refer to the implementation

Unfortunately, looks like I introduced more confusion than I was hoping with my previous comment related to signalling. I meant to drop the part with shared resources altogether

Suggestion: The Zephyr RTOS shall provide a semaphore signalling primitive for task synchronization and coordination

[tobiaskaestner]

suggestion: As a Zephyr RTOS user I want to use semaphores for task coordination and synchronization as required for accessing shared resources and related issues in concurrent and parallel programming.

[tobiaskaestner]

Good point, when I read it I immediately translated to static initialization with K_SEM_DEFINE... Yet build time isn't strictly correct as there still happens run-time initialization, it;s just being taken care of during system init. So Zephyr provides a way to automatically create(actually initialize) semaphores without the user having to add additional runtime code

[tobiaskaestner]

see above, perhaps change the wording from create to initialize

[tobiaskaestner]

For me this is a case where a conjuction would be ok, since it's actually describing the function signature.

[tobiaskaestner]

I apologize in advance for my somewhat academic view on this: For me the semaphore is a pool of (semaphore) tokens (sem_max_count of them) that can be taken by tasks (one at a time as per our current implementation) until said pool is empty. Any task can (try to) take as many tokens as it likes. Conversely tasks can add tokens back to the pool by giving to the semaphore until the pool capacity is reached, again one at a time (as per the current implementation). Obviously, the implementation doesn't know about such a pool, as there is just a counter for how many (abstract) tokens are currently held by the (abstract) pool.

[tobiaskaestner]

See comment about how to handle invalid parameters in more general

[tobiaskaestner]

At this level I am fine with error and leave the details to the design specification. Yet, are we on the same page regarding a distinction between requirements and design specification?

[tobiaskaestner]

Another point where it looks to me like differing angles. I'd prefer to leave RQTs at lot less specific than the actual design specification to which I would defer any such details

[tobiaskaestner]

I am also not sure if this is needed here at all.
suggestion: After a semaphore was successfully initialized the Zephyr RTOS shall enforce that the semaphore can only be taken or given the specified amount of times.

Overflows/Underflows of an integer reveal too much of the underlying implementation IMHO.

[tobiaskaestner]

Just noticed, that while I was reviewing and responding in part to @gregshue comments @nashif force pushed a new revision which did separate my replies from the original comments. Apologies for that.

[nashif]

Just noticed, that while I was reviewing and responding in part to @gregshue comments @nashif force pushed a new revision which did separate my replies from the original comments. Apologies for that.

no worries.

[simhein]

Suggested change

	When a semaphore is used for counteing purposes and when the semaphore does not have an explicit
	When a semaphore is used for counting purposes and when the semaphore does not have an explicit

A small typo

[nashif]

traceability to tests:

[gregshue]

@tobiaskaestner Does your concept allow a task to hold multiple tokens from the same pool?

[gregshue]

@tobiaskaestner Interfaces to the "system" are an interesting beast. At which decomposition level are you looking for them to be first specified in detail (e.g., Project, Ecosystem, Platform, kernel, component, file)?

[gregshue]

@romkell I have found it very useful to use "start-time" to distinguish reset-vector up to when the entire executable is finished with initialization (entering main()), and reserve "runtime" for after that point.

the first line of RTOS code (I guess after C main)

If you do not count the init sequence itself as RTOS code (which I don't) then the first line of RTOS code happens very early in the init sequence.

until application execution starts

Almost the entire application could be initialized and run through SYSINIT() hooks. That may have some of the application running before the RTOS is fully up. All that may be needed in main() is to announce when the system initialization is done (which really ought to be another SYSINIT() notification) and wait for a signal to return and let the shutdown execute (which might be a better implementation of __weak__ main()).

[gregshue]

"option" is fine for me. It is clear enough but generic, not directly describing the interface.

At some level of decomposition the requirements on the interface must be captured. (After all, what do the function signatures link to?) Above that level "option" is fine. Below that level it is not. The big question is what is that decomposition level when these are end-user-facing public interfaces? I find "Zephyr RTOS" too vague. I propose it is Zephyr Platform since this public API is directly used by supplementary subsystems and drivers in other modules.

[gregshue]

1. "Until" prevents this statement from being Atomic.
2. "If" as used here will create confusion with how it is used in the recommended EARS syntax, where it indicates an undesirable condition.
3. This behavior does not apply under all conditions, so the statement is missing at least one conditional. One case where this behavior does not apply is when it is requested as a non-blocking call. Until these conditions are stated here the requirement is not Independent of other requirements.

Consider expressing it in the (recommended) EARS syntax. Here is an example:
While a Counting Semaphore count is 0,

When a thread takes that Counting Semaphore with a FOREVER timeout,

the Zephyr RTOS shall block the taking thread waiting for the availability of that Counting Semaphore.

[simhein]

Not needed blank line

[simhein]

Maybe change within the specified time to within the set timeout time to make it more clear that the time is the one from the acquisition timeout.