Documentation: devicetree: codify extension of upstream DTS by phandles

Sync with the upstream device tree repository has been a common cause
for breakage in barebox. Often unnoticed:

* New bindings are merged upstream and device trees migrated, but
  barebox didn't yet have support
* Nodes are renamed upstream, but barebox still extends the old name,
  with duplicate nodes resulting

We can solve the second one by requiring dtc to give us errors when
paths we extend no longer exist. Document how to do so.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

1 files changed, 43 insertions, 0 deletions

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 908652642b..c5478d1f85 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -31,6 +31,49 @@ device tree under ``dts/src/$ARCH`` with ``#include "$ARCH/board.dts"`` and
 then extends it with barebox-specifics like :ref:`barebox,state`,
 environment or boot-time device configuration.
 
+Device Tree probing largely happens via compatible properties with no special
+meaning to the node names themselves. It's thus paramount that any device tree
+nodes extended in the barebox device tree are referenced by a phandle, not by
+path, to avoid run-time breakage like this::
+
+  # Upstream dts/src/$ARCH/board.dts
+  / {
+  	leds {
+            led-red { /* formerly named red when the barebox DTS was written */
+            	/* ... */
+            };
+        };
+  };
+
+  # barebox arch/$ARCH/dts/board.dts
+  #include <$ARCH/board.dts>
+  / {
+  	leds {
+            red {
+                barebox,default-trigger = "heartbeat";
+            };
+        };
+  };
+
+In the previous example, a device tree sync with upstream resulted in a regression
+as the former override became a new node with a single property without effect.
+
+Using phandles avoids this. When no phandle mapping the full path is defined
+upstream, the ``&{/path}`` syntax should be used instead, e.g.::
+
+  &{/leds/red} {
+      barebox,default-trigger = "heartbeat";
+  };
+
+This would lead to a compile error should the ``/leds/red`` path be renamed or
+removed. This also applies to uses of ``/delete-node/``.
+
+Only exception to this rule are well-known node names that are specified by
+the `specification`_ to be parsed by name. These are: ``chosen``, ``aliases``
+and ``cpus``, but **not** ``memory``.
+
+.. _specification: https://www.devicetree.org/specifications/
+
 Device Tree Compiler
 --------------------