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: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250713-dt-bindings-docs-v2-2-672c898054ae@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 a2d2afd099c0bd922cf12dcf49f5dffe6da748f1..e63de88385b5bc5859d8d9fca82bcf30380f3e73 100644 (file)
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -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
 ====================