From 87ef382e445a74bc508ea267c76f0b0c27e997ba Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Wed, 22 Jul 2026 08:22:41 +0200 Subject: docs: dt: writing-schema: Extend expectations about example part of binding Document already used rules about example DTS in the binding: - All final device bindings (except sub-block of more complex devices) should have an example. - Phandles do not need to be resolvable - Sashiko already provided incorrect review, so this might help it to understand the concept. - Example should be complete, readable (use known defines), without 'status' property. Signed-off-by: Krzysztof Kozlowski Link: https://patch.msgid.link/20260722062240.19382-2-krzysztof.kozlowski@oss.qualcomm.com Signed-off-by: Rob Herring (Arm) --- Documentation/devicetree/bindings/writing-schema.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 3ffd0828617a..d31b94300f46 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -127,9 +127,16 @@ additionalProperties / unevaluatedProperties two above cases ('false'). examples - Optional. A list of one or more DTS hunks implementing this binding only. - Example should not contain unrelated device nodes, e.g. consumer nodes in a - provider binding, other nodes referenced by phandle. + Optional, although expected outside of bindings describing common properties + or sub-blocks of more complex devices. A list of one or more DTS hunks + implementing this binding only. Example should not contain unrelated device + nodes, e.g. consumer nodes in a provider binding, other nodes referenced by + phandles or node labels which are not directly referenced in the example + itself. Phandles in the example do not have to be resolvable. The example + must be complete as much as possible - have most of the properties - and look + readable to developers, thus for example use known defines for interrupt or + GPIO flags. Example should not contain 'status' property in typical cases. + Note: YAML doesn't allow leading tabs, so spaces must be used instead. Unless noted otherwise, all above schema properties are required. -- cgit v1.2.3