Pipeline Architecture#

The Pipeline Engine is the core real-time audio scheduling and signal processing framework of Sound Open Firmware (SOF). It organizes audio processing components into connected execution graphs, coordinates data movement through circular ring buffers, enforces strict real-time deadlines, and provides an end-to-end operational state machine.

This guide provides a high-level conceptual overview of how pipelines, modules, scheduling domains, and buffer queues function inside the DSP firmware without focusing on low-level C code.

—

1. What is an SOF Pipeline?#

A Pipeline in SOF is a logical execution container that groups a collection of audio processing components and buffers into a single, cohesive scheduling entity.

Figure 6 Pipeline Containers, Inter-Pipeline Buffers, and Multi-Core Distribution#

Why Separate Pipelines?#

Rather than placing all audio processing modules into one monolithic loop, SOF partitions graphs into distinct pipelines for three primary reasons:

Scheduling Boundaries: Modules inside the same pipeline execute at the same scheduling period (e.g., 1ms low-latency intervals vs 10ms bulk processing).
Core Affinity: Different pipelines can be bound to separate DSP processor cores (e.g., Core 0 handles high-speed DMA transfers, while Core 1 handles intensive beamforming or AI inference).
Power and Lifecycle Partitioning: An input pipeline can remain active to capture microphone data while a playback pipeline is paused and powered down into a low-power sleep state.

—

2. Audio Modules & Pin Interfaces #

An Audio Module (or component) is the atomic building block of signal processing in SOF. Modules accept incoming audio frames on Sink Pins (inputs), process or transform the samples, and produce processed frames on Source Pins (outputs). For an in-depth architectural guide on module containers, Source/Sink APIs, and memory sandboxing, see Module Framework Architecture.

Figure 7 Anatomy of an SOF Audio Processing Module#

Module Topology Configurations #

Modules support different pin topologies depending on their functional role:

Single-Input Single-Output (SISO): Standard processing filters such as Volume, Equalizer (EQ), Sample Rate Converter (SRC), and Dynamic Range Compressor (DRC).
Multi-Input Single-Output (MISO): Components that combine multiple audio streams into one, such as the Audio Mixer or Mixin/Mixout blocks.
Single-Input Multi-Output (SIMO): Components that split or replicate audio streams, such as the Demux, Channel Splitter, or Audio Copier.
Endpoints: Components that bridge the DSP with external hardware: * Ingress Endpoints: Host DMA readers (from host PC memory) and DAI receivers (from digital microphones or line-in). * Egress Endpoints: Host DMA writers (to host PC memory for recording) and DAI transmitters (to speaker codecs or S/PDIF).

—

3. Scheduling Domains: Low-Latency (LL) vs Data Processing (DP)#

Audio signal processing has diverse timing requirements. Simple volume adjustment must happen with sub-millisecond determinism to prevent hardware dropouts, whereas complex algorithms like Acoustic Echo Cancellation (AEC) or neural speech enhancement require flexible execution windows.

To resolve these conflicting demands, SOF separates pipeline execution into multiple Scheduling Domains (see Scheduler Architecture for a comprehensive deep dive):

Characteristic	Low-Latency (LL) Domain	Data Processing (DP) Domain
Trigger Source	Hardware timer tick (e.g., 1ms) or DMA completion interrupt.	Asynchronous Zephyr RTOS thread notification when buffer data is available.
Execution Model	Single cooperative task iterates through all modules in the graph synchronously.	Independent preemptive or cooperative Zephyr RTOS thread with dedicated stack.
Deadline Requirement	Hard real-time deadline; must complete within the 1ms timeslice.	Soft real-time deadline; can buffer data across multiple milliseconds.
Typical Modules	Host DMA Copier, Volume, Mixer, Tone Generator, DAI Copier.	AEC, Beamforming (TDFB), Keyword Detect (WoV), TensorFlow Lite Micro (TFLM).

Execution Comparison #

Figure 8 LL Synchronous Periodic Walk vs DP Asynchronous Thread Processing#

—

4. Data Movement & Buffer Queues #

Audio samples move through the pipeline via continuous Circular Ring Buffers (see Audio Buffer Management for a comprehensive deep dive into lockless SPSC mechanics, sizing criteria, and DSP memory tiers). Rather than allocating dynamic memory packets on every audio tick, SOF pre-allocates cache-aligned circular memory pools during pipeline initialization.

The Producer-Consumer Model #

Every buffer connects an upstream Producer module to a downstream Consumer module:

Figure 9 Circular Buffer Producer-Consumer Queue Model#

Key Buffer Properties #

Occupancy Tracking: The buffer tracks the number of unconsumed bytes currently stored (available to read) and the remaining free space (available to write).
Wrap-Around Handling: When either the write or read pointer reaches the boundary of the allocated buffer, it wraps back to the starting memory address.
Cache Coherency & Memory Tiers: * For single-core pipelines, buffers reside in fast on-chip SRAM with zero-copy shared memory access. * For cross-core pipelines, cache lines are invalidated and written back to ensure memory consistency across DSP cores.

—

5. Pipeline Construction & Destruction Lifecycle #

Pipelines are created and destroyed dynamically by host drivers or instantiated statically during boot on hostless microcontrollers. The lifecycle consists of six distinct phases:

Figure 10 Pipeline Lifecycle: From Instantiation to Streaming and Destruction#

Instantiation: The pipeline manager creates the container, registers a mailbox offset for host status notifications, and configures scheduling attributes.
Component Creation: Individual audio processing modules are instantiated in DSP memory.
Graph Binding: Audio buffers are attached between output pins and input pins, forming the Directed Acyclic Graph (DAG).
Graph Validation: The pipeline engine traverses the entire graph (pipeline_complete) to verify that all connections are valid, there are no unlinked endpoints, and no routing cycles exist.
Parameter Propagation: Stream parameters (e.g., 48 kHz, 32-bit float, stereo) propagate across all modules. Buffers calculate required period sizes, and DSP filters allocate scratch memory.
Streaming: The host issues a start trigger. The pipeline scheduler attaches to hardware interrupts and audio streaming commences.
Teardown: When the audio stream terminates, the host driver stops the pipeline, cancels scheduled tasks, flushes lingering audio samples, frees circular buffers, and reclaims heap memory.

—

6. Pipeline & Module State Machine #

Every pipeline and component operates according to a well-defined State Machine. Operational triggers command state transitions, which propagate down the graph from source to sink:

Figure 11 SOF Pipeline State Transition Diagram#

State Descriptions #

INIT: The pipeline is newly allocated; modules and buffers are being instantiated and bound.
READY: The graph is completely constructed, validated, and initialized with stream parameters. It is idle and ready to stream.
PRE_ACTIVE: An intermediate transition state where hardware clocks, PLLs, and power rails stabilize prior to sample delivery.
ACTIVE: The pipeline is actively processing audio frames on every scheduling interval.
PAUSED: Audio processing is halted upon host request, but sample history, filter coefficients, and buffer allocations are preserved for instant resume.
SUSPEND: The DSP is entering a low-power system sleep state (S3 / S0ix / D3). Module states are preserved in retention memory or saved to host memory.
XRUN_PAUSED: An audio buffer underrun or overrun has occurred; processing is temporarily suspended to prevent noise bursts or system panics while recovery executes.

—

7. Error Handling & XRUN Self-Healing #

In real-time audio systems, timing jitter can cause XRUNs:

Underrun (Starvation): The consumer attempts to read audio data, but the buffer is empty because the producer has not produced samples in time.
Overrun (Overflow): The producer attempts to write audio data, but the buffer is full because the consumer has fallen behind.

Figure 12 Automated XRUN Detection and Self-Healing Recovery Workflow#

Automated Self-Healing #

Rather than allowing an underrun to crash the audio subsystem, SOF features an automated Self-Healing Recovery mechanism:

When a hardware DAI or DMA endpoint detects starvation, it immediately flags an XRUN.
The pipeline engine halts active processing, dropping components into XRUN_PAUSED to avoid rendering corrupted memory.
The scheduler checks the xrun_bytes flag. Unless explicitly disabled by firmware configuration, the pipeline: * Flushes stale samples from affected ring buffers. * Reinitializes read and write pointers to a safe initial offset. * Re-prepares the pipeline components. * Issues an internal START trigger to seamlessly resume streaming.

—

8. Upstream Code Reference & Next Steps #

For developers seeking low-level C implementation details, data structures, and function prototypes:

Upstream Pipeline Specification: Consult the comprehensive code-level design guide in the main SOF repository at thesofproject/sof: src/audio/pipeline/README.md.
Source Files: * pipeline-graph.c: Graph traversal, component binding, and route discovery. * pipeline-stream.c: State machine triggers (START, STOP, PAUSE, RESET). * pipeline-params.c: Parameter propagation, period configuration, and format negotiation. * pipeline-schedule.c: Task scheduling, low-latency execution loops, and timer binding. * pipeline-xrun.c: Overrun/underrun detection and self-healing recovery.