doc: comprehensive modernization of developer guides, toolchain architectures, and release catalog - #527
Merged
lgirdwood merged 64 commits intoSep 20, 2026
Conversation
Reorganize the Developer Guides portal into five modern technical pillars: 1. Firmware Development (FW) 2. Kernel & Host Driver Development (Kernel) 3. Hardware & Platform Bringup (HW) 4. Testing, Simulation & Toolchains (SDK & Test) 5. Telemetry, Probes & Diagnostics (Debug) Key updates include: - Add Linux driver architecture guide (sound/soc/sof/, IPC3/IPC4, SRAM mailboxes, runtime PM). - Add ASoC machine drivers, ACPI/NHLT/DISCO, and DMI quirk guide. - Add hostless embedded firmware guide (sof_static_pipeline, static topologies, Teensy 4.1, ESP32-P4/C6, Zephyr shell). - Add hardware audio loopback verification guide (test_p4_loopback.py, test_c6_loopback.py, test_teensy_loopback.py). - Modernize unit tests guide for Zephyr Ztest & Twister runner. - Modernize rimage documentation for the modern Rust tool and TOML configs. - Modernize DSP traces for Zephyr logging, smex, and TCP probe server. - Modernize CMake build guide for Zephyr RTOS and West. - Add legacy notice to Topology 1.0 pointing to Topology 2.0. - Remove obsolete guides (lmdk_user_guide, setup_up_2_board, compile_wsl, fuzzing_in_docker). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Create comprehensive, high-level documentation explaining the SOF pipeline architecture without delving into low-level C code: - Explain pipeline containers, boundaries, and multi-core affinity. - Detail audio modules, sink/source pins, and topology models. - Contrast Low-Latency (LL) periodic timer scheduling against Data Processing (DP) asynchronous Zephyr RTOS threads. - Detail data movement through circular ring buffers and producer/consumer pointer mechanics. - Document the end-to-end construction, parameter propagation, streaming, and destruction lifecycle. - Detail the runtime state machine (INIT, READY, PRE_ACTIVE, ACTIVE, PAUSED, SUSPEND, XRUN_PAUSED) and trigger flows. - Explain audio XRUN detection and self-healing recovery. - Include 7 vector Graphviz diagrams illustrating each subject. - Cross-reference upstream src/audio/pipeline/README.md for implementation details and C struct definitions. - Update architectures/index.rst and developer_guides/index.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Create comprehensive, high-level documentation explaining the SOF Audio Processing Module Framework and Module Adapter without delving into low-level C code: - Document the Three-Tier architecture: Pipeline Schedulers, Module Adapter system layer, and Standardized Module Interface. - Detail the Module Adapter proxy and sandboxing container. - Explain the decoupled Source and Sink APIs (Get -> Manipulate -> Commit/Release pattern). - Detail pin topologies (SISO, MISO, SIMO) and dynamic graph binding. - Document the module runtime state machine (MODULE_DISABLED, MODULE_INITIALIZED, MODULE_IDLE, MODULE_PROCESSING). - Detail runtime parameter management (initialization blobs, large coefficient blobs, scalar controls via IPC). - Explain memory sandboxing (dp_heap_user, objpool) and automated leak protection (mod_free_all). - Include 7 vector Graphviz diagrams illustrating each concept. - Cross-reference upstream src/module/README.md and src/audio/module_adapter/README.md. - Update developer_guides/index.rst and pipeline_architecture.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Create developer_guides/firmware/scheduler_architecture.rst providing a comprehensive, high-level overview of SOF's real-time scheduling infrastructure on top of the Zephyr RTOS: - Three-tier scheduling model: Low-Latency (LL), Data Processing (DP), and Thread With Budget (TWB) - Hardware interrupt sources (1ms/10ms timers, DMA buffer interrupts) - Thread-per-task architecture and dynamic Earliest Deadline First (EDF) - Cycle accounting, priority demotion, and LL tick replenishment in TWB - Multi-core scheduling topology, core affinity, and IDC messaging - Real-time task prioritization and deadline tie-breaking - Power management duty cycles, autonomous wait states, and tickless idle - 7 vector Graphviz diagrams illustrating all architectural concepts - Cross-references to upstream thesofproject/sof: src/schedule/README.md Update developer_guides/index.rst, pipeline_architecture.rst, and module_framework.rst with cross-references. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Create developer_guides/firmware/audio_buffer_management.rst providing a comprehensive, high-level overview of SOF's audio buffer subsystem: - Lockless Single-Producer Single-Consumer (SPSC) ring buffer mechanics - Modulo offset wrap-around arithmetic resolving empty vs full states - Buffer sizing criterion (2 * max(IBS, OBS)) and asynchronous decoupling - Multi-tier DSP memory hierarchy (L1 TCM, L2 HP-SRAM, LP-SRAM, Host DRAM) - Local mode vs cross-core shared mode with cache write-back/invalidation - Sample container formats (S16_LE, S24_4LE, S32_LE, FLOAT) and SIMD/DMA alignment - In-place zero-copy processing vs intermediate buffering - Buffer overrun/underrun (XRUN) detection and automated self-healing recovery - 7 vector Graphviz diagrams illustrating all architectural concepts - Cross-references to upstream thesofproject/sof: src/audio/buffers/README.md Update developer_guides/index.rst, pipeline_architecture.rst, module_framework.rst, and scheduler_architecture.rst with cross-references. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer guide covering the Sound Open Firmware (SOF) Inter-Processor Communication (IPC) infrastructure across IPC3 and IPC4 generations. The guide covers: - The dual planes of inter-processor communication (control vs telemetry). - Shared memory mailbox architecture (Windows 0 to 3) and doorbell handshake protocols. - Core framework and deferred Zephyr k_work queue thread handoff. - Protocol generational comparison (IPC3 flat scalar model vs IPC4 dynamic compound object model). - Dynamic pipeline lifecycle and pin binding in IPC4. - Firmware-initiated asynchronous notifications (stream positions, XRUNs, panic dumps). - Multi-core IPC routing and Inter-Domain Communication (IDC) with Core 0 as the host gateway. - Upstream code references and related architecture links. Includes 7 custom vector Graphviz SVG diagrams illustrating system architecture, mailbox handshakes, Zephyr queue handoffs, IPC3 vs IPC4 structure, pipeline binding sequences, async telemetry, and multi-core IDC topology. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide covering the Sound Open Firmware (SOF) initialization and boot subsystem. The guide covers: - End-to-end boot lifecycle across host staging, hardware boot ROM, Zephyr kernel initialization, SOF primary core bringup, and host ready synchronization. - Extended firmware manifest (.fw_metadata) structure and pre-boot host discovery. - Zephyr RTOS multi-stage kernel initialization levels (EARLY, PRE_KERNEL_1, PRE_KERNEL_2, POST_KERNEL, APPLICATION) and the rationale for SYS_INIT(sof_init, POST_KERNEL, 99). - Primary core platform bringup (primary_core_init) covering context allocation, DMA trace buffering, system notifiers, runtime PM, schedulers, DMACs, IPC, and AltBootManifest LP-SRAM unpacking. - Host-firmware boot synchronization and FW Ready handshake protocols (IPC3 vs IPC4) in Mailbox Window 0, along with boot timeout detection. - Multi-core secondary core boot flow, dynamic power state assessment (check_restore for cold boot vs D0ix retention wake), and IDC. - Power state lifecycles and wake transitions (D3 cold boot, D0 active, D0ix low-power retention, and S0ix/S3 suspend), including LLEXT dynamic library preservation. - Upstream code references and related architecture links. Includes 7 custom vector Graphviz SVG diagrams illustrating all boot phases, binary manifest structures, Zephyr hook levels, platform bringup, mailbox handshakes, secondary core activation, and power states. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide covering the Sound Open Firmware (SOF) Volume Control module (PGA widget). The guide covers: - System-level architecture & signal flow across asynchronous control plane (ALSA mixer, IPC3/IPC4) and hard real-time data plane. - Fixed-point gain scaling and saturation arithmetic across protocol generations (IPC3 Q8.16 vs IPC4 Q1.31) and audio formats. - Smooth volume ramping and zipper noise elimination comparing linear ramping with smooth Windows S-curve / Hann fades and adaptive update rate selection (125 µs to 1000 µs). - Zero-crossing muting and pop suppression mechanics using lookahead waveform analysis, plus stateful unmuting. - Zero-overhead unity gain passthrough mode decision flow for 0 dB unmodified playback. - Real-time in-line peak meter telemetry (COMP_PEAK_VOL) and shared Mailbox Window 0 synchronization for zero-IPC host VU meters. - SIMD vector processing parallelism comparing portable generic C with Tensilica Xtensa HiFi 3, HiFi 4 (4-way vector), and HiFi 5 (8-way vector). - Upstream code references and related architecture links. Includes 7 custom vector Graphviz SVG diagrams illustrating architecture, fixed-point math, ramping curves, zero-crossing muting, passthrough logic, peak telemetry, and SIMD vector bandwidth. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide covering the Sound Open Firmware (SOF) Mixin / Mixout audio processing subsystem. The guide covers: - Decoupled mixing paradigm comparing legacy monolithic mixers (rigid scheduling, single-core bottlenecks) with the asynchronous Mixin and Mixout decoupled architecture. - Multi-stream fan-out (up to 3 output sinks per Mixin for speakers, headphones, and AEC reference loopbacks) and fan-in (up to 8 input sources per Mixout). - Direct-to-sink zero-intermediate-buffer in-place accumulation mechanics, eliminating intermediate FIFO allocations and halving memory bus bandwidth. - Asynchronous scheduling coordination and pending frames tracking across independent pipeline rates, with autonomous silence generation on source stream starvation. - Per-sink gain scaling (10-bit fractional precision) and flexible channel remapping nibble masks. - SIMD vector accumulation and hardware saturation clamping comparing generic C with Tensilica Xtensa HiFi 3 and HiFi 5 (8-way vector). - Mixin telemetry, rate-limited underrun reporting to prevent IPC message flooding, and End-of-Stream (EOS) DAI latency flushing. - Upstream code references and related architecture links. Includes 7 custom vector Graphviz SVG diagrams illustrating architecture, routing topologies, in-place accumulation, pending frames state machine, per-sink engine, SIMD vector saturation, and telemetry workflows. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide for Sample Rate Conversion (SRC & ASRC) in Sound Open Firmware. Covers: - Architectural taxonomy: Synchronous SRC (locked rational ratios M/N) vs Asynchronous ASRC (independent crystals and continuous drift). - Synchronous polyphase FIR filter bank decomposition, subfilter phase commutator, and zero-elimination optimization. - Multi-stage conversion and latency optimization (factoring 44.1 kHz to 48 kHz into two stages with halfband filters to reduce latency by >75%). - Asynchronous Farrow filter structure with polynomial approximation and continuous fractional sample delay parameter mu. - Closed-loop drift estimation and buffer watermark tracking controller. - Push-mode (playback/transmit) vs pull-mode (capture/receive) execution topologies across audio endpoints. - SIMD vector acceleration across Cadence Xtensa HiFi 3, HiFi 4, HiFi 5, and generic scalar C implementations. - 7 native vector Graphviz SVG diagrams. - Cross-references in developer_guides/index.rst, pipeline_architecture.rst, and algorithms/src/sample_rate_conversion.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide for Equalizers (EQ FIR & EQ IIR) in Sound Open Firmware. Covers: - Filter taxonomy and architectural trade-offs: feedforward transversal FIR (linear phase, constant group delay, unconditional stability) vs recursive cascaded biquad IIR (ultra-low latency, minimum phase, analog filter emulation). - Finite Impulse Response (FIR) architecture: discrete-time convolution, circular delay line buffer management, and linear phase symmetric tap folding optimization (reducing multiplications by 50%). - Infinite Impulse Response (IIR) architecture: sensitivity of high-order monolithic polynomials, cascaded Second-Order Sections (SOS / biquads), and Direct Form I (DF1) with 64-bit accumulators preventing limit cycles and internal overflow on low-frequency poles. - Parametric equalizer topologies based on the Audio EQ Cookbook: peaking bells, shelving filters, high-pass/low-pass roll-offs, surgical notch filters, and flat passthrough sections. - Real-time dynamic parameter updates via IPC configuration blobs, fragment reassembly with comp_data_blob_handler, safety validation, and atomic pointer swapping for glitchless filter updates. - Multi-channel processing with per-channel independent response mapping (assign_response[]) and ALSA Topology 2 component integration. - SIMD vector acceleration across Cadence Tensilica Xtensa HiFi 3, HiFi 4, HiFi 5, and generic portable scalar C fallbacks. - 7 native vector Graphviz SVG diagrams. - Cross-references in developer_guides/index.rst, pipeline_architecture.rst, and algorithms/eq/equalizers_tuning.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…ture guide Add a comprehensive, high-level developer architecture guide for Dynamic Range Compression (DRC & Multi-Band DRC) in Sound Open Firmware. Covers: - Dynamic range compression principles and use cases: speaker excursion protection, dialogue intelligibility, and microphone capture dynamics. - Static transfer characteristic: threshold, quadratic soft knee, compression ratio, and makeup gain. - Single-band DRC processing architecture: signal path vs sidechain detector path, lookahead pre-delay circular buffers (up to 512 frames), and division-based sub-block processing (32 frames). - Envelope ballistics and adaptive multi-segment release curve: fast attack transient capture vs adaptive non-linear recovery (kA through kE) preventing harmonic distortion and audible pumping/breathing. - The spectral pumping hazard and the multi-band DRC paradigm: frequency partitioning to eliminate wideband ducking caused by heavy bass energy. - Multi-band compound 4-stage processing pipeline: Emphasis EQ (2-biquad IIR), Linkwitz-Riley 4th-order (LR4) crossover bank (flat 0 dB sum, zero phase error), parallel independent DRC band engines, and De-emphasis summation filter. - Dynamic parameter updates via IPC configuration blobs, multi-packet staging, and ALSA Topology 2 component widgets (drc.conf, multiband_drc.conf). - SIMD vector acceleration across Tensilica Xtensa HiFi 3, HiFi 4, HiFi 5, and generic portable scalar C fallbacks. - 7 native vector Graphviz SVG diagrams. - Cross-references in developer_guides/index.rst and pipeline_architecture.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…guide Add a comprehensive, high-level developer architecture guide for the Crossover Filter in Sound Open Firmware. Covers: - Electro-acoustic motivations: physical transducer frequency limits (subwoofers, woofers, midrange, tweeters) and active digital DSP crossovers vs passive analog crossovers. - Linkwitz-Riley 4th-order (LR4) filter theory: flaws of conventional Butterworth crossovers (+3 dB acoustic bump and 90 degree phase quadrature), cascaded Butterworth pairs (-6 dB at fc), flat 0 dB magnitude summation, and 360/0 degree in-phase acoustic alignment. - Crossover split topologies: 2-way splitting, 3-way splitting with the LR4 all-pass phase equalization trick (crossover_generic_lr4_merge), and 4-way symmetrical tree decomposition. - Direct Form I (DF1) cascaded biquad implementation mechanics with 64-bit accumulators and Q2.30 coefficient formatting. - 1-to-N multi-sink buffer distribution (bsinks[], assign_sinks[]), ALSA Topology 2 component integration (crossover.conf), and IPC4 dynamic pin indexing (init_config = 1). - System-level deployment: standalone multi-amplifier bi-amping/tri-amping vs embedded spectral splitting within Multi-Band DRC. - SIMD vector acceleration across Cadence Tensilica Xtensa HiFi 3, HiFi 4, HiFi 5, and generic portable scalar C fallbacks. - 7 native vector Graphviz SVG diagrams. - Cross-references in developer_guides/index.rst and pipeline_architecture.rst. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide for the DC Blocker subsystem (developer_guides/firmware/dcblock.rst). Topics covered: - Physical origins of DC bias (ADC preamplifier offset, PDM decimation leakage, thermal ground drift, synthetic non-linear algorithms) and system hazards (headroom penalty, asymmetric clipping, loudspeaker voice coil thermal destruction, cone excursion displacement, clicks/pops, and downstream DSP corruption in AEC, DRC, and VAD). - Digital filter theory and pole-zero mechanics of the first-order recursive high-pass DC blocker (H(z) = (1 - z^-1) / (1 - R z^-1)), exact 0 Hz transmission nulling, flat passband behavior, and cutoff frequency formulation. - Transient step response (y[n] = Delta_dc * R^n), exponential decay time constants (tau = 1 / (2*pi*fc)), settling times, and the engineering trade-off between sub-bass fidelity and transient recovery. - High-precision fixed-point arithmetic (Q2.30 coefficients, Q1.31 states, 64-bit Q3.61 intermediate accumulation), symmetric rounding, saturation clamping, and limit cycle oscillation elimination. - Multi-channel stream processing with independent per-channel state isolation, heterogeneous per-channel cutoff tuning, interleaved buffer traversal, and sample depth adaptability (S16, S24, S32). - Architecture-specific SIMD vector acceleration across Tensilica Xtensa HiFi 3, HiFi 4 (dual circular buffer registers for branchless processing), HiFi 5, and portable generic scalar C. - ALSA Topology 2 component configuration (dcblock.conf), Module Adapter lifecycle, LLEXT dynamic linking, IPC3/IPC4 control blobs, and pipeline deployment topologies in capture, playback, and post-effects. - GNU Octave / MATLAB tuning workflow and upstream code references. - Seven native vector Graphviz SVG architecture diagrams. - Clean Sphinx build with zero warnings under -W --keep-going and zero inclusive language violations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide for the Time-Domain Fixed Beamformer (TDFB) subsystem (developer_guides/firmware/tdfb.rst). Topics covered: - Spatial acoustics and microphone array principles: Far-field planar wavefront propagation, Time Difference of Arrival (TDOA), and advantages of Filter-and-Sum over Delay-and-Sum beamforming. - Filter-and-Sum FIR architecture and multi-channel mixing: Up to 16 FIR filter instances (<= 256 taps), input_channel_select, output_channel_mix, output_stream_mix, multi-beam simultaneous extraction (dual-beam stereo capture, speech + noise reference), and Q5.27 fixed-point headroom management. - Microphone array geometries: Uniform/non-uniform linear arrays (1D), circular ring arrays (2D 360-degree coverage), planar/rectangular arrays (azimuth + elevation 3D), and Q4.12 meter coordinates. - Direction of Arrival (DOA) tracking and acoustic localization: Pre-emphasis IIR filtering (500 Hz - 4 kHz speech band), ambient noise floor tracking with primitive VAD gate, pairwise cross-correlation lag extraction, 8-iteration geometric error minimization, and two-pole angle smoothing. - Host IPC control plane: ALSA mixer controls (process switch, direction tracking switch, steer azimuth enum, azimuth estimate enum), and asynchronous rate-limited host notifications (>= 200 ms). - SIMD vector acceleration across Tensilica Xtensa HiFi 3 (dual 32x16 MAC, circular buffer auto-wrapping), HiFi 2 EP, and portable scalar C. - System capture pipeline integration: Ingestion after DC Blocker, supplying high-SNR directional speech to AEC, RTNR, and VAD/TFLM. - Tuning workflows and upstream source code references. - Seven native vector Graphviz SVG architecture diagrams. - Clean Sphinx build under -W --keep-going and zero woke violations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add a comprehensive, high-level developer architecture guide for the TensorFlow Lite Micro (TFLM) embedded AI subsystem (developer_guides/firmware/tflm.rst). Topics covered: - Edge Audio AI Paradigm: Cloud offload vs. Host CPU processing vs. On-DSP microcontroller inference trade-offs (latency, privacy, power). - TensorFlow Lite Micro (TFLM) Component Architecture: Zero-heap static tensor arena (g_arena, kArenaSize), two-ended memory planning, zero-copy FlatBuffer model ingestion, and selective operator resolution via MicroMutableOpResolver<N>. - End-to-End Audio Machine Learning Pipeline: Raw PCM capture, framing, windowing, FFT, Mel-scale filterbank, and 2D spectrogram feature matrix. - Asymmetric Int8 Affine Quantization: Mathematical formulation (r = S * (q - Z)), fixed-point matrix multiplication kernel mechanics, effective scaling factor decomposition (M = M_0 * 2^-n), and 32-bit integer accumulation without floating-point emulation. - Continuous Sliding Window Inference: 49-frame buffer maintenance and 20 ms temporal stride advancement for continuous 50 Hz evaluation. - Hardware Neural Network Acceleration: Tensilica NNLib (xa_nnlib) SIMD vector routines (depthwise convolution, matrix-vector dot products, vector softmax) and circular buffer addressing. - Host IPC Control Plane & Dynamic LLEXT Packaging: ALSA Topology 2 widget declaration, runtime model updates via IPC3/IPC4 blobs, and LLEXT modular packaging. - Microphone Voice AI Pipeline Integration: Capture chain from DMIC/I2S through DC Blocker, TDFB, MFCC, TFLM, and Host Wake trigger. - Upstream source references and tuning guide links. - Seven native vector Graphviz SVG architecture diagrams. - Clean Sphinx build under -W --keep-going and zero woke violations. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add comprehensive high-level Mel-Frequency Cepstral Coefficients (MFCC) feature extraction architecture developer guide, covering: - Psychoacoustic auditory perception & homomorphic source-filter separation - 5-stage transformation pipeline (pre-emphasis, framing/windowing, 32-bit real-to-complex FFT, auditory Mel filterbanks, DCT-II & sinusoidal cepstral lifter) - Slaney area normalization & uniform Mel filterbank synthesis - OpenAI Whisper feature extraction integration (80 Mel channels, dynamic m_max leaky tracking, top_db clamping, host offload) - Integrated Mel-domain VAD & Discontinuous Transmission (DTX) state machine - Fixed-point scratch overlay memory architecture (dual complex FFT buffers) & decoupled staging buffer - Cadence Tensilica HiFi 3/4/5 SIMD vector acceleration primitives - ALSA Topology 2 configuration (Class.Widget.mfcc) & Compress/Legacy PCM streaming modes - End-to-end edge AI audio pipeline with 7 native vector Graphviz SVG diagrams Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Add comprehensive high-level Smart Amplifier Protection & Physics developer guide, covering: - Physical electro-acoustic foundations & speaker damage mechanisms (thermal burnout vs excursion bottoming) - Current & voltage (I/V) sense telemetry, back-EMF isolation & continuous voice coil temperature tracking - Two-layer architecture (generic component middleware vs solution-specific inner models: PASSTHRU_AMP, MAXIM_DSM) - Three-block structured memory hierarchy (MOD_MEMBLK_PRIVATE, MOD_MEMBLK_FRAME, MOD_MEMBLK_PARAM) & double-buffering - Dual-pipeline asynchronous scheduling (playback feed-forward vs capture I/V feedback stream synchronization) - Multi-band excursion limiting, slow broadband thermal limiting, dynamic bass extension & psychoacoustic harmonic synthesis - IPC3/IPC4 configuration blobs, volatile telemetry readback & factory assembly line calibration - ALSA Topology 2 declaration (Class.Widget.smart_amp) & end-to-end audio graph with 7 native vector Graphviz SVG diagrams Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Create a comprehensive developer guide for the Sound Dose Evaluator subsystem in Sound Open Firmware. Key topics covered: - Auditory health physiology, Temporary/Permanent Threshold Shift (TTS/PTS), and international regulatory frameworks (IEC 62368-1 Clause 10.6, WHO-ITU H.870, and Calculated Sound Dose / 3 dB exchange rule). - IEC 61672-1 Class 1 A-weighting acoustic transfer function and cascaded Direct Form I (DF1) biquad realization in SOF. - Fixed-point real-time energy accumulation in 64-bit precision. - 1-second interval periodic trigger and logarithmic mean dBFS conversion. - Momentary Exposure Level (MEL) calculation and acoustic sensitivity mapping. - Unsolicited IPC4 asynchronous event notifications to host exposure daemons. - Closed-loop dynamic protection via smooth exponential per-frame gain ramping. - ALSA Topology 2 widget configuration, byte controls, and end-to-end graph. - 7 native vector Graphviz SVG diagrams (Figures 167-173). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…itecture guide Add comprehensive high-level architecture documentation for Copier, Multiplexer/Demultiplexer, and Channel Selector components under developer_guides/firmware/copier_mux_selector.rst. Key topics covered: - Separation of concerns between boundary movers (Copier), multi-stream crossbars (Mux/Demux), and intra-stream mixers (Selector). - Copier subsystem deep dive: Host Copier, DAI Copier, IPC Gateway Copier, four binding topologies, and Fast Mode. - 4-way stream fan-out and dynamic per-sink format conversion pipeline. - Linear Link Position (LLP) telemetry and DSP wall-clock hardware timestamping synchronizer. - Integrated Copier Gain and static bit-shift attenuation. - Multiplexer & Demultiplexer binary bitmask routing matrices and pre-compiled lookup table optimizations. - IPC4 Echo Cancellation (AEC) reference stream aggregation with autonomous zero-padding fallback for missing reference streams. - Channel Selector intra-stream channel extraction and 8x8 Q10 matrix mixing (downmixing, upmixing, and channel swapping). - ALSA Topology 2 widget declarations (UUIDs, node types, and controls). - End-to-end system audio graph walkthrough integrating simultaneous media playback, speaker loopback, microphone capture, and AEC. - 7 native Graphviz vector diagrams (Figures 174 through 180). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…cture guide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) PCM Format Converter subsystem. Key architectural concepts and sections: - Supported formats matrix covering U8, G.711 A-law/mu-law, S16_LE, S24_3LE, S24_4LE, S24_4LE_MSB, S32_LE, and IEEE-754 single-precision float. - Container geometry vs valid bit depth resolution, sign-extension, and dual dispatch tables (pcm_func_map and pcm_func_vc_map). - Linear fragmentation engine (pcm_convert_as_linear) and circular buffer boundary resolution. - Tensilica HiFi3/HiFi4 vector SIMD acceleration using AE_LA16X4_IP, AE_CVT32X2F16, AE_SRAI32R, AE_SLAI32S, and AE_SA32X2_IP. - G.711 logarithmic companding curves (13-segment A-law, 15-segment mu-law), inversion masks, and bit packing. - Channel remapping and selective zero-fill muting architecture (0xF mute nibble and out-of-bounds protection). - Fixed-to-float normalization and float-to-fixed denormalization bridge. - Seven native vector Graphviz SVG diagrams (Figures 181 through 187). - Integrated into developer_guides/index.rst toctree and modules list. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…tnr) architecture guide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Real-Time Noise Reduction (RTNR) subsystem. Key architectural concepts and sections: - Principles of acoustic noise reduction: stationary background hum, non-stationary transient interference, diffuse ambient babble, and musical noise suppression trade-offs. - Mathematical foundations: Short-Time Spectral Analysis (STFT), recursive PSD estimation, minimum statistics noise floor tracking, decision-directed a priori/a posteriori SNR estimation, Wiener filtering, and spectral floor clamping. - Component architecture: audio_stream_rtnr circular buffer adapter, format dispatch table (S16_LE, S24_4LE, S32_LE), sub-block quantum processing (RTNR_BLK_LENGTH = 4), and internal FIFO queueing. - Dual sampling rate operation: 16 kHz voice communications/AI path (speech core formant optimization, low MIPS) vs 48 kHz high-fidelity full audio bandwidth media capture path. - Runtime configuration: dual IPC3/IPC4 parameter delivery, ALSA mixer switch control, preset blobs (ID 12345678) via comp_data_blob_handler, and zero-overhead bypass gate. - Open-source CI stub (rtnr_stub.c, cir_buf_copy passthrough) vs commercial production LLEXT dynamic module packaging. - End-to-end multi-stage capture audio pipeline: DMIC -> DC Blocker -> TDFB -> AEC -> RTNR -> Copier -> Host Recording & MFCC/TFLM AI. - Seven native vector Graphviz SVG diagrams (Figures 188 through 194). - Integrated into developer_guides/index.rst toctree and modules list. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Key Phrase Buffer (KPB) and Wake-on-Voice (WoV) subsystem. Key architectural concepts and sections: - Low-power wake-on-voice principles: Host CPU deep sleep (ACPI S0ix / Modern Standby / S3 / S4) vs DSP autonomous D0ix listening. - The Pre-Roll Dilemma: Acoustic keyword recognition latency and host resume latency, and how circular buffering prevents data loss of spoken activation commands. - KPB Component State Machine: Ten lifecycle states covering creation, buffering, keyword trigger, accelerated draining, host copy hand-off, and reset. - Circular History Ring Buffer: Linked-list buffer chaining, buffer sizing equations (sample width, channels, buffering duration), and backward read pointer calculation. - Dual-Sink Architecture: Real-time selector sink (Pin 0) for on-DSP keyword spotters (TFLM/MFCC) with integrated microphone channel selection (MicSelector bitmask) vs host capture sink (Pin 1). - Accelerated Burst Draining: Asynchronous draining task, synchronized pacing, dynamic interval adjustment (adjust_drain_interval) via DSP wall-clock cycles, and Fast Mode Task (FMT) execution. - Event Notification Framework: IPC3 Notifier callbacks vs IPC4 Asynchronous Message Service (AMS) and ALSA DAPM control sequencing. - End-to-End WoV Audio Pipeline: DMIC array, DC Blocker, KPB, Keyword Spotter, and Host DMA Copier with ALSA Topology 2 configuration. - Seven native vector Graphviz SVG diagrams (Figures 195 through 201). - Integrated into developer_guides/index.rst toctree and modules list. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…guide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Tone Generator (Tone) subsystem. Key architectural concepts and sections: - Signal synthesis & diagnostic roles: Hostless audio pipeline bringup, THD+N & linearity calibration, acoustic transducer profiling, AEC zero-reference fallback, and automated manufacturing line screening. - Mathematical foundations & fixed-point synthesis: Phase accumulator in Q4.28 format, Q16.16 frequency representation, Q1.31 pre-computed angular step coefficients, and 31-bit CORDIC sine calculation achieving >110 dB SFDR and <-105 dB THD without floating-point units. - Envelope & sweep modulation dynamics: 125-microsecond sub-block quantization, anti-click phase reset at zero amplitude, linear attack/sustain/decay ramping, and logarithmic frequency/amplitude sweeping with Q2.30 scale multipliers. - Tri-mode operational engine: TONE_MODE_TONEGEN (autonomous generator when nb_input_pins == 0), TONE_MODE_PASSTHROUGH (zero-overhead copy when bound as sink), and TONE_MODE_SILENCE (clean zero-fill AEC reference stream when uncoupled or in capture direction). - Multi-channel architecture: Independent struct tone_state instances per channel supporting stereo separation, phase-inversion testing, and selective channel muting. - Runtime control & parameter delivery: IPC3 enumerated controls (indices 0-7) vs IPC4 base module configuration and LLEXT dynamic module packaging (SOF_LLEXT_MODULE_MANIFEST). - Bringup & testbench runbook: Topology 1 M4 macro (W_TONE), ALSA control command sequences, and closed-loop host loopback verification via ESP32-P4 and Teensy 4.1 audio bridges. - Seven native vector Graphviz SVG diagrams (Figures 202 through 208). - Integrated into developer_guides/index.rst toctree and modules list. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…uide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Up/Down Channel Mixer (up_down_mixer) subsystem. Key topics covered: - Spatial acoustic conversion across Mono, Stereo, 2.1, 3.0, 3.1, Quatro (4.0 surround), 4.0 (L/C/R/Cs), 5.0, 5.1, and 7.1. - Architectural comparison with Mixin/Mixout, Selector, and Copier. - ITU-R BS.775 standard downmixing formulation and mathematical derivation of headroom-scaled anti-clipping coefficients (1/(1+sqrt(2)) ≈ 0.4142). - Half-scaled coefficients for 3.0/3.1 and Quatro-to-Mono fold-down. - 32-bit (Q1.31) and 16-bit (Q1.15) pre-computed fixed-point tables. - 32-bit channel_map format with 4-bit nibble encoding and dynamic slot resolution. - Mono/Stereo to 5.1 and 7.1 upmixing engines with side-channel fallback. - Tensilica HiFi3/HiFi4 SIMD vector acceleration: Vector coefficient packing via AE_SEL32_LL saving 3 registers to overcome the 8-register constraint, pipelined AE_L32_IP, AE_MULF32S_LH, AE_MULAF32S_LH, and 64-to-32-bit symmetric rounding. - IPC4 module interface (struct ipc4_up_down_mixer_module_cfg) with 4 coefficient selection modes. - Intel platform performance profiles (MTL, LNL, PTL). - ALSA Topology 2 widget definition and end-to-end 5.1 downmixing playback pipeline. - Automated audio quality verification runbook. - 7 native vector Graphviz SVG diagrams (Figures 209-215). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Aria (Automatic Regressive Input Amplifier) subsystem. Key topics covered: - Intelligent dynamic range pre-amplification and peak-limiting amplifier design. - Mathematical derivation of input headroom threshold (A_thresh = A_FS / 2^att) and regressive back-off factor (g = A_FS * 2^31 / (max_data * 2^att)) guaranteeing 0 dBFS peak clamping without clipping. - Target pre-amplification modes (0, +6, +12, +18 dB) across att parameter (0, 1, 2, 3). - 1 ms lookahead circular delay buffer and phased execution cycle maintaining invariant 1 ms latency across active and bypass modes. - 10-state sliding gain tracking table (sof_aria_index_tab), lookahead minimum-envelope follower, and continuous per-sample linear interpolation eliminating zipper noise. - Tensilica HiFi3/HiFi4 SIMD vectorization with single-cycle AE_MAXABS32S, odd/even channel specialization, and symmetric rounding (AE_ROUND24X2F48SSYM). - Tensilica HiFi5 hardware circular addressing registers (AE_SETCBEGIN0/1, AE_SETCEND0/1, AE_L32X2_XC, AE_S32X2_XC1) and 128-bit vector pipelines. - IPC4 module interface (struct ipc4_aria_module_cfg), runtime control (ARIA_SET_ATTENUATION), and Zephyr Loadable Linkable Extension (LLEXT) dynamic ELF packaging. - Platform performance profiles (aria.toml) and ALSA Topology 2 widget definition and pipeline graph. - Engineering verification and factory bringup runbook. - 7 native vector Graphviz SVG diagrams (Figures 216-222). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…e guide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Level Multiplier subsystem. Key topics covered: - Ultra-low-latency, zero-overhead digital linear gain and attenuation component architecture. - Q9.23 fixed-point number system (9 integer bits, 23 fractional bits) covering dynamic range from -138.47 dB to +48.17 dB with 1.19e-7 quantization resolution. - Dynamic range extremes, decibel-to-linear conversion formula, and unity gain definition (LEVEL_MULTIPLIER_GAIN_ONE = 0x00800000). - Universal PCM frame format support: 16-bit (SOF_IPC_FRAME_S16_LE), 24-bit (SOF_IPC_FRAME_S24_4LE), and 32-bit (SOF_IPC_FRAME_S32_LE) with unified 23-bit right-shift constant. - Ring buffer wrap segmentation algorithm for contiguous sample processing. - Zero-overhead fast-path bypass: direct memory block copy (source_to_sink_copy) at unity gain (0 dB), eliminating arithmetic multiplication loops and conserving active DSP cycles. - Tensilica HiFi3/HiFi4 SIMD vectorization with dual 64-bit vector registers, 16-bit parallel load/multiplication (AE_LA16X4_IP, AE_MULFP32X16X2RS_H/L), and symmetric rounding (AE_ROUND16X4F32SSYM). - Tensilica HiFi5 128-bit vector pipelines: octal 16-bit (AE_LA16X4X2_IP, AE_MULF2P32X16X4RS) and quad 32-bit (AE_LA32X2X2_IP, AE_MULF2P32X4RS) SIMD MAC acceleration. - IPC4 modular interface (level_multiplier_set_config), Zephyr Loadable Linkable Extension (LLEXT) dynamic packaging (level_multiplier.llext), and UUID registration. - Platform performance profiles (level_multiplier.toml), ALSA Topology 2 widget definition, and Octave/MATLAB blob generation script (sof_level_multiplier_blobs.m). - Factory bringup, precision linearity and gain accuracy test runbook. - 7 native vector Graphviz SVG diagrams (Figures 223-229). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…uide Author a comprehensive, modern architectural guide for the Sound Open Firmware (SOF) Phase Vocoder subsystem. Key topics covered: - Real-time frequency-domain Time-Scale Modification (TSM) architecture spanning 0.5x to 2.0x playback speed without pitch shifting. - Short-Time Fourier Transform (STFT) analysis & Overlap-Add (OLA) synthesis: rectangular, Blackman, Hamming, and Hann windows; Constant Overlap-Add (COLA) conditions; power-of-two frame sizing (256, 512, 1024) and hop geometry. - Exact reconstructive window gain compensation (g_comp = R_a / sum(w[n]^2)) in 32-bit Q1.31 format ensuring unity gain (0 dBFS) reconstruction. - Polar domain coordinate transformation (Q2.30 magnitude, Q5.27 phase angle), modulo-2pi phase unwrapping (unwrap_angle_q27), and continuous synthesis phase accumulation preventing comb filtering, tremolo, and phasiness. - Variable playback speed engine: 32-bit signed fixed-point Q3.29 format, ALSA discrete 16-step enum control grid (0.5x to 2.0x in 0.1x steps), and dual-domain linear interpolation across magnitude and phase deltas. - Exact Greatest-Common-Divisor (GCD) frame counter normalization (phase_vocoder_normalize_counters) preventing 32-bit counter overflow during indefinite streaming without timeline fraction drift. - Interactive transient-preserving phase re-anchoring state machine (phase_vocoder_reset_for_new_speed) avoiding cold-start reset, volume drop, and transient smearing during live tempo adjustments. - Multi-channel processing and Mono Downmix Optimization (mono_mix_coef = 2^31 / stream_channels) slashing DSP cycles and memory footprint by up to 75%. - Universal PCM frame format support (S16_LE, S24_4LE, S32_LE) and zero-overhead bypass fast-path (source_to_sink_copy). - IPC4 runtime configuration handler, Zephyr LLEXT dynamic module packaging (phase_vocoder.llext), component UUID registration, and ALSA Topology 2 graph. - Factory bringup runbook, GNU Octave offline blob generation (setup_phase_vocoder.m), testbench automated verification scripts (phase_vocoder_s16.sh, phase_vocoder_s32.sh), and acoustic pitch invariance validation. - 7 native vector Graphviz SVG diagrams (Figures 230-236). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Author an in-depth, authoritative architectural and developer guide for the SOF Short-Time Fourier Transform (STFT) Process subsystem: - Mathematical formulation: discrete STFT/iSTFT, convolution theorem, and frequency-domain filtering vs time-domain filters and phase vocoder. - Ring buffer ingress/egress, framing geometry, and hop sizing. - Five configurable window profiles (Rectangular, Blackman, Hamming, Hann, and Kaldi-compatible Povey) with COLA condition and exact Q1.31 synthesis gain compensation. - Dual-domain Cartesian complex vs polar magnitude/phase processing with conjugate Hermitian symmetry restoration. - Single contiguous memory allocation and zero-copy polar buffer overlay. - Cadence Tensilica HiFi3 SIMD vectorization (AE_MULFP32X2RS, AE_MULAFP32X2RS). - Intel IPC4 64-byte configuration blob, Zephyr LLEXT packaging, and ALSA Topology 2 graph integration. - Factory bringup runbook: Octave blob synthesis, standalone testbench, and acoustic linearity validation. - 7 native vector Graphviz SVG architecture diagrams (Figures 237-243). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Author an in-depth, authoritative architectural and developer guide for the SOF Media Codecs: Audio Encoders & Decoders subsystem: - Architectural foundations: DSP compress-offload, host CPU C10/D3 deep sleep residency, deep buffer DMA, and low-power audio pipeline comparison. - Cadence Xtensa Audio (XA) API standard and lifecycle state machine: size query, pre/post-config, memory negotiation, and execution protocol. - Standard memory management: 4 XA memory classes (PERSIST, SCRATCH, INPUT, OUTPUT), two-phase allocation, and circular buffer linearization. - Supported codecs: MP3 dec/enc (1152 samples), AAC ADTS dec (1024 samples), Vorbis, SBC, in-tree PCM reference (xa_pcm_dec.c with EOS safety counter), and DTS Audio spatializer integration (dts.c). - Control plane integration: legacy IPC3 snd_codec vs modern IPC4 unified module architecture, DP scheduling domain, and asynchronous unsolicited compress EOS notifications (SOF_IPC4_NOTIFY_MODULE_EVENTID_COMPR_MAGIC_VAL). - ALSA Topology 2 deep-buffer pipeline graph: decoder.conf, encoder.conf, compr-playback.conf, format adaptors, and mixin lp_mode 1. - Factory bringup runbook: tinycompress (cplay, crecord), capabilities query, turbostat C10 power telemetry verification, and testbench validation. - 7 native vector Graphviz SVG architecture diagrams (Figures 244-250). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…odernization
Modernize and significantly expand the Rimage developer documentation
to establish an authoritative, deeply technical reference for firmware
packaging, cryptographic signing, and hardware boot handshakes:
- Author comprehensive developer_guides/rimage/index.rst covering:
* Dual implementations: production C99 toolchain (tools/rimage/) and
the upstream Rust port (thesofproject/rimage).
* Byte-level binary image layout (.ri) from offset 0x0000 to EOF,
covering XMan, CSE (), CSS (), Signed Pkg metadata,
Firmware Descriptor (), and Module Table ().
* Platform memory matrix comparing cAVS (1.5, 1.8, 2.5) and ACE
(1.5, 2.0, 3.0) addressing, cached/uncached SRAM aliases, IMR
staging windows, L2 cache bypass, and alignment rules.
* Dual cryptographic signing workflows (native RSA PKCS#1 v1.5 vs
Intel MEU/HSM) and Silicon Root-of-Trust (RoT) eFuse authentication.
* Zephyr LLEXT dynamic module packaging (-l).
* Declarative TOML configuration (platform-*.toml and *.toml.h).
* Complete CLI reference, CMake/west integration, and troubleshooting
matrix with hexdump and readelf diagnostic recipes.
- Rewrite developer_guides/rimage/extended_manifest.rst into an
in-depth architectural specification of the Extended Manifest (XMan),
documenting header invariants, all element types (0 through 6),
alignment constraints (EXT_MAN_ALIGN = 16), Linux kernel host driver
handshake flow (loader.c), and step-by-step element extension guide.
- Replace legacy PlantUML .pu diagrams with 5 publication-quality
native vector SVG diagrams:
* rimage_pipeline_architecture.svg (5-stage packaging pipeline)
* rimage_binary_layout.svg (byte-level binary layout)
* rimage_extended_manifest_handshake.svg (XMan element taxonomy & handshake)
* rimage_crypto_signing_flow.svg (signing workflows & hardware RoT)
* rimage_platform_memory_matrix.svg (cAVS vs ACE memory & virtual addressing)
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Elevate developer_guides/firmware/hostless_firmware.rst into an authoritative technical reference for hostless embedded firmware operation. Key additions and updates: - Host-driven vs hostless paradigm comparative matrix. - Detailed static topology architecture with C structures (sof_static_topology, sof_static_comp, sof_static_buffer, sof_static_route, sof_static_kcontrol) and static_pipeline_loader initialization flow. - Supported platform architectural breakdown covering Teensy 4.1 (i.MX RT1062, Audio PLL4, SAI1, S/PDIF), ESP32-P4 (dual RISC-V @ 400 MHz, FPU/SIMD, High-Speed USB UAC2), and ESP32-C6 (wireless coprocessor bridge). - Digital endpoint subsystem integration for USB Audio Class 2.0 (UAC2) with asynchronous rate feedback and Feature Unit binding, plus Bluetooth LE Audio and Auracast streaming. - Clocking topologies and hardware test bridges across Clock Provider, Clock Consumer, and DMIC injector modes, with Header J1 cross-jumper interconnect wiring table for Pallas/Ceres loopback testing. - Zephyr interactive shell command reference and terminal session walk-through. - 5-step tutorial for authoring custom static topologies in C and Kconfig. - Troubleshooting matrix and terminal diagnostic recipes. - Three vector SVG diagrams: hostless_system_architecture.svg (Fig 218), hostless_static_pipeline_graph.svg (Fig 219), and hostless_clocking_audio_bridges.svg (Fig 220). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Elevate developer_guides/linux_driver/architecture.rst into an authoritative technical reference for the Sound Open Firmware Linux kernel driver subsystem. Key technical additions and coverage: - Layered system architectural hierarchy from user-space daemons (PipeWire, PulseAudio, ALSA lib, UCM2) through ALSA Core/ASoC, SOF Core, IPC protocols, platform DSP drivers, and physical hardware buses. - Subsystem responsibility matrix (Table 44). - Core device registration, struct snd_sof_dev, Extended Manifest parsing, firmware downloading, and DSP boot notification flow. - Dynamic PCM (DPCM) Front-End and Back-End decoupling, full ALSA PCM stream operations lifecycle (Table 46), and sub-microsecond position reporting (hardware DMA position vs DSP Linear Link Position). - Inter-Processor Communication (IPC) subsystem architecture comparing Classic IPC3 (fixed-envelope SRAM mailboxes) against Modern IPC4 (64-bit bitpacked register envelopes) in Table 45, with unified driver transaction lifecycle, completion waitqueues, and timeout watchdog recovery. - Dynamic topology parsing (topology.c) translating ALSA binary topology (.tplg) into DSP runtime component pipelines, ring buffers, and kcontrols. - Dual-axis power management state machine (pm.c) detailing transitions across D0, D0ix (autonomous active idle with WAITI clock gating), D3hot (runtime suspend), and D3cold (system suspend S0ix/S3 with LLEXT DRAM staging). - Modular auxiliary client driver framework (sof-client.c, snd_sof_client_dev) covering probes/tracing (snd-sof-probes.ko), dynamic LLEXT module injection (snd-sof-llext-load.ko), remote GDB stub, and IPC injectors. - Platform DSP operations abstraction (struct snd_sof_dsp_ops) and platform dispatch matrix (Table 47) across Intel cAVS/ACE, NXP i.MX, and AMD ACP. - Debugfs telemetry hierarchy (/sys/kernel/debug/sof/), ftrace events, troubleshooting matrix (Table 48), and terminal diagnostic recipes. - Three custom vector SVG diagrams: driver_layered_architecture.svg, driver_ipc_lifecycle_flow.svg, and driver_pcm_power_state_machine.svg. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Remove the obsolete third-party feature pages under developer_guides/linux_driver/third_party/ and the VirtIO virtualization guides under developer_guides/virtualization/. Clean up parent toctrees, cross-references in developer_guides/index.rst, and woke configuration. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…r guide Comprehensive modernization of the ALSA Topology 2.0 developer guide: - Complete language primitive specification: Classes, Objects, Attributes, Qualifiers (!constructor, !mandatory, !immutable, unique), Constraints, Arguments (@Args), and Conditional Includes (IncludeByKey, Define). - Decoupled Front-End (PCM) and Back-End (DAI) pipeline architecture with mixin/mixout dynamic routing and dynamic index resolution. - Standardized PCM ID and Pipeline ID allocation conventions (SoundWire stride-10 rule and HDMI stride-10 patterns). - Detailed 5-step developer tutorials for: 1) Creating a new module (widget/component) 2) Creating a new pipeline template 3) Adding a new silicon platform - Deep dive on Split Topologies: Functional Topologies (single-function hardware endpoint graphs) vs Feature Topologies (orthogonal DSP feature overlays) and dynamic kernel assembly (sof-function-topology-lib.c). - Four high-resolution dark-themed publication-grade SVG diagrams. - Building, decompiling (alsatplg -P), and DUT diagnostic recipes. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Comprehensively update and expand the ktest developer guide to match the publication standards of the SOF documentation suite: - Modernize introduction and architecture overview for SOF kernel testing - Add 2 native dark-themed SVGs: automated testing loop architecture and automated regression bisection workflow - Detail complete target setup: ed25519 SSH keys, GRUB2 saved_entry and grub-reboot boot-once fail-safe lifecycle, and BLS support - Provide Git worktrees workflow for multi-DUT and multi-branch testing - Include complete production-grade ktest.conf and directive reference table - Provide a robust automated audio smoke test script (test_sof_audio.sh) validating DSP firmware boot, ALSA cards, PCM playback, and dmesg guards - Detail automated regression bisection (TEST_TYPE = bisect, BISECT_TYPE = git) - Include network boot (PXE/TFTP/NFS) and hardware relay power control - Add comprehensive troubleshooting and maintenance runbook - Pass strict Sphinx build (-W --keep-going) and woke inclusive language checks Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Comprehensively overhaul and expand the unit testing developer guide: - Document the 5-tier firmware verification hierarchy comparing Ztest, Host Testbench, QEMU simulation, hardware loopbacks, and ktest - Add 2 native dark-themed SVGs: Ztest & Twister architecture and Ztest v3 suite execution fixture lifecycle flow - Detail Ztest v3 fixture hooks: suite_setup, test_before, test_after, suite_teardown, and comprehensive assertion macros - Document Fake Function Framework (FFF) hardware and subsystem mocking - Complete testcase.yaml configuration specification and directive table - Comprehensive Twister CLI execution recipes, filtering, and options - Detail Gcov/lcov code coverage, AddressSanitizer (ASan), and Valgrind - Provide 3 step-by-step developer tutorials: core math routine suite, audio component test with mocked pipeline, and interactive GDB debugging - Include legacy CMocka to Ztest v3 migration mapping table - Pass strict Sphinx build (-W --keep-going) and woke inclusive language checks Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Comprehensively modernize and expand the Hardware Audio Loopback Verification guide in developer_guides/testing/hardware_loopback.rst. - Document physical silicon verification rationale, bridging host automated test runners to target DUTs via embedded microcontrollers. - Detail 5-tier hardware loopback system architecture with custom SVG diagram (developer_guides/testing/images/hardware_loopback_system_architecture.svg). - Provide complete hardware wiring and pinout specifications for ESP32-P4 (Pallas Provider Tx to Ceres Consumer Rx 7-wire J1 header cross-connect, Spider I2S0 40-pin header mapping, Aphid PDM DMIC capture injector). - Document Teensy 4.1 Audio Bridge (NXP i.MX RT1062, Audio PLL4 688.128 MHz, fast slew S/PDIF BMC on Pins 14/15, SAI1 I2S). - Add persistent /dev/serial/by-id/ device mapping table and explicit safety isolation instructions for /dev/ttyACM1 power relay controller. - Explain Clock Provider vs Clock Consumer roles with custom SVG diagram (developer_guides/testing/images/hardware_loopback_clocking_modes.svg), Philips I2S bit-alignment timing waveforms, TDM-8 slot allocation, and PDM dual-microphone edge multiplexing. - Include multi-rate, multi-format, multi-channel verification matrix (I2S, TDM, PDM, S/PDIF across 16 kHz to 384 kHz). - Detail automated test runners (test_p4_loopback.py, test_teensy_loopback.py, and capmat capture matrix) with mandatory pre-commit policies. - Formulate acoustic analysis algorithms (FFT dominant tone detection, SNR, THD+N, and bit-exact differential testing). - Cover Saleae Logic Pro 8 high-speed bus analysis with saleae-tool CLI and Python automation scripts with I2S protocol decoder. - Add comprehensive hardware troubleshooting and diagnostic matrix. - Ensure strict compliance with rules-woke.yaml (0 non-inclusive terms). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Comprehensively modernize, rewrite, and expand the SOF Host Audio Pipeline Testbench documentation suite under developer_guides/testbench/: - Modernize index.rst into an authoritative master architecture and user manual covering offline simulation, dual IPC4/IPC3 execution engines, fast offline audio processing, dynamic control scripting, and cycle- accurate Xtensa simulation. - Rewrite build_testbench.rst with scripts/rebuild-testbench.sh, CMake, host-testbench.sh, sof-testbench-helper.sh, and Xtensa targets (-p mtl). - Overhaul debug_in_testbench.rst with GDB/LLDB component lifecycle hooks, circular audio buffer inspection, Valgrind, sanitizers, and xt-gprof. - Rewrite prepare_new_component.rst replacing obsolete 2018 hardcoded UUID tables and m4 macros with modern Module Adapter API and Topology 2.0. - Overhaul test_audio_quality.rst with AES17 electroacoustic validation, GNU Octave process_test.m, chirp spectrograms, and CI automation. - Author two native dark-themed SVGs: testbench_system_architecture.svg (Figure 316) and testbench_pipeline_execution_flow.svg (Figure 317). - Full compliance with rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…ication guide Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…curity guide Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
In Figure 327 (fuzzing_architecture_overview.svg) and Figure 325 (xtrun_system_architecture.svg), horizontal and vertical sub-cards were offset while their internal <text> elements retained local coordinate origins without enclosing translate groups, causing text from multiple cards to overlap in the top/leftmost box. Wrap each sub-card in dedicated <g transform="translate(...)"> groups with local origins, cleanly separating all cards across: - Figure 327: Section 1 input mutators, Section 2 libFuzzer/AFL++ engines, and Section 3 sanitizers/triage pipelines. - Figure 325: Section 1 CLI/orchestrator tools, Section 2 core descriptors/LSP, Section 3 memory hierarchy, and Section 4 backends. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…ll guides Comprehensively modernize the SOF debugability and telemetry documentation suite: - Overhaul master debugability portal with tool comparison matrix and diagnostic decision tree. - Detail DSP trace architecture, smex token dictionary (.ldc), DMA buffer, debugfs, sof-logger, and TCP probe server (Figure 329). - Modernize coredump post-mortem debugging for Zephyr RTOS (CONFIG_DEBUG_COREDUMP, Intel ADSP memory window backend, coredump_gdbserver.py, and GDB analysis) (Figure 330). - Deep-dive dynamic audio buffer probes, injection/extraction, crecord compress capture, probe server :9999, and differential acoustic analysis (Figure 331). - Document interactive in-memory Zephyr shell (CONFIG_SHELL_BACKEND_ADSP_MEMORY_WINDOW, cavstool.py terminal bridge, thread/stack analysis, D0ix/D3 resilience). - Update hardware performance counters guide (Xtensa CCOUNT, MCPS calculation formula, pipeline budgeting). - Expand firmware binary manifest guide ($CPD, $AM1, $AME, $AE1, XMan, Intel signing certificates). - Enforce strict SVG coordinate grouping (<g transform='translate(...)'>) across all diagrams. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Comprehensively modernize the SOF UUID developer guide: - Document architectural rationale: ABI fragility, 8-way combination matrix, enum collisions, and dynamic LLEXT module support. - Detail the end-to-end subsystem lifecycle across Specification/Registry, Firmware Core/Linker Placement, Topology/Host Kernel Driver, and Telemetry/Logger tiers (Figure 332). - Formulate wire format translation and little-endian word swap rules from RFC 4122 canonical string to memory bytes and Topology 2 tokens (Figure 333). - Document the global registry (uuid-registry.txt), gen-uuid-reg.py, and automated module allocation with sdk-create-module.py. - Explain Zephyr RTOS iterable sections (STRUCT_SECTION_ITERABLE in .rodata) and garbage collection of unused UUIDs. - Detail ALSA Topology 2.0 (.conf) token syntax (DefineAttribute.uuid, comp.uuid, SOF_TKN_COMP_UUID). - Detail host kernel parsing (ipc*-topology.c) and on-demand dynamic module loading (ipc4-loader.c with %pUL.bin). - Cover smex dictionary extraction (.static_uuid_entries), compact 32-bit trace DMA pointers, and live sof-logger decoding. - Provide step-by-step developer checklist and troubleshooting runbook. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…bility subsection toctree Align the DSP telemetry and diagnostic documentation with the other Developer Guides pillars: - Expand Section 6 (DSP Telemetry, Logging & Diagnostics) in developer_guides/index.rst into four functional categories with annotated descriptions and references. - Configure direct toctree entries for all telemetry, coredump, probes, shell, performance counters, ri-info, and uuid subsystem guides. - Remove the redundant Subsystem Developer Guides section and nested toctree from developer_guides/debugability/index.rst, replacing it with clean cross-references. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…links - Configure :hidden: on the Section 6 .. toctree:: directive in developer_guides/index.rst. - Eliminates redundant bulleted document link list rendered directly beneath the annotated subsections while preserving sidebar navigation hierarchy. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Replace specific DUT hostnames (Spider, Aphid, Dragon Fly) with generalized target DUT references (<dut>, Target DUT). - Reframe specific board GPIO wiring and pinout tables as concrete reference examples. - Update SVG system diagrams and platform YAML matrices. - Preserve legitimate electro-acoustic loudspeaker suspension terminology in tuning guides. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Generalize loopback test script references (test_p4_loopback.py, test_teensy_loopback.py) to generic test runners and standard ALSA utilities. - Reframe J1 loopback wiring tables as illustrative examples, replacing private board names (Pallas, Ceres) with generic bridge card designations. - Generalize SVG system architecture and clocking diagrams. - Clean up lingering hardcoded user paths in ktest, stft_process, and phase_vocoder guides. - Clean audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
… and ESP32-P4 - Add prominent hardware warning and pinout table showing 1.8V to 3.3V bidirectional level translation between Panther Lake and ESP32-P4. - Update hostless clock consumer mode notes and hardware loopback architecture SVG. - Clean audit against rules-woke.yaml (0 infractions) and strict Sphinx build (0 warnings/errors). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Remove Saleae Logic Pro 8 High-Speed Bus Analysis section from hardware_loopback.rst. - Generalize instrumentation, timing, and troubleshooting checks across loopback and dmic tuning guides. - Update hardware loopback system architecture SVG to highlight power telemetry and remote relay control. - Verify 0 saleae occurrences remain across documentation repository. - Comply with rules-woke.yaml (0 infractions) and pass strict Sphinx build. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Clarify Cadence Xtensa tools as the production default for Xtensa DSP targets. - Document Zephyr SDK compiling compliant binaries without Xtensa SIMD. - Document experimental LLVM/Clang compiling HiFi for Xtensa SIMD with mandatory IAS. - Provide explicit environment setup and build commands (west and xtensa-build-zephyr.py) for each toolchain. - Update CMake build pipeline architecture SVG to match the 3-toolchain hierarchy. - Pass strict Sphinx build (0 warnings/errors) and audit against rules-woke.yaml (0 infractions). Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Update parse_fw_version regex in generate_matrices.py to match 'SOF Version v...' as formatted in the v2026.09 release body on GitHub. Update cached release data and installation guide download example to reflect firmware v2.15. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
requested review from
deb-intel,
intelkevinputnam,
mmaka1 and
mwasko
as code owners
September 20, 2026 13:13
- Sanitize non-inclusive terms in developer guides, diagrams, and testbench documentation. - Replace c code-block with text in rimage toml.h excerpt to resolve Pygments token failure. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation modernization across Sound Open Firmware developer guides, processing module architectures, testing frameworks, toolchains, and release catalog:
Developer Guides & Processing Modules Architecture:
Testing, Simulation & Debugging:
Hardware Generalization & Interconnect Safety:
CMake 3-Toolchain Architecture Guide:
developer_guides/tech/cmake.rstto document the 3 supported toolchain backends:xt-clang/xcc): Production default for Xtensa DSP targets with full HiFi SIMD vectorization.west buildandxtensa-build-zephyr.py) for each toolchain backend.Release Catalog & Firmware Version Mapping:
scripts/generate_matrices.pyto handleSOF Version v...string formatting in GitHub release bodies.v2.15for latest binary releasev2026.09indata/sof_bin_releases.json, hero card, and recent releases table.Verification
sphinx-build -b html -W --keep-going . _build/htmlpasses with 0 warnings and 0 errors.rules-woke.yamlwith 0 infractions.Signed-off-by: Liam Girdwood liam.r.girdwood@linux.intel.com