Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1 | Binman Entry Documentation |
| 2 | =========================== |
| 3 | |
| 4 | This file describes the entry types supported by binman. These entry types can |
| 5 | be placed in an image one by one to build up a final firmware image. It is |
| 6 | fairly easy to create new entry types. Just add a new file to the 'etype' |
| 7 | directory. You can use the existing entries as examples. |
| 8 | |
| 9 | Note that some entries are subclasses of others, using and extending their |
| 10 | features to produce new behaviours. |
| 11 | |
| 12 | |
| 13 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 14 | Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob |
| 15 | ----------------------------------------------------- |
Simon Glass | dc2f81a | 2020-09-01 05:13:58 -0600 | [diff] [blame] | 16 | |
| 17 | Properties / Entry arguments: |
| 18 | - atf-bl31-path: Filename of file to read into entry. This is typically |
| 19 | called bl31.bin or bl31.elf |
| 20 | |
| 21 | This entry holds the run-time firmware, typically started by U-Boot SPL. |
| 22 | See the U-Boot README for your architecture or board for how to use it. See |
| 23 | https://github.com/ARM-software/arm-trusted-firmware for more information |
| 24 | about ATF. |
| 25 | |
| 26 | |
| 27 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 28 | Entry: blob: Arbitrary binary blob |
| 29 | ---------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 30 | |
| 31 | Note: This should not be used by itself. It is normally used as a parent |
| 32 | class by other entry types. |
| 33 | |
| 34 | Properties / Entry arguments: |
| 35 | - filename: Filename of file to read into entry |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 36 | - compress: Compression algorithm to use: |
| 37 | none: No compression |
| 38 | lz4: Use lz4 compression (via 'lz4' command-line utility) |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 39 | |
| 40 | This entry reads data from a file and places it in the entry. The |
| 41 | default filename is often specified specified by the subclass. See for |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 42 | example the 'u-boot' entry which provides the filename 'u-boot.bin'. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 43 | |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 44 | If compression is enabled, an extra 'uncomp-size' property is written to |
| 45 | the node (if enabled with -u) which provides the uncompressed size of the |
| 46 | data. |
| 47 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 48 | |
| 49 | |
Simon Glass | 6ed45ba | 2018-09-14 04:57:24 -0600 | [diff] [blame] | 50 | Entry: blob-dtb: A blob that holds a device tree |
| 51 | ------------------------------------------------ |
| 52 | |
| 53 | This is a blob containing a device tree. The contents of the blob are |
| 54 | obtained from the list of available device-tree files, managed by the |
| 55 | 'state' module. |
| 56 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 57 | |
| 58 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 59 | Entry: blob-ext: Externally built binary blob |
| 60 | --------------------------------------------- |
Simon Glass | ce867ad | 2020-07-09 18:39:36 -0600 | [diff] [blame] | 61 | |
| 62 | Note: This should not be used by itself. It is normally used as a parent |
| 63 | class by other entry types. |
| 64 | |
Simon Glass | 4f9f105 | 2020-07-09 18:39:38 -0600 | [diff] [blame] | 65 | If the file providing this blob is missing, binman can optionally ignore it |
| 66 | and produce a broken image with a warning. |
| 67 | |
Simon Glass | ce867ad | 2020-07-09 18:39:36 -0600 | [diff] [blame] | 68 | See 'blob' for Properties / Entry arguments. |
| 69 | |
| 70 | |
| 71 | |
Simon Glass | ec127af | 2018-07-17 13:25:39 -0600 | [diff] [blame] | 72 | Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass |
| 73 | ----------------------------------------------------------------------------------------- |
| 74 | |
| 75 | Properties / Entry arguments: |
| 76 | - <xxx>-path: Filename containing the contents of this entry (optional, |
Simon Glass | 3decfa3 | 2020-09-01 05:13:54 -0600 | [diff] [blame] | 77 | defaults to None) |
Simon Glass | ec127af | 2018-07-17 13:25:39 -0600 | [diff] [blame] | 78 | |
| 79 | where <xxx> is the blob_fname argument to the constructor. |
| 80 | |
| 81 | This entry cannot be used directly. Instead, it is used as a parent class |
| 82 | for another entry, which defined blob_fname. This parameter is used to |
| 83 | set the entry-arg or property containing the filename. The entry-arg or |
| 84 | property is in turn used to set the actual filename. |
| 85 | |
| 86 | See cros_ec_rw for an example of this. |
| 87 | |
| 88 | |
| 89 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 90 | Entry: blob-phase: Section that holds a phase binary |
| 91 | ---------------------------------------------------- |
| 92 | |
| 93 | This is a base class that should not normally be used directly. It is used |
| 94 | when converting a 'u-boot' entry automatically into a 'u-boot-expanded' |
| 95 | entry; similarly for SPL. |
| 96 | |
| 97 | |
| 98 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 99 | Entry: cbfs: Coreboot Filesystem (CBFS) |
| 100 | --------------------------------------- |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 101 | |
| 102 | A CBFS provides a way to group files into a group. It has a simple directory |
| 103 | structure and allows the position of individual files to be set, since it is |
| 104 | designed to support execute-in-place in an x86 SPI-flash device. Where XIP |
| 105 | is not used, it supports compression and storing ELF files. |
| 106 | |
| 107 | CBFS is used by coreboot as its way of orgnanising SPI-flash contents. |
| 108 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 109 | The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:: |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 110 | |
| 111 | cbfs { |
| 112 | size = <0x100000>; |
| 113 | u-boot { |
| 114 | cbfs-type = "raw"; |
| 115 | }; |
| 116 | u-boot-dtb { |
| 117 | cbfs-type = "raw"; |
| 118 | }; |
| 119 | }; |
| 120 | |
| 121 | This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb. |
| 122 | Note that the size is required since binman does not support calculating it. |
| 123 | The contents of each entry is just what binman would normally provide if it |
| 124 | were not a CBFS node. A blob type can be used to import arbitrary files as |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 125 | with the second subnode below:: |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 126 | |
| 127 | cbfs { |
| 128 | size = <0x100000>; |
| 129 | u-boot { |
| 130 | cbfs-name = "BOOT"; |
| 131 | cbfs-type = "raw"; |
| 132 | }; |
| 133 | |
| 134 | dtb { |
| 135 | type = "blob"; |
| 136 | filename = "u-boot.dtb"; |
| 137 | cbfs-type = "raw"; |
| 138 | cbfs-compress = "lz4"; |
Simon Glass | e073d4e | 2019-07-08 13:18:56 -0600 | [diff] [blame] | 139 | cbfs-offset = <0x100000>; |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 140 | }; |
| 141 | }; |
| 142 | |
| 143 | This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and |
| 144 | u-boot.dtb (named "dtb") and compressed with the lz4 algorithm. |
| 145 | |
| 146 | |
| 147 | Properties supported in the top-level CBFS node: |
| 148 | |
| 149 | cbfs-arch: |
| 150 | Defaults to "x86", but you can specify the architecture if needed. |
| 151 | |
| 152 | |
| 153 | Properties supported in the CBFS entry subnodes: |
| 154 | |
| 155 | cbfs-name: |
| 156 | This is the name of the file created in CBFS. It defaults to the entry |
| 157 | name (which is the node name), but you can override it with this |
| 158 | property. |
| 159 | |
| 160 | cbfs-type: |
| 161 | This is the CBFS file type. The following are supported: |
| 162 | |
| 163 | raw: |
| 164 | This is a 'raw' file, although compression is supported. It can be |
| 165 | used to store any file in CBFS. |
| 166 | |
| 167 | stage: |
| 168 | This is an ELF file that has been loaded (i.e. mapped to memory), so |
| 169 | appears in the CBFS as a flat binary. The input file must be an ELF |
| 170 | image, for example this puts "u-boot" (the ELF image) into a 'stage' |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 171 | entry:: |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 172 | |
| 173 | cbfs { |
| 174 | size = <0x100000>; |
| 175 | u-boot-elf { |
| 176 | cbfs-name = "BOOT"; |
| 177 | cbfs-type = "stage"; |
| 178 | }; |
| 179 | }; |
| 180 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 181 | You can use your own ELF file with something like:: |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 182 | |
| 183 | cbfs { |
| 184 | size = <0x100000>; |
| 185 | something { |
| 186 | type = "blob"; |
| 187 | filename = "cbfs-stage.elf"; |
| 188 | cbfs-type = "stage"; |
| 189 | }; |
| 190 | }; |
| 191 | |
| 192 | As mentioned, the file is converted to a flat binary, so it is |
| 193 | equivalent to adding "u-boot.bin", for example, but with the load and |
| 194 | start addresses specified by the ELF. At present there is no option |
| 195 | to add a flat binary with a load/start address, similar to the |
| 196 | 'add-flat-binary' option in cbfstool. |
| 197 | |
Simon Glass | e073d4e | 2019-07-08 13:18:56 -0600 | [diff] [blame] | 198 | cbfs-offset: |
| 199 | This is the offset of the file's data within the CBFS. It is used to |
| 200 | specify where the file should be placed in cases where a fixed position |
| 201 | is needed. Typical uses are for code which is not relocatable and must |
| 202 | execute in-place from a particular address. This works because SPI flash |
| 203 | is generally mapped into memory on x86 devices. The file header is |
| 204 | placed before this offset so that the data start lines up exactly with |
| 205 | the chosen offset. If this property is not provided, then the file is |
| 206 | placed in the next available spot. |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 207 | |
| 208 | The current implementation supports only a subset of CBFS features. It does |
| 209 | not support other file types (e.g. payload), adding multiple files (like the |
| 210 | 'files' entry with a pattern supported by binman), putting files at a |
| 211 | particular offset in the CBFS and a few other things. |
| 212 | |
| 213 | Of course binman can create images containing multiple CBFSs, simply by |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 214 | defining these in the binman config:: |
Simon Glass | ac62fba | 2019-07-08 13:18:53 -0600 | [diff] [blame] | 215 | |
| 216 | |
| 217 | binman { |
| 218 | size = <0x800000>; |
| 219 | cbfs { |
| 220 | offset = <0x100000>; |
| 221 | size = <0x100000>; |
| 222 | u-boot { |
| 223 | cbfs-type = "raw"; |
| 224 | }; |
| 225 | u-boot-dtb { |
| 226 | cbfs-type = "raw"; |
| 227 | }; |
| 228 | }; |
| 229 | |
| 230 | cbfs2 { |
| 231 | offset = <0x700000>; |
| 232 | size = <0x100000>; |
| 233 | u-boot { |
| 234 | cbfs-type = "raw"; |
| 235 | }; |
| 236 | u-boot-dtb { |
| 237 | cbfs-type = "raw"; |
| 238 | }; |
| 239 | image { |
| 240 | type = "blob"; |
| 241 | filename = "image.jpg"; |
| 242 | }; |
| 243 | }; |
| 244 | }; |
| 245 | |
| 246 | This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB, |
| 247 | both of size 1MB. |
| 248 | |
| 249 | |
| 250 | |
Simon Glass | ec127af | 2018-07-17 13:25:39 -0600 | [diff] [blame] | 251 | Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image |
| 252 | -------------------------------------------------------------------------------- |
| 253 | |
| 254 | Properties / Entry arguments: |
| 255 | - cros-ec-rw-path: Filename containing the EC image |
| 256 | |
| 257 | This entry holds a Chromium OS EC (embedded controller) image, for use in |
| 258 | updating the EC on startup via software sync. |
| 259 | |
| 260 | |
| 261 | |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 262 | Entry: fdtmap: An entry which contains an FDT map |
| 263 | ------------------------------------------------- |
| 264 | |
| 265 | Properties / Entry arguments: |
| 266 | None |
| 267 | |
| 268 | An FDT map is just a header followed by an FDT containing a list of all the |
Simon Glass | 12bb1a9 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 269 | entries in the image. The root node corresponds to the image node in the |
| 270 | original FDT, and an image-name property indicates the image name in that |
| 271 | original tree. |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 272 | |
| 273 | The header is the string _FDTMAP_ followed by 8 unused bytes. |
| 274 | |
| 275 | When used, this entry will be populated with an FDT map which reflects the |
| 276 | entries in the current image. Hierarchy is preserved, and all offsets and |
| 277 | sizes are included. |
| 278 | |
| 279 | Note that the -u option must be provided to ensure that binman updates the |
| 280 | FDT with the position of each entry. |
| 281 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 282 | Example output for a simple image with U-Boot and an FDT map:: |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 283 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 284 | / { |
| 285 | image-name = "binman"; |
| 286 | size = <0x00000112>; |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 287 | image-pos = <0x00000000>; |
| 288 | offset = <0x00000000>; |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 289 | u-boot { |
| 290 | size = <0x00000004>; |
| 291 | image-pos = <0x00000000>; |
| 292 | offset = <0x00000000>; |
| 293 | }; |
| 294 | fdtmap { |
| 295 | size = <0x0000010e>; |
| 296 | image-pos = <0x00000004>; |
| 297 | offset = <0x00000004>; |
| 298 | }; |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 299 | }; |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 300 | |
Simon Glass | 12bb1a9 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 301 | If allow-repack is used then 'orig-offset' and 'orig-size' properties are |
| 302 | added as necessary. See the binman README. |
| 303 | |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 304 | |
| 305 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 306 | Entry: files: A set of files arranged in a section |
| 307 | -------------------------------------------------- |
Simon Glass | 0a98b28 | 2018-09-14 04:57:28 -0600 | [diff] [blame] | 308 | |
| 309 | Properties / Entry arguments: |
| 310 | - pattern: Filename pattern to match the files to include |
Simon Glass | 9248c8d | 2020-10-26 17:40:07 -0600 | [diff] [blame] | 311 | - files-compress: Compression algorithm to use: |
Simon Glass | 0a98b28 | 2018-09-14 04:57:28 -0600 | [diff] [blame] | 312 | none: No compression |
| 313 | lz4: Use lz4 compression (via 'lz4' command-line utility) |
Simon Glass | 4ce4077 | 2021-03-18 20:24:53 +1300 | [diff] [blame] | 314 | - files-align: Align each file to the given alignment |
Simon Glass | 0a98b28 | 2018-09-14 04:57:28 -0600 | [diff] [blame] | 315 | |
| 316 | This entry reads a number of files and places each in a separate sub-entry |
| 317 | within this entry. To access these you need to enable device-tree updates |
| 318 | at run-time so you can obtain the file positions. |
| 319 | |
| 320 | |
| 321 | |
Simon Glass | 3af8e49 | 2018-07-17 13:25:40 -0600 | [diff] [blame] | 322 | Entry: fill: An entry which is filled to a particular byte value |
| 323 | ---------------------------------------------------------------- |
| 324 | |
| 325 | Properties / Entry arguments: |
| 326 | - fill-byte: Byte to use to fill the entry |
| 327 | |
| 328 | Note that the size property must be set since otherwise this entry does not |
| 329 | know how large it should be. |
| 330 | |
| 331 | You can often achieve the same effect using the pad-byte property of the |
| 332 | overall image, in that the space between entries will then be padded with |
| 333 | that byte. But this entry is sometimes useful for explicitly setting the |
| 334 | byte value of a region. |
| 335 | |
| 336 | |
| 337 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 338 | Entry: fit: Flat Image Tree (FIT) |
| 339 | --------------------------------- |
Simon Glass | fdc3436 | 2020-07-09 18:39:45 -0600 | [diff] [blame] | 340 | |
| 341 | This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the |
| 342 | input provided. |
| 343 | |
| 344 | Nodes for the FIT should be written out in the binman configuration just as |
| 345 | they would be in a file passed to mkimage. |
| 346 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 347 | For example, this creates an image containing a FIT with U-Boot SPL:: |
Simon Glass | fdc3436 | 2020-07-09 18:39:45 -0600 | [diff] [blame] | 348 | |
| 349 | binman { |
| 350 | fit { |
| 351 | description = "Test FIT"; |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 352 | fit,fdt-list = "of-list"; |
Simon Glass | fdc3436 | 2020-07-09 18:39:45 -0600 | [diff] [blame] | 353 | |
| 354 | images { |
| 355 | kernel@1 { |
| 356 | description = "SPL"; |
| 357 | os = "u-boot"; |
| 358 | type = "rkspi"; |
| 359 | arch = "arm"; |
| 360 | compression = "none"; |
| 361 | load = <0>; |
| 362 | entry = <0>; |
| 363 | |
| 364 | u-boot-spl { |
| 365 | }; |
| 366 | }; |
| 367 | }; |
| 368 | }; |
| 369 | }; |
| 370 | |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 371 | U-Boot supports creating fdt and config nodes automatically. To do this, |
| 372 | pass an of-list property (e.g. -a of-list=file1 file2). This tells binman |
| 373 | that you want to generates nodes for two files: file1.dtb and file2.dtb |
| 374 | The fit,fdt-list property (see above) indicates that of-list should be used. |
| 375 | If the property is missing you will get an error. |
| 376 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 377 | Then add a 'generator node', a node with a name starting with '@':: |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 378 | |
| 379 | images { |
| 380 | @fdt-SEQ { |
| 381 | description = "fdt-NAME"; |
| 382 | type = "flat_dt"; |
| 383 | compression = "none"; |
| 384 | }; |
| 385 | }; |
| 386 | |
| 387 | This tells binman to create nodes fdt-1 and fdt-2 for each of your two |
| 388 | files. All the properties you specify will be included in the node. This |
| 389 | node acts like a template to generate the nodes. The generator node itself |
| 390 | does not appear in the output - it is replaced with what binman generates. |
| 391 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 392 | You can create config nodes in a similar way:: |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 393 | |
| 394 | configurations { |
| 395 | default = "@config-DEFAULT-SEQ"; |
| 396 | @config-SEQ { |
| 397 | description = "NAME"; |
Samuel Holland | 68158d5 | 2020-10-21 21:12:14 -0500 | [diff] [blame] | 398 | firmware = "atf"; |
| 399 | loadables = "uboot"; |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 400 | fdt = "fdt-SEQ"; |
| 401 | }; |
| 402 | }; |
| 403 | |
| 404 | This tells binman to create nodes config-1 and config-2, i.e. a config for |
| 405 | each of your two files. |
| 406 | |
| 407 | Available substitutions for '@' nodes are: |
| 408 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 409 | SEQ: |
| 410 | Sequence number of the generated fdt (1, 2, ...) |
| 411 | NAME |
| 412 | Name of the dtb as provided (i.e. without adding '.dtb') |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 413 | |
| 414 | Note that if no devicetree files are provided (with '-a of-list' as above) |
| 415 | then no nodes will be generated. |
| 416 | |
Simon Glass | c0f1ebe | 2020-09-06 10:39:08 -0600 | [diff] [blame] | 417 | The 'default' property, if present, will be automatically set to the name |
| 418 | if of configuration whose devicetree matches the 'default-dt' entry |
| 419 | argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'. |
| 420 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 421 | Available substitutions for '@' property values are |
Simon Glass | f324330 | 2020-10-26 17:39:59 -0600 | [diff] [blame] | 422 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 423 | DEFAULT-SEQ: |
| 424 | Sequence number of the default fdt,as provided by the 'default-dt' entry |
| 425 | argument |
Simon Glass | 6cf9953 | 2020-09-01 05:13:59 -0600 | [diff] [blame] | 426 | |
| 427 | Properties (in the 'fit' node itself): |
Simon Glass | fdc3436 | 2020-07-09 18:39:45 -0600 | [diff] [blame] | 428 | fit,external-offset: Indicates that the contents of the FIT are external |
| 429 | and provides the external offset. This is passsed to mkimage via |
| 430 | the -E and -p flags. |
| 431 | |
| 432 | |
| 433 | |
| 434 | |
Simon Glass | 11e36cc | 2018-07-17 13:25:38 -0600 | [diff] [blame] | 435 | Entry: fmap: An entry which contains an Fmap section |
| 436 | ---------------------------------------------------- |
| 437 | |
| 438 | Properties / Entry arguments: |
| 439 | None |
| 440 | |
| 441 | FMAP is a simple format used by flashrom, an open-source utility for |
| 442 | reading and writing the SPI flash, typically on x86 CPUs. The format |
| 443 | provides flashrom with a list of areas, so it knows what it in the flash. |
| 444 | It can then read or write just a single area, instead of the whole flash. |
| 445 | |
| 446 | The format is defined by the flashrom project, in the file lib/fmap.h - |
| 447 | see www.flashrom.org/Flashrom for more information. |
| 448 | |
| 449 | When used, this entry will be populated with an FMAP which reflects the |
| 450 | entries in the current image. Note that any hierarchy is squashed, since |
Simon Glass | 95a0f3c | 2019-07-20 12:24:00 -0600 | [diff] [blame] | 451 | FMAP does not support this. Also, CBFS entries appear as a single entry - |
| 452 | the sub-entries are ignored. |
Simon Glass | 11e36cc | 2018-07-17 13:25:38 -0600 | [diff] [blame] | 453 | |
| 454 | |
| 455 | |
Simon Glass | 0ef87aa | 2018-07-17 13:25:44 -0600 | [diff] [blame] | 456 | Entry: gbb: An entry which contains a Chromium OS Google Binary Block |
| 457 | --------------------------------------------------------------------- |
| 458 | |
| 459 | Properties / Entry arguments: |
| 460 | - hardware-id: Hardware ID to use for this build (a string) |
| 461 | - keydir: Directory containing the public keys to use |
| 462 | - bmpblk: Filename containing images used by recovery |
| 463 | |
| 464 | Chromium OS uses a GBB to store various pieces of information, in particular |
| 465 | the root and recovery keys that are used to verify the boot process. Some |
| 466 | more details are here: |
| 467 | |
| 468 | https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts |
| 469 | |
| 470 | but note that the page dates from 2013 so is quite out of date. See |
| 471 | README.chromium for how to obtain the required keys and tools. |
| 472 | |
| 473 | |
| 474 | |
Simon Glass | cf22894 | 2019-07-08 14:25:28 -0600 | [diff] [blame] | 475 | Entry: image-header: An entry which contains a pointer to the FDT map |
| 476 | --------------------------------------------------------------------- |
| 477 | |
| 478 | Properties / Entry arguments: |
| 479 | location: Location of header ("start" or "end" of image). This is |
| 480 | optional. If omitted then the entry must have an offset property. |
| 481 | |
| 482 | This adds an 8-byte entry to the start or end of the image, pointing to the |
| 483 | location of the FDT map. The format is a magic number followed by an offset |
| 484 | from the start or end of the image, in twos-compliment format. |
| 485 | |
| 486 | This entry must be in the top-level part of the image. |
| 487 | |
| 488 | NOTE: If the location is at the start/end, you will probably need to specify |
| 489 | sort-by-offset for the image, unless you actually put the image header |
| 490 | first/last in the entry list. |
| 491 | |
| 492 | |
| 493 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 494 | Entry: intel-cmc: Intel Chipset Micro Code (CMC) file |
| 495 | ----------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 496 | |
| 497 | Properties / Entry arguments: |
| 498 | - filename: Filename of file to read into entry |
| 499 | |
| 500 | This file contains microcode for some devices in a special format. An |
| 501 | example filename is 'Microcode/C0_22211.BIN'. |
| 502 | |
| 503 | See README.x86 for information about x86 binary blobs. |
| 504 | |
| 505 | |
| 506 | |
| 507 | Entry: intel-descriptor: Intel flash descriptor block (4KB) |
| 508 | ----------------------------------------------------------- |
| 509 | |
| 510 | Properties / Entry arguments: |
| 511 | filename: Filename of file containing the descriptor. This is typically |
| 512 | a 4KB binary file, sometimes called 'descriptor.bin' |
| 513 | |
| 514 | This entry is placed at the start of flash and provides information about |
| 515 | the SPI flash regions. In particular it provides the base address and |
| 516 | size of the ME (Management Engine) region, allowing us to place the ME |
| 517 | binary in the right place. |
| 518 | |
| 519 | With this entry in your image, the position of the 'intel-me' entry will be |
| 520 | fixed in the image, which avoids you needed to specify an offset for that |
| 521 | region. This is useful, because it is not possible to change the position |
| 522 | of the ME region without updating the descriptor. |
| 523 | |
| 524 | See README.x86 for information about x86 binary blobs. |
| 525 | |
| 526 | |
| 527 | |
Simon Glass | 5af1207 | 2019-08-24 07:22:50 -0600 | [diff] [blame] | 528 | Entry: intel-fit: Intel Firmware Image Table (FIT) |
| 529 | -------------------------------------------------- |
| 530 | |
| 531 | This entry contains a dummy FIT as required by recent Intel CPUs. The FIT |
| 532 | contains information about the firmware and microcode available in the |
| 533 | image. |
| 534 | |
| 535 | At present binman only supports a basic FIT with no microcode. |
| 536 | |
| 537 | |
| 538 | |
| 539 | Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer |
| 540 | -------------------------------------------------------------- |
| 541 | |
| 542 | This entry contains a pointer to the FIT. It is required to be at address |
| 543 | 0xffffffc0 in the image. |
| 544 | |
| 545 | |
| 546 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 547 | Entry: intel-fsp: Intel Firmware Support Package (FSP) file |
| 548 | ----------------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 549 | |
| 550 | Properties / Entry arguments: |
| 551 | - filename: Filename of file to read into entry |
| 552 | |
| 553 | This file contains binary blobs which are used on some devices to make the |
| 554 | platform work. U-Boot executes this code since it is not possible to set up |
| 555 | the hardware using U-Boot open-source code. Documentation is typically not |
| 556 | available in sufficient detail to allow this. |
| 557 | |
| 558 | An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' |
| 559 | |
| 560 | See README.x86 for information about x86 binary blobs. |
| 561 | |
| 562 | |
| 563 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 564 | Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init |
| 565 | -------------------------------------------------------------------- |
Simon Glass | ea0fff9 | 2019-08-24 07:23:07 -0600 | [diff] [blame] | 566 | |
| 567 | Properties / Entry arguments: |
| 568 | - filename: Filename of file to read into entry |
| 569 | |
| 570 | This file contains a binary blob which is used on some devices to set up |
| 571 | SDRAM. U-Boot executes this code in SPL so that it can make full use of |
| 572 | memory. Documentation is typically not available in sufficient detail to |
| 573 | allow U-Boot do this this itself.. |
| 574 | |
| 575 | An example filename is 'fsp_m.bin' |
| 576 | |
| 577 | See README.x86 for information about x86 binary blobs. |
| 578 | |
| 579 | |
| 580 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 581 | Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init |
| 582 | --------------------------------------------------------------------- |
Simon Glass | bc6a88f | 2019-10-20 21:31:35 -0600 | [diff] [blame] | 583 | |
| 584 | Properties / Entry arguments: |
| 585 | - filename: Filename of file to read into entry |
| 586 | |
| 587 | This file contains a binary blob which is used on some devices to set up |
| 588 | the silicon. U-Boot executes this code in U-Boot proper after SDRAM is |
| 589 | running, so that it can make full use of memory. Documentation is typically |
| 590 | not available in sufficient detail to allow U-Boot do this this itself. |
| 591 | |
| 592 | An example filename is 'fsp_s.bin' |
| 593 | |
| 594 | See README.x86 for information about x86 binary blobs. |
| 595 | |
| 596 | |
| 597 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 598 | Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init |
| 599 | ---------------------------------------------------------------------- |
Simon Glass | 998d148 | 2019-10-20 21:31:36 -0600 | [diff] [blame] | 600 | |
| 601 | Properties / Entry arguments: |
| 602 | - filename: Filename of file to read into entry |
| 603 | |
| 604 | This file contains a binary blob which is used on some devices to set up |
| 605 | temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so |
| 606 | that it has access to memory for its stack and initial storage. |
| 607 | |
| 608 | An example filename is 'fsp_t.bin' |
| 609 | |
| 610 | See README.x86 for information about x86 binary blobs. |
| 611 | |
| 612 | |
| 613 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 614 | Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file |
| 615 | -------------------------------------------------------------- |
Simon Glass | e073d4e | 2019-07-08 13:18:56 -0600 | [diff] [blame] | 616 | |
| 617 | Properties / Entry arguments: |
| 618 | - filename: Filename of file to read into entry. This is either the |
| 619 | IFWI file itself, or a file that can be converted into one using a |
| 620 | tool |
| 621 | - convert-fit: If present this indicates that the ifwitool should be |
| 622 | used to convert the provided file into a IFWI. |
| 623 | |
| 624 | This file contains code and data used by the SoC that is required to make |
| 625 | it work. It includes U-Boot TPL, microcode, things related to the CSE |
| 626 | (Converged Security Engine, the microcontroller that loads all the firmware) |
| 627 | and other items beyond the wit of man. |
| 628 | |
| 629 | A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a |
| 630 | file that will be converted to an IFWI. |
| 631 | |
| 632 | The position of this entry is generally set by the intel-descriptor entry. |
| 633 | |
| 634 | The contents of the IFWI are specified by the subnodes of the IFWI node. |
| 635 | Each subnode describes an entry which is placed into the IFWFI with a given |
| 636 | sub-partition (and optional entry name). |
| 637 | |
Simon Glass | 3da9ce8 | 2019-08-24 07:22:47 -0600 | [diff] [blame] | 638 | Properties for subnodes: |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 639 | - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP" |
| 640 | - ifwi-entry: entry name t use, e.g. "IBBL" |
| 641 | - ifwi-replace: if present, indicates that the item should be replaced |
| 642 | in the IFWI. Otherwise it is added. |
Simon Glass | 3da9ce8 | 2019-08-24 07:22:47 -0600 | [diff] [blame] | 643 | |
Simon Glass | e073d4e | 2019-07-08 13:18:56 -0600 | [diff] [blame] | 644 | See README.x86 for information about x86 binary blobs. |
| 645 | |
| 646 | |
| 647 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 648 | Entry: intel-me: Intel Management Engine (ME) file |
| 649 | -------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 650 | |
| 651 | Properties / Entry arguments: |
| 652 | - filename: Filename of file to read into entry |
| 653 | |
| 654 | This file contains code used by the SoC that is required to make it work. |
| 655 | The Management Engine is like a background task that runs things that are |
Thomas Hebb | 32f2ca2 | 2019-11-13 18:18:03 -0800 | [diff] [blame] | 656 | not clearly documented, but may include keyboard, display and network |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 657 | access. For platform that use ME it is not possible to disable it. U-Boot |
| 658 | does not directly execute code in the ME binary. |
| 659 | |
| 660 | A typical filename is 'me.bin'. |
| 661 | |
Simon Glass | fa1c937 | 2019-07-08 13:18:38 -0600 | [diff] [blame] | 662 | The position of this entry is generally set by the intel-descriptor entry. |
| 663 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 664 | See README.x86 for information about x86 binary blobs. |
| 665 | |
| 666 | |
| 667 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 668 | Entry: intel-mrc: Intel Memory Reference Code (MRC) file |
| 669 | -------------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 670 | |
| 671 | Properties / Entry arguments: |
| 672 | - filename: Filename of file to read into entry |
| 673 | |
| 674 | This file contains code for setting up the SDRAM on some Intel systems. This |
| 675 | is executed by U-Boot when needed early during startup. A typical filename |
| 676 | is 'mrc.bin'. |
| 677 | |
| 678 | See README.x86 for information about x86 binary blobs. |
| 679 | |
| 680 | |
| 681 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 682 | Entry: intel-refcode: Intel Reference Code file |
| 683 | ----------------------------------------------- |
Simon Glass | 5385f5a | 2019-05-17 22:00:53 -0600 | [diff] [blame] | 684 | |
| 685 | Properties / Entry arguments: |
| 686 | - filename: Filename of file to read into entry |
| 687 | |
| 688 | This file contains code for setting up the platform on some Intel systems. |
| 689 | This is executed by U-Boot when needed early during startup. A typical |
| 690 | filename is 'refcode.bin'. |
| 691 | |
| 692 | See README.x86 for information about x86 binary blobs. |
| 693 | |
| 694 | |
| 695 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 696 | Entry: intel-vbt: Intel Video BIOS Table (VBT) file |
| 697 | --------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 698 | |
| 699 | Properties / Entry arguments: |
| 700 | - filename: Filename of file to read into entry |
| 701 | |
| 702 | This file contains code that sets up the integrated graphics subsystem on |
| 703 | some Intel SoCs. U-Boot executes this when the display is started up. |
| 704 | |
| 705 | See README.x86 for information about Intel binary blobs. |
| 706 | |
| 707 | |
| 708 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 709 | Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file |
| 710 | --------------------------------------------------------- |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 711 | |
| 712 | Properties / Entry arguments: |
| 713 | - filename: Filename of file to read into entry |
| 714 | |
| 715 | This file contains code that sets up the integrated graphics subsystem on |
| 716 | some Intel SoCs. U-Boot executes this when the display is started up. |
| 717 | |
| 718 | This is similar to the VBT file but in a different format. |
| 719 | |
| 720 | See README.x86 for information about Intel binary blobs. |
| 721 | |
| 722 | |
| 723 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 724 | Entry: mkimage: Binary produced by mkimage |
| 725 | ------------------------------------------ |
Simon Glass | 0dc706f | 2020-07-09 18:39:31 -0600 | [diff] [blame] | 726 | |
| 727 | Properties / Entry arguments: |
| 728 | - datafile: Filename for -d argument |
| 729 | - args: Other arguments to pass |
| 730 | |
| 731 | The data passed to mkimage is collected from subnodes of the mkimage node, |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 732 | e.g.:: |
Simon Glass | 0dc706f | 2020-07-09 18:39:31 -0600 | [diff] [blame] | 733 | |
| 734 | mkimage { |
| 735 | args = "-n test -T imximage"; |
| 736 | |
| 737 | u-boot-spl { |
| 738 | }; |
| 739 | }; |
| 740 | |
| 741 | This calls mkimage to create an imximage with u-boot-spl.bin as the input |
| 742 | file. The output from mkimage then becomes part of the image produced by |
| 743 | binman. |
| 744 | |
| 745 | |
| 746 | |
Jagdish Gediya | 9d368f3 | 2018-09-03 21:35:08 +0530 | [diff] [blame] | 747 | Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot |
| 748 | ----------------------------------------------------------------------------------------- |
| 749 | |
| 750 | Properties / Entry arguments: |
| 751 | - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin') |
| 752 | |
Thomas Hebb | 32f2ca2 | 2019-11-13 18:18:03 -0800 | [diff] [blame] | 753 | This entry is valid for PowerPC mpc85xx cpus. This entry holds |
Jagdish Gediya | 9d368f3 | 2018-09-03 21:35:08 +0530 | [diff] [blame] | 754 | 'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be |
| 755 | placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'. |
| 756 | |
| 757 | |
| 758 | |
Simon Glass | 96d340e | 2021-03-18 20:25:16 +1300 | [diff] [blame^] | 759 | Entry: scp: System Control Processor (SCP) firmware blob |
| 760 | -------------------------------------------------------- |
Simon Glass | f324330 | 2020-10-26 17:39:59 -0600 | [diff] [blame] | 761 | |
| 762 | Properties / Entry arguments: |
| 763 | - scp-path: Filename of file to read into the entry, typically scp.bin |
| 764 | |
| 765 | This entry holds firmware for an external platform-specific coprocessor. |
| 766 | |
| 767 | |
| 768 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 769 | Entry: section: Entry that contains other entries |
| 770 | ------------------------------------------------- |
| 771 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 772 | Properties / Entry arguments: (see binman README for more information): |
Simon Glass | 8beb11e | 2019-07-08 14:25:47 -0600 | [diff] [blame] | 773 | pad-byte: Pad byte to use when padding |
| 774 | sort-by-offset: True if entries should be sorted by offset, False if |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 775 | they must be in-order in the device tree description |
| 776 | |
Simon Glass | 8beb11e | 2019-07-08 14:25:47 -0600 | [diff] [blame] | 777 | end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 778 | |
Simon Glass | 8beb11e | 2019-07-08 14:25:47 -0600 | [diff] [blame] | 779 | skip-at-start: Number of bytes before the first entry starts. These |
| 780 | effectively adjust the starting offset of entries. For example, |
| 781 | if this is 16, then the first entry would start at 16. An entry |
| 782 | with offset = 20 would in fact be written at offset 4 in the image |
| 783 | file, since the first 16 bytes are skipped when writing. |
| 784 | name-prefix: Adds a prefix to the name of every entry in the section |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 785 | when writing out the map |
| 786 | |
Simon Glass | 3decfa3 | 2020-09-01 05:13:54 -0600 | [diff] [blame] | 787 | Properties: |
Simon Glass | 8795898 | 2020-09-01 05:13:57 -0600 | [diff] [blame] | 788 | allow_missing: True if this section permits external blobs to be |
Simon Glass | 3decfa3 | 2020-09-01 05:13:54 -0600 | [diff] [blame] | 789 | missing their contents. The second will produce an image but of |
| 790 | course it will not work. |
| 791 | |
Simon Glass | 8beb11e | 2019-07-08 14:25:47 -0600 | [diff] [blame] | 792 | Since a section is also an entry, it inherits all the properies of entries |
| 793 | too. |
| 794 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 795 | A section is an entry which can contain other entries, thus allowing |
| 796 | hierarchical images to be created. See 'Sections and hierarchical images' |
| 797 | in the binman README for more information. |
| 798 | |
| 799 | |
| 800 | |
| 801 | Entry: text: An entry which contains text |
| 802 | ----------------------------------------- |
| 803 | |
| 804 | The text can be provided either in the node itself or by a command-line |
| 805 | argument. There is a level of indirection to allow multiple text strings |
| 806 | and sharing of text. |
| 807 | |
| 808 | Properties / Entry arguments: |
| 809 | text-label: The value of this string indicates the property / entry-arg |
| 810 | that contains the string to place in the entry |
| 811 | <xxx> (actual name is the value of text-label): contains the string to |
| 812 | place in the entry. |
Simon Glass | aa88b50 | 2019-07-08 13:18:40 -0600 | [diff] [blame] | 813 | <text>: The text to place in the entry (overrides the above mechanism). |
| 814 | This is useful when the text is constant. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 815 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 816 | Example node:: |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 817 | |
| 818 | text { |
| 819 | size = <50>; |
| 820 | text-label = "message"; |
| 821 | }; |
| 822 | |
| 823 | You can then use: |
| 824 | |
| 825 | binman -amessage="this is my message" |
| 826 | |
| 827 | and binman will insert that string into the entry. |
| 828 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 829 | It is also possible to put the string directly in the node:: |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 830 | |
| 831 | text { |
| 832 | size = <8>; |
| 833 | text-label = "message"; |
| 834 | message = "a message directly in the node" |
| 835 | }; |
| 836 | |
Simon Glass | 6bc4309 | 2021-03-18 20:25:15 +1300 | [diff] [blame] | 837 | or just:: |
Simon Glass | aa88b50 | 2019-07-08 13:18:40 -0600 | [diff] [blame] | 838 | |
| 839 | text { |
| 840 | size = <8>; |
| 841 | text = "some text directly in the node" |
| 842 | }; |
| 843 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 844 | The text is not itself nul-terminated. This can be achieved, if required, |
| 845 | by setting the size of the entry to something larger than the text. |
| 846 | |
| 847 | |
| 848 | |
| 849 | Entry: u-boot: U-Boot flat binary |
| 850 | --------------------------------- |
| 851 | |
| 852 | Properties / Entry arguments: |
| 853 | - filename: Filename of u-boot.bin (default 'u-boot.bin') |
| 854 | |
| 855 | This is the U-Boot binary, containing relocation information to allow it |
| 856 | to relocate itself at runtime. The binary typically includes a device tree |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 857 | blob at the end of it. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 858 | |
| 859 | U-Boot can access binman symbols at runtime. See: |
| 860 | |
| 861 | 'Access to binman entry offsets at run time (fdt)' |
| 862 | |
| 863 | in the binman README for more information. |
| 864 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 865 | Note that this entry is automatically replaced with u-boot-expanded unless |
| 866 | --no-expanded is used. |
| 867 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 868 | |
| 869 | |
| 870 | Entry: u-boot-dtb: U-Boot device tree |
| 871 | ------------------------------------- |
| 872 | |
| 873 | Properties / Entry arguments: |
| 874 | - filename: Filename of u-boot.dtb (default 'u-boot.dtb') |
| 875 | |
| 876 | This is the U-Boot device tree, containing configuration information for |
| 877 | U-Boot. U-Boot needs this to know what devices are present and which drivers |
| 878 | to activate. |
| 879 | |
Simon Glass | 6ed45ba | 2018-09-14 04:57:24 -0600 | [diff] [blame] | 880 | Note: This is mostly an internal entry type, used by others. This allows |
| 881 | binman to know which entries contain a device tree. |
| 882 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 883 | |
| 884 | |
| 885 | Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed |
| 886 | ----------------------------------------------------------------------------------- |
| 887 | |
| 888 | Properties / Entry arguments: |
| 889 | - filename: Filename of u-boot.dtb (default 'u-boot.dtb') |
| 890 | |
| 891 | See Entry_u_boot_ucode for full details of the three entries involved in |
| 892 | this process. This entry provides the U-Boot device-tree file, which |
| 893 | contains the microcode. If the microcode is not being collated into one |
| 894 | place then the offset and size of the microcode is recorded by this entry, |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 895 | for use by u-boot-with-ucode_ptr. If it is being collated, then this |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 896 | entry deletes the microcode from the device tree (to save space) and makes |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 897 | it available to u-boot-ucode. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 898 | |
| 899 | |
| 900 | |
Simon Glass | fe1ae3e | 2018-09-14 04:57:35 -0600 | [diff] [blame] | 901 | Entry: u-boot-elf: U-Boot ELF image |
| 902 | ----------------------------------- |
| 903 | |
| 904 | Properties / Entry arguments: |
| 905 | - filename: Filename of u-boot (default 'u-boot') |
| 906 | |
| 907 | This is the U-Boot ELF image. It does not include a device tree but can be |
| 908 | relocated to any address for execution. |
| 909 | |
| 910 | |
| 911 | |
Simon Glass | f324330 | 2020-10-26 17:39:59 -0600 | [diff] [blame] | 912 | Entry: u-boot-env: An entry which contains a U-Boot environment |
| 913 | --------------------------------------------------------------- |
| 914 | |
| 915 | Properties / Entry arguments: |
| 916 | - filename: File containing the environment text, with each line in the |
| 917 | form var=value |
| 918 | |
| 919 | |
| 920 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 921 | Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts |
| 922 | ------------------------------------------------------------------------------ |
| 923 | |
| 924 | This is a section containing the U-Boot binary and a devicetree. Using this |
| 925 | entry type automatically creates this section, with the following entries |
| 926 | in it: |
| 927 | |
| 928 | u-boot-nodtb |
| 929 | u-boot-dtb |
| 930 | |
| 931 | Having the devicetree separate allows binman to update it in the final |
| 932 | image, so that the entries positions are provided to the running U-Boot. |
| 933 | |
| 934 | |
| 935 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 936 | Entry: u-boot-img: U-Boot legacy image |
| 937 | -------------------------------------- |
| 938 | |
| 939 | Properties / Entry arguments: |
| 940 | - filename: Filename of u-boot.img (default 'u-boot.img') |
| 941 | |
| 942 | This is the U-Boot binary as a packaged image, in legacy format. It has a |
| 943 | header which allows it to be loaded at the correct address for execution. |
| 944 | |
| 945 | You should use FIT (Flat Image Tree) instead of the legacy image for new |
| 946 | applications. |
| 947 | |
| 948 | |
| 949 | |
| 950 | Entry: u-boot-nodtb: U-Boot flat binary without device tree appended |
| 951 | -------------------------------------------------------------------- |
| 952 | |
| 953 | Properties / Entry arguments: |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 954 | - filename: Filename to include (default 'u-boot-nodtb.bin') |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 955 | |
| 956 | This is the U-Boot binary, containing relocation information to allow it |
| 957 | to relocate itself at runtime. It does not include a device tree blob at |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 958 | the end of it so normally cannot work without it. You can add a u-boot-dtb |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 959 | entry after this one, or use a u-boot entry instead, normally expands to a |
| 960 | section containing u-boot and u-boot-dtb |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 961 | |
| 962 | |
| 963 | |
| 964 | Entry: u-boot-spl: U-Boot SPL binary |
| 965 | ------------------------------------ |
| 966 | |
| 967 | Properties / Entry arguments: |
| 968 | - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') |
| 969 | |
| 970 | This is the U-Boot SPL (Secondary Program Loader) binary. This is a small |
| 971 | binary which loads before U-Boot proper, typically into on-chip SRAM. It is |
| 972 | responsible for locating, loading and jumping to U-Boot. Note that SPL is |
| 973 | not relocatable so must be loaded to the correct address in SRAM, or written |
Simon Glass | b8ef5b6 | 2018-07-17 13:25:48 -0600 | [diff] [blame] | 974 | to run from the correct address if direct flash execution is possible (e.g. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 975 | on x86 devices). |
| 976 | |
| 977 | SPL can access binman symbols at runtime. See: |
| 978 | |
| 979 | 'Access to binman entry offsets at run time (symbols)' |
| 980 | |
| 981 | in the binman README for more information. |
| 982 | |
| 983 | The ELF file 'spl/u-boot-spl' must also be available for this to work, since |
| 984 | binman uses that to look up symbols to write into the SPL binary. |
| 985 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 986 | Note that this entry is automatically replaced with u-boot-spl-expanded |
| 987 | unless --no-expanded is used. |
| 988 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 989 | |
| 990 | |
| 991 | Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region |
| 992 | --------------------------------------------------------------------- |
| 993 | |
| 994 | Properties / Entry arguments: |
| 995 | None |
| 996 | |
Simon Glass | dccdc38 | 2021-03-18 20:24:55 +1300 | [diff] [blame] | 997 | This holds the padding added after the SPL binary to cover the BSS (Block |
| 998 | Started by Symbol) region. This region holds the various variables used by |
| 999 | SPL. It is set to 0 by SPL when it starts up. If you want to append data to |
| 1000 | the SPL image (such as a device tree file), you must pad out the BSS region |
| 1001 | to avoid the data overlapping with U-Boot variables. This entry is useful in |
| 1002 | that case. It automatically pads out the entry size to cover both the code, |
| 1003 | data and BSS. |
| 1004 | |
| 1005 | The contents of this entry will a certain number of zero bytes, determined |
| 1006 | by __bss_size |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1007 | |
| 1008 | The ELF file 'spl/u-boot-spl' must also be available for this to work, since |
| 1009 | binman uses that to look up the BSS address. |
| 1010 | |
| 1011 | |
| 1012 | |
| 1013 | Entry: u-boot-spl-dtb: U-Boot SPL device tree |
| 1014 | --------------------------------------------- |
| 1015 | |
| 1016 | Properties / Entry arguments: |
| 1017 | - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') |
| 1018 | |
| 1019 | This is the SPL device tree, containing configuration information for |
| 1020 | SPL. SPL needs this to know what devices are present and which drivers |
| 1021 | to activate. |
| 1022 | |
| 1023 | |
| 1024 | |
Simon Glass | fe1ae3e | 2018-09-14 04:57:35 -0600 | [diff] [blame] | 1025 | Entry: u-boot-spl-elf: U-Boot SPL ELF image |
| 1026 | ------------------------------------------- |
| 1027 | |
| 1028 | Properties / Entry arguments: |
Simon Glass | a6a520e | 2019-07-08 13:18:45 -0600 | [diff] [blame] | 1029 | - filename: Filename of SPL u-boot (default 'spl/u-boot-spl') |
Simon Glass | fe1ae3e | 2018-09-14 04:57:35 -0600 | [diff] [blame] | 1030 | |
| 1031 | This is the U-Boot SPL ELF image. It does not include a device tree but can |
| 1032 | be relocated to any address for execution. |
| 1033 | |
| 1034 | |
| 1035 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 1036 | Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts |
| 1037 | -------------------------------------------------------------------------------------- |
| 1038 | |
| 1039 | Properties / Entry arguments: |
| 1040 | - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to |
| 1041 | select) |
| 1042 | |
| 1043 | This is a section containing the U-Boot binary, BSS padding if needed and a |
| 1044 | devicetree. Using this entry type automatically creates this section, with |
| 1045 | the following entries in it: |
| 1046 | |
| 1047 | u-boot-spl-nodtb |
| 1048 | u-boot-spl-bss-pad |
| 1049 | u-boot-dtb |
| 1050 | |
| 1051 | Having the devicetree separate allows binman to update it in the final |
| 1052 | image, so that the entries positions are provided to the running U-Boot. |
| 1053 | |
| 1054 | This entry is selected based on the value of the 'spl-dtb' entryarg. If |
| 1055 | this is non-empty (and not 'n' or '0') then this expanded entry is selected. |
| 1056 | |
| 1057 | |
| 1058 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1059 | Entry: u-boot-spl-nodtb: SPL binary without device tree appended |
| 1060 | ---------------------------------------------------------------- |
| 1061 | |
| 1062 | Properties / Entry arguments: |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 1063 | - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin') |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1064 | |
| 1065 | This is the U-Boot SPL binary, It does not include a device tree blob at |
| 1066 | the end of it so may not be able to work without it, assuming SPL needs |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 1067 | a device tree to operate on your platform. You can add a u-boot-spl-dtb |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 1068 | entry after this one, or use a u-boot-spl entry instead' which normally |
| 1069 | expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and |
| 1070 | u-boot-spl-dtb |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1071 | |
Simon Glass | f589882 | 2021-03-18 20:24:56 +1300 | [diff] [blame] | 1072 | SPL can access binman symbols at runtime. See: |
| 1073 | |
| 1074 | 'Access to binman entry offsets at run time (symbols)' |
| 1075 | |
| 1076 | in the binman README for more information. |
| 1077 | |
| 1078 | The ELF file 'spl/u-boot-spl' must also be available for this to work, since |
| 1079 | binman uses that to look up symbols to write into the SPL binary. |
| 1080 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1081 | |
| 1082 | |
| 1083 | Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer |
| 1084 | ---------------------------------------------------------------------------- |
| 1085 | |
Simon Glass | f025363 | 2018-09-14 04:57:32 -0600 | [diff] [blame] | 1086 | This is used when SPL must set up the microcode for U-Boot. |
| 1087 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1088 | See Entry_u_boot_ucode for full details of the entries involved in this |
| 1089 | process. |
| 1090 | |
| 1091 | |
| 1092 | |
Simon Glass | b8ef5b6 | 2018-07-17 13:25:48 -0600 | [diff] [blame] | 1093 | Entry: u-boot-tpl: U-Boot TPL binary |
| 1094 | ------------------------------------ |
| 1095 | |
| 1096 | Properties / Entry arguments: |
| 1097 | - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') |
| 1098 | |
| 1099 | This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small |
| 1100 | binary which loads before SPL, typically into on-chip SRAM. It is |
| 1101 | responsible for locating, loading and jumping to SPL, the next-stage |
| 1102 | loader. Note that SPL is not relocatable so must be loaded to the correct |
| 1103 | address in SRAM, or written to run from the correct address if direct |
| 1104 | flash execution is possible (e.g. on x86 devices). |
| 1105 | |
| 1106 | SPL can access binman symbols at runtime. See: |
| 1107 | |
| 1108 | 'Access to binman entry offsets at run time (symbols)' |
| 1109 | |
| 1110 | in the binman README for more information. |
| 1111 | |
| 1112 | The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since |
| 1113 | binman uses that to look up symbols to write into the TPL binary. |
| 1114 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 1115 | Note that this entry is automatically replaced with u-boot-tpl-expanded |
| 1116 | unless --no-expanded is used. |
| 1117 | |
Simon Glass | b8ef5b6 | 2018-07-17 13:25:48 -0600 | [diff] [blame] | 1118 | |
| 1119 | |
Simon Glass | d26efc8 | 2021-03-18 20:24:58 +1300 | [diff] [blame] | 1120 | Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region |
| 1121 | --------------------------------------------------------------------- |
| 1122 | |
| 1123 | Properties / Entry arguments: |
| 1124 | None |
| 1125 | |
| 1126 | This holds the padding added after the TPL binary to cover the BSS (Block |
| 1127 | Started by Symbol) region. This region holds the various variables used by |
| 1128 | TPL. It is set to 0 by TPL when it starts up. If you want to append data to |
| 1129 | the TPL image (such as a device tree file), you must pad out the BSS region |
| 1130 | to avoid the data overlapping with U-Boot variables. This entry is useful in |
| 1131 | that case. It automatically pads out the entry size to cover both the code, |
| 1132 | data and BSS. |
| 1133 | |
| 1134 | The contents of this entry will a certain number of zero bytes, determined |
| 1135 | by __bss_size |
| 1136 | |
| 1137 | The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since |
| 1138 | binman uses that to look up the BSS address. |
| 1139 | |
| 1140 | |
| 1141 | |
Simon Glass | b8ef5b6 | 2018-07-17 13:25:48 -0600 | [diff] [blame] | 1142 | Entry: u-boot-tpl-dtb: U-Boot TPL device tree |
| 1143 | --------------------------------------------- |
| 1144 | |
| 1145 | Properties / Entry arguments: |
| 1146 | - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') |
| 1147 | |
| 1148 | This is the TPL device tree, containing configuration information for |
| 1149 | TPL. TPL needs this to know what devices are present and which drivers |
| 1150 | to activate. |
| 1151 | |
| 1152 | |
| 1153 | |
Simon Glass | f025363 | 2018-09-14 04:57:32 -0600 | [diff] [blame] | 1154 | Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer |
| 1155 | ---------------------------------------------------------------------------- |
| 1156 | |
| 1157 | This is used when TPL must set up the microcode for U-Boot. |
| 1158 | |
| 1159 | See Entry_u_boot_ucode for full details of the entries involved in this |
| 1160 | process. |
| 1161 | |
| 1162 | |
| 1163 | |
Simon Glass | 4c65025 | 2019-07-08 13:18:46 -0600 | [diff] [blame] | 1164 | Entry: u-boot-tpl-elf: U-Boot TPL ELF image |
| 1165 | ------------------------------------------- |
| 1166 | |
| 1167 | Properties / Entry arguments: |
| 1168 | - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl') |
| 1169 | |
| 1170 | This is the U-Boot TPL ELF image. It does not include a device tree but can |
| 1171 | be relocated to any address for execution. |
| 1172 | |
| 1173 | |
| 1174 | |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 1175 | Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts |
| 1176 | -------------------------------------------------------------------------------------- |
| 1177 | |
| 1178 | Properties / Entry arguments: |
| 1179 | - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to |
| 1180 | select) |
| 1181 | |
| 1182 | This is a section containing the U-Boot binary, BSS padding if needed and a |
| 1183 | devicetree. Using this entry type automatically creates this section, with |
| 1184 | the following entries in it: |
| 1185 | |
| 1186 | u-boot-tpl-nodtb |
| 1187 | u-boot-tpl-bss-pad |
| 1188 | u-boot-dtb |
| 1189 | |
| 1190 | Having the devicetree separate allows binman to update it in the final |
| 1191 | image, so that the entries positions are provided to the running U-Boot. |
| 1192 | |
| 1193 | This entry is selected based on the value of the 'tpl-dtb' entryarg. If |
| 1194 | this is non-empty (and not 'n' or '0') then this expanded entry is selected. |
| 1195 | |
| 1196 | |
| 1197 | |
Simon Glass | 77a64e0 | 2021-03-18 20:24:57 +1300 | [diff] [blame] | 1198 | Entry: u-boot-tpl-nodtb: TPL binary without device tree appended |
| 1199 | ---------------------------------------------------------------- |
| 1200 | |
| 1201 | Properties / Entry arguments: |
| 1202 | - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin') |
| 1203 | |
| 1204 | This is the U-Boot TPL binary, It does not include a device tree blob at |
| 1205 | the end of it so may not be able to work without it, assuming TPL needs |
| 1206 | a device tree to operate on your platform. You can add a u-boot-tpl-dtb |
Simon Glass | 0668492 | 2021-03-18 20:25:07 +1300 | [diff] [blame] | 1207 | entry after this one, or use a u-boot-tpl entry instead, which normally |
| 1208 | expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and |
| 1209 | u-boot-tpl-dtb |
Simon Glass | 77a64e0 | 2021-03-18 20:24:57 +1300 | [diff] [blame] | 1210 | |
| 1211 | TPL can access binman symbols at runtime. See: |
| 1212 | |
| 1213 | 'Access to binman entry offsets at run time (symbols)' |
| 1214 | |
| 1215 | in the binman README for more information. |
| 1216 | |
| 1217 | The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since |
| 1218 | binman uses that to look up symbols to write into the TPL binary. |
| 1219 | |
| 1220 | |
| 1221 | |
Simon Glass | f025363 | 2018-09-14 04:57:32 -0600 | [diff] [blame] | 1222 | Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer |
| 1223 | ---------------------------------------------------------------------------- |
| 1224 | |
| 1225 | See Entry_u_boot_ucode for full details of the entries involved in this |
| 1226 | process. |
| 1227 | |
| 1228 | |
| 1229 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1230 | Entry: u-boot-ucode: U-Boot microcode block |
| 1231 | ------------------------------------------- |
| 1232 | |
| 1233 | Properties / Entry arguments: |
| 1234 | None |
| 1235 | |
| 1236 | The contents of this entry are filled in automatically by other entries |
| 1237 | which must also be in the image. |
| 1238 | |
| 1239 | U-Boot on x86 needs a single block of microcode. This is collected from |
| 1240 | the various microcode update nodes in the device tree. It is also unable |
| 1241 | to read the microcode from the device tree on platforms that use FSP |
| 1242 | (Firmware Support Package) binaries, because the API requires that the |
| 1243 | microcode is supplied before there is any SRAM available to use (i.e. |
| 1244 | the FSP sets up the SRAM / cache-as-RAM but does so in the call that |
| 1245 | requires the microcode!). To keep things simple, all x86 platforms handle |
| 1246 | microcode the same way in U-Boot (even non-FSP platforms). This is that |
| 1247 | a table is placed at _dt_ucode_base_size containing the base address and |
| 1248 | size of the microcode. This is either passed to the FSP (for FSP |
| 1249 | platforms), or used to set up the microcode (for non-FSP platforms). |
| 1250 | This all happens in the build system since it is the only way to get |
| 1251 | the microcode into a single blob and accessible without SRAM. |
| 1252 | |
| 1253 | There are two cases to handle. If there is only one microcode blob in |
| 1254 | the device tree, then the ucode pointer it set to point to that. This |
| 1255 | entry (u-boot-ucode) is empty. If there is more than one update, then |
| 1256 | this entry holds the concatenation of all updates, and the device tree |
| 1257 | entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This |
| 1258 | last step ensures that that the microcode appears in one contiguous |
| 1259 | block in the image and is not unnecessarily duplicated in the device |
| 1260 | tree. It is referred to as 'collation' here. |
| 1261 | |
| 1262 | Entry types that have a part to play in handling microcode: |
| 1263 | |
| 1264 | Entry_u_boot_with_ucode_ptr: |
| 1265 | Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). |
| 1266 | It updates it with the address and size of the microcode so that |
| 1267 | U-Boot can find it early on start-up. |
| 1268 | Entry_u_boot_dtb_with_ucode: |
| 1269 | Contains u-boot.dtb. It stores the microcode in a |
| 1270 | 'self.ucode_data' property, which is then read by this class to |
| 1271 | obtain the microcode if needed. If collation is performed, it |
| 1272 | removes the microcode from the device tree. |
| 1273 | Entry_u_boot_ucode: |
| 1274 | This class. If collation is enabled it reads the microcode from |
| 1275 | the Entry_u_boot_dtb_with_ucode entry, and uses it as the |
| 1276 | contents of this entry. |
| 1277 | |
| 1278 | |
| 1279 | |
| 1280 | Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer |
| 1281 | -------------------------------------------------------------------- |
| 1282 | |
| 1283 | Properties / Entry arguments: |
Masahiro Yamada | f6a8c0f | 2019-12-14 13:47:26 +0900 | [diff] [blame] | 1284 | - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin') |
Simon Glass | f069303 | 2018-09-14 04:57:07 -0600 | [diff] [blame] | 1285 | - optional-ucode: boolean property to make microcode optional. If the |
| 1286 | u-boot.bin image does not include microcode, no error will |
| 1287 | be generated. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1288 | |
| 1289 | See Entry_u_boot_ucode for full details of the three entries involved in |
| 1290 | this process. This entry updates U-Boot with the offset and size of the |
| 1291 | microcode, to allow early x86 boot code to find it without doing anything |
Simon Glass | adc59ea | 2021-03-18 20:24:54 +1300 | [diff] [blame] | 1292 | complicated. Otherwise it is the same as the u-boot entry. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1293 | |
| 1294 | |
| 1295 | |
Simon Glass | 24d0d3c | 2018-07-17 13:25:47 -0600 | [diff] [blame] | 1296 | Entry: vblock: An entry which contains a Chromium OS verified boot block |
| 1297 | ------------------------------------------------------------------------ |
| 1298 | |
| 1299 | Properties / Entry arguments: |
Simon Glass | 5385f5a | 2019-05-17 22:00:53 -0600 | [diff] [blame] | 1300 | - content: List of phandles to entries to sign |
Simon Glass | 24d0d3c | 2018-07-17 13:25:47 -0600 | [diff] [blame] | 1301 | - keydir: Directory containing the public keys to use |
| 1302 | - keyblock: Name of the key file to use (inside keydir) |
| 1303 | - signprivate: Name of provide key file to use (inside keydir) |
| 1304 | - version: Version number of the vblock (typically 1) |
| 1305 | - kernelkey: Name of the kernel key to use (inside keydir) |
| 1306 | - preamble-flags: Value of the vboot preamble flags (typically 0) |
| 1307 | |
Simon Glass | a326b49 | 2018-09-14 04:57:11 -0600 | [diff] [blame] | 1308 | Output files: |
| 1309 | - input.<unique_name> - input file passed to futility |
| 1310 | - vblock.<unique_name> - output file generated by futility (which is |
| 1311 | used as the entry contents) |
| 1312 | |
Jagdish Gediya | 9d368f3 | 2018-09-03 21:35:08 +0530 | [diff] [blame] | 1313 | Chromium OS signs the read-write firmware and kernel, writing the signature |
Simon Glass | 24d0d3c | 2018-07-17 13:25:47 -0600 | [diff] [blame] | 1314 | in this block. This allows U-Boot to verify that the next firmware stage |
| 1315 | and kernel are genuine. |
| 1316 | |
| 1317 | |
| 1318 | |
Simon Glass | 2250ee6 | 2019-08-24 07:22:48 -0600 | [diff] [blame] | 1319 | Entry: x86-reset16: x86 16-bit reset code for U-Boot |
| 1320 | ---------------------------------------------------- |
| 1321 | |
| 1322 | Properties / Entry arguments: |
| 1323 | - filename: Filename of u-boot-x86-reset16.bin (default |
| 1324 | 'u-boot-x86-reset16.bin') |
| 1325 | |
| 1326 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
| 1327 | must be placed at a particular address. This entry holds that code. It is |
| 1328 | typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible |
| 1329 | for jumping to the x86-start16 code, which continues execution. |
| 1330 | |
| 1331 | For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead. |
| 1332 | |
| 1333 | |
| 1334 | |
| 1335 | Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot |
| 1336 | -------------------------------------------------------- |
| 1337 | |
| 1338 | Properties / Entry arguments: |
| 1339 | - filename: Filename of u-boot-x86-reset16.bin (default |
| 1340 | 'u-boot-x86-reset16.bin') |
| 1341 | |
| 1342 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
| 1343 | must be placed at a particular address. This entry holds that code. It is |
| 1344 | typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible |
| 1345 | for jumping to the x86-start16 code, which continues execution. |
| 1346 | |
| 1347 | For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead. |
| 1348 | |
| 1349 | |
| 1350 | |
| 1351 | Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot |
| 1352 | -------------------------------------------------------- |
| 1353 | |
| 1354 | Properties / Entry arguments: |
| 1355 | - filename: Filename of u-boot-x86-reset16.bin (default |
| 1356 | 'u-boot-x86-reset16.bin') |
| 1357 | |
| 1358 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
| 1359 | must be placed at a particular address. This entry holds that code. It is |
| 1360 | typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible |
| 1361 | for jumping to the x86-start16 code, which continues execution. |
| 1362 | |
| 1363 | For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead. |
| 1364 | |
| 1365 | |
| 1366 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1367 | Entry: x86-start16: x86 16-bit start-up code for U-Boot |
| 1368 | ------------------------------------------------------- |
| 1369 | |
| 1370 | Properties / Entry arguments: |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1371 | - filename: Filename of u-boot-x86-start16.bin (default |
| 1372 | 'u-boot-x86-start16.bin') |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1373 | |
| 1374 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1375 | must be placed in the top 64KB of the ROM. The reset code jumps to it. This |
| 1376 | entry holds that code. It is typically placed at offset |
| 1377 | CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode |
| 1378 | and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit |
| 1379 | U-Boot). |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1380 | |
| 1381 | For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. |
| 1382 | |
| 1383 | |
| 1384 | |
| 1385 | Entry: x86-start16-spl: x86 16-bit start-up code for SPL |
| 1386 | -------------------------------------------------------- |
| 1387 | |
| 1388 | Properties / Entry arguments: |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1389 | - filename: Filename of spl/u-boot-x86-start16-spl.bin (default |
| 1390 | 'spl/u-boot-x86-start16-spl.bin') |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1391 | |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1392 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
| 1393 | must be placed in the top 64KB of the ROM. The reset code jumps to it. This |
| 1394 | entry holds that code. It is typically placed at offset |
| 1395 | CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode |
| 1396 | and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit |
| 1397 | U-Boot). |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1398 | |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1399 | For 32-bit U-Boot, the 'x86-start16' entry type is used instead. |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1400 | |
| 1401 | |
| 1402 | |
Simon Glass | 35b384c | 2018-09-14 04:57:10 -0600 | [diff] [blame] | 1403 | Entry: x86-start16-tpl: x86 16-bit start-up code for TPL |
| 1404 | -------------------------------------------------------- |
| 1405 | |
| 1406 | Properties / Entry arguments: |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1407 | - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default |
| 1408 | 'tpl/u-boot-x86-start16-tpl.bin') |
Simon Glass | 35b384c | 2018-09-14 04:57:10 -0600 | [diff] [blame] | 1409 | |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1410 | x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code |
| 1411 | must be placed in the top 64KB of the ROM. The reset code jumps to it. This |
| 1412 | entry holds that code. It is typically placed at offset |
| 1413 | CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode |
| 1414 | and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit |
| 1415 | U-Boot). |
Simon Glass | 35b384c | 2018-09-14 04:57:10 -0600 | [diff] [blame] | 1416 | |
Simon Glass | 5e23918 | 2019-08-24 07:22:49 -0600 | [diff] [blame] | 1417 | If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types |
Simon Glass | 35b384c | 2018-09-14 04:57:10 -0600 | [diff] [blame] | 1418 | may be used instead. |
| 1419 | |
| 1420 | |
| 1421 | |