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-dtb: A blob that holds a device tree 30------------------------------------------------ 31 32This is a blob containing a device tree. The contents of the blob are 33obtained from the list of available device-tree files, managed by the 34'state' module. 35 36 37 38Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 39----------------------------------------------------------------------------------------- 40 41Properties / Entry arguments: 42 - <xxx>-path: Filename containing the contents of this entry (optional, 43 defaults to 0) 44 45where <xxx> is the blob_fname argument to the constructor. 46 47This entry cannot be used directly. Instead, it is used as a parent class 48for another entry, which defined blob_fname. This parameter is used to 49set the entry-arg or property containing the filename. The entry-arg or 50property is in turn used to set the actual filename. 51 52See cros_ec_rw for an example of this. 53 54 55 56Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 57-------------------------------------------------------------------------------- 58 59Properties / Entry arguments: 60 - cros-ec-rw-path: Filename containing the EC image 61 62This entry holds a Chromium OS EC (embedded controller) image, for use in 63updating the EC on startup via software sync. 64 65 66 67Entry: fill: An entry which is filled to a particular byte value 68---------------------------------------------------------------- 69 70Properties / Entry arguments: 71 - fill-byte: Byte to use to fill the entry 72 73Note that the size property must be set since otherwise this entry does not 74know how large it should be. 75 76You can often achieve the same effect using the pad-byte property of the 77overall image, in that the space between entries will then be padded with 78that byte. But this entry is sometimes useful for explicitly setting the 79byte value of a region. 80 81 82 83Entry: fmap: An entry which contains an Fmap section 84---------------------------------------------------- 85 86Properties / Entry arguments: 87 None 88 89FMAP is a simple format used by flashrom, an open-source utility for 90reading and writing the SPI flash, typically on x86 CPUs. The format 91provides flashrom with a list of areas, so it knows what it in the flash. 92It can then read or write just a single area, instead of the whole flash. 93 94The format is defined by the flashrom project, in the file lib/fmap.h - 95see www.flashrom.org/Flashrom for more information. 96 97When used, this entry will be populated with an FMAP which reflects the 98entries in the current image. Note that any hierarchy is squashed, since 99FMAP does not support this. 100 101 102 103Entry: gbb: An entry which contains a Chromium OS Google Binary Block 104--------------------------------------------------------------------- 105 106Properties / Entry arguments: 107 - hardware-id: Hardware ID to use for this build (a string) 108 - keydir: Directory containing the public keys to use 109 - bmpblk: Filename containing images used by recovery 110 111Chromium OS uses a GBB to store various pieces of information, in particular 112the root and recovery keys that are used to verify the boot process. Some 113more details are here: 114 115 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts 116 117but note that the page dates from 2013 so is quite out of date. See 118README.chromium for how to obtain the required keys and tools. 119 120 121 122Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file 123------------------------------------------------------------------------- 124 125Properties / Entry arguments: 126 - filename: Filename of file to read into entry 127 128This file contains microcode for some devices in a special format. An 129example filename is 'Microcode/C0_22211.BIN'. 130 131See README.x86 for information about x86 binary blobs. 132 133 134 135Entry: intel-descriptor: Intel flash descriptor block (4KB) 136----------------------------------------------------------- 137 138Properties / Entry arguments: 139 filename: Filename of file containing the descriptor. This is typically 140 a 4KB binary file, sometimes called 'descriptor.bin' 141 142This entry is placed at the start of flash and provides information about 143the SPI flash regions. In particular it provides the base address and 144size of the ME (Management Engine) region, allowing us to place the ME 145binary in the right place. 146 147With this entry in your image, the position of the 'intel-me' entry will be 148fixed in the image, which avoids you needed to specify an offset for that 149region. This is useful, because it is not possible to change the position 150of the ME region without updating the descriptor. 151 152See README.x86 for information about x86 binary blobs. 153 154 155 156Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file 157------------------------------------------------------------------------------- 158 159Properties / Entry arguments: 160 - filename: Filename of file to read into entry 161 162This file contains binary blobs which are used on some devices to make the 163platform work. U-Boot executes this code since it is not possible to set up 164the hardware using U-Boot open-source code. Documentation is typically not 165available in sufficient detail to allow this. 166 167An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 168 169See README.x86 for information about x86 binary blobs. 170 171 172 173Entry: intel-me: Entry containing an Intel Management Engine (ME) file 174---------------------------------------------------------------------- 175 176Properties / Entry arguments: 177 - filename: Filename of file to read into entry 178 179This file contains code used by the SoC that is required to make it work. 180The Management Engine is like a background task that runs things that are 181not clearly documented, but may include keyboard, deplay and network 182access. For platform that use ME it is not possible to disable it. U-Boot 183does not directly execute code in the ME binary. 184 185A typical filename is 'me.bin'. 186 187See README.x86 for information about x86 binary blobs. 188 189 190 191Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file 192---------------------------------------------------------------------------- 193 194Properties / Entry arguments: 195 - filename: Filename of file to read into entry 196 197This file contains code for setting up the SDRAM on some Intel systems. This 198is executed by U-Boot when needed early during startup. A typical filename 199is 'mrc.bin'. 200 201See README.x86 for information about x86 binary blobs. 202 203 204 205Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file 206----------------------------------------------------------------------- 207 208Properties / Entry arguments: 209 - filename: Filename of file to read into entry 210 211This file contains code that sets up the integrated graphics subsystem on 212some Intel SoCs. U-Boot executes this when the display is started up. 213 214See README.x86 for information about Intel binary blobs. 215 216 217 218Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file 219----------------------------------------------------------------------------- 220 221Properties / Entry arguments: 222 - filename: Filename of file to read into entry 223 224This file contains code that sets up the integrated graphics subsystem on 225some Intel SoCs. U-Boot executes this when the display is started up. 226 227This is similar to the VBT file but in a different format. 228 229See README.x86 for information about Intel binary blobs. 230 231 232 233Entry: section: Entry that contains other entries 234------------------------------------------------- 235 236Properties / Entry arguments: (see binman README for more information) 237 - size: Size of section in bytes 238 - align-size: Align size to a particular power of two 239 - pad-before: Add padding before the entry 240 - pad-after: Add padding after the entry 241 - pad-byte: Pad byte to use when padding 242 - sort-by-offset: Reorder the entries by offset 243 - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 244 - name-prefix: Adds a prefix to the name of every entry in the section 245 when writing out the map 246 247A section is an entry which can contain other entries, thus allowing 248hierarchical images to be created. See 'Sections and hierarchical images' 249in the binman README for more information. 250 251 252 253Entry: text: An entry which contains text 254----------------------------------------- 255 256The text can be provided either in the node itself or by a command-line 257argument. There is a level of indirection to allow multiple text strings 258and sharing of text. 259 260Properties / Entry arguments: 261 text-label: The value of this string indicates the property / entry-arg 262 that contains the string to place in the entry 263 <xxx> (actual name is the value of text-label): contains the string to 264 place in the entry. 265 266Example node: 267 268 text { 269 size = <50>; 270 text-label = "message"; 271 }; 272 273You can then use: 274 275 binman -amessage="this is my message" 276 277and binman will insert that string into the entry. 278 279It is also possible to put the string directly in the node: 280 281 text { 282 size = <8>; 283 text-label = "message"; 284 message = "a message directly in the node" 285 }; 286 287The text is not itself nul-terminated. This can be achieved, if required, 288by setting the size of the entry to something larger than the text. 289 290 291 292Entry: u-boot: U-Boot flat binary 293--------------------------------- 294 295Properties / Entry arguments: 296 - filename: Filename of u-boot.bin (default 'u-boot.bin') 297 298This is the U-Boot binary, containing relocation information to allow it 299to relocate itself at runtime. The binary typically includes a device tree 300blob at the end of it. Use u_boot_nodtb if you want to package the device 301tree separately. 302 303U-Boot can access binman symbols at runtime. See: 304 305 'Access to binman entry offsets at run time (fdt)' 306 307in the binman README for more information. 308 309 310 311Entry: u-boot-dtb: U-Boot device tree 312------------------------------------- 313 314Properties / Entry arguments: 315 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 316 317This is the U-Boot device tree, containing configuration information for 318U-Boot. U-Boot needs this to know what devices are present and which drivers 319to activate. 320 321Note: This is mostly an internal entry type, used by others. This allows 322binman to know which entries contain a device tree. 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 - optional-ucode: boolean property to make microcode optional. If the 540 u-boot.bin image does not include microcode, no error will 541 be generated. 542 543See Entry_u_boot_ucode for full details of the three entries involved in 544this process. This entry updates U-Boot with the offset and size of the 545microcode, to allow early x86 boot code to find it without doing anything 546complicated. Otherwise it is the same as the u_boot entry. 547 548 549 550Entry: vblock: An entry which contains a Chromium OS verified boot block 551------------------------------------------------------------------------ 552 553Properties / Entry arguments: 554 - keydir: Directory containing the public keys to use 555 - keyblock: Name of the key file to use (inside keydir) 556 - signprivate: Name of provide key file to use (inside keydir) 557 - version: Version number of the vblock (typically 1) 558 - kernelkey: Name of the kernel key to use (inside keydir) 559 - preamble-flags: Value of the vboot preamble flags (typically 0) 560 561Output files: 562 - input.<unique_name> - input file passed to futility 563 - vblock.<unique_name> - output file generated by futility (which is 564 used as the entry contents) 565 566Chromium OS signs the read-write firmware and kernel, writing the signature 567in this block. This allows U-Boot to verify that the next firmware stage 568and kernel are genuine. 569 570 571 572Entry: x86-start16: x86 16-bit start-up code for U-Boot 573------------------------------------------------------- 574 575Properties / Entry arguments: 576 - filename: Filename of u-boot-x86-16bit.bin (default 577 'u-boot-x86-16bit.bin') 578 579x86 CPUs start up in 16-bit mode, even if they are 32-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 jumping to U-Boot's entry point, which 583requires 32-bit mode (for 32-bit U-Boot). 584 585For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 586 587 588 589Entry: x86-start16-spl: x86 16-bit start-up code for SPL 590-------------------------------------------------------- 591 592Properties / Entry arguments: 593 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 594 'spl/u-boot-x86-16bit-spl.bin') 595 596x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 597must be placed at a particular address. This entry holds that code. It is 598typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 599for changing to 32-bit mode and starting SPL, which in turn changes to 60064-bit mode and jumps to U-Boot (for 64-bit U-Boot). 601 602For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 603 604 605 606Entry: x86-start16-tpl: x86 16-bit start-up code for TPL 607-------------------------------------------------------- 608 609Properties / Entry arguments: 610 - filename: Filename of tpl/u-boot-x86-16bit-tpl.bin (default 611 'tpl/u-boot-x86-16bit-tpl.bin') 612 613x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 614must be placed at a particular address. This entry holds that code. It is 615typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 616for changing to 32-bit mode and starting TPL, which in turn jumps to SPL. 617 618If TPL is not being used, the 'x86_start16_spl or 'x86_start16' entry types 619may be used instead. 620 621 622 623