diff options
Diffstat (limited to 'Documentation/devicetree')
| -rw-r--r-- | Documentation/devicetree/index.rst | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 70ff9bc74a..8c47d033fc 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -33,6 +33,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 -------------------- |