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