doc/uImage.FIT/overlay-fdt-boot.txt

   1 U-Boot FDT Overlay FIT usage
   2 ============================
   3
   4 Introduction
   5 ------------
   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.
  10
  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
  14
  15 Configuration without overlays
  16 ------------------------------
  17
  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.
  21
  22 Without using overlays the configuration would be as follows for every case.
  23
  24         /dts-v1/;
  25         / {
  26                 images {
  27                         kernel@1 {
  28                                 data = /incbin/("./zImage");
  29                                 type = "kernel";
  30                                 arch = "arm";
  31                                 os = "linux";
  32                                 load = <0x82000000>;
  33                                 entry = <0x82000000>;
  34                         };
  35                         fdt@1 {
  36                                 data = /incbin/("./foo-reva.dtb");
  37                                 type = "flat_dt";
  38                                 arch = "arm";
  39                         };
  40                         fdt@2 {
  41                                 data = /incbin/("./foo-revb.dtb");
  42                                 type = "flat_dt";
  43                                 arch = "arm";
  44                         };
  45                         fdt@3 {
  46                                 data = /incbin/("./foo-reva-bar.dtb");
  47                                 type = "flat_dt";
  48                                 arch = "arm";
  49                         };
  50                         fdt@4 {
  51                                 data = /incbin/("./foo-revb-bar.dtb");
  52                                 type = "flat_dt";
  53                                 arch = "arm";
  54                         };
  55                         fdt@5 {
  56                                 data = /incbin/("./foo-revb-baz.dtb");
  57                                 type = "flat_dt";
  58                                 arch = "arm";
  59                         };
  60                         fdt@6 {
  61                                 data = /incbin/("./foo-revb-bar-baz.dtb");
  62                                 type = "flat_dt";
  63                                 arch = "arm";
  64                         };
  65                 };
  66
  67                 configurations {
  68                         default = "foo-reva.dtb;
  69                         foo-reva.dtb {
  70                                 kernel = "kernel@1";
  71                                 fdt = "fdt@1";
  72                         };
  73                         foo-revb.dtb {
  74                                 kernel = "kernel@1";
  75                                 fdt = "fdt@2";
  76                         };
  77                         foo-reva-bar.dtb {
  78                                 kernel = "kernel@1";
  79                                 fdt = "fdt@3";
  80                         };
  81                         foo-revb-bar.dtb {
  82                                 kernel = "kernel@1";
  83                                 fdt = "fdt@4";
  84                         };
  85                         foo-revb-baz.dtb {
  86                                 kernel = "kernel@1";
  87                                 fdt = "fdt@5";
  88                         };
  89                         foo-revb-bar-baz.dtb {
  90                                 kernel = "kernel@1";
  91                                 fdt = "fdt@6";
  92                         };
  93                 };
  94         };
  95
  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.
  99
 100 Booting this image is done by using
 101
 102         # bootm <addr>#<config>
 103
 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
 107
 108 This selects the DTB to use when booting.
 109
 110 Configuration using overlays
 111 ----------------------------
 112
 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
 115 explosion problem.
 116
 117         /dts-v1/;
 118         / {
 119                 images {
 120                         kernel@1 {
 121                                 data = /incbin/("./zImage");
 122                                 type = "kernel";
 123                                 arch = "arm";
 124                                 os = "linux";
 125                                 load = <0x82000000>;
 126                                 entry = <0x82000000>;
 127                         };
 128                         fdt@1 {
 129                                 data = /incbin/("./foo.dtb");
 130                                 type = "flat_dt";
 131                                 arch = "arm";
 132                                 load = <0x87f00000>;
 133                         };
 134                         fdt@2 {
 135                                 data = /incbin/("./reva.dtbo");
 136                                 type = "flat_dt";
 137                                 arch = "arm";
 138                                 load = <0x87fc0000>;
 139                         };
 140                         fdt@3 {
 141                                 data = /incbin/("./revb.dtbo");
 142                                 type = "flat_dt";
 143                                 arch = "arm";
 144                                 load = <0x87fc0000>;
 145                         };
 146                         fdt@4 {
 147                                 data = /incbin/("./bar.dtbo");
 148                                 type = "flat_dt";
 149                                 arch = "arm";
 150                                 load = <0x87fc0000>;
 151                         };
 152                         fdt@5 {
 153                                 data = /incbin/("./baz.dtbo");
 154                                 type = "flat_dt";
 155                                 arch = "arm";
 156                                 load = <0x87fc0000>;
 157                         };
 158                 };
 159
 160                 configurations {
 161                         default = "foo-reva.dtb;
 162                         foo-reva.dtb {
 163                                 kernel = "kernel@1";
 164                                 fdt = "fdt@1", "fdt@2";
 165                         };
 166                         foo-revb.dtb {
 167                                 kernel = "kernel@1";
 168                                 fdt = "fdt@1", "fdt@3";
 169                         };
 170                         foo-reva-bar.dtb {
 171                                 kernel = "kernel@1";
 172                                 fdt = "fdt@1", "fdt@2", "fdt@4";
 173                         };
 174                         foo-revb-bar.dtb {
 175                                 kernel = "kernel@1";
 176                                 fdt = "fdt@1", "fdt@3", "fdt@4";
 177                         };
 178                         foo-revb-baz.dtb {
 179                                 kernel = "kernel@1";
 180                                 fdt = "fdt@1", "fdt@3", "fdt@5";
 181                         };
 182                         foo-revb-bar-baz.dtb {
 183                                 kernel = "kernel@1";
 184                                 fdt = "fdt@1", "fdt@3", "fdt@4", "fdt@5";
 185                         };
 186                         bar {
 187                                 fdt = "fdt@4";
 188                         };
 189                         baz {
 190                                 fdt = "fdt@5";
 191                         };
 192                 };
 193         };
 194
 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.
 198
 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
 201 to be writeable.
 202
 203 Configuration using overlays and feature selection
 204 --------------------------------------------------
 205
 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
 209 might make sense.
 210
 211 Note the two bar & baz configuration nodes. To boot a reva board with
 212 the bar add-on board enabled simply use:
 213
 214         # bootm <addr>#foo-reva.dtb#bar
 215
 216 While booting a revb with bar and baz is as follows:
 217
 218         # bootm <addr>#foo-revb.dtb#bar#baz
 219
 220 The limitation for a feature selection configuration node is that a single
 221 fdt option is currently supported.
 222
 223 Pantelis Antoniou
 224 pantelis.antoniou@konsulko.com
 225 12/6/2017