diff --git a/tools/topology/README.md b/tools/topology/README.md new file mode 100644 index 000000000000..d7403b2bdfb9 --- /dev/null +++ b/tools/topology/README.md @@ -0,0 +1,22 @@ +# SOF Topology Tools (`tools/topology`) + +The `tools/topology` directory contains the build infrastructure and source files used to generate Advanced Linux Sound Architecture (ALSA) topology (`.tplg`) binaries for Sound Open Firmware. + +ALSA topology files describe the audio DSP graph (pipelines, widgets, routes, DAIs) and are loaded dynamically by the Linux kernel SOF driver during initialization. This allows a single generic driver to support a wide variety of hardware configurations and routing paths without requiring source code changes in the kernel. + +## Directory Structure + +To support the evolution of the SOF topology syntax, the configuration files are split into two main versions: + +- [`topology1/`](topology1/README.md): Contains the legacy (v1) `m4`-based ALSA topology generation scripts and configuration files. Topology 1 heavily relies on `m4` macro preprocessing to generate the final `.conf` files before being compiled by `alsatplg`. +- [`topology2/`](topology2/README.md): Contains the newer (v2) ALSA topology generation files. Topology 2 introduces a more structured, object-oriented syntax natively supported by newer versions of the `alsatplg` compiler (specifically the pre-processor `-p` flag), reducing reliance on external macro languages. + +## Build Process + +The topology build process is managed by `CMakeLists.txt` in this root directory. It performs the following key steps: + +1. **Compiler Detection**: It locates the `alsatplg` tool (usually built in `tools/bin/alsatplg` alongside the firmware) and checks its version. +2. **Feature Validation**: It ensures the `alsatplg` version is at least `1.2.5`. Older versions are known to silently corrupt certain topology structures (e.g., converting `codec_consumer` to `codec_master`). If the tool is too old, topology generation is safely skipped with a warning. +3. **Target Generation**: It provides macros (`add_alsatplg_command` and `add_alsatplg2_command`) used by the subdirectories to invoke the topology compiler on the pre-processed `.conf` files to generate the final `.tplg` binaries. + +The `topologies` CMake target is the master target that depends on the generation targets inside both `topology1` and `topology2`. diff --git a/tools/topology/topology1/README.md b/tools/topology/topology1/README.md new file mode 100644 index 000000000000..78253bb06ee2 --- /dev/null +++ b/tools/topology/topology1/README.md @@ -0,0 +1,86 @@ +# ALSA Topology v1 (`tools/topology/topology1`) + +This directory contains the source files and `m4` macros used to generate version 1 of the ALSA topology binary files (`.tplg`) for Sound Open Firmware. + +## Overview + +Topology v1 relies heavily on the `m4` macro processor to handle the complexity and reusability of DSP graph definitions. Because raw ALSA configuration files for complex audio routing can become extremely verbose and repetitive, SOF uses `m4` to define logical blocks (like DAIs, SSPs, pipelines, and volume controls) that can be easily instantiated and connected. + +## Structure + +The core generation components include: + +- **`m4/`**: This directory contains the foundational macro definitions. These macros define how base elements like widgets (e.g., `PGA`, `Mixer`, `SRC`), pipelines, and routing paths are constructed in the ALSA `.conf` format. +- **`common/`**: Contains shared components and standard pipeline definitions that are reused across multiple different hardware platforms. +- **`platform/`**: Contains macros and configurations specific to individual hardware architectures (e.g., Intel cAVS, IMX). +- **Platform `.m4` files**: At the root of `topology1`, there are numerous `.m4` files (e.g., `sof-cavs-nocodec.m4`, `sof-imx8-wm8960.m4`). These are the top-level files that instantiate the macros to build a complete topology graph for a specific board or hardware configuration. + +## Component Assembly + +Building a topology in v1 is essentially a process of calling nested `m4` macros to piece together the DSP pipeline. Here's how the ingredients combine: + +1. **Base Macros (`m4/`)**: Define the raw ALSA syntax for things like a single PGA volume control or a DAI link. +2. **Pipelines (`common/`)**: Define a logical sequence of base widgets. For example, a "Playback Pipeline" macro might chain together a Host PCM, a Buffer, a Volume Control (PGA), and an output Buffer. +3. **Top-Level File (`*.m4`)**: Instantiates the pipelines, defines the physical DAI hardware connections, and sets up routing lines between the pipelines and the DAIs. + +```mermaid +graph TD + subgraph "Base Ingredients (m4/)" + A[Widget: PCM] + B[Widget: PGA Volume] + C[Widget: DAI] + D[Widget: Mixer] + end + + subgraph "Recipes (common/ & platform/)" + P1[Playback Pipeline] + P1 -.->|Includes| A + P1 -.->|Includes| B + + P2[Capture Pipeline] + P2 -.->|Includes| D + P2 -.->|Includes| C + end + + subgraph "The Meal (sof-board.m4)" + Top[Top-Level Topology] + Top ==>|Instantiates| P1 + Top ==>|Instantiates| P2 + Top ==>|Defines| Routes[Audio Routes] + Routes -.->|Connects Pipeline to DAI| Top + end +``` + +## Build Flow + +### Architecture Diagram + +```mermaid +flowchart TD + m4_core(["m4/ (Core Macros)"]) -.-> m4_plat(["platform/ (Platform Macros)"]) + m4_comp(["common/ (Shared Components)"]) -.-> m4_plat + + m4_plat -.-> m4_top(["sof-*.m4 (Top-level Platform File)"]) + + m4_top -->|"m4 processor"| conf["ALSA .conf Output"] + + conf -->|"alsatplg"| tplg["ALSA .tplg Binary"] +``` + +When the SOF build system compiles a v1 topology: + +1. The `m4` processor takes a top-level platform `.m4` file. +2. It expands all the macros defined in `m4/`, `common/`, and `platform/`. +3. The output is a raw ALSA `.conf` text file. +4. The `alsatplg` compiler parses this `.conf` file and compiles it into the final `.tplg` binary format loaded by the kernel. + +### Build Instructions + +Topologies are built automatically as part of the standard SOF CMake build process. To explicitly build all topologies (including v1): + +```bash +# From your build directory: +make topologies1 +# OR +cmake --build . --target topologies1 +``` diff --git a/tools/topology/topology2/README.md b/tools/topology/topology2/README.md new file mode 100644 index 000000000000..db03ab39e5af --- /dev/null +++ b/tools/topology/topology2/README.md @@ -0,0 +1,92 @@ +# ALSA Topology v2 (`tools/topology/topology2`) + +This directory contains the ALSA Topology 2.0 source files for Sound Open Firmware. + +## Overview + +Topology 2.0 (Topology v2) is a modernization of the ALSA topology infrastructure. It aims to solve the verbosity and complexity issues of Topology v1 without relying as heavily on external macro processors like `m4`. + +Topology v2 introduces an object-oriented pre-processing layer directly into the newer `alsatplg` compiler (invoked via the `-p` flag). This allows the configuration files to define classes, objects, and attributes natively within the ALSA configuration syntax. + +## Key Advantages + +- **Object-Oriented Syntax**: Topology v2 allows for the definition of classes (`Class.Widget`, `Class.Pipeline`) and object instantiation, making the topology files much easier to read, maintain, and extend. +- **Reduced Pre-Processing**: By handling templating and instantiation inside the `alsatplg` tool itself, the build process is cleaner and errors are easier to trace back to the source files, as opposed to deciphering expanded `m4` output. +- **Dynamic Variables**: Attributes can be parameterized and passed down to nested objects, allowing for highly flexible definitions of audio pipelines. + +## Structure and Component Assembly + +Topology v2 shifts the source code layout from macro definitions to class definitions, leveraging the structured nature of the newer compiler. + +The directory is built around these core parts: + +- **`include/`**: Contains the base ALSA topology class definitions. + - `components/`: Base classes for individual processing nodes (e.g., PGA, Mixer, SRC). + - `pipelines/`: Reusable pipeline class definitions that instantiate and connect several base components. + - `dais/`: Definitions for Digital Audio Interfaces (hardware endpoints). + - `controls/`: Definitions for volume, enum, and byte controls. +- **`platform/`**: Hardware-specific configurations and overrides (e.g., Intel-specific IPC attributes). +- **Top-Level `.conf` files**: The board-specific configurations (e.g., `cavs-rt5682.conf`). These behave like standard ALSA `.conf` files but utilize the `@include` directive to import classes and instantiate them dynamically. + +```mermaid +graph TD + subgraph "Class Definitions (include/)" + C_Comp[Class: components/pga.conf] + C_Pipe[Class: pipelines/volume-playback.conf] + C_DAI[Class: dais/ssp.conf] + end + + subgraph "Pipeline Object" + C_Pipe -.->|Instantiates| C_Comp + end + + subgraph "Top-Level Topology (board.conf)" + Board[cavs-board.conf] + Board -->|"@include"| C_Pipe + Board -->|"@include"| C_DAI + + Obj_Pipe[Object.Pipeline.volume-playback.1] + Obj_DAI[Object.Dai.SSP.1] + + Board -.->|Instantiates| Obj_Pipe + Board -.->|Instantiates| Obj_DAI + + Routes[Object.Base.route] + Board -.->|Connects Objects| Routes + end +``` + +## Architecture and Build Flow + +Unlike v1, Topology 2 processes objects and classes within the `alsatplg` compiler itself. + +### Diagram + +```mermaid +flowchart TD + conf_classes(["Class Definitions (.conf)"]) -.-> conf_objs(["Object Instantiations (.conf)"]) + + conf_objs -->|"alsatplg -p (Pre-processor Engine)"| tplg["ALSA .tplg Binary"] + + subgraph alsatplg_internal [alsatplg Internal Processing] + direction TB + parse["Parse Classes & Objects"] --> resolve["Resolve Attributes"] + resolve --> validate["Validate Topologies"] + end + + conf_objs -.-> alsatplg_internal + alsatplg_internal -.-> tplg +``` + +When building a v2 topology, the `CMakeLists.txt` in `tools/topology/` provides the `add_alsatplg2_command` macro. This macro specifically passes the `-p` flag to `alsatplg`, instructing it to use the new pre-processor engine to resolve the classes and objects defined in the `.conf` files before compiling them into the `.tplg` binary. + +### Build Instructions + +Topologies are built automatically as part of the standard SOF CMake build process. To explicitly build Topology 2 configurations: + +```bash +# From your build directory: +make topologies2 +# OR +cmake --build . --target topologies2 +```