156fc7032SFranklin S Cooper JrU-Boot FDT Overlay FIT usage 256fc7032SFranklin S Cooper Jr============================ 36b54e50bSPantelis Antoniou 46b54e50bSPantelis AntoniouIntroduction 56b54e50bSPantelis Antoniou------------ 66b54e50bSPantelis AntoniouIn many cases it is desirable to have a single FIT image support a multitude 76b54e50bSPantelis Antoniouof similar boards and their expansion options. The same kernel on DT enabled 86b54e50bSPantelis Antoniouplatforms can support this easily enough by providing a DT blob upon boot 96b54e50bSPantelis Antoniouthat matches the desired configuration. 106b54e50bSPantelis Antoniou 1156fc7032SFranklin S Cooper JrThis document focuses on specifically using overlays as part of a FIT image. 1256fc7032SFranklin S Cooper JrGeneral information regarding overlays including its syntax and building it 1356fc7032SFranklin S Cooper Jrcan be found in doc/README.fdt-overlays 1456fc7032SFranklin S Cooper Jr 156b54e50bSPantelis AntoniouConfiguration without overlays 166b54e50bSPantelis Antoniou------------------------------ 176b54e50bSPantelis Antoniou 186b54e50bSPantelis AntoniouTake a hypothetical board named 'foo' where there are different supported 196b54e50bSPantelis Antoniourevisions, reva and revb. Assume that both board revisions can use add a bar 206b54e50bSPantelis Antoniouadd-on board, while only the revb board can use a baz add-on board. 216b54e50bSPantelis Antoniou 226b54e50bSPantelis AntoniouWithout using overlays the configuration would be as follows for every case. 236b54e50bSPantelis Antoniou 246b54e50bSPantelis Antoniou /dts-v1/; 256b54e50bSPantelis Antoniou / { 266b54e50bSPantelis Antoniou images { 27*83840405SAndre Przywara kernel { 286b54e50bSPantelis Antoniou data = /incbin/("./zImage"); 296b54e50bSPantelis Antoniou type = "kernel"; 306b54e50bSPantelis Antoniou arch = "arm"; 316b54e50bSPantelis Antoniou os = "linux"; 326b54e50bSPantelis Antoniou load = <0x82000000>; 336b54e50bSPantelis Antoniou entry = <0x82000000>; 346b54e50bSPantelis Antoniou }; 35*83840405SAndre Przywara fdt-1 { 366b54e50bSPantelis Antoniou data = /incbin/("./foo-reva.dtb"); 376b54e50bSPantelis Antoniou type = "flat_dt"; 386b54e50bSPantelis Antoniou arch = "arm"; 396b54e50bSPantelis Antoniou }; 40*83840405SAndre Przywara fdt-2 { 416b54e50bSPantelis Antoniou data = /incbin/("./foo-revb.dtb"); 426b54e50bSPantelis Antoniou type = "flat_dt"; 436b54e50bSPantelis Antoniou arch = "arm"; 446b54e50bSPantelis Antoniou }; 45*83840405SAndre Przywara fdt-3 { 466b54e50bSPantelis Antoniou data = /incbin/("./foo-reva-bar.dtb"); 476b54e50bSPantelis Antoniou type = "flat_dt"; 486b54e50bSPantelis Antoniou arch = "arm"; 496b54e50bSPantelis Antoniou }; 50*83840405SAndre Przywara fdt-4 { 516b54e50bSPantelis Antoniou data = /incbin/("./foo-revb-bar.dtb"); 526b54e50bSPantelis Antoniou type = "flat_dt"; 536b54e50bSPantelis Antoniou arch = "arm"; 546b54e50bSPantelis Antoniou }; 55*83840405SAndre Przywara fdt-5 { 566b54e50bSPantelis Antoniou data = /incbin/("./foo-revb-baz.dtb"); 576b54e50bSPantelis Antoniou type = "flat_dt"; 586b54e50bSPantelis Antoniou arch = "arm"; 596b54e50bSPantelis Antoniou }; 60*83840405SAndre Przywara fdt-6 { 616b54e50bSPantelis Antoniou data = /incbin/("./foo-revb-bar-baz.dtb"); 626b54e50bSPantelis Antoniou type = "flat_dt"; 636b54e50bSPantelis Antoniou arch = "arm"; 646b54e50bSPantelis Antoniou }; 656b54e50bSPantelis Antoniou }; 666b54e50bSPantelis Antoniou 676b54e50bSPantelis Antoniou configurations { 686b54e50bSPantelis Antoniou default = "foo-reva.dtb; 696b54e50bSPantelis Antoniou foo-reva.dtb { 70*83840405SAndre Przywara kernel = "kernel"; 71*83840405SAndre Przywara fdt = "fdt-1"; 726b54e50bSPantelis Antoniou }; 736b54e50bSPantelis Antoniou foo-revb.dtb { 74*83840405SAndre Przywara kernel = "kernel"; 75*83840405SAndre Przywara fdt = "fdt-2"; 766b54e50bSPantelis Antoniou }; 776b54e50bSPantelis Antoniou foo-reva-bar.dtb { 78*83840405SAndre Przywara kernel = "kernel"; 79*83840405SAndre Przywara fdt = "fdt-3"; 806b54e50bSPantelis Antoniou }; 816b54e50bSPantelis Antoniou foo-revb-bar.dtb { 82*83840405SAndre Przywara kernel = "kernel"; 83*83840405SAndre Przywara fdt = "fdt-4"; 846b54e50bSPantelis Antoniou }; 856b54e50bSPantelis Antoniou foo-revb-baz.dtb { 86*83840405SAndre Przywara kernel = "kernel"; 87*83840405SAndre Przywara fdt = "fdt-5"; 886b54e50bSPantelis Antoniou }; 896b54e50bSPantelis Antoniou foo-revb-bar-baz.dtb { 90*83840405SAndre Przywara kernel = "kernel"; 91*83840405SAndre Przywara fdt = "fdt-6"; 926b54e50bSPantelis Antoniou }; 936b54e50bSPantelis Antoniou }; 946b54e50bSPantelis Antoniou }; 956b54e50bSPantelis Antoniou 966b54e50bSPantelis AntoniouNote the blob needs to be compiled for each case and the combinatorial explosion of 976b54e50bSPantelis Antoniouconfigurations. A typical device tree blob is in the low hunderds of kbytes so a 986b54e50bSPantelis Antonioumultitude of configuration grows the image quite a bit. 996b54e50bSPantelis Antoniou 1006b54e50bSPantelis AntoniouBooting this image is done by using 1016b54e50bSPantelis Antoniou 1026b54e50bSPantelis Antoniou # bootm <addr>#<config> 1036b54e50bSPantelis Antoniou 1046b54e50bSPantelis AntoniouWhere config is one of: 1056b54e50bSPantelis Antoniou foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb, 1066b54e50bSPantelis Antoniou foo-revb-baz.dtb, foo-revb-bar-baz.dtb 1076b54e50bSPantelis Antoniou 1086b54e50bSPantelis AntoniouThis selects the DTB to use when booting. 1096b54e50bSPantelis Antoniou 1106b54e50bSPantelis AntoniouConfiguration using overlays 1116b54e50bSPantelis Antoniou---------------------------- 1126b54e50bSPantelis Antoniou 1136b54e50bSPantelis AntoniouDevice tree overlays can be applied to a base DT and result in the same blob 1146b54e50bSPantelis Antonioubeing passed to the booting kernel. This saves on space and avoid the combinatorial 1156b54e50bSPantelis Antoniouexplosion problem. 1166b54e50bSPantelis Antoniou 1176b54e50bSPantelis Antoniou /dts-v1/; 1186b54e50bSPantelis Antoniou / { 1196b54e50bSPantelis Antoniou images { 120*83840405SAndre Przywara kernel { 1216b54e50bSPantelis Antoniou data = /incbin/("./zImage"); 1226b54e50bSPantelis Antoniou type = "kernel"; 1236b54e50bSPantelis Antoniou arch = "arm"; 1246b54e50bSPantelis Antoniou os = "linux"; 1256b54e50bSPantelis Antoniou load = <0x82000000>; 1266b54e50bSPantelis Antoniou entry = <0x82000000>; 1276b54e50bSPantelis Antoniou }; 128*83840405SAndre Przywara fdt-1 { 1296b54e50bSPantelis Antoniou data = /incbin/("./foo.dtb"); 1306b54e50bSPantelis Antoniou type = "flat_dt"; 1316b54e50bSPantelis Antoniou arch = "arm"; 1326b54e50bSPantelis Antoniou load = <0x87f00000>; 1336b54e50bSPantelis Antoniou }; 134*83840405SAndre Przywara fdt-2 { 1356b54e50bSPantelis Antoniou data = /incbin/("./reva.dtbo"); 1366b54e50bSPantelis Antoniou type = "flat_dt"; 1376b54e50bSPantelis Antoniou arch = "arm"; 1386b54e50bSPantelis Antoniou load = <0x87fc0000>; 1396b54e50bSPantelis Antoniou }; 140*83840405SAndre Przywara fdt-3 { 1416b54e50bSPantelis Antoniou data = /incbin/("./revb.dtbo"); 1426b54e50bSPantelis Antoniou type = "flat_dt"; 1436b54e50bSPantelis Antoniou arch = "arm"; 1446b54e50bSPantelis Antoniou load = <0x87fc0000>; 1456b54e50bSPantelis Antoniou }; 146*83840405SAndre Przywara fdt-4 { 1476b54e50bSPantelis Antoniou data = /incbin/("./bar.dtbo"); 1486b54e50bSPantelis Antoniou type = "flat_dt"; 1496b54e50bSPantelis Antoniou arch = "arm"; 1506b54e50bSPantelis Antoniou load = <0x87fc0000>; 1516b54e50bSPantelis Antoniou }; 152*83840405SAndre Przywara fdt-5 { 1536b54e50bSPantelis Antoniou data = /incbin/("./baz.dtbo"); 1546b54e50bSPantelis Antoniou type = "flat_dt"; 1556b54e50bSPantelis Antoniou arch = "arm"; 1566b54e50bSPantelis Antoniou load = <0x87fc0000>; 1576b54e50bSPantelis Antoniou }; 1586b54e50bSPantelis Antoniou }; 1596b54e50bSPantelis Antoniou 1606b54e50bSPantelis Antoniou configurations { 1616b54e50bSPantelis Antoniou default = "foo-reva.dtb; 1626b54e50bSPantelis Antoniou foo-reva.dtb { 163*83840405SAndre Przywara kernel = "kernel"; 164*83840405SAndre Przywara fdt = "fdt-1", "fdt-2"; 1656b54e50bSPantelis Antoniou }; 1666b54e50bSPantelis Antoniou foo-revb.dtb { 167*83840405SAndre Przywara kernel = "kernel"; 168*83840405SAndre Przywara fdt = "fdt-1", "fdt-3"; 1696b54e50bSPantelis Antoniou }; 1706b54e50bSPantelis Antoniou foo-reva-bar.dtb { 171*83840405SAndre Przywara kernel = "kernel"; 172*83840405SAndre Przywara fdt = "fdt-1", "fdt-2", "fdt-4"; 1736b54e50bSPantelis Antoniou }; 1746b54e50bSPantelis Antoniou foo-revb-bar.dtb { 175*83840405SAndre Przywara kernel = "kernel"; 176*83840405SAndre Przywara fdt = "fdt-1", "fdt-3", "fdt-4"; 1776b54e50bSPantelis Antoniou }; 1786b54e50bSPantelis Antoniou foo-revb-baz.dtb { 179*83840405SAndre Przywara kernel = "kernel"; 180*83840405SAndre Przywara fdt = "fdt-1", "fdt-3", "fdt-5"; 1816b54e50bSPantelis Antoniou }; 1826b54e50bSPantelis Antoniou foo-revb-bar-baz.dtb { 183*83840405SAndre Przywara kernel = "kernel"; 184*83840405SAndre Przywara fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5"; 1856b54e50bSPantelis Antoniou }; 1866b54e50bSPantelis Antoniou bar { 187*83840405SAndre Przywara fdt = "fdt-4"; 1886b54e50bSPantelis Antoniou }; 1896b54e50bSPantelis Antoniou baz { 190*83840405SAndre Przywara fdt = "fdt-5"; 1916b54e50bSPantelis Antoniou }; 1926b54e50bSPantelis Antoniou }; 1936b54e50bSPantelis Antoniou }; 1946b54e50bSPantelis Antoniou 1956b54e50bSPantelis AntoniouBooting this image is exactly the same as the non-overlay example. 1966b54e50bSPantelis Antoniouu-boot will retrieve the base blob and apply the overlays in sequence as 1976b54e50bSPantelis Antoniouthey are declared in the configuration. 1986b54e50bSPantelis Antoniou 1996b54e50bSPantelis AntoniouNote the minimum amount of different DT blobs, as well as the requirement for 2006b54e50bSPantelis Antoniouthe DT blobs to have a load address; the overlay application requires the blobs 2016b54e50bSPantelis Antoniouto be writeable. 2026b54e50bSPantelis Antoniou 2036b54e50bSPantelis AntoniouConfiguration using overlays and feature selection 2046b54e50bSPantelis Antoniou-------------------------------------------------- 2056b54e50bSPantelis Antoniou 2066b54e50bSPantelis AntoniouAlthough the configuration in the previous section works is a bit inflexible 2076b54e50bSPantelis Antoniousince it requires all possible configuration options to be laid out before 2086b54e50bSPantelis Antoniouhand in the FIT image. For the add-on boards the extra config selection method 2096b54e50bSPantelis Antonioumight make sense. 2106b54e50bSPantelis Antoniou 2116b54e50bSPantelis AntoniouNote the two bar & baz configuration nodes. To boot a reva board with 2126b54e50bSPantelis Antoniouthe bar add-on board enabled simply use: 2136b54e50bSPantelis Antoniou 2146b54e50bSPantelis Antoniou # bootm <addr>#foo-reva.dtb#bar 2156b54e50bSPantelis Antoniou 2166b54e50bSPantelis AntoniouWhile booting a revb with bar and baz is as follows: 2176b54e50bSPantelis Antoniou 2186b54e50bSPantelis Antoniou # bootm <addr>#foo-revb.dtb#bar#baz 2196b54e50bSPantelis Antoniou 2206b54e50bSPantelis AntoniouThe limitation for a feature selection configuration node is that a single 2216b54e50bSPantelis Antonioufdt option is currently supported. 2226b54e50bSPantelis Antoniou 2236b54e50bSPantelis AntoniouPantelis Antoniou 2246b54e50bSPantelis Antonioupantelis.antoniou@konsulko.com 2256b54e50bSPantelis Antoniou12/6/2017 226