[PATCH v1 03/20] Documentation: devicetree: describe new label-relative-path syntax

[Ahmad Fatoum]

For use in barebox, DTC v1.7.0 now allows constructing labels that are
comprised of a parent label and a relative path. This is a middle ground
for when no suitable label is defined upstream and a full path is too
verbose and more likely to cause breakages that could've been avoided
by restricting the path component. Describe this in the docs.

Signed-off-by: Ahmad Fatoum <a.fatoum at pengutronix.de>
---
 Documentation/devicetree/index.rst | 45 ++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 6 deletions(-)

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 61ac0433fb41..36fa69058d1d 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -37,8 +37,8 @@ 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::
+nodes extended in the barebox device tree are referenced by label (e.g.
+``<&phandle>``, not by path, to avoid run-time breakage like this::
 
   # Upstream dts/src/$ARCH/board.dts
   / {
@@ -62,15 +62,48 @@ path, to avoid run-time breakage like this::
 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.::
+The preferred way around this is to use labels directly::
+
+  # Upstream dts/src/$ARCH/board.dts
+  / {
+  	leds {
+            status_led: red { };
+        };
+  };
+
+  # barebox arch/$ARCH/dts/board.dts
+  #include <$ARCH/board.dts>
+
+  &status_led {
+      barebox,default-trigger = "heartbeat";
+  };
+
+If there's no label defined upstream for the node, but for a parent,
+a new label can be constructed from that label and a relative path::
+
+  # Upstream dts/src/$ARCH/board.dts
+  / {
+  	led_controller: leds {
+            red { };
+        };
+  };
+
+  # barebox arch/$ARCH/dts/board.dts
+  #include <$ARCH/board.dts>
+
+  &{led_controller/red} {
+      barebox,default-trigger = "heartbeat";
+  };
+
+As last resort, the full path shall be used::
 
   &{/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/``.
+Any of these three approaches 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``
-- 
2.30.2