diff --git a/api/components.rst b/api/components.rst new file mode 100644 index 00000000..0f092f9b --- /dev/null +++ b/api/components.rst @@ -0,0 +1,11 @@ +.. _api_components: + +Audio Processing Components 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. + +.. doxygengroup:: audio_components_api + :project: SOF Project diff --git a/api/index.rst b/api/index.rst index b23c6ae8..cd49b302 100644 --- a/api/index.rst +++ b/api/index.rst @@ -42,6 +42,19 @@ The Doxygen documentation covers the entire public firmware and host-shared inte * **Source Code Graphs & File Browsing**: Full source file tree, header include dependency graphs, and function call/caller graphs. +Subsystem C API References +************************** + +.. toctree:: + :maxdepth: 1 + + ipc4 + modules + pipeline + components + rtos + math + Building API Documentation Locally ********************************** diff --git a/api/ipc4.rst b/api/ipc4.rst new file mode 100644 index 00000000..82403c31 --- /dev/null +++ b/api/ipc4.rst @@ -0,0 +1,11 @@ +.. _api_ipc4: + +IPC4 Host-DSP Protocol API +########################## + +The IPC4 protocol defines the communication contract between the host operating system +driver and the Sound Open Firmware DSP. It governs pipeline creation, module binding, +audio gateway configuration, runtime parameter adjustment, and asynchronous telemetry. + +.. doxygengroup:: ipc4_api + :project: SOF Project diff --git a/api/math.rst b/api/math.rst new file mode 100644 index 00000000..647cbc4c --- /dev/null +++ b/api/math.rst @@ -0,0 +1,12 @@ +.. _api_math: + +DSP Math & Filter Libraries API +############################### + +Digital signal processing routines in SOF provide optimized fixed-point and floating-point +mathematical routines. These include trigonometric approximations, polynomial functions, +CORDIC algorithms, Fast Fourier Transforms (FFT), IIR/FIR filter structures, and matrix +operations. + +.. doxygengroup:: dsp_math_api + :project: SOF Project diff --git a/api/modules.rst b/api/modules.rst new file mode 100644 index 00000000..870af3c9 --- /dev/null +++ b/api/modules.rst @@ -0,0 +1,12 @@ +.. _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 new file mode 100644 index 00000000..046a6fb7 --- /dev/null +++ b/api/pipeline.rst @@ -0,0 +1,12 @@ +.. _api_pipeline: + +Audio Pipeline & Buffer 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. + +.. doxygengroup:: audio_pipeline_api + :project: SOF Project diff --git a/api/rtos.rst b/api/rtos.rst new file mode 100644 index 00000000..1b70173b --- /dev/null +++ b/api/rtos.rst @@ -0,0 +1,12 @@ +.. _api_rtos: + +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. + +.. doxygengroup:: rtos_api + :project: SOF Project diff --git a/index.rst b/index.rst index 6d0a285a..d6536f36 100644 --- a/index.rst +++ b/index.rst @@ -1,20 +1,117 @@ -.. meta:: - :http-equiv=Refresh: 0; url=introduction/index.html - -.. raw:: html - - - .. _SOF_home: Sound Open Firmware Documentation ################################# +Welcome to the **Sound Open Firmware (SOF)** technical documentation portal. + +Sound Open Firmware is a permissively licensed, open-source audio Digital Signal Processing (DSP) firmware infrastructure, SDK, and real-time execution framework governed under the **Linux Foundation** and directed by the **SOF Technical Steering Committee (TSC)**. + +SOF provides transparent, deterministic, low-latency audio processing infrastructure for modern computing architectures ranging from embedded microcontrollers and IoT devices to multi-core client PCs and servers. + +.. figure:: introduction/images/sof-waveform.jpeg + :alt: Sound Open Firmware audio DSP processing + :align: center + :width: 100% + +Architecture & Key Capabilities +******************************* + +Sound Open Firmware delivers a unified, cross-platform audio software stack across two foundational deployment paradigms: + +* **Host-Based Client Architecture**: Where the DSP operates as an accelerator coupled to a host application processor running **Linux**, **ChromeOS**, **Android**, or **Windows**. The mainline Linux kernel driver subsystem (``sound/soc/sof/``) manages firmware lifecycle, dynamic ALSA topology parsing, and aggressive power gating (D0ix runtime idle, D3 cold suspend), while real-time audio streams exchange through mailbox IPC protocols (IPC4 and IPC3) and host DMA memory windows. +* **Hostless & Standalone Architecture**: Where SOF executes autonomously on microcontrollers and embedded DSPs (such as the **Espressif ESP32-P4** or **PJRC Teensy 4.1 / i.MX RT1062**) atop the **Zephyr RTOS**. Standalone topologies process audio directly between hardware peripherals (I2S/TDM, SoundWire, PDM microphones, and S/PDIF) without requiring a host OS. + +Documentation Pillars & Navigation +********************************** + +Explore the documentation portal by selecting one of the core technical pillars below: + .. raw:: html -

Redirecting to Introduction to the SOF Project...

+
+ +
+

+ Introduction to SOF → +

+

+ Learn about the SOF project mission, benefits of audio DSP offloading (power, deterministic latency, vertical stack centralization), licensing, and governance. +

+ Read Introduction » +
+ +
+

+ Getting Started → +

+

+ Set up your build host, configure the LLVM/Clang Xtensa cross-compiler toolchain, compile firmware images for target platforms, and run simulation in QEMU. +

+ Explore Quickstart » +
+ +
+

+ Architecture & System Design → +

+

+ Deep dive into firmware architecture: audio pipeline execution graphs (DAGs), lockless ring buffers, Zephyr RTOS abstraction, IPC3/IPC4 protocols, and power management. +

+ View Architecture » +
+ +
+

+ Supported Platforms Matrix → +

+

+ Hardware compatibility specifications across Intel CAVS & ACE (PTL, ARL, MTL, TGL), AMD, NXP i.MX, MediaTek, Espressif ESP32-P4, and PJRC Teensy 4.1. +

+ Browse Platforms » +
+ +
+

+ Audio Algorithms & Components → +

+

+ Comprehensive catalog of built-in audio signal processing modules: Volume, Mixer, Parametric EQ (FIR/IIR), DRC, SRC, ASRC, Crossover, DCBlock, and Wake-on-Voice. +

+ Inspect Algorithms » +
+ +
+

+ Developer Guides & Runbooks → +

+

+ Step-by-step developer runbooks: ALSA Topology 2 creation, UCM2 configuration and debugging, LLEXT dynamic module integration, CMake workflows, and real-time DSP probes. +

+ Read Guides » +
+ +
+

+ C API & Firmware Reference → +

+

+ Interactive Doxygen API documentation and Sphinx Breathe subsystem reference for IPC4, LLEXT modules, pipeline scheduling, audio components, RTOS abstraction, and DSP math. +

+ Explore C API » +
+ +
+

+ Community & Contributing → +

+

+ Join the SOF open-source community: contributor guidelines, Git patch submission rules, TSC meeting minutes, releases, and frequently asked questions. +

+ Contribute » +
+ +
.. toctree:: :hidden: @@ -32,4 +129,3 @@ Sound Open Firmware Documentation api/index.rst presentations/index.rst faq/index.rst -