|
@@ -0,0 +1,134 @@
|
|
|
+.. 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.
|