From 3ef9c995fa51a90b08b0cc8d2951acb53c38936c Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Thu, 4 Sep 2025 16:24:01 +0200 Subject: [PATCH] docs: dt: writing-schema: Describe defining properties in top-level Document established Devicetree bindings maintainers review practice: Properties having differences per each device in the binding, e.g. different constraints for lists or different allowed values, should still be defined in top-level 'properties' section and only customized in 'if:then:'. Signed-off-by: Krzysztof Kozlowski Link: https://lore.kernel.org/r/20250904142400.179955-2-krzysztof.kozlowski@linaro.org Signed-off-by: Rob Herring (Arm) --- Documentation/devicetree/bindings/writing-schema.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index fcd4726f8df4c..05c34248e5447 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar values a matrix (in order to define groupings) even when only a single value is present. Single entries in schemas are fixed up to match this encoding. +When bindings cover multiple similar devices that differ in some properties, +those properties should be constrained for each device. This usually means: + + * In top level 'properties' define the property with the broadest constraints. + * In 'if:then:' blocks, further narrow the constraints for those properties. + * Do not define the properties within an 'if:then:' block (note that + 'additionalItems' also won't allow that). + Coding style ------------ -- 2.47.3