diff --git a/architecture.md b/architecture.md new file mode 100644 index 000000000000..e236a2b659e6 --- /dev/null +++ b/architecture.md @@ -0,0 +1,46 @@ +# Sound Open Firmware (SOF) Architecture + +This document provides a high-level overview of the Sound Open Firmware (SOF) architecture. SOF provides an open-source audio DSP firmware and an SDK for audio development. + +## 1. High-Level Overview + +At a macro level, the SOF stack consists of: +* **Host Driver (OS):** The OS-level driver (Linux ALSA/ASoC, Windows, etc.) that acts as the frontend, managing audio devices, streams, and IPC communication. +* **Firmware (DSP):** The embedded firmware running on the Audio DSP (typically Xtensa/Tensilica or other DSPs). +* **Topology:** A configuration file loaded by the host driver that defines the hardware constraints, routing, and instantiated audio processing graphs (pipelines). + +## 2. Firmware Architecture + +The SOF firmware is built with a modular, layered architecture to support multiple platforms, DSP architectures, and operating systems. + +### 2.1 OS Abstraction and RTOS +* **Zephyr RTOS:** Modern SOF extensively leverages the Zephyr RTOS for core operating system services, including thread scheduling, synchronization, logging, and hardware abstraction. +* **XTOS / Bare-metal (Legacy):** Older platforms or specific stripped-down environments might use XTOS or bare-metal abstractions. + +### 2.2 Inter-Process Communication (IPC) +The IPC subsystem is responsible for all communication between the Host OS and the DSP Firmware. +* **Message Passing:** Uses hardware mailboxes, shared memory, and interrupts to send messages. +* **Commands:** Includes stream setup, pipeline instantiation, run/pause/stop commands, volume changes, and parameter updates. +* **Versions:** IPC relies on a versioned message protocol (e.g., IPC3, IPC4) allowing the host and firmware to understand each other's commands. + +### 2.3 Audio Processing Pipelines +At the core of the SOF firmware is the DSP pipeline. A pipeline is a directed graph consisting of connected audio modules (components) that process streams of data. +* **Endpoints:** Pipelines connect external interfaces (like I2S/HDA/DMIC DAIs - Digital Audio Interfaces) to host DMA buffers. +* **Scheduling:** Each pipeline is scheduled to run periodically based on its timing requirements and deadlines. SOF provides an LL (Low Latency) scheduler and an EDF (Earliest Deadline First) scheduler. + +### 2.4 Audio Components (Modules) +The firmware processing graph is assembled using individual audio modules, which are dynamically instantiated based on the topology file: +* **Host / DAI Components:** Read/write audio frames from/to DMA buffers or hardware interfaces. +* **Copier:** Moves data between buffers or other components without modification. +* **Volume / Mixer:** Changes signal amplitude or mixes multiple streams. +* **SRC (Sample Rate Converter):** Resamples audio streams. +* **Effect Modules:** EQs (Equalizers), DRCs (Dynamic Range Compressors), smart amplifiers, arrays, and other algorithmic components. + +### 2.5 Memory Management +The DSP handles multiple memory domains depending on the hardware (SRAM, L1 Cache, L2, external memory). +* **Heaps:** Different memory heaps exist for dynamic allocation (e.g., system heap, buffer heap, runtime heap) to ensure real-time constraints and avoid fragmentation. +* **Data Buffers:** Audio buffers are carefully allocated in appropriate memory to minimize power consumption and pipeline latency. + +## 3. Topologies + +The host driver parses a topology file (`.tplg`) which describes the expected processing graphs. Instead of hardcoding audio routing in the firmware, SOF uses these topology constraints. The firmware receives the component creation sequences, parameter configurations, and connections over IPC to construct pipelines at runtime. diff --git a/scripts/Readme.md b/scripts/README.md similarity index 100% rename from scripts/Readme.md rename to scripts/README.md diff --git a/src/audio/aria/README.md b/src/audio/aria/README.md new file mode 100644 index 000000000000..99dcc595ac6d --- /dev/null +++ b/src/audio/aria/README.md @@ -0,0 +1,23 @@ +# Aria Audio Component Architecture + +This directory contains the implementation of the Aria audio component. + +## Overview + +The Aria component implements an automatic regressive input amplifier that applies variable input gain, reducing gain for high-level signals to prevent clipping while introducing about 1 ms of processing latency. + +## Architecture Diagram + +```mermaid +graph LR + In[Input Data] --> Aria[Aria Core Processing] + Aria --> Out[Output Data] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the ARIA (Automatic Regressive Input Amplifier Module) component. It applies a variable gain (target: 0, 6, 12, 18 dB) that is reduced for high-level signals to prevent clipping, introducing a 1ms latency. Users can choose HIFI optimization levels (HIFI3, HIFI4, Max, Generic). +- **CMakeLists.txt**: Handles the build integration. Depends on `IPC_MAJOR_4`. If built modularly (`CONFIG_COMP_ARIA="m"`), it uses a loadable extension (`llext`); otherwise, it compiles `aria.c` and HIFI-specific files locally. +- **aria.toml**: Defines the topology parameters for the module (UUID, affinity, pin configuration) and an array of `mod_cfg` configurations defining processing constraints for various setups. +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/aria.conf`, it defines the `aria` widget object for topology generation. It exposes attributes like `cpc` (cycles per chunk) and `is_pages`. It sets up an `extctl` byte control with a maximum payload of 4096 bytes and defaults to UUID `6d:16:f7:99:2c:37:ef:43:81:f6:22:00:7a:a1:5f:03` (type `effect`). +- **MATLAB Tuning (`tune/`)**: Contains `.m` scripts (e.g., `sof_aria_blobs.m`) which generate ALSA control binary blobs, text formats, and M4 configuration fragments used at topology creation or runtime to supply operational parameters like attenuation settings (e.g., `param_1.conf`, `param_2.conf`). diff --git a/src/audio/asrc/README.md b/src/audio/asrc/README.md new file mode 100644 index 000000000000..0ed94f83f8dc --- /dev/null +++ b/src/audio/asrc/README.md @@ -0,0 +1,23 @@ +# Asynchronous Sample Rate Converter (ASRC) Architecture + +This directory contains the ASRC component implementation. + +## Overview + +The ASRC component converts the sample rate of an incoming audio stream to a different outgoing sample rate, independently of any synchronous clocks. This is commonly used when crossing clock domains. + +## Architecture Diagram + +```mermaid +graph LR + In[Input Buffer Rate A] --> ASRC[ASRC Core Engine] + ASRC --> Out[Output Buffer Rate B] + Clock[Target Clock Domain] -.-> ASRC +``` + +## Configuration and Scripts + +- **Kconfig**: Controls the ASRC component. ASRC tracks a slave DAI out of sync with firmware timers and uses less RAM than synchronous SRC. It also supports granular configuration of downsampling ratios (from 24kHz/48kHz to lower rates) to optimize memory footprint (about 1.5-2.1 kB per conversion ratio). +- **CMakeLists.txt**: Manages source inclusion (`asrc.c`, `asrc_farrow.c`, etc.). Handles modular builds (`llext`) and chooses IPC abstraction (`asrc_ipc3.c` vs `asrc_ipc4.c`) based on the active IPC major version. +- **asrc.toml**: Holds topology module entry parameters. Features pre-defined `mod_cfg` parameter arrays specifically tailored for `CONFIG_METEORLAKE`, `CONFIG_LUNARLAKE`, and `CONFIG_SOC_ACE30`/`40` SOC platforms. +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/asrc.conf`, defining the `asrc` widget object. It introduces parameters like `rate_out` (target sample rate) and `operation_mode`. Defaults to UUID `2d:40:b4:66:68:b4:f2:42:81:a7:b3:71:21:86:3d:d4` and type `asrc`. diff --git a/src/audio/buffers/README.md b/src/audio/buffers/README.md new file mode 100644 index 000000000000..fcd4516dd4ab --- /dev/null +++ b/src/audio/buffers/README.md @@ -0,0 +1,20 @@ +# Audio Buffers Architecture + +This directory contains the core audio buffer management. + +## Overview + +Buffers connect the output of one component to the input of the next in an audio pipeline graph. They implement circular (ring) buffer semantics and handle cache coherency for DSP memory. + +## Architecture Diagram + +```mermaid +graph LR + CompA[Component A / Producer] -->|Write| Buf[Ring Buffer] + Buf -->|Read| CompB[Component B / Consumer] +``` + +## Configuration and Scripts + +- **CMakeLists.txt**: Includes the base core buffer source files (`audio_buffer.c`, `comp_buffer.c`). When the `CONFIG_PIPELINE_2_0` feature flag is enabled, it additionally compiles `ring_buffer.c`. +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/buffer.conf`, defining the `buffer` widget object. Key parameters include `size` (automatically computed), `periods`, `channels`, and `caps` (capabilities like `dai`, `host`, `pass`, `comp`). Defaults to UUID `92:4c:54:42:92:8e:41:4e:b6:79:34:51:9f:1c:1d:28`. diff --git a/src/audio/codec/README.md b/src/audio/codec/README.md new file mode 100644 index 000000000000..76a27e696d1a --- /dev/null +++ b/src/audio/codec/README.md @@ -0,0 +1,13 @@ +# Codec Abstraction Architecture + +This directory contains abstractions and adapters for various hardware and software audio codecs. + +## Overview + +Provides a unified interface to initialize, configure, and stream data to/from codec dependencies. + +## Configuration and Scripts + +- **Kconfig**: Specifically manages configurations for external codecs. For example, it defines options for the `DTS_CODEC`, including a testing/CI stub `DTS_CODEC_STUB` when `COMP_STUBS` is enabled. Use of the actual DTS codec requires a pre-compiled static library from Xperi. +- **CMakeLists.txt**: Specifies Zephyr build integration. For the DTS codec, it checks for modular builds (`llext`). If built statically, it either links the stub source or imports the pre-compiled `libdts-sof-interface-i32.a` library depending on configuration. +- **Topology (.conf)**: `tools/topology/topology2/include/components/dts.conf` defines the `dts` widget. It exposes `cpc` (cycles per chunk) and configures a byte control of size 2048 with `extctl` operations. Defaults to UUID `4f:c3:5f:d9:0f:37:c7:4a:bc:86:bf:dc:5b:e2:41:e6`. diff --git a/src/audio/copier/README.md b/src/audio/copier/README.md new file mode 100644 index 000000000000..f120f9cd7a86 --- /dev/null +++ b/src/audio/copier/README.md @@ -0,0 +1,22 @@ +# Copier Architecture + +This directory contains the Copier component. + +## Overview + +The Copier is a versatile component responsible for moving data smoothly between hardware endpoints (DAIs, Host APIs) and internal buffers. It may also apply simple format conversions (e.g., 16-bit to 32-bit). + +## Architecture Diagram + +```mermaid +graph LR + DMA[DMA Engine] <--> Copier[Copier Component] + Copier <--> Buf[Internal Buffer] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the `COMP_COPIER` component (depends on IPC 4). Also defines `COMP_DAI`, options to reverse DMA/DAI trigger stop ordering (`COMP_DAI_STOP_TRIGGER_ORDER_REVERSE`), DAI grouping, and an optional copier gain feature (`COPIER_GAIN`) for static gain, mute, or transition gain (fade-in/fade-out). +- **CMakeLists.txt**: Includes base copier implementations (HIFI, generic, host, DAI). If `CONFIG_IPC4_GATEWAY` is enabled, it adds `copier_ipcgtw.c`, and if `CONFIG_COPIER_GAIN` is selected, includes `copier_gain.c`. +- **copier.toml**: Contains topology configurations, describing UUID, pins, and complex `mod_cfg` tuples tailored per platform (`CONFIG_METEORLAKE`, `CONFIG_LUNARLAKE`, or `CONFIG_SOC_ACE30`/`40`). +- **Topology (.conf)**: `tools/topology/topology2/include/components/dai-copier.conf` (among others like `host-copier`, `module-copier`) define copier widget objects. They configure connection-specific attributes like `copier_type` (e.g., `HDA`, `SSP`, `DMIC`, `SAI`), `direction` (`playback` or `capture`), `node_type`, and `cpc`. `dai-copier` defaults to UUID `83:0c:a0:9b:12:CA:83:4a:94:3c:1f:a2:e8:2f:9d:da`. diff --git a/src/audio/crossover/README.md b/src/audio/crossover/README.md new file mode 100644 index 000000000000..01845ac23d76 --- /dev/null +++ b/src/audio/crossover/README.md @@ -0,0 +1,24 @@ +# Crossover Architecture + +This directory contains the Crossover filter component. + +## Overview + +The Crossover splits an audio signal into multiple frequency bands (e.g., Low, Mid, High) so they can be processed or routed independently (like to a woofer and a tweeter). + +## Architecture Diagram + +```mermaid +graph LR + In[Wideband Audio In] --> Cross[Crossover Split] + Cross --> OutLow[Low Frequency Out] + Cross --> OutHigh[High Frequency Out] +``` + +## Configuration and Scripts + +- **Kconfig**: Selects the Crossover Filter (`COMP_CROSSOVER`), which splits signals into driver-specific frequencies. Also automatically selects `COMP_BLOB` and `MATH_IIR_DF2T` math functions for its internal filters. +- **CMakeLists.txt**: Handles modular builds (`llext`). Selects `crossover.c` and generic implementations, and chooses the correct IPC file (`crossover_ipc3.c` or `crossover_ipc4.c`) based on the active IPC major version. +- **crossover.toml**: Topology parameters for the Crossover module. Sets `init_config = 1` so that `base_cfg_ext` is appended to the IPC payload, which is required up-front to identify output pin indices. Defines UUID, pins, and memory requirements. +- **Topology (.conf)**: `tools/topology/topology2/include/components/crossover.conf` defines the `crossover` widget object. It sets basic widget requirements and defaults to type `effect` with UUID `d1:9a:8c:94:6a:80:31:41:ad:6c:b2:bd:a9:e3:5a:9f`. +- **MATLAB Tuning (`tune/`)**: The `tune` directory holds MATLAB/Octave scripts (like `sof_example_crossover.m`) that convert mathematical frequency split parameters (e.g., 200 Hz, 1000 Hz, 3000 Hz cutoffs) into binary, ALSA, and `.conf` payloads suitable for 2-way, 3-way, or 4-way driver crossover configurations. diff --git a/src/audio/dcblock/README.md b/src/audio/dcblock/README.md new file mode 100644 index 000000000000..4cbae3402540 --- /dev/null +++ b/src/audio/dcblock/README.md @@ -0,0 +1,23 @@ +# DC Block Architecture + +This directory contains the DC Blocking filter. + +## Overview + +The DC Blocker removes the DC offset (0 Hz component) from an audio signal, avoiding speaker damage and maximizing dynamic range. + +## Architecture Diagram + +```mermaid +graph LR + In[Audio Input] --> IIR[High-pass IIR Filter] + IIR --> Out[DC-Free Audio Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the DC Blocking Filter component (`COMP_DCBLOCK`) which filters out DC offsets often from a microphone's output. Includes selectable HIFI optimization levels (Max, HIFI4, HIFI3, Generic). +- **CMakeLists.txt**: Manages local build sources including generic and HIFI optimized versions (`dcblock_generic.c`, `dcblock_hifi3.c`, etc.) and determines the valid IPC abstraction (`dcblock_ipc3.c` vs `dcblock_ipc4.c`). Supports loadable extension generation via `llext`. +- **dcblock.toml**: Topology parameters for the DCBlock module. Defines UUID, pins, and memory limits for IPC integration. +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/dcblock.conf`, it defines the `dcblock` widget object for topology generation. It defaults to type `effect` with UUID `af:ef:09:b8:81:56:b1:42:9e:d6:04:bb:01:2d:d3:84` and enforces input/output pins configuration. +- **MATLAB Tuning (`tune/`)**: The included `.m` scripts (e.g., `sof_example_dcblock.m`) automatically determine the optimal R coefficients to achieve various high-pass cutoff frequencies (-3dB point) across supported sample rates (like 16kHz and 48kHz). These coefficients are then packed into configuration blobs. diff --git a/src/audio/drc/README.md b/src/audio/drc/README.md new file mode 100644 index 000000000000..a0a1eb8dd80a --- /dev/null +++ b/src/audio/drc/README.md @@ -0,0 +1,26 @@ +# Dynamic Range Compressor (DRC) Architecture + +This directory contains the DRC component. + +## Overview + +The Dynamic Range Compressor reduces the volume of loud sounds or amplifies quiet sounds by narrowing or "compressing" an audio signal's dynamic range. + +## Architecture Diagram + +```mermaid +graph TD + In[Audio Input] --> Det[Envelope Detector] + In --> Gain[Gain Element] + Det --> Calc[Gain Calculation] + Calc --> Gain + Gain --> Out[Audio Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the Dynamic Range Compressor component (`COMP_DRC`). It relies on various math features like `CORDIC_FIXED`, `MATH_LUT_SINE_FIXED`, and `MATH_EXP`. The maximum number of pre-delay frames is tunable via `DRC_MAX_PRE_DELAY_FRAMES` (defaults to 512). +- **CMakeLists.txt**: Manages local base sources and generic/HIFI specific files such as `drc_hifi4.c` and `drc_math_hifi3.c`. Adds logging capabilities if compiled in (`drc_log.c`). +- **drc.toml**: Topology parameters for the DRC module definition, exposing UUID and standard buffer sizes and processing capabilities. +- **Topology (.conf)**: `tools/topology/topology2/include/components/drc.conf` configures the `drc` widget object, providing switch controls by binding a mixer control to switch get/put handlers (`259`). Defaults to type `effect` with UUID `da:e4:6e:b3:6f:00:f9:47:a0:6d:fe:cb:e2:d8:b6:ce`. +- **MATLAB Tuning (`tune/`)**: Contains `.m` scripts (e.g., `sof_example_drc.m`) capable of tuning compressor parameters (threshold, knee, ratio, attack, release) and visualizing their gain reaction curves. The outputs are exported as `.conf` configurations, M4 macros, and ALSA `alsactl` payload blobs for preset instantiation defaults (e.g., speaker or DMIC presets). diff --git a/src/audio/eq_fir/README.md b/src/audio/eq_fir/README.md new file mode 100644 index 000000000000..24be526f6189 --- /dev/null +++ b/src/audio/eq_fir/README.md @@ -0,0 +1,24 @@ +# FIR Equalizer Architecture + +This directory contains the Finite Impulse Response (FIR) EQ component. + +## Overview + +FIR equalizers implement linear-phase (or minimal-phase) audio frequency shaping over a specified set of taps. + +## Architecture Diagram + +```mermaid +graph LR + In[Input Frame] --> FIR[FIR Filter Engine] + Coeffs[(Filter Coefficients)] --> FIR + FIR --> Out[Output Frame] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the FIR component (`COMP_FIR`), which automatically imports `MATH_FIR` and `COMP_BLOB`. Relies on compiler capabilities to leverage DSP MAC instructions for optimal performance. +- **CMakeLists.txt**: Integrates generic and architecture-specific (`eq_fir_hifi2ep.c`, `eq_fir_hifi3.c`) files into the build, picking the correct IPC wrapper (`ipc3` or `ipc4`), and supports `llext`. +- **eq_fir.toml**: Topology parameters for the EQFIR module, defining UUIDs, memory parameters (like 4096 bytes limits) and pin layouts. +- **Topology (.conf)**: Constrained by `tools/topology/topology2/include/components/eqfir.conf`, assigning it widget type `effect` and UUID `e7:0c:a9:43:a5:f3:df:41:ac:06:ba:98:65:1a:e6:a3`. +- **MATLAB Tuning (`tune/`)**: `sof_example_fir_eq.m` utilizes the Parks-McClellan (or related) algorithms to model loudness or mid-boost curves, iterating length variables to determine optimal FIR phase behaviors. It outputs quantized binary arrays containing the calculated taps necessary for topology population. diff --git a/src/audio/eq_iir/README.md b/src/audio/eq_iir/README.md new file mode 100644 index 000000000000..6af07ceae354 --- /dev/null +++ b/src/audio/eq_iir/README.md @@ -0,0 +1,24 @@ +# IIR Equalizer Architecture + +This directory contains the Infinite Impulse Response (IIR) EQ component. + +## Overview + +IIR equalizers provide frequency shaping (like parametric EQs, shelves, high/low passes) typically using arrays of biquad filters. + +## Architecture Diagram + +```mermaid +graph LR + In[Input Frame] --> IIR[Biquad Cascade] + Coeffs[(Biquad Coefficients)] --> IIR + IIR --> Out[Output Frame] +``` + +## Configuration and Scripts + +- **Kconfig**: Activates the IIR component (`COMP_IIR`), selecting `MATH_IIR_DF1` and depending on the module adapter. +- **CMakeLists.txt**: Compiles generic logic (`eq_iir_generic.c`) and IPC-specific files depending on the Zephyr IPC configuration. +- **eq_iir.toml**: Topology parameters tailored by platform. Defines custom `mod_cfg` arrays with varying constraints based on `CONFIG_METEORLAKE` versus `CONFIG_LUNARLAKE` and ACE SOCs. +- **Topology (.conf)**: Dictated by `tools/topology/topology2/include/components/eqiir.conf`, representing an `effect` widget object with UUID `e6:c0:50:51:f9:27:c8:4e:83:51:c7:05:b6:42:d1:2f`. +- **MATLAB Tuning (`tune/`)**: `sof_example_iir_eq.m` and associated scripts can design parametric biquad presets (e.g., loudness, bass boost, bandpass, flat). These scripts compute the IIR coefficients, calculate precise scaling values, quantize mathematically, and bundle the permutations into binaries and configuration fragments suitable for SOF IPC messages. diff --git a/src/audio/google/README.md b/src/audio/google/README.md new file mode 100644 index 000000000000..feb5ce615b0a --- /dev/null +++ b/src/audio/google/README.md @@ -0,0 +1,10 @@ +# Google Custom Components Architecture + +This directory houses components specific to Google integrations, such as specialized wake-word or hotword engines. + +## Configuration and Scripts + +- **Kconfig**: Exposes menus for Google components, including `COMP_GOOGLE_HOTWORD_DETECT` (engine for hotword detection), `COMP_GOOGLE_RTC_AUDIO_PROCESSING` (acoustic echo cancellation with tunable memory size, sample rates, max channels, and reference max channels), and `COMP_GOOGLE_CTC_AUDIO_PROCESSING` (crosstalk cancellation). It also exposes mock definitions for CI testing (`COMP_STUBS`). +- **CMakeLists.txt**: Conditionally links external static libraries (`libhifi3_google_hotword_dsp_api.a`, `google_rtc_audio_processing`, `google_ctc_audio_processing`) from `third_party` tools. Defines Zephyr and non-Zephyr build pipelines. +- **google_rtc_audio_processing.toml / google_ctc_audio_processing.toml**: Specify topology module configurations for `RTC_AEC` and `CTC` models respectively with pinning mappings (like DMIC pins and playback references). +- **Topology (.conf)**: Incorporates `tools/topology/topology2/include/components/ctc.conf` (defaults to UUID `bc:1b:0e:bf:6a:dc:fe:45:bc:90:25:54:cb:13:7a:b4`) and `google-rtc-aec.conf` (defaults to UUID `a6:a0:80:b7:9f:26:6f:46:b4:77:23:df:a0:5a:f7:58`) with strict audio format channel maps (e.g. 2ch vs 4ch mappings). diff --git a/src/audio/igo_nr/README.md b/src/audio/igo_nr/README.md new file mode 100644 index 000000000000..3ab01a6a9cbc --- /dev/null +++ b/src/audio/igo_nr/README.md @@ -0,0 +1,14 @@ +# Intelligo Noise Reduction (IGO NR) Architecture + +This directory contains integration for the Intelligo Noise Reduction algorithms. + +## Overview + +IGO NR is an advanced noise suppression engine targeting microphone input paths to improve speech intelligibility. + +## Configuration and Scripts + +- **Kconfig**: Enables the Intelligo non-speech noise reduction component (`COMP_IGO_NR`), which utilizes a proprietary binary `libigonr.a`. Also provides a `COMP_IGO_NR_STUB` option for testing/CI environments that links a stub library instead of the proprietary binary. +- **CMakeLists.txt**: Handles the build integration. It either links the stub (`igo_nr_stub.c`) or the actual binary (`libigonr.a`) based on the Kconfig selection. Supports Zephyr integration module loading and standard external library compilation (`llext`). +- **igo_nr.toml**: Defines the topology parameters for the module (UUID, module_type, pin configuration, and processing constraints configured under `mod_cfg`). +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/igo_nr.conf`, it defines the `igo_nr` widget object for topology generation. Included with mixer controls binding get/put operations (`259`) and defaults to UUID `bc:e2:6a:69:77:28:eb:11:ad:c1:02:42:ac:12:00:02` (type `effect`). diff --git a/src/audio/level_multiplier/README.md b/src/audio/level_multiplier/README.md new file mode 100644 index 000000000000..278b895d099c --- /dev/null +++ b/src/audio/level_multiplier/README.md @@ -0,0 +1,14 @@ +# Level Multiplier Architecture + +This directory contains the Level Multiplier component. + +## Overview + +Applies simple digital gain/attenuation (multiplication) to an audio signal stream. + +## Configuration and Scripts + +- **Kconfig**: Enables the Level multiplier component (`COMP_LEVEL_MULTIPLIER`). This applies a configured fixed gain to an audio stream, typically to increase capture sensitivity of voice applications compared to media capture. +- **CMakeLists.txt**: Manages local base sources and optimized implementations (`level_multiplier-generic.c`, `level_multiplier-hifi3.c`, `level_multiplier-hifi5.c`). Includes the IPC version 4 wrapper (`level_multiplier-ipc4.c`) when `CONFIG_IPC_MAJOR_4` is present, and supports `llext`. +- **level_multiplier.toml**: Holds topology module entry parameters including UUIDs, standard pin layouts, and `mod_cfg` limits. +- **Topology (.conf)**: `tools/topology/topology2/include/components/level_multiplier.conf` configures the `level_multiplier` widget object. It specifies `num_input_pins` and `num_output_pins` mapping and defaults to type `effect` with UUID `56:74:39:30:61:46:44:46:97:e5:39:a9:e5:ab:17:78`. diff --git a/src/audio/mfcc/README.md b/src/audio/mfcc/README.md new file mode 100644 index 000000000000..31f9c331e545 --- /dev/null +++ b/src/audio/mfcc/README.md @@ -0,0 +1,25 @@ +# MFCC Feature Extraction Architecture + +This directory contains the Mel-Frequency Cepstral Coefficients (MFCC) feature extractor. + +## Overview + +MFCC extracts audio features commonly used as inputs for machine learning models, such as wake-word detection or speech recognition. + +## Architecture Diagram + +```mermaid +graph LR + In[Audio Frame] --> Win[Windowing] + Win --> FFT[FFT] + FFT --> Mel[Mel Filterbank] + Mel --> DCT[DCT] + DCT --> Out[MFCC Output Features] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the MFCC component (`COMP_MFCC`) which selects necessary math libraries (`MATH_FFT`, `MATH_DCT`, `MATH_16BIT_MEL_FILTERBANK`, etc.). Depends on `COMP_MODULE_ADAPTER`. +- **CMakeLists.txt**: Compiles generic, common, and HIFI implementations (`mfcc_hifi3.c`, `mfcc_hifi4.c`). Provides support for Zephyr loadable extensions (`llext`). +- **mfcc.toml**: Specifies the topology configuration for the MFCC module (UUID, affinity, memory parameters, and pin formats). +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/mfcc.conf`, configuring a `mfcc` widget object of type `effect` with UUID `73:a7:10:db:a4:1a:ea:4c:a2:1f:2d:57:a5:c9:82:eb`. diff --git a/src/audio/mic_privacy_manager/README.md b/src/audio/mic_privacy_manager/README.md new file mode 100644 index 000000000000..8d85f43e1a2b --- /dev/null +++ b/src/audio/mic_privacy_manager/README.md @@ -0,0 +1,11 @@ +# Microphone Privacy Manager Architecture + +This directory contains the Mic Privacy Manager. + +## Overview + +Provides a secure mechanism to optionally mute the microphone paths deeply inside the DSP, ensuring user privacy regardless of host OS behavior. + +## Configuration and Scripts + +- **CMakeLists.txt**: Simply builds the Intel-specific privacy implementation (`mic_privacy_manager_intel.c`). Currently, there is no generic or separate module wrapper defined within the scope of this directory. diff --git a/src/audio/mixer/README.md b/src/audio/mixer/README.md new file mode 100644 index 000000000000..eef844d0313c --- /dev/null +++ b/src/audio/mixer/README.md @@ -0,0 +1,22 @@ +# Mixer Architecture + +This directory contains the Mixer component. + +## Overview + +The Mixer adds together multiple input audio streams into a single output stream, applying required scaling or saturation logic. + +## Architecture Diagram + +```mermaid +graph TD + In1[Source 1] --> Mix[Mixer Core] + In2[Source 2] --> Mix + InN[Source N] --> Mix + Mix --> Out[Mixed Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the Mixer component (`COMP_MIXER`), which inherently depends on the older IPC framework `IPC_MAJOR_3`. +- **CMakeLists.txt**: Manages local base sources and optimized implementations (`mixer_generic.c`, `mixer_hifi3.c`) alongside the core `mixer.c`. diff --git a/src/audio/mixin_mixout/README.md b/src/audio/mixin_mixout/README.md new file mode 100644 index 000000000000..a73b39e7655b --- /dev/null +++ b/src/audio/mixin_mixout/README.md @@ -0,0 +1,14 @@ +# Mix-In / Mix-Out Architecture + +This directory provides specialized Mix-in and Mix-out instances. + +## Overview + +These components typically act as routing endpoints to inject or extract specific streams in/out of an ongoing audio mix. + +## Configuration and Scripts + +- **Kconfig**: Compiles the Mixin_mixout component (`COMP_MIXIN_MIXOUT`), which depends on the modern `IPC_MAJOR_4`. Allows choosing SIMD optimization logic explicitly. +- **CMakeLists.txt**: Integrates generic, HIFI3, and HIFI5 specialized processing source files. Fully supports modular execution via `llext`. +- **mixin_mixout.toml**: Extensive configuration separating `MIXIN` and `MIXOUT` instances. Configures UUIDs, domain types, and highly localized `mod_cfg` arrays adapted for `CONFIG_METEORLAKE`, `CONFIG_LUNARLAKE`, and ACE SOCs. +- **Topology (.conf)**: Uses `tools/topology/topology2/include/components/mixin.conf` (type `mixer` with `mix_type` `"mix_in"`, defaulting to UUID `b2:6e:65:39:71:3b:49:40:8d:3f:f9:2c:d5:c4:3c:09`, supporting 3 output pins) and `mixout.conf` (type `mixer` with `mix_type` `"mix_out"`, defaulting to UUID `5a:50:56:3c:d7:24:8f:41:bd:dc:c1:f5:a3:ac:2a:e0`, mapping to 8 input pins). Both force a 32-bit depth processing format. diff --git a/src/audio/module_adapter/README.md b/src/audio/module_adapter/README.md new file mode 100644 index 000000000000..c642c46096bd --- /dev/null +++ b/src/audio/module_adapter/README.md @@ -0,0 +1,115 @@ +# Module Adapter Architecture + +This directory contains the Module Adapter. + +## Overview + +The Module Adapter is a crucial piece of the IPC4 pipeline, allowing the core SOF graph mechanism to interact with 3rd party processing modules (like Windows APOs or customized vendor DSP engines) through a generic wrapper format. + +## Creation and Teardown Flow + +The Module Adapter wraps an external DSP processing component and translates standard SOF pipeline calls (like `comp_new`, `comp_free`, `comp_trigger`) into an interface the external module natively understands (`ops->init`, `ops->free`, `ops->reset`, etc.). + +```mermaid +sequenceDiagram + participant Pipe as Pipeline + participant ModAd as Module Adapter (module_adapter_new) + participant Mod as Processing Module + participant Ext as External DSP Module (e.g., Windows APO) + + Pipe->>ModAd: comp_new() + activate ModAd + ModAd->>ModAd: Allocates comp_dev & struct processing_module + ModAd->>ModAd: module_adapter_dp_heap_new() (If DP domain) + ModAd->>ModAd: pipeline_comp_dp_task_init() (Spins up Zephyr thread if DP) + ModAd->>Mod: module_init() + Mod->>Ext: ops->init(mod) + Ext-->>ModAd: Init OK + ModAd-->>Pipe: Component READY + deactivate ModAd + + Note over Pipe,Ext: ... Audio Streaming ... + + Pipe->>ModAd: comp_free() + activate ModAd + ModAd->>Mod: module_free() + Mod->>Ext: ops->free(mod) + ModAd->>ModAd: schedule_task_free() (terminates thread) + ModAd->>ModAd: mod_free_all() (cleans up objpool and heap) + ModAd-->>Pipe: Component Destroyed + deactivate ModAd +``` + +## Configuration and Binding Flow + +Connection establishes buffer relationships (`comp_buffer`) connecting the component sources and sinks to the rest of the generic pipeline graph. + +```mermaid +sequenceDiagram + participant Pipe as Pipeline + participant ModAd as Module Adapter + participant Mod as Processing Module + + Pipe->>ModAd: comp_bind() / comp_unbind() + activate ModAd + ModAd->>Mod: module_bind() / module_unbind() + ModAd->>ModAd: module_update_source_buffer_params() + ModAd-->>Pipe: Bind successfully mapped + deactivate ModAd + + Pipe->>ModAd: comp_prepare() + activate ModAd + ModAd->>ModAd: Calculate chunks (period bytes, deep_buff_bytes) + ModAd->>Mod: module_prepare() + Mod-->>ModAd: External DSP prepared internal states + ModAd-->>Pipe: Prepared (Buffer formats synced) + deactivate ModAd +``` + +## Processing Flow (DP and LL Execution) + +To unify components operating directly in interrupt boundaries (DMA Low Latency (LL)) with heavy computational blocks executing asynchronously in Zephyr RTOS threads (Data Processing (DP)), the wrapper intercepts `comp_copy()`. + +### Low Latency (LL) Execution + +For LL modules, processing is fully synchronous within the pipeline tick: + +1. `comp_copy()` invokes `module_adapter_copy()`. +2. Data is fetched directly into `module_process_legacy()` or `module_process_sink_src()`. +3. `ops->process()` consumes upstream arrays and produces downstream arrays. + +### Data Processing (DP) Execution + +For DP modules, a discrete Zephyr thread manages execution asynchronously: + +```mermaid +sequenceDiagram + participant Sched as LL Scheduler + participant ModAd as Module Adapter (comp_copy) + participant DP as DP Thread (dp_task_run) + participant Mod as Processing Module (Ops) + + Sched->>ModAd: comp_copy() + activate ModAd + ModAd->>ModAd: Checks source data & sink free space + ModAd->>DP: Wakeup background thread (module_adapter_process_dp) + ModAd-->>Sched: Returns (No computation done yet) + deactivate ModAd + + activate DP + DP->>Mod: module_process_sink_src() + Mod->>Mod: ops->process(sources, sinks) + Mod-->>DP: Computation Complete + DP->>Sched: Signals data is ready + deactivate DP +``` + +## Error Handling and Memory Sandboxing + +* **Sandboxing (`mod_balloc_align`, `z_impl_mod_fast_get`, `z_impl_mod_free`)**: Since third-party DSP code is treated as semi-untrusted in memory lifetimes, module allocations grab slices from a dedicated component `dp_heap_user` heap instead of the global system heap (`mod_heap_info`). The wrapper automatically prunes leaked objects (`mod_free_all(mod)`) during teardown by keeping an `objpool` of all resource containers. +* **Reset Propagation**: Re-initializations via `COMP_TRIGGER_STOP` map down to `module_reset()` clearing the runtime state of the nested DSP module back to `MODULE_INITIALIZED`. + +## Configuration and Scripts + +* **Kconfig**: Highly customizable environment for "Processing modules" (`COMP_MODULE_ADAPTER`). Provides options for memory allocations, CADENCE codecs (AAC, BSAC, DAB, DRM, MP3, SBC, VORBIS, and their associated libraries), Dolby DAX Audio processing hooks (with stub support), Waves MaxxEffect codec support, and Intel module loaders. +* **CMakeLists.txt**: Handles the sprawling linkage process for the enabled processing modules. Links the core IPC abstraction layers (`module_adapter_ipc3.c` vs `module_adapter_ipc4.c`), external static libraries directly (e.g., `libdax.a`, `libMaxxChrome.a`, arbitrary CADENCE libraries), and includes custom Zephyr build options for `IADK` and `LIBRARY_MANAGER` systems. diff --git a/src/audio/multiband_drc/README.md b/src/audio/multiband_drc/README.md new file mode 100644 index 000000000000..2a86e93ddbb6 --- /dev/null +++ b/src/audio/multiband_drc/README.md @@ -0,0 +1,27 @@ +# Multi-Band DRC Architecture + +This directory contains the Multi-Band Dynamic Range Compressor. + +## Overview + +Splits the audio into several discrete frequency bands (e.g., bass, mids, treble) and applies a separate instance of DRC to each band before remixing them. + +## Architecture Diagram + +```mermaid +graph LR + In[Audio Input] --> Splitter[Band Splitter] + Splitter --> DRC1[DRC Band 1] + Splitter --> DRC2[DRC Band 2] + DRC1 --> Sum[Mixer] + DRC2 --> Sum + Sum --> Out[Audio Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the Multiband Dynamic Range Compressor component (`COMP_MULTIBAND_DRC`). Has explicit dependencies on standard equalizers and filters: `COMP_IIR && COMP_CROSSOVER && COMP_DRC`. +- **CMakeLists.txt**: Compiles `multiband_drc.c` and generic versions, wrapping with IPC specifics (`multiband_drc_ipc3.c` or `multiband_drc_ipc4.c`). Supports Zephyr loadable extensions (`llext`). +- **multiband_drc.toml**: Defines module topology constraints and mapping (UUID `UUIDREG_STR_MULTIBAND_DRC`, module type 9). +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/multiband_drc.conf`, configuring the `multiband_drc` widget object of type `effect` (UUID `56:22:9f:0d:4f:8e:b3:47:84:48:23:9a:33:4f:11:91`). Utilizes an internal switch control for `fc`. +- **MATLAB Tuning (`tune/`)**: Features `sof_example_multiband_drc.m` to generate the complex configuration structures necessary to bind multiple EQs, crossovers, and compressors together. The scripts output the aggregated `.m4`, binary `.bin`, and ALSA `.txt` blobs which define parameter blocks for each individual sub-system active within the multiband processor. diff --git a/src/audio/mux/README.md b/src/audio/mux/README.md new file mode 100644 index 000000000000..97a5a3905b5e --- /dev/null +++ b/src/audio/mux/README.md @@ -0,0 +1,23 @@ +# Multiplexer/Demultiplexer Architecture + +This directory contains the Mux/Demux component. + +## Overview + +Selects between multiple audio paths, routing N inputs to 1 output, or 1 input to N outputs. + +## Architecture Diagram + +```mermaid +graph LR + In1[Path A] --> Mux[Path Selector] + In2[Path B] --> Mux + Mux --> Out[Selected Path] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the MUX component (`COMP_MUX`), relying on the standard `COMP_MODULE_ADAPTER`. +- **CMakeLists.txt**: Manages `mux.c` and generic code paths alongside IPC abstraction interfaces (`mux_ipc3.c`, `mux_ipc4.c`). Supports `llext` modular integration. +- **mux.toml**: Topology settings defining UUID `UUIDREG_STR_MUX4` and accommodating up to 15 concurrent instances with multiple 10-channel I/O pins. +- **Topology (.conf)**: Found at `tools/topology/topology2/include/components/muxdemux.conf`, which declares a `muxdemux` widget object. Provides flexible process typing such as `DEMUX` with type `effect` (UUID `68:68:b2:c4:30:14:0e:47:a0:89:15:d1:c7:7f:85:1a`). diff --git a/src/audio/nxp/README.md b/src/audio/nxp/README.md new file mode 100644 index 000000000000..b8a59e0256aa --- /dev/null +++ b/src/audio/nxp/README.md @@ -0,0 +1,10 @@ +# NXP Specific Components Architecture + +## Overview + +This directory contains DSP components tailored for NXP hardware acceleration or special features. + +## Configuration and Scripts + +- **Kconfig**: Manages the proprietary NXP Essential Audio Processing blocks (`COMP_NXP_EAP`), aiming to enhance tonal and spatial audio perception. Also supports testing through a stub mechanism (`COMP_NXP_EAP_STUB`). +- **CMakeLists.txt**: Configures external NXP SDK directories and intelligently links the `eap.c` wrapper either against the stub logic or the authentic `libEAP16_3_0_13_FP1_RT600.a` static library blob. diff --git a/src/audio/pcm_converter/README.md b/src/audio/pcm_converter/README.md new file mode 100644 index 000000000000..d9fd8152383a --- /dev/null +++ b/src/audio/pcm_converter/README.md @@ -0,0 +1,11 @@ +# PCM Format Converter Architecture + +This directory provides PCM format conversion. + +## Overview + +Handles conversions like 16-bit to 24-bit, interleaved to non-interleaved, and other basic PCM layout translations. + +## Configuration and Scripts + +- **CMakeLists.txt**: Organizes standard and highly performant HIFI implementations (`pcm_converter.c`, `pcm_converter_generic.c`, `pcm_converter_hifi3.c`). Includes optional support for `pcm_remap.c` dependent on the `CONFIG_PCM_REMAPPING_CONVERTERS` flag. diff --git a/src/audio/pipeline/README.md b/src/audio/pipeline/README.md new file mode 100644 index 000000000000..4e530bdc1463 --- /dev/null +++ b/src/audio/pipeline/README.md @@ -0,0 +1,245 @@ +# Pipeline Engine Architecture + +This directory contains the core graph/pipeline logic. + +## Overview + +The Pipeline engine is the heart of the SOF processing architecture. It links `components` together using `buffers`, and provides scheduling execution entities (tasks) to repeatedly trigger these component graphs. + +## Architecture Diagram + +```mermaid +graph TD + Host[Host Topology] -.-> Manager[Pipeline Manager] + Manager --> Buf1[Buffer] + Manager --> CompA[Component] + Manager --> Sched[Task Scheduler] + Sched --> CompA +``` + +## State Machine + +The pipeline progresses through various states (`COMP_STATE_INIT`, `COMP_STATE_READY`, `COMP_STATE_ACTIVE`, etc.) largely directed by `comp_trigger()` commands cascaded down the graph. + +```mermaid +stateDiagram-v2 + [*] --> INIT : pipeline_new() + INIT --> READY : pipeline_complete() + READY --> PRE_ACTIVE : COMP_TRIGGER_PRE_START + PRE_ACTIVE --> ACTIVE : COMP_TRIGGER_START + ACTIVE --> PAUSED : COMP_TRIGGER_PAUSE + PAUSED --> ACTIVE : COMP_TRIGGER_RELEASE / START + ACTIVE --> SUSPEND : COMP_TRIGGER_SUSPEND + SUSPEND --> ACTIVE : COMP_TRIGGER_RESUME + ACTIVE --> PRE_ACTIVE : COMP_TRIGGER_PRE_RELEASE + ACTIVE --> READY : COMP_TRIGGER_STOP + ACTIVE --> XRUN_PAUSED : COMP_TRIGGER_XRUN + XRUN_PAUSED --> READY : pipeline_xrun_recover() +``` + +## Processing Flow (LL and DP Modes) + +Execution within the SOF pipeline is divided between two primary timing domains depending on the component's `proc_domain` property. + +1. **Low Latency (LL) Domain:** + * **Driven By:** DMA interrupts or precise timers. + * **Execution:** A single cooperative scheduler task (`pipeline_task`) iterates over the entire connected graph. + * **Process:** The pipeline scheduler invokes `pipeline_copy()` which calls `comp_copy()` on the source or sink, and then recursively relies on `pipeline_for_each_comp` to pull or push data through the graph synchronously within that single timeslice. + +2. **Data Processing (DP) Domain:** + * **Driven By:** A Zephyr-based discrete RTOS thread (`CONFIG_ZEPHYR_DP_SCHEDULER`). + * **Execution:** Modules that require extensive computation (especially those leveraging the `module_adapter`) are spun off into their own isolated threads using `pipeline_comp_dp_task_init()`. + * **Process:** Instead of synchronous execution alongside the DMA, they consume and produce data (`module_process_sink_src`) with their own stack (`TASK_DP_STACK_SIZE`), relying on inter-component buffers and thread synchronization to pass chunks back to the LL domain when ready. + +```mermaid +sequenceDiagram + participant DMA + participant Sched as LL Scheduler (pipeline_task) + participant Source as Source Component (e.g., Host Interface) + participant Buffer as Internal Buffer + participant Filter as Filter Component (e.g., EQ) + participant Sink as Sink Component (e.g., DAI) + + DMA->>Sched: Interrupt / Timer Tick + activate Sched + Sched->>Source: pipeline_copy() -> comp_copy() + Source-->>Buffer: Copies PCM Data to Buffer + Sched->>Filter: pipeline_for_each_comp() -> comp_copy() + Filter->>Buffer: Reads PCM Data + Filter-->>Buffer: Writes Processed Data + Sched->>Sink: pipeline_for_each_comp() -> comp_copy() + Sink->>Buffer: Reads Processed Data + Sink-->>Sink: Transmits to Audio Hardware + deactivate Sched +``` + +### Mixed LL and DP Execution + +```mermaid +sequenceDiagram + participant DMA + participant Sched as LL Scheduler (pipeline_task) + participant DPThread as DP Thread (dp_task_run) + participant CompLL as LL Component + participant CompDP as DP Component + + DMA->>Sched: Interrupt / Timer Tick + activate Sched + Sched->>CompLL: pipeline_copy() -> comp_copy() + CompLL-->>Sched: Data Produced into Buffer + Sched->>DPThread: Wakeup (Buffer Data Available) + deactivate Sched + + activate DPThread + DPThread->>CompDP: module_process_sink_src() + CompDP-->>DPThread: Computations finished + DPThread->>Sched: Notification (Data Ready) + deactivate DPThread +``` + +## Control and Configuration Flows + +The lifecycle of a pipeline graph involves several discrete initialization and connection steps orchestrated by IPC topology commands before streaming begins. + +1. **Creation (`pipeline_new`)**: Instantiates the `struct pipeline` object, associates the memory heap, and grabs a mailbox offset for IPC position tracking. +2. **Connection (`pipeline_connect` / `pipeline_disconnect`)**: Establishes the directional edges of the graph by attaching a `comp_buffer` between a source and sink `comp_dev`. It updates the component's internal buffer lists. +3. **Completion (`pipeline_complete`)**: Validates the graph structure. It recursively walks the entire chain from source to sink (`pipeline_for_each_comp`), verifying consistency (e.g., ensuring components aren't part of mismatched pipelines unless properly handled), and transitions the pipeline state to `COMP_STATE_READY`. +4. **Parameter Propagation (`pipeline_params`, `pipeline_prepare`)**: Triggered prior to streaming, `pipeline_prepare()` walks the graph to finalize PCM formats, period sizes, and hardware configurations (like iterating over the audio buffers to `audio_buffer_reset_params`). +5. **Teardown (`pipeline_free`)**: When a stream is closed, after all `comp_dev` objects internal to the pipeline are halted and detached, `pipeline_free` cleans up the `pipe_task` scheduler footprint, IPC messages, and unlinks memory allocations freeing the `struct pipeline` entirely. + +### Creation and Teardown Flow + +```mermaid +sequenceDiagram + participant Host + participant Sched as LL Scheduler + participant Pipe as Pipeline + participant Source as Source Component + + Host->>Pipe: pipeline_new() + activate Pipe + Pipe-->>Pipe: Allocates struct pipeline & gets Mailbox Offset + + Host->>Source: comp_new() (Creates Components) + + Host->>Pipe: pipeline_connect() + Pipe-->>Pipe: Links comp_buffers internally + + Host->>Pipe: pipeline_complete() + Pipe->>Source: pipeline_for_each_comp() + Source-->>Pipe: Graph validates + Pipe-->>Host: Status: COMP_STATE_READY + + Note over Host,Pipe: ... Active Audio Streaming ... + + Host->>Pipe: pipeline_free() + Pipe->>Sched: schedule_task_free(pipe_task) + Pipe-->>Pipe: sof_heap_free() (Frees tracking structs) + Pipe-->>Host: Pipeline Extinguished + deactivate Pipe +``` + +### Triggering Flow + +Triggering is fundamentally responsible for transitioning graph states (`COMP_STATE_ACTIVE`, `COMP_STATE_PAUSED`, etc). A trigger (like `COMP_TRIGGER_START` or `COMP_TRIGGER_STOP`) commands an underlying state change and pushes the `pipeline_task` into the `schedule_task` queue. + +```mermaid +sequenceDiagram + participant Host + participant PPL as Pipeline (pipeline_trigger) + participant Sched as LL Scheduler (pipeline_task) + participant Source as Source Component + participant Sink as Sink Component + + Host->>PPL: pipeline_trigger(COMP_TRIGGER_START) + activate PPL + PPL->>Source: pipeline_for_each_comp(COMP_TRIGGER_START) + Source->>Sink: comp_trigger(COMP_TRIGGER_START) + Sink-->>PPL: State -> COMP_STATE_ACTIVE + + PPL->>Sched: pipeline_schedule_copy() + Sched-->>Sched: Adds `pipe_task` to active scheduler + PPL-->>Host: Trigger successful + deactivate PPL + + Note over PPL,Sched: Pipeline repeatedly scheduled via DMA or Timers + + Host->>PPL: pipeline_trigger(COMP_TRIGGER_STOP) + activate PPL + PPL->>Sched: pipeline_schedule_cancel() + Sched-->>Sched: Removes `pipe_task` from active scheduler + PPL->>Source: pipeline_for_each_comp(COMP_TRIGGER_STOP) + Source->>Sink: comp_trigger(COMP_TRIGGER_STOP) + Sink-->>PPL: State -> COMP_STATE_PAUSED / READY + PPL-->>Host: Trigger successful + deactivate PPL +``` + +```mermaid +sequenceDiagram + participant Host + participant Pipe as Pipeline (pipeline_complete) + participant Source as Source Component + participant Sink as Sink Component + participant Buf as Buffer + + Host->>Pipe: ipc_pipeline_complete() + activate Pipe + Pipe->>Source: pipeline_for_each_comp(PPL_DIR_DOWNSTREAM) + Source->>Buf: buffer_set_comp() + Buf->>Sink: comp_is_single_pipeline() + Sink-->>Pipe: Pipeline graph linked + Pipe-->>Host: Status: COMP_STATE_READY + deactivate Pipe + + Host->>Pipe: ipc_comp_prepare() + activate Pipe + Pipe->>Source: pipeline_prepare() + Source->>Buf: audio_buffer_reset_params() + Buf->>Sink: comp_prepare() + Sink-->>Pipe: Prepared formats + Pipe-->>Host: Prepared + deactivate Pipe +``` + +## Error Handling (XRUNs) + +Overruns (host writes too fast/firmware reads too slow) and underruns (host reads too fast/firmware writes too slow) are tracked continuously. + +1. **Detection**: Components directly hooked to interfaces (like a host IPC component or a hardware DAI) monitor their `comp_copy` status. If they detect starvation or overflow, they trigger an XRUN event. +2. **Propagation (`pipeline_xrun`)**: The pipeline immediately invokes a broadcast `pipeline_trigger(..., COMP_TRIGGER_XRUN)` forcing all internal components to drop to a halted `XRUN_PAUSED` state. In older IPC3 topologies, it additionally signals the host via mailbox offsets (`ipc_build_stream_posn`). +3. **Recovery (`pipeline_xrun_handle_trigger` / `pipeline_xrun_recover`)**: By default, the `pipeline_task` scheduler will intercept the `xrun_bytes` flag. Unless `NO_XRUN_RECOVERY` is defined, the firmware attempts self-healing: + * It resets the pipeline downstream of the source (`pipeline_reset`). + * It prepares it again (`pipeline_prepare`). + * It issues an internal `COMP_TRIGGER_START` to restart data flow automatically without host intervention. + +```mermaid +sequenceDiagram + participant DAI as Hardware Interface + participant Comp as Connected Component + participant PPL as Pipeline (pipeline_xrun) + participant Sched as LL Scheduler (pipeline_task) + participant Host as Host Interface + + DAI-->>Comp: Overflow/Underrun Detected + activate Comp + Comp->>PPL: pipeline_xrun() + PPL->>Comp: pipeline_trigger(COMP_TRIGGER_XRUN) + PPL-->>Host: Mailbox XRUN position (IPC3) + deactivate Comp + + Note over PPL,Sched: Pipeline halts (XRUN_PAUSED) + + Sched->>PPL: intercepts xrun_bytes > 0 + activate Sched + Sched->>PPL: pipeline_xrun_recover() + PPL->>Comp: pipeline_reset() + PPL->>Comp: pipeline_prepare() + PPL->>Comp: pipeline_trigger(COMP_TRIGGER_START) + PPL-->>Sched: Recovered (xrun_bytes = 0) + deactivate Sched +``` + +## Configuration and Scripts + +* **CMakeLists.txt**: Straightforward build configuration integrating the fundamental internal execution blocks of the SOF graph: `pipeline-graph.c`, `pipeline-stream.c`, `pipeline-params.c`, `pipeline-xrun.c`, and `pipeline-schedule.c`. diff --git a/src/audio/rtnr/README.md b/src/audio/rtnr/README.md new file mode 100644 index 000000000000..2dd6d718f15f --- /dev/null +++ b/src/audio/rtnr/README.md @@ -0,0 +1,13 @@ +# Real-Time Noise Reduction (RTNR) Architecture + +This directory houses the RTNR component. + +## Overview + +Reduces steady-state or transient background noise from an input signal path in real time. + +## Configuration and Scripts + +- **Kconfig**: Dictates the build behavior for the Realtek noise reduction and suppression components (`COMP_RTNR`). The feature depends heavily on specific, proprietary Realtek libraries (`libSOF_RTK_MA_API.a`, etc.). Configures stubs (`COMP_RTNR_STUB`) to circumvent library unavailability during testing and CI logic runs. +- **CMakeLists.txt**: Injects `rtnr.c` directly into Zephyr builds and gracefully falls back to Zephyr external libraries handling. Offers thorough `llext` generation and cleanly wraps stub testing modules `rtnr_stub.c`. +- **rtnr.toml**: Defines topology properties for the loadable RTNR logic (UUID binding, generic pinning setups). diff --git a/src/audio/selector/README.md b/src/audio/selector/README.md new file mode 100644 index 000000000000..54f09e2ba876 --- /dev/null +++ b/src/audio/selector/README.md @@ -0,0 +1,14 @@ +# Channel Selector Architecture + +This directory contains the Channel Selector component. + +## Overview + +Given a multi-channel stream (e.g., 8-channel microphone array), the channel selector component isolates specific channels (e.g., channels 1 and 2) to pass forward while dropping the rest. + +## Configuration and Scripts + +- **Kconfig**: Enables the selector component (`COMP_SEL`). +- **CMakeLists.txt**: Compiles `selector.c` and `selector_generic.c`, and natively supports Zephyr environment modules (`llext`). +- **selector.toml**: Includes topology parameters under `MICSEL`, using UUID `UUIDREG_STR_SELECTOR4` and limits up to 8 instances, with distinct `mod_cfg` limits depending on chipset architectures (Meteor Lake, Lunar Lake, ACE). +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/micsel.conf`, which defines a `micsel` widget of type `effect` (UUID `c1:92:fe:32:17:1e:c2:4f:97:58:c7:f3:54:2e:98:0a`). diff --git a/src/audio/smart_amp/README.md b/src/audio/smart_amp/README.md new file mode 100644 index 000000000000..848d7abd7b15 --- /dev/null +++ b/src/audio/smart_amp/README.md @@ -0,0 +1,23 @@ +# Smart Amplifier Architecture + +This directory contains the Smart Amp Component. + +## Overview + +Uses predictive speaker models and real-time Current/Voltage (I/V) feedback to push speakers louder without causing thermal damage or physical over-excursion. + +## Architecture Diagram + +```mermaid +graph LR + In[Audio Input] --> Proc[Protection Algorithm] + FB[I/V Sense Input] --> Proc + Model[(Speaker Parameters)] --> Proc + Proc --> Out[Safe Audio Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Enables the Smart Amplifier component (`COMP_SMART_AMP`). Features selectable architectures depending on third-party supply (defaults to `PASSTHRU_AMP`, or optionally `MAXIM_DSM` utilizing `libdsm.a`). Includes stubs for CI (`MAXIM_DSM_STUB`). +- **CMakeLists.txt**: Manages standard smart amp implementations (`smart_amp.c`, `smart_amp_generic.c`) and vendor-specific paths (`smart_amp_maxim_dsm.c`, `smart_amp_passthru.c`). Uses `zephyr_library_import` to link the Maxim SDK libraries. +- **Topology (.conf)**: Configured in `tools/topology/topology2/include/components/smart_amp.conf`, declaring a `smart_amp` effect component with UUID `1e:96:7a:16:e4:8a:ea:11:89:f1:00:0c:29:ce:16:35` (matching the test module) and hardcoding default configuration payloads into ALSA controls (`tlv_read`/`extctl`). diff --git a/src/audio/sound_dose/README.md b/src/audio/sound_dose/README.md index 2a25ad19d1ba..0436da7b886d 100644 --- a/src/audio/sound_dose/README.md +++ b/src/audio/sound_dose/README.md @@ -1,75 +1,14 @@ -Sound Dose +# Sound Dose Architecture -The purpose of this component is to calculate with DSP offload the -headphone audio playback MEL values (momentary sound exposure level). -The calculated MEL values are notified to user space to be available -every one second. The user space should respond to notification with -bytes control get to get the data. The MEL values are used to -calculate the CSD value (cumulative sound dose). Low enough CSD value -ensures the music listening is safe the user's hearing. +This directory contains the Sound Dose component. -The calculation of MEL values and CSD values is defined in EN 50332-3 -stadard. The implementation in the Android OS is described in -https://source.android.com/docs/core/audio/sound-dose . +## Overview -The SOF Sound Dose component should be placed in topology as last -component before playback dai-copier. +Monitors the acoustic energy output to headphones over time, ensuring it complies with regulations governing maximum cumulative sound exposure (to protect user hearing). -Currently it can be tested with next test topologies: -- sof-hda-benchmark-sound_dose32.tplg -- sof-mtl-sdw-benchmark-sound_dose32-sdw0.tplg -- sof-mtl-sdw-benchmark-sound_dose32-simplejack.tplg +## Configuration and Scripts -E.g. in the sdw topologies the controls for setting it up can be -seen with command: - -$ amixer -c0 controls | grep "Jack Out Sound Dose" -numid=33,iface=MIXER,name='Jack Out Sound Dose data bytes' -numid=32,iface=MIXER,name='Jack Out Sound Dose gain bytes' -numid=30,iface=MIXER,name='Jack Out Sound Dose setup bytes' -numid=31,iface=MIXER,name='Jack Out Sound Dose volume bytes' - -The above topologies program the setup bytes for acoustical -sensitivity of acoustical 100 dBSPL for 0 dBFS digital level. -The gain is set to 0 dB and volume to 0 dB. - -To test the basics copy a compatible test topology over the -normal topology file. Or alternative use module options -tplg_filename and tplg_path for module snd_sof. - -Get kcontrol_events from https://github.com/ujfalusi/kcontrol_events -and build and install it. - -Start playback of some music or test signal. Note that there is no SOF -volume control component in the test topology, so it plays out at max -volume. - -Start in other console kcontrol_events. The control 'Jack Out Sound -Dose data bytes' should get updates every one second. The structures -are defined in src/include/user/audio_feature.h and -src/include/user/sound_dose.h. - -The next steps require build of blobs for sof-ctl. The blobs can be -rebuilt with command - -cd src/audio/sound_dose/tune; octave --quiet --no-window-system sof_sound_dose_blobs.m - -To simulate effect of initial sensitivity setup, try command - -sof-ctl -c name='Jack Out Sound Dose setup bytes' -s /sound_dose/setup_sens_0db.txt -sof-ctl -c name='Jack Out Sound Dose setup bytes' -s /sound_dose/setup_sens_100db.txt - -To simulate adjusting codec volume control down 10 dB and up again 10 dB - -sof-ctl -c name='Jack Out Sound Dose volume bytes' -s ctl4/sound_dose/setup_vol_-10db.txt -sof-ctl -c name='Jack Out Sound Dose volume bytes' -s ctl4/sound_dose/setup_vol_0db.txt - -To force user's listening level 10 dB down after observing too large dose per the MSD value - -sof-ctl -c name='Jack Out Sound Dose gain bytes' -s ctl4/sound_dose/setup_gain_-10db.txt - -To restore user's listening level to non-attenuated - -sof-ctl -c name='Jack Out Sound Dose gain bytes' -s ctl4/sound_dose/setup_gain_0db.txt - -The above commands have impact to data shown by kcontrol_events. +- **Kconfig**: Dictates the Sound Dose component (`COMP_SOUND_DOSE`) with prerequisites on `IPC_MAJOR_4` and `COMP_MODULE_ADAPTER`, plus mathematical modules (`MATH_EXP`, `MATH_IIR`). +- **CMakeLists.txt**: Compiles generic operations (`sound_dose-generic.c`, `sound_dose.c`) alongside their IPC wrappers (`sound_dose-ipc4.c`), offering full `llext` enablement. +- **sound_dose.toml**: Contains topology descriptors, declaring UUID `UUIDREG_STR_SOUND_DOSE` and standard memory allocation bounds. +- **Topology (.conf)**: Extracted from `tools/topology/topology2/include/components/sound_dose.conf`, configuring a `sound_dose` widget of type `effect` (UUID `7c:9d:3f:a4:75:ea:d5:44:94:2d:96:79:91:a3:38:09`). diff --git a/src/audio/src/README.md b/src/audio/src/README.md new file mode 100644 index 000000000000..0cb434a67b81 --- /dev/null +++ b/src/audio/src/README.md @@ -0,0 +1,23 @@ +# Synchronous Sample Rate Converter (SRC) Architecture + +This directory contains the Synchronous SRC implementation. + +## Overview + +Converts sample rates by an exact, locked integer or fractional ratio (e.g., 48 kHz to 44.1 kHz) using a polyphase filter bank. + +## Architecture Diagram + +```mermaid +graph LR + In[48kHz Stream] --> SRC[Polyphase FIR Interpolator] + SRC --> Out[44.1kHz Stream] +``` + +## Configuration and Scripts + +- **Kconfig**: Extensive options for `COMP_SRC`, determining conversion quality targets and memory consumption limitations: standard (`COMP_SRC_STD`), small (`COMP_SRC_SMALL`), and tiny (`COMP_SRC_TINY`) filter sets. Alternatively targets IPC4 full conversions (`COMP_SRC_IPC4_FULL_MATRIX`), and supports lite conversions (`COMP_SRC_LITE`). +- **CMakeLists.txt**: Wraps numerous internal source implementations spanning multiple SIMD platforms (`src_hifi2ep.c`, `src_hifi3.c`, `src_hifi4.c`, `src_hifi5.c`) and connects the required IPC APIs. Allows Zephyr out-of-tree loader configurations (`llext`). +- **src.toml**: Declares massive topology limits under `mod_cfg` per chipset to enforce correct processing behavior of varied rate conversions internally, specifying `UUIDREG_STR_SRC4` and `UUIDREG_STR_SRC_LITE`. +- **Topology (.conf)**: Instantiated via `tools/topology/topology2/include/components/src.conf`, utilizing `rate_in` and `rate_out` attributes to specify integer transformations. Associates as a `src` widget type with UUID `8d:b2:1b:e6:9a:14:1f:4c:b7:09:46:82:3e:f5:f5:ae`. +- **MATLAB Tuning (`tune/`)**: Houses heavily comprehensive scripts like `sof_src_generate.m` which compute optimal polyphase filter bank coefficients for a massive grid of supported input-to-output fractional sample rate conversions. The scripts export these fixed-point (or float) arrays as C header data structs (`.h` code outputs) allowing the DSP to pull static transition parameters depending on memory (`std`, `small`, `tiny`, `lite`) profiles. diff --git a/src/audio/stft_process/README.md b/src/audio/stft_process/README.md new file mode 100644 index 000000000000..074b2c0cf331 --- /dev/null +++ b/src/audio/stft_process/README.md @@ -0,0 +1,14 @@ +# STFT Process Architecture + +This directory provides Short-Time Fourier Transform (STFT) utilities. + +## Overview + +Converts time-domain audio slices into the frequency domain using FFTs, runs frequency-domain processing over those bins, and applies the inverse-STFT (Overlap-Add) back to the time-domain. + +## Configuration and Scripts + +- **Kconfig**: Manages the STFT processing component (`COMP_STFT_PROCESS`) and requires multi-channel 32-bit FFT math libraries (`MATH_FFT`, `MATH_32BIT_FFT`, `MATH_FFT_MULTI`). Also optionally supports converting pure FFTs into polar magnitude and phase domains (`STFT_PROCESS_MAGNITUDE_PHASE`). +- **CMakeLists.txt**: Compiles generic STFT operations (`stft_process.c`, `stft_process_common.c`, `stft_process-generic.c`) and IPC4 wrappers (`stft_process-ipc4.c`), fully supporting the `llext` format. +- **stft_process.toml**: Defines the default `STFTPROC` module layout with UUID `UUIDREG_STR_STFT_PROCESS`. +- **Topology (.conf)**: Instantiated from `tools/topology/topology2/include/components/stft_process.conf`, creating a `stft_process` widget type `effect` (UUID `a6:6e:11:0d:50:91:de:46:98:b8:b2:b3:a7:91:da:29`). diff --git a/src/audio/tdfb/README.md b/src/audio/tdfb/README.md new file mode 100644 index 000000000000..cf3bc13dbe2d --- /dev/null +++ b/src/audio/tdfb/README.md @@ -0,0 +1,15 @@ +# Time Domain Filter Bank Architecture + +This directory contains the TDFB component. + +## Overview + +Generally used for operations like beamforming or highly directional microphone array processing in the time domain. + +## Configuration and Scripts + +- **Kconfig**: Manages the Time Domain Fixed Beamformer component (`COMP_TDFB`), requiring generic `COMP_MODULE_ADAPTER` integration along with high-precision math packages (`MATH_FIR`, `MATH_IIR_DF1`, `SQRT_FIXED`, `CORDIC_FIXED`). +- **CMakeLists.txt**: Builds the standard source set (`tdfb.c`, `tdfb_generic.c`, `tdfb_hifiep.c`, `tdfb_hifi3.c`, `tdfb_direction.c`) handling generic and HIFI implementations alongside IPC abstractions (`tdfb_ipc3.c`, `tdfb_ipc4.c`). Inherits out-of-tree loader (`llext`) generation. +- **tdfb.toml**: Generates ALSA properties mapping the component to `UUIDREG_STR_TDFB`. +- **Topology (.conf)**: Instantiated from `tools/topology/topology2/include/components/tdfb.conf`, creating a `tdfb` widget type `effect` (UUID `49:17:51:dd:fa:d9:5c:45:b3:a7:13:58:56:93:f1:af`). Provides multiple internal mixer controls spanning phase/direction toggles. +- **MATLAB Tuning (`tune/`)**: `sof_example_circular_array.m` and similar array topology scripts define spatial setups (e.g., circular, linear, L-shape, rectangular). They take microphone layout coordinates, compute beamforming angles (azimuth/elevation) and delays, and pack them into binary configuration blobs allowing microphones to "steer" their listening direction interactively. diff --git a/src/audio/template/README.md b/src/audio/template/README.md new file mode 100644 index 000000000000..93e48c80f2cc --- /dev/null +++ b/src/audio/template/README.md @@ -0,0 +1,14 @@ +# Template Component Architecture + +This directory contains template code. + +## Overview + +Provides a reference or stub implementation that developers can copy and modify to easily construct new custom audio components. + +## Configuration and Scripts + +- **Kconfig**: Exposes the `COMP_TEMPLATE` toggle to build the baseline framework plugin (internally swaps or reverses channels). +- **CMakeLists.txt**: Compiles generic operations (`template.c`, `template-generic.c`) and connects via either IPC major version. Generates a Zephyr `llext` by default. +- **template.toml**: Includes default setup arguments and UUID bindings (`UUIDREG_STR_TEMPLATE`). +- **Topology (.conf)**: Defined in `tools/topology/topology2/include/components/template_comp.conf`, registering the `template_comp` widget of type `effect` (UUID `af:e1:2d:a6:64:59:2e:4e:b1:67:7f:dc:97:27:9a:29`). diff --git a/src/audio/tensorflow/README.md b/src/audio/tensorflow/README.md index 07c9089afb4c..a8e3f59ba3ce 100644 --- a/src/audio/tensorflow/README.md +++ b/src/audio/tensorflow/README.md @@ -1,34 +1,22 @@ -# SOF Tensorflow Micro Integration +# TensorFlow Lite Micro (TFLM) Architecture -The TFLM module integrates tensorflow micro into SOF as an audio classifiction and in the future an audio processing module. This module is currently still work in progress, and needs a few features to be completed before its ready for production. +This directory acts as the bridge for running ML models. -## Building +## Overview -Please run ```./scripts/tensorflow-clone.sh``` before building as this will clone all dependencies required to build tensor flow micro with optimized xtensa kernels. +Integrates TensorFlow Lite for Microcontrollers into the SOF audio pipeline. Evaluates pre-trained neural network topologies inline with the audio stream for tasks like wake-word, noise cancellation, or sound classification. -Please select the following in Kconfig -``` -CONFIG_CPP=y -CONFIG_STD_CPP17=y -CONFIG_SOF_STAGING=y -``` - -To build as built-in, select ```CONFIG_COMP_TENSORFLOW=y``` in Kconfig and build. - -To build as a llext module, select ```CONFIG_COMP_TENSORFLOW=m``` in Kconfig and the build. - -## Running +## Architecture Diagram -The TFLM SOF module needs features created by the MFCC module as its input. This step is still in progress. The following pipeline will be used - -``` Mic --> MFCC --> TFLM --> Classification ``` - -## TODO - -1) Create MFCC pipeline and align with TFLM micro_speech audio feature extraction configuration. - -2) Support compressed output PCM with Classification results. +```mermaid +graph LR + Feat[Audio Features] --> TFLM[TFLM Inference Engine] + SubGraph[FlatBuffer Model] -.-> TFLM + TFLM --> Out[Inference Labels/Scores] +``` -3) Load tflite models via binary kcontrol. +## Configuration and Scripts -4) Support audio processing via TFLM module. \ No newline at end of file +- **Kconfig**: Enforces requirements for C++17 support and core framework staging logic (`COMP_TENSORFLOW`). +- **CMakeLists.txt**: An intricate build specification linking the Tensilica neural network library block computations (`nn_hifi_lib`) and the TensorFlow Lite micro core engine (`tflm_lib`). Also hooks the `tflm-classify.c` SOF adapter via compiler flags explicitly enforcing memory, precision, and XTENSA optimizations. +- **tflmcly.toml**: Topology definition for the specific TFLM Classifier implementation binding the engine against the UUID `UUIDREG_STR_TFLMCLY`. diff --git a/src/audio/tone/README.md b/src/audio/tone/README.md new file mode 100644 index 000000000000..e2435c2e2b3a --- /dev/null +++ b/src/audio/tone/README.md @@ -0,0 +1,13 @@ +# Tone Generator Architecture + +This directory contains the Tone component. + +## Overview + +Synthesizes simple sine-waves or beep sequences, generally used for internal testing, diagnostics, or system alert sounds. + +## Configuration and Scripts + +- **Kconfig**: Controls compilation inclusion via `COMP_TONE` acting securely on top of the generic `COMP_MODULE_ADAPTER` and `IPC_MAJOR_4`. Depends on the `CORDIC_FIXED` library for sine approximations. +- **CMakeLists.txt**: Links `tone.c` to respective system-level pipelines (`tone-ipc3.c` or `tone-ipc4.c`) and allows execution seamlessly as a zephyr `llext`. +- **tone.toml**: Describes module structure mappings assigning `UUIDREG_STR_TONE` up to multi-instance capacities. diff --git a/src/audio/up_down_mixer/README.md b/src/audio/up_down_mixer/README.md new file mode 100644 index 000000000000..723d5cc609fc --- /dev/null +++ b/src/audio/up_down_mixer/README.md @@ -0,0 +1,13 @@ +# Up/Down Mixer Architecture + +This directory contains the Up/Down channel mixer. + +## Overview + +Converts the spatial format of audio (e.g., Stereo up to 5.1 surround, or 5.1 mixed down to Stereo) natively. + +## Configuration and Scripts + +- **Kconfig**: Enabled via `COMP_UP_DOWN_MIXER`, specifically tuned for `IPC_MAJOR_4`. Supports heavy format transformations up to 7.1 endpoints. +- **CMakeLists.txt**: Implements the base `up_down_mixer.c` component along with highly-optimized architecture primitives (`up_down_mixer_hifi3.c`). +- **up_down_mixer.toml**: Robust configuration map controlling `UPDWMIX` deployment against variable system arrays depending on Meteor Lake, Lunar Lake, or ACE platform parameters (UUID binding `UUIDREG_STR_UP_DOWN_MIXER`). diff --git a/src/audio/volume/README.md b/src/audio/volume/README.md new file mode 100644 index 000000000000..c044d73fd11d --- /dev/null +++ b/src/audio/volume/README.md @@ -0,0 +1,24 @@ +# Volume Component Architecture + +This directory contains the Volume control component. + +## Overview + +Applies amplitude modifications to the stream, supporting smooth ramping and muting interfaces configurable by the host. + +## Architecture Diagram + +```mermaid +graph LR + In[Audio Input] --> Mult[Multiplier] + IPC[IPC Control] -.-> Ramp[Ramp Generator] + Ramp --> Mult + Mult --> Out[Audio Output] +``` + +## Configuration and Scripts + +- **Kconfig**: Extensive tuning for the standard volume framework (`COMP_VOLUME`), selecting underlying algorithms (e.g., `COMP_VOLUME_WINDOWS_FADE`, `COMP_VOLUME_LINEAR_RAMP`). Manages sub-settings like querying host telemetry (`COMP_PEAK_VOL`, `PEAK_METER_UPDATE_PERIOD_CHOICE`). +- **CMakeLists.txt**: Extremely versatile linkage resolving general pathways (`volume_generic.c`), custom optimized builds across HIFI pipelines (`volume_hifi3.c`, `volume_hifi4.c`, `volume_hifi5.c`), and dual-path execution logic (`*_with_peakvol.c`). +- **volume.toml**: Registers independent modules `PEAKVOL` (`UUIDREG_STR_VOLUME4`) and `GAIN` (`UUIDREG_STR_GAIN`), outlining explicit memory mapping parameters via platform-dependent constraints. +- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/volume.conf`, configuring a standard `pga` widget (UUID `7e:67:7e:b7:f4:5f:88:41:af:14:fb:a8:bd:bf:86:82`). Outlines parameters for ramp steps interpolation methods and binds specific ALSA interface elements. diff --git a/src/include/Readme.md b/src/include/README.md similarity index 100% rename from src/include/Readme.md rename to src/include/README.md