requirements: add Work Queues system and software requirements by nashif · Pull Request #141 · zephyrproject-rtos/reqmgmt

nashif · 2026-06-25T22:08:47Z

Add a System requirement (ZEP-SYRS-26) describing the Zephyr work queue
framework, and a new Work Queues software requirements document
(ZEP-SRS-26-*) refining it into 25 atomic, implementation-free
requirements covering work queue management, work item submission and
processing, status and cancellation, and delayable work.

The requirements reflect the currently implemented k_work API behavior
following the Route 3s approach. All software requirements link to the
ZEP-SYRS-26 system parent, and the new document is registered in the
software requirements index.

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

anobli

Here are a first set of comments. That's all I can achieve today!

anobli · 2026-07-07T12:18:13Z

+<<<
+RELATIONS:
+- TYPE: Parent
+  VALUE: ZEP-SYRS-26


Maybe we should also add ZEP-SYRS-15 which defines thread.

anobli · 2026-07-07T13:20:51Z

+COMPONENT: Work Queues
+TITLE: Work queue thread priority
+STATEMENT: >>>
+When a work queue is started, the Zephyr RTOS shall allow the priority of its dedicated thread to be configured.


I feel like we would need more requirements here:

one for describing k_work_queue_start, and maybe the fact it creates its thread

this one, explaining behavior regarding thread priority

probably another one, about other option given passed to thread using k_work_queue_config

anobli · 2026-07-07T13:22:46Z

+COMPONENT: Work Queues
+TITLE: Work item processing order
+STATEMENT: >>>
+The work queue thread shall process the queued work items in the order in which they were submitted.


nit: inconsistency with other requirement where we have Zephyr RTOS shall

anobli · 2026-07-07T13:28:44Z

+COMPONENT: Work Queues
+TITLE: Work queue definition
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to define a work queue that is served by a dedicated thread.


I am not sure about define word, it more look like init or start

anobli · 2026-07-07T13:48:11Z

+COMPONENT: Work Queues
+TITLE: Work queue thread yielding
+STATEMENT: >>>
+Unless configured otherwise, the work queue thread shall yield to other ready threads between processing successive work items.


This doesn't respect EARS.
Maybe some thing like that would work: When yielding between work items is not disabled, the work queue ...

anobli · 2026-07-07T14:02:09Z

+COMPONENT: Work Queues
+TITLE: Work queue draining
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to wait until all work items submitted to a work queue have been processed.


Something missing here is that we block submitting new item (except if it come from the work queue thread itself).

anobli · 2026-07-07T14:17:35Z

+COMPONENT: Work Queues
+TITLE: Work queue submission blocking on drain
+STATEMENT: >>>
+When a work queue is drained, the Zephyr RTOS shall accept an option that prevents further work items from being submitted to the work queue until it is explicitly unblocked.


The sentence is incorrect. We give the option when we call the draining function not when the work queue has been drained.
A suggestion would be: WHEN a drain operation is initiated with submission blocking enabled, the Zephyr RTOS shall prevent further work items from being submitted to the work queue after the drain completes.

anobli · 2026-07-07T14:31:47Z

+COMPONENT: Work Queues
+TITLE: Work queue stop
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to stop the dedicated thread of a work queue.


I think we must explicitly say that only work on a drained (and refusing new item) work queue.

anobli · 2026-07-07T14:37:04Z

+COMPONENT: Work Queues
+TITLE: Work item submission to the system work queue
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to submit a work item to the system work queue.


We need to define what is a system work queue in my opinion

anobli · 2026-07-07T14:43:09Z

+COMPONENT: Work Queues
+TITLE: Work item handler invocation
+STATEMENT: >>>
+When the work queue thread removes a work item from the queue, the work queue thread shall invoke that work item's handler function.


nit: inconsistency with other requirement where we have Zephyr RTOS shall

anobli · 2026-07-08T08:18:00Z

+COMPONENT: Work Queues
+TITLE: Work item definition
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to define a work item that associates a handler function to be executed when the work item is processed.


We currently have 4 different way to do it: two init functions, one for kernel mode and one for user mode. We also have two macro doing the same thing but at build time.
So, we probably need 4 requirements here.

anobli · 2026-07-08T09:03:42Z

+COMPONENT: Work Queues
+TITLE: Waiting for a work item to complete
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to wait until a submitted work item has been processed by its work queue.


Has been processed is probably ambiguous. A suggestion would be until a submitted work item's handler function has finished executing.

anobli · 2026-07-08T09:08:57Z

+COMPONENT: Work Queues
+TITLE: Work item pending status
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to determine whether a work item is currently pending.


Pending is ambiguous! My initial tough was queued or running but after reading the code, this seems to be much more.

anobli · 2026-07-08T09:23:06Z

+COMPONENT: Work Queues
+TITLE: Cancellation of a running work item handler
+STATEMENT: >>>
+If a work item's handler function has already started running, then cancelling the work item shall not interrupt the execution of that handler function.


nit: inconsistency with other requirement where we have Zephyr RTOS shall

anobli · 2026-07-08T09:35:48Z

+COMPONENT: Work Queues
+TITLE: Cancellation with wait for completion
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to cancel a work item and wait until the work item is neither queued nor running.


is neither queued nor running.. Here, I would have used pending.
I said that pending is ambiguous, which is true so we need to define with a new requirement what is a pending work item, in order to using it in ZEP-SRS-26-16 and here.

anobli · 2026-07-08T09:38:00Z

+COMPONENT: Work Queues
+TITLE: Delayable work item definition
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to define a delayable work item that associates a handler function to be executed when the work item is processed.


Same here, we have both a function for doing it at runtime and a macro fr doing it a build time so we need 2 requirements in my opinion.

anobli · 2026-07-08T09:48:57Z

+COMPONENT: Work Queues
+TITLE: Scheduling a delayable work item
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to schedule a delayable work item to be submitted to a work queue after a specified delay.


We need two requirements here, one for a specific work queue and one for the system queue.

Incorporate the second round of review comments from Aurelien Jarno (anobli) on PR zephyrproject-rtos#141: - Split work item definition by construction path: run-time initialization (26-9, reworded) and compile-time definition (26-34), and likewise for delayable work items (26-20 reworded, 26-35 added). - Add a User Mode Work Queues section (26-37..26-40) covering the implemented user work API: run-time and compile-time user work item definition, starting a work queue whose thread runs in user mode, and submission from user mode threads. - Make "pending" precise (26-16): enumerate the states -- delayed, queued, running, being cancelled, being flushed -- matching the implemented work item state flags, and reuse the defined term in the cancel-and-wait requirement (26-19). - Reword wait-for-completion (26-15) to "until a submitted work item's handler function has finished executing". - Split delayable scheduling by target queue: specified work queue (26-21, reworded) and system work queue (26-36), mirroring the existing submit requirements 26-10/26-11. - Use "the Zephyr RTOS shall" as the acting subject in the running-handler cancellation requirement (26-18). Assisted-by: Claude:claude-fable-5 Signed-off-by: Anas Nashif <anas.nashif@intel.com>

nashif · 2026-07-13T21:38:33Z

@anobli all comments addressed I hope

anobli · 2026-07-16T12:09:26Z

+COMPONENT: Work Queues
+TITLE: Work item timeout monitoring
+STATEMENT: >>>
+Where workqueue work timeout monitoring is enabled, the Zephyr RTOS shall monitor the execution duration of each work item and, if a work item handler runs longer than the configured timeout, abort the work queue thread.


I was not aware of that one. The requirement does the job, despite I would have probably done 2 requirement (one for the monitoring feature itself) and one about behavior in case of time out.
Aside of that, my concerns is more about the feature itself. We are just killing the queue's thread, without any notice (except a log). This looks like something we want to enable for debugging and not as a safety features as we may think when we just read the requirement. Maybe this would deserve some additional notes

there is some ongoing work about fixing this and improving this, see zephyrproject-rtos/zephyr#109844

anobli · 2026-07-16T12:26:42Z

+[[/SECTION]]
+
+[[SECTION]]
+TITLE: Triggered Work


We miss init requirement here I think.

anobli · 2026-07-16T12:27:36Z

+TITLE: Triggered Work
+
+[REQUIREMENT]
+UID: ZEP-SRS-26-27


we need to requirements here, one for the system queue and one for other queues.

anobli · 2026-07-16T12:31:27Z

+COMPONENT: Work Queues
+TITLE: Submitting a triggered work item
+STATEMENT: >>>
+The Zephyr RTOS shall provide a mechanism to submit a work item that is processed when any of a specified set of poll events becomes ready or when a specified timeout elapses, and to report the triggering outcome to the work item handler.


The requirements look quite simple regarding the documentation. As example, we miss a requirement for explaining this behavior: Submitting a previously submitted triggered work item that is still waiting for the event cancels the existing submission and reschedules it the using the new event list from documentation

anobli · 2026-07-16T12:40:57Z

+[[/SECTION]]
+
+[[SECTION]]
+TITLE: User Mode Work Queues


nit: I realize that we don't have any system requirement about kernel and user mode.
Once we will have it (ticket is TODO), we would have to update the requirements here for parenting them with user mode.

Incorporate the second round of review comments from Aurelien Jarno (anobli) on PR zephyrproject-rtos#141: - Split work item definition by construction path: run-time initialization (26-9, reworded) and compile-time definition (26-34), and likewise for delayable work items (26-20 reworded, 26-35 added). - Add a User Mode Work Queues section (26-37..26-40) covering the implemented user work API: run-time and compile-time user work item definition, starting a work queue whose thread runs in user mode, and submission from user mode threads. - Make "pending" precise (26-16): enumerate the states -- delayed, queued, running, being cancelled, being flushed -- matching the implemented work item state flags, and reuse the defined term in the cancel-and-wait requirement (26-19). - Reword wait-for-completion (26-15) to "until a submitted work item's handler function has finished executing". - Split delayable scheduling by target queue: specified work queue (26-21, reworded) and system work queue (26-36), mirroring the existing submit requirements 26-10/26-11. - Use "the Zephyr RTOS shall" as the acting subject in the running-handler cancellation requirement (26-18). Assisted-by: Claude:claude-fable-5 Signed-off-by: Anas Nashif <anas.nashif@intel.com>

kartben · 2026-07-23T20:38:19Z

FWIW commit messages are off, e.g. they mention ZEP-SRS-26-* / ZEP-SYRS-26 instead of ZEP-SRS-38-* / ZEP-SYRS-37.

nashif · 2026-07-23T21:00:06Z

FWIW commit messages are off, e.g. they mention ZEP-SRS-26-* / ZEP-SYRS-26 instead of ZEP-SRS-38-* / ZEP-SYRS-37.

yeah, I just rebased and had to change numbering after atomic services got merged, will fix

Add a System requirement (ZEP-SYRS-37) describing the Zephyr work queue framework, and a new Work Queues software requirements document (ZEP-SRS-38-*) refining it into atomic, implementation-free requirements covering work queue management, work item submission and processing, status and cancellation, delayable work, and user mode work queues. The requirements reflect the currently implemented k_work API behavior following the Route 3s approach: - Work item definition split by construction path: run-time initialization and compile-time definition, for plain, delayable and user work items. - "Pending" made precise (ZEP-SRS-38-16) by enumerating the states -- delayed, queued, running, being cancelled, being flushed -- matching the implemented work item state flags; the cancel-and-wait requirements reuse the defined term. - Delayable scheduling split by target queue (specified work queue and system work queue), mirroring the submit requirements. - Full coverage of the queue lifecycle: initialization, start, processing in the calling thread (k_work_queue_run), drain, submission blocking and unblocking, and stop; also flushing and synchronous cancellation of delayable work items (k_work_flush_delayable, k_work_cancel_delayable_sync). All software requirements link to the ZEP-SYRS-37 system parent (the queue thread requirements also to ZEP-SYRS-15), and the new document is registered in the software requirements index. UIDs were generated with "strictdoc manage auto-uid". Assisted-by: Claude:claude-fable-5 Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Add requirements for the triggered work API, which submits a work item when any of a set of poll events becomes ready or a timeout elapses: - ZEP-SRS-38-27 Submitting a triggered work item - ZEP-SRS-38-28 Cancelling a triggered work item Parented to ZEP-SYRS-37. Assisted-by: Claude:claude-fable-5 Signed-off-by: Anas Nashif <anas.nashif@intel.com>

parphane mentioned this pull request Jun 30, 2026

Work Queue #120

Open

4 tasks

anobli reviewed Jul 7, 2026

View reviewed changes

nashif force-pushed the topic/req/wq branch from 71f33d1 to e999cf7 Compare July 8, 2026 10:31

nashif requested review from nicpappler, parphane and tobiaskaestner as code owners July 8, 2026 10:31

anobli reviewed Jul 9, 2026

View reviewed changes

nashif force-pushed the topic/req/wq branch from e999cf7 to 4fe8dc1 Compare July 13, 2026 21:38

anobli reviewed Jul 16, 2026

View reviewed changes

nashif force-pushed the topic/req/wq branch from 4fe8dc1 to fcc2194 Compare July 23, 2026 20:01

nashif added 2 commits July 23, 2026 18:02

nashif force-pushed the topic/req/wq branch from fcc2194 to 18bf8c2 Compare July 23, 2026 22:09

Uh oh!

Conversation

nashif commented Jun 25, 2026

Uh oh!

anobli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nashif commented Jul 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kartben commented Jul 23, 2026

Uh oh!

nashif commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants