Skip to content

requirements: correct misc Threads requirements for accuracy and add new Thread requirements#142

Open
nashif wants to merge 15 commits into
zephyrproject-rtos:mainfrom
nashif:topic/req/thread_001
Open

requirements: correct misc Threads requirements for accuracy and add new Thread requirements#142
nashif wants to merge 15 commits into
zephyrproject-rtos:mainfrom
nashif:topic/req/thread_001

Conversation

@nashif

@nashif nashif commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

correct misc Threads requirements for accuracy and add new Thread requirements

look at individual commits for details.

@nashif
nashif force-pushed the topic/req/thread_001 branch from 896f4b9 to 3256bae Compare June 25, 2026 22:26
@nashif nashif changed the title requirements: correct Threads requirements for accuracy requirements: correct misc Threads requirements for accuracy and add new Thread requirements Jun 25, 2026
anobli
anobli reviewed Jun 29, 2026
View reviewed changes

@anobli anobli left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated and added requirements for threads look good to me.
Regarding the changes for thread scheduling, there is #85 what would deserve another round of review and to be merge before.

nashif and others added 15 commits July 18, 2026 08:58
@nashif
requirements: correct Threads requirements for accuracy
f14f38d 
Audit of the Threads software requirements against the implemented
k_thread API found several inaccurate or weak statements:

- ZEP-SRS-1-5 described "resuming a suspended thread after a timeout",
  which no API provides: suspension persists until k_thread_resume()
  regardless of any timeout. Repurpose it to the real, adjacent
  capability of delayed thread start (the k_thread_create delay).
- ZEP-SRS-1-1 conflated creating and starting a thread; restrict it to
  run-time creation.
- ZEP-SRS-1-6 reworded to use the implementation term "abort".
- ZEP-SRS-1-7 reworded from a vague statement into a single, clear one.
- ZEP-SRS-1-8 reworded for clarity and grammar.
- ZEP-SRS-1-10 ("Scheduling multiple threads") removed as redundant with
  the Thread Scheduling document.

No requirement UIDs were renumbered; nothing references the removed
ZEP-SRS-1-10.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: add missing Threads software requirements
3b9316f 
Audit of the Threads software requirements against the implemented
k_thread API found several user-facing capabilities without a
requirement. Add nine requirements (ZEP-SRS-1-13 .. ZEP-SRS-1-21):

- Defining a thread at compile time (K_THREAD_DEFINE)
- Starting an inactive thread (k_thread_start)
- Passing parameters to a thread entry point (k_thread_create p1..p3)
- Getting a thread's priority (k_thread_priority_get)
- Assigning a thread name (k_thread_name_set)
- Retrieving a thread name (k_thread_name_get)
- Identifying the current thread (k_current_get)
- Waiting for a thread to terminate (k_thread_join)
- Querying a thread state (k_thread_state_str)

The requirements reflect the currently implemented behavior following
the Route 3s approach and link to the existing Threads system parents.
UIDs were generated with "strictdoc manage auto-uid".

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: fix wording in Threads stack user story
f48cb8b 
Correct the grammar in the ZEP-SRS-1-8 user story ("it's" -> "its",
run-on sentence) to match the reworded statement.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: correct Thread Scheduling structure and accuracy
b60cbe6 
Audit of the Thread Scheduling requirements found structural,
traceability, and accuracy issues:

- The first section was titled "Thread Scheduling" but contains only
  multi-core/SMP requirements; rename it to "Multi Core and SMP".
- ZEP-SRS-2-1, 2-2, 2-3 (multi-core) had no parent links; relate them to
  the SMP system requirements (ZEP-SYRS-11, ZEP-SYRS-12).
- ZEP-SRS-2-5, 2-8, 2-9, 2-10, 2-11 had no parent links; relate them to
  the thread management and priority system requirements (ZEP-SYRS-16,
  ZEP-SYRS-17).
- ZEP-SRS-2-5 overstated earliest-deadline-first scheduling; reword it as
  a config-gated tie-breaker among ready threads of equal static
  priority, matching the implementation.
- ZEP-SRS-2-6 and 2-7 described the work queue utility and are now
  redundant with the dedicated Work Queues document (ZEP-SRS-26);
  remove them.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: add missing Thread Scheduling requirements
bc98160 
Add six requirements (ZEP-SRS-2-12 .. ZEP-SRS-2-17) for core scheduling
behavior that had no requirement:

- Selecting the highest-priority ready thread as the current thread
- Scheduling order among ready threads of equal priority
- Cooperative threads (run until they yield or block)
- Yielding the CPU (k_yield)
- Locking the scheduler (k_sched_lock / k_sched_unlock)
- Setting a thread deadline (k_thread_deadline_set)

The requirements reflect the currently implemented scheduler behavior
following the Route 3s approach and link to the thread management and
priority system requirements. UIDs were generated with
"strictdoc manage auto-uid".

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
Add thread requirements for configurable thread features
ccfe0f6 
Capture implemented, configuration-driven thread capabilities not yet
reflected as requirements (Route 3s):

- ZEP-SRS-1-22 Single-thread operation (MULTITHREADING=n)
- ZEP-SRS-1-23 Thread-local storage (THREAD_LOCAL_STORAGE)
- ZEP-SRS-1-24 Allocating a thread stack at run time (DYNAMIC_THREAD)
- ZEP-SRS-1-25 Releasing a run-time allocated thread stack
- ZEP-SRS-1-26 Iterating over threads (THREAD_MONITOR)
- ZEP-SRS-1-27 Querying thread stack usage (THREAD_STACK_INFO)
- ZEP-SRS-1-28 Thread runtime statistics (THREAD_RUNTIME_STATS)
- ZEP-SRS-1-29 Total system runtime statistics
- ZEP-SRS-1-30 Runtime stack safety monitoring (THREAD_RUNTIME_STACK_SAFETY)

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: add main thread, idle thread, thread timeout query
106e191 
A sweep of tests/kernel/threads against the Threads component found three
implemented, tested capabilities with no corresponding requirement:

- ZEP-SRS-1-31 Main thread (kernel-provided thread that runs the
  application entry point; verified by test_systhreads_main)
- ZEP-SRS-1-32 Idle thread (runs when no other thread is ready; verified
  by test_systhreads_idle)
- ZEP-SRS-1-33 Querying a thread's pending timeout
  (k_thread_timeout_remaining_ticks / k_thread_timeout_expires_ticks;
  verified by test_thread_timeout_remaining_expires)

All parented to ZEP-SYRS-15 / ZEP-SYRS-16.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: add thread runtime-stats enable/disable
725cecb 
- k_thread_runtime_stats_enable/disable + k_sys_runtime_stats_enable/
  disable -> ZEP-SRS-1-34 'Enabling and disabling thread runtime
  statistics' (1-28/1-29 covered only querying;
  tests/kernel/usage/thread_runtime_stats).

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: threads: add compile-time thread stack definition
9c642e0 
The thread requirements cover the dedicated per-thread stack
(ZEP-SRS-1-8) and the run-time stack allocation and release paths
(ZEP-SRS-1-24/25), but no requirement captures defining a thread stack
of a chosen size at compile time, which is the primary way applications
provide thread stacks.

Add ZEP-SRS-1-35 for the compile-time stack definition mechanism.

Derived from the gap identified in reqmgmt PR zephyrproject-rtos#73.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: threads: drop boilerplate user stories
20528bb 
Remove the generic user stories from the thread software requirements
and the thread system requirements. Per the requirements checklist a
USER_STORY is only added when it clarifies intent beyond the statement;
these restated the requirement in as-a-user form without adding
information.

Adopts the cleanup proposed for the thread sections in reqmgmt PR zephyrproject-rtos#73.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: move Multicore and SMP requirements to a dedicated docu…
53a1305 
…ment

SMP / multicore support is an isolatable, configurable feature
(CONFIG_SMP) and was mixed into the Thread Scheduling document. Move the
three multi-core requirements (formerly ZEP-SRS-2-1, 2-2, 2-3) into a
new dedicated Multicore and SMP document (ZEP-SRS-34-*), removing the
"Multi Core and SMP" section from Thread Scheduling and registering the
new document in the software requirements index.

The requirement statements and their parent links (ZEP-SYRS-11,
ZEP-SYRS-12) are unchanged; only their location and UIDs change. UIDs
were generated with "strictdoc manage auto-uid".

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
threads: Per-thread time slice (CONFIG_TIMESLICE_PER_THREAD)
a03e8e0 
Add per thread time slidcing requirement.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
requirements: add forcing a reschedule and querying preemptibility
7fca26d 
Sweep of tests/kernel/sched against the Thread Scheduling component
found two implemented, tested public scheduling APIs with no requirement:

- ZEP-SRS-2-19 Forcing a scheduling decision (k_reschedule();
  verified by deadline/test_thread_reschedule)
- ZEP-SRS-2-20 Querying thread preemptibility (k_is_preempt_thread();
  verified by test_sched_is_preempt_thread and user_api/test_user_k_is_preempt)

Both parented to ZEP-SYRS-16.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif @jkey-eng
requirements: scheduling: add ready queue, meta-IRQ and slice threshold
5251278 
Adopt three scheduling requirements identified in reqmgmt PR zephyrproject-rtos#85 that
the current set did not cover:

- ZEP-SRS-2-21: the scheduler's ready queue implementation is
  selectable at build time.
- ZEP-SRS-2-22: a ready meta-IRQ thread is scheduled in preference to
  all other threads, including cooperative threads.
- ZEP-SRS-2-23: threads above a configurable priority threshold are
  exempt from time slicing.

Statements reworked into EARS form with parent relations; the concepts
originate from PR zephyrproject-rtos#85 (scheduling.sdoc items 23-003, 23-006 and
23-017).

Co-authored-by: Joel Key <Joel@keyengineeringllc.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif @jkey-eng
requirements: scheduling: make time sharing requirement verifiable
0979086 
ZEP-SRS-2-11 stated that CPU time is shared among threads of the same
priority without saying when or by how much, leaving no acceptance
criterion. Rephrase it with the bounded, testable form proposed in
reqmgmt PR zephyrproject-rtos#85 (item 23-009): the current thread relinquishes the CPU
after not more than a configurable time slice period whenever other
ready threads of the same priority exist.

Co-authored-by: Joel Key <Joel@keyengineeringllc.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
@nashif
nashif force-pushed the topic/req/thread_001 branch from 3256bae to 0979086 Compare July 18, 2026 13:00
This was referenced Jul 18, 2026
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@parphane parphane Awaiting requested review from parphane parphane is a code owner
@tobiaskaestner tobiaskaestner Awaiting requested review from tobiaskaestner tobiaskaestner is a code owner
@nicpappler nicpappler Awaiting requested review from nicpappler nicpappler is a code owner
1 more reviewer
@anobli anobli anobli left review comments
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nashif @anobli