Reviewing DTS examples in binding YAML files for coding style is
tedious and repetitive. The rules in dts-coding-style.rst are well
defined but currently not enforced by any tooling -- dtc does not
care about whitespace, and yamllint only sees the YAML structure,
not the DTS content inside literal block scalars.

This series adds a Python script that produces a canonical form of
each DTS example and diffs it against the original. Any difference
is a style violation. The checks cover:

 - 4-space indentation per nesting level
 - property ordering (compatible, reg, ranges, standard, vendor, status)
 - child node ordering by unit address
 - blank line placement (before child nodes and status, nowhere else)
 - no trailing whitespace, no tabs in DTS lines
 - node names using only [a-z0-9-]
 - no unused labels (defined but never &-referenced)

The script uses only ruamel.yaml (already required by dtschema) and
has no other dependencies. It is wired into dt_binding_check_one
with || true, so currently informational.

Running it against the current tree finds issues in roughly 70% of
existing binding files -- mostly indentation (many older bindings
use 2-space indent) and unused labels. These can be cleaned up in
follow-up series; the immediate value is catching problems in new
submissions before reviewers have to.

A --diff flag produces unified diffs showing exactly what needs to
change, making fixes trivial. A future --fix mode could rewrite
examples in-place.

As someone who has repeatedly annoyed DT maintainers with exactly
the kind of mistakes this tool catches, I hope this makes up for
some of that. And since my Python is even much worse than my DTS
coding style, the script was written with generous help from
Claude Opus 4.6.

Daniel Golle (2):
  dt-bindings: add DTS example style checker
  dt-bindings: wire example style check into dt_binding_check

 Documentation/devicetree/bindings/Makefile |  15 +-
 scripts/dtc/dt-check-example-style         | 712 +++++++++++++++++++++
 2 files changed, 725 insertions(+), 2 deletions(-)
 create mode 100755 scripts/dtc/dt-check-example-style

-- 
2.53.0

On Mon, Apr 20, 2026 at 04:50:19PM +0100, Daniel Golle wrote:
> Reviewing DTS examples in binding YAML files for coding style is
> tedious and repetitive. The rules in dts-coding-style.rst are well
> defined but currently not enforced by any tooling -- dtc does not
> care about whitespace, and yamllint only sees the YAML structure,
> not the DTS content inside literal block scalars.
> 

Thanks for this!

> This series adds a Python script that produces a canonical form of
> each DTS example and diffs it against the original. Any difference
> is a style violation. The checks cover:
> 
>  - 4-space indentation per nesting level

I would like to see a way to disable 2 space indentation warnings. It's 
not something I think we should 'fix' treewide, so we can't have 
warnings for all of them. Perhaps just check for consistent indentation.

>  - property ordering (compatible, reg, ranges, standard, vendor, status)
>  - child node ordering by unit address

I would guess this is more a .dts issue as examples are mostly a single 
node.

>  - blank line placement (before child nodes and status, nowhere else)
>  - no trailing whitespace, no tabs in DTS lines

I think we already check this except for spaces followed by tabs. We 
might be able to add that to yamllint.

>  - node names using only [a-z0-9-]

This could be a schema. I actually have a WIP schema that I never 
finished. The check I had added was banning 'status' in examples.

>  - no unused labels (defined but never &-referenced)
> 
> The script uses only ruamel.yaml (already required by dtschema) and
> has no other dependencies. It is wired into dt_binding_check_one
> with || true, so currently informational.

One reason the binding checks are so slow is due to python start-up 
times. Part of the start-up time is module imports and IIRC ruamel.yaml 
is pretty slow. That's why dt-doc-validate is not called for each 
individual binding file for example and we shard it with xargs which you 
followed. But really, make wants to do things a file at a time.

We already parse the example once with dt-extract-example, so perhaps 
the best approach would be to run these checks at that point.

> Running it against the current tree finds issues in roughly 70% of
> existing binding files -- mostly indentation (many older bindings
> use 2-space indent) and unused labels. These can be cleaned up in
> follow-up series; the immediate value is catching problems in new
> submissions before reviewers have to.

'make dt_binding_check' must be warning free (with the exception of 
using dtschema main (unreleased) branch. So this will need to be 
reworked to maintain that to be mergeable.

I think this would be useful for .dts files too, so it would be good if 
the extract example part and checks could be separated. We already have 
code to extract examples, but then you lose some things like what the 
indentation should be. And implementing as a diff or automatic fix mode 
would be harder.

Rob