Pipeline Graph & Lifecycle API#

The Pipeline Graph API governs the topology, execution model, scheduling binding, and graph traversal of Sound Open Firmware (SOF) audio processing pipelines.

Architecture & Execution Model#

In SOF, an audio pipeline is a directed acyclic graph (DAG) of processing components connected via shared interconnect buffers:

+-------------------------------------------------------------------------+
|                             Pipeline Graph                              |
|                                                                         |
|   +-------------+       +---------------+       +------------------+    |
|   | Host Copier | ----> | Volume / Gain | ----> | Mixer / Endpoint |    |
|   | (Source)    |       | (Processing)  |       | (Sink)           |    |
|   +------+------+       +-------+-------+       +--------+---------+    |
|          |                      |                        |              |
|          v                      v                        v              |
|   +------+------+       +-------+-------+       +--------+---------+    |
|   | comp_buffer |       | comp_buffer   |       | Sched Component  |    |
|   +-------------+       +---------------+       +--------+---------+    |
+----------------------------------------------------------|--------------+
                                                           |
                                                 Pipeline Task Trigger
                                                           v
                                           +---------------+---------------+
                                           | Low-Latency (LL) Timer or     |
                                           | Data Processing (DP) Thread   |
                                           +-------------------------------+

Pipeline Lifecycle & State Management#

A pipeline encapsulates its own execution state, scheduling parameters, and task context:

  1. Pipeline Instantiation (`pipeline_create`): Allocates struct pipeline, initializes the component list, and configures the scheduling period (in microseconds), core binding, and priority.

  2. Scheduling Attachment (`pipeline_connect`): Binds the pipeline’s root or scheduling source component (sched_comp) to a real-time execution domain: - Low-Latency (LL) Domain: Pinned to high-priority timer or DMA ticks. - Data Processing (DP) Domain: Bound to a preemptible worker thread.

  3. Graph Traversal & Walking (`pipeline_walk_op`): Recursively propagates operations (prepare, params, trigger, reset) across connected components and downstream/upstream pipelines using depth-first traversal algorithms.

  4. Multi-Pipeline Interconnection: Pipelines connect to other pipelines across core boundaries or sample-rate boundaries using cross-pipeline interconnect buffers or lockless ring buffers.

C API Reference#

group Pipeline Graph & Lifecycle Infrastructure

Directed Acyclic Graph (DAG) pipeline creation, scheduling binding, traversal, and lifecycle management.

Pipeline connection directions

PPL_CONN_DIR_COMP_TO_BUFFER#

Connection from component to buffer.

PPL_CONN_DIR_BUFFER_TO_COMP#

Connection from buffer to component.

Pipeline processing directions

PPL_DIR_DOWNSTREAM#

Downstream playback/processing direction.

PPL_DIR_UPSTREAM#

Upstream capture/processing direction.

Defines

PPL_STATUS_PATH_STOP#

Pipeline status to stop execution of current path, but to keep the pipeline alive, when processing COMP_TRIGGER_STOP or COMP_TRIGGER_PAUSE.

PPL_STATUS_PATH_TERMINATE#

Pipeline status to stop execution of current path, and to terminate the pipeline, when processing COMP_TRIGGER_STOP or COMP_TRIGGER_PAUSE.

PPL_STATUS_SCHEDULED#

Pipeline scheduled in another thread other than IPC thread.

pipeline_task_get(t)#

Retrieves the enclosing pipeline_task structure from a task pointer.

Functions

struct pipeline *pipeline_new(struct k_heap *heap, uint32_t pipeline_id, uint32_t priority, uint32_t comp_id, struct create_pipeline_params *pparams)#

Creates a new pipeline.

Parameters:

  • heap – [inout] Heap to allocate the pipeline on, or NULL for default.

  • pipeline_id – [in] Pipeline ID number.

  • priority – [in] Pipeline scheduling priority.

  • comp_id – [in] Pipeline component ID number.

  • pparams – [in] Pipeline parameters from IPC payload, may be NULL.

Returns:

Pointer to new pipeline on success, or NULL on failure.

int pipeline_free(struct pipeline *p)#

Frees a pipeline and its associated resources.

Parameters:

  • p – [inout] Pipeline to free.

Returns:

0 on success, or negative error code on failure.

int pipeline_connect(struct comp_dev *comp, struct comp_buffer *buffer, int dir)#

Connect components in a pipeline.

Parameters:

  • comp – [inout] Connecting component device.

  • buffer – [inout] Connecting buffer.

  • dir – [in] Connection direction (PPL_CONN_DIR_*).

Returns:

0 on success, or negative error code on failure.

void pipeline_disconnect(struct comp_dev *comp, struct comp_buffer *buffer, int dir)#

Disconnect components and buffers in a pipeline.

Parameters:

  • comp – [inout] Connecting component device.

  • buffer – [inout] Connecting buffer.

  • dir – [in] Connection direction (PPL_CONN_DIR_*).

int pipeline_complete(struct pipeline *p, struct comp_dev *source, struct comp_dev *sink)#

Completes a pipeline setup by verifying connectivity between source and sink.

Parameters:

  • p – [inout] Pipeline to complete.

  • source – [inout] Pipeline source component device.

  • sink – [inout] Pipeline sink component device.

Returns:

0 on success, or negative error code on failure.

void pipeline_posn_init(struct sof *sof)#

Initializes pipeline position structure.

Parameters:

  • sof – [inout] Pointer to global SOF system context.

int pipeline_reset(struct pipeline *p, struct comp_dev *host_cd)#

Resets the pipeline and frees runtime resources.

Parameters:

  • p – [inout] Pipeline to reset.

  • host_cd – [inout] Host DMA component device.

Returns:

0 on success, or negative error code on failure.

void pipeline_set_eos(struct pipeline *p, bool eos)#

Sets End Of Stream state for all devices in the pipeline.

Parameters:

  • p – [inout] Target pipeline.

  • eos – [in] End Of Stream flag state.

int pipeline_for_each_comp(struct comp_dev *current, struct pipeline_walk_context *ctx, int dir)#

Walks the pipeline graph for each component.

Parameters:

  • current – [inout] Current pipeline component to start traversal from.

  • ctx – [inout] Pipeline graph walk context.

  • dir – [in] Walk direction (PPL_DIR_*).

Returns:

0 on success, or negative error code on failure.

struct comp_dev *pipeline_get_dai_comp(uint32_t pipeline_id, int dir)#

Walks pipeline graph to find DAI component.

Parameters:

  • pipeline_id – [in] Start pipeline ID.

  • dir – [in] Direction of traversal (PPL_DIR_*).

Returns:

Pointer to DAI component device, or NULL if not found.

struct comp_dev *pipeline_get_dai_comp_latency(uint32_t pipeline_id, uint32_t *latency)#

Walks pipeline graph to find DAI component and latency.

Parameters:

  • pipeline_id – [in] Start pipeline ID.

  • latency – [out] Receives latency to DAI as a count of buffered processing blocks (input_data/ibs - output_data/obs).

Returns:

Pointer to DAI component device, or NULL if not found.

static inline uint32_t pipeline_id(struct pipeline *p)#

Retrieves pipeline ID from pipeline structure.

Parameters:

  • p – [in] Target pipeline.

Returns:

Pipeline ID.

int pipeline_params(struct pipeline *p, struct comp_dev *cd, struct sof_ipc_pcm_params *params)#

Sets pipeline runtime audio stream parameters.

Parameters:

  • p – [inout] Pipeline to configure.

  • cd – [inout] Pipeline component device.

  • params – [in] Stream PCM parameters.

Returns:

0 on success, or negative error code on failure.

int pipeline_prepare(struct pipeline *p, struct comp_dev *cd)#

Prepares pipeline for audio processing.

Parameters:

  • p – [inout] Pipeline to prepare.

  • cd – [inout] Pipeline component device.

Returns:

0 on success, or negative error code on failure.

int pipeline_trigger(struct pipeline *p, struct comp_dev *host, int cmd)#

Trigger pipeline in IPC context.

Parameters:

  • p – [inout] Target pipeline.

  • host – [inout] Host DMA component device.

  • cmd – [in] Pipeline trigger command (COMP_TRIGGER_*).

Returns:

0 on success, or negative error code on failure.

int pipeline_trigger_run(struct pipeline *p, struct comp_dev *host, int cmd)#

Trigger pipeline in either IPC or pipeline task context.

Parameters:

  • p – [inout] Target pipeline.

  • host – [inout] Host DMA component device.

  • cmd – [in] Pipeline trigger command (COMP_TRIGGER_*).

Returns:

0 on success, or negative error code on failure.

int pipeline_copy(struct pipeline *p)#

Copy and process stream data along a pipeline.

Parameters:

  • p – [inout] Target pipeline.

Returns:

0 on success, or negative error code on failure.

void pipeline_get_timestamp(struct pipeline *p, struct comp_dev *host_dev, struct sof_ipc_stream_posn *posn)#

Get pipeline timestamps from host to DAI.

Parameters:

  • p – [in] Target pipeline.

  • host_dev – [in] Host DMA component device.

  • posn – [inout] Pipeline stream position structure to populate.

static inline bool pipeline_is_same_sched_comp(struct pipeline *current, struct pipeline *previous)#

Checks if two pipelines share the same scheduling component.

Parameters:

  • current – [in] First pipeline.

  • previous – [in] Second pipeline.

Returns:

True if both pipelines are scheduled together, false otherwise.

static inline bool pipeline_is_timer_driven(struct pipeline *p)#

Checks if pipeline is scheduled with timer.

Parameters:

  • p – [in] Target pipeline.

Returns:

True if pipeline uses timer-based scheduling, false otherwise.

static inline bool pipeline_is_this_cpu(struct pipeline *p)#

Checks if pipeline is scheduled on the current core.

Parameters:

  • p – [in] Target pipeline.

Returns:

True if pipeline core ID matches current core ID, false otherwise.

int pipeline_comp_ll_task_init(struct pipeline *p)#

Initializes a low-latency (LL) task for a pipeline.

Parameters:

  • p – [inout] Target pipeline.

Returns:

0 on success, or negative error code on failure.

void pipeline_comp_ll_task_free(struct pipeline *p)#

Frees the low-latency (LL) tasks owned by a pipeline.

Parameters:

  • p – [inout] Target pipeline.

int pipeline_comp_dp_task_init(struct comp_dev *comp)#

Initializes a data processing (DP) task for a component.

Parameters:

  • comp – [inout] Component device for which the task is created.

Returns:

0 on success, or negative error code on failure.

void pipeline_schedule_copy(struct pipeline *p, uint64_t start)#

Schedules a pipeline copy operation to run after a delay.

Parameters:

  • p – [inout] Target pipeline.

  • start – [in] Pipeline start time in microseconds.

void pipeline_comp_trigger_sched_comp(struct pipeline *p, struct comp_dev *comp, struct pipeline_walk_context *ctx)#

Triggers pipeline’s scheduling component.

Parameters:

  • p – [inout] Target pipeline.

  • comp – [inout] Pipeline component device.

  • ctx – [inout] Pipeline graph walk context.

void pipeline_schedule_triggered(struct pipeline_walk_context *ctx, int cmd)#

Schedules all triggered pipelines collected during traversal.

Parameters:

  • ctx – [inout] Pipeline graph walk context.

  • cmd – [in] Trigger command (COMP_TRIGGER_*).

void pipeline_schedule_config(struct pipeline *p, uint32_t sched_id, uint32_t core, uint32_t period, uint32_t period_mips, uint32_t frames_per_sched, uint32_t time_domain)#

Configures pipeline scheduling parameters.

Parameters:

  • p – [inout] Target pipeline.

  • sched_id – [in] Scheduling component ID.

  • core – [in] DSP core the pipeline runs on.

  • period – [in] Pipeline scheduling period in microseconds.

  • period_mips – [in] Pipeline worst-case MCPS per period.

  • frames_per_sched – [in] Pipeline frames processed per schedule.

  • time_domain – [in] Pipeline scheduling time domain.

int pipeline_xrun_recover(struct pipeline *p)#

Recovers the pipeline from an XRUN condition.

Parameters:

  • p – [inout] Target pipeline.

Returns:

0 on success, or negative error code on failure.

int pipeline_xrun_handle_trigger(struct pipeline *p, int cmd)#

Performs XRUN recovery trigger handling.

Parameters:

  • p – [inout] Target pipeline.

  • cmd – [in] Trigger command (COMP_TRIGGER_*).

Returns:

0 on success, or negative error code on failure.

void pipeline_xrun(struct pipeline *p, struct comp_dev *dev, int32_t bytes)#

Notifies host and pipeline that an XRUN condition occurred.

Parameters:

  • p – [inout] Target pipeline.

  • dev – [inout] Pipeline component device where XRUN occurred.

  • bytes – [in] Number of overrun or underrun bytes.

int pipeline_xrun_set_limit(struct pipeline *p, uint32_t xrun_limit_usecs)#

Sets tolerance limit for pipeline XRUN handling.

Parameters:

  • p – [inout] Target pipeline.

  • xrun_limit_usecs – [in] Limit in microseconds that pipeline will tolerate before reporting.

Returns:

0 on success, or negative error code on failure.

void pipeline_comp_copy_error_notify(const struct comp_dev *component, int error_code)#

Sends an IPC notification that an error occurred in a module’s processing function.

Parameters:

  • component – [in] Component device in which the error occurred.

  • error_code – [in] Error code to report.

struct pipeline#
#include <src/include/sof/audio/pipeline.h>

Audio pipeline structure representing a stream graph and execution context.

Public Members

struct mod_alloc_ctx *alloc#

Alloc context used for allocating this pipeline.

uint32_t comp_id#

Component ID for pipeline.

uint32_t pipeline_id#

Pipeline ID.

uint32_t sched_id#

Scheduling component ID.

uint32_t core#

Core we run on.

uint32_t period#

Execution period in microseconds.

uint32_t priority#

Priority level 0 (low) to 10 (max).

uint32_t period_mips#

Worst case instruction count per period.

uint32_t frames_per_sched#

Output frames of pipeline, 0 is variable.

uint32_t xrun_limit_usecs#

Report xruns greater than limit.

uint32_t time_domain#

Scheduling time domain.

uint32_t attributes#

Pipeline attributes from IPC extension message.

int32_t xrun_bytes#

Last xrun length in bytes.

uint32_t status#

Pipeline status flags.

struct tr_ctx tctx#

Trace settings.

struct task *trigger_task#

IPC4 pipeline trigger task.

struct task *pipe_task#

IPC3 pipeline processing task or IPC4 pipeline copy task.

struct pipeline *sched_next#

Pipeline scheduled after this.

struct pipeline *sched_prev#

Pipeline scheduled before this.

struct comp_dev *sched_comp#

Component that drives scheduling in this pipe.

struct comp_dev *source_comp#

Source component for this pipe.

struct comp_dev *sink_comp#

Sink component for this pipe.

struct list_item list#

List item in walk context.

uint32_t posn_offset#

Position update array offset.

struct ipc_msg *msg#

IPC message pointer for position updates.

int cmd#

Trigger command.

struct comp_dev *host#

Associated host component device.

unsigned int delay#

Period count delay.

bool aborted#

STOP or PAUSE failed, stay active.

bool pending#

Trigger scheduled but not executed yet.

struct pipeline trigger#

Pipeline trigger control structure.

struct pipeline_walk_context#
#include <src/include/sof/audio/pipeline.h>

Pipeline traversal walk context for graph exploration and operations.

Public Members

int (*comp_func)(struct comp_dev *cd, struct comp_buffer *buffer, struct pipeline_walk_context *ctx, int dir)#

Callback function invoked for each component in walk.

void *comp_data#

Component callback user data.

void (*buff_func)(struct comp_buffer *buffer, void *data)#

Callback function invoked for each buffer in walk.

void *buff_data#

Buffer callback user data.

struct comp_buffer *incoming#

Incoming buffer context.

struct list_item pipelines#

Pipelines to be scheduled after trigger walk.

bool skip_incomplete#

Skip incompletely initialized components.

struct pipeline_data#
#include <src/include/sof/audio/pipeline.h>

Generic pipeline data used by pipeline_comp_* functions.

Public Members

struct comp_dev *start#

Starting component device.

struct sof_ipc_pcm_params *params#

Stream PCM parameters.

struct sof_ipc_stream_posn *posn#

Stream position structure.

struct pipeline *p#

Target pipeline.

int cmd#

Command code.

uint32_t delay_ms#

Delay in milliseconds between pre and main trigger phases.

struct pipeline_task#
#include <src/include/sof/audio/pipeline.h>

Task type registered by pipelines.

Public Members

struct task task#

Parent task structure.

bool registrable#

Should task be registered on IRQ.

struct comp_dev *sched_comp#

Pipeline scheduling component.

struct create_pipeline_params#
#include <src/include/sof/audio/pipeline.h>

For storing IPC payload data during pipeline creation.

Public Members

const struct ipc4_pipeline_ext_obj_mem_data *mem_data#

IPC4 pipeline external memory descriptor.

On this page