diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index a39b6662..ba7c7dfd 100644 --- a/docs/software_requirements/index.sdoc +++ b/docs/software_requirements/index.sdoc @@ -69,3 +69,6 @@ FILE: tracing.sdoc [DOCUMENT_FROM_FILE] FILE: condition_variables.sdoc + +[DOCUMENT_FROM_FILE] +FILE: scheduling.sdoc diff --git a/docs/software_requirements/scheduling.sdoc b/docs/software_requirements/scheduling.sdoc new file mode 100644 index 00000000..0d96531b --- /dev/null +++ b/docs/software_requirements/scheduling.sdoc @@ -0,0 +1,204 @@ +[DOCUMENT] +TITLE: Scheduling +REQ_PREFIX: ZEP-SRS-23- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[SECTION] +TITLE: Thread Scheduling Algorithm + +[REQUIREMENT] +UID: ZEP-SRS-23-001 +STATUS: Active +TYPE: Functional +COMPONENT: Thread Scheduling +TITLE: Priority-Based Selection +STATEMENT: >>> +The Zephyr RTOS shall select the highest priority ready thread as the current thread from the ready queue. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-002 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Earliest Deadline First Scheduling +STATEMENT: >>> +When earliest-deadline-first (EDF) scheduling is enabled, the Zephyr RTOS shall prioritize threads with equal static priority based on earliest deadline. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to be able to schedule threads by earliest deadline first. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-003 +STATUS: Active +TYPE: Non-Functional +COMPONENT: Scheduling +TITLE: Ready Queue Scalability +STATEMENT: >>> +The Zephyr RTOS shall support configurable ready queue implementations. +<<< + +[/SECTION] + +[SECTION] +TITLE: Reschedule Points + +[REQUIREMENT] +UID: ZEP-SRS-23-004 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Mandatory Context Switch Triggers +STATEMENT: >>> +The Zephyr RTOS shall trigger rescheduling during: thread state transitions (→SUSPENDED/WAITING), ISR returns, explicit k_yield() calls, and time slice expiration. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-005 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Atomic Rescheduling +STATEMENT: >>> +The Zephyr RTOS shall perform rescheduling atomically at designated points to prevent partial state corruption during thread swaps. +<<< + +[/SECTION] + +[SECTION] +TITLE: Thread States and Priorities + +[REQUIREMENT] +UID: ZEP-SRS-23-006 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Cooperative Thread Non-Preemption +STATEMENT: >>> +The Zephyr RTOS shall ensure Cooperative threads (negative priority) retain execution until explicitly yielding or entering unready state. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to be able to configure thread prioritizes which cannot be preempted by other user threads. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-007 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Preemptive Thread Interruption +STATEMENT: >>> +The Zephyr RTOS shall allow Preemptive threads (≥0 priority) to be interrupted immediately by higher-priority ready threads. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want that the OS preempt running threads by a thread with higher priority. +<<< + +[/SECTION] + +[SECTION] +TITLE: Time Slicing + +[REQUIREMENT] +UID: ZEP-SRS-23-008 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Cooperative Voluntary Yielding +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism for Cooperative threads to allow equal/higher priority threads to execute before resuming. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-009 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Preemptive Time Quantum +STATEMENT: >>> +The Zephyr RTOS shall ensure Preemptive threads relinquish CPU after a configurable time slice (system ticks) if equal-priority threads are ready. +<<< + +[/SECTION] + +[SECTION] +TITLE: Thread Management + +[REQUIREMENT] +UID: ZEP-SRS-23- +STATUS: Draft +TYPE: Functional +COMPONENT: Scheduling +TITLE: Scheduling multiple threads +STATEMENT: >>> +The Zephyr RTOS shall provide an interface to schedule multiple threads. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-16 + +[REQUIREMENT] +UID: ZEP-SRS-23-010 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Non-Preemptible Critical Sections +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism to treat preemptive threads as cooperative until a unlock function is called. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-011 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Thread Sleeping +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism to delay thread execution within ±1 tick of requested duration. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-011 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Thread Waking +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism to for a thread to wake another thread. Note: A wakeup can be attempted on a thread that is already awake - this has no effect. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-23-012 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Busy Wait Non-Relinquishing +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism to perform a busy wait where the Zephyr RTOS will not yield CPU or trigger rescheduling during delay. +<<< + +[/SECTION] + +[SECTION] +TITLE: SMP Considerations + +[REQUIREMENT] +UID: ZEP-SRS-23-015 +STATUS: Active +TYPE: Functional +COMPONENT: Scheduling +TITLE: Deterministic Latency +STATEMENT: >>> +Worst-case context switch latency shall be ≤X μs (platform-specific). +<<< + +[/SECTION] + diff --git a/docs/software_requirements/symmetric_multiprocessing.sdoc b/docs/software_requirements/symmetric_multiprocessing.sdoc new file mode 100644 index 00000000..914d4633 --- /dev/null +++ b/docs/software_requirements/symmetric_multiprocessing.sdoc @@ -0,0 +1,80 @@ +[DOCUMENT] +TITLE: Symmetric Multiprocessing +REQ_PREFIX: ZEP-SRS-24- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[REQUIREMENT] +UID: ZEP-SRS-24- +STATUS: Draft +TYPE: Functional +COMPONENT: Multi Core +TITLE: Support operation on more than one CPU +STATEMENT: >>> +The Zephyr RTOS shall support operation on more than one physical CPU sharing the same kernel state. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-2-2 +STATUS: Draft +TYPE: Functional +COMPONENT: Multi Core +TITLE: Running threads on specific CPUs +STATEMENT: >>> +The Zephyr RTOS shall provide an interface for running threads on specific sets of CPUs ( default is 1 CPU). +<<< +USER_STORY: >>> +As a Zephyr RTOS user I want Zephyr OS to be able to specify the CPU core or the set of CPU cores on which a thread shall be executed. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-2-3 +STATUS: Draft +TYPE: Functional +COMPONENT: Multi Core +TITLE: Exclusion between physical CPUs +STATEMENT: >>> +The Zephyr RTOS shall provide an interface for mutual exclusion between multiple physical CPUs. +<<< +USER_STORY: >>> +As a Zephyr RTOS user I want Zephyr OS to provide synchronization mechanisms between the CPU cores and the access to common resources. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-24- +STATUS: Draft +TYPE: Functional +COMPONENT: Scheduling +TITLE: Affinity Awareness +STATEMENT: >>> +The Zephyr RTOS shall honor thread-CPU affinity masks in SMP configurations. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-24- +STATUS: Draft +TYPE: Functional +COMPONENT: Symmetric Multiprocessing +TITLE: Cross-CPU Atomicity +STATEMENT: >>> +The Zephyr RTOS shall ensure that Spinlocks enforce cross-CPU mutual exclusion for Zephyr RTOS data structures. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-24- +STATUS: Draft +TYPE: Functional +COMPONENT: Symmetric Multiprocessing +TITLE: Time sharing of CPU resources +STATEMENT: >>> +The Zephyr RTOS shall support time sharing of CPU resources among threads of the same priority. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to be able to configure my RTOS in the way, that the CPU resources are shared evenly among executed threads of the same priority. +<<< diff --git a/docs/software_requirements/thread_events.sdoc b/docs/software_requirements/thread_events.sdoc new file mode 100644 index 00000000..a10c78c9 --- /dev/null +++ b/docs/software_requirements/thread_events.sdoc @@ -0,0 +1,28 @@ +[DOCUMENT] +TITLE: Thread Events +REQ_PREFIX: ZEP-SRS-25- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[REQUIREMENT] +UID: ZEP-SRS-25- +STATUS: Draft +TYPE: Functional +COMPONENT: Thread Events +TITLE: Scheduling a thread based on an event +STATEMENT: >>> +The Zephyr RTOS shall provide an interface to schedule a thread based on an event. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to be able to execute work which reacts on events and interrupts the current executed work. +<<< +RELATIONS: +- TYPE: Parent + VALUE: ZEP-SYRS-15 + diff --git a/docs/software_requirements/thread_scheduling.sdoc b/docs/software_requirements/thread_scheduling.sdoc deleted file mode 100644 index 01646837..00000000 --- a/docs/software_requirements/thread_scheduling.sdoc +++ /dev/null @@ -1,164 +0,0 @@ -[DOCUMENT] -TITLE: Thread Scheduling -REQ_PREFIX: ZEP-SRS-2- - -[GRAMMAR] -IMPORT_FROM_FILE: software_requirements.sgra - -[TEXT] -STATEMENT: >>> -SPDX-License-Identifier: Apache-2.0 -<<< - -[SECTION] -TITLE: Thread Scheduling - -[REQUIREMENT] -UID: ZEP-SRS-2-1 -STATUS: Draft -TYPE: Functional -COMPONENT: Multi Core -TITLE: Support operation on more than one CPU -STATEMENT: >>> -The Zephyr RTOS shall support operation on more than one physical CPU sharing the same kernel state. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-2 -STATUS: Draft -TYPE: Functional -COMPONENT: Multi Core -TITLE: Running threads on specific CPUs -STATEMENT: >>> -The Zephyr RTOS shall provide an interface for running threads on specific sets of CPUs ( default is 1 CPU). -<<< -USER_STORY: >>> -As a Zephyr RTOS user I want Zephyr OS to be able to specify the CPU core or the set of CPU cores on which a thread shall be executed. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-3 -STATUS: Draft -TYPE: Functional -COMPONENT: Multi Core -TITLE: Exclusion between physical CPUs -STATEMENT: >>> -The Zephyr RTOS shall provide an interface for mutual exclusion between multiple physical CPUs. -<<< -USER_STORY: >>> -As a Zephyr RTOS user I want Zephyr OS to provide synchronization mechanisms between the CPU cores and the access to common resources. -<<< - -[/SECTION] - -[SECTION] -TITLE: Thread Scheduling - -[REQUIREMENT] -UID: ZEP-SRS-2-4 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Scheduling a thread based on an event -STATEMENT: >>> -The Zephyr RTOS shall provide an interface to schedule a thread based on an event. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to execute work which reacts on events and interrupts the current executed work. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-15 - -[REQUIREMENT] -UID: ZEP-SRS-2-5 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Deadline Scheduling Priorities -STATEMENT: >>> -The Zephyr RTOS shall organize running threads by earliest deadline first priority. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to schedule threads by earliest deadline first. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-6 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Work Queue utility capable of running preemptible work items -STATEMENT: >>> -The Zephyr RTOS shall provide a thread-pooled work queue utility capable of running preemptible work items with specific scheduler priorities. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to add work items in a thread work queue with different priorities and these shall be scheduled according their priorities. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-7 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Run user supplied functions in-order in a separate thread(s) -STATEMENT: >>> -The Zephyr RTOS shall provide an interface for running user-supplied functions. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to run functions in-order in a separated thread/threads. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-8 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Organize running threads into a fixed list -STATEMENT: >>> -The Zephyr RTOS shall organize running threads into a fixed list of numeric priorities. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want that the OS organize running threads in a fixed list of numeric priorities. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-9 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Preemption support -STATEMENT: >>> -The Zephyr RTOS shall support preemption of a running thread by a higher priority thread. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want that the OS preempt running threads by a thread with higher priority. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-10 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Un-preemptible thread priorities -STATEMENT: >>> -The Zephyr RTOS shall support thread priorities which cannot be preempted by other user threads. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to configure thread prioritizes which cannot be preempted by other user threads. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-2-11 -STATUS: Draft -TYPE: Functional -COMPONENT: Thread Scheduling -TITLE: Time sharing of CPU resources -STATEMENT: >>> -The Zephyr RTOS shall support time sharing of CPU resources among threads of the same priority. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to be able to configure my RTOS in the way, that the CPU resources are shared evenly among executed threads of the same priority. -<<< - -[/SECTION] diff --git a/docs/software_requirements/threads.sdoc b/docs/software_requirements/threads.sdoc index fdbffa91..87591c76 100644 --- a/docs/software_requirements/threads.sdoc +++ b/docs/software_requirements/threads.sdoc @@ -17,7 +17,7 @@ TYPE: Functional COMPONENT: Threads TITLE: Creating threads STATEMENT: >>> -The Zephyr RTOS shall provide an interface to create (start) a thread. +The Zephyr RTOS shall provide an interface to create a thread. <<< RELATIONS: - TYPE: Parent @@ -149,19 +149,6 @@ RELATIONS: - TYPE: Parent VALUE: ZEP-SYRS-16 -[REQUIREMENT] -UID: ZEP-SRS-1-10 -STATUS: Draft -TYPE: Functional -COMPONENT: Threads -TITLE: Scheduling multiple threads -STATEMENT: >>> -The Zephyr RTOS shall provide an interface to schedule multiple threads. -<<< -RELATIONS: -- TYPE: Parent - VALUE: ZEP-SYRS-16 - [REQUIREMENT] UID: ZEP-SRS-1-11 STATUS: Draft @@ -197,3 +184,4 @@ RELATIONS: VALUE: ZEP-SYRS-15 - TYPE: Parent VALUE: ZEP-SYRS-16 + diff --git a/docs/system_requirements/index.sdoc b/docs/system_requirements/index.sdoc index a73ccdaf..679f603b 100644 --- a/docs/system_requirements/index.sdoc +++ b/docs/system_requirements/index.sdoc @@ -266,6 +266,49 @@ USER_STORY: >>> As a Zephyr RTOS user, I want to be able to give my threads different priorities for execution. <<< +[REQUIREMENT] +UID: ZEP-SYRS- +STATUS: Draft +TYPE: Functional +COMPONENT: Workqueue Threads +TITLE: Work Queue utility capable of running preemptible work items +STATEMENT: >>> +The Zephyr RTOS shall provide a thread-pooled work queue utility capable of running preemptible work items with specific scheduler priorities. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to be able to add work items in a thread work queue with different priorities and these shall be scheduled according their priorities. +<<< + +[REQUIREMENT] +UID: ZEP-SYRS-23 +STATUS: Draft +TYPE: Functional +COMPONENT: Thread Scheduling +TITLE: Thread Scheduling +STATEMENT: >>> +The Zephyr RTOS shall provide a scheduler that determines which thread is allowed to execute at any point in time. +<<< + +[REQUIREMENT] +UID: ZEP-SYRS- +STATUS: Draft +TYPE: Functional +COMPONENT: Thread Events +TITLE: Thread Events +STATEMENT: >>> +The Zephyr RTOS shall provide a mechanism for threads to synchronize and communicate by signaling and waiting for the occurrence of defined events. +<<< + +[REQUIREMENT] +UID: ZEP-SYRS- +STATUS: Draft +TYPE: Functional +COMPONENT: Symmetric Multiprocessing +TITLE: Symmetric Multiprocessing +STATEMENT: >>> +The Zephyr RTOS shall provide the functionality to support the use of multiple physical CPUs with Zephyr Application code. +<<< + [/SECTION] [REQUIREMENT] @@ -308,3 +351,4 @@ The Zephyr RTOS shall provide a framework to synchronize threads based on a cond <<< [/SECTION] +