diff options
Diffstat (limited to 'Documentation/devicetree/index.rst')
| -rw-r--r-- | Documentation/devicetree/index.rst | 73 |
1 files changed, 67 insertions, 6 deletions
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 8c47d033fc..f85ce6608d 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,3 +1,5 @@ +.. _bareboxdt: + Barebox devicetree handling and bindings ======================================== @@ -35,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 / { @@ -60,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`` @@ -108,7 +143,33 @@ Contents: :maxdepth: 1 bindings/barebox/* + bindings/firmware/* bindings/leds/* bindings/misc/* bindings/mtd/* + bindings/power/* + bindings/regulator/* bindings/rtc/* + bindings/watchdog/* + +Automatic Boot Argument Fixups to the Devicetree +------------------------------------------------ + +barebox automatically fixes up some boot and system information in the device tree. + +In the device tree root, barebox fixes up + + * serial-number (if available) + * machine compatible (if overridden) + +In the ``chosen``-node, barebox fixes up + + * barebox-version + * reset-source + * reset-source-instance (if available) + * reset-source-device (node-path, only if available) + * bootsource + * boot-hartid (only on RISC-V) + +These values can be read from the booted linux system in ``/proc/device-tree/`` +or ``/sys/firmware/devicetree/base``. |