From: Krzysztof Kozlowski Date: Thu, 4 Sep 2025 14:24:01 +0000 (+0200) Subject: docs: dt: writing-schema: Describe defining properties in top-level X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=3ef9c995fa51a90b08b0cc8d2951acb53c38936c;p=users%2Fhch%2Fmisc.git 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) --- diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index fcd4726f8df4..05c34248e544 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 ------------