1Binman Entry Documentation 2=========================== 3 4This file describes the entry types supported by binman. These entry types can 5be placed in an image one by one to build up a final firmware image. It is 6fairly easy to create new entry types. Just add a new file to the 'etype' 7directory. You can use the existing entries as examples. 8 9Note that some entries are subclasses of others, using and extending their 10features to produce new behaviours. 11 12 13 14Entry: blob: Entry containing an arbitrary binary blob 15------------------------------------------------------ 16 17Note: This should not be used by itself. It is normally used as a parent 18class by other entry types. 19 20Properties / Entry arguments: 21 - filename: Filename of file to read into entry 22 - compress: Compression algorithm to use: 23 none: No compression 24 lz4: Use lz4 compression (via 'lz4' command-line utility) 25 26This entry reads data from a file and places it in the entry. The 27default filename is often specified specified by the subclass. See for 28example the 'u_boot' entry which provides the filename 'u-boot.bin'. 29 30If compression is enabled, an extra 'uncomp-size' property is written to 31the node (if enabled with -u) which provides the uncompressed size of the 32data. 33 34 35 36Entry: blob-dtb: A blob that holds a device tree 37------------------------------------------------ 38 39This is a blob containing a device tree. The contents of the blob are 40obtained from the list of available device-tree files, managed by the 41'state' module. 42 43 44 45Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 46----------------------------------------------------------------------------------------- 47 48Properties / Entry arguments: 49 - <xxx>-path: Filename containing the contents of this entry (optional, 50 defaults to 0) 51 52where <xxx> is the blob_fname argument to the constructor. 53 54This entry cannot be used directly. Instead, it is used as a parent class 55for another entry, which defined blob_fname. This parameter is used to 56set the entry-arg or property containing the filename. The entry-arg or 57property is in turn used to set the actual filename. 58 59See cros_ec_rw for an example of this. 60 61 62 63Entry: cbfs: Entry containing a Coreboot Filesystem (CBFS) 64---------------------------------------------------------- 65 66A CBFS provides a way to group files into a group. It has a simple directory 67structure and allows the position of individual files to be set, since it is 68designed to support execute-in-place in an x86 SPI-flash device. Where XIP 69is not used, it supports compression and storing ELF files. 70 71CBFS is used by coreboot as its way of orgnanising SPI-flash contents. 72 73The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.: 74 75 cbfs { 76 size = <0x100000>; 77 u-boot { 78 cbfs-type = "raw"; 79 }; 80 u-boot-dtb { 81 cbfs-type = "raw"; 82 }; 83 }; 84 85This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb. 86Note that the size is required since binman does not support calculating it. 87The contents of each entry is just what binman would normally provide if it 88were not a CBFS node. A blob type can be used to import arbitrary files as 89with the second subnode below: 90 91 cbfs { 92 size = <0x100000>; 93 u-boot { 94 cbfs-name = "BOOT"; 95 cbfs-type = "raw"; 96 }; 97 98 dtb { 99 type = "blob"; 100 filename = "u-boot.dtb"; 101 cbfs-type = "raw"; 102 cbfs-compress = "lz4"; 103 cbfs-offset = <0x100000>; 104 }; 105 }; 106 107This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and 108u-boot.dtb (named "dtb") and compressed with the lz4 algorithm. 109 110 111Properties supported in the top-level CBFS node: 112 113cbfs-arch: 114 Defaults to "x86", but you can specify the architecture if needed. 115 116 117Properties supported in the CBFS entry subnodes: 118 119cbfs-name: 120 This is the name of the file created in CBFS. It defaults to the entry 121 name (which is the node name), but you can override it with this 122 property. 123 124cbfs-type: 125 This is the CBFS file type. The following are supported: 126 127 raw: 128 This is a 'raw' file, although compression is supported. It can be 129 used to store any file in CBFS. 130 131 stage: 132 This is an ELF file that has been loaded (i.e. mapped to memory), so 133 appears in the CBFS as a flat binary. The input file must be an ELF 134 image, for example this puts "u-boot" (the ELF image) into a 'stage' 135 entry: 136 137 cbfs { 138 size = <0x100000>; 139 u-boot-elf { 140 cbfs-name = "BOOT"; 141 cbfs-type = "stage"; 142 }; 143 }; 144 145 You can use your own ELF file with something like: 146 147 cbfs { 148 size = <0x100000>; 149 something { 150 type = "blob"; 151 filename = "cbfs-stage.elf"; 152 cbfs-type = "stage"; 153 }; 154 }; 155 156 As mentioned, the file is converted to a flat binary, so it is 157 equivalent to adding "u-boot.bin", for example, but with the load and 158 start addresses specified by the ELF. At present there is no option 159 to add a flat binary with a load/start address, similar to the 160 'add-flat-binary' option in cbfstool. 161 162cbfs-offset: 163 This is the offset of the file's data within the CBFS. It is used to 164 specify where the file should be placed in cases where a fixed position 165 is needed. Typical uses are for code which is not relocatable and must 166 execute in-place from a particular address. This works because SPI flash 167 is generally mapped into memory on x86 devices. The file header is 168 placed before this offset so that the data start lines up exactly with 169 the chosen offset. If this property is not provided, then the file is 170 placed in the next available spot. 171 172The current implementation supports only a subset of CBFS features. It does 173not support other file types (e.g. payload), adding multiple files (like the 174'files' entry with a pattern supported by binman), putting files at a 175particular offset in the CBFS and a few other things. 176 177Of course binman can create images containing multiple CBFSs, simply by 178defining these in the binman config: 179 180 181 binman { 182 size = <0x800000>; 183 cbfs { 184 offset = <0x100000>; 185 size = <0x100000>; 186 u-boot { 187 cbfs-type = "raw"; 188 }; 189 u-boot-dtb { 190 cbfs-type = "raw"; 191 }; 192 }; 193 194 cbfs2 { 195 offset = <0x700000>; 196 size = <0x100000>; 197 u-boot { 198 cbfs-type = "raw"; 199 }; 200 u-boot-dtb { 201 cbfs-type = "raw"; 202 }; 203 image { 204 type = "blob"; 205 filename = "image.jpg"; 206 }; 207 }; 208 }; 209 210This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB, 211both of size 1MB. 212 213 214 215Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 216-------------------------------------------------------------------------------- 217 218Properties / Entry arguments: 219 - cros-ec-rw-path: Filename containing the EC image 220 221This entry holds a Chromium OS EC (embedded controller) image, for use in 222updating the EC on startup via software sync. 223 224 225 226Entry: fdtmap: An entry which contains an FDT map 227------------------------------------------------- 228 229Properties / Entry arguments: 230 None 231 232An FDT map is just a header followed by an FDT containing a list of all the 233entries in the image. The root node corresponds to the image node in the 234original FDT, and an image-name property indicates the image name in that 235original tree. 236 237The header is the string _FDTMAP_ followed by 8 unused bytes. 238 239When used, this entry will be populated with an FDT map which reflects the 240entries in the current image. Hierarchy is preserved, and all offsets and 241sizes are included. 242 243Note that the -u option must be provided to ensure that binman updates the 244FDT with the position of each entry. 245 246Example output for a simple image with U-Boot and an FDT map: 247 248/ { 249 image-name = "binman"; 250 size = <0x00000112>; 251 image-pos = <0x00000000>; 252 offset = <0x00000000>; 253 u-boot { 254 size = <0x00000004>; 255 image-pos = <0x00000000>; 256 offset = <0x00000000>; 257 }; 258 fdtmap { 259 size = <0x0000010e>; 260 image-pos = <0x00000004>; 261 offset = <0x00000004>; 262 }; 263}; 264 265If allow-repack is used then 'orig-offset' and 'orig-size' properties are 266added as necessary. See the binman README. 267 268 269 270Entry: files: Entry containing a set of files 271--------------------------------------------- 272 273Properties / Entry arguments: 274 - pattern: Filename pattern to match the files to include 275 - compress: Compression algorithm to use: 276 none: No compression 277 lz4: Use lz4 compression (via 'lz4' command-line utility) 278 279This entry reads a number of files and places each in a separate sub-entry 280within this entry. To access these you need to enable device-tree updates 281at run-time so you can obtain the file positions. 282 283 284 285Entry: fill: An entry which is filled to a particular byte value 286---------------------------------------------------------------- 287 288Properties / Entry arguments: 289 - fill-byte: Byte to use to fill the entry 290 291Note that the size property must be set since otherwise this entry does not 292know how large it should be. 293 294You can often achieve the same effect using the pad-byte property of the 295overall image, in that the space between entries will then be padded with 296that byte. But this entry is sometimes useful for explicitly setting the 297byte value of a region. 298 299 300 301Entry: fmap: An entry which contains an Fmap section 302---------------------------------------------------- 303 304Properties / Entry arguments: 305 None 306 307FMAP is a simple format used by flashrom, an open-source utility for 308reading and writing the SPI flash, typically on x86 CPUs. The format 309provides flashrom with a list of areas, so it knows what it in the flash. 310It can then read or write just a single area, instead of the whole flash. 311 312The format is defined by the flashrom project, in the file lib/fmap.h - 313see www.flashrom.org/Flashrom for more information. 314 315When used, this entry will be populated with an FMAP which reflects the 316entries in the current image. Note that any hierarchy is squashed, since 317FMAP does not support this. Also, CBFS entries appear as a single entry - 318the sub-entries are ignored. 319 320 321 322Entry: gbb: An entry which contains a Chromium OS Google Binary Block 323--------------------------------------------------------------------- 324 325Properties / Entry arguments: 326 - hardware-id: Hardware ID to use for this build (a string) 327 - keydir: Directory containing the public keys to use 328 - bmpblk: Filename containing images used by recovery 329 330Chromium OS uses a GBB to store various pieces of information, in particular 331the root and recovery keys that are used to verify the boot process. Some 332more details are here: 333 334 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts 335 336but note that the page dates from 2013 so is quite out of date. See 337README.chromium for how to obtain the required keys and tools. 338 339 340 341Entry: image-header: An entry which contains a pointer to the FDT map 342--------------------------------------------------------------------- 343 344Properties / Entry arguments: 345 location: Location of header ("start" or "end" of image). This is 346 optional. If omitted then the entry must have an offset property. 347 348This adds an 8-byte entry to the start or end of the image, pointing to the 349location of the FDT map. The format is a magic number followed by an offset 350from the start or end of the image, in twos-compliment format. 351 352This entry must be in the top-level part of the image. 353 354NOTE: If the location is at the start/end, you will probably need to specify 355sort-by-offset for the image, unless you actually put the image header 356first/last in the entry list. 357 358 359 360Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file 361------------------------------------------------------------------------- 362 363Properties / Entry arguments: 364 - filename: Filename of file to read into entry 365 366This file contains microcode for some devices in a special format. An 367example filename is 'Microcode/C0_22211.BIN'. 368 369See README.x86 for information about x86 binary blobs. 370 371 372 373Entry: intel-descriptor: Intel flash descriptor block (4KB) 374----------------------------------------------------------- 375 376Properties / Entry arguments: 377 filename: Filename of file containing the descriptor. This is typically 378 a 4KB binary file, sometimes called 'descriptor.bin' 379 380This entry is placed at the start of flash and provides information about 381the SPI flash regions. In particular it provides the base address and 382size of the ME (Management Engine) region, allowing us to place the ME 383binary in the right place. 384 385With this entry in your image, the position of the 'intel-me' entry will be 386fixed in the image, which avoids you needed to specify an offset for that 387region. This is useful, because it is not possible to change the position 388of the ME region without updating the descriptor. 389 390See README.x86 for information about x86 binary blobs. 391 392 393 394Entry: intel-fit: Intel Firmware Image Table (FIT) 395-------------------------------------------------- 396 397This entry contains a dummy FIT as required by recent Intel CPUs. The FIT 398contains information about the firmware and microcode available in the 399image. 400 401At present binman only supports a basic FIT with no microcode. 402 403 404 405Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer 406-------------------------------------------------------------- 407 408This entry contains a pointer to the FIT. It is required to be at address 4090xffffffc0 in the image. 410 411 412 413Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file 414------------------------------------------------------------------------------- 415 416Properties / Entry arguments: 417 - filename: Filename of file to read into entry 418 419This file contains binary blobs which are used on some devices to make the 420platform work. U-Boot executes this code since it is not possible to set up 421the hardware using U-Boot open-source code. Documentation is typically not 422available in sufficient detail to allow this. 423 424An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 425 426See README.x86 for information about x86 binary blobs. 427 428 429 430Entry: intel-fsp-m: Entry containing Intel Firmware Support Package (FSP) memory init 431------------------------------------------------------------------------------------- 432 433Properties / Entry arguments: 434 - filename: Filename of file to read into entry 435 436This file contains a binary blob which is used on some devices to set up 437SDRAM. U-Boot executes this code in SPL so that it can make full use of 438memory. Documentation is typically not available in sufficient detail to 439allow U-Boot do this this itself.. 440 441An example filename is 'fsp_m.bin' 442 443See README.x86 for information about x86 binary blobs. 444 445 446 447Entry: intel-fsp-s: Entry containing Intel Firmware Support Package (FSP) silicon init 448-------------------------------------------------------------------------------------- 449 450Properties / Entry arguments: 451 - filename: Filename of file to read into entry 452 453This file contains a binary blob which is used on some devices to set up 454the silicon. U-Boot executes this code in U-Boot proper after SDRAM is 455running, so that it can make full use of memory. Documentation is typically 456not available in sufficient detail to allow U-Boot do this this itself. 457 458An example filename is 'fsp_s.bin' 459 460See README.x86 for information about x86 binary blobs. 461 462 463 464Entry: intel-fsp-t: Entry containing Intel Firmware Support Package (FSP) temp ram init 465--------------------------------------------------------------------------------------- 466 467Properties / Entry arguments: 468 - filename: Filename of file to read into entry 469 470This file contains a binary blob which is used on some devices to set up 471temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so 472that it has access to memory for its stack and initial storage. 473 474An example filename is 'fsp_t.bin' 475 476See README.x86 for information about x86 binary blobs. 477 478 479 480Entry: intel-ifwi: Entry containing an Intel Integrated Firmware Image (IFWI) file 481---------------------------------------------------------------------------------- 482 483Properties / Entry arguments: 484 - filename: Filename of file to read into entry. This is either the 485 IFWI file itself, or a file that can be converted into one using a 486 tool 487 - convert-fit: If present this indicates that the ifwitool should be 488 used to convert the provided file into a IFWI. 489 490This file contains code and data used by the SoC that is required to make 491it work. It includes U-Boot TPL, microcode, things related to the CSE 492(Converged Security Engine, the microcontroller that loads all the firmware) 493and other items beyond the wit of man. 494 495A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a 496file that will be converted to an IFWI. 497 498The position of this entry is generally set by the intel-descriptor entry. 499 500The contents of the IFWI are specified by the subnodes of the IFWI node. 501Each subnode describes an entry which is placed into the IFWFI with a given 502sub-partition (and optional entry name). 503 504Properties for subnodes: 505 ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP" 506 ifwi-entry - entry name t use, e.g. "IBBL" 507 ifwi-replace - if present, indicates that the item should be replaced 508 in the IFWI. Otherwise it is added. 509 510See README.x86 for information about x86 binary blobs. 511 512 513 514Entry: intel-me: Entry containing an Intel Management Engine (ME) file 515---------------------------------------------------------------------- 516 517Properties / Entry arguments: 518 - filename: Filename of file to read into entry 519 520This file contains code used by the SoC that is required to make it work. 521The Management Engine is like a background task that runs things that are 522not clearly documented, but may include keyboard, display and network 523access. For platform that use ME it is not possible to disable it. U-Boot 524does not directly execute code in the ME binary. 525 526A typical filename is 'me.bin'. 527 528The position of this entry is generally set by the intel-descriptor entry. 529 530See README.x86 for information about x86 binary blobs. 531 532 533 534Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file 535---------------------------------------------------------------------------- 536 537Properties / Entry arguments: 538 - filename: Filename of file to read into entry 539 540This file contains code for setting up the SDRAM on some Intel systems. This 541is executed by U-Boot when needed early during startup. A typical filename 542is 'mrc.bin'. 543 544See README.x86 for information about x86 binary blobs. 545 546 547 548Entry: intel-refcode: Entry containing an Intel Reference Code file 549------------------------------------------------------------------- 550 551Properties / Entry arguments: 552 - filename: Filename of file to read into entry 553 554This file contains code for setting up the platform on some Intel systems. 555This is executed by U-Boot when needed early during startup. A typical 556filename is 'refcode.bin'. 557 558See README.x86 for information about x86 binary blobs. 559 560 561 562Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file 563----------------------------------------------------------------------- 564 565Properties / Entry arguments: 566 - filename: Filename of file to read into entry 567 568This file contains code that sets up the integrated graphics subsystem on 569some Intel SoCs. U-Boot executes this when the display is started up. 570 571See README.x86 for information about Intel binary blobs. 572 573 574 575Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file 576----------------------------------------------------------------------------- 577 578Properties / Entry arguments: 579 - filename: Filename of file to read into entry 580 581This file contains code that sets up the integrated graphics subsystem on 582some Intel SoCs. U-Boot executes this when the display is started up. 583 584This is similar to the VBT file but in a different format. 585 586See README.x86 for information about Intel binary blobs. 587 588 589 590Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot 591----------------------------------------------------------------------------------------- 592 593Properties / Entry arguments: 594 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin') 595 596This entry is valid for PowerPC mpc85xx cpus. This entry holds 597'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be 598placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'. 599 600 601 602Entry: section: Entry that contains other entries 603------------------------------------------------- 604 605Properties / Entry arguments: (see binman README for more information) 606 pad-byte: Pad byte to use when padding 607 sort-by-offset: True if entries should be sorted by offset, False if 608 they must be in-order in the device tree description 609 end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 610 skip-at-start: Number of bytes before the first entry starts. These 611 effectively adjust the starting offset of entries. For example, 612 if this is 16, then the first entry would start at 16. An entry 613 with offset = 20 would in fact be written at offset 4 in the image 614 file, since the first 16 bytes are skipped when writing. 615 name-prefix: Adds a prefix to the name of every entry in the section 616 when writing out the map 617 618Since a section is also an entry, it inherits all the properies of entries 619too. 620 621A section is an entry which can contain other entries, thus allowing 622hierarchical images to be created. See 'Sections and hierarchical images' 623in the binman README for more information. 624 625 626 627Entry: text: An entry which contains text 628----------------------------------------- 629 630The text can be provided either in the node itself or by a command-line 631argument. There is a level of indirection to allow multiple text strings 632and sharing of text. 633 634Properties / Entry arguments: 635 text-label: The value of this string indicates the property / entry-arg 636 that contains the string to place in the entry 637 <xxx> (actual name is the value of text-label): contains the string to 638 place in the entry. 639 <text>: The text to place in the entry (overrides the above mechanism). 640 This is useful when the text is constant. 641 642Example node: 643 644 text { 645 size = <50>; 646 text-label = "message"; 647 }; 648 649You can then use: 650 651 binman -amessage="this is my message" 652 653and binman will insert that string into the entry. 654 655It is also possible to put the string directly in the node: 656 657 text { 658 size = <8>; 659 text-label = "message"; 660 message = "a message directly in the node" 661 }; 662 663or just: 664 665 text { 666 size = <8>; 667 text = "some text directly in the node" 668 }; 669 670The text is not itself nul-terminated. This can be achieved, if required, 671by setting the size of the entry to something larger than the text. 672 673 674 675Entry: u-boot: U-Boot flat binary 676--------------------------------- 677 678Properties / Entry arguments: 679 - filename: Filename of u-boot.bin (default 'u-boot.bin') 680 681This is the U-Boot binary, containing relocation information to allow it 682to relocate itself at runtime. The binary typically includes a device tree 683blob at the end of it. Use u_boot_nodtb if you want to package the device 684tree separately. 685 686U-Boot can access binman symbols at runtime. See: 687 688 'Access to binman entry offsets at run time (fdt)' 689 690in the binman README for more information. 691 692 693 694Entry: u-boot-dtb: U-Boot device tree 695------------------------------------- 696 697Properties / Entry arguments: 698 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 699 700This is the U-Boot device tree, containing configuration information for 701U-Boot. U-Boot needs this to know what devices are present and which drivers 702to activate. 703 704Note: This is mostly an internal entry type, used by others. This allows 705binman to know which entries contain a device tree. 706 707 708 709Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 710----------------------------------------------------------------------------------- 711 712Properties / Entry arguments: 713 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 714 715See Entry_u_boot_ucode for full details of the three entries involved in 716this process. This entry provides the U-Boot device-tree file, which 717contains the microcode. If the microcode is not being collated into one 718place then the offset and size of the microcode is recorded by this entry, 719for use by u_boot_with_ucode_ptr. If it is being collated, then this 720entry deletes the microcode from the device tree (to save space) and makes 721it available to u_boot_ucode. 722 723 724 725Entry: u-boot-elf: U-Boot ELF image 726----------------------------------- 727 728Properties / Entry arguments: 729 - filename: Filename of u-boot (default 'u-boot') 730 731This is the U-Boot ELF image. It does not include a device tree but can be 732relocated to any address for execution. 733 734 735 736Entry: u-boot-img: U-Boot legacy image 737-------------------------------------- 738 739Properties / Entry arguments: 740 - filename: Filename of u-boot.img (default 'u-boot.img') 741 742This is the U-Boot binary as a packaged image, in legacy format. It has a 743header which allows it to be loaded at the correct address for execution. 744 745You should use FIT (Flat Image Tree) instead of the legacy image for new 746applications. 747 748 749 750Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 751-------------------------------------------------------------------- 752 753Properties / Entry arguments: 754 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin') 755 756This is the U-Boot binary, containing relocation information to allow it 757to relocate itself at runtime. It does not include a device tree blob at 758the end of it so normally cannot work without it. You can add a u_boot_dtb 759entry after this one, or use a u_boot entry instead (which contains both 760U-Boot and the device tree). 761 762 763 764Entry: u-boot-spl: U-Boot SPL binary 765------------------------------------ 766 767Properties / Entry arguments: 768 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 769 770This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 771binary which loads before U-Boot proper, typically into on-chip SRAM. It is 772responsible for locating, loading and jumping to U-Boot. Note that SPL is 773not relocatable so must be loaded to the correct address in SRAM, or written 774to run from the correct address if direct flash execution is possible (e.g. 775on x86 devices). 776 777SPL can access binman symbols at runtime. See: 778 779 'Access to binman entry offsets at run time (symbols)' 780 781in the binman README for more information. 782 783The ELF file 'spl/u-boot-spl' must also be available for this to work, since 784binman uses that to look up symbols to write into the SPL binary. 785 786 787 788Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 789--------------------------------------------------------------------- 790 791Properties / Entry arguments: 792 None 793 794This is similar to u_boot_spl except that padding is added after the SPL 795binary to cover the BSS (Block Started by Symbol) region. This region holds 796the various used by SPL. It is set to 0 by SPL when it starts up. If you 797want to append data to the SPL image (such as a device tree file), you must 798pad out the BSS region to avoid the data overlapping with U-Boot variables. 799This entry is useful in that case. It automatically pads out the entry size 800to cover both the code, data and BSS. 801 802The ELF file 'spl/u-boot-spl' must also be available for this to work, since 803binman uses that to look up the BSS address. 804 805 806 807Entry: u-boot-spl-dtb: U-Boot SPL device tree 808--------------------------------------------- 809 810Properties / Entry arguments: 811 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 812 813This is the SPL device tree, containing configuration information for 814SPL. SPL needs this to know what devices are present and which drivers 815to activate. 816 817 818 819Entry: u-boot-spl-elf: U-Boot SPL ELF image 820------------------------------------------- 821 822Properties / Entry arguments: 823 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl') 824 825This is the U-Boot SPL ELF image. It does not include a device tree but can 826be relocated to any address for execution. 827 828 829 830Entry: u-boot-spl-nodtb: SPL binary without device tree appended 831---------------------------------------------------------------- 832 833Properties / Entry arguments: 834 - filename: Filename of spl/u-boot-spl-nodtb.bin (default 835 'spl/u-boot-spl-nodtb.bin') 836 837This is the U-Boot SPL binary, It does not include a device tree blob at 838the end of it so may not be able to work without it, assuming SPL needs 839a device tree to operation on your platform. You can add a u_boot_spl_dtb 840entry after this one, or use a u_boot_spl entry instead (which contains 841both SPL and the device tree). 842 843 844 845Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 846---------------------------------------------------------------------------- 847 848This is used when SPL must set up the microcode for U-Boot. 849 850See Entry_u_boot_ucode for full details of the entries involved in this 851process. 852 853 854 855Entry: u-boot-tpl: U-Boot TPL binary 856------------------------------------ 857 858Properties / Entry arguments: 859 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') 860 861This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small 862binary which loads before SPL, typically into on-chip SRAM. It is 863responsible for locating, loading and jumping to SPL, the next-stage 864loader. Note that SPL is not relocatable so must be loaded to the correct 865address in SRAM, or written to run from the correct address if direct 866flash execution is possible (e.g. on x86 devices). 867 868SPL can access binman symbols at runtime. See: 869 870 'Access to binman entry offsets at run time (symbols)' 871 872in the binman README for more information. 873 874The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 875binman uses that to look up symbols to write into the TPL binary. 876 877 878 879Entry: u-boot-tpl-dtb: U-Boot TPL device tree 880--------------------------------------------- 881 882Properties / Entry arguments: 883 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') 884 885This is the TPL device tree, containing configuration information for 886TPL. TPL needs this to know what devices are present and which drivers 887to activate. 888 889 890 891Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer 892---------------------------------------------------------------------------- 893 894This is used when TPL must set up the microcode for U-Boot. 895 896See Entry_u_boot_ucode for full details of the entries involved in this 897process. 898 899 900 901Entry: u-boot-tpl-elf: U-Boot TPL ELF image 902------------------------------------------- 903 904Properties / Entry arguments: 905 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl') 906 907This is the U-Boot TPL ELF image. It does not include a device tree but can 908be relocated to any address for execution. 909 910 911 912Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer 913---------------------------------------------------------------------------- 914 915See Entry_u_boot_ucode for full details of the entries involved in this 916process. 917 918 919 920Entry: u-boot-ucode: U-Boot microcode block 921------------------------------------------- 922 923Properties / Entry arguments: 924 None 925 926The contents of this entry are filled in automatically by other entries 927which must also be in the image. 928 929U-Boot on x86 needs a single block of microcode. This is collected from 930the various microcode update nodes in the device tree. It is also unable 931to read the microcode from the device tree on platforms that use FSP 932(Firmware Support Package) binaries, because the API requires that the 933microcode is supplied before there is any SRAM available to use (i.e. 934the FSP sets up the SRAM / cache-as-RAM but does so in the call that 935requires the microcode!). To keep things simple, all x86 platforms handle 936microcode the same way in U-Boot (even non-FSP platforms). This is that 937a table is placed at _dt_ucode_base_size containing the base address and 938size of the microcode. This is either passed to the FSP (for FSP 939platforms), or used to set up the microcode (for non-FSP platforms). 940This all happens in the build system since it is the only way to get 941the microcode into a single blob and accessible without SRAM. 942 943There are two cases to handle. If there is only one microcode blob in 944the device tree, then the ucode pointer it set to point to that. This 945entry (u-boot-ucode) is empty. If there is more than one update, then 946this entry holds the concatenation of all updates, and the device tree 947entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 948last step ensures that that the microcode appears in one contiguous 949block in the image and is not unnecessarily duplicated in the device 950tree. It is referred to as 'collation' here. 951 952Entry types that have a part to play in handling microcode: 953 954 Entry_u_boot_with_ucode_ptr: 955 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 956 It updates it with the address and size of the microcode so that 957 U-Boot can find it early on start-up. 958 Entry_u_boot_dtb_with_ucode: 959 Contains u-boot.dtb. It stores the microcode in a 960 'self.ucode_data' property, which is then read by this class to 961 obtain the microcode if needed. If collation is performed, it 962 removes the microcode from the device tree. 963 Entry_u_boot_ucode: 964 This class. If collation is enabled it reads the microcode from 965 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 966 contents of this entry. 967 968 969 970Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 971-------------------------------------------------------------------- 972 973Properties / Entry arguments: 974 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 975 - optional-ucode: boolean property to make microcode optional. If the 976 u-boot.bin image does not include microcode, no error will 977 be generated. 978 979See Entry_u_boot_ucode for full details of the three entries involved in 980this process. This entry updates U-Boot with the offset and size of the 981microcode, to allow early x86 boot code to find it without doing anything 982complicated. Otherwise it is the same as the u_boot entry. 983 984 985 986Entry: vblock: An entry which contains a Chromium OS verified boot block 987------------------------------------------------------------------------ 988 989Properties / Entry arguments: 990 - content: List of phandles to entries to sign 991 - keydir: Directory containing the public keys to use 992 - keyblock: Name of the key file to use (inside keydir) 993 - signprivate: Name of provide key file to use (inside keydir) 994 - version: Version number of the vblock (typically 1) 995 - kernelkey: Name of the kernel key to use (inside keydir) 996 - preamble-flags: Value of the vboot preamble flags (typically 0) 997 998Output files: 999 - input.<unique_name> - input file passed to futility 1000 - vblock.<unique_name> - output file generated by futility (which is 1001 used as the entry contents) 1002 1003Chromium OS signs the read-write firmware and kernel, writing the signature 1004in this block. This allows U-Boot to verify that the next firmware stage 1005and kernel are genuine. 1006 1007 1008 1009Entry: x86-reset16: x86 16-bit reset code for U-Boot 1010---------------------------------------------------- 1011 1012Properties / Entry arguments: 1013 - filename: Filename of u-boot-x86-reset16.bin (default 1014 'u-boot-x86-reset16.bin') 1015 1016x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1017must be placed at a particular address. This entry holds that code. It is 1018typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1019for jumping to the x86-start16 code, which continues execution. 1020 1021For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead. 1022 1023 1024 1025Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot 1026-------------------------------------------------------- 1027 1028Properties / Entry arguments: 1029 - filename: Filename of u-boot-x86-reset16.bin (default 1030 'u-boot-x86-reset16.bin') 1031 1032x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1033must be placed at a particular address. This entry holds that code. It is 1034typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1035for jumping to the x86-start16 code, which continues execution. 1036 1037For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead. 1038 1039 1040 1041Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot 1042-------------------------------------------------------- 1043 1044Properties / Entry arguments: 1045 - filename: Filename of u-boot-x86-reset16.bin (default 1046 'u-boot-x86-reset16.bin') 1047 1048x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1049must be placed at a particular address. This entry holds that code. It is 1050typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1051for jumping to the x86-start16 code, which continues execution. 1052 1053For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead. 1054 1055 1056 1057Entry: x86-start16: x86 16-bit start-up code for U-Boot 1058------------------------------------------------------- 1059 1060Properties / Entry arguments: 1061 - filename: Filename of u-boot-x86-start16.bin (default 1062 'u-boot-x86-start16.bin') 1063 1064x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1065must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1066entry holds that code. It is typically placed at offset 1067CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1068and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1069U-Boot). 1070 1071For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 1072 1073 1074 1075Entry: x86-start16-spl: x86 16-bit start-up code for SPL 1076-------------------------------------------------------- 1077 1078Properties / Entry arguments: 1079 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default 1080 'spl/u-boot-x86-start16-spl.bin') 1081 1082x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1083must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1084entry holds that code. It is typically placed at offset 1085CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1086and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1087U-Boot). 1088 1089For 32-bit U-Boot, the 'x86-start16' entry type is used instead. 1090 1091 1092 1093Entry: x86-start16-tpl: x86 16-bit start-up code for TPL 1094-------------------------------------------------------- 1095 1096Properties / Entry arguments: 1097 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default 1098 'tpl/u-boot-x86-start16-tpl.bin') 1099 1100x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1101must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1102entry holds that code. It is typically placed at offset 1103CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1104and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1105U-Boot). 1106 1107If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types 1108may be used instead. 1109 1110 1111 1112