1Binman Entry Documentation 2=========================== 3 4This file describes the entry types supported by binman. These entry types can 5be placed in an image one by one to build up a final firmware image. It is 6fairly easy to create new entry types. Just add a new file to the 'etype' 7directory. You can use the existing entries as examples. 8 9Note that some entries are subclasses of others, using and extending their 10features to produce new behaviours. 11 12 13 14Entry: blob: Entry containing an arbitrary binary blob 15------------------------------------------------------ 16 17Note: This should not be used by itself. It is normally used as a parent 18class by other entry types. 19 20Properties / Entry arguments: 21 - filename: Filename of file to read into entry 22 - compress: Compression algorithm to use: 23 none: No compression 24 lz4: Use lz4 compression (via 'lz4' command-line utility) 25 26This entry reads data from a file and places it in the entry. The 27default filename is often specified specified by the subclass. See for 28example the 'u_boot' entry which provides the filename 'u-boot.bin'. 29 30If compression is enabled, an extra 'uncomp-size' property is written to 31the node (if enabled with -u) which provides the uncompressed size of the 32data. 33 34 35 36Entry: blob-dtb: A blob that holds a device tree 37------------------------------------------------ 38 39This is a blob containing a device tree. The contents of the blob are 40obtained from the list of available device-tree files, managed by the 41'state' module. 42 43 44 45Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 46----------------------------------------------------------------------------------------- 47 48Properties / Entry arguments: 49 - <xxx>-path: Filename containing the contents of this entry (optional, 50 defaults to 0) 51 52where <xxx> is the blob_fname argument to the constructor. 53 54This entry cannot be used directly. Instead, it is used as a parent class 55for another entry, which defined blob_fname. This parameter is used to 56set the entry-arg or property containing the filename. The entry-arg or 57property is in turn used to set the actual filename. 58 59See cros_ec_rw for an example of this. 60 61 62 63Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 64-------------------------------------------------------------------------------- 65 66Properties / Entry arguments: 67 - cros-ec-rw-path: Filename containing the EC image 68 69This entry holds a Chromium OS EC (embedded controller) image, for use in 70updating the EC on startup via software sync. 71 72 73 74Entry: fill: An entry which is filled to a particular byte value 75---------------------------------------------------------------- 76 77Properties / Entry arguments: 78 - fill-byte: Byte to use to fill the entry 79 80Note that the size property must be set since otherwise this entry does not 81know how large it should be. 82 83You can often achieve the same effect using the pad-byte property of the 84overall image, in that the space between entries will then be padded with 85that byte. But this entry is sometimes useful for explicitly setting the 86byte value of a region. 87 88 89 90Entry: fmap: An entry which contains an Fmap section 91---------------------------------------------------- 92 93Properties / Entry arguments: 94 None 95 96FMAP is a simple format used by flashrom, an open-source utility for 97reading and writing the SPI flash, typically on x86 CPUs. The format 98provides flashrom with a list of areas, so it knows what it in the flash. 99It can then read or write just a single area, instead of the whole flash. 100 101The format is defined by the flashrom project, in the file lib/fmap.h - 102see www.flashrom.org/Flashrom for more information. 103 104When used, this entry will be populated with an FMAP which reflects the 105entries in the current image. Note that any hierarchy is squashed, since 106FMAP does not support this. 107 108 109 110Entry: gbb: An entry which contains a Chromium OS Google Binary Block 111--------------------------------------------------------------------- 112 113Properties / Entry arguments: 114 - hardware-id: Hardware ID to use for this build (a string) 115 - keydir: Directory containing the public keys to use 116 - bmpblk: Filename containing images used by recovery 117 118Chromium OS uses a GBB to store various pieces of information, in particular 119the root and recovery keys that are used to verify the boot process. Some 120more details are here: 121 122 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts 123 124but note that the page dates from 2013 so is quite out of date. See 125README.chromium for how to obtain the required keys and tools. 126 127 128 129Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file 130------------------------------------------------------------------------- 131 132Properties / Entry arguments: 133 - filename: Filename of file to read into entry 134 135This file contains microcode for some devices in a special format. An 136example filename is 'Microcode/C0_22211.BIN'. 137 138See README.x86 for information about x86 binary blobs. 139 140 141 142Entry: intel-descriptor: Intel flash descriptor block (4KB) 143----------------------------------------------------------- 144 145Properties / Entry arguments: 146 filename: Filename of file containing the descriptor. This is typically 147 a 4KB binary file, sometimes called 'descriptor.bin' 148 149This entry is placed at the start of flash and provides information about 150the SPI flash regions. In particular it provides the base address and 151size of the ME (Management Engine) region, allowing us to place the ME 152binary in the right place. 153 154With this entry in your image, the position of the 'intel-me' entry will be 155fixed in the image, which avoids you needed to specify an offset for that 156region. This is useful, because it is not possible to change the position 157of the ME region without updating the descriptor. 158 159See README.x86 for information about x86 binary blobs. 160 161 162 163Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file 164------------------------------------------------------------------------------- 165 166Properties / Entry arguments: 167 - filename: Filename of file to read into entry 168 169This file contains binary blobs which are used on some devices to make the 170platform work. U-Boot executes this code since it is not possible to set up 171the hardware using U-Boot open-source code. Documentation is typically not 172available in sufficient detail to allow this. 173 174An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 175 176See README.x86 for information about x86 binary blobs. 177 178 179 180Entry: intel-me: Entry containing an Intel Management Engine (ME) file 181---------------------------------------------------------------------- 182 183Properties / Entry arguments: 184 - filename: Filename of file to read into entry 185 186This file contains code used by the SoC that is required to make it work. 187The Management Engine is like a background task that runs things that are 188not clearly documented, but may include keyboard, deplay and network 189access. For platform that use ME it is not possible to disable it. U-Boot 190does not directly execute code in the ME binary. 191 192A typical filename is 'me.bin'. 193 194See README.x86 for information about x86 binary blobs. 195 196 197 198Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file 199---------------------------------------------------------------------------- 200 201Properties / Entry arguments: 202 - filename: Filename of file to read into entry 203 204This file contains code for setting up the SDRAM on some Intel systems. This 205is executed by U-Boot when needed early during startup. A typical filename 206is 'mrc.bin'. 207 208See README.x86 for information about x86 binary blobs. 209 210 211 212Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file 213----------------------------------------------------------------------- 214 215Properties / Entry arguments: 216 - filename: Filename of file to read into entry 217 218This file contains code that sets up the integrated graphics subsystem on 219some Intel SoCs. U-Boot executes this when the display is started up. 220 221See README.x86 for information about Intel binary blobs. 222 223 224 225Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file 226----------------------------------------------------------------------------- 227 228Properties / Entry arguments: 229 - filename: Filename of file to read into entry 230 231This file contains code that sets up the integrated graphics subsystem on 232some Intel SoCs. U-Boot executes this when the display is started up. 233 234This is similar to the VBT file but in a different format. 235 236See README.x86 for information about Intel binary blobs. 237 238 239 240Entry: section: Entry that contains other entries 241------------------------------------------------- 242 243Properties / Entry arguments: (see binman README for more information) 244 - size: Size of section in bytes 245 - align-size: Align size to a particular power of two 246 - pad-before: Add padding before the entry 247 - pad-after: Add padding after the entry 248 - pad-byte: Pad byte to use when padding 249 - sort-by-offset: Reorder the entries by offset 250 - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 251 - name-prefix: Adds a prefix to the name of every entry in the section 252 when writing out the map 253 254A section is an entry which can contain other entries, thus allowing 255hierarchical images to be created. See 'Sections and hierarchical images' 256in the binman README for more information. 257 258 259 260Entry: text: An entry which contains text 261----------------------------------------- 262 263The text can be provided either in the node itself or by a command-line 264argument. There is a level of indirection to allow multiple text strings 265and sharing of text. 266 267Properties / Entry arguments: 268 text-label: The value of this string indicates the property / entry-arg 269 that contains the string to place in the entry 270 <xxx> (actual name is the value of text-label): contains the string to 271 place in the entry. 272 273Example node: 274 275 text { 276 size = <50>; 277 text-label = "message"; 278 }; 279 280You can then use: 281 282 binman -amessage="this is my message" 283 284and binman will insert that string into the entry. 285 286It is also possible to put the string directly in the node: 287 288 text { 289 size = <8>; 290 text-label = "message"; 291 message = "a message directly in the node" 292 }; 293 294The text is not itself nul-terminated. This can be achieved, if required, 295by setting the size of the entry to something larger than the text. 296 297 298 299Entry: u-boot: U-Boot flat binary 300--------------------------------- 301 302Properties / Entry arguments: 303 - filename: Filename of u-boot.bin (default 'u-boot.bin') 304 305This is the U-Boot binary, containing relocation information to allow it 306to relocate itself at runtime. The binary typically includes a device tree 307blob at the end of it. Use u_boot_nodtb if you want to package the device 308tree separately. 309 310U-Boot can access binman symbols at runtime. See: 311 312 'Access to binman entry offsets at run time (fdt)' 313 314in the binman README for more information. 315 316 317 318Entry: u-boot-dtb: U-Boot device tree 319------------------------------------- 320 321Properties / Entry arguments: 322 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 323 324This is the U-Boot device tree, containing configuration information for 325U-Boot. U-Boot needs this to know what devices are present and which drivers 326to activate. 327 328Note: This is mostly an internal entry type, used by others. This allows 329binman to know which entries contain a device tree. 330 331 332 333Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 334----------------------------------------------------------------------------------- 335 336Properties / Entry arguments: 337 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 338 339See Entry_u_boot_ucode for full details of the three entries involved in 340this process. This entry provides the U-Boot device-tree file, which 341contains the microcode. If the microcode is not being collated into one 342place then the offset and size of the microcode is recorded by this entry, 343for use by u_boot_with_ucode_ptr. If it is being collated, then this 344entry deletes the microcode from the device tree (to save space) and makes 345it available to u_boot_ucode. 346 347 348 349Entry: u-boot-img: U-Boot legacy image 350-------------------------------------- 351 352Properties / Entry arguments: 353 - filename: Filename of u-boot.img (default 'u-boot.img') 354 355This is the U-Boot binary as a packaged image, in legacy format. It has a 356header which allows it to be loaded at the correct address for execution. 357 358You should use FIT (Flat Image Tree) instead of the legacy image for new 359applications. 360 361 362 363Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 364-------------------------------------------------------------------- 365 366Properties / Entry arguments: 367 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin') 368 369This is the U-Boot binary, containing relocation information to allow it 370to relocate itself at runtime. It does not include a device tree blob at 371the end of it so normally cannot work without it. You can add a u_boot_dtb 372entry after this one, or use a u_boot entry instead (which contains both 373U-Boot and the device tree). 374 375 376 377Entry: u-boot-spl: U-Boot SPL binary 378------------------------------------ 379 380Properties / Entry arguments: 381 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 382 383This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 384binary which loads before U-Boot proper, typically into on-chip SRAM. It is 385responsible for locating, loading and jumping to U-Boot. Note that SPL is 386not relocatable so must be loaded to the correct address in SRAM, or written 387to run from the correct address if direct flash execution is possible (e.g. 388on x86 devices). 389 390SPL can access binman symbols at runtime. See: 391 392 'Access to binman entry offsets at run time (symbols)' 393 394in the binman README for more information. 395 396The ELF file 'spl/u-boot-spl' must also be available for this to work, since 397binman uses that to look up symbols to write into the SPL binary. 398 399 400 401Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 402--------------------------------------------------------------------- 403 404Properties / Entry arguments: 405 None 406 407This is similar to u_boot_spl except that padding is added after the SPL 408binary to cover the BSS (Block Started by Symbol) region. This region holds 409the various used by SPL. It is set to 0 by SPL when it starts up. If you 410want to append data to the SPL image (such as a device tree file), you must 411pad out the BSS region to avoid the data overlapping with U-Boot variables. 412This entry is useful in that case. It automatically pads out the entry size 413to cover both the code, data and BSS. 414 415The ELF file 'spl/u-boot-spl' must also be available for this to work, since 416binman uses that to look up the BSS address. 417 418 419 420Entry: u-boot-spl-dtb: U-Boot SPL device tree 421--------------------------------------------- 422 423Properties / Entry arguments: 424 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 425 426This is the SPL device tree, containing configuration information for 427SPL. SPL needs this to know what devices are present and which drivers 428to activate. 429 430 431 432Entry: u-boot-spl-nodtb: SPL binary without device tree appended 433---------------------------------------------------------------- 434 435Properties / Entry arguments: 436 - filename: Filename of spl/u-boot-spl-nodtb.bin (default 437 'spl/u-boot-spl-nodtb.bin') 438 439This is the U-Boot SPL binary, It does not include a device tree blob at 440the end of it so may not be able to work without it, assuming SPL needs 441a device tree to operation on your platform. You can add a u_boot_spl_dtb 442entry after this one, or use a u_boot_spl entry instead (which contains 443both SPL and the device tree). 444 445 446 447Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 448---------------------------------------------------------------------------- 449 450See Entry_u_boot_ucode for full details of the entries involved in this 451process. 452 453 454 455Entry: u-boot-tpl: U-Boot TPL binary 456------------------------------------ 457 458Properties / Entry arguments: 459 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') 460 461This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small 462binary which loads before SPL, typically into on-chip SRAM. It is 463responsible for locating, loading and jumping to SPL, the next-stage 464loader. Note that SPL is not relocatable so must be loaded to the correct 465address in SRAM, or written to run from the correct address if direct 466flash execution is possible (e.g. on x86 devices). 467 468SPL can access binman symbols at runtime. See: 469 470 'Access to binman entry offsets at run time (symbols)' 471 472in the binman README for more information. 473 474The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 475binman uses that to look up symbols to write into the TPL binary. 476 477 478 479Entry: u-boot-tpl-dtb: U-Boot TPL device tree 480--------------------------------------------- 481 482Properties / Entry arguments: 483 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') 484 485This is the TPL device tree, containing configuration information for 486TPL. TPL needs this to know what devices are present and which drivers 487to activate. 488 489 490 491Entry: u-boot-ucode: U-Boot microcode block 492------------------------------------------- 493 494Properties / Entry arguments: 495 None 496 497The contents of this entry are filled in automatically by other entries 498which must also be in the image. 499 500U-Boot on x86 needs a single block of microcode. This is collected from 501the various microcode update nodes in the device tree. It is also unable 502to read the microcode from the device tree on platforms that use FSP 503(Firmware Support Package) binaries, because the API requires that the 504microcode is supplied before there is any SRAM available to use (i.e. 505the FSP sets up the SRAM / cache-as-RAM but does so in the call that 506requires the microcode!). To keep things simple, all x86 platforms handle 507microcode the same way in U-Boot (even non-FSP platforms). This is that 508a table is placed at _dt_ucode_base_size containing the base address and 509size of the microcode. This is either passed to the FSP (for FSP 510platforms), or used to set up the microcode (for non-FSP platforms). 511This all happens in the build system since it is the only way to get 512the microcode into a single blob and accessible without SRAM. 513 514There are two cases to handle. If there is only one microcode blob in 515the device tree, then the ucode pointer it set to point to that. This 516entry (u-boot-ucode) is empty. If there is more than one update, then 517this entry holds the concatenation of all updates, and the device tree 518entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 519last step ensures that that the microcode appears in one contiguous 520block in the image and is not unnecessarily duplicated in the device 521tree. It is referred to as 'collation' here. 522 523Entry types that have a part to play in handling microcode: 524 525 Entry_u_boot_with_ucode_ptr: 526 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 527 It updates it with the address and size of the microcode so that 528 U-Boot can find it early on start-up. 529 Entry_u_boot_dtb_with_ucode: 530 Contains u-boot.dtb. It stores the microcode in a 531 'self.ucode_data' property, which is then read by this class to 532 obtain the microcode if needed. If collation is performed, it 533 removes the microcode from the device tree. 534 Entry_u_boot_ucode: 535 This class. If collation is enabled it reads the microcode from 536 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 537 contents of this entry. 538 539 540 541Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 542-------------------------------------------------------------------- 543 544Properties / Entry arguments: 545 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 546 - optional-ucode: boolean property to make microcode optional. If the 547 u-boot.bin image does not include microcode, no error will 548 be generated. 549 550See Entry_u_boot_ucode for full details of the three entries involved in 551this process. This entry updates U-Boot with the offset and size of the 552microcode, to allow early x86 boot code to find it without doing anything 553complicated. Otherwise it is the same as the u_boot entry. 554 555 556 557Entry: vblock: An entry which contains a Chromium OS verified boot block 558------------------------------------------------------------------------ 559 560Properties / Entry arguments: 561 - keydir: Directory containing the public keys to use 562 - keyblock: Name of the key file to use (inside keydir) 563 - signprivate: Name of provide key file to use (inside keydir) 564 - version: Version number of the vblock (typically 1) 565 - kernelkey: Name of the kernel key to use (inside keydir) 566 - preamble-flags: Value of the vboot preamble flags (typically 0) 567 568Output files: 569 - input.<unique_name> - input file passed to futility 570 - vblock.<unique_name> - output file generated by futility (which is 571 used as the entry contents) 572 573Chromium OS signs the read-write firmware and kernel, writing the signature 574in this block. This allows U-Boot to verify that the next firmware stage 575and kernel are genuine. 576 577 578 579Entry: x86-start16: x86 16-bit start-up code for U-Boot 580------------------------------------------------------- 581 582Properties / Entry arguments: 583 - filename: Filename of u-boot-x86-16bit.bin (default 584 'u-boot-x86-16bit.bin') 585 586x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 587must be placed at a particular address. This entry holds that code. It is 588typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 589for changing to 32-bit mode and jumping to U-Boot's entry point, which 590requires 32-bit mode (for 32-bit U-Boot). 591 592For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 593 594 595 596Entry: x86-start16-spl: x86 16-bit start-up code for SPL 597-------------------------------------------------------- 598 599Properties / Entry arguments: 600 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 601 'spl/u-boot-x86-16bit-spl.bin') 602 603x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 604must be placed at a particular address. This entry holds that code. It is 605typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 606for changing to 32-bit mode and starting SPL, which in turn changes to 60764-bit mode and jumps to U-Boot (for 64-bit U-Boot). 608 609For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 610 611 612 613Entry: x86-start16-tpl: x86 16-bit start-up code for TPL 614-------------------------------------------------------- 615 616Properties / Entry arguments: 617 - filename: Filename of tpl/u-boot-x86-16bit-tpl.bin (default 618 'tpl/u-boot-x86-16bit-tpl.bin') 619 620x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 621must be placed at a particular address. This entry holds that code. It is 622typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 623for changing to 32-bit mode and starting TPL, which in turn jumps to SPL. 624 625If TPL is not being used, the 'x86_start16_spl or 'x86_start16' entry types 626may be used instead. 627 628 629 630