readme: Add readme for topology 1 & 2

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

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

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