Commit b57ce963 authored by Krzysztof Kozlowski's avatar Krzysztof Kozlowski Committed by Rob Herring (Arm)
Browse files

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: default avatarKrzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: default avatarConor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-5-krzysztof.kozlowski@linaro.org


Signed-off-by: default avatarRob Herring (Arm) <robh@kernel.org>
parent 49ed6868

Documentation/devicetree/bindings/writing-bindings.rst

+22 −5
Original line number Diff line number Diff line
@@ -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

=========================