Scheduling Infrastructure API#

Sound Open Firmware (SOF) implements a multi-tiered, real-time task scheduling infrastructure deeply integrated with the underlying Zephyr RTOS. The scheduling architecture accommodates diverse audio execution constraints, ranging from hard real-time, zero-jitter low-latency hardware streaming to asynchronous, compute-intensive data processing algorithms.

Architecture & Execution Domains#

SOF partitions firmware execution across four distinct scheduling domains:

+--------------------+     +------------------------+
| Hardware Timer     |     | DMA Interrupt          |
| (1ms / 500us tick) |     | (Transfer complete)    |
+---------+----------+     +-----------+------------+
          |                            |
+---------v----------------------------v------------+
|             Low-Latency (LL) Domain               |
|   - zephyr_domain.c / zephyr_dma_domain.c         |
|   - Dedicated real-time LL thread (zephyr_ll.c)   |
|   - Hard real-time audio components               |
+---------+----------------------------+------------+
          | LL Tick                    | LL Tick
          v                            v
+-----------------------+    +----------------------+
| Data Processing (DP)  |    | Thread With Budget   |
|  - zephyr_dp_schedule |    |  - zephyr_twb_sched  |
|  - Preemptible worker |    |  - Budgeted thread   |
|    threads            |    |  - Dynamic priority  |
|  - Zephyr EDF kernel  |    |    demotion/restore  |
|  - IPC command queue  |    |  - IDC/background    |
+-----------------------+    +----------------------+

  1. Low-Latency (LL) Scheduler: Hard real-time, deterministic task execution. Tasks run within a dedicated high-priority Zephyr thread pinned to each core (ll_thread0, etc.). Work items execute in strict priority order without sleeping or yielding. The LL scheduler supports two primary clock domains:

    • Timer Domain (SOF_SCHEDULE_LL_TIMER): Driven by periodic hardware timer interrupts (1000 µs default, 500 µs on AMD ACP platforms).

    • DMA Domain (SOF_SCHEDULE_LL_DMA): Driven directly by hardware DMA completion interrupts.

  2. Data Processing (DP) Scheduler (SOF_SCHEDULE_DP): Manages asynchronous, compute-heavy pipeline modules (e.g. ASRC, Smart Amp, ML keyword spotters). Each DP task is assigned its own preemptible Zephyr thread running at a lower priority than the LL domain. After every LL tick, the scheduler evaluates task buffer readiness across sinks and sources, calculates the task’s deadline timestamp, and configures the Zephyr kernel’s Earliest Deadline First (EDF) scheduler via k_thread_absolute_deadline_set().

  3. Thread With Budget (TWB) Scheduler (SOF_SCHEDULE_TWB): Provides CPU cycle limits for non-pipeline background tasks (such as Inter-Domain Communication or heavy diagnostics) to prevent systemic starvation. When a task consumes its allotted cycle budget during a tick, Zephyr time slicing triggers a callback that drops its priority to CONFIG_TWB_THREAD_LOW_PRIORITY. At the next LL tick, the cycle consumption is reset and standard priority is restored.

  4. Legacy Earliest Deadline First (EDF) Workqueue (SOF_SCHEDULE_EDF): Deprecated for audio pipelines. On Zephyr-based firmware, EDF is implemented as a single-thread delayed workqueue (edf_workq) dedicated exclusively to host IPC message dispatch. New audio pipelines must use the DP or LL schedulers.

Schedulers Comparison Matrix#

Scheduler

SOF Type Constant

Threading Model

Trigger / Clock Source

Status & Primary Use

LL-Timer

SOF_SCHEDULE_LL_TIMER

Single pinned Zephyr thread per core; runs tasks in priority sequence.

Hardware Timer (1000 µs / 500 µs tick).

Active: Real-time pipeline copiers and mixers.

LL-DMA

SOF_SCHEDULE_LL_DMA

Single pinned Zephyr thread per core triggered on DMA IRQ.

Hardware DMA completion interrupt.

Active: Low-latency DAI stream endpoints.

DP

SOF_SCHEDULE_DP

Dedicated preemptible Zephyr thread per SOF task.

LL post-run tick + Zephyr EDF deadlines.

Active: Compute-intensive algorithms (SRC, EQ, ML).

TWB

SOF_SCHEDULE_TWB

Dedicated preemptible Zephyr thread with cycle budget accounting.

System tick slice + LL tick replenishment.

Active: IDC tasks, background workers.

EDF (Legacy)

SOF_SCHEDULE_EDF

Shared Zephyr delayed workqueue (edf_workq).

Workqueue timeout delay.

Deprecated: Retained only for host IPC processing.

Task Lifecycle & State Machine#

All tasks scheduled within SOF transition through standardized lifecycle states:

          +-----------------------+
          |  SOF_TASK_STATE_INIT  | <--- schedule_task_init()
          +-----------+-----------+
                      | schedule_task()
                      v
          +-----------------------+
+-------> |  SOF_TASK_STATE_QUEUED| <---------------------------+
|         +-----------+-----------+                             |
|                     | Tick / Event trigger                    |
|                     v                                         |
|         +-----------------------+                             |
|         |  SOF_TASK_STATE_RUNNING                             |
|         +-----+-----------+-----+                             |
|               |           |                                   |
|   RESCHEDULE  |           | COMPLETED                         |
+---------------+           v                                   |
|                 +-------------------+                         |
|                 |    COMPLETED      |                         |
|                 +---------+---------+                         |
|                           |                                   |
|  schedule_task_cancel()   |                                   |
+--------------+            |                                   |
               |            |                                   |
               v            v                                   |
          +-----------------------+                             |
          |  SOF_TASK_STATE_CANCEL|                             |
          +-----------+-----------+                             |
                      | schedule_task_free()                    |
                      v                                         |
          +-----------------------+                             |
          |   SOF_TASK_STATE_FREE |                             |
          +-----------------------+                             |

  • SOF_TASK_STATE_INIT: Task descriptor allocated and bound to a scheduler.

  • SOF_TASK_STATE_QUEUED: Task enqueued in the scheduler run list awaiting trigger conditions.

  • SOF_TASK_STATE_RUNNING: Task currently executing its run() callback.

  • SOF_TASK_STATE_RESCHEDULE: Periodic task completed a processing chunk and requested rescheduling.

  • SOF_TASK_STATE_COMPLETED: One-shot task finished; removed from active scheduling until re-triggered.

  • SOF_TASK_STATE_CANCEL: Task was cancelled and will be safely dequeued before releasing memory.

  • SOF_TASK_STATE_FREE: Task resources and thread handles released.

C API Reference#

group Scheduling Infrastructure

Real-time task schedulers (Low-Latency Timer/DMA, Data Processing preemptible threads, Thread With Budget), scheduling domains, and task state machines.

Defines

IPC_PERIOD_USEC#

Scheduling period for host IPC worker task in microseconds.

edf_sch_set_pdata(task, data)#

Set private data pointer of an EDF task.

Deprecated:

See sof/schedule/edf_schedule.h.

Parameters:

  • task – [inout] Pointer to the target task structure.

  • data – [in] Pointer to private context data.

edf_sch_get_pdata(task)#

Retrieve private data pointer of an EDF task.

Deprecated:

See sof/schedule/edf_schedule.h.

Parameters:

  • task – [in] Pointer to the target task structure.

Returns:

Pointer to private context data.

ll_sch_set_pdata(task, data)#

Set the private data pointer of a Low-Latency task.

Parameters:

  • task – [inout] Pointer to the target task structure.

  • data – [in] Pointer to private context data (e.g. ll_task_pdata).

ll_sch_get_pdata(task)#

Retrieve the private data pointer of a Low-Latency task.

Parameters:

  • task – [in] Pointer to the target task structure.

Returns:

Pointer to private context data.

scheduler_init_ll#
schedule_task_init_ll#
LL_TIMER_PERIOD_US#

Default Low-Latency timer scheduling period in microseconds (1000us / 1ms).

LL_WATCHDOG_TIMEOUT_US#

Default Low-Latency watchdog timeout in microseconds.

Configured as two periods to provide a safe margin between watchdog start and initial task feeding.

ll_sch_domain_set_pdata(domain, data)#

Set the private data pointer of a Low-Latency scheduling domain.

Parameters:

  • domain – [inout] Target domain.

  • data – [in] Private context pointer.

ll_sch_domain_get_pdata(domain)#

Retrieve the private data pointer of a Low-Latency scheduling domain.

Parameters:

  • domain – [in] Target domain.

Returns:

Pointer to domain-specific context data.

timer_domain_init(timer, clk)#
SOF_SCHEDULER_FREE_IRQ_ONLY#

Scheduler free available flags.

Free function disables interrupts only, keeping data structures intact.

ZEPHYR_TWB_STACK_SIZE#

Default static stack size in bytes for each TWB worker thread.

ZEPHYR_TWB_BUDGET_MAX#

Maximum budget limit in system clock ticks per period.

SYS_TICKS_TO_HW_CYCLES(x)#

Convert Zephyr system clock ticks to DSP hardware clock cycles.

Parameters:

  • x – [in] System ticks.

HW_CYCLES_TO_SYS_TICKS(x)#

Convert DSP hardware clock cycles to Zephyr system clock ticks.

Parameters:

  • x – [in] Hardware cycles.

SOF_TASK_PRI_HIGH#

Predefined Low-Latency task priority levels.

Priority level 0 - high (hard real-time).

SOF_TASK_PRI_MED#

Priority level 4 - medium.

SOF_TASK_PRI_LOW#

Priority level 9 - low (background/idle).

SOF_TASK_DEADLINE_IDLE#

Predefined EDF task deadlines.

Idle deadline; run only when nothing else is ready.

SOF_TASK_DEADLINE_ALMOST_IDLE#

Almost idle deadline.

SOF_TASK_DEADLINE_NOW#

Immediate deadline; run as soon as possible.

SOF_TASK_SKIP_COUNT#

Task counter initial value.

Enums

Events signaled to Data Processing (DP) worker threads.

Values:

enumerator DP_TASK_EVENT_PROCESS#
enumerator DP_TASK_EVENT_CANCEL#
enumerator DP_TASK_EVENT_IPC#
enumerator DP_TASK_EVENT_IPC_DONE#

Values:

enumerator SOF_SCHEDULE_EDF#

Earliest Deadline First (EDF) scheduler.

Deprecated:

Deprecated for modern audio pipeline processing. In Zephyr-based builds, EDF is implemented as a delayed workqueue (edf_workq) retained for host IPC processing and legacy KPB draining tasks until migration. Audio pipeline components should use SOF_SCHEDULE_DP for preemptible deadline-driven tasks or SOF_SCHEDULE_LL_TIMER / SOF_SCHEDULE_LL_DMA for hard real-time tasks.

enumerator SOF_SCHEDULE_LL_TIMER#

Low Latency timer domain scheduler.

Executes tasks immediately upon expiration of the primary hardware timer tick.

enumerator SOF_SCHEDULE_LL_DMA#

Low Latency DMA interrupt domain scheduler.

Executes tasks immediately upon scheduling component’s DMA transfer completion interrupt.

enumerator SOF_SCHEDULE_DP#

Data Processing (DP) worker thread scheduler.

Preemptible Zephyr worker thread per SOF task. Evaluates task readiness after each Low-Latency (LL) tick, setting absolute deadlines in Zephyr EDF.

enumerator SOF_SCHEDULE_TWB#

Tasks With Budget (TWB) scheduler.

Preemptible Zephyr thread per SOF task with a pre-allocated cycle budget renewed every system tick. Drops thread priority on budget exhaustion to prevent system starvation.

enumerator SOF_SCHEDULE_COUNT#

Indicates total number of scheduler types.

enum task_state#

Lifecycle and execution states of an SOF task.

Values:

enumerator SOF_TASK_STATE_INIT#

Task allocated and initialized, not yet scheduled.

enumerator SOF_TASK_STATE_QUEUED#

Task queued in scheduler run list awaiting tick or trigger.

enumerator SOF_TASK_STATE_PENDING#

Task waiting for preconditions, audio data, or buffer space.

enumerator SOF_TASK_STATE_RUNNING#

Task actively executing in thread or timer/DMA handler.

enumerator SOF_TASK_STATE_PREEMPTED#

Task preempted by higher priority thread or ISR.

enumerator SOF_TASK_STATE_COMPLETED#

Task execution finished; removed from active scheduling.

enumerator SOF_TASK_STATE_FREE#

Task resources released.

enumerator SOF_TASK_STATE_CANCEL#

Task cancelled, pending removal from scheduler.

enumerator SOF_TASK_STATE_RESCHEDULE#

Return code from run callback requesting rescheduling in next period.

Functions

static inline uint64_t ipc_task_deadline(void *data)#

Retrieve IPC command processing deadline.

Parameters:

  • data – [in] Task structure context pointer.

Returns:

Task deadline timestamp (SOF_TASK_DEADLINE_NOW).

void ipc_schedule_process(struct ipc *ipc)#

Schedule processing of the next pending IPC command received from host.

Parameters:

  • ipc – [inout] Global IPC subsystem context pointer.

int scheduler_dp_init(void)#

Initialize the Data Processing (DP) scheduler on the calling core.

Allocates per-core DP scheduler state and initializes its driving LL tick source task.

Returns:

0 on success, negative error code (-ENOMEM) on failure.

int scheduler_dp_task_init(struct task **task, const struct sof_uuid_entry *uid, const struct task_ops *ops, struct processing_module *mod, uint16_t core, size_t stack_size, uint32_t options)#

Initialize a Data Processing task and attach a dedicated Zephyr worker thread.

Must be invoked on the same core that the task is configured to execute on.

Parameters:

  • task – [out] Pointer to store the allocated task structure.

  • uid – [in] UUID identifying the task/module.

  • ops – [in] Task operations callbacks (task_ops).

  • mod – [in] Processing module descriptor bound to this task.

  • core – [in] DSP core affinity for the task thread.

  • stack_size – [in] Stack byte size for the Zephyr worker thread.

  • options – [in] Task configuration flags.

Returns:

0 on success, negative error code on failure.

void scheduler_dp_internal_free(struct task *task)#

Free kernel-side internal resources associated with a DP task.

Parameters:

  • task – [inout] Task being freed.

void scheduler_dp_ll_tick(void)#

Tick notification from the Low-Latency (LL) timer domain to the DP scheduler.

Invoked on each core after all LL tasks complete. Evaluates readiness for all queued DP tasks, updates their absolute deadlines, and signals worker threads.

void scheduler_get_task_info_dp(struct scheduler_props *scheduler_props, uint32_t *data_off_size)#

Extract telemetry information about Data Processing scheduler tasks.

Populates scheduler_props with COMP_PROCESSING_DOMAIN_DP and active DP tasks.

Parameters:

  • scheduler_props – Structure to be filled with DP scheduler properties.

  • data_off_size – [inout] Pointer to the current size of scheduler_props buffer.

static inline int scheduler_dp_thread_ipc(struct processing_module *pmod, unsigned int cmd, union scheduler_dp_thread_ipc_param *param)#

Dispatch an IPC command synchronously to a Data Processing (DP) worker thread.

Posts DP_TASK_EVENT_IPC to the thread’s event queue and blocks waiting on completion (via dp_sync with a 100 ms timeout) before returning.

Parameters:

  • pmod – [inout] Pointer to the processing module descriptor.

  • cmd – [in] IPC command identifier to execute.

  • param – [inout] Parameters payload for the IPC command.

Returns:

0 on success, negative error code on failure.

int scheduler_init_edf(void)#

Initialize the Earliest Deadline First (EDF) workqueue scheduler.

Deprecated:

Deprecated for audio pipelines; retained for host IPC and legacy KPB draining.

Returns:

0 on success, negative error code on failure.

int schedule_task_init_edf(struct task *task, const struct sof_uuid_entry *uid, const struct task_ops *ops, void *data, uint16_t core, uint32_t flags)#

Initialize a task for Earliest Deadline First (EDF) workqueue execution.

Deprecated:

Deprecated for audio pipelines; use scheduler_dp_task_init() instead.

Parameters:

  • task – [out] Pointer to task structure to initialize.

  • uid – [in] UUID identifying the task.

  • ops – [in] Task operations callbacks (task_ops).

  • data – [in] Context pointer passed to task callbacks.

  • core – [in] Target DSP core ID.

  • flags – [in] Scheduling flags.

Returns:

0 on success, negative error code on failure.

int zephyr_ll_scheduler_init(struct ll_schedule_domain *domain)#

Initialize the Zephyr Low-Latency scheduler domain.

Parameters:

  • domain – [inout] Pointer to the Low-Latency schedule domain.

Returns:

0 on success, negative error code on failure.

int zephyr_ll_task_init(struct task *task, const struct sof_uuid_entry *uid, uint16_t type, int16_t priority, enum task_state (*run)(void *data), void *data, uint16_t core, uint32_t flags)#

Initialize a Zephyr Low-Latency task.

Parameters:

  • task – [out] Pointer to task structure.

  • uid – [in] UUID identifying the task.

  • type – [in] Task type identifier (SOF_SCHEDULE_LL_TIMER or SOF_SCHEDULE_LL_DMA).

  • priority – [in] Task priority (lower values indicate higher priority).

  • run – [in] Work callback function.

  • data – [in] Context pointer.

  • core – [in] Target DSP core ID.

  • flags – [in] Scheduling flags.

Returns:

0 on success, negative error code on failure.

void scheduler_get_task_info_ll(struct scheduler_props *scheduler_props, uint32_t *data_off_size)#

Extract telemetry information about Low-Latency scheduler tasks.

Populates scheduler_props with COMP_PROCESSING_DOMAIN_LL and active LL tasks.

Parameters:

  • scheduler_props – Structure to be filled with LL scheduler properties.

  • data_off_size – [inout] Pointer to the current size of scheduler_props buffer.

static inline struct ll_schedule_domain *timer_domain_get(void)#

Get the primary platform timer scheduling domain.

Returns:

Pointer to global timer scheduling domain.

static inline struct ll_schedule_domain *dma_domain_get(void)#

Get the primary platform DMA scheduling domain.

Returns:

Pointer to global DMA scheduling domain.

static inline struct ll_schedule_domain *domain_init(int type, int clk, bool synchronous, const struct ll_schedule_domain_ops *ops)#

Initialize a Low-Latency scheduling domain descriptor.

Allocates a ll_schedule_domain on the user or kernel heap, initializes synchronization locks, resets task and core counters, and computes tick conversion constants.

Parameters:

  • type – [in] Domain type (SOF_SCHEDULE_LL_TIMER or SOF_SCHEDULE_LL_DMA).

  • clk – [in] Source clock identifier.

  • synchronous – [in] True if domain tasks must run synchronously.

  • ops – [in] Domain operations table pointer.

Returns:

Pointer to initialized domain, or NULL on allocation failure.

static inline void domain_set(struct ll_schedule_domain *domain, uint64_t start)#

Configure the next interrupt or tick timestamp for the domain.

Parameters:

  • domain – [inout] Target scheduling domain.

  • start – [in] Next execution start timestamp in clock ticks.

static inline void domain_clear(struct ll_schedule_domain *domain)#

Clear/disarm the interrupt tick for the domain.

Parameters:

  • domain – [inout] Target scheduling domain.

static inline void domain_task_cancel(struct ll_schedule_domain *domain, struct task *task)#

Notify the domain that a task has been cancelled.

Parameters:

  • domain – [inout] Target scheduling domain.

  • task – [inout] Cancelled task pointer.

static inline int domain_register(struct ll_schedule_domain *domain, struct task *task, void (*handler)(void *arg), void *arg)#

Register a real-time task with the scheduling domain.

Parameters:

  • domain – [inout] Target scheduling domain.

  • task – [inout] Task to register.

  • handler – [in] Work handler callback function.

  • arg – [inout] Private context argument passed to handler.

Returns:

0 on success, negative error code on failure.

static inline void domain_unregister(struct ll_schedule_domain *domain, struct task *task, uint32_t num_tasks)#

Unregister a real-time task from the scheduling domain.

Parameters:

  • domain – [inout] Target scheduling domain.

  • task – [inout] Task to unregister.

  • num_tasks – [in] Current total registered task count.

static inline void domain_enable(struct ll_schedule_domain *domain, int core)#

Enable Low-Latency scheduling domain execution on the specified core.

Parameters:

  • domain – [inout] Target scheduling domain.

  • core – [in] Target core ID.

static inline void domain_disable(struct ll_schedule_domain *domain, int core)#

Disable Low-Latency scheduling domain execution on the specified core.

Parameters:

  • domain – [inout] Target scheduling domain.

  • core – [in] Target core ID.

static inline bool domain_is_pending(struct ll_schedule_domain *domain, struct task *task, struct comp_dev **comp)#

Query whether a task in the domain has pending execution work.

Parameters:

  • domain – [in] Target scheduling domain.

  • task – [in] Task to inspect.

  • comp – [out] Pointer to associated component device pointer, if any.

Returns:

true if work is pending, false otherwise.

struct ll_schedule_domain *zephyr_ll_domain(void)#

Retrieve the global Low-Latency timer scheduling domain descriptor on Zephyr.

Returns:

Pointer to active domain descriptor.

struct ll_schedule_domain *zephyr_domain_init(int clk)#

Initialize the primary timer-driven Low-Latency scheduling domain on Zephyr.

Parameters:

  • clk – [in] Clock source identifier.

Returns:

Pointer to initialized scheduling domain, or NULL on failure.

int zephyr_ll_task_sem_alloc(struct task *task)#

Allocate a completion semaphore for a Low-Latency task.

Parameters:

  • task – [inout] Target task.

Returns:

0 on success, negative error code on failure.

int zephyr_ll_task_sem_free(struct task *task)#

Free a completion semaphore for a Low-Latency task.

Parameters:

  • task – [inout] Target task.

Returns:

0 on success, negative error code on failure.

struct ll_schedule_domain *dma_multi_chan_domain_init(struct dma *dma_array, uint32_t num_dma, int clk, bool aggregated_irq)#

Initialize multi-channel DMA scheduling domain.

Parameters:

  • dma_array – [in] Array of DMA controllers.

  • num_dma – [in] Number of DMA controllers.

  • clk – [in] Clock source identifier.

  • aggregated_irq – [in] True if IRQs from channels are aggregated into a single line.

Returns:

Pointer to initialized scheduling domain.

struct ll_schedule_domain *dma_single_chan_domain_init(struct dma *dma_array, uint32_t num_dma, int clk)#

Initialize single-channel DMA scheduling domain.

Parameters:

  • dma_array – [in] Array of DMA controllers.

  • num_dma – [in] Number of DMA controllers.

  • clk – [in] Clock source identifier.

Returns:

Pointer to initialized scheduling domain.

struct schedulers **arch_schedulers_get(void)#

Retrieve the array of registered kernel-space schedulers for the current core.

Must only be called from privileged/kernel context (!k_is_user_context()).

Returns:

Pointer to the per-core schedulers list head pointer.

struct schedulers **arch_user_schedulers_get(void)#

Retrieve registered schedulers for user-space threads on the current core.

Invokes cpu_get_id(), so this function must only be called from kernel context. User-space callers should use arch_user_schedulers_get_for_core instead.

Returns:

Pointer to the per-core user schedulers list head pointer, or NULL if user LL is disabled.

struct schedulers **arch_user_schedulers_get_for_core(int core)#

Retrieve registered schedulers for user-space threads on a specific core.

Safe to invoke from user-space contexts because the target core ID is explicitly provided.

Parameters:

  • core – [in] Target DSP core ID.

Returns:

Pointer to the user schedulers list head pointer for the specified core, or NULL if disabled.

static inline void *scheduler_list_get_data(struct schedulers *schedulers, uint16_t type)#

Lookup scheduler private context data by scheduler type from a schedulers container.

Parameters:

  • schedulers – [in] Schedulers list container.

  • type – [in] Scheduler type identifier (SOF_SCHEDULE_*).

Returns:

Pointer to scheduler-specific private data, or NULL if not found.

static inline void *scheduler_get_data(uint16_t type)#

Retrieve private data of a registered kernel scheduler on the current core.

Parameters:

  • type – [in] Scheduler type (SOF_SCHEDULE_*).

Returns:

Pointer to scheduler private data, or NULL if not found.

static inline void *scheduler_get_user_data(uint16_t type)#

Retrieve private data of a registered user-space scheduler on the current core.

Parameters:

  • type – [in] Scheduler type (SOF_SCHEDULE_*).

Returns:

Pointer to scheduler private data, or NULL if not found.

static inline int schedule_task_running(struct task *task)#

Notify the scheduler that a task is transitioning to the running state.

Parameters:

  • task – [inout] Task being set to running.

Returns:

0 on success, or negative error code from scheduler ops.

static inline int schedule_task(struct task *task, uint64_t start, uint64_t period)#

Schedule a task for execution with start delay and period.

Parameters:

  • task – [inout] Task to schedule.

  • start – [in] Start delay in microseconds from now.

  • period – [in] Repetition period in microseconds (0 for one-shot execution).

Returns:

0 on success, -EINVAL if task is NULL, or negative error code from scheduler ops.

static inline int schedule_task_before(struct task *task, uint64_t start, uint64_t period, struct task *before)#

Schedule a task to execute before a specified reference task.

Note

Relative task ordering is optional and scheduler-specific. If the underlying scheduler does not implement schedule_task_before, this wrapper falls back to ordinary schedule_task() and ignores before.

Parameters:

  • task – [inout] Task to schedule.

  • start – [in] Start timing parameter (scheduler-specific).

  • period – [in] Repetition period in microseconds (scheduler-specific).

  • before – [in] Reference task before which this task must run.

Returns:

0 on success, -EINVAL if arguments are invalid, or negative error code from scheduler ops.

static inline int schedule_task_after(struct task *task, uint64_t start, uint64_t period, struct task *after)#

Schedule a task to execute after a specified reference task.

Note

Relative task ordering is optional and scheduler-specific. If the underlying scheduler does not implement schedule_task_after, this wrapper falls back to ordinary schedule_task() and ignores after.

Parameters:

  • task – [inout] Task to schedule.

  • start – [in] Start timing parameter (scheduler-specific).

  • period – [in] Repetition period in microseconds (scheduler-specific).

  • after – [in] Reference task after which this task must run.

Returns:

0 on success, -EINVAL if arguments are invalid, or negative error code from scheduler ops.

static inline int reschedule_task(struct task *task, uint64_t start)#

Reschedule an already scheduled task with an updated start time.

Parameters:

  • task – [inout] Task to reschedule.

  • start – [in] New start delay in microseconds.

Returns:

0 on success, or negative error code from scheduler ops.

static inline int schedule_task_cancel(struct task *task)#

Cancel a scheduled or queued task.

Parameters:

  • task – [inout] Task to cancel.

Returns:

0 on success, -EINVAL if task or bound scheduler is NULL, or negative error code from scheduler ops.

static inline int schedule_task_free(struct task *task)#

Free scheduler resources associated with a task.

Parameters:

  • task – [inout] Task whose resources should be freed.

Returns:

0 on success, -EINVAL if task or bound scheduler is NULL, or negative error code from scheduler ops.

static inline struct k_thread *scheduler_init_context(struct task *task)#

Initialize thread execution context for a task.

Parameters:

  • task – [inout] Task requiring execution context initialization.

Returns:

Pointer to allocated Zephyr thread, or NULL if unsupported or failed.

int schedule_task_init(struct task *task, const struct sof_uuid_entry *uid, uint16_t type, int16_t priority, enum task_state (*run)(void *data), void *data, uint16_t core, uint32_t flags)#

Initialize a scheduling task and bind it to the registered scheduler for its type and core.

Validates scheduler type and searches registered schedulers. User schedulers look up the target core via arch_user_schedulers_get_for_core(core), whereas kernel schedulers look up via arch_schedulers_get() on the calling core. Therefore, kernel task initialization must execute directly on the target core. Initializes task properties, priority, execution callback, and sets task state to SOF_TASK_STATE_INIT.

Parameters:

  • task – [out] Task structure to initialize.

  • uid – [in] Statically assigned task UUID entry.

  • type – [in] Scheduler type (SOF_SCHEDULE_*).

  • priority – [in] Task scheduling priority (lower values indicate higher priority).

  • run – [in] Execution callback function returning task_state.

  • data – [in] Private context pointer passed to run callback.

  • core – [in] DSP core ID on which the task should execute.

  • flags – [in] Task-specific scheduling flags.

Returns:

0 on success, -EINVAL if type >= SOF_SCHEDULE_COUNT, -ENODEV if scheduler cannot be found.

void scheduler_init(int type, const struct scheduler_ops *ops, void *data)#

Register a scheduler type instance with its operations table and private context data.

Allocates a schedule_data container on the system (or user) heap, links it into the active core scheduler list, and associates the provided operations.

Parameters:

  • type – [in] Scheduler type identifier (SOF_SCHEDULE_*).

  • ops – [in] Pointer to scheduler operations table (must provide schedule_task, schedule_task_cancel, schedule_task_free).

  • data – [in] Pointer to scheduler private instance data.

void scheduler_get_task_info(struct scheduler_props *scheduler_props, uint32_t *data_off_size, struct list_item *tasks)#

Extract scheduler task telemetry and properties for IPC4 base firmware.

Populates scheduler_props with the calling core ID and total task count, appending task_props structures for each active task in the list.

Parameters:

  • scheduler_props – Properties structure to be filled.

  • data_off_size – [inout] Pointer to running byte size of scheduler_props buffer.

  • tasks – [in] Linked list of tasks to inspect.

int scheduler_twb_init(void)#

Initialize the Thread With Budget (TWB) scheduler on the calling core.

Allocates per-core TWB scheduler state and binds its driving LL tick source task.

Returns:

0 on success, negative error code (-ENOMEM) on failure.

int scheduler_twb_task_init(struct task **task, const struct sof_uuid_entry *uid, const struct task_ops *ops, void *data, int32_t core, const char *name, size_t stack_size, int32_t thread_priority, uint32_t cycles_granted)#

Initialize a TWB task with a dedicated Zephyr worker thread and cycle budget.

Must be invoked on the same core that the task is configured to execute on.

Parameters:

  • task – [out] Pointer to store the allocated task structure.

  • uid – [in] UUID identifying the task.

  • ops – [in] Task operations callbacks (task_ops).

  • data – [in] Private context pointer passed to task callbacks.

  • core – [in] DSP core affinity for the worker thread.

  • name – [in] Debug name assigned to the Zephyr thread.

  • stack_size – [in] Stack byte size for the worker thread.

  • thread_priority – [in] Default preemptible thread priority (must be >= 0).

  • cycles_granted – [in] Budget in Zephyr system clock ticks per period (0 or >= ZEPHYR_TWB_BUDGET_MAX for unlimited).

Returns:

0 on success, negative error code (-EINVAL, -ENOMEM, -EFAULT) on failure.

static inline bool task_is_active(struct task *task)#

Check whether a task is active (queued, running, pending, or rescheduling).

Parameters:

  • task – [in] Task to check.

Returns:

true if task is in an active execution state, false otherwise.

static inline enum task_state task_run(struct task *task)#

Execute a task’s run callback.

Parameters:

  • task – [inout] Task to execute.

Returns:

Resulting task state returned by the run callback.

static inline void task_complete(struct task *task)#

Execute a task’s complete callback, if registered.

Parameters:

  • task – [inout] Task whose completion callback should be invoked.

static inline uint64_t task_get_deadline(struct task *task)#

Retrieve a task’s deadline timestamp.

Parameters:

  • task – [in] Task to query.

Returns:

Current deadline timestamp.

int task_main_start(struct sof *sof)#

Start the main SOF background task.

Parameters:

  • sof – [inout] Global SOF context pointer.

Returns:

0 on success, negative error code on failure.

int start_complete(void)#

Signal completion of system startup.

Returns:

0 on success, negative error code on failure.

Variables

struct tr_ctx ll_tr#
union scheduler_dp_thread_ipc_param#
#include <src/include/sof/schedule/dp_schedule.h>

Public Members

const struct bind_info *bind_data#
const struct module_ext_init_data *ext_data#
unsigned int trigger_cmd#
enum ipc4_pipeline_state state#
int n_sources#
struct sof_source **sources#
int n_sinks#
struct sof_sink **sinks#
struct scheduler_dp_thread_ipc_param pipeline_state#
uint32_t param_id#
enum module_cfg_fragment_position position#
uint32_t data_offset_size#
size_t fragment_size#
const char *data#
struct scheduler_dp_thread_ipc_param set_config#
char *data
struct scheduler_dp_thread_ipc_param get_config#
struct edf_task_pdata#
#include <src/include/sof/schedule/edf_schedule.h>

Legacy EDF task private data container.

Deprecated:

Deprecated along with SOF_SCHEDULE_EDF.

Public Members

void *ctx#

Task context pointer.

struct ll_task_pdata#
#include <src/include/sof/schedule/ll_schedule.h>

Low-Latency task private scheduling parameters.

Public Members

uint64_t period#

Execution period in microseconds.

uint16_t ratio#

Ratio of periods compared to the base registrable task.

uint16_t skip_cnt#

Counter tracking how many periods the task was skipped for rate alignment.

struct ll_schedule_domain_ops#
#include <src/include/sof/schedule/ll_schedule_domain.h>

Low-Latency schedule domain operations table.

Implements driver-level primitives for timer and DMA scheduling domains.

Public Members

int (*domain_register)(struct ll_schedule_domain *domain, struct task *task, void (*handler)(void *arg), void *arg)#

Register a real-time task with the domain.

Param domain:

[inout] Target scheduling domain.

Param task:

[inout] Task being registered.

Param handler:

[in] Domain tick handler callback.

Param arg:

[inout] Context argument passed to tick handler.

Return:

0 on success, negative error code on failure.

int (*domain_unregister)(struct ll_schedule_domain *domain, struct task *task, uint32_t num_tasks)#

Unregister a task from the domain.

Param domain:

[inout] Target scheduling domain.

Param task:

[inout] Task being unregistered.

Param num_tasks:

[in] Current total task count.

Return:

0 on success, negative error code on failure.

void (*domain_enable)(struct ll_schedule_domain *domain, int core)#

Enable domain interrupts/triggers on the specified core.

Param domain:

[inout] Target scheduling domain.

Param core:

[in] Core index to enable.

void (*domain_disable)(struct ll_schedule_domain *domain, int core)#

Disable domain interrupts/triggers on the specified core.

Param domain:

[inout] Target scheduling domain.

Param core:

[in] Core index to disable.

void (*domain_set)(struct ll_schedule_domain *domain, uint64_t start)#

Set the next tick timestamp for the domain.

Param domain:

[inout] Target scheduling domain.

Param start:

[in] Next execution start timestamp in clock ticks.

void (*domain_clear)(struct ll_schedule_domain *domain)#

Clear scheduled domain interrupt / tick timer.

Param domain:

[inout] Target scheduling domain.

bool (*domain_is_pending)(struct ll_schedule_domain *domain, struct task *task, struct comp_dev **comp)#

Query whether a task in the domain has pending execution work.

Param domain:

[in] Target scheduling domain.

Param task:

[in] Task to check.

Param comp:

[out] Pointer to associated component device, if any.

Return:

true if work is pending, false otherwise.

void (*domain_task_cancel)(struct ll_schedule_domain *domain, struct task *task)#

Notification hook invoked when a task within the domain is cancelled.

Param domain:

[inout] Target scheduling domain.

Param task:

[inout] Task being cancelled.

struct ll_schedule_domain#
#include <src/include/sof/schedule/ll_schedule_domain.h>

Low-Latency scheduling domain instance descriptor.

Public Members

uint64_t next_tick#

Ticks just set for next run.

uint64_t new_target_tick#

For the next set, used during the reschedule stage.

struct k_spinlock lock#

Standard spinlock.

atomic_t total_num_tasks#

Total number of registered tasks across all cores.

atomic_t enabled_cores#

Number of currently enabled cores.

uint32_t ticks_per_ms#

Number of clock ticks per millisecond.

int type#

Domain type (SOF_SCHEDULE_LL_TIMER or SOF_SCHEDULE_LL_DMA).

int clk#

Source clock identifier.

bool synchronous#

True if tasks in this domain execute synchronously.

bool full_sync#

True if tasks are fully synchronous with no time dependency.

void *priv_data#

Pointer to private domain driver data.

bool enabled[CONFIG_CORE_COUNT]#

Per-core enablement flags.

const struct ll_schedule_domain_ops *ops#

Domain operations table.

struct scheduler_ops#
#include <src/include/sof/schedule/schedule.h>

Scheduler operations interface table.

Schedulers implement this interface to plug into the unified SOF scheduling abstraction. Almost all schedule operations must return 0 for success and negative values for errors. Only the optional scheduler_free operation returns void.

Public Members

int (*schedule_task)(void *data, struct task *task, uint64_t start, uint64_t period)#

Schedule a task with the given timing parameters.

This operation is mandatory.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor to be scheduled.

Param start:

[in] Start timing parameter (scheduler-specific, e.g. start delay or absolute tick for LL).

Param period:

[in] Repetition period in microseconds for periodic schedulers (such as LL, where 0 denotes one-shot). Schedulers such as DP and TWB ignore this parameter as rescheduling is governed by the task’s returned execution state.

Return:

0 on success, negative error code on failure.

int (*schedule_task_before)(void *data, struct task *task, uint64_t start, uint64_t period, struct task *before)#

Schedule a task to execute before a specified reference task.

This operation is optional.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor to be scheduled.

Param start:

[in] Start timing parameter (scheduler-specific).

Param period:

[in] Repetition period in microseconds (scheduler-specific).

Param before:

[in] Reference task before which this task must be enqueued.

Return:

0 on success, negative error code on failure.

int (*schedule_task_after)(void *data, struct task *task, uint64_t start, uint64_t period, struct task *after)#

Schedule a task to execute after a specified reference task.

This operation is optional.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor to be scheduled.

Param start:

[in] Start timing parameter (scheduler-specific).

Param period:

[in] Repetition period in microseconds (scheduler-specific).

Param after:

[in] Reference task after which this task must be enqueued.

Return:

0 on success, negative error code on failure.

int (*schedule_task_running)(void *data, struct task *task)#

Transition a task to running state and perform scheduler-specific execution hooks.

This operation is optional.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task transitioning to running state.

Return:

0 on success, negative error code on failure.

int (*reschedule_task)(void *data, struct task *task, uint64_t start)#

Reschedule an already scheduled task with an updated start delay.

This operation is optional.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor to reschedule.

Param start:

[in] New start delay in microseconds.

Return:

0 on success, negative error code on failure.

int (*schedule_task_cancel)(void *data, struct task *task)#

Cancel a previously scheduled task.

This operation is mandatory.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor to cancel.

Return:

0 on success, negative error code on failure.

int (*schedule_task_free)(void *data, struct task *task)#

Free scheduler resources associated with a task.

This operation is mandatory.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task descriptor whose resources are to be freed.

Return:

0 on success, negative error code on failure.

struct k_thread *(*scheduler_init_context)(void *data, struct task *task)#

Initialize execution thread context for a scheduled task.

This operation is optional.

Param data:

[inout] Private state of the selected scheduler.

Param task:

[inout] Task requiring dedicated execution context.

Return:

Pointer to allocated Zephyr thread object, or NULL on error or unsupported.

struct schedule_data#
#include <src/include/sof/schedule/schedule.h>

Descriptor container representing a registered scheduler instance.

Public Members

struct list_item list#

List node linking this scheduler into the per-core schedulers list.

int type#

Scheduler type identifier (SOF_SCHEDULE_*).

const struct scheduler_ops *ops#

Pointer to scheduler operations table.

void *data#

Pointer to scheduler-specific private context data.

struct schedulers#
#include <src/include/sof/schedule/schedule.h>

Container holding the linked list of all registered schedulers on a core.

Public Members

struct list_item list#

Head of the linked list of registered schedulers.

struct task_ops#
#include <zephyr/include/rtos/task.h>

Operations and callbacks associated with a scheduling task.

Public Members

enum task_state (*run)(void *data)#

Task’s main execution callback function.

void (*complete)(void *data)#

Optional callback executed on task completion.

uint64_t (*get_deadline)(void *data)#

Optional callback returning current task deadline timestamp.

struct task#
#include <zephyr/include/rtos/task.h>

Core task structure managed by SOF schedulers.

Public Members

uint64_t start#

Scheduler/domain-specific start state (e.g.

absolute next-run tick timestamp in LL).

const struct sof_uuid_entry *uid#

UUID identifying the task or associated component.

uint16_t type#

Scheduler type identifier (SOF_SCHEDULE_*).

int16_t priority#

Priority of the task (lower values run first).

uint16_t core#

Execution core ID affinity.

uint16_t flags#

Custom task flags.

struct schedule_data *sch#

Pointer to scheduler instance bound to this task.

enum task_state state#

Current task lifecycle state.

void *data#

Custom context pointer passed to task operations.

struct list_item list#

List node linking task into scheduler run queue.

void *priv_data#

Scheduler-specific private task context.

struct task_ops ops#

Task operations callbacks table.

struct k_work_delayable z_delayed_work#

Zephyr delayable work item (used by legacy EDF).

uint32_t cycles_sum#

Cumulative execution cycles.

uint32_t cycles_max#

Maximum cycle count recorded in a single run.

uint32_t cycles_cnt#

Number of completed execution runs.

On this page