123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225 |
- U-Boot FDT Overlay FIT usage
- ============================
- Introduction
- ------------
- In many cases it is desirable to have a single FIT image support a multitude
- of similar boards and their expansion options. The same kernel on DT enabled
- platforms can support this easily enough by providing a DT blob upon boot
- that matches the desired configuration.
- This document focuses on specifically using overlays as part of a FIT image.
- General information regarding overlays including its syntax and building it
- can be found in doc/README.fdt-overlays
- Configuration without overlays
- ------------------------------
- Take a hypothetical board named 'foo' where there are different supported
- revisions, reva and revb. Assume that both board revisions can use add a bar
- add-on board, while only the revb board can use a baz add-on board.
- Without using overlays the configuration would be as follows for every case.
- /dts-v1/;
- / {
- images {
- kernel {
- data = /incbin/("./zImage");
- type = "kernel";
- arch = "arm";
- os = "linux";
- load = <0x82000000>;
- entry = <0x82000000>;
- };
- fdt-1 {
- data = /incbin/("./foo-reva.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- fdt-2 {
- data = /incbin/("./foo-revb.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- fdt-3 {
- data = /incbin/("./foo-reva-bar.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- fdt-4 {
- data = /incbin/("./foo-revb-bar.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- fdt-5 {
- data = /incbin/("./foo-revb-baz.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- fdt-6 {
- data = /incbin/("./foo-revb-bar-baz.dtb");
- type = "flat_dt";
- arch = "arm";
- };
- };
- configurations {
- default = "foo-reva.dtb;
- foo-reva.dtb {
- kernel = "kernel";
- fdt = "fdt-1";
- };
- foo-revb.dtb {
- kernel = "kernel";
- fdt = "fdt-2";
- };
- foo-reva-bar.dtb {
- kernel = "kernel";
- fdt = "fdt-3";
- };
- foo-revb-bar.dtb {
- kernel = "kernel";
- fdt = "fdt-4";
- };
- foo-revb-baz.dtb {
- kernel = "kernel";
- fdt = "fdt-5";
- };
- foo-revb-bar-baz.dtb {
- kernel = "kernel";
- fdt = "fdt-6";
- };
- };
- };
- Note the blob needs to be compiled for each case and the combinatorial explosion of
- configurations. A typical device tree blob is in the low hunderds of kbytes so a
- multitude of configuration grows the image quite a bit.
- Booting this image is done by using
- # bootm <addr>#<config>
- Where config is one of:
- foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb,
- foo-revb-baz.dtb, foo-revb-bar-baz.dtb
- This selects the DTB to use when booting.
- Configuration using overlays
- ----------------------------
- Device tree overlays can be applied to a base DT and result in the same blob
- being passed to the booting kernel. This saves on space and avoid the combinatorial
- explosion problem.
- /dts-v1/;
- / {
- images {
- kernel {
- data = /incbin/("./zImage");
- type = "kernel";
- arch = "arm";
- os = "linux";
- load = <0x82000000>;
- entry = <0x82000000>;
- };
- fdt-1 {
- data = /incbin/("./foo.dtb");
- type = "flat_dt";
- arch = "arm";
- load = <0x87f00000>;
- };
- fdt-2 {
- data = /incbin/("./reva.dtbo");
- type = "flat_dt";
- arch = "arm";
- load = <0x87fc0000>;
- };
- fdt-3 {
- data = /incbin/("./revb.dtbo");
- type = "flat_dt";
- arch = "arm";
- load = <0x87fc0000>;
- };
- fdt-4 {
- data = /incbin/("./bar.dtbo");
- type = "flat_dt";
- arch = "arm";
- load = <0x87fc0000>;
- };
- fdt-5 {
- data = /incbin/("./baz.dtbo");
- type = "flat_dt";
- arch = "arm";
- load = <0x87fc0000>;
- };
- };
- configurations {
- default = "foo-reva.dtb;
- foo-reva.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-2";
- };
- foo-revb.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-3";
- };
- foo-reva-bar.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-2", "fdt-4";
- };
- foo-revb-bar.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-3", "fdt-4";
- };
- foo-revb-baz.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-3", "fdt-5";
- };
- foo-revb-bar-baz.dtb {
- kernel = "kernel";
- fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5";
- };
- bar {
- fdt = "fdt-4";
- };
- baz {
- fdt = "fdt-5";
- };
- };
- };
- Booting this image is exactly the same as the non-overlay example.
- u-boot will retrieve the base blob and apply the overlays in sequence as
- they are declared in the configuration.
- Note the minimum amount of different DT blobs, as well as the requirement for
- the DT blobs to have a load address; the overlay application requires the blobs
- to be writeable.
- Configuration using overlays and feature selection
- --------------------------------------------------
- Although the configuration in the previous section works is a bit inflexible
- since it requires all possible configuration options to be laid out before
- hand in the FIT image. For the add-on boards the extra config selection method
- might make sense.
- Note the two bar & baz configuration nodes. To boot a reva board with
- the bar add-on board enabled simply use:
- # bootm <addr>#foo-reva.dtb#bar
- While booting a revb with bar and baz is as follows:
- # bootm <addr>#foo-revb.dtb#bar#baz
- The limitation for a feature selection configuration node is that a single
- fdt option is currently supported.
- Pantelis Antoniou
- pantelis.antoniou@konsulko.com
- 12/6/2017
|