From 68801feea99d89f6ddd6a2a8ea218033e14d08d0 Mon Sep 17 00:00:00 2001 From: Ahmad Fatoum Date: Fri, 17 Feb 2023 18:30:40 +0100 Subject: Documentation: devicetree: describe new label-relative-path syntax 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 Link: https://lore.barebox.org/20230217173057.1839835-4-a.fatoum@pengutronix.de Signed-off-by: Sascha Hauer --- Documentation/devicetree/index.rst | 45 +++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 61ac0433fb..36fa69058d 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`` -- cgit v1.2.1