diff --git a/api/audio_buffer.rst b/api/audio_buffer.rst new file mode 100644 index 0000000..702e98c --- /dev/null +++ b/api/audio_buffer.rst @@ -0,0 +1,60 @@ +.. _api_audio_buffer: + +Audio Buffer & Stream Management API +#################################### + +The Audio Buffer and Stream Management API governs intermediate audio data storage, +circular stream pointer tracking, inter-component buffer negotiation, and lockless +cross-core ring buffer streaming. + +Buffer Subsystem Architecture +***************************** + +SOF audio buffers decouple processing components, absorbing execution jitter and +rate differences: + +.. code-block:: text + + +-------------------+ +-------------------+ + | Upstream Copier | | Downstream Mixer | + | (Source Component)| | (Sink Component) | + +---------+---------+ +---------^---------+ + | | + | audio_stream_produce() audio_stream_consume()| + v | + +---------+---------------------------------------------------+---------+ + | struct comp_buffer | + | - id, size, free, avail, flags | + | - source -> upstream comp_dev sink -> downstream comp_dev | + | - stream (struct audio_stream) | + | * r_ptr, w_ptr (circular byte/frame pointers) | + | * addr, end_addr (underlying audio memory buffer) | + +-----------------------------------------------------------------------+ + +Buffer Types & Usage Profiles +***************************** + +1. **Interconnect Buffers (`struct comp_buffer`)**: + Allocated in internal SRAM via `buffer_alloc()` or `rballoc()`. Connects adjacent + components within a pipeline. Supports transaction callbacks (`BUFF_CB_TYPE_*`) + to notify consumers when fresh audio data is written. + +2. **Abstract Audio Buffers (`struct sof_audio_buffer`)**: + Unified buffer descriptor providing polymorphic operations (`struct audio_buffer_ops`) + across legacy component buffers (`BUFFER_TYPE_LEGACY_BUFFER`) and lockless + ring buffers (`BUFFER_TYPE_RING_BUFFER`). + +3. **Lockless Ring Buffers (`struct ring_buffer`)**: + Designed for cross-core audio streaming (such as Inter-Domain Communication between + Core 0 and secondary DSP cores). Lockless atomic read/write head updates eliminate + spinlock contention between cores. + +4. **Circular Audio Streams (`struct audio_stream`)**: + Format-aware circular buffer tracking sample rates, channels, and bit depths, + enabling sample-accurate and frame-accurate data production and consumption. + +C API Reference +*************** + +.. doxygengroup:: audio_buffer_api + :project: SOF Project diff --git a/api/audio_format.rst b/api/audio_format.rst new file mode 100644 index 0000000..e1d3fb4 --- /dev/null +++ b/api/audio_format.rst @@ -0,0 +1,37 @@ +.. _api_audio_format: + +Audio Formats & Channel Routing API +################################### + +The Audio Formats and Channel Routing API provides channel map parsing, multi-channel +spatial routing, and integer sample saturation arithmetic across SOF audio processing graphs. + +Channel Mapping Infrastructure +****************************** + +Multi-channel audio streams require precise channel assignments across ALSA PCM devices, +DSP processing algorithms, and hardware Digital Audio Interfaces (DAI). + +SOF utilizes channel mapping tokens (`struct sof_ipc_channel_map`) to configure: +- Channel slot numbering and spatial assignments (Front Left, Front Right, Center, LFE, Surround). +- Dynamic channel routing and demultiplexing. +- Helper functions: `chmap_get()` and `chmap_get_size()`. + +PCM Sample Saturation Arithmetic +******************************** + +DSP filter and gain stages can generate audio sample values that exceed the representable +dynamic range of target fixed-point bit depths. Rather than allowing integer overflow +wrap-around distortion (which creates severe acoustic clicks), SOF provides inline +hardware-optimized saturation primitives: + +- **`sat_int32(int64_t x)`**: Clamps 64-bit intermediate products to 32-bit signed range (`[INT32_MIN, INT32_MAX]`). +- **`sat_int24(int32_t x)`**: Clamps 32-bit values to 24-bit audio range (`[-8388608, 8388607]`). +- **`sat_int16(int32_t x)`**: Clamps 32-bit values to 16-bit audio range (`[-32768, 32767]`). +- **`sat_int8(int32_t x)`**: Clamps 32-bit values to 8-bit signed range (`[-128, 127]`). + +C API Reference +*************** + +.. doxygengroup:: audio_format_api + :project: SOF Project diff --git a/api/component_infra.rst b/api/component_infra.rst new file mode 100644 index 0000000..07cb6fc --- /dev/null +++ b/api/component_infra.rst @@ -0,0 +1,97 @@ +.. _api_component_infra: + +Audio Component Infrastructure API +################################## + +The Audio Component Infrastructure API provides the foundational driver model, +lifecycle state machine, copy execution interface, and Inter-Domain Communication (IDC) +binding protocol for all audio processing nodes within SOF. + +Component Architecture & Driver Model +************************************* + +Audio processing components implement the standardized operations vtable (`struct comp_ops`), +allowing the pipeline engine to manage disparate processing nodes (codecs, volume controls, +equalizers, mixers, and hardware DAIs) through a uniform interface: + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | struct comp_dev (Instance) | + | - id, type, state, core, is_shared, period, frames | + | - bsink_list, bsource_list (connected comp_buffer lists) | + | - drvdata (private component algorithm context) | + +------------------------------------+------------------------------------+ + | Points to + v + +-------------------------------------------------------------------------+ + | struct comp_driver (Driver) | + | - type, uid, tplg_type, ops | + +------------------------------------+------------------------------------+ + | Contains + v + +-------------------------------------------------------------------------+ + | struct comp_ops (VTable) | + | - new() / free() : Lifecycle allocation & cleanup | + | - params() / dai_hw_params() : Stream format negotiation | + | - prepare() / reset() : Buffer allocation & resource reset | + | - trigger() : START, STOP, PAUSE, RELEASE transitions | + | - copy() : Audio block processing algorithm loop | + | - bind() / unbind() : Multi-module IPC graph interconnection | + | - get_attribute() / set() : Runtime dynamic module parameters | + +-------------------------------------------------------------------------+ + +Component Lifecycle & State Machine +*********************************** + +Every component instance transitions through deterministic execution states in response +to pipeline trigger commands: + +.. code-block:: text + + +-----------------------+ + | COMP_STATE_INIT | <--- comp_new() + +-----------+-----------+ + | params() + v + +-----------------------+ + +--------> | COMP_STATE_READY | <---------------------------+ + | +-----------+-----------+ | + | | prepare() | + | v | + | +-----------------------+ | + | | COMP_STATE_PREPARE | | + | +-----------+-----------+ | + | | START / PRE_START | + | v | + | +-----------------------+ | + | | COMP_STATE_ACTIVE | <-------+ | + | +-----+-----------+-----+ | | + | | | | RELEASE | + | PAUSE | | STOP | | + | v v | | + | +------------------+ +-------------------+ | + | | COMP_STATE_PAUSED| | COMP_STATE_PREPARE| | + | +--------+---------+ +---------+---------+ | + | | | | + | +-----------------------+ | + | | RESET | + | v | + +------------------------+---------------------------------------+ + +Multi-Core IDC & IPC4 Module Binding +************************************ + +When components communicate across DSP core boundaries or connect dynamically in IPC4 +firmware, binding information is propagated via `struct bind_info` and Inter-Domain +Communication (IDC) messages: + +- **Local Core Binding**: Direct buffer attachment between source and sink components. +- **Remote Core Binding**: Uses `comp_ipc4_bind_remote()` to establish cross-core shared + buffers or lockless ring buffer streaming channels. + +C API Reference +*************** + +.. doxygengroup:: component_infra_api + :project: SOF Project diff --git a/api/components.rst b/api/components.rst index 0f092f9..46b1638 100644 --- a/api/components.rst +++ b/api/components.rst @@ -1,11 +1,156 @@ .. _api_components: +.. _api_modules: -Audio Processing Components API -############################### +Audio Processing Components & Modules API +######################################### -SOF includes a rich library of standard audio processing components, covering volume control, -gain attenuation, channel mixing, IIR/FIR equalization, dynamic range compression (DRC), -sample rate conversion (SRC/ASRC), sound dose measurement, and acoustic filters. +In Sound Open Firmware (SOF), all audio processing components—including volume controllers, +mixers, equalizers (EQ FIR/IIR), dynamic range compressors (DRC), sample rate converters +(SRC/ASRC), crossover filters, and smart amplifiers—are architected as **processing modules**. -.. doxygengroup:: audio_components_api +Modules can be built statically into the base firmware binary or compiled and loaded +dynamically at runtime as relocatable ELF extensions using the Zephyr Loadable Extension +(LLEXT) framework. + +Architecture & Module Adapter Layer +*********************************** + +The pipeline execution graph decouples pipeline orchestration from signal processing +algorithms through the **Module Adapter** layer: + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | Pipeline Graph | + | pipeline_create() / pipeline_connect() / walk_op | + +------------------------------------+------------------------------------+ + | comp_ops (params, prepare, copy) + v + +-------------------------------------------------------------------------+ + | Module Adapter Component | + | DECLARE_MODULE_ADAPTER(name) | + | - Adapts comp_ops into struct module_interface calls | + | - Binds comp_buffer streaming queues to sof_source and sof_sink APIs | + | - Handles parameter fragmentation (large configuration blobs) | + +------------------------------------+------------------------------------+ + | module_interface + v + +-------------------------------------------------------------------------+ + | Audio Processing Algorithm Module | + | (Volume, Mixer, EQ FIR/IIR, DRC, SRC, ASRC, Smart Amp, etc.) | + | - init() / prepare() / process() / apply_config() / free() | + | - Pulls audio from struct sof_source | + | - Pushes audio to struct sof_sink | + +------------------------------------+------------------------------------+ + | System Services + v + +-------------------------------------------------------------------------+ + | Host & RTOS System Services | + | (Dynamic Heap Memory, Timers, Tracing, UUID, Math) | + +-------------------------------------------------------------------------+ + +Processing Component Catalog +**************************** + +SOF provides an extensive suite of built-in processing modules optimized for low-latency +DSP execution: + +.. list-table:: + :widths: 20 22 28 30 + :header-rows: 1 + + * - Component + - Processing Mode + - Hardware Acceleration + - Primary Function + * - **Volume** + - Source/Sink (LL / DP) + - SIMD HiFi3 / HiFi4 / HiFi5 + - Smooth logarithmic/linear volume ramp, mute, gain attenuation, zero-crossing detection. + * - **Mixer / Mixout** + - Source/Sink (LL) + - Vectorized summation + - Multi-channel audio stream summation, channel splitting, and matrix routing. + * - **EQ (FIR & IIR)** + - Source/Sink (LL / DP) + - DF2T biquad SIMD + - Parametric equalization, shelving filters, high/low-pass filters, and speaker tuning. + * - **DRC & Multiband** + - Source/Sink (LL / DP) + - Vectorized RMS detector + - Dynamic range compression, peak limiting, soft/hard knee thresholds, and multiband crossover. + * - **SRC & ASRC** + - Source/Sink (LL / DP) + - Polyphase FIR filterbank + - Synchronous and asynchronous sample rate conversion with fractional drift compensation. + * - **Crossover** + - Source/Sink (LL / DP) + - 4th-order Linkwitz-Riley (LR4) + - Multi-way acoustic frequency splitting (woofer, midrange, tweeter). + * - **Smart Amp** + - Source/Sink (LL / DP) + - Thermal/Excursion observer + - Speaker transducer protection, coil temperature estimation, and IV-sense feedback. + * - **Sound Dose** + - Source/Sink (LL / DP) + - A-weighted filterbank + - Real-time acoustic energy integration complying with IEC 62368-1 and EN 50332 standards. + * - **KPB / MFCC** + - Source/Sink (LL / DP) + - FFT & Mel filterbank + - Keyword pre-roll circular buffering and Mel-frequency cepstral coefficient feature extraction. + +Module Lifecycle & Interface Contracts +************************************** + +All audio modules implement `struct module_interface`: + +1. **Initialization (`init`)**: + Invoked when the module adapter component is instantiated (`.new()`). Allocates private + algorithm state memory and registers default parameters. Typically marked `__cold`. + +2. **Stream Preparation (`prepare`)**: + Called when stream parameters are configured (`.prepare()`). Validates sample rates, + channel counts, and buffer formats across all attached sources and sinks. + +3. **Audio Block Processing (`process`)**: + The primary execution callback running in the real-time processing loop. Consumes audio + samples from source endpoint buffers and emits processed audio samples into sink + endpoint buffers. + +4. **Dynamic Configuration (`set_configuration` / `get_configuration`)**: + Transfers runtime parameter blobs (filter coefficients, DRC curves, tuning parameters) + from the host via IPC. Supports multi-fragment chunking for large configuration structures. + +5. **Reset & Teardown (`reset`, `free`)**: + Restores algorithm states to initial default settings and frees runtime buffers. + +Streaming Endpoints: Source & Sink APIs +*************************************** + +Modules consume audio data exclusively via `struct sof_source` and produce audio data +via `struct sof_sink`: + +- **Source API (`source_get_data()`, `source_release_data()`)**: + Allows the module to request a contiguous block of audio samples from the input stream. + The underlying source handles circular buffer rollover, cache invalidation, and pointer advance. + +- **Sink API (`sink_get_buffer()`, `sink_commit_buffer()`)**: + Provides a destination memory region for the module to store processed samples. + The sink commits the written bytes, flushes cache lines, and advances write pointers. + +Dynamic LLEXT Loading & Identification +************************************** + +Dynamic processing modules declare their ABI version, format compatibility tag, and unique +UUID using standard SOF registration macros: + +- `SOF_DEFINE_UUID()`: Associates a 128-bit RFC 4122 UUID with the module driver. +- `struct sof_module_api_build_info`: Encodes module build timestamp, git hash, and API version. +- `SOF_LLEXT_EXPORT_SYMBOL()`: Exposes module entry points for dynamic symbol resolution. + +C API Reference +*************** + +.. doxygengroup:: module_api :project: SOF Project diff --git a/api/index.rst b/api/index.rst index cd49b30..cfba567 100644 --- a/api/index.rst +++ b/api/index.rst @@ -27,14 +27,23 @@ Overview of Documented Modules The Doxygen documentation covers the entire public firmware and host-shared interface: -* **Audio Components & Pipelines**: - Core component driver lifecycle (``component.h``), component extensions and buffer helpers (``component_ext.h``), and PCM stream buffer utilities (``audio_stream.h``). +* **Audio Processing Components & Modules**: + Unified processing module interface (``module/interface.h``), lifecycle callbacks, streaming endpoints (``sink_api.h``, ``source_api.h``), dynamic LLEXT symbols, and built-in audio components (Volume, Mixer, EQ FIR/IIR, DRC, SRC, ASRC, Crossover, Smart Amp, Sound Dose). + +* **Audio Pipelines & Buffers**: + Audio pipeline DAG graphs (``pipeline.h``), component driver lifecycle and ops (``component.h``, ``component_ext.h``), interconnect and lockless ring buffers (``buffer.h``, ``audio_buffer.h``, ``ring_buffer.h``, ``audio_stream.h``), and channel mapping routines (``channel_map.h``). * **Hardware Drivers & Interfaces**: Direct Memory Access (``dma.h``), Digital Audio Interfaces for I2S/SSP, SoundWire/ALH, DMIC/PDM, and HDA (``dai.h``), Power Management runtime (``pm_runtime.h``), and platform hardware timers and interrupt controllers (``platform.h``). * **Core RTOS & System Services**: - Real-time task scheduling (EDF, LL-Timer, LL-DMA, Zephyr DataProcessing threads in ``schedule.h``), memory allocation heaps (``alloc.h``), and component/pipeline UUID declarations (``uuid.h``). + Spinlocks, mutexes, condition variables, clocks, and component/pipeline UUID declarations (``uuid.h``). + +* **Scheduling Infrastructure**: + Real-time task schedulers (Low-Latency Timer and DMA in ``ll_schedule.h`` and ``ll_schedule_domain.h``, Data Processing preemptible threads in ``dp_schedule.h``, Thread With Budget in ``twb_schedule.h``, and task state machines in ``schedule.h`` and ``rtos/task.h``). + +* **Memory Management Infrastructure**: + Multi-tier system heaps and flags (``rtos/alloc.h``), Virtual Memory Heap (``regions_mm.h``), virtual regions (``vregion.h``), cold DRAM staging (``fast-get.h``), and virtual page mapping (``vpage.h``). * **IPC & Host Interfaces**: User/Kernel IPC ABI protocols and messaging envelopes (``ipc/header.h``, ``ipc/control.h``), and SRAM Window 0 firmware status registers and telemetry offsets (``kernel/mailbox.h``). @@ -49,9 +58,10 @@ Subsystem C API References :maxdepth: 1 ipc4 - modules - pipeline components + pipeline + memory + scheduling rtos math diff --git a/api/memory.rst b/api/memory.rst new file mode 100644 index 0000000..04aecc5 --- /dev/null +++ b/api/memory.rst @@ -0,0 +1,108 @@ +.. _api_memory: + +Memory Management Infrastructure API +#################################### + +The Sound Open Firmware (SOF) memory architecture is organized into a multi-tier +subsystem engineered for low-latency DSP audio pipelines, fine-grained power management, +dynamic loadable module isolation, and flexible physical-to-virtual memory mapping. + +Memory Architecture Organization +******************************** + +SOF firmware executes across DSP architectures with heterogeneous memory pools +and dedicated cache hierarchies: + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | Audio Processing Modules (LLEXT) | + | mod_balloc_align() / mod_alloc_ext() / mod_alloc() | + +------------------------------------+------------------------------------+ + | + +------------------------------------v------------------------------------+ + | Context & Virtual Region Allocator (vregion) | + | struct mod_alloc_ctx { heap, vregion } | + | [ Lifetime Partition ] <---> [ Interim Partition ] | + +------------------------------------+------------------------------------+ + | + +------------------------------------v------------------------------------+ + | Core RTOS Memory Allocators | + | rmalloc_align() / rmalloc() / rzalloc() / rfree() | + | rballoc_align() / rballoc() | + +-----------------+------------------+------------------+-----------------+ + | | | + +-----------------v----+ +---------v----------+ +---v-----------------+ + | System & Shared Heap | | Virtual Heap (VMH) | | L3 IMR / DRAM Heap | + | - sof_heap (SRAM) | | - Dynamic TLB | | - External DRAM | + | - shared_buffer_heap| | - vpage_alloc() | | - Cached only | + | - Syscall k_heap | | - Power-of-2 bins | | - l3_heap_save() | + +----------------------+ +--------------------+ +---------------------+ + +Physical & Virtual Address Spaces +================================= + +1. **High-Speed Internal SRAM (L2 SRAM)**: + Low-latency on-chip memory where time-critical Low Latency (LL) task code, + stack frames, ring buffers, and active processing states reside. + +2. **Cached vs. Uncached (Coherent) Memory Windows**: + On architectures like Xtensa and Intel cAVS/ACE, physical SRAM is mapped into + both cached and uncached address aliases. The allocator dynamically selects the + appropriate pointer representation based on ``SOF_MEM_FLAG_COHERENT``: + + * **Cached addresses**: Default for algorithm compute loops to maximize L1 cache throughput. + * **Uncached (coherent) addresses**: Required for DMA ring buffer descriptors, host mailboxes, + and multi-core shared IPC control blocks. + +3. **External DRAM / Isolated Memory Region (L3 / IMR)**: + High-capacity DRAM backing storage used on Intel ACE platforms (e.g. MTL, ARL, LNL, PTL) + for storing large coefficient blobs, deep buffers, and inactive LLEXT modules. + L3 allocations are strictly cached; requesting coherent L3 memory returns ``NULL``. + ``l3_heap_save()`` preserves L3 state and flushes cache lines across DSP power gating. + +4. **Shared User/Kernel Memory Heap**: + When ``CONFIG_SOF_USERSPACE_USE_SHARED_HEAP`` is active, a dedicated + ``shared_buffer_heap`` is mapped across user space and supervisor domains + for zero-copy buffer transfer between user modules and kernel drivers. + +Subsystem Hierarchy & Allocators +================================ + +* **Core Allocators (``rmalloc_align``, ``rmalloc``, ``rzalloc``, ``rfree``)**: + General-purpose RTOS allocators evaluating flags (``SOF_MEM_FLAG_*``) to select + between ``l3_heap``, ``shared_buffer_heap``, and ``sof_heap``, with automatic + VMH fallback on exhaustion. + +* **Audio Streaming Buffer Allocator (``rballoc_align``, ``rballoc``)**: + Specialized runtime buffer allocator for PCM streams. Unlike ``rmalloc_align()``, + ``rballoc_align()`` actively prioritizes the Virtual Memory Heap (VMH) when available + to preserve scarce internal SRAM. + +* **Context-Based Allocations (``struct mod_alloc_ctx``, ``sof_ctx_*``)**: + Pairs a Zephyr ``k_heap`` with an optional ``vregion``. Allocations are automatically + directed to the vregion interim partition when present, and fall back to ``sof_heap_alloc()``. + +* **Contiguous Virtual Regions (``vregion``)**: + Manages a pre-allocated contiguous address range partitioned into **Lifetime** + (non-freeable pipeline topology allocations) and **Interim** (dynamically freed + runtime parameter buffers and control payloads) segments. + +* **Virtual Page Allocator (``vpage``) & Multi-Bundle VMH**: + Provides dynamic TLB page-table mapping (``vpage_alloc`` / ``vpage_free``) and + power-of-2 block bundle management (``vmh_init_heap``, ``vmh_alloc``, ``vmh_free``). + +* **Cold DRAM Dynamic Staging (``fast_get`` / ``fast_put``)**: + Enables code or read-only constants stored in cold DRAM to be temporarily staged + into high-speed SRAM during processing execution, then released back. + +* **Cold Path Annotations & Safety Invariants**: + Functions annotated with ``__cold`` and data with ``__cold_rodata`` may be placed + in offload storage. The runtime invariant ``assert_can_be_cold()`` validates that + non-latency-critical code is never invoked from a real-time Low Latency (LL) thread. + +C API Reference +*************** + +.. doxygengroup:: memory_api + :project: SOF Project diff --git a/api/modules.rst b/api/modules.rst deleted file mode 100644 index 870af3c..0000000 --- a/api/modules.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _api_modules: - -Loadable Module & LLEXT API -########################### - -Sound Open Firmware supports dynamic, modular audio processing through both built-in -and dynamically loadable ELF extensions (LLEXT). The module API defines the common -interface contracts, initialization structures, parameter exchange mechanisms, -and source/sink endpoint buffers. - -.. doxygengroup:: module_api - :project: SOF Project diff --git a/api/pipeline.rst b/api/pipeline.rst index 046a6fb..e78d84e 100644 --- a/api/pipeline.rst +++ b/api/pipeline.rst @@ -1,12 +1,82 @@ .. _api_pipeline: -Audio Pipeline & Buffer API -########################### +Audio Pipeline Infrastructure API +################################# -Audio pipelines in SOF represent directed processing graphs linking audio stream sources, -processing components, interconnect buffers, and audio sinks. This API governs pipeline -scheduling domains, thread execution models, circular buffer management, and stream -state transitions. +Audio pipelines in Sound Open Firmware (SOF) represent directed processing graphs linking +audio stream sources, processing components, interconnect buffers, and audio sinks. +This infrastructure governs pipeline graph lifecycle, component driver execution, +circular buffer management, and format negotiation. -.. doxygengroup:: audio_pipeline_api - :project: SOF Project +Architecture & Subsystem Organization +************************************* + +The audio pipeline infrastructure is decomposed into four modular API subsystems: + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | Pipeline Graph & Lifecycle | + | pipeline_create() / pipeline_connect() / walk_op | + | [ Directed Acyclic Graph (DAG) ] <---> [ Scheduling Task ] | + +------------------------------------+------------------------------------+ + | Traverses & Drives + v + +-------------------------------------------------------------------------+ + | Audio Component Infrastructure | + | struct comp_dev / struct comp_ops / trigger | + | [ Component Driver Model ] <---> [ State Machine Transitions ] | + +-----------------+-----------------------------------+-------------------+ + | Produces | Consumes + v v + +-----------------+-----------------------------------+-------------------+ + | Audio Buffer & Stream Management | + | struct comp_buffer / struct sof_audio_buffer / ring_buffer | + | [ Circular Buffers ] <---> [ Lockless Cross-Core Streaming ] | + +------------------------------------+------------------------------------+ + | Formats & Maps + v + +-------------------------------------------------------------------------+ + | Audio Formats & Channel Routing | + | chmap_get() / sat_int32() / sat_int24() / sat_int16 | + | [ Channel Maps ] <---> [ Integer Saturation Math ] | + +-------------------------------------------------------------------------+ + +.. note:: + For real-time scheduling domains (Low-Latency Timer and DMA), Data Processing + preemptible worker threads, Thread With Budget, and task state machines, + see :ref:`api_scheduling`. + +Subsystem API Modules +********************* + +To optimize navigation and readability, the pipeline API documentation is partitioned into +focused sub-pages: + +.. toctree:: + :maxdepth: 1 + :caption: Pipeline API Subsystems + + pipeline_graph + component_infra + audio_buffer + audio_format + +Subsystem Summaries +******************* + +1. :ref:`api_pipeline_graph`: + Directed Acyclic Graph (DAG) construction, scheduling task binding (LL/DP), + depth-first pipeline hierarchy traversal, and graph-wide state transitions. + +2. :ref:`api_component_infra`: + Unified audio component driver model (`struct comp_ops`), lifecycle callbacks, + trigger commands (`enum comp_trigger_cmd`), state machines, and multi-core IDC bindings. + +3. :ref:`api_audio_buffer`: + Interconnect buffers (`struct comp_buffer`), abstract audio buffers (`struct sof_audio_buffer`), + circular stream endpoints, lockless ring buffers, and transaction callbacks. + +4. :ref:`api_audio_format`: + Channel mapping extraction, multi-channel spatial routing, and audio sample + saturation arithmetic preventing integer wrap-around clipping. diff --git a/api/pipeline_graph.rst b/api/pipeline_graph.rst new file mode 100644 index 0000000..ed53cb8 --- /dev/null +++ b/api/pipeline_graph.rst @@ -0,0 +1,67 @@ +.. _api_pipeline_graph: + +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: + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | 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 +*************** + +.. doxygengroup:: audio_pipeline_api + :project: SOF Project diff --git a/api/rtos.rst b/api/rtos.rst index 1b70173..f8de5d1 100644 --- a/api/rtos.rst +++ b/api/rtos.rst @@ -5,8 +5,15 @@ RTOS Abstraction Layer API The RTOS abstraction layer decouples Sound Open Firmware core logic from underlying real-time operating system primitives. It standardizes spinlocks, mutexes, task -scheduling, high-resolution clocks, hardware timers, memory allocation pools, -and cache coherency operations across supported DSP architectures. +scheduling, high-resolution clocks, hardware timers, and cache coherency operations +across supported DSP architectures. + +.. note:: + * For heap allocators, Virtual Memory Heap (VMH), pre-allocated virtual regions, + and streaming buffer allocation infrastructure, see :ref:`api_memory`. + * For real-time scheduling domains (Low-Latency Timer and DMA), Data Processing + preemptible threads, Thread With Budget, and task state machines, + see :ref:`api_scheduling`. .. doxygengroup:: rtos_api :project: SOF Project diff --git a/api/scheduling.rst b/api/scheduling.rst new file mode 100644 index 0000000..5f1d81b --- /dev/null +++ b/api/scheduling.rst @@ -0,0 +1,159 @@ +.. _api_scheduling: + +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: + +.. code-block:: text + + +--------------------+ +------------------------+ + | 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 +**************************** + +.. list-table:: + :widths: 16 18 20 22 24 + :header-rows: 1 + + * - 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: + +.. code-block:: text + + +-----------------------+ + | 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 +*************** + +.. doxygengroup:: scheduling_api + :project: SOF Project diff --git a/conf.py b/conf.py index 5022cfe..f3aac82 100755 --- a/conf.py +++ b/conf.py @@ -48,6 +48,9 @@ sphinx_tabs_disable_tab_closing = True sphinx_tabs_disable_css_loading = True +# Suppress duplicate declaration warnings from anonymous structs in Breathe +suppress_warnings = ['duplicate_declaration.c'] + try: import myst_parser extensions.append('myst_parser') @@ -249,8 +252,8 @@ def setup(app): class BreatheAnonymousUnionFilter(logging.Filter): def filter(self, record): msg = record.getMessage() - # Suppress breathe limitation parsing anonymous union in struct bind_info - if "bind_info" in msg or "Expected identifier in nested name" in msg: + # Suppress breathe limitation parsing anonymous union/struct members (e.g. bind_info, dp_schedule) + if "bind_info" in msg or "Expected identifier in nested name" in msg or "Duplicate C declaration" in msg: return False return True