[PATCH v2 1/3] docs: dt: writing-bindings: Rephrase typical fallback (superset) usage

[PATCH v2 1/3] docs: dt: writing-bindings: Rephrase typical fallback (superset) usage

[Krzysztof Kozlowski]

When speaking about compatibles for new devices comparing to "prior
implementations", usually we expect new device to come with more
features, thus logically it is a superset, not subset, of "prior
implementations".

Suggested-by: Conor Dooley <conor@kernel.org>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. New patch, superset suggested by Conor.
---
 Documentation/devicetree/bindings/writing-bindings.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 1ad081de2dd0..66c94b5adc87 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -40,9 +40,9 @@ 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.
+  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 vendor prefix on device-specific property names. Consider if
   properties could be common among devices of the same class. Check other
-- 
2.43.0

[PATCH v2 2/3] docs: dt: writing-bindings: Express better expectations of "specific"

[Krzysztof Kozlowski]

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>

---

Changes in v2:
Implement entire Conor's feedback:
1. Grammar
2. Split DO/DON'T in compatible section
3. Rephrase the ABI break
---
 .../devicetree/bindings/writing-bindings.rst  | 27 +++++++++++++++----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 66c94b5adc87..962e38a1751a 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
 =========================
-- 
2.43.0

[PATCH v2 3/3] docs: dt: writing-bindings: Consistently use single-whitespace

[Krzysztof Kozlowski]

Document uses only single whitespace after full stop, so fix
inconsistency.

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

---

Changes in v2:
1. New patch
---
 Documentation/devicetree/bindings/writing-bindings.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 962e38a1751a..a2d2afd099c0 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -81,7 +81,7 @@ Typical cases and caveats
 - Phandle entries, like clocks/dmas/interrupts/resets, should always be
   explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
   more than one phandle. When used, both of these fields need the same
-  constraints (e.g.  list of items).
+  constraints (e.g. list of items).
 
 - For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
   e.g.: "tx" instead of "txirq" (for interrupt).
-- 
2.43.0

Re: [PATCH v2 1/3] docs: dt: writing-bindings: Rephrase typical fallback (superset) usage

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 480 bytes --]

On Mon, Jul 07, 2025 at 11:50:20AM +0200, Krzysztof Kozlowski wrote:
> When speaking about compatibles for new devices comparing to "prior
> implementations", usually we expect new device to come with more
> features, thus logically it is a superset, not subset, of "prior
> implementations".
> 
> Suggested-by: Conor Dooley <conor@kernel.org>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 2/3] docs: dt: writing-bindings: Express better expectations of "specific"

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 876 bytes --]

On Mon, Jul 07, 2025 at 11:50:21AM +0200, Krzysztof Kozlowski wrote:
> 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>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 3/3] docs: dt: writing-bindings: Consistently use single-whitespace

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 285 bytes --]

On Mon, Jul 07, 2025 at 11:50:22AM +0200, Krzysztof Kozlowski wrote:
> Document uses only single whitespace after full stop, so fix
> inconsistency.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/3] docs: dt: writing-bindings: Rephrase typical fallback (superset) usage

[Rob Herring (Arm)]

On Mon, 07 Jul 2025 11:50:20 +0200, Krzysztof Kozlowski wrote:
> When speaking about compatibles for new devices comparing to "prior
> implementations", usually we expect new device to come with more
> features, thus logically it is a superset, not subset, of "prior
> implementations".
> 
> Suggested-by: Conor Dooley <conor@kernel.org>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. New patch, superset suggested by Conor.
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 

Applied, thanks!

Re: [PATCH v2 2/3] docs: dt: writing-bindings: Express better expectations of "specific"

[Rob Herring (Arm)]

On Mon, 07 Jul 2025 11:50:21 +0200, Krzysztof Kozlowski wrote:
> 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>
> 
> ---
> 
> Changes in v2:
> Implement entire Conor's feedback:
> 1. Grammar
> 2. Split DO/DON'T in compatible section
> 3. Rephrase the ABI break
> ---
>  .../devicetree/bindings/writing-bindings.rst  | 27 +++++++++++++++----
>  1 file changed, 22 insertions(+), 5 deletions(-)
> 

Applied, thanks!

Re: [PATCH v2 3/3] docs: dt: writing-bindings: Consistently use single-whitespace

[Rob Herring (Arm)]

On Mon, 07 Jul 2025 11:50:22 +0200, Krzysztof Kozlowski wrote:
> Document uses only single whitespace after full stop, so fix
> inconsistency.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 

Applied, thanks!