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