Zephyr Software Requirements

Hardware Architecture Interface

The Zephyr RTOS shall provide an interface functionality to access memory while ensuring mutual exclusion. Note: Implementation by atomic variables and accessing them by APIs.

The Zephyr RTOS shall provide a mechanism for context switching between threads.

The Zephyr RTOS shall provide an interface to implement software exceptions.

The Zephyr RTOS shall provide an interface for managing processor modes.

C Library

The Zephyr RTOS shall support formatted output.

The Zephyr RTOS shall support floating point math libraries for processors where floating point is available.

The Zephyr RTOS shall support boolean primitives.

The Zephyr RTOS shall support the standard UNIX time interface.

The Zephyr RTOS shall support an interface to manage strings.

The Zephyr RTOS shall support an interface to move contents between regions of memory.

The Zephyr RTOS shall support a file i/O based interface for driver communication.

The Zephyr RTOS shall support standard C99 integer types.

The Zephyr RTOS shall support standard system error numbers as defined by IEEE Std 1003.1-2017.

The set of C Library functions required by Zephyr needs to be documented in the Zephyr Safety Manual.

The Zephyr Safety Manual needs to specify how to configure the support of external C Libraries.

Device Driver API

The Zephyr RTOS shall provide abstraction of device drivers with common functionalities as an intermediate interface between applications and device drivers, where such interface is implemented by individual device drivers.

Proposal for replacement: Zephyr shall provide an interface between application and individual device drivers to provide an abstraction of device drivers with common functionalities.

The Zephyr RTOS shall provide an interface for managing a defined set of hardware exceptions (including interrupts) across all systems.

Exception and Error Handling

The Zephyr RTOS shall provide default handlers for exceptions.

The Zephyr RTOS shall provide default handlers for fatal errors that do not have a dedicated handler.

The Zephyr RTOS shall provide an interface to assign a specific handler with an exception.

The Zephyr RTOS shall provide an interface to assign a specific handler for a fatal error.

File System

Zephyr shall provide file create capabilities for files on the file system.

Zephyr shall provide file open capabilities for files on the file system.

Zephyr shall provide read access to files in the file system.

Zephyr shall provide write access to the files in the file system.

Zephyr shall provide file close capabilities for files on the file system.

Zephyr shall provide the capability to move files on the file system.

Zephyr shall provide file delete capabilities for files on the file system.

Interrupts

Zephyr RTOS shall provide a mechanism to initialize a static IRQ service routine (ISR), providing all parameters needed to configure the hardware and software.

The static IRQ shall be initially disabled.

Zephyr RTOS shall provide a mechanism to initialize a direct IRQ handler, providing all parameters needed to configure the hardware and software.

The direct IRQ shall be initially disabled.

Zephyr RTOS shall provide a mechanism to initialize a dynamic IRQ service routine, providing all parameters needed to configure the hardware and software.

The dynamic IRQ shall be initially disabled.

Zephyr RTOS shall provide a mechanism to uninstall a dynamic ISR.

Zephyr RTOS shall provide a mechanism to Disable all IRQs on a CPU, and return the state the IRQ hardware prior to being disabled.

Zephyr RTOS shall provide a mechanism to Enable all IRQs on a CPU and return them to thier previous state.

Zephyr RTOS shall provide a mechanism to Disable a specified IRQ.

Zephyr RTOS shall provide a mechanism to Enable a specified IRQ.

Zephyr RTOS shall provide mechanisms that returns the Enabled status of a specified IRQ, where the status is Enabled or Disabled.

Zephyr RTOS shall provide mechanisms that returns the execution context, where the context is In-ISR or Not In-ISR.

The Zephyr RTOS shall support multi-level preemptive interrupt priorities, when supported by hardware.

Logging

The Zephyr RTOS shall support isolation of logging from other functionality.

The Zephyr RTOS logging shall produce logs that are capable of being post processed.

The Zephyr RTOS logging shall support formatting of log messages to enable filtering.

The Zephyr RTOS logging system shall support filtering based on severity level.

The Zephyr RTOS shall support logging messages to multiple system resources.

The Zephyr RTOS shall support deferred logging (TODO: need more detail about the constraints and limits on what can be deferred).

Memory Protection

The Zephyr RTOS shall support memory protection features to isolate a thread’s memory region.

The Zephyr RTOS shall provide a mechanism to grant user threads access to kernel objects.

The Zephyr RTOS shall be able to differentiate between user threads and kernel threads for memory access.

The Zephyr RTOS shall have a defined behaviour when an invocation of an unimplemented system call is made.

The Zephyr RTOS shall have a defined behaviour when an invalid system call ID is used.

The Zephyr RTOS shall prevent user threads from creating new threads that are higher priority than the caller.

The Zephyr RTOS shall support revoking permission to a kernel object. User mode threads may only revoke their own access to an object.

The Zephyr RTOS shall prevent user threads from creating kernel threads.

The Zephyr RTOS shall allow the creation of threads that run in reduced privilege level.

The Zephyr RTOS shall provide system calls to allow user mode threads to perform privileged operations.

The Zephyr RTOS shall support a defined mechanism for user mode handling a of detected stack overflow.

The Zephyr RTOS shall support detection of stack overflows.

The Zephyr RTOS shall support configurable access to memory during boot time.

The Zephyr RTOS shall provide helper functions for system call handler functions to validate the inputs passed in from user mode before invoking the implementation function to protect the kernel.

The Zephyr RTOS shall support system calls to be able to safely accept C strings passed in from user mode.

The Zephyr RTOS shall track kernel objects that are used by user mode threads.

Note: this means Zephyr shall track the resources used by the user mode thread (associate this with a user story).

The Zephyr RTOS shall have an interface to request access to specific memory after initial allocation.

The Zephyr RTOS shall support assigning a memory pool to act as that thread’s resource pool.

Memory Objects

The Zephyr RTOS shall allow threads to dynamically allocate variable-sized memory regions from a specified range of memory.

The Zephyr RTOS shall allow threads to dynamically allocate fixed-sized memory regions from a specified range of memory.

Data Passing

The Zephyr RTOS shall provide a kernel object that implements a traditional first in, first out (FIFO) queue, allowing threads and ISRs to add and remove a limited number of 32-bit data values.

The Zephyr RTOS shall provide a kernel object that implements a traditional last in, first out (LIFO) queue, allowing threads and ISRs to add and remove a limited number of 32-bit data values.

Mutex

The Zephyr RTOS shall support resource synchronization. (Note synchronization can be for memory access, and mutex may be one implementation, but not the only one).

Semaphore

The Zephyr RTOS shall provide a mechanism to define and initialize a semaphore at compile time.

The Zephyr RTOS shall provide a mechanism to define and initialize a semaphore at runtime.

The Zephyr RTOS shall define the maximum limit of a semaphore when the semaphore is used for counting purposes and does not have an explicit limit.

When initializing a counting semaphore, the maximum permitted count a semaphore can have shall be set.

When initializing a counting semaphore, the initial semaphore value shall be set.

The Zephyr RTOS shall provide a mechanism allowing threads to acquire a semaphore.

While the semaphore’s count is greater than zero, the requesting thread shall acquire the semaphore and decrement its count.

While the semaphore’s count is zero, the requesting thread shall be blocked until the semaphore is released by another thread.

When attempting to acquire a semaphore, the Zephyr RTOS shall accept options that specify timeout periods, allowing threads to set a maximum wait time for semaphore acquisition.

When attempting to acquire a semaphore, where the semaphore is not acquired within the specified time, the Zephyr RTOS shall return an error indicating a timeout.

When attempting to acquire a semaphore, where the current count is zero and no timeout time was provided, the Zephyr RTOS shall return an error indicating the semaphore is busy.

The Zephyr RTOS shall provide a mechanism allowing threads to release a semaphore.

The Zephyr RTOS shall increment the semaphore’s count upon release.

When there are threads waiting on the semaphore, the highest-priority waiting thread shall be unblocked and acquire the semaphore.

The Zephyr RTOS shall provide a mechanism for threads to check the current count of a semaphore without acquiring it.

The Zephyr RTOS shall provide a mechanism that resets the semaphore count to zero.

When a semaphore is reset, the Zephyr RTOS shall abort all existing acquisitions of the semaphore returning a resource contention error code.

When initializing a counting semaphore, where the maximum permitted count of a semaphore is invalid, then the Zephyr RTOS shall return an error indicating invalid values.

Power Management

The Zephyr RTOS shall provide control over changes to system power states.

TBD

The Zephyr RTOS shall provide notification of changes to system power states.

Thread Communication

The Zephyr RTOS shall provide a mechanism for exchanging data between threads.

The Zephyr RTOS shall provide mechanisms to enable waiting for results during communication between threads. (NOTE: waiting for results is really bad and dangerous, want to avoid if at all possible).

The Zephyr RTOS shall support a poll operation which enables waiting concurrently for any one of multiple conditions to be fulfilled.

The Zephyr RTOS shall provide a communication primitive that allows a thread to transfer a block of data to another thread.

The Zephyr RTOS shall provide a a communication primitive that allow threads and ISRs to asynchronously exchange fixed-size data items.

The Zephyr RTOS shall provide a communication primitive that allows threads to exchange messages of varying sizes asynchronously or synchronously.

Multi Core

The Zephyr RTOS shall support operation on more than one physical CPU sharing the same kernel state.

The Zephyr RTOS shall provide an interface for running threads on specific sets of CPUs ( default is 1 CPU).

The Zephyr RTOS shall provide an interface for mutual exclusion between multiple physical CPUs.

Thread Scheduling

The Zephyr RTOS shall provide an interface to schedule a thread based on an event.

The Zephyr RTOS shall organize running threads by earliest deadline first priority.

The Zephyr RTOS shall provide a thread-pooled work queue utility capable of running preemptible work items with specific scheduler priorities.

The Zephyr RTOS shall provide an interface for running user-supplied functions.

The Zephyr RTOS shall organize running threads into a fixed list of numeric priorities.

The Zephyr RTOS shall support preemption of a running thread by a higher priority thread.

The Zephyr RTOS shall support thread priorities which cannot be preempted by other user threads.

The Zephyr RTOS shall support time sharing of CPU resources among threads of the same priority.

Threads

The Zephyr RTOS shall provide an interface to create (start) a thread.

The Zephyr RTOS shall provide an interface to set a thread’s priority.

The Zephyr RTOS shall provide an interface to suspend a thread.

The Zephyr RTOS shall provide an interface to resume a suspended thread.

The Zephyr RTOS shall provide an interface to resume a suspended thread after a timeout.

The Zephyr RTOS shall provide an interface to delete (end) a thread.

Threads shall have different states to fulfill the Life-cycle of a thread

Every Thread shall have it’s own stack.

The Zephyr RTOS shall provide an interface to create threads with defined privilege.

The Zephyr RTOS shall provide an interface to schedule multiple threads.

The Zephyr RTOS shall support a set of thread options.

Every thread shall have a custom data area.

Timers

The Zephyr RTOS shall provide a interface for checking the current value of the real-time clock.

The Zephyr RTOS shall provide an interface to schedule user mode call back function triggered by a real time clock value.

Tracing

Zephyr shall provide an interface to initialize a trace.

Zephyr shall provide an interface to trigger a trace.

Zephyr shall provide an interface to dump results from a trace.

Zephyr shall provide an interface to remove trace data.

Zephyr shall provide an interface to identify the objects being traced.

Zepyhr shall prevent the tracing functionality from interfering with normal operations.

Condition Variables

The Zephyr RTOS shall provide a mechanism to define and initialize a condition variable dynamically (at runtime).

The Zephyr RTOS shall provide a mechanism to define and initialize a condition variable statically (at compile time).

The Zephyr RTOS shall provide a mechanism to signal the highest priorite waiting thread when a condition is met.

The Zephyr RTOS shall provide a mechanism to signal all waiting threads when a condition is met.

The Zephyr RTOS shall provide a mechanism for a thread to wait on a condition variable.

When waiting on a condition variable, the thread shall specify a timeout value.

When a timeout occurs while waiting on a condition variable, the thread shall be unblocked and a timeout error shall be returned.

If a thread is waiting on a condition variable, the thread shall release the current owned mutex independently.

henever some thread signals a condition variable the Zephyr RTOS shall unblock the highest priority thread currently waiting for this condition variable.