readme: add readme for each audio directory

Add a high level readme describing each audio directory to help
new users understand what each modules does.

This large patch of high level text that can be a starting point
for further refinement by module authors.

Author: lrgirdwo

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.

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`).

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`.

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`.

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`.

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`.

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.

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.

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).

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.