From: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Date: Mon, 7 Jul 2025 09:50:21 +0000 (+0200)
Subject: docs: dt: writing-bindings: Express better expectations of "specific"
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b57ce9630bab1a468643fd5fb34d42cb936f0cb0;p=thirdparty%2Flinux.git

docs: dt: writing-bindings: Express better expectations of "specific"

Devicetree bindings are supposed to be specific in terms of compatibles
and other properties.  Short "specific" has many implications, so extend
the description to cover them:

1. Mention no family names and avoid generic SoC fallbacks in
   compatible.  The list grew, mixing DO's and DON'T's, so split it into
   multiple items.

2. No properties implied by the compatible.

3. Document desired lack of ABI impact and acceptable solution if such
   needs arises: clearly marking it in commit msg.

All above follows established Devicetree bindings maintainers review
practice, so no new rules in practice are introduced here.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-5-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
---

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 66c94b5adc871..962e38a1751a5 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -39,10 +39,18 @@ Overall design
 Properties
 ==========
 
-- DO make 'compatible' properties specific. DON'T use wildcards in compatible
-  strings. DO use fallback compatibles when devices are the same as or a
-  superset of prior implementations. DO add new compatibles in case there are
-  new features or bugs.
+- DO make 'compatible' properties specific.
+
+   - DON'T use wildcards or device-family names in compatible strings.
+
+   - DO use fallback compatibles when devices are the same as or a superset of
+     prior implementations.
+
+   - DO add new compatibles in case there are new features or bugs.
+
+   - DO use a SoC-specific compatible for all SoC devices, followed by a
+     fallback if appropriate. SoC-specific compatibles are also preferred for
+     the fallbacks.
 
 - DO use a vendor prefix on device-specific property names. Consider if
   properties could be common among devices of the same class. Check other
@@ -51,12 +59,21 @@ Properties
 - DON'T redefine common properties. Just reference the definition and define
   constraints specific to the device.
 
+- DON'T add properties to avoid a specific compatible. DON'T add properties if
+  they are implied by (deducible from) the compatible.
+
 - DO use common property unit suffixes for properties with scientific units.
   Recommended suffixes are listed at
   https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
 
 - DO define properties in terms of constraints. How many entries? What are
-  possible values? What is the order?
+  possible values? What is the order? All these constraints represent the ABI
+  as well.
+
+- DON'T make changes that break the ABI without explicit and detailed rationale
+  for why the changes have to be made and their impact. ABI impact goes beyond
+  the Linux kernel, because it also covers other open-source upstream projects.
+
 
 Typical cases and caveats
 =========================