]> git.ipfire.org Git - thirdparty/linux.git/commitdiff
docs: dt: writing-bindings: Document discouraged instance IDs
authorKrzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Sun, 13 Jul 2025 12:46:38 +0000 (14:46 +0200)
committerRob Herring (Arm) <robh@kernel.org>
Mon, 14 Jul 2025 21:23:52 +0000 (16:23 -0500)
Document established Devicetree bindings maintainers review practice:
instance indexes, either as properties or as custom new OF alias, are
not accepted.  Recommended way is to use, depending on the
situation/hardware: different compatible, cell arguments or syscon
phandle arguments.

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-3-672c898054ae@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
Documentation/devicetree/bindings/writing-bindings.rst

index e63de88385b5bc5859d8d9fca82bcf30380f3e73..f8e0293a7c0621a343a493d448624bff916ba021 100644 (file)
@@ -105,6 +105,11 @@ Typical cases and caveats
 - "syscon" is not a generic property. Use vendor and type, e.g.
   "vendor,power-manager-syscon".
 
+- Do not add instance index (IDs) properties or custom OF aliases.  If the
+  devices have different programming model, they might need different
+  compatibles.  If such devices use some other device in a different way, e.g.
+  they program the phy differently, use cell/phandle arguments.
+
 - 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.