[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@xxxxxxxxxx>
---
 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