topology2: validator: add a tool to check topology validity at build time by kv2019i · Pull Request #11344 · thesofproject/sof

kv2019i · 2026-10-23T11:08:13Z

Prompted by recent bugs in topology2 files (e.g. #11258 ), here's a PR that adds a build time tool that checks generated topology files against expectations of the Linux kernel SOF driver. The tool tries to cover common errors alsatplg tool doesnt' cover, and to give more understanable error messages when problems are seen.

The tool is designed such we can have it run for every topology build, and also run standalone when debugging specific issues.

lgirdwood

LGTM

Copilot

🟡 Changes recommended

Input-handling, validation-accuracy, and incremental-build dependency issues remain unresolved.

7 open issues

What changed in this PR

Adds an offline SOF IPC4 topology validator to catch kernel-facing errors during topology2 builds, complementing checks performed by alsatplg.

Changes:

Adds binary parsing, kernel token emulation, and layered validation rules.
Integrates validation into topology2 builds with waivers for known issues.
Adds tests, schema drift checks, and usage documentation.

File	Description
`tools/topology/validator/tplgparse/model.py`	Models parsed topology objects and vendor tuples.
`tools/topology/validator/tplgparse/kernel_engine.py`	Emulates kernel token parsing.
`tools/topology/validator/tplgparse/binary.py`	Parses ALSA topology binary structures.
`tools/topology/validator/tplgparse/__init__.py`	Initializes the parser package.
`tools/topology/validator/tplg_validate.py`	Provides the CLI, reporting, and waiver handling.
`tools/topology/validator/tests/tplgbuild.py`	Builds synthetic topology fixtures.
`tools/topology/validator/tests/test_rules.py`	Tests validation rules.
`tools/topology/validator/tests/test_integration.py`	Tests real topologies, CLI behavior, and schema drift.
`tools/topology/validator/tests/conftest.py`	Configures test imports.
`tools/topology/validator/schema/kernel_tokens.py`	Supplies generated kernel token tables.
`tools/topology/validator/schema/gen_kernel_tokens.py`	Generates and checks the kernel schema.
`tools/topology/validator/schema/check_tokens_conf.py`	Cross-checks topology2 token definitions.
`tools/topology/validator/schema/__init__.py`	Initializes the schema package.
`tools/topology/validator/README.md`	Documents usage, design, and maintenance.
`tools/topology/validator/known-issues.txt`	Records existing validation waivers.
`tools/topology/validator/checks/tokens.py`	Checks vendor tuples and format counts.
`tools/topology/validator/checks/structure.py`	Checks binary structure and control metadata.
`tools/topology/validator/checks/paths.py`	Checks PCM paths and format compatibility.
`tools/topology/validator/checks/ipc4.py`	Checks IPC4 setup requirements.
`tools/topology/validator/checks/__init__.py`	Registers and runs validation rules.
`tools/topology/topology2/README.md`	Documents build-time validation.
`tools/topology/README.md`	Introduces the validator in the topology overview.
`tools/topology/CMakeLists.txt`	Runs validation after topology2 compilation.
`.github/workflows/tplg-validator-schema.yml`	Adds scheduled kernel schema checks.
`.github/workflows/tools.yml`	Installs dependencies and runs validator tests.

_{Review effort: Balanced}

intel-sofci · 2026-10-23T12:06:05Z

PR 11344: test results

Run date: 2026-10-27 15:08 UTC

Tested commit: 069ea43f5be2f26352babfcfa12355bbacf382f6

kv2019i · 2026-10-26T13:49:18Z

V2 pushed:

addressing the findings so far

Copilot

🟡 Changes recommended

Valid DAPM configurations can produce false diagnostics, and directly built topology aliases bypass validation.

3 open issues

Make SYMLINKS aliases depend on validated targets · New
Require schedulers only for IPC4 setup widgets · New
Check MUX enum entries for route validation · New

7 resolved since last review

_{Review effort: Balanced}

kv2019i · 2026-10-26T15:49:27Z

V3 pushed:

fixing issues in V2 review

Add the foundation for an offline validator of SOF IPC4 topology binaries. tplgparse/binary.py describes the ALSA topology binary format (ABI 5) with construct. The record layouts are ported from sof-test tools/tplgtool2.py, but the section walk mirrors soc_tplg_load() in the kernel so that malformed input is reported as an issue with a file offset instead of a parser exception. DAI and DAI link sections are parsed too, and all values are kept as plain integers. tplgparse/model.py provides a typed view of widgets, kcontrols, routes, PCMs and links, with vendor tuples decoded by the type of the vendor array they are in. The Linux SOF driver is the reference for how a topology is read. Instead of hand copying its token lists, schema/gen_kernel_tokens.py extracts from a kernel tree the SOF_TKN_* IDs, the struct sof_topology_token tables with their token types, the token lists of tplg_ipc4_widget_ops, the DAI type names and the kcontrol handler IDs into schema/kernel_tokens.py. With --check it reports drift against a kernel tree. tplgparse/kernel_engine.py emulates the kernel tuple engine (sof_parse_token_sets(), sof_copy_tuples(), sof_update_ipc_object(), sof_widget_parse_tokens()) on top of the generated tables. The kernel does not always read tuples the way a topology means them: multiple token sets are filled by occurrence count, parsing stops once enough tokens are found and sof_copy_tuples() picks the element layout from the expected token type, not from the vendor array type. Every value read is recorded with its source offset so that checks can compare the kernel view to the intended one. kernel_tokens.py is generated from sof-dev at commit 5c16bd4ee077 Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

kv2019i · 2026-10-27T09:33:58Z

V4 pushed:

fix gap found in topology2: echo reference: route from loopback DAI only when it exists #11359 -- validator didn't correctly handle SDCA function topologies when they referred to each others definitions, add support to handle these (to the extent possible in the validator)

Copilot

🟡 Changes recommended

Base-topology handling duplicates accumulated data and omits inherited host copiers from PCM binding and path checks.

3 open issues

3 resolved since last review

_{Review effort: Balanced}

kv2019i · 2026-10-27T14:16:14Z

+            if not enabled:
+                continue
+            name = p.raw.caps[d].name.split(b"\0", 1)[0].decode("ascii", "replace")
+            if not any(w.type_name == wtype and w.sname == name for w in t.widgets):


Fixed in V5

kv2019i · 2026-10-27T14:16:02Z

+            if not enabled:
+                continue
+            name = p.raw.caps[d].name.split(b"\0", 1)[0].decode("ascii", "replace")
+            host = next((w for w in t.widgets


Fixed in V5

kv2019i · 2026-10-27T14:16:08Z

+        for earlier in bases:
+            base.add_base(earlier)


Fixed in V5

Add tplg_validate.py, which checks topology binaries against what the Linux SOF driver does when loading them, so that problems are found without the target hardware. Rules are grouped in layers: L1 binary structure as checked by sound/soc/soc-topology.c: headers, element sizes, NUL terminated names, widget types, enum items, TLV types and kcontrol handler binding L2 vendor tuples as read by the emulated SOF tuple engine: kernel parse errors, values read from the wrong tuple, malformed vendor arrays, unknown tokens, tuple types the kernel ignores, and audio format blocks versus NUM_INPUT/OUTPUT_AUDIO_FORMATS L3 IPC4 load and setup rules from topology.c and ipc4-topology.c: route endpoints, scheduler widgets, chain DMA, volatile controls in dynamic pipelines, audio formats, module UUIDs, DAI types, pin counts and bindings, volume and bytes controls, PCM to host copier binding, BE link configs and the manifest L4 PCM path walk and host copier format matching (advisory) Each finding names the rule and the kernel function it follows, and --list-rules prints them all for review against kernel changes. Errors mean the kernel fails to load the topology or to use a PCM, warnings are likely mistakes or failures that depend on runtime state. The exit status is non-zero on errors, or on warnings with --werror. known-issues.txt lists errors present in the current topologies, which --waivers reports as warnings, so that the build can enforce the rules for new problems while the existing ones are fixed. schema/check_tokens_conf.py cross-checks topology2 tokens.conf and the token_ref attributes of the classes against the kernel schema. The --base option is available to check combinations of SDCA function topologies. With function topologies the kernel loads several topology files into the same component, and loads the feature topologies given with the feature_topologies module parameter after them, in the given order. Routes in a later file may refer to widgets of an earlier one. The pytest suite builds small topologies with tests/tplgbuild.py and has a passing and failing case for each rule. Integration tests build real topology2 targets with alsatplg and, with KERNEL_TREE set, check the token schema against a kernel tree. Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

alsatplg accepts many topologies that the SOF driver rejects at load time, e.g. it reports a route to an undefined widget but still exits successfully. Such problems are usually only found on target hardware. Run tools/topology/validator/tplg_validate.py after alsatplg for every topology2 target. A validation error fails the target and deletes the .tplg so that it is checked again on the next build. Errors listed in validator/known-issues.txt are reported as warnings. Validation is enabled by default with the TPLG_VALIDATE option and is skipped with a warning when python3 with the construct module is not available. Document the validator and point to it from the topology READMEs. Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

Install python3-construct in the tools workflow so that the topology build validates every topology2 binary, and run the validator pytest suite after the build. Add a weekly workflow that checks the validator kernel token schema against the SOF driver in thesofproject/linux topic/sof-dev, so that token table changes in the kernel are noticed. Signed-off-by: Kai Vehmanen <kai.vehmanen@linux.intel.com>

kv2019i · 2026-10-27T14:16:36Z

V5 pushed:

addressing the copilot reviews for V4

lgirdwood · 2026-10-27T20:06:11Z

@kv2019i I've created a new repo called sof-utils, I think this would be a good addition for sof-utiils. It would be a good addition if it could be used by the SOF topology builder. i.e. invoked from cmd line and its output parsed,

kv2019i · 2026-10-28T09:13:17Z

@lgirdwood Potentially, but can sof-utils use it from this repo. I'd like to keep this here as long as we have the topologies here, so the validator can be integrated tighly to the build process. IOW, people cannot build invalid topologies but will get errors already at build time. Alternatively we can add sof-utils to west manifest so it is always available for SOF builds.

kv2019i requested review from dbaluta, jsarha, lgirdwood and ranj063 as code owners October 23, 2026 11:08

kv2019i requested review from bardliao, lgirdwood, singalsu and ujfalusi and a balanced review from Copilot and removed request for Copilot, dbaluta, jsarha, lgirdwood and ranj063 October 23, 2026 11:08

Copilot stopped reviewing on behalf of kv2019i due to an error October 23, 2026 11:09
The job was not acquired by a runner even after multiple attempts.

Copilot started reviewing on behalf of kv2019i October 23, 2026 11:13

View session

lgirdwood approved these changes Oct 23, 2026

View reviewed changes

Copilot AI reviewed Oct 23, 2026

View reviewed changes

kv2019i force-pushed the 202610-tplg-validator-tool branch from 4890c28 to 62cb412 Compare October 26, 2026 13:47

kv2019i requested a balanced review from Copilot October 26, 2026 13:49

Copilot started reviewing on behalf of kv2019i October 26, 2026 13:53

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread tools/topology/topology2/production/CMakeLists.txt

Comment thread tools/topology/validator/checks/ipc4.py Outdated

Comment thread tools/topology/validator/checks/ipc4.py Outdated

This was referenced Oct 26, 2026

topology2: dmic-wov: fix KPB output pin binding to the host copier #11357

Open

tools: topology2: fixes to nocodec tplg #11358

Open

topology2: echo reference: route from loopback DAI only when it exists #11359

Closed

kv2019i force-pushed the 202610-tplg-validator-tool branch from 62cb412 to af80e2f Compare October 26, 2026 15:48

kv2019i force-pushed the 202610-tplg-validator-tool branch from af80e2f to d1a42b6 Compare October 27, 2026 09:26

kv2019i requested a balanced review from Copilot October 27, 2026 09:34

Copilot started reviewing on behalf of kv2019i October 27, 2026 09:35

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

kv2019i added 3 commits October 27, 2026 16:15

kv2019i force-pushed the 202610-tplg-validator-tool branch from d1a42b6 to 069ea43 Compare October 27, 2026 14:15

Conversation

kv2019i commented Oct 23, 2026

Uh oh!

lgirdwood left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

intel-sofci commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR 11344: test results

Uh oh!

kv2019i commented Oct 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kv2019i commented Oct 26, 2026

Uh oh!

kv2019i commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

kv2019i Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

kv2019i Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

kv2019i Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

kv2019i commented Oct 27, 2026

Uh oh!

lgirdwood commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kv2019i commented Oct 28, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

intel-sofci commented Oct 23, 2026 •

edited

Loading

lgirdwood commented Oct 27, 2026 •

edited

Loading