docs: add topology2 README with structure and conventions by kv2019i · Pull Request #10623 · thesofproject/sof

kv2019i · 2026-03-13T13:58:24Z

document directory structure, class-based object model, and build pipeline
add PCM ID and pipeline ID convention tables for SoundWire and HDA
describe cmake target registration, platform overrides, and route definitions

Copilot

Pull request overview

This PR adds a comprehensive README for the SOF Topology2 system, documenting its directory structure, class-based object model, build pipeline, and conventions for PCM/pipeline IDs.

Changes:

Added a new README.md documenting directory structure, build process, and the class-based object model
Documented PCM ID and pipeline ID convention tables for SoundWire and HDA topology families
Described CMake target registration, platform overrides, route definitions, and widget naming conventions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

ujfalusi · 2026-03-13T14:29:55Z

tools/topology/topology2/README.md

+| HDMI 2 | 4 | `HDMI2_PCM_ID` |
+| HDMI 3 | 5 | `HDMI3_PCM_ID` |
+| DMIC0 | 6 | `DMIC0_PCM_ID` |
+| Deep Buffer | 31 | `DEEP_BUFFER_PCM_ID` |


| Compress HDA Analog | 50 | COMPR_PCM_ID |

Fixed in V2

ujfalusi · 2026-03-13T14:31:07Z

tools/topology/topology2/README.md

+| Deep Buffer (Jack) | 31 | `DEEP_BUFFER_PCM_ID` |
+| Deep Buffer (Speaker) | 35 | `DEEP_BUFFER_PCM_ID_2` |
+| DMIC Deep Buffer | 46 | `DMIC0_DEEP_BUFFER_PCM_ID` |
+| Compressed Playback 1 | 50 | `COMPR_PCM_ID` |


Compress Jack Out

ujfalusi · 2026-03-13T14:31:24Z

tools/topology/topology2/README.md

+| Deep Buffer (Speaker) | 35 | `DEEP_BUFFER_PCM_ID_2` |
+| DMIC Deep Buffer | 46 | `DMIC0_DEEP_BUFFER_PCM_ID` |
+| Compressed Playback 1 | 50 | `COMPR_PCM_ID` |
+| Compressed Playback 2 | 52 | `COMPR_2_PCM_ID` |


Compress Speaker

ujfalusi · 2026-03-13T14:36:26Z

tools/topology/topology2/README.md

+| HDMI 3 Host / DAI | 70 / 71 | `HDMI3_HOST_PIPELINE_ID` / `HDMI3_DAI_PIPELINE_ID` |
+| HDMI 4 Host / DAI | 80 / 81 | `HDMI4_HOST_PIPELINE_ID` / `HDMI4_DAI_PIPELINE_ID` |
+| Compressed 1 / 2 | 90 / 92 | `COMPR_PIPELINE_ID` / `COMPR_2_PIPELINE_ID` |
+| PCH DMIC0 Host / DAI | 100 / 101 | `DMIC0_HOST_PIPELINE_ID` / `DMIC0_DAI_PIPELINE_ID` |


why only these random pipeline IDs? There is pipeline with ID 22 for example and based on this readme, it is up for grab, when if you define a pipeline with 22, it will have really fun side effects as it is used by something else...

@ujfalusi I don't think the readme needs to be exhaustive. pipeline IDs are not visible in the public ALSA interface, so as long as the resulting topology is consistent internally, the pipeline IDs do not matter. I do think it's useful to highlight with some practical examples that within families of topology files (that used shared definitions), one must understand the pipeline ID conventions.

ujfalusi · 2026-03-13T14:43:37Z

tools/topology/topology2/README.md

+| HDMI 2 Host / DAI | 60 / 61 | `HDMI2_HOST_PIPELINE_ID` / `HDMI2_DAI_PIPELINE_ID` |
+| HDMI 3 Host / DAI | 70 / 71 | `HDMI3_HOST_PIPELINE_ID` / `HDMI3_DAI_PIPELINE_ID` |
+| HDMI 4 Host / DAI | 80 / 81 | `HDMI4_HOST_PIPELINE_ID` / `HDMI4_DAI_PIPELINE_ID` |
+| Compressed 1 / 2 | 90 / 92 | `COMPR_PIPELINE_ID` / `COMPR_2_PIPELINE_ID` |


Compress Jack and Speaker...

ujfalusi · 2026-03-13T14:44:31Z

tools/topology/topology2/README.md

+| HDMI 1 Host / DAI | 50 / 51 | `HDMI1_HOST_PIPELINE_ID` / `HDMI1_DAI_PIPELINE_ID` |
+| HDMI 2 Host / DAI | 60 / 61 | `HDMI2_HOST_PIPELINE_ID` / `HDMI2_DAI_PIPELINE_ID` |
+| HDMI 3 Host / DAI | 70 / 71 | `HDMI3_HOST_PIPELINE_ID` / `HDMI3_DAI_PIPELINE_ID` |
+| HDMI 4 Host / DAI | 80 / 81 | `HDMI4_HOST_PIPELINE_ID` / `HDMI4_DAI_PIPELINE_ID` |


Compress HDA Analog is 90 and who knows what pipeline IDs are in use in HDA topology, I would not dare to guess...

You can also use alsatplg --decode to just check. Agreed the build doesn't notify if you have conflicting pipeline IDs, so one needs to either use tplgtool2.py or test the topology with Linux kernel to really verify pipeline ID usage.

kv2019i

Thanks @ujfalusi . I'll make some improvements to V2 based on the comments. See also my replies inline. I don't think this readme should be the complete documentation (I'll add a link to https://thesofproject.github.io/latest/developer_guides/topology2/topology2.html ), nor full database of IDs, but provide enough examples for people to understand what are key things to pay attention to when writing new topologies (or updating existing once).

kv2019i · 2026-03-23T13:05:40Z

tools/topology/topology2/README.md

+| HDMI 2 | 4 | `HDMI2_PCM_ID` |
+| HDMI 3 | 5 | `HDMI3_PCM_ID` |
+| DMIC0 | 6 | `DMIC0_PCM_ID` |
+| Deep Buffer | 31 | `DEEP_BUFFER_PCM_ID` |


Fixed in V2

kv2019i · 2026-03-23T13:08:00Z

tools/topology/topology2/README.md

+| HDMI 3 Host / DAI | 70 / 71 | `HDMI3_HOST_PIPELINE_ID` / `HDMI3_DAI_PIPELINE_ID` |
+| HDMI 4 Host / DAI | 80 / 81 | `HDMI4_HOST_PIPELINE_ID` / `HDMI4_DAI_PIPELINE_ID` |
+| Compressed 1 / 2 | 90 / 92 | `COMPR_PIPELINE_ID` / `COMPR_2_PIPELINE_ID` |
+| PCH DMIC0 Host / DAI | 100 / 101 | `DMIC0_HOST_PIPELINE_ID` / `DMIC0_DAI_PIPELINE_ID` |


@ujfalusi I don't think the readme needs to be exhaustive. pipeline IDs are not visible in the public ALSA interface, so as long as the resulting topology is consistent internally, the pipeline IDs do not matter. I do think it's useful to highlight with some practical examples that within families of topology files (that used shared definitions), one must understand the pipeline ID conventions.

kv2019i · 2026-03-23T15:08:08Z

tools/topology/topology2/README.md

+| HDMI 1 Host / DAI | 50 / 51 | `HDMI1_HOST_PIPELINE_ID` / `HDMI1_DAI_PIPELINE_ID` |
+| HDMI 2 Host / DAI | 60 / 61 | `HDMI2_HOST_PIPELINE_ID` / `HDMI2_DAI_PIPELINE_ID` |
+| HDMI 3 Host / DAI | 70 / 71 | `HDMI3_HOST_PIPELINE_ID` / `HDMI3_DAI_PIPELINE_ID` |
+| HDMI 4 Host / DAI | 80 / 81 | `HDMI4_HOST_PIPELINE_ID` / `HDMI4_DAI_PIPELINE_ID` |


You can also use alsatplg --decode to just check. Agreed the build doesn't notify if you have conflicting pipeline IDs, so one needs to either use tplgtool2.py or test the topology with Linux kernel to really verify pipeline ID usage.

- document directory structure, class-based object model, and build pipeline - add PCM ID and pipeline ID convention tables for Intel SoundWire and HDA - describe cmake target registration, platform overrides, and route definitions Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

kv2019i · 2026-03-23T15:27:19Z

V2 pushed:

added a link to sof-docs https://thesofproject.github.io/latest/developer_guides/topology2/topology2.html
added clarifications that the examples are for Intel HDA and Intel SDW. other vendors can use different conventions (or reuse Intel ones, it's upto each vendor)
fixed the specific issues raised by @ujfalusi
can you @ranj063 and @bardliao check the primary rules and conventions make sense

kv2019i requested review from bardliao, lgirdwood and ujfalusi March 13, 2026 13:58

kv2019i requested review from jsarha and ranj063 as code owners March 13, 2026 13:58

Copilot AI review requested due to automatic review settings March 13, 2026 13:58

kv2019i mentioned this pull request Mar 13, 2026

topology2: add SDW echo reference function topologies #10600

Merged

Copilot started reviewing on behalf of kv2019i March 13, 2026 14:01 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

ujfalusi requested changes Mar 13, 2026

View reviewed changes

kv2019i commented Mar 23, 2026

View reviewed changes

kv2019i requested a review from singalsu March 23, 2026 15:09

kv2019i force-pushed the 202603-tplg2-docs branch from 96c10d0 to 25dd574 Compare March 23, 2026 15:24

Conversation

kv2019i commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kv2019i left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kv2019i commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants