From b957f0c578987bc44371dfb28cfdc943b53dc6eb Mon Sep 17 00:00:00 2001 From: Ahmad Fatoum Date: Thu, 18 Jun 2020 11:11:02 +0200 Subject: 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 Signed-off-by: Sascha Hauer --- Documentation/devicetree/index.rst | 43 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'Documentation') 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 -------------------- -- cgit v1.2.3