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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-ID: <20250818132534.120217-2-krzysztof.kozlowski@linaro.org>
Date: Mon, 18 Aug 2025 15:25:35 +0200
From: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
To: Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>,
	devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org
Cc: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Subject: [PATCH] docs: dt: writing-bindings: Document node name ABI and simple-mfd

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@...aro.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