.. 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. :: => fdt addr $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.