1 .. SPDX-License-Identifier: GPL-2.0+
2 .. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
10 Device-tree overlays require a slightly different syntax compared to traditional
11 device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
12 sources for information regarding the internal format of overlays:
13 https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
18 In a nutshell overlays provides a means to manipulate a symbol a previous
19 device-tree or device-tree overlay has defined. It requires both the base
20 device-tree and all the overlays to be compiled with the *-@* command line
21 switch of the device-tree compiler so that symbol information is included.
24 Support for *-@* option can only be found in dtc version 1.4.4 or newer.
25 Only version 4.14 or higher of the Linux kernel includes a built in version
26 of dtc that meets this requirement.
28 Building a binary device-tree overlay follows the same process as building a
29 traditional binary device-tree. For example:
42 .. code-block:: console
44 $ dtc -@ -I dts -O dtb -o base.dtb base.dts
64 .. code-block:: console
66 $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
68 Ways to Utilize Overlays in U-Boot
69 ----------------------------------
71 There are two ways to apply overlays in U-Boot.
73 * Include and define overlays within a FIT image and have overlays
74 automatically applied.
76 * Manually load and apply overlays
78 The remainder of this document will discuss using overlays via the manual
79 approach. For information on using overlays as part of a FIT image please see:
80 doc/uImage.FIT/overlay-fdt-boot.txt
82 Manually Loading and Applying Overlays
83 --------------------------------------
85 1. Figure out where to place both the base device tree blob and the
86 overlay. Make sure you have enough space to grow the base tree without
91 => setenv fdtaddr 0x87f00000
92 => setenv fdtovaddr 0x87fc0000
94 2. Load the base binary device-tree and the binary device-tree overlay.
98 => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
99 => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
101 3. Set the base binary device-tree as the working fdt tree.
107 4. Grow it enough so it can encompass all applied overlays
113 5. You are now ready to apply the overlay.
117 => fdt apply $fdtovaddr
119 6. Boot system like you would do with a traditional dtb.
125 => bootm ${kerneladdr} - ${fdtaddr}
131 => bootz ${kerneladdr} - ${fdtaddr}
133 Please note that in case of an error, both the base and overlays are going
134 to be invalidated, so keep copies to avoid reloading.