1 U-Boot FDT Overlay FIT usage
2 ============================
6 In many cases it is desirable to have a single FIT image support a multitude
7 of similar boards and their expansion options. The same kernel on DT enabled
8 platforms can support this easily enough by providing a DT blob upon boot
9 that matches the desired configuration.
11 This document focuses on specifically using overlays as part of a FIT image.
12 General information regarding overlays including its syntax and building it
13 can be found in doc/README.fdt-overlays
15 Configuration without overlays
16 ------------------------------
18 Take a hypothetical board named 'foo' where there are different supported
19 revisions, reva and revb. Assume that both board revisions can use add a bar
20 add-on board, while only the revb board can use a baz add-on board.
22 Without using overlays the configuration would be as follows for every case.
28 data = /incbin/("./zImage");
36 data = /incbin/("./foo-reva.dtb");
41 data = /incbin/("./foo-revb.dtb");
46 data = /incbin/("./foo-reva-bar.dtb");
51 data = /incbin/("./foo-revb-bar.dtb");
56 data = /incbin/("./foo-revb-baz.dtb");
61 data = /incbin/("./foo-revb-bar-baz.dtb");
68 default = "foo-reva.dtb;
89 foo-revb-bar-baz.dtb {
96 Note the blob needs to be compiled for each case and the combinatorial explosion of
97 configurations. A typical device tree blob is in the low hunderds of kbytes so a
98 multitude of configuration grows the image quite a bit.
100 Booting this image is done by using
102 # bootm <addr>#<config>
104 Where config is one of:
105 foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
106 foo-revb-baz.dtb, foo-revb-bar-baz.dtb
108 This selects the DTB to use when booting.
110 Configuration using overlays
111 ----------------------------
113 Device tree overlays can be applied to a base DT and result in the same blob
114 being passed to the booting kernel. This saves on space and avoid the combinatorial
121 data = /incbin/("./zImage");
126 entry = <0x82000000>;
129 data = /incbin/("./foo.dtb");
135 data = /incbin/("./reva.dtbo");
141 data = /incbin/("./revb.dtbo");
147 data = /incbin/("./bar.dtbo");
153 data = /incbin/("./baz.dtbo");
161 default = "foo-reva.dtb;
164 fdt = "fdt-1", "fdt-2";
168 fdt = "fdt-1", "fdt-3";
172 fdt = "fdt-1", "fdt-2", "fdt-4";
176 fdt = "fdt-1", "fdt-3", "fdt-4";
180 fdt = "fdt-1", "fdt-3", "fdt-5";
182 foo-revb-bar-baz.dtb {
184 fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
195 Booting this image is exactly the same as the non-overlay example.
196 u-boot will retrieve the base blob and apply the overlays in sequence as
197 they are declared in the configuration.
199 Note the minimum amount of different DT blobs, as well as the requirement for
200 the DT blobs to have a load address; the overlay application requires the blobs
203 Configuration using overlays and feature selection
204 --------------------------------------------------
206 Although the configuration in the previous section works is a bit inflexible
207 since it requires all possible configuration options to be laid out before
208 hand in the FIT image. For the add-on boards the extra config selection method
211 Note the two bar & baz configuration nodes. To boot a reva board with
212 the bar add-on board enabled simply use:
214 # bootm <addr>#foo-reva.dtb#bar
216 While booting a revb with bar and baz is as follows:
218 # bootm <addr>#foo-revb.dtb#bar#baz
220 The limitation for a feature selection configuration node is that a single
221 fdt option is currently supported.
224 pantelis.antoniou@konsulko.com