pipeline: introduce declarative static topology definition and loader

[lgirdwood]

Summary

Add support for declarative static audio pipelines in Sound Open Firmware.
In microcontroller, hostless, and standalone embedded environments (such as ESP32-P4/S3/C6, PJRC Teensy 4.1, Nordic nRF54, RP2350, smart speakers, and audio bridges), there is no dynamic IPC host driver (Linux ALSA/SoundWire or Windows) to construct topologies at runtime.

Key Additions & Features

1. Declarative Topology Structures & Macros (<sof/audio/pipeline/static_pipeline.h>):

   • Full Doxygen API docblocks covering all structures, fields, enums, macros, and public APIs.
   • Comprehensive sample rate bitmasks (SOF_STATIC_RATE_*) aligned with SOF_RATE_* and format bitmasks (SOF_STATIC_FMT_*) aligned with enum sof_ipc_frame.
   • Concise constructor macros (SOF_STATIC_MODULE, SOF_STATIC_MODULE_RATE_CONV, SOF_STATIC_ENDPOINT_DAI, SOF_STATIC_ENDPOINT_USB) for clean declarative pipeline definition.

2. Ops-Driven Decoupled Architecture:

   • Generic headers and loader engine have zero per-module logic or dependencies.
   • Audio processing modules define and self-register their static operations (struct sof_static_module_ops) providing .create, .apply_volume, .apply_switch, and .apply_enum callbacks directly in their own source files (SRC, ASRC, Volume/Gain, Level Multiplier, Selector, EQ IIR, DRC, and TDFB) using DECLARE_STATIC_MODULE_OPS().

3. Generic Module Registry & Base IPC4 Config Synthesizer (static_pipeline_modules.c):

   • Generic ops registry with structured error logging on lookup failures.
   • Base IPC4 config synthesizer (sof_static_init_base_cfg) generating standard IPC4 base module configurations (struct ipc4_base_module_cfg) on behalf of the absent host, calculating IBS/OBS and channel mapping from declarative capabilities and periods.

4. Dynamic Format & Rate Negotiation:

   • Dynamically resolves primary stream sample rates from topology descriptors, removing hardcoded defaults.
   • Supports sample rate converters (SRC/ASRC), up/down mixers, and format conversions with per-buffer rate/channel inheritance.

5. Static Topology Loader Engine (static_pipeline_loader.c):

   • Instantiates native SOF pipelines, components, intermediate buffers, routes, and kcontrols directly at boot.
   • Component preparation and parameter negotiation to ensure all processing modules reach ready state prior to streaming.
   • Comprehensive inline comments on every code block explaining the action and rationale.

6. Dedicated Pipeline Control & Trigger Safety:

   • Separate start/stop routines (sof_static_pipeline_start, sof_static_pipeline_stop).
   • Strict abort on pipeline_prepare() failure preventing triggers on uninitialized circular buffers.
   • UAC2 terminal dispatch routing directly to modular start/stop helpers.
   • Decoupled custom kcontrol callback handler for board- and platform-specific controls.

7. Kconfig & Build Integration:

   • CONFIG_STATIC_PIPELINE Kconfig option and CMakeLists integration.

8. Developer Documentation:

   • Comprehensive architectural guide, API references, and step-by-step tutorial with multi-rate SRC examples in src/audio/pipeline/README.md.

[lgirdwood]

Lets split this patch into patch per feature. Need to LOG_ERR any errors and IPC3 support not needed

[Copilot]

🟡 Changes recommended

It contains compilation failures plus multiple unsafe initialization, triggering, control, and format-handling defects.

16 open findings

• ABI header size and payload bounds are not validated · New
• Application-tier loader performs privileged DAI configuration · New
• Selector callback accepts invalid channel indexes · New
• Unchecked volume channel count can overflow arrays · New
• Unchecked mute channel count can overflow arrays · New
• Runtime processing ignores updated enable switch · New
• EQ re-enable selects wrong routine for S24 and S32 · New
• S16-in-32-bit format incorrectly reports 32 valid bits · New
• U8 format incorrectly mapped as signed integer · New
• Unsupported channel counts produce inconsistent IPC4 maps · New
• UAC2 unity volume uses incorrect fixed-point representation · New
• Volume interpolation is non-monotonic at 6 dB boundaries · New
• UAC2 channel index ignored by volume setter · New
• UAC2 query ignores requested channel · New
• UAC2 GET_CUR returns linear gain instead of dB · New
• Volume example uses incorrect Q1.16 unity value · New

What changed in this PR

Introduces declarative, boot-time audio topology construction for hostless SOF platforms.

Changes:

• Adds static topology descriptors, module registry, loader, controls, and UAC2 integration.
• Registers static operations for supported processing modules.
• Adds configuration, build integration, and developer documentation.

File	Description
src/​include/​sof/​audio/​pipeline/​static_pipeline.h	Defines the public static topology API.
src/​include/​sof/​audio/​component.h	Declares component-driver lookup.
src/​audio/​component.c	Implements component-driver lookup.
src/​audio/​pipeline/​static_pipeline_loader.c	Builds, configures, controls, and triggers static graphs.
src/​audio/​pipeline/​static_pipeline_modules.c	Implements module registration and IPC4 config synthesis.
src/​audio/​pipeline/​static_pipeline_modules.h	Declares internal module helpers.
src/​audio/​pipeline/​static_pipeline_uac2.c	Bridges UAC2 controls and triggers.
src/​audio/​pipeline/​CMakeLists.txt	Adds static pipeline sources.
src/​audio/​pipeline/​README.md	Documents architecture and usage.
src/​audio/​Kconfig	Adds feature and capacity options.
src/​audio/​volume/​volume.c	Adds Volume and Gain operations.
src/​audio/​src/​src.c	Adds SRC creation support.
src/​audio/​asrc/​asrc.c	Adds ASRC creation support.
src/​audio/​selector/​selector.c	Adds Selector creation and controls.
src/​audio/​level_multiplier/​level_multiplier.c	Adds gain and switch controls.
src/​audio/​eq_iir/​eq_iir.c	Adds EQ bypass control.
src/​audio/​drc/​drc.c	Adds DRC enable control.
src/​audio/​tdfb/​tdfb.c	Adds beamforming switch control.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[intel-sofci]

PR 11266: test results

Run date: 2026-10-12 21:27 UTC

Tested commit: 2d670f719bf4c782f243e0cee03f6c2e470627c2

[Copilot]

🔵 Needs a closer look

Core endpoint configuration, trigger sequencing, format metadata, rate updates, and several module controls contain unresolved correctness issues.

22 open findings

• Playback ASRCs are created in the wrong mode · New
• Volume gain uses incompatible fixed-point representation · New
• DAI configuration reads an incompatible undersized payload · New
• Host endpoints use an incompatible module-adapter configuration · New
• Oversized topologies can truncate and overflow fixed arrays · New
• Duplicate pipeline start triggers can start DMA twice · New
• Selector initialization uses an unsupported IPC4 payload layout · New
• Loader globals lack userspace partition placement · New
• S16-in-32 format reports incorrect valid bit depth · New
• Zero-valued DMA domain incorrectly defaults to timer domain · New
• Descriptor core affinity is ignored · New
• S16 format is confused with the format inheritance sentinel · New
• Pipeline connection errors are ignored · New
• Missing pipeline endpoints are silently accepted · New
• Failed topology loads remain published with stale allocations · New
• Unsupported controls silently succeed without implementation · New
• Runtime rate setter updates bookkeeping without reconfiguration · New
• Channel fallback leaves buffer sizes based on the old count · New
• Control cache updates before operation success · New
• IPC4 Selector control updates an unused legacy field · New

And 2 more that still need to be addressed.

16 resolved since last review

• Unchecked mute channel count can overflow arrays
• Unchecked volume channel count can overflow arrays
• Selector callback accepts invalid channel indexes
• Application-tier loader performs privileged DAI configuration
• ABI header size and payload bounds are not validated
• UAC2 GET_CUR returns linear gain instead of dB
• UAC2 query ignores requested channel
• UAC2 channel index ignored by volume setter
• Volume interpolation is non-monotonic at 6 dB boundaries
• UAC2 unity volume uses incorrect fixed-point representation
• Unsupported channel counts produce inconsistent IPC4 maps
• U8 format incorrectly mapped as signed integer
• S16-in-32-bit format incorrectly reports 32 valid bits
• EQ re-enable selects wrong routine for S24 and S32
• Runtime processing ignores updated enable switch
• Volume example uses incorrect Q1.16 unity value

🧠 Review effort: Balanced