Developer Guides

Sound Open Firmware (SOF) provides comprehensive architectural specifications, developer runbooks, and implementation guides covering the entire audio stack: from low-level DSP firmware and Zephyr RTOS integration to mainline Linux kernel drivers, embedded microcontroller audio bridges, and automated verification suites.

The developer documentation is organized into six core technical pillars:

1. 1. Firmware Development (FW)

2. 2. Audio Algorithm Tuning, Calibration & Runtime Control (Tuning)

3. 3. Kernel & Host Driver Development (Kernel)

4. 4. Hardware & Platform Bringup (HW)

5. 5. Testing, Simulation & Toolchains (SDK & Test)

6. 6. DSP Telemetry, Logging & Diagnostics (Debug)

—

1. Firmware Development (FW)

Guides and specifications for developing, compiling, and debugging DSP firmware components, Zephyr RTOS integration, audio processing algorithms, dynamic modules, and firmware image signing.

Upstream Firmware Feature Specifications

The SOF firmware repository maintains detailed, up-to-date specifications for each audio processing module, pipeline feature, and subsystem directly alongside the source code in thesofproject/sof:

Core Infrastructure & Pipeline

• Pipeline Architecture (High-level architecture; also see upstream pipeline README)

• Module Framework Architecture (High-level architecture; also see upstream module README & module adapter README)

• Scheduler Architecture (High-level architecture; also see upstream scheduler README)

• Audio Buffer Management (High-level architecture; also see upstream buffer README)

• IPC Infrastructure (IPC3 & IPC4) (High-level architecture; also see upstream IPC README)

• Firmware Initialization & Boot Architecture (High-level architecture; also see upstream init README)

Audio Processing Modules & Algorithms

• Volume Control Module Architecture (High-level architecture; also see upstream volume README)

• Mixin / Mixout Audio Processing Architecture (High-level architecture; also see upstream mixin_mixout README & mixer README)

• Sample Rate Conversion Architecture (SRC & ASRC) (High-level architecture; also see upstream SRC README & ASRC README)

• Equalizer Architecture (EQ FIR & EQ IIR) (High-level architecture; also see upstream FIR README & IIR README)

• Dynamic Range Compression Architecture (DRC & Multi-Band DRC) (High-level architecture; also see upstream DRC README & Multiband DRC README)

• Crossover Filter Architecture (High-level architecture; also see upstream crossover README)

• DC Blocker Architecture (High-level architecture; also see upstream dcblock README)

• Time-Domain Fixed Beamformer (TDFB) Architecture (High-level architecture; also see upstream tdfb README & tuning guide Time Domain Fixed Beamformer (TDFB))

• Real-Time Noise Reduction (RTNR) Architecture (High-level architecture; also see upstream RTNR README)

• TensorFlow Lite Micro (TFLM) Architecture (High-level architecture; also see upstream TFLM README)

• Mel-Frequency Cepstral Coefficients (MFCC) Feature Extraction Architecture (High-level architecture; also see upstream MFCC README)

• Smart Amplifier Protection & Physics (High-level architecture; also see upstream Smart Amp README)

• Sound Dose Evaluator Architecture (High-level architecture; also see upstream Sound Dose README)

• Data Routing, Multiplexing & Selection Architecture: Copier, Multiplexer & Selector (High-level architecture; also see upstream Copier README, Mux README & Selector README)

• PCM Format Converter Architecture (High-level architecture; also see upstream PCM converter README)

• Key Phrase Buffer (KPB) & Wake-on-Voice (WoV) Architecture (High-level architecture; also see upstream KPB source)

• Tone Generator (Tone) Architecture & Signal Engine (High-level architecture; also see upstream Tone README)

• Up/Down Channel Mixer (Spatial Channel Converter) Architecture (High-level architecture; also see upstream Up/Down Mixer README)

• Aria (Automatic Regressive Input Amplifier) Architecture (High-level architecture; also see upstream Aria README & tuning guide Level Multiplier & Aria AGC Dynamic Range Control Tuning Guide)

• Level Multiplier Architecture (High-level architecture; also see upstream Level Multiplier README & tuning guide Level Multiplier & Aria AGC Dynamic Range Control Tuning Guide)

• Phase Vocoder Architecture (High-level architecture; also see upstream Phase Vocoder source tree)

• STFT Process Architecture (High-level architecture; also see upstream STFT Process README)

• Media Codecs: Audio Encoders & Decoders Architecture (High-level architecture; also see upstream Cadence Codec module adapter & Codec README)

Firmware Packaging, Dynamic Modules & Subsystems

Firmware image packaging, cryptographic signing, loadable modules, and standalone hostless embedded firmware:

• Rimage Firmware Packaging & Signing Architecture (Firmware binary packaging, Intel cAVS and ACE partition manifests, cryptographic signing with MeCSS / CSE, hardware authorization keys, and multi-module extended manifest structures)

• LLEXT Dynamic Loadable Modules Architecture (Zephyr Loadable Linkable Extensions (LLEXT) dynamic loading framework, ELF relocation mechanics, manifest export, and runtime on-demand module binding over IPC4)

• Hostless Embedded Firmware Architecture (Embedded standalone firmware architecture for microcontrollers without a host processor, autonomous pipeline creation, clock provider/consumer bridges, and interactive Zephyr shell diagnostics)

How-To Developer Guides & Module Integration

Step-by-step developer runbooks for authoring new audio components, porting third-party audio algorithms, configuring builds, declaring topology widgets, and verifying execution:

• How-To Guide: Creating and Integrating Audio Processing Modules (End-to-end walkthrough on authoring a new DSP audio processing module or integrating third-party algorithms: header structures, CMakeLists.txt, Kconfig, UUID registration, cold-code memory placement, SIMD vector data alignment, ALSA Topology 2.0 configuration, multi-toolchain compilation, device deployment, and simulation with Host Testbench and Cadence xt-run)

• How-To Guide: Customizing Multi-Slot WOV & ECNS Pipelines (Architectural walkthrough on customizing complex multi-pipeline Wake-on-Voice (WOV) and Echo Cancellation & Noise Suppression (ECNS) topologies from the wcl-uaol-wov branch: replacing keyword detectors and acoustic echo cancellers, managing SOF Notifier inter-module arbitration, tuning Data Processing (DP) scheduling periods, cross-core affinity, and ALSA Topology 2.0 graph routing)

—

2. Audio Algorithm Tuning, Calibration & Runtime Control (Tuning)

Comprehensive workflows, filter coefficient synthesis, offline tuning tools (GNU Octave, MATLAB, Python), ALSA byte control packaging, Topology 2 and UCM2 integration, and live parameter injection via sof-ctl, amixer, and the Linux kernel ALSA subsystem:

Core Runtime Tuning & Control Infrastructure

• Runtime Tuning, Control Blobs & Parameter Injection Architecture (Authoritative runtime parameter injection, ABI serialization, and sof-ctl guide)

Dynamics & Transducer Protection Tuning

• Dynamic Range Compression & Multiband DRC Tuning Guide (Single-band DRC and Multiband DRC compression curves, adaptive ballistics, and speaker protection)

• Level Multiplier & Aria AGC Dynamic Range Control Tuning Guide (Level Multiplier Q9.23 precision scaling, zero-overhead fast-path bypass, Aria AGC target pre-amplification boost, 1 ms lookahead circular buffering, and regressive anti-clipping protection)

• Smart Amplifier (DSM) & Transducer Protection Calibration Guide (Smart Amplifier Dynamic Speaker Management, I/V sense feedback calibration, Thiele-Small modeling, thermal and excursion protection)

• Sound Dose / Hearing Health Calibration & Acoustic Protection Guide (Sound Dose Evaluator, IEC 61672-1 Class 1 A-weighting, EN 50332 / IEC 62368-1 compliance, HATS acoustic sensitivity calibration, and closed-loop exposure regulation)

Acoustic, Transducer & Array Tuning

• Crossover Filter Design & Multi-Driver Speaker Tuning (Linkwitz-Riley LR4 2-way, 3-way, and 4-way crossover filter design, phase-alignment merge, and multi-driver speaker tuning)

• Digital Microphone (DMIC) Acoustic Calibration & Array Tuning Guide (Digital Microphone acoustic calibration, 5th-order CIC and FIR decimation design, dual-FIFO mode matching, and array sensitivity/phase alignment)

• Equalizers, IIR and FIR (Parametric FIR & IIR equalizers, MLS acoustical measurement, and speaker tuning)

• Time Domain Fixed Beamformer (TDFB) (Time-Domain Fixed Beamformer array geometry and spatial filter design)

• Sample Rate Conversion (Polyphase FIR filter design and multi-stage resampling)

• Multiplexer/Demultiplexer (Multi-channel routing matrix configuration)

Machine Learning & Speech Feature Extraction

• Mel-Frequency Cepstral Coefficients (MFCC) & Audio Feature Extraction Tuning Guide (Mel-Frequency Cepstral Coefficients (MFCC), triangular Mel filterbank design, Slaney normalization, Whisper-compatible Mel spectrogram scaling, Voice Activity Detection (VAD), and TensorFlow Lite Micro (TFLM) keyword spotting co-design)

—

3. Kernel & Host Driver Development (Kernel)

Guides for Linux ASoC kernel driver developers, machine drivers, DMI quirk authoring, topology configurations, and host testing utilities:

• SOF Linux Driver (Linux kernel ASoC driver architecture, multi-vendor DSP core abstraction, IPC3/IPC4 protocol layers, ACPI/PCI platform probing, DMI machine quirks, runtime PM, and stream DMA management)

• ALSA Topology 2.0 Architecture & Developer Guide (ALSA Topology 2.0 architecture, split functional model, pre-processor token parsing, widget and pipeline definition syntax, hardware DAI graph routing, and dynamic UCM2 integration)

• Legacy Topology 1.0 (M4-Based) (Legacy ALSA Topology 1.0 architecture, M4 macro expansion templates, pipeline graph generation, and backward-compatibility guidelines)

• ALSA Use Case Manager v2 (UCM2) Architecture & Runbook (ALSA Use Case Manager v2 (UCM2) architecture, card directory layouts, syntax versions 2–7, device definitions, jack detection, sequence verbs, volume mixer remapping, PipeWire/WirePlumber integration, and step-by-step authoring and debugging workflows)

• Automated Kernel Testing and Bisection with ktest (Automated Linux kernel testing and bisection framework with ktest, rapid git bisect workflows, automated kernel build/deploy, and headless serial console validation)

—

4. Hardware & Platform Bringup (HW)

Hardware integration, platform memory layouts, boot architectures, and bringup checklists across silicon vendors and embedded development boards:

• SOF User Guide on NXP i.MX8 platforms (NXP i.MX8 platform integration, ARM Cortex-M and Tensilica DSP memory mappings, EDMA channel routing, SAI audio serial interfaces, and Linux BSP bringup)

• Hostless Embedded Firmware Architecture (Embedded microcontroller platforms including Teensy 4.1, ESP32-P4, and ESP32-C6, GPIO pinout definitions, 1.8V to 3.3V level shifting, and autonomous audio bridging)

• Hardware Audio Loopback Verification (Hardware loopback test harnesses, I2S and PDM clock provider/consumer synchronization, and rate/format verification matrices)

—

5. Testing, Simulation & Toolchains (SDK & Test)

Unit testing with Zephyr Ztest and Twister runner, host audio pipeline simulation, automated hardware loopback verification, Zephyr CMake build flags, cycle-accurate simulation, and protocol fuzzing:

• Unit Testing with Zephyr Ztest & Twister (Unit testing architecture with Zephyr Ztest framework and Twister test runner, fixture lifecycle, mock dependencies, and automated CI test matrix execution)

• Hardware Audio Loopback Verification (Automated hardware audio verification, ESP32-P4 and Teensy 4.1 audio bridges, I2S and PDM clock mode switching, and capture matrix validation)

• Testbench Host Audio Pipeline Simulation (Host audio pipeline simulation tool, native x86-64 and ARM execution, topology verification, dynamic runtime control scripting, and acoustic output analysis)

• Zephyr CMake & Build Configuration (Zephyr CMake build system architecture, comprehensive 3-toolchain guide comparing Cadence Xtensa Tools, Zephyr SDK, and experimental LLVM/Clang with mandatory Integrated Assembler)

• Xtensa Simulator (xt-run) Architecture & Verification Guide (Cycle-accurate Cadence Xtensa simulator verification (xt-run), Million Cycles Per Second (MCPS) profiling, memory trace dumping, and ISS verification runbooks)

• Firmware Fuzzing Architecture & Protocol Security Guide (Firmware security fuzzing framework, LLVM LibFuzzer integration, IPC mailbox protocol testing, topology fuzzing, and AddressSanitizer/UBSan vulnerability detection)

—

6. DSP Telemetry, Logging & Diagnostics (Debug)

Comprehensive observability and diagnostic frameworks for hard real-time DSP firmware: real-time trace DMA streaming, compile-time string dictionary extraction (smex), offline and live log decoding (sof-logger), zero-IPC interactive Zephyr memory shells, post-mortem coredump crash analysis, live audio buffer probing, performance cycle budgeting, and firmware binary manifest validation.

Observability Portal & Framework Architecture

• DSP Telemetry, Logging & Diagnostics Portal (Primary observability overview, zero-overhead asynchronous tracing, multi-tier diagnostic framework breakdown, and symptom-based diagnostic decision tree)

Real-Time Tracing & Network Telemetry

• DSP Telemetry, Logging & Traces (Compile-time string dictionary extraction with smex and .ldc catalogs, lockless internal SRAM circular trace DMA buffers, Linux kernel debugfs interface, boot-time logging via snd-sof-probes, and live console decoding via sof-logger)

• Audio Data Probes & Network Telemetry (Dynamic ALSA widget buffer injection and extraction tap points across processing DAGs, ALSA Compress Offload capture via crecord, stream demultiplexing with sof-probes -p, and high-throughput TCP network probe daemon on port 9999 streaming to dut-monitor)

Crash Diagnostics, Shell & Runtime Inspection

• DSP Crash Diagnostics & Zephyr Coredump (Native Zephyr RTOS coredump subsystem, Intel ADSP memory window backend, fatal CPU exception vector capture, register preservation, and interactive post-mortem GDB backtrace analysis with coredump_gdbserver.py)

• Zephyr Interactive Shell (Zero-IPC interactive Zephyr shell over shared DSP SRAM memory windows, host cavstool.py pseudo-terminal bridge, real-time thread state and stack high-water mark inspection, and low-power D0ix/D3 suspend/resume resilience)

Performance Profiling, Binary Manifests & Identifiers

• Performance Counters & MCPS Profiling (Hardware cycle counters via Tensilica CCOUNT registers, 64-bit platform timers, mathematical Million Cycles Per Second (MCPS) budget formulation, and component benchmarking)

• Firmware Binary Manifest & Security Inspection (sof-ri-info) (Signed firmware binary manifest formats across cAVS and ACE architectures, partition directories, CSE manifests, Intel digital signature certificates, and manifest inspection tooling)

• UUID Subsystem & Component Identification (Universal Unique Identifier subsystem, global registry in uuid-registry.txt, little-endian word swap wire format translation, ALSA Topology 2.0 token declarations, and IPC4 on-demand dynamic module loading)