123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134 |
- .. SPDX-License-Identifier: GPL-2.0+
- .. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
- Device Tree Overlays
- ====================
- Overlay Syntax
- --------------
- Device-tree overlays require a slightly different syntax compared to traditional
- device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
- sources for information regarding the internal format of overlays:
- https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
- Building Overlays
- -----------------
- In a nutshell overlays provides a means to manipulate a symbol a previous
- device-tree or device-tree overlay has defined. It requires both the base
- device-tree and all the overlays to be compiled with the *-@* command line
- switch of the device-tree compiler so that symbol information is included.
- Note
- Support for *-@* option can only be found in dtc version 1.4.4 or newer.
- Only version 4.14 or higher of the Linux kernel includes a built in version
- of dtc that meets this requirement.
- Building a binary device-tree overlay follows the same process as building a
- traditional binary device-tree. For example:
- **base.dts**
- ::
- /dts-v1/;
- / {
- foo: foonode {
- foo-property;
- };
- };
- .. code-block:: console
- $ dtc -@ -I dts -O dtb -o base.dtb base.dts
- **overlay.dts**
- ::
- /dts-v1/;
- /plugin/;
- / {
- fragment@1 {
- target = <&foo>;
- __overlay__ {
- overlay-1-property;
- bar: barnode {
- bar-property;
- };
- };
- };
- };
- .. code-block:: console
- $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
- Ways to Utilize Overlays in U-Boot
- ----------------------------------
- There are two ways to apply overlays in U-Boot.
- * Include and define overlays within a FIT image and have overlays
- automatically applied.
- * Manually load and apply overlays
- The remainder of this document will discuss using overlays via the manual
- approach. For information on using overlays as part of a FIT image please see:
- doc/uImage.FIT/overlay-fdt-boot.txt
- Manually Loading and Applying Overlays
- --------------------------------------
- 1. Figure out where to place both the base device tree blob and the
- overlay. Make sure you have enough space to grow the base tree without
- overlapping anything.
- ::
- => setenv fdtaddr 0x87f00000
- => setenv fdtovaddr 0x87fc0000
- 2. Load the base binary device-tree and the binary device-tree overlay.
- ::
- => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
- => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
- 3. Set the base binary device-tree as the working fdt tree.
- ::
- => fdtaddr $fdtaddr
- 4. Grow it enough so it can encompass all applied overlays
- ::
- => fdt resize 8192
- 5. You are now ready to apply the overlay.
- ::
- => fdt apply $fdtovaddr
- 6. Boot system like you would do with a traditional dtb.
- For bootm:
- ::
- => bootm ${kerneladdr} - ${fdtaddr}
- For bootz:
- ::
- => bootz ${kerneladdr} - ${fdtaddr}
- Please note that in case of an error, both the base and overlays are going
- to be invalidated, so keep copies to avoid reloading.
|