.agent/.github: add topology2 agent design guidance#10685
.agent/.github: add topology2 agent design guidance#10685kv2019i wants to merge 1 commit intothesofproject:mainfrom
Conversation
Add a canonical topology2 instruction file under .github/instructions and a matching companion rule under .agent/rules. Document topology v2 structure, reuse expectations, PCM and pipeline ID conventions, routing rules, platform overrides, and target registration guidance for agents working in tools/topology/topology2. Our existing agent rules are in .agent, but github copilot doesn't understand these yet, so add the companion rule. Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>
kv2019i
requested review from
dbaluta,
lbetlej,
lgirdwood,
mmaka1 and
plbossart
as code owners
|
The path-based rules are not so standardized yet (copilot, antigravity. cursor all have different conventions). I now added copilot once here and a link to .agent/rules (as we already have .agent/rules for SOF). |
There was a problem hiding this comment.
Pull request overview
Adds canonical, in-repo guidance for authors/agents working on ALSA Topology v2 sources under tools/topology/topology2, and wires that guidance into both GitHub Copilot instructions and the existing .agent rule system.
Changes:
- Added a new GitHub Copilot instruction file documenting topology2 structure, reuse expectations, ID/routing conventions, platform overrides, and CMake target registration.
- Added a companion
.agentrule to apply the same guidance when working undertools/topology/topology2/**.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
.github/instructions/topology2-design.instructions.md |
New canonical topology2 design guidance for Copilot/agents scoped to tools/topology/topology2/**. |
.agent/rules/topology2_design.md |
Companion .agent rule pointing contributors to the canonical instruction file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * When adding a new target, use the tuple format exactly: | ||
|
|
||
| ```text | ||
| "input-conf;output-name;variable1=value1,variable2=value2" |
There was a problem hiding this comment.
The documented CMake tuple format uses raw semicolons, but the topology2 CMake target lists escape semicolons inside quoted strings (e.g., "cavs-sdw\;...\;PLATFORM=..." as in tools/topology/topology2/README.md:204 and production/tplg-targets-ace1.cmake:6). As written, “use the tuple format exactly” may cause copy/paste errors in CMake. Please update this section to either show the escaped form used in CMake (\;) or explicitly call out that semicolons must be escaped in CMake strings.
| * When adding a new target, use the tuple format exactly: | |
| ```text | |
| "input-conf;output-name;variable1=value1,variable2=value2" | |
| * When adding a new target, use this tuple structure. In CMake quoted strings, escape each semicolon as `\;`. | |
| ```text | |
| Logical tuple format: | |
| "input-conf;output-name;variable1=value1,variable2=value2" | |
| CMake string form: | |
| "input-conf\;output-name\;variable1=value1,variable2=value2" |
|
|
||
| * Use IncludeByKey.PLATFORM for platform-specific Define overrides | ||
| * Restrict platform-specific tuning to platform/intel/*.conf instead of duplicating board-level logic | ||
| * Ensure supported platform keys remain consistent with project usage: tgl, mtl, lnl, ptl |
There was a problem hiding this comment.
This list of “supported platform keys” is incomplete compared to current topology2 usage. Existing top-level configs use additional keys like adl and nvl (e.g., tools/topology/topology2/cavs-nocodec.conf:105-112 and cavs-sdw.conf:129-134). Please update the guidance to include the full set of in-tree keys (or reference the authoritative list) so new changes don’t incorrectly reject/avoid valid platform values.
| * Ensure supported platform keys remain consistent with project usage: tgl, mtl, lnl, ptl | |
| * Ensure platform keys remain consistent with the authoritative in-tree overrides under tools/topology/topology2/platform/intel/*.conf; current examples include tgl, adl, mtl, lnl, ptl, and nvl |
| * Panther Lake: production/tplg-targets-ace3.cmake | ||
| * HDA generic: production/tplg-targets-hda-generic.cmake | ||
| * Development and test topologies: development/tplg-targets.cmake | ||
|
|
There was a problem hiding this comment.
The target-placement mapping omits existing production target lists such as production/tplg-targets-ace4.cmake (used for sof-nvl-* targets) and others like tplg-targets-imx8.cmake / tplg-targets-sdca-generic.cmake. Since this file is intended as canonical guidance, please extend the table (or point to a single source of truth) so contributors register targets in the correct CMake file.
| * Panther Lake: production/tplg-targets-ace3.cmake | |
| * HDA generic: production/tplg-targets-hda-generic.cmake | |
| * Development and test topologies: development/tplg-targets.cmake | |
| * Panther Lake: production/tplg-targets-ace3.cmake | |
| * Nova Lake / `sof-nvl-*`: production/tplg-targets-ace4.cmake | |
| * i.MX8 platforms: production/tplg-targets-imx8.cmake | |
| * SDCA generic topologies: production/tplg-targets-sdca-generic.cmake | |
| * HDA generic: production/tplg-targets-hda-generic.cmake | |
| * Development and test topologies: development/tplg-targets.cmake | |
| If a target family is not listed above, use the existing `tplg-targets-*.cmake` | |
| file that already contains similar topologies as the source of truth, and keep new | |
| targets grouped with the same platform or product family in either `production/` or | |
| `development/`. |
Add a canonical topology2 instruction file under .github/instructions and a matching companion rule under .agent/rules. Document topology v2 structure, reuse expectations, PCM and pipeline ID conventions, routing rules, platform overrides, and target registration guidance for agents working in tools/topology/topology2.
Our existing agent rules are in .agent, but github copilot doesn't understand these yet, so add the companion rule.