Message-ID: <20250702161700.229458-2-krzysztof.kozlowski@linaro.org>
Date: Wed,  2 Jul 2025 18:17:01 +0200
From: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
To: Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>,
	devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org
Cc: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Subject: [PATCH] docs: dt: writing-bindings: Express better expectation 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: no family names, avoid generic SoC
fallbacks, avoid versioned compatibles, avoid properties implied by
compatible.

Also 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 are introduced here.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>

---

I have vast (~10-page) document describing DT bindings and DTS rules,
based on Rob's and other people's reviews (with references...). Let me
try to funnel it here gradually. Why gradually? The intention of
writing-bindings document is to be concise, so rephrasing my 10 pages
covering each little detail into generic, concise rule is not that easy,
especially for non-native speaker.

Optionally I could also post my 10-page guide somewhere, but then it
would be one more document to ignore. I think we have enough of such.
Ah, and I would have one less topic for conference. :)
---
 .../devicetree/bindings/writing-bindings.rst  | 25 +++++++++++++++----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 1ad081de2dd0..dc0e4b63984c 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -39,10 +39,15 @@ 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 subset
-  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 subset of prior implementations. DO add new
+  compatibles in case there are new features or bugs.
+
+   - Use SoC-specific compatible for all SoC devices, followed by a fallback if
+     appropriate.
+
+   - Specific SoC compatible is 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 +56,22 @@ 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 change the ABI, but if ever needed to change, then DO explicitly
+  document that in the commit msg with rationale WHY ABI has to be broken and
+  what is the impact. ABI impact is beyond Linux kernel, because it covers also
+  other open-source upstream projects.
+
 
 Typical cases and caveats
 =========================
-- 
2.43.0

Powered by blists - more mailing lists