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 is 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-ucode: U-Boot microcode block 437------------------------------------------- 438 439Properties / Entry arguments: 440 None 441 442The contents of this entry are filled in automatically by other entries 443which must also be in the image. 444 445U-Boot on x86 needs a single block of microcode. This is collected from 446the various microcode update nodes in the device tree. It is also unable 447to read the microcode from the device tree on platforms that use FSP 448(Firmware Support Package) binaries, because the API requires that the 449microcode is supplied before there is any SRAM available to use (i.e. 450the FSP sets up the SRAM / cache-as-RAM but does so in the call that 451requires the microcode!). To keep things simple, all x86 platforms handle 452microcode the same way in U-Boot (even non-FSP platforms). This is that 453a table is placed at _dt_ucode_base_size containing the base address and 454size of the microcode. This is either passed to the FSP (for FSP 455platforms), or used to set up the microcode (for non-FSP platforms). 456This all happens in the build system since it is the only way to get 457the microcode into a single blob and accessible without SRAM. 458 459There are two cases to handle. If there is only one microcode blob in 460the device tree, then the ucode pointer it set to point to that. This 461entry (u-boot-ucode) is empty. If there is more than one update, then 462this entry holds the concatenation of all updates, and the device tree 463entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 464last step ensures that that the microcode appears in one contiguous 465block in the image and is not unnecessarily duplicated in the device 466tree. It is referred to as 'collation' here. 467 468Entry types that have a part to play in handling microcode: 469 470 Entry_u_boot_with_ucode_ptr: 471 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 472 It updates it with the address and size of the microcode so that 473 U-Boot can find it early on start-up. 474 Entry_u_boot_dtb_with_ucode: 475 Contains u-boot.dtb. It stores the microcode in a 476 'self.ucode_data' property, which is then read by this class to 477 obtain the microcode if needed. If collation is performed, it 478 removes the microcode from the device tree. 479 Entry_u_boot_ucode: 480 This class. If collation is enabled it reads the microcode from 481 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 482 contents of this entry. 483 484 485 486Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 487-------------------------------------------------------------------- 488 489Properties / Entry arguments: 490 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 491 492See Entry_u_boot_ucode for full details of the three entries involved in 493this process. This entry updates U-Boot with the offset and size of the 494microcode, to allow early x86 boot code to find it without doing anything 495complicated. Otherwise it is the same as the u_boot entry. 496 497 498 499Entry: vblock: An entry which contains a Chromium OS verified boot block 500------------------------------------------------------------------------ 501 502Properties / Entry arguments: 503 - keydir: Directory containing the public keys to use 504 - keyblock: Name of the key file to use (inside keydir) 505 - signprivate: Name of provide key file to use (inside keydir) 506 - version: Version number of the vblock (typically 1) 507 - kernelkey: Name of the kernel key to use (inside keydir) 508 - preamble-flags: Value of the vboot preamble flags (typically 0) 509 510Chromium OS signs the read-write firmware and kernel, writing the signature 511in this block. This allows U-Boot to verify that the next firmware stage 512and kernel are genuine. 513 514 515 516Entry: x86-start16: x86 16-bit start-up code for U-Boot 517------------------------------------------------------- 518 519Properties / Entry arguments: 520 - filename: Filename of u-boot-x86-16bit.bin (default 521 'u-boot-x86-16bit.bin') 522 523x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 524must be placed at a particular address. This entry holds that code. It is 525typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 526for changing to 32-bit mode and jumping to U-Boot's entry point, which 527requires 32-bit mode (for 32-bit U-Boot). 528 529For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 530 531 532 533Entry: x86-start16-spl: x86 16-bit start-up code for SPL 534-------------------------------------------------------- 535 536Properties / Entry arguments: 537 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 538 'spl/u-boot-x86-16bit-spl.bin') 539 540x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 541must be placed at a particular address. This entry holds that code. It is 542typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 543for changing to 32-bit mode and starting SPL, which in turn changes to 54464-bit mode and jumps to U-Boot (for 64-bit U-Boot). 545 546For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 547 548 549 550