Add atomic-services requirement#136
Conversation
f387442 to
38c0eef
Compare
anobli
changed the title
This adds requirements for the atomic services. Signed-off-by: Alexandre Bailon <abailon@baylibre.com>
38c0eef to
a82fa6e
Compare
|
can you please rebase? |
| COMPONENT: Atomic Service | ||
| TITLE: Consistency | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall guarantee that each operation on an atomic variable is free from torn reads or writes, and that its result is visible to all processors in the system. |
There was a problem hiding this comment.
Consider splitting into 2 requirements (atomicity) 1. free from torn and 2. Visibility
| COMPONENT: Atomic Service | ||
| TITLE: Indivisibility | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism for performing all Atomic Service operations on an atomic variable in an indivisible manner. |
There was a problem hiding this comment.
Not a major issue, but could rephrase with "The Zephyr RTOS shall provide a mechanism for performing all operations on a variable in an indivisible manner."
The answer to that mechanism is the creation of the Atomic Services component.
Then non expert question: Is indivisibility an implementation decision to avoid torn read/writes? Asking because we could leave it up to the architecture/low level design/code developers to document/decide on how to avoid torn read/write. Thus decoupling the "what" from the "how"
If so, then consider removing this sub-requirement (and leaving it up to architecture/deisgn/code to decide and document the how)
| COMPONENT: Atomic Service | ||
| TITLE: Platform independence | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide atomic operations on all supported platforms, regardless of whether the hardware or toolchain provides native atomic instruction support. |
There was a problem hiding this comment.
Consider rephrasing this requirement.
"All supported platforms" is ambiguous/undetermined, it is also not in scope of the Kernel.
It is up to the final integrators to ensure the atomic operations work on their target platform.
A potential rephrase could be "The Zephyr RTOS shall support executing atomic operations on hardware that does not provide native atomic instruction support"
Thus guiding the architects to think of a software only solution/option
You then can also have
"The Zephyr RTOS shall support executing atomic operations using native hardware atomic instruction support"
| COMPONENT: Atomic Service | ||
| TITLE: Compute size of atomic variables | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a compile-time mechanism for computing the minimum number of atomic variables necessary to represent a bit array of a given number of bits, rounding up to the nearest whole atomic variable. |
There was a problem hiding this comment.
Nearest is ambiguous, please refine using half round up, half round down, ceil or floor.
| COMPONENT: Atomic Service | ||
| TITLE: Initialize atomic variable | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism for initializing an atomic variable. |
There was a problem hiding this comment.
consider adding "compile-time" since there is no runtime init function
| COMPONENT: Atomic Service | ||
| TITLE: Atomic value operations | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide operations for reading, writing, and modifying atomic variables. All such operations shall use the atomic value type and satisfy the consistency, indivisibility, memory ordering, and platform independence requirements. |
There was a problem hiding this comment.
Consider splitting
- The Zephyr RTOS shall provide operations for reading and modifying (note the removal of writing, which is similar to modifying, also consider using getting/setting to remain consistent with documentation/function terminology) atomic variables.
- The Zephyr RTOS reading, writing, and modifying operations for atomic variables shall use the atomic value type
- The Zephyr RTOS reading, writing, and modifying operations for atomic variables shall satisfy the consistency, indivisibility, memory ordering, and platform independence requirements.
However, I'd consider removing - since ZEP-SRS-26-2 already requires atomic variable operations to be done on the type defined there
- since it would be redundant to ZEP-SRS-26-4 / 5 / 6
There was a problem hiding this comment.
After review of rest of requirements, consider removing altogether to simplify
- There is no function to just set (without returning previous value) and that "get and set" is already covered by -12
- 13 covers get
This will simplify review/test linkeage/maintenance
| COMPONENT: Atomic Service | ||
| TITLE: Atomic compare and set | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism for setting an atomic variable to a new value if and only if its current value equals the expected value, leaving the atomic variable unchanged otherwise, and return whether the atomic variable was updated. |
There was a problem hiding this comment.
Assuming this is for atomic_cas consider changing
- "the expected value" to "an expected value", as "the" could infer that the value is inferred from the "new value", and not from "an expected value" that is passed as a parameter
- "return" to "returning" to match "for setting"
| COMPONENT: Atomic Service | ||
| TITLE: Atomic bit operations | ||
| STATEMENT: >>> | ||
| When performing a bit-level operation, the Zephyr RTOS shall support operating on individual bits within either a single atomic variable or an array of atomic variables. All such operations shall satisfy the consistency, indivisibility, memory ordering, and platform independence requirements. |
There was a problem hiding this comment.
Consider removing "All such operations shall satisfy the consistency, indivisibility, memory ordering, and platform independence requirements." since already covered by overall atomic operation statement from 3 4 5 6
If you want a parent requirement for bit operations, consider: "The Zephyr RTOS shall support performing bit-level operation on individual bits within either a single atomic variable or an array of atomic variables."
| COMPONENT: Atomic Service | ||
| TITLE: Atomic pointer compare and set | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide a mechanism for setting an atomic pointer to a new value if and only if its current value equals the expected value, leaving the atomic pointer unchanged otherwise, and return whether the atomic pointer was updated. |
There was a problem hiding this comment.
Similar remark to atomic cas
| COMPONENT: Atomic Service | ||
| TITLE: Atomic Service | ||
| STATEMENT: >>> | ||
| The Zephyr RTOS shall provide an interface for reading and modifying variables in threads and interrupt service routines in an uninterruptible manner. |
There was a problem hiding this comment.
Consider replacing "uninterruptible" by "atomic operations"
"interrupt" feels to close to the "how" which is ensuring no interrupts are possible to guarantee "atomicity" of the operation, the "what"
Could also use the "free from torn reads or writes across all processors" as mentioned in the SW reqs.
Suggestion:
"The Zephyr RTOS shall provide an interface to perform atomic operations on variables, guaranteeing that all reads and writes are free from tearing across all processors."
4 participants
This adds requirements for the atomic services.
This should cover many existing features of Zephyr RTOS atomic services.
I know there are missing requirements but I would be interested in having some feedback before going further.
This is the first time I am doing that and I would happy to exchange to improve my first requirements and then figure out how to write correctly the missing ones!
Please note that I have been using IA for checking / fixing spelling mistake and for reviewing what I did!