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

docs: dt: writing-bindings: Document compatible and filename naming 



Document established Devicetree bindings maintainers review practices:

1. Compatibles should not use bus suffixes to encode the type of
   interface, because the parent bus node defines that interface, e.g.
   "vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".

2. If the compatible represents the device as a whole, it should not
   contain the type of device in the name.

3. Filenames should match compatible.  The best if match is 100%, but if
   binding has multiple compatibles, then one of the fallbacks should be
   used.  Alternatively a genericish name is allowed if it follows
   "vendor,device" style.

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/20250713-dt-bindings-docs-v2-2-672c898054ae@linaro.org


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

Documentation/devicetree/bindings/writing-bindings.rst

+8 −0
Original line number Diff line number Diff line
@@ -52,6 +52,10 @@ Properties 
     fallback if appropriate. SoC-specific compatibles are also preferred for

     the fallbacks.



   - DON'T use bus suffixes to encode the type of interface device is using.

     The parent bus node already implies that interface.  DON'T add the type of

     device, if the device cannot be anything else.



- DO use a vendor prefix on device-specific property names. Consider if

  properties could be common among devices of the same class. Check other

  existing bindings for similar devices.
@@ -101,6 +105,10 @@ Typical cases and caveats 
- "syscon" is not a generic property. Use vendor and type, e.g.

  "vendor,power-manager-syscon".



- Bindings files should be named like compatible: vendor,device.yaml. In case

  of multiple compatibles in the binding, use one of the fallbacks or a more

  generic name, yet still matching compatible style.



Board/SoC .dts Files

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