readme: Add readme for topology 1 & 2#10610
readme: Add readme for topology 1 & 2#10610lgirdwood wants to merge 1 commit intothesofproject:mainfrom
Conversation
Add some high level descriptiond of topology 1 & 2 Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
There was a problem hiding this comment.
Pull request overview
Adds high-level documentation explaining SOF’s ALSA topology tooling and the differences between Topology v1 (m4-based) and Topology v2 (alsatplg preprocessor / class-object model).
Changes:
- Added README for
topology1/explaining m4-based structure, assembly, and build flow. - Added README for
topology2/explaining class/object concepts, directory layout, and build flow. - Added top-level
tools/topology/README.mddescribing overall directory structure and CMake-driven build process.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| tools/topology/topology2/README.md | Documents Topology v2 concepts, directory structure, and build flow (with diagrams). |
| tools/topology/topology1/README.md | Documents Topology v1 (m4) structure, assembly model, and build flow (with diagrams). |
| tools/topology/README.md | Adds a landing page describing both topology versions and the build system responsibilities. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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. |
There was a problem hiding this comment.
Terminology is slightly inconsistent across the docs (e.g., “Topology 2.0”, “Topology v2”, and elsewhere “Topology 2”). Consider standardizing on one term (commonly “Topology v2”) throughout to reduce reader confusion and make searching/grepping more reliable.
| - `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. | ||
|
|
There was a problem hiding this comment.
These READMEs rely on Mermaid for key explanations. Some renderers (non-GitHub Markdown viewers, certain doc pipelines) won’t render Mermaid blocks, which can make the doc harder to follow. Consider adding a short textual fallback summary adjacent to each diagram (or linking to an exported PNG/SVG) so the structure/build flow remains understandable without Mermaid support.
Add some high level descriptiond of topology 1 & 2