[PATCH] docs: dt: writing-bindings: Document node name ABI and simple-mfd

[PATCH] docs: dt: writing-bindings: Document node name ABI and simple-mfd

[Krzysztof Kozlowski]

Document established Devicetree bindings maintainers review practice:

1. Device node names should not be treated as an ABI, unless for
   children of a device when documented.
   There were many patches posted using of_find_node_by_name() or
   of_node_name_eq() for accessing siblings or completely different
   nodes.  These cases were introducing undocumented ABI, so they are
   discouraged.

2. 'simple-mfd' means children do not depend on parent device resources.
   'simple-bus' is so simple, that even 'reg' properties are not
   applicable.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 Documentation/devicetree/bindings/writing-bindings.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index f8e0293a7c06..667816dd7d50 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -31,10 +31,19 @@ Overall design
   devices only need child nodes when the child nodes have their own DT
   resources. A single node can be multiple providers (e.g. clocks and resets).
 
+- DON'T treat device node names as a stable ABI, but instead use phandles or
+  compatibles to find sibling devices. Exception: sub-nodes of given device
+  could be treated as ABI, if explicitly documented in the bindings.
+
 - DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
   hardware block should have a compatible string unique enough to infer the
   register layout of the entire block (at a minimum).
 
+- DON'T use 'simple-mfd' compatible for non-trivial devices, where children
+  depend on some resources from the parent. Similarly, 'simple-bus' should not
+  be used for complex buses and even 'regs' property means device is not
+  a simple bus.
+
 
 Properties
 ==========
-- 
2.48.1

Re: [PATCH] docs: dt: writing-bindings: Document node name ABI and simple-mfd

[Rob Herring (Arm)]

On Mon, 18 Aug 2025 15:25:35 +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> 
> 1. Device node names should not be treated as an ABI, unless for
>    children of a device when documented.
>    There were many patches posted using of_find_node_by_name() or
>    of_node_name_eq() for accessing siblings or completely different
>    nodes.  These cases were introducing undocumented ABI, so they are
>    discouraged.
> 
> 2. 'simple-mfd' means children do not depend on parent device resources.
>    'simple-bus' is so simple, that even 'reg' properties are not
>    applicable.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 

Applied, thanks!