xref: /openbmc/u-boot/doc/README.fdt-overlays (revision 66dae3bb)
1U-Boot FDT Overlay usage
2=============================================
3
4Overlays Syntax
5---------------
6
7Overlays require slightly different syntax compared to traditional overlays.
8Please refer to dt-object-internal.txt in the dtc sources for information
9regarding the internal format of overlays:
10https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
11
12Building Overlays
13-----------------
14
15In a nutshell overlays provides a means to manipulate a symbol a previous dtb
16or overlay has defined. It requires both the base and all the overlays
17to be compiled with the -@ command line switch so that symbol information is
18included.
19
20Note support for -@ option can only be found in dtc version 1.4.4 or newer.
21Only version 4.14 or higher of the Linux kernel includes a built in version
22of dtc that meets this requirement.
23
24Building an overlay follows the same process as building a traditional dtb.
25
26For example:
27
28base.dts
29--------
30
31	/dts-v1/;
32	/ {
33		foo: foonode {
34			foo-property;
35		};
36	};
37
38	$ dtc -@ -I dts -O dtb -o base.dtb base.dts
39
40bar.dts
41-------
42
43	/dts-v1/;
44	/plugin/;
45	/ {
46		fragment@1 {
47			target = <&foo>;
48			__overlay__ {
49				overlay-1-property;
50				bar: barnode {
51					bar-property;
52				};
53			};
54		};
55	};
56
57	$ dtc -@ -I dts -O dtb -o bar.dtb bar.dts
58
59Ways to Utilize Overlays in U-boot
60----------------------------------
61
62There are two ways to apply overlays in U-boot.
631. Include and define overlays within a FIT image and have overlays
64   automatically applied.
65
662. Manually load and apply overlays
67
68The remainder of this document will discuss using overlays via the manual
69approach. For information on using overlays as part of a FIT image please see:
70doc/uImage.FIT/overlay-fdt-boot.txt
71
72Manually Loading and Applying Overlays
73--------------------------------------
74
751. Figure out where to place both the base device tree blob and the
76overlay. Make sure you have enough space to grow the base tree without
77overlapping anything.
78
79=> setenv fdtaddr 0x87f00000
80=> setenv fdtovaddr 0x87fc0000
81
822. Load the base blob and overlay blobs
83
84=> load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
85=> load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtb
86
873. Set it as the working fdt tree.
88
89=> fdtaddr $fdtaddr
90
914. Grow it enough so it can 'fit' all the applied overlays
92
93=> fdt resize 8192
94
955. You are now ready to apply the overlay.
96
97=> fdt apply $fdtovaddr
98
996. Boot system like you would do with a traditional dtb.
100
101For bootm:
102
103=> bootm ${kerneladdr} - ${fdtaddr}
104
105For bootz:
106
107=> bootz ${kerneladdr} - ${fdtaddr}
108
109Please note that in case of an error, both the base and overlays are going
110to be invalidated, so keep copies to avoid reloading.
111
112Pantelis Antoniou
113pantelis.antoniou@konsulko.com
11411/7/2017
115