topology2: validator: add a tool to check topology validity at build time

.github/workflows/tools.yml

@@ -30,7 +30,7 @@ jobs:
         run: sudo apt-get update &&
                sudo apt-get -y install ninja-build
                   automake autoconf libtool gettext libasound2-dev
-                  pkg-config
+                  pkg-config python3-construct python3-pytest
 
       # Ubuntu 24.04 ships autoconf 2.71, but current alsa-lib/alsa-utils
       # require >= 2.72. Build a newer autoconf from the GNU release
@@ -84,3 +84,10 @@ jobs:
         run: CMAKE_BUILD_TYPE=Release ./sof/scripts/build-tools.sh ||
              VERBOSE=1 NO_PROCESSORS=1 USE_XARGS=no
              CMAKE_BUILD_TYPE=Release ./sof/scripts/build-tools.sh
+
+      # The build above already validated every topology v2 binary
+      - name: topology validator tests
+        env:
+          LD_LIBRARY_PATH: ${{ github.workspace }}/tools/lib
+          ALSATPLG: ${{ github.workspace }}/tools/bin/alsatplg
+        run: python3 -m pytest -v sof/tools/topology/validator/tests

.github/workflows/tplg-validator-schema.yml

@@ -0,0 +1,36 @@
+---
+name: Topology validator kernel schema
+
+# Checks that tools/topology/validator/schema/kernel_tokens.py still
+# matches the SOF driver token tables in the kernel. When this fails,
+# rerun schema/gen_kernel_tokens.py against a kernel tree and review the
+# validator rules against the kernel changes.
+
+# yamllint disable-line rule:truthy
+on:
+  schedule:
+    - cron: '0 3 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  kernel-schema:
+    runs-on: ubuntu-26.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          filter: 'tree:0'
+          path: sof
+
+      - name: Fetch SOF driver sources
+        run: |
+          git clone --depth 1 --filter=blob:none --sparse \
+            --branch topic/sof-dev https://github.com/thesofproject/linux.git linux
+          git -C linux sparse-checkout set --no-cone \
+            /include/uapi/sound/ /sound/soc/sof/ /sound/soc/soc-topology.c
+
+      - name: Check kernel token schema
+        run: python3 sof/tools/topology/validator/schema/gen_kernel_tokens.py
+               --kernel linux --check

tools/topology/CMakeLists.txt

@@ -56,6 +56,34 @@ else()
 	message("-- alsatplg version: " ${ALSATPLG_VERSION_NUMBER})
 endif()
 
+# Check every topology2 binary like the Linux SOF driver would when
+# loading it, see validator/README.md. Errors fail the build, warnings
+# are only counted. Needs the python3 construct module.
+option(TPLG_VALIDATE "Validate topology2 binaries after building them" ON)
+set(TPLG_VALIDATOR "${CMAKE_CURRENT_SOURCE_DIR}/validator/tplg_validate.py")
+set(TPLG_VALIDATE_WAIVERS "${CMAKE_CURRENT_SOURCE_DIR}/validator/known-issues.txt")
+set(TPLG_VALIDATE_ENABLED FALSE)
+if(TPLG_VALIDATE)
+	find_package(Python3 COMPONENTS Interpreter)
+	if(Python3_Interpreter_FOUND)
+		execute_process(COMMAND ${Python3_EXECUTABLE} -c "import construct"
+		  RESULT_VARIABLE construct_status OUTPUT_QUIET ERROR_QUIET)
+	endif()
+	if(Python3_Interpreter_FOUND AND construct_status EQUAL 0)
+		set(TPLG_VALIDATE_ENABLED TRUE)
+		message("-- topology validation: enabled")
+		# recheck the binaries when the rules, the kernel schema or the
+		# waivers change
+		file(GLOB_RECURSE TPLG_VALIDATE_DEPENDS CONFIGURE_DEPENDS
+			"${CMAKE_CURRENT_SOURCE_DIR}/validator/*.py")
+		list(FILTER TPLG_VALIDATE_DEPENDS EXCLUDE REGEX "/tests/")
+		list(APPEND TPLG_VALIDATE_DEPENDS ${TPLG_VALIDATE_WAIVERS})
+	else()
+		message(WARNING "topology validation skipped: python3 with the construct "
+			"module not found (install python3-construct or set -DTPLG_VALIDATE=OFF)")
+	endif()
+endif()
+
 
 # This use of VERBOSE relies on original CMake behavior.
 # From the add_custom_command() manual:
@@ -111,6 +139,24 @@ macro(add_alsatplg2_command conf_header conf_target input_name output_name inclu
 		        -I ${include_path} -D "'${defines}'" -p -c ${output_name}.conf -o ${output_name}.tplg
 		${TPLG_USES_TERMINAL}
 		)
+
+	# Files the topology target must depend on, for the callers
+	set(tplg2_outputs ${output_name}.tplg)
+
+	# Validate in a separate command, so that a change to the validator
+	# or the waivers rechecks the binary without rebuilding it. A failed
+	# check leaves no stamp file, so the check is repeated next time.
+	if (TPLG_VALIDATE_ENABLED)
+		add_custom_command(
+			OUTPUT ${output_name}.tplg.validated
+			DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${output_name}.tplg ${TPLG_VALIDATE_DEPENDS}
+			COMMAND ${Python3_EXECUTABLE} ${TPLG_VALIDATOR} --quiet
+				--waivers ${TPLG_VALIDATE_WAIVERS} ${output_name}.tplg
+			COMMAND ${CMAKE_COMMAND} -E touch ${output_name}.tplg.validated
+			${TPLG_USES_TERMINAL}
+			)
+		list(APPEND tplg2_outputs ${output_name}.tplg.validated)
+	endif()
 endmacro()
 
 

tools/topology/README.md

@@ -10,6 +10,7 @@ To support the evolution of the SOF topology syntax, the configuration files are
 
 - [`topology1/`](topology1/README.md): Contains the legacy (v1) `m4`-based ALSA topology generation scripts and configuration files. Topology v1 heavily relies on `m4` macro preprocessing to generate the final `.conf` files before being compiled by `alsatplg`.
 - [`topology2/`](topology2/README.md): Contains the newer (v2) ALSA topology generation files. Topology v2 introduces a more structured, object-oriented syntax natively supported by newer versions of the `alsatplg` compiler (specifically the pre-processor `-p` flag), reducing reliance on external macro languages.
+- [`validator/`](validator/README.md): Offline validator that checks topology v2 binaries the way the Linux SOF driver loads them.
 
 ## Build Process
 
@@ -18,5 +19,6 @@ The topology build process is managed by `CMakeLists.txt` in this root directory
 1. **Compiler Detection**: It locates the `alsatplg` tool (usually built in `tools/bin/alsatplg` alongside the firmware) and checks its version.
 2. **Feature Validation**: It ensures the `alsatplg` version is at least `1.2.5`. Older versions are known to silently corrupt certain topology structures (e.g., converting `codec_consumer` to `codec_master`). If the tool is too old, topology generation is safely skipped with a warning.
 3. **Target Generation**: It provides macros (`add_alsatplg_command` and `add_alsatplg2_command`) used by the subdirectories to invoke the topology compiler on the pre-processed `.conf` files to generate the final `.tplg` binaries.
+4. **Validation**: With `TPLG_VALIDATE=ON` (the default) and python3 with the `construct` module available, `add_alsatplg2_command` runs [`validator/tplg_validate.py`](validator/README.md) on every topology v2 binary. Validation errors fail the build; known problems are listed in `validator/known-issues.txt`.
 
 The `topologies` CMake target is the master target that depends on the generation targets inside both `topology1` and `topology2`.

tools/topology/topology2/README.md

@@ -143,6 +143,14 @@ To build a specific topology target:
 make sof-lnl-sdw-cs42l43-l0-cs35l56-l12
 ```
 
+Each built binary is checked by the [topology validator](../validator/README.md), which repeats
+the checks the Linux SOF driver does when loading a topology. A validation error fails the
+build of that topology. To check a binary by hand, for example to see warnings too:
+
+```bash
+tools/topology/validator/tplg_validate.py build_tools/topology/topology2/production/sof-mtl-rt711-4ch.tplg
+```
+
 ## Best Practices for Adding New Topology Definitions
 
 ### Topology Structure

tools/topology/topology2/development/CMakeLists.txt

@@ -23,6 +23,6 @@ foreach(tplg ${TPLGS})
 	  "${CMAKE_CURRENT_SOURCE_DIR}/../${input}" "${output}"
 	  "${CMAKE_CURRENT_SOURCE_DIR}/../" "${defines}")
 
-	add_custom_target(topology2_dev_${output} DEPENDS ${output}.tplg)
+	add_custom_target(topology2_dev_${output} DEPENDS ${tplg2_outputs})
 	add_dependencies(topology2_dev topology2_dev_${output})
 endforeach()

tools/topology/topology2/production/CMakeLists.txt

@@ -29,7 +29,7 @@ foreach(tplg ${TPLGS})
 	  "${CMAKE_CURRENT_SOURCE_DIR}/../${input}" "${output}"
 	  "${CMAKE_CURRENT_SOURCE_DIR}/../" "${defines}")
 
-	add_custom_target(topology2_prod_${output} DEPENDS ${output}.tplg)
+	add_custom_target(topology2_prod_${output} DEPENDS ${tplg2_outputs})
 	add_dependencies(topology2_prod topology2_prod_${output})
 endforeach()
 
@@ -50,5 +50,7 @@ foreach(link ${SYMLINKS})
 	)
 
 	add_custom_target(topology2_prod_${link_name} DEPENDS ${link_name}.tplg)
+	# the alias is only as good as its target, build and validate it too
+	add_dependencies(topology2_prod_${link_name} topology2_prod_${link_target})
 	add_dependencies(topology2_prod topology2_prod_${link_name})
 endforeach()

tools/topology/validator/README.md

@@ -0,0 +1,107 @@
+# Topology validator (`tools/topology/validator`)
+
+`tplg_validate.py` checks SOF IPC4 topology binaries (`.tplg`) offline, without
+target hardware. It parses the binary and repeats what the Linux SOF driver
+does when it loads the topology, so that problems show up at build time
+instead of on a device. `alsatplg` accepts many topologies that the kernel
+rejects; for instance it prints `undefined sink widget` for a dangling route
+and still exits successfully.
+
+```bash
+# check topologies, print errors and warnings
+tplg_validate.py build_tools/topology/topology2/production/sof-mtl-rt711-4ch.tplg
+
+# also print informational findings, check core IDs against a 5 core DSP
+tplg_validate.py -v --num-cores 5 *.tplg
+
+# list the rules and the kernel functions they mirror
+tplg_validate.py --list-rules
+
+# print the decoded topology with kernel token names
+tplg_validate.py --dump foo.tplg
+```
+
+Exit status is 1 if any error is found (`--werror`: any warning). Python 3.8+
+and the `construct` module (`python3-construct`) are required.
+
+## Build integration
+
+`add_alsatplg2_command` in `tools/topology/CMakeLists.txt` runs the validator
+after `alsatplg` for every topology v2 target, unless configured with
+`-DTPLG_VALIDATE=OFF` or `construct` is missing. A successful check writes a
+`<topology>.tplg.validated` stamp file. An error fails the target and leaves no
+stamp, so the check reruns on the next build. Changes to the validator sources
+or to `known-issues.txt` recheck all topologies without rebuilding them.
+
+Known errors are listed in `known-issues.txt` as `<topology glob> <rule>`
+pairs and reported as warnings. Do not add entries to silence new errors:
+fix the topology. Remove entries when a topology is fixed.
+
+## What is checked
+
+Rules are grouped in layers by how closely they follow kernel code:
+
+| Layer | Mirrors | Examples |
+|-------|---------|----------|
+| L1 | `sound/soc/soc-topology.c` | headers, element sizes, names, kcontrol handler IDs, TLV types |
+| L2 | `sound/soc/sof/topology.c` tuple engine | kernel parse errors, tuple types, audio format blocks vs. counts |
+| L3 | `topology.c`, `ipc4-topology.c` setup | routes, pipelines, chain DMA, DAI types, pins, bytes controls, PCM binding |
+| L4 | `sof-audio.c` path walk, format selection | PCM formats vs. host copier formats (advisory) |
+
+Every finding names the rule and the kernel function it follows, e.g.
+
+```
+foo.tplg: error: G001 route 'mixin.90.1' -> 'mixout.1.1': sink widget 'mixout.1.1' does not exist (kernel: snd_soc_dapm_add_routes, sof_route_load)
+```
+
+Severities: `error` means the kernel fails to load the topology, or fails
+when the affected PCM is used. `warning` means a likely mistake, or a failure
+that depends on runtime state the validator cannot know. `info` lists
+observations (`-v`).
+
+Not checked, because the data only exists on the target: firmware module
+UUIDs and module types from the firmware manifest, ACPI NHLT blobs, machine
+driver BE links, and the DSP's answers to IPC messages.
+
+## Keeping up with the kernel
+
+The kernel driver is the reference. The validator follows it in two ways:
+
+- **Generated token schema.** `schema/kernel_tokens.py` is generated from a
+  kernel tree by `schema/gen_kernel_tokens.py`. It holds the `SOF_TKN_*` IDs, the
+  `struct sof_topology_token` tables with token types, the per widget type
+  token lists of `tplg_ipc4_widget_ops`, the DAI type names and the kcontrol
+  handler IDs. `tplgparse/kernel_engine.py` emulates the kernel tuple parser
+  (`sof_parse_token_sets()`, `sof_copy_tuples()`, `sof_update_ipc_object()`)
+  on top of these tables. New tokens or widget types only need a
+  regeneration:
+
+  ```bash
+  schema/gen_kernel_tokens.py --kernel ~/linux           # update kernel_tokens.py
+  schema/gen_kernel_tokens.py --kernel ~/linux --check   # CI: fail on drift
+  ```
+
+- **Hand written rules** in `checks/`. Each rule names the kernel function it
+  mirrors (`--list-rules`). Changes that add or remove topology checks in
+  `sound/soc/sof/ipc4-topology.c` or `topology.c` should get a matching rule
+  update here.
+
+`schema/check_tokens_conf.py` cross-checks `topology2/include/common/tokens.conf`
+and the `token_ref` attributes of the topology2 classes against the kernel schema.
+
+## Layout
+
+```
+tplg_validate.py        command line tool
+tplgparse/binary.py     ALSA topology binary format (ported from sof-test tplgtool2.py)
+tplgparse/model.py      typed view, vendor tuples decoded as written
+tplgparse/kernel_engine.py  kernel tuple engine emulation
+schema/                 generated kernel token schema and its generator
+checks/                 rules, one module per layer
+tests/                  pytest suite; tplgbuild.py builds test topologies
+known-issues.txt        waived errors
+```
+
+Run the tests with `pytest tools/topology/validator/tests`. Set `ALSATPLG`
+to select the `alsatplg` binary for the integration tests and `KERNEL_TREE`
+to include the schema drift check.