Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
12 changes: 12 additions & 0 deletions .agent/rules/topology2_design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
trigger: glob
glob: topology2/**
---

# Topology2 Design Rule

When working in 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.
98 changes: 98 additions & 0 deletions .github/instructions/topology2-design.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
description: "Agent instructions for designing and updating ALSA topology v2 files in SOF"
applyTo: 'topology2/**'
---

# Topology2 Design Instructions

Use this guidance when creating or modifying files under 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 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"
```

## 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 platform keys remain consistent with the authoritative in-tree overrides under topology2/platform/intel/*.conf; current examples include tgl, adl, mtl, lnl, ptl, and nvl

## 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
* 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/.

## 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
61 changes: 61 additions & 0 deletions .github/workflows/topology.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: SOF Topologies Build & Validation

# yamllint disable-line rule:truthy
on: [pull_request, push, workflow_dispatch, workflow_call]

permissions:
contents: read

concurrency:
group: "${{ github.workflow }}-${{ github.event_name }}-\
${{ github.event_name == 'pull_request' && github.ref || github.run_id }}"
cancel-in-progress: true

jobs:
build-topologies:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
with:
path: sof-topologies

- name: Install build dependencies
run: |
sudo apt-get update
sudo apt-get -y install ninja-build cmake m4 \
automake autoconf libtool gettext libasound2-dev \
pkg-config python3-construct

- name: Install autoconf 2.72
run: |
cd "${GITHUB_WORKSPACE}"
wget -q https://ftp.gnu.org/gnu/autoconf/autoconf-2.72.tar.gz
tar xf autoconf-2.72.tar.gz
cd autoconf-2.72
./configure --prefix=/usr/local
make -j"$(nproc)"
sudo make install
hash -r

- name: Build ALSA lib & utils (alsatplg)
run: |
SOF_WORKSPACE="${GITHUB_WORKSPACE}" ./sof-topologies/scripts/build-alsa-tools.sh

- name: Build Topology1, Topology2 & Test Topologies
env:
SOF_WORKSPACE: ${{ github.workspace }}
run: |
./sof-topologies/scripts/build-topology.sh -T -t

- name: Run Topology Validation Suite
run: |
ctest --test-dir "${GITHUB_WORKSPACE}/sof-topologies/build" --output-on-failure

- name: Validate Install & Package Targets
run: |
./sof-topologies/scripts/install-topology.sh --dest "${GITHUB_WORKSPACE}/stage/lib/firmware"
test -d "${GITHUB_WORKSPACE}/stage/lib/firmware/intel/sof-tplg"
test -d "${GITHUB_WORKSPACE}/stage/lib/firmware/intel/sof-ipc4-tplg"
test -L "${GITHUB_WORKSPACE}/stage/lib/firmware/intel/sof-ace-tplg"
./sof-topologies/scripts/build-topology.sh -p
11 changes: 11 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
build/
build_*/
build_test_topo/
*.tplg
*.conf.tmp
/topology1/abi.h
/topology2/abi.conf
/topology2/abi-ipc3.conf
__pycache__/
*.pyc
.sof-sync-commit
181 changes: 181 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
# SPDX-License-Identifier: BSD-3-Clause

cmake_minimum_required(VERSION 3.17)

if("${CMAKE_CURRENT_SOURCE_DIR}" STREQUAL "${CMAKE_CURRENT_BINARY_DIR}")
message(FATAL_ERROR
" In-source builds are not supported.\n"
" Please remove CMakeCache.txt and the CMakeFiles directory.\n"
" Then specify a build directory. Example: cmake -Bbuild ..."
)
endif()

project(SOF_TOPOLOGY NONE)

option(BUILD_TOPOLOGY1 "Build legacy M4-based v1 (IPC3) topologies" ON)
option(BUILD_TOPOLOGY2 "Build class-based v2 (IPC4 & IPC3) topologies" ON)
option(BUILD_DEV_TOPOLOGIES "Build development and benchmark topologies" ON)
option(BUILD_TEST_TOPOLOGIES "Build test/topology matrix by default" OFF)

set(SOF_TPLG_VERSION_SUFFIX "" CACHE STRING "Optional version suffix for installed topology directories (e.g. -v2.14)")
set(SOF_TPLG_INSTALL_VENDOR_DIR "intel" CACHE STRING "Subdirectory under CMAKE_INSTALL_PREFIX for installed topologies")

if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
set(CMAKE_INSTALL_PREFIX "/lib/firmware" CACHE PATH "Default firmware install prefix" FORCE)
endif()

# Resolve SOF ABI header (include/kernel/abi.h)
# 1. Explicit -DSOF_ABI_HEADER=/path/to/abi.h
# 2. External SOF checkout via -DSOF_ROOT_SOURCE_DIRECTORY=/path/to/sof
# 3. Local standalone copy in ${PROJECT_SOURCE_DIR}/include/kernel/abi.h
if(NOT SOF_ABI_HEADER)
if(DEFINED SOF_ROOT_SOURCE_DIRECTORY AND EXISTS "${SOF_ROOT_SOURCE_DIRECTORY}/src/include/kernel/abi.h")
set(SOF_ABI_HEADER "${SOF_ROOT_SOURCE_DIRECTORY}/src/include/kernel/abi.h")
else()
set(SOF_ABI_HEADER "${PROJECT_SOURCE_DIR}/include/kernel/abi.h")
endif()
endif()
get_filename_component(SOF_ABI_HEADER "${SOF_ABI_HEADER}" ABSOLUTE)
message(STATUS "Using SOF ABI header: ${SOF_ABI_HEADER}")

# Parse ABI version from header for packaging metadata
file(READ "${SOF_ABI_HEADER}" _abi_contents)
string(REGEX MATCH "#define[ \t]+SOF_ABI_MAJOR[ \t]+([0-9]+)" _ "${_abi_contents}")
set(SOF_ABI_MAJOR "${CMAKE_MATCH_1}")
string(REGEX MATCH "#define[ \t]+SOF_ABI_MINOR[ \t]+([0-9]+)" _ "${_abi_contents}")
set(SOF_ABI_MINOR "${CMAKE_MATCH_1}")
string(REGEX MATCH "#define[ \t]+SOF_ABI_PATCH[ \t]+([0-9]+)" _ "${_abi_contents}")
set(SOF_ABI_PATCH "${CMAKE_MATCH_1}")
set(SOF_ABI_VERSION_STRING "${SOF_ABI_MAJOR}.${SOF_ABI_MINOR}.${SOF_ABI_PATCH}")
message(STATUS "SOF Topology ABI version: ${SOF_ABI_VERSION_STRING}")

set(SOF_TOPOLOGY_BINARY_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
set(SOF_TOPOLOGY1_SOURCE_DIR "${PROJECT_SOURCE_DIR}/topology1")
set(SOF_TOPOLOGY2_SOURCE_DIR "${PROJECT_SOURCE_DIR}/topology2")

include("${PROJECT_SOURCE_DIR}/cmake/alsatplg.cmake")

alsatplg_version(STATUS ALSATPLG_VERSION_NUMBER)
if(NOT STATUS EQUAL 0)
message(WARNING "${ALSATPLG_CMD} failed: ${STATUS}; all topologies skipped")
return()
else()
if(${ALSATPLG_VERSION_NUMBER} VERSION_LESS "1.2.5")
message(WARNING "All topologies skipped: minimum alsatplg version 1.2.5, found ${ALSATPLG_VERSION_NUMBER}.")
return()
endif()
message(STATUS "alsatplg: ${ALSATPLG_CMD} (version ${ALSATPLG_VERSION_NUMBER})")
endif()

add_custom_target(topologies ALL)

if(BUILD_TOPOLOGY1)
add_dependencies(topologies topologies1)
add_subdirectory(topology1)
endif()

if(BUILD_TOPOLOGY2)
add_subdirectory(topology2)
endif()

add_subdirectory(test)

# ---------------------------------------------------------------------------
# Installation Support (cmake --install <build_dir> [--prefix /lib/firmware])
# ---------------------------------------------------------------------------
set(_install_base "${SOF_TPLG_INSTALL_VENDOR_DIR}")
set(_ipc3_dest "${_install_base}/sof-tplg${SOF_TPLG_VERSION_SUFFIX}")
set(_ipc4_dest "${_install_base}/sof-ipc4-tplg${SOF_TPLG_VERSION_SUFFIX}")
set(_ace_link_name "sof-ace-tplg${SOF_TPLG_VERSION_SUFFIX}")
set(_ipc4_dir_name "sof-ipc4-tplg${SOF_TPLG_VERSION_SUFFIX}")

if(BUILD_TOPOLOGY1)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/topology1/production/"
DESTINATION "${_ipc3_dest}"
COMPONENT ipc3-prod
FILES_MATCHING PATTERN "*.tplg"
)
endif()

if(BUILD_TOPOLOGY2)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/topology2/production/ipc3/"
DESTINATION "${_ipc3_dest}"
COMPONENT ipc3-prod
FILES_MATCHING PATTERN "*.tplg"
)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/topology2/production/"
DESTINATION "${_ipc4_dest}"
COMPONENT ipc4-prod
FILES_MATCHING
PATTERN "ipc3" EXCLUDE
PATTERN "*.tplg"
)
# Create sof-ace-tplg -> sof-ipc4-tplg symlink on install
install(CODE "
set(_dest_dir \"\$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/${_install_base}\")
file(MAKE_DIRECTORY \"\${_dest_dir}\")
execute_process(
COMMAND \"${CMAKE_COMMAND}\" -E create_symlink \"${_ipc4_dir_name}\" \"\${_dest_dir}/${_ace_link_name}\"
)
" COMPONENT ipc4-prod)

if(BUILD_DEV_TOPOLOGIES)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/topology2/development/"
DESTINATION "${_install_base}/sof-ipc4-tplg-dev${SOF_TPLG_VERSION_SUFFIX}"
COMPONENT dev
EXCLUDE_FROM_ALL
FILES_MATCHING PATTERN "*.tplg"
)
endif()
endif()

# ---------------------------------------------------------------------------
# Testing / Validation Support (ctest --test-dir <build_dir>)
# ---------------------------------------------------------------------------
enable_testing()
find_package(Python3 COMPONENTS Interpreter QUIET)
if(Python3_Interpreter_FOUND)
if(BUILD_TOPOLOGY1)
add_test(
NAME validate_topology1_prod
COMMAND ${Python3_EXECUTABLE} "${PROJECT_SOURCE_DIR}/tools/validate-tplg.py"
"${CMAKE_CURRENT_BINARY_DIR}/topology1/production"
)
add_test(
NAME validate_topology1_pcm_parse
COMMAND ${Python3_EXECUTABLE} "${PROJECT_SOURCE_DIR}/tools/tplgtool2.py"
-d pcm -t "${CMAKE_CURRENT_BINARY_DIR}/topology1/production" "*.tplg"
)
endif()
if(BUILD_TOPOLOGY2)
add_test(
NAME validate_topology2_prod
COMMAND ${Python3_EXECUTABLE} "${PROJECT_SOURCE_DIR}/tools/validate-tplg.py"
"${CMAKE_CURRENT_BINARY_DIR}/topology2/production"
"${CMAKE_CURRENT_BINARY_DIR}/topology2/production/ipc3"
)
if(BUILD_DEV_TOPOLOGIES)
add_test(
NAME validate_topology2_dev
COMMAND ${Python3_EXECUTABLE} "${PROJECT_SOURCE_DIR}/tools/validate-tplg.py"
"${CMAKE_CURRENT_BINARY_DIR}/topology2/development"
)
endif()
endif()
endif()

# ---------------------------------------------------------------------------
# Packaging Support (cpack / ninja package)
# ---------------------------------------------------------------------------
set(CPACK_PACKAGE_NAME "sof-topology")
set(CPACK_PACKAGE_VENDOR "Sound Open Firmware Project")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "SOF ALSA Topology Binaries (IPC3 & IPC4)")
set(CPACK_PACKAGE_VERSION_MAJOR "${SOF_ABI_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${SOF_ABI_MINOR}")
set(CPACK_PACKAGE_VERSION_PATCH "${SOF_ABI_PATCH}")
set(CPACK_GENERATOR "TGZ")
include(CPack)
Loading
Loading