Skip to content

Commit 4bd78d1

Browse files
lrgirdwolrgirdwo
committed
readme: Add readme for topology 1 & 2
Add some high level descriptiond of topology 1 & 2 Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
1 parent 9ee2d5d commit 4bd78d1

File tree

3 files changed

+200
-0
lines changed

3 files changed

+200
-0
lines changed

‎tools/topology/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# SOF Topology Tools (`tools/topology`)
2+
3+
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.
4+
5+
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.
6+
7+
## Directory Structure
8+
9+
To support the evolution of the SOF topology syntax, the configuration files are split into two main versions:
10+
11+
- [`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`.
12+
- [`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.
13+
14+
## Build Process
15+
16+
The topology build process is managed by `CMakeLists.txt` in this root directory. It performs the following key steps:
17+
18+
1. **Compiler Detection**: It locates the `alsatplg` tool (usually built in `tools/bin/alsatplg` alongside the firmware) and checks its version.
19+
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.
20+
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.
21+
22+
The `topologies` CMake target is the master target that depends on the generation targets inside both `topology1` and `topology2`.

‎tools/topology/topology1/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# ALSA Topology v1 (`tools/topology/topology1`)
2+
3+
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.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Structure
10+
11+
The core generation components include:
12+
13+
- **`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.
14+
- **`common/`**: Contains shared components and standard pipeline definitions that are reused across multiple different hardware platforms.
15+
- **`platform/`**: Contains macros and configurations specific to individual hardware architectures (e.g., Intel cAVS, IMX).
16+
- **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.
17+
18+
## Component Assembly
19+
20+
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:
21+
22+
1. **Base Macros (`m4/`)**: Define the raw ALSA syntax for things like a single PGA volume control or a DAI link.
23+
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.
24+
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.
25+
26+
```mermaid
27+
graph TD
28+
subgraph "Base Ingredients (m4/)"
29+
A[Widget: PCM]
30+
B[Widget: PGA Volume]
31+
C[Widget: DAI]
32+
D[Widget: Mixer]
33+
end
34+
35+
subgraph "Recipes (common/ & platform/)"
36+
P1[Playback Pipeline]
37+
P1 -.->|Includes| A
38+
P1 -.->|Includes| B
39+
40+
P2[Capture Pipeline]
41+
P2 -.->|Includes| D
42+
P2 -.->|Includes| C
43+
end
44+
45+
subgraph "The Meal (sof-board.m4)"
46+
Top[Top-Level Topology]
47+
Top ==>|Instantiates| P1
48+
Top ==>|Instantiates| P2
49+
Top ==>|Defines| Routes[Audio Routes]
50+
Routes -.->|Connects Pipeline to DAI| Top
51+
end
52+
```
53+
54+
## Build Flow
55+
56+
### Architecture Diagram
57+
58+
```mermaid
59+
flowchart TD
60+
m4_core(["m4/ (Core Macros)"]) -.-> m4_plat(["platform/ (Platform Macros)"])
61+
m4_comp(["common/ (Shared Components)"]) -.-> m4_plat
62+
63+
m4_plat -.-> m4_top(["sof-*.m4 (Top-level Platform File)"])
64+
65+
m4_top -->|"m4 processor"| conf["ALSA .conf Output"]
66+
67+
conf -->|"alsatplg"| tplg["ALSA .tplg Binary"]
68+
```
69+
70+
When the SOF build system compiles a v1 topology:
71+
72+
1. The `m4` processor takes a top-level platform `.m4` file.
73+
2. It expands all the macros defined in `m4/`, `common/`, and `platform/`.
74+
3. The output is a raw ALSA `.conf` text file.
75+
4. The `alsatplg` compiler parses this `.conf` file and compiles it into the final `.tplg` binary format loaded by the kernel.
76+
77+
### Build Instructions
78+
79+
Topologies are built automatically as part of the standard SOF CMake build process. To explicitly build all topologies (including v1):
80+
81+
```bash
82+
# From your build directory:
83+
make topologies1
84+
# OR
85+
cmake --build . --target topologies1
86+
```

‎tools/topology/topology2/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# ALSA Topology v2 (`tools/topology/topology2`)
2+
3+
This directory contains the ALSA Topology 2.0 source files for Sound Open Firmware.
4+
5+
## Overview
6+
7+
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`.
8+
9+
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.
10+
11+
## Key Advantages
12+
13+
- **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.
14+
- **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.
15+
- **Dynamic Variables**: Attributes can be parameterized and passed down to nested objects, allowing for highly flexible definitions of audio pipelines.
16+
17+
## Structure and Component Assembly
18+
19+
Topology v2 shifts the source code layout from macro definitions to class definitions, leveraging the structured nature of the newer compiler.
20+
21+
The directory is built around these core parts:
22+
23+
- **`include/`**: Contains the base ALSA topology class definitions.
24+
- `components/`: Base classes for individual processing nodes (e.g., PGA, Mixer, SRC).
25+
- `pipelines/`: Reusable pipeline class definitions that instantiate and connect several base components.
26+
- `dais/`: Definitions for Digital Audio Interfaces (hardware endpoints).
27+
- `controls/`: Definitions for volume, enum, and byte controls.
28+
- **`platform/`**: Hardware-specific configurations and overrides (e.g., Intel-specific IPC attributes).
29+
- **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.
30+
31+
```mermaid
32+
graph TD
33+
subgraph "Class Definitions (include/)"
34+
C_Comp[Class: components/pga.conf]
35+
C_Pipe[Class: pipelines/volume-playback.conf]
36+
C_DAI[Class: dais/ssp.conf]
37+
end
38+
39+
subgraph "Pipeline Object"
40+
C_Pipe -.->|Instantiates| C_Comp
41+
end
42+
43+
subgraph "Top-Level Topology (board.conf)"
44+
Board[cavs-board.conf]
45+
Board -->|"@include"| C_Pipe
46+
Board -->|"@include"| C_DAI
47+
48+
Obj_Pipe[Object.Pipeline.volume-playback.1]
49+
Obj_DAI[Object.Dai.SSP.1]
50+
51+
Board -.->|Instantiates| Obj_Pipe
52+
Board -.->|Instantiates| Obj_DAI
53+
54+
Routes[Object.Base.route]
55+
Board -.->|Connects Objects| Routes
56+
end
57+
```
58+
59+
## Architecture and Build Flow
60+
61+
Unlike v1, Topology 2 processes objects and classes within the `alsatplg` compiler itself.
62+
63+
### Diagram
64+
65+
```mermaid
66+
flowchart TD
67+
conf_classes(["Class Definitions (.conf)"]) -.-> conf_objs(["Object Instantiations (.conf)"])
68+
69+
conf_objs -->|"alsatplg -p (Pre-processor Engine)"| tplg["ALSA .tplg Binary"]
70+
71+
subgraph alsatplg_internal [alsatplg Internal Processing]
72+
direction TB
73+
parse["Parse Classes & Objects"] --> resolve["Resolve Attributes"]
74+
resolve --> validate["Validate Topologies"]
75+
end
76+
77+
conf_objs -.-> alsatplg_internal
78+
alsatplg_internal -.-> tplg
79+
```
80+
81+
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.
82+
83+
### Build Instructions
84+
85+
Topologies are built automatically as part of the standard SOF CMake build process. To explicitly build Topology 2 configurations:
86+
87+
```bash
88+
# From your build directory:
89+
make topologies2
90+
# OR
91+
cmake --build . --target topologies2
92+
```

0 commit comments

Comments
 (0)