diff --git a/.agent/rules/topology2_design.md b/.agent/rules/topology2_design.md new file mode 100644 index 000000000000..35d98473a57c --- /dev/null +++ b/.agent/rules/topology2_design.md @@ -0,0 +1,12 @@ +--- +trigger: glob +glob: tools/topology/topology2/** +--- + +# Topology2 Design Rule + +When working in tools/topology/topology2, follow the canonical guidance in +.github/instructions/topology2-design.instructions.md. + +Apply those instructions for topology structure, ID assignment, routing, +platform overrides, and topology target registration. \ No newline at end of file diff --git a/.github/instructions/topology2-design.instructions.md b/.github/instructions/topology2-design.instructions.md new file mode 100644 index 000000000000..678eb3a46d8f --- /dev/null +++ b/.github/instructions/topology2-design.instructions.md @@ -0,0 +1,86 @@ +--- +description: "Agent instructions for designing and updating ALSA topology v2 files in SOF" +applyTo: 'tools/topology/topology2/**' +--- + +# Topology2 Design Instructions + +Use this guidance when creating or modifying files under tools/topology/topology2. +These rules align with the topology2 README and capture expected design patterns for +class-based ALSA topology v2 authoring. + +## Scope + +* Applies to topology2 .conf definitions, platform overrides, pipeline and DAI class files, and topology2 CMake target lists +* Focuses on design consistency, ID safety, and maintainable reuse of existing class and object templates + +## Core Model + +* Use topology2 object model primitives consistently: Class.*, Object.*, Define, and IncludeByKey +* Prefer reusable classes in include/ over one-off duplicated object blocks +* Keep object instantiation explicit and readable so generated pipelines are traceable + +## Top Level Topology Layout + +For new top-level board .conf files, keep this order: + +1. Search directories +2. Required class includes +3. Define block with defaults +4. IncludeByKey.PLATFORM overrides +5. Feature-gated IncludeByKey blocks +6. DAI, pipeline, and PCM objects +7. Route definitions + +## Reuse Before New Base Files + +* Prefer extending an existing base input .conf with variable overrides from CMake targets +* Add a new base .conf only when existing topologies cannot represent the use case cleanly +* When adding a new target, use the tuple format exactly: + +```text +"input-conf;output-name;variable1=value1,variable2=value2" +``` + +## ID Conventions and Safety + +* Keep PCM IDs unique within a single topology +* Keep pipeline indexes unique within a single topology +* Pair FE and BE pipelines as N and N+1 where applicable +* For SoundWire pipelines, follow index equals PCM ID times 10 unless a documented topology-specific exception exists +* For HDMI pipelines, keep stride-10 layout with host at N0 and DAI at N1 +* When combining features such as SDW, PCH DMIC, HDMI, deep buffer, or compress, verify there are no ID collisions after overrides + +## Routing Rules + +* Connect FE mixin outputs to BE mixout inputs using Object.Base.route +* Keep route naming and widget references aligned with topology naming patterns +* Validate that each route endpoint maps to a declared widget in the same compiled topology + +## Widget Naming + +* Follow naming pattern type.pipeline-index.instance +* Keep naming stable and descriptive for easier graph inspection and debug + +## Platform Overrides + +* 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 + +## CMake Target Placement + +Register targets in the correct file for platform generation: + +* Tiger Lake and Alder Lake: production/tplg-targets-cavs25.cmake +* Meteor Lake: production/tplg-targets-ace1.cmake +* Lunar Lake: production/tplg-targets-ace2.cmake +* Panther Lake: production/tplg-targets-ace3.cmake +* HDA generic: production/tplg-targets-hda-generic.cmake +* Development and test topologies: development/tplg-targets.cmake + +## Validation Expectations + +* Keep topology2 buildable through the topologies2 target +* Preserve compatibility with alsatplg pre-processing mode used by the build system +* Ensure topology edits remain synchronized with nearby architecture or README documentation when design behavior changes