1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
3
4Device Tree Overlays
5====================
6
7Overlay Syntax
8--------------
9
10Device-tree overlays require a slightly different syntax compared to traditional
11device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
12sources for information regarding the internal format of overlays:
13https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
14
15Building Overlays
16-----------------
17
18In a nutshell overlays provides a means to manipulate a symbol a previous
19device-tree or device-tree overlay has defined. It requires both the base
20device-tree and all the overlays to be compiled with the *-@* command line
21switch of the device-tree compiler so that symbol information is included.
22
23Note
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.
27
28Building a binary device-tree overlay follows the same process as building a
29traditional binary device-tree. For example:
30
31**base.dts**
32
33::
34
35	/dts-v1/;
36	/ {
37		foo: foonode {
38			foo-property;
39		};
40	};
41
42.. code-block:: console
43
44	$ dtc -@ -I dts -O dtb -o base.dtb base.dts
45
46**overlay.dts**
47
48::
49
50	/dts-v1/;
51	/plugin/;
52	/ {
53		fragment@1 {
54			target = <&foo>;
55			__overlay__ {
56				overlay-1-property;
57				bar: barnode {
58					bar-property;
59				};
60			};
61		};
62	};
63
64.. code-block:: console
65
66	$ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
67
68Ways to Utilize Overlays in U-Boot
69----------------------------------
70
71There are two ways to apply overlays in U-Boot.
72
73* Include and define overlays within a FIT image and have overlays
74  automatically applied.
75
76* Manually load and apply overlays
77
78The remainder of this document will discuss using overlays via the manual
79approach. For information on using overlays as part of a FIT image please see:
80doc/uImage.FIT/overlay-fdt-boot.txt
81
82Manually Loading and Applying Overlays
83--------------------------------------
84
851. 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
87   overlapping anything.
88
89::
90
91    => setenv fdtaddr 0x87f00000
92    => setenv fdtovaddr 0x87fc0000
93
942. Load the base binary device-tree and the binary device-tree overlay.
95
96::
97
98    => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
99    => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
100
1013. Set the base binary device-tree as the working fdt tree.
102
103::
104
105    => fdtaddr $fdtaddr
106
1074. Grow it enough so it can encompass all applied overlays
108
109::
110
111    => fdt resize 8192
112
1135. You are now ready to apply the overlay.
114
115::
116
117    => fdt apply $fdtovaddr
118
1196. Boot system like you would do with a traditional dtb.
120
121For bootm:
122
123::
124
125    => bootm ${kerneladdr} - ${fdtaddr}
126
127For bootz:
128
129::
130
131    => bootz ${kerneladdr} - ${fdtaddr}
132
133Please note that in case of an error, both the base and overlays are going
134to be invalidated, so keep copies to avoid reloading.
135