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: section: Entry that contains other entries 225------------------------------------------------- 226 227Properties / Entry arguments: (see binman README for more information) 228 - size: Size of section in bytes 229 - align-size: Align size to a particular power of two 230 - pad-before: Add padding before the entry 231 - pad-after: Add padding after the entry 232 - pad-byte: Pad byte to use when padding 233 - sort-by-offset: Reorder the entries by offset 234 - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 235 - name-prefix: Adds a prefix to the name of every entry in the section 236 when writing out the map 237 238A section is an entry which can contain other entries, thus allowing 239hierarchical images to be created. See 'Sections and hierarchical images' 240in the binman README for more information. 241 242 243 244Entry: text: An entry which contains text 245----------------------------------------- 246 247The text can be provided either in the node itself or by a command-line 248argument. There is a level of indirection to allow multiple text strings 249and sharing of text. 250 251Properties / Entry arguments: 252 text-label: The value of this string indicates the property / entry-arg 253 that contains the string to place in the entry 254 <xxx> (actual name is the value of text-label): contains the string to 255 place in the entry. 256 257Example node: 258 259 text { 260 size = <50>; 261 text-label = "message"; 262 }; 263 264You can then use: 265 266 binman -amessage="this is my message" 267 268and binman will insert that string into the entry. 269 270It is also possible to put the string directly in the node: 271 272 text { 273 size = <8>; 274 text-label = "message"; 275 message = "a message directly in the node" 276 }; 277 278The text is not itself nul-terminated. This can be achieved, if required, 279by setting the size of the entry to something larger than the text. 280 281 282 283Entry: u-boot: U-Boot flat binary 284--------------------------------- 285 286Properties / Entry arguments: 287 - filename: Filename of u-boot.bin (default 'u-boot.bin') 288 289This is the U-Boot binary, containing relocation information to allow it 290to relocate itself at runtime. The binary typically includes a device tree 291blob at the end of it. Use u_boot_nodtb if you want to package the device 292tree separately. 293 294U-Boot can access binman symbols at runtime. See: 295 296 'Access to binman entry offsets at run time (fdt)' 297 298in the binman README for more information. 299 300 301 302Entry: u-boot-dtb: U-Boot device tree 303------------------------------------- 304 305Properties / Entry arguments: 306 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 307 308This is the U-Boot device tree, containing configuration information for 309U-Boot. U-Boot needs this to know what devices are present and which drivers 310to activate. 311 312 313 314Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 315----------------------------------------------------------------------------------- 316 317Properties / Entry arguments: 318 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 319 320See Entry_u_boot_ucode for full details of the three entries involved in 321this process. This entry provides the U-Boot device-tree file, which 322contains the microcode. If the microcode is not being collated into one 323place then the offset and size of the microcode is recorded by this entry, 324for use by u_boot_with_ucode_ptr. If it is being collated, then this 325entry deletes the microcode from the device tree (to save space) and makes 326it available to u_boot_ucode. 327 328 329 330Entry: u-boot-img: U-Boot legacy image 331-------------------------------------- 332 333Properties / Entry arguments: 334 - filename: Filename of u-boot.img (default 'u-boot.img') 335 336This is the U-Boot binary as a packaged image, in legacy format. It has a 337header which allows it to be loaded at the correct address for execution. 338 339You should use FIT (Flat Image Tree) instead of the legacy image for new 340applications. 341 342 343 344Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 345-------------------------------------------------------------------- 346 347Properties / Entry arguments: 348 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin') 349 350This is the U-Boot binary, containing relocation information to allow it 351to relocate itself at runtime. It does not include a device tree blob at 352the end of it so normally cannot work without it. You can add a u_boot_dtb 353entry after this one, or use a u_boot entry instead (which contains both 354U-Boot and the device tree). 355 356 357 358Entry: u-boot-spl: U-Boot SPL binary 359------------------------------------ 360 361Properties / Entry arguments: 362 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 363 364This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 365binary which loads before U-Boot proper, typically into on-chip SRAM. It is 366responsible for locating, loading and jumping to U-Boot. Note that SPL is 367not relocatable so must be loaded to the correct address in SRAM, or written 368to run from the correct address if direct flash execution is possible (e.g. 369on x86 devices). 370 371SPL can access binman symbols at runtime. See: 372 373 'Access to binman entry offsets at run time (symbols)' 374 375in the binman README for more information. 376 377The ELF file 'spl/u-boot-spl' must also be available for this to work, since 378binman uses that to look up symbols to write into the SPL binary. 379 380 381 382Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 383--------------------------------------------------------------------- 384 385Properties / Entry arguments: 386 None 387 388This is similar to u_boot_spl except that padding is added after the SPL 389binary to cover the BSS (Block Started by Symbol) region. This region holds 390the various used by SPL. It is set to 0 by SPL when it starts up. If you 391want to append data to the SPL image (such as a device tree file), you must 392pad out the BSS region to avoid the data overlapping with U-Boot variables. 393This entry is useful in that case. It automatically pads out the entry size 394to cover both the code, data and BSS. 395 396The ELF file 'spl/u-boot-spl' must also be available for this to work, since 397binman uses that to look up the BSS address. 398 399 400 401Entry: u-boot-spl-dtb: U-Boot SPL device tree 402--------------------------------------------- 403 404Properties / Entry arguments: 405 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 406 407This is the SPL device tree, containing configuration information for 408SPL. SPL needs this to know what devices are present and which drivers 409to activate. 410 411 412 413Entry: u-boot-spl-nodtb: SPL binary without device tree appended 414---------------------------------------------------------------- 415 416Properties / Entry arguments: 417 - filename: Filename of spl/u-boot-spl-nodtb.bin (default 418 'spl/u-boot-spl-nodtb.bin') 419 420This is the U-Boot SPL binary, It does not include a device tree blob at 421the end of it so may not be able to work without it, assuming SPL needs 422a device tree to operation on your platform. You can add a u_boot_spl_dtb 423entry after this one, or use a u_boot_spl entry instead (which contains 424both SPL and the device tree). 425 426 427 428Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 429---------------------------------------------------------------------------- 430 431See Entry_u_boot_ucode for full details of the entries involved in this 432process. 433 434 435 436Entry: u-boot-tpl: U-Boot TPL binary 437------------------------------------ 438 439Properties / Entry arguments: 440 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') 441 442This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small 443binary which loads before SPL, typically into on-chip SRAM. It is 444responsible for locating, loading and jumping to SPL, the next-stage 445loader. Note that SPL is not relocatable so must be loaded to the correct 446address in SRAM, or written to run from the correct address if direct 447flash execution is possible (e.g. on x86 devices). 448 449SPL can access binman symbols at runtime. See: 450 451 'Access to binman entry offsets at run time (symbols)' 452 453in the binman README for more information. 454 455The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 456binman uses that to look up symbols to write into the TPL binary. 457 458 459 460Entry: u-boot-tpl-dtb: U-Boot TPL device tree 461--------------------------------------------- 462 463Properties / Entry arguments: 464 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') 465 466This is the TPL device tree, containing configuration information for 467TPL. TPL needs this to know what devices are present and which drivers 468to activate. 469 470 471 472Entry: u-boot-ucode: U-Boot microcode block 473------------------------------------------- 474 475Properties / Entry arguments: 476 None 477 478The contents of this entry are filled in automatically by other entries 479which must also be in the image. 480 481U-Boot on x86 needs a single block of microcode. This is collected from 482the various microcode update nodes in the device tree. It is also unable 483to read the microcode from the device tree on platforms that use FSP 484(Firmware Support Package) binaries, because the API requires that the 485microcode is supplied before there is any SRAM available to use (i.e. 486the FSP sets up the SRAM / cache-as-RAM but does so in the call that 487requires the microcode!). To keep things simple, all x86 platforms handle 488microcode the same way in U-Boot (even non-FSP platforms). This is that 489a table is placed at _dt_ucode_base_size containing the base address and 490size of the microcode. This is either passed to the FSP (for FSP 491platforms), or used to set up the microcode (for non-FSP platforms). 492This all happens in the build system since it is the only way to get 493the microcode into a single blob and accessible without SRAM. 494 495There are two cases to handle. If there is only one microcode blob in 496the device tree, then the ucode pointer it set to point to that. This 497entry (u-boot-ucode) is empty. If there is more than one update, then 498this entry holds the concatenation of all updates, and the device tree 499entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 500last step ensures that that the microcode appears in one contiguous 501block in the image and is not unnecessarily duplicated in the device 502tree. It is referred to as 'collation' here. 503 504Entry types that have a part to play in handling microcode: 505 506 Entry_u_boot_with_ucode_ptr: 507 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 508 It updates it with the address and size of the microcode so that 509 U-Boot can find it early on start-up. 510 Entry_u_boot_dtb_with_ucode: 511 Contains u-boot.dtb. It stores the microcode in a 512 'self.ucode_data' property, which is then read by this class to 513 obtain the microcode if needed. If collation is performed, it 514 removes the microcode from the device tree. 515 Entry_u_boot_ucode: 516 This class. If collation is enabled it reads the microcode from 517 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 518 contents of this entry. 519 520 521 522Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 523-------------------------------------------------------------------- 524 525Properties / Entry arguments: 526 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 527 - optional-ucode: boolean property to make microcode optional. If the 528 u-boot.bin image does not include microcode, no error will 529 be generated. 530 531See Entry_u_boot_ucode for full details of the three entries involved in 532this process. This entry updates U-Boot with the offset and size of the 533microcode, to allow early x86 boot code to find it without doing anything 534complicated. Otherwise it is the same as the u_boot entry. 535 536 537 538Entry: vblock: An entry which contains a Chromium OS verified boot block 539------------------------------------------------------------------------ 540 541Properties / Entry arguments: 542 - keydir: Directory containing the public keys to use 543 - keyblock: Name of the key file to use (inside keydir) 544 - signprivate: Name of provide key file to use (inside keydir) 545 - version: Version number of the vblock (typically 1) 546 - kernelkey: Name of the kernel key to use (inside keydir) 547 - preamble-flags: Value of the vboot preamble flags (typically 0) 548 549Chromium OS signs the read-write firmware and kernel, writing the signature 550in this block. This allows U-Boot to verify that the next firmware stage 551and kernel are genuine. 552 553 554 555Entry: x86-start16: x86 16-bit start-up code for U-Boot 556------------------------------------------------------- 557 558Properties / Entry arguments: 559 - filename: Filename of u-boot-x86-16bit.bin (default 560 'u-boot-x86-16bit.bin') 561 562x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 563must be placed at a particular address. This entry holds that code. It is 564typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 565for changing to 32-bit mode and jumping to U-Boot's entry point, which 566requires 32-bit mode (for 32-bit U-Boot). 567 568For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 569 570 571 572Entry: x86-start16-spl: x86 16-bit start-up code for SPL 573-------------------------------------------------------- 574 575Properties / Entry arguments: 576 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 577 'spl/u-boot-x86-16bit-spl.bin') 578 579x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 580must be placed at a particular address. This entry holds that code. It is 581typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 582for changing to 32-bit mode and starting SPL, which in turn changes to 58364-bit mode and jumps to U-Boot (for 64-bit U-Boot). 584 585For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 586 587 588 589