diff options
author | Ahmad Fatoum <a.fatoum@pengutronix.de> | 2023-02-17 18:30:40 +0100 |
---|---|---|
committer | Sascha Hauer <s.hauer@pengutronix.de> | 2023-02-22 07:19:40 +0100 |
commit | 68801feea99d89f6ddd6a2a8ea218033e14d08d0 (patch) | |
tree | bd97bc8af6350212bc84c0417ed523d678c3e951 /Documentation | |
parent | 4d28b4cf797adab9447519530423aeadc61b5286 (diff) | |
download | barebox-68801feea99d89f6ddd6a2a8ea218033e14d08d0.tar.gz |
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 <a.fatoum@pengutronix.de>
Link: https://lore.barebox.org/20230217173057.1839835-4-a.fatoum@pengutronix.de
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/devicetree/index.rst | 45 |
1 files changed, 39 insertions, 6 deletions
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`` |