From a2009525ce97e59ec7066c90060f7810ab45eac2 Mon Sep 17 00:00:00 2001 From: Bjarki Arge Andreasen Date: Fri, 18 Jul 2025 13:50:18 +0200 Subject: [PATCH] doc: build: dts: bindings-syntax: clarify compat matching Clarify the identification and matching of bindings to devicetree node compats. The previous definition implicitly hinted at two bindings with the same compat being allowed, but did not state this clearly. The updated wording should make it clear exactly how bindings may be defined, and how they are matched. Signed-off-by: Bjarki Arge Andreasen --- doc/build/dts/bindings-syntax.rst | 46 ++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/doc/build/dts/bindings-syntax.rst b/doc/build/dts/bindings-syntax.rst index 1447a2e61653e..4c2ccf32a7183 100644 --- a/doc/build/dts/bindings-syntax.rst +++ b/doc/build/dts/bindings-syntax.rst @@ -124,11 +124,49 @@ match this node: compatible = "manufacturer,device-v2", "manufacturer,device"; }; -Each node's ``compatible`` property is tried in order. The first matching -binding is used. The :ref:`on-bus: ` key can be used to -refine the search. +Each node's ``compatible`` property is tried in order. The +:ref:`bindings ` are uniquely identified by a pair of +(:ref:`compatible `, +:ref:`on-bus `), where the +:ref:`on-bus ` may be unspecified. A specified +:ref:`on-bus ` takes precedence over unspecified. The +first matching binding is used. -If more than one binding for a compatible is found, an error is raised. +For the following device: + +.. code-block:: devicetree + + spi-bus { + device-3 { + compatible = "manufacturer,device"; + }; + }; + +The following two bindings can coexist and would match in the following order: + +``manufacturer,device-spi.yaml`` + +.. code-block:: YAML + + compatible: "manufacturer,device" + on-bus: spi + +``manufacturer,device.yaml`` + +.. code-block:: YAML + + compatible: "manufacturer,device" + +The following binding can coexist but would not match. + +``manufacturer,device-i2c.yaml`` + +.. code-block:: YAML + + compatible: "manufacturer,device" + on-bus: i2c + +If more than one matching binding for a compatible is found, an error is raised. The ``manufacturer`` prefix identifies the device vendor. See :zephyr_file:`dts/bindings/vendor-prefixes.txt` for a list of accepted vendor