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