xref: /rk3399_rockchip-uboot/doc/uImage.FIT/overlay-fdt-boot.txt (revision b8631b11ec8643dabd94eae4997742f2db322488) 
1U-Boot FDT Overlay usage
2========================
3
4Introduction
5------------
6In many cases it is desirable to have a single FIT image support a multitude
7of similar boards and their expansion options. The same kernel on DT enabled
8platforms can support this easily enough by providing a DT blob upon boot
9that matches the desired configuration.
10
11Configuration without overlays
12------------------------------
13
14Take a hypothetical board named 'foo' where there are different supported
15revisions, reva and revb. Assume that both board revisions can use add a bar
16add-on board, while only the revb board can use a baz add-on board.
17
18Without using overlays the configuration would be as follows for every case.
19
20	/dts-v1/;
21	/ {
22		images {
23			kernel@1 {
24				data = /incbin/("./zImage");
25				type = "kernel";
26				arch = "arm";
27				os = "linux";
28				load = <0x82000000>;
29				entry = <0x82000000>;
30			};
31			fdt@1 {
32				data = /incbin/("./foo-reva.dtb");
33				type = "flat_dt";
34				arch = "arm";
35			};
36			fdt@2 {
37				data = /incbin/("./foo-revb.dtb");
38				type = "flat_dt";
39				arch = "arm";
40			};
41			fdt@3 {
42				data = /incbin/("./foo-reva-bar.dtb");
43				type = "flat_dt";
44				arch = "arm";
45			};
46			fdt@4 {
47				data = /incbin/("./foo-revb-bar.dtb");
48				type = "flat_dt";
49				arch = "arm";
50			};
51			fdt@5 {
52				data = /incbin/("./foo-revb-baz.dtb");
53				type = "flat_dt";
54				arch = "arm";
55			};
56			fdt@6 {
57				data = /incbin/("./foo-revb-bar-baz.dtb");
58				type = "flat_dt";
59				arch = "arm";
60			};
61		};
62
63		configurations {
64			default = "foo-reva.dtb;
65			foo-reva.dtb {
66				kernel = "kernel@1";
67				fdt = "fdt@1";
68			};
69			foo-revb.dtb {
70				kernel = "kernel@1";
71				fdt = "fdt@2";
72			};
73			foo-reva-bar.dtb {
74				kernel = "kernel@1";
75				fdt = "fdt@3";
76			};
77			foo-revb-bar.dtb {
78				kernel = "kernel@1";
79				fdt = "fdt@4";
80			};
81			foo-revb-baz.dtb {
82				kernel = "kernel@1";
83				fdt = "fdt@5";
84			};
85			foo-revb-bar-baz.dtb {
86				kernel = "kernel@1";
87				fdt = "fdt@6";
88			};
89		};
90	};
91
92Note the blob needs to be compiled for each case and the combinatorial explosion of
93configurations. A typical device tree blob is in the low hunderds of kbytes so a
94multitude of configuration grows the image quite a bit.
95
96Booting this image is done by using
97
98	# bootm <addr>#<config>
99
100Where config is one of:
101	foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
102	foo-revb-baz.dtb, foo-revb-bar-baz.dtb
103
104This selects the DTB to use when booting.
105
106Configuration using overlays
107----------------------------
108
109Device tree overlays can be applied to a base DT and result in the same blob
110being passed to the booting kernel. This saves on space and avoid the combinatorial
111explosion problem.
112
113	/dts-v1/;
114	/ {
115		images {
116			kernel@1 {
117				data = /incbin/("./zImage");
118				type = "kernel";
119				arch = "arm";
120				os = "linux";
121				load = <0x82000000>;
122				entry = <0x82000000>;
123			};
124			fdt@1 {
125				data = /incbin/("./foo.dtb");
126				type = "flat_dt";
127				arch = "arm";
128				load = <0x87f00000>;
129			};
130			fdt@2 {
131				data = /incbin/("./reva.dtbo");
132				type = "flat_dt";
133				arch = "arm";
134				load = <0x87fc0000>;
135			};
136			fdt@3 {
137				data = /incbin/("./revb.dtbo");
138				type = "flat_dt";
139				arch = "arm";
140				load = <0x87fc0000>;
141			};
142			fdt@4 {
143				data = /incbin/("./bar.dtbo");
144				type = "flat_dt";
145				arch = "arm";
146				load = <0x87fc0000>;
147			};
148			fdt@5 {
149				data = /incbin/("./baz.dtbo");
150				type = "flat_dt";
151				arch = "arm";
152				load = <0x87fc0000>;
153			};
154		};
155
156		configurations {
157			default = "foo-reva.dtb;
158			foo-reva.dtb {
159				kernel = "kernel@1";
160				fdt = "fdt@1", "fdt@2";
161			};
162			foo-revb.dtb {
163				kernel = "kernel@1";
164				fdt = "fdt@1", "fdt@3";
165			};
166			foo-reva-bar.dtb {
167				kernel = "kernel@1";
168				fdt = "fdt@1", "fdt@2", "fdt@4";
169			};
170			foo-revb-bar.dtb {
171				kernel = "kernel@1";
172				fdt = "fdt@1", "fdt@3", "fdt@4";
173			};
174			foo-revb-baz.dtb {
175				kernel = "kernel@1";
176				fdt = "fdt@1", "fdt@3", "fdt@5";
177			};
178			foo-revb-bar-baz.dtb {
179				kernel = "kernel@1";
180				fdt = "fdt@1", "fdt@3", "fdt@4", "fdt@5";
181			};
182			bar {
183				fdt = "fdt@4";
184			};
185			baz {
186				fdt = "fdt@5";
187			};
188		};
189	};
190
191Booting this image is exactly the same as the non-overlay example.
192u-boot will retrieve the base blob and apply the overlays in sequence as
193they are declared in the configuration.
194
195Note the minimum amount of different DT blobs, as well as the requirement for
196the DT blobs to have a load address; the overlay application requires the blobs
197to be writeable.
198
199Configuration using overlays and feature selection
200--------------------------------------------------
201
202Although the configuration in the previous section works is a bit inflexible
203since it requires all possible configuration options to be laid out before
204hand in the FIT image. For the add-on boards the extra config selection method
205might make sense.
206
207Note the two bar & baz configuration nodes. To boot a reva board with
208the bar add-on board enabled simply use:
209
210	# bootm <addr>#foo-reva.dtb#bar
211
212While booting a revb with bar and baz is as follows:
213
214	# bootm <addr>#foo-revb.dtb#bar#baz
215
216The limitation for a feature selection configuration node is that a single
217fdt option is currently supported.
218
219Pantelis Antoniou
220pantelis.antoniou@konsulko.com
22112/6/2017
222