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: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob 15----------------------------------------------------- 16 17Properties / Entry arguments: 18 - atf-bl31-path: Filename of file to read into entry. This is typically 19 called bl31.bin or bl31.elf 20 21This entry holds the run-time firmware, typically started by U-Boot SPL. 22See the U-Boot README for your architecture or board for how to use it. See 23https://github.com/ARM-software/arm-trusted-firmware for more information 24about ATF. 25 26 27 28Entry: blob: Arbitrary binary blob 29---------------------------------- 30 31Note: This should not be used by itself. It is normally used as a parent 32class by other entry types. 33 34Properties / Entry arguments: 35 - filename: Filename of file to read into entry 36 - compress: Compression algorithm to use: 37 none: No compression 38 lz4: Use lz4 compression (via 'lz4' command-line utility) 39 40This entry reads data from a file and places it in the entry. The 41default filename is often specified specified by the subclass. See for 42example the 'u-boot' entry which provides the filename 'u-boot.bin'. 43 44If compression is enabled, an extra 'uncomp-size' property is written to 45the node (if enabled with -u) which provides the uncompressed size of the 46data. 47 48 49 50Entry: blob-dtb: A blob that holds a device tree 51------------------------------------------------ 52 53This is a blob containing a device tree. The contents of the blob are 54obtained from the list of available device-tree files, managed by the 55'state' module. 56 57 58 59Entry: blob-ext: Externally built binary blob 60--------------------------------------------- 61 62Note: This should not be used by itself. It is normally used as a parent 63class by other entry types. 64 65If the file providing this blob is missing, binman can optionally ignore it 66and produce a broken image with a warning. 67 68See 'blob' for Properties / Entry arguments. 69 70 71 72Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 73----------------------------------------------------------------------------------------- 74 75Properties / Entry arguments: 76 - <xxx>-path: Filename containing the contents of this entry (optional, 77 defaults to None) 78 79where <xxx> is the blob_fname argument to the constructor. 80 81This entry cannot be used directly. Instead, it is used as a parent class 82for another entry, which defined blob_fname. This parameter is used to 83set the entry-arg or property containing the filename. The entry-arg or 84property is in turn used to set the actual filename. 85 86See cros_ec_rw for an example of this. 87 88 89 90Entry: blob-phase: Section that holds a phase binary 91---------------------------------------------------- 92 93This is a base class that should not normally be used directly. It is used 94when converting a 'u-boot' entry automatically into a 'u-boot-expanded' 95entry; similarly for SPL. 96 97 98 99Entry: cbfs: Coreboot Filesystem (CBFS) 100--------------------------------------- 101 102A CBFS provides a way to group files into a group. It has a simple directory 103structure and allows the position of individual files to be set, since it is 104designed to support execute-in-place in an x86 SPI-flash device. Where XIP 105is not used, it supports compression and storing ELF files. 106 107CBFS is used by coreboot as its way of orgnanising SPI-flash contents. 108 109The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:: 110 111 cbfs { 112 size = <0x100000>; 113 u-boot { 114 cbfs-type = "raw"; 115 }; 116 u-boot-dtb { 117 cbfs-type = "raw"; 118 }; 119 }; 120 121This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb. 122Note that the size is required since binman does not support calculating it. 123The contents of each entry is just what binman would normally provide if it 124were not a CBFS node. A blob type can be used to import arbitrary files as 125with the second subnode below:: 126 127 cbfs { 128 size = <0x100000>; 129 u-boot { 130 cbfs-name = "BOOT"; 131 cbfs-type = "raw"; 132 }; 133 134 dtb { 135 type = "blob"; 136 filename = "u-boot.dtb"; 137 cbfs-type = "raw"; 138 cbfs-compress = "lz4"; 139 cbfs-offset = <0x100000>; 140 }; 141 }; 142 143This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and 144u-boot.dtb (named "dtb") and compressed with the lz4 algorithm. 145 146 147Properties supported in the top-level CBFS node: 148 149cbfs-arch: 150 Defaults to "x86", but you can specify the architecture if needed. 151 152 153Properties supported in the CBFS entry subnodes: 154 155cbfs-name: 156 This is the name of the file created in CBFS. It defaults to the entry 157 name (which is the node name), but you can override it with this 158 property. 159 160cbfs-type: 161 This is the CBFS file type. The following are supported: 162 163 raw: 164 This is a 'raw' file, although compression is supported. It can be 165 used to store any file in CBFS. 166 167 stage: 168 This is an ELF file that has been loaded (i.e. mapped to memory), so 169 appears in the CBFS as a flat binary. The input file must be an ELF 170 image, for example this puts "u-boot" (the ELF image) into a 'stage' 171 entry:: 172 173 cbfs { 174 size = <0x100000>; 175 u-boot-elf { 176 cbfs-name = "BOOT"; 177 cbfs-type = "stage"; 178 }; 179 }; 180 181 You can use your own ELF file with something like:: 182 183 cbfs { 184 size = <0x100000>; 185 something { 186 type = "blob"; 187 filename = "cbfs-stage.elf"; 188 cbfs-type = "stage"; 189 }; 190 }; 191 192 As mentioned, the file is converted to a flat binary, so it is 193 equivalent to adding "u-boot.bin", for example, but with the load and 194 start addresses specified by the ELF. At present there is no option 195 to add a flat binary with a load/start address, similar to the 196 'add-flat-binary' option in cbfstool. 197 198cbfs-offset: 199 This is the offset of the file's data within the CBFS. It is used to 200 specify where the file should be placed in cases where a fixed position 201 is needed. Typical uses are for code which is not relocatable and must 202 execute in-place from a particular address. This works because SPI flash 203 is generally mapped into memory on x86 devices. The file header is 204 placed before this offset so that the data start lines up exactly with 205 the chosen offset. If this property is not provided, then the file is 206 placed in the next available spot. 207 208The current implementation supports only a subset of CBFS features. It does 209not support other file types (e.g. payload), adding multiple files (like the 210'files' entry with a pattern supported by binman), putting files at a 211particular offset in the CBFS and a few other things. 212 213Of course binman can create images containing multiple CBFSs, simply by 214defining these in the binman config:: 215 216 217 binman { 218 size = <0x800000>; 219 cbfs { 220 offset = <0x100000>; 221 size = <0x100000>; 222 u-boot { 223 cbfs-type = "raw"; 224 }; 225 u-boot-dtb { 226 cbfs-type = "raw"; 227 }; 228 }; 229 230 cbfs2 { 231 offset = <0x700000>; 232 size = <0x100000>; 233 u-boot { 234 cbfs-type = "raw"; 235 }; 236 u-boot-dtb { 237 cbfs-type = "raw"; 238 }; 239 image { 240 type = "blob"; 241 filename = "image.jpg"; 242 }; 243 }; 244 }; 245 246This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB, 247both of size 1MB. 248 249 250 251Entry: collection: An entry which contains a collection of other entries 252------------------------------------------------------------------------ 253 254Properties / Entry arguments: 255 - content: List of phandles to entries to include 256 257This allows reusing the contents of other entries. The contents of the 258listed entries are combined to form this entry. This serves as a useful 259base class for entry types which need to process data from elsewhere in 260the image, not necessarily child entries. 261 262 263 264Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 265-------------------------------------------------------------------------------- 266 267Properties / Entry arguments: 268 - cros-ec-rw-path: Filename containing the EC image 269 270This entry holds a Chromium OS EC (embedded controller) image, for use in 271updating the EC on startup via software sync. 272 273 274 275Entry: fdtmap: An entry which contains an FDT map 276------------------------------------------------- 277 278Properties / Entry arguments: 279 None 280 281An FDT map is just a header followed by an FDT containing a list of all the 282entries in the image. The root node corresponds to the image node in the 283original FDT, and an image-name property indicates the image name in that 284original tree. 285 286The header is the string _FDTMAP_ followed by 8 unused bytes. 287 288When used, this entry will be populated with an FDT map which reflects the 289entries in the current image. Hierarchy is preserved, and all offsets and 290sizes are included. 291 292Note that the -u option must be provided to ensure that binman updates the 293FDT with the position of each entry. 294 295Example output for a simple image with U-Boot and an FDT map:: 296 297 / { 298 image-name = "binman"; 299 size = <0x00000112>; 300 image-pos = <0x00000000>; 301 offset = <0x00000000>; 302 u-boot { 303 size = <0x00000004>; 304 image-pos = <0x00000000>; 305 offset = <0x00000000>; 306 }; 307 fdtmap { 308 size = <0x0000010e>; 309 image-pos = <0x00000004>; 310 offset = <0x00000004>; 311 }; 312 }; 313 314If allow-repack is used then 'orig-offset' and 'orig-size' properties are 315added as necessary. See the binman README. 316 317 318 319Entry: files: A set of files arranged in a section 320-------------------------------------------------- 321 322Properties / Entry arguments: 323 - pattern: Filename pattern to match the files to include 324 - files-compress: Compression algorithm to use: 325 none: No compression 326 lz4: Use lz4 compression (via 'lz4' command-line utility) 327 - files-align: Align each file to the given alignment 328 329This entry reads a number of files and places each in a separate sub-entry 330within this entry. To access these you need to enable device-tree updates 331at run-time so you can obtain the file positions. 332 333 334 335Entry: fill: An entry which is filled to a particular byte value 336---------------------------------------------------------------- 337 338Properties / Entry arguments: 339 - fill-byte: Byte to use to fill the entry 340 341Note that the size property must be set since otherwise this entry does not 342know how large it should be. 343 344You can often achieve the same effect using the pad-byte property of the 345overall image, in that the space between entries will then be padded with 346that byte. But this entry is sometimes useful for explicitly setting the 347byte value of a region. 348 349 350 351Entry: fit: Flat Image Tree (FIT) 352--------------------------------- 353 354This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the 355input provided. 356 357Nodes for the FIT should be written out in the binman configuration just as 358they would be in a file passed to mkimage. 359 360For example, this creates an image containing a FIT with U-Boot SPL:: 361 362 binman { 363 fit { 364 description = "Test FIT"; 365 fit,fdt-list = "of-list"; 366 367 images { 368 kernel@1 { 369 description = "SPL"; 370 os = "u-boot"; 371 type = "rkspi"; 372 arch = "arm"; 373 compression = "none"; 374 load = <0>; 375 entry = <0>; 376 377 u-boot-spl { 378 }; 379 }; 380 }; 381 }; 382 }; 383 384U-Boot supports creating fdt and config nodes automatically. To do this, 385pass an of-list property (e.g. -a of-list=file1 file2). This tells binman 386that you want to generates nodes for two files: file1.dtb and file2.dtb 387The fit,fdt-list property (see above) indicates that of-list should be used. 388If the property is missing you will get an error. 389 390Then add a 'generator node', a node with a name starting with '@':: 391 392 images { 393 @fdt-SEQ { 394 description = "fdt-NAME"; 395 type = "flat_dt"; 396 compression = "none"; 397 }; 398 }; 399 400This tells binman to create nodes fdt-1 and fdt-2 for each of your two 401files. All the properties you specify will be included in the node. This 402node acts like a template to generate the nodes. The generator node itself 403does not appear in the output - it is replaced with what binman generates. 404 405You can create config nodes in a similar way:: 406 407 configurations { 408 default = "@config-DEFAULT-SEQ"; 409 @config-SEQ { 410 description = "NAME"; 411 firmware = "atf"; 412 loadables = "uboot"; 413 fdt = "fdt-SEQ"; 414 }; 415 }; 416 417This tells binman to create nodes config-1 and config-2, i.e. a config for 418each of your two files. 419 420Available substitutions for '@' nodes are: 421 422SEQ: 423 Sequence number of the generated fdt (1, 2, ...) 424NAME 425 Name of the dtb as provided (i.e. without adding '.dtb') 426 427Note that if no devicetree files are provided (with '-a of-list' as above) 428then no nodes will be generated. 429 430The 'default' property, if present, will be automatically set to the name 431if of configuration whose devicetree matches the 'default-dt' entry 432argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'. 433 434Available substitutions for '@' property values are 435 436DEFAULT-SEQ: 437 Sequence number of the default fdt,as provided by the 'default-dt' entry 438 argument 439 440Properties (in the 'fit' node itself): 441 fit,external-offset: Indicates that the contents of the FIT are external 442 and provides the external offset. This is passsed to mkimage via 443 the -E and -p flags. 444 445 446 447 448Entry: fmap: An entry which contains an Fmap section 449---------------------------------------------------- 450 451Properties / Entry arguments: 452 None 453 454FMAP is a simple format used by flashrom, an open-source utility for 455reading and writing the SPI flash, typically on x86 CPUs. The format 456provides flashrom with a list of areas, so it knows what it in the flash. 457It can then read or write just a single area, instead of the whole flash. 458 459The format is defined by the flashrom project, in the file lib/fmap.h - 460see www.flashrom.org/Flashrom for more information. 461 462When used, this entry will be populated with an FMAP which reflects the 463entries in the current image. Note that any hierarchy is squashed, since 464FMAP does not support this. Sections are represented as an area appearing 465before its contents, so that it is possible to reconstruct the hierarchy 466from the FMAP by using the offset information. This convention does not 467seem to be documented, but is used in Chromium OS. 468 469CBFS entries appear as a single entry, i.e. the sub-entries are ignored. 470 471 472 473Entry: gbb: An entry which contains a Chromium OS Google Binary Block 474--------------------------------------------------------------------- 475 476Properties / Entry arguments: 477 - hardware-id: Hardware ID to use for this build (a string) 478 - keydir: Directory containing the public keys to use 479 - bmpblk: Filename containing images used by recovery 480 481Chromium OS uses a GBB to store various pieces of information, in particular 482the root and recovery keys that are used to verify the boot process. Some 483more details are here: 484 485 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts 486 487but note that the page dates from 2013 so is quite out of date. See 488README.chromium for how to obtain the required keys and tools. 489 490 491 492Entry: image-header: An entry which contains a pointer to the FDT map 493--------------------------------------------------------------------- 494 495Properties / Entry arguments: 496 location: Location of header ("start" or "end" of image). This is 497 optional. If omitted then the entry must have an offset property. 498 499This adds an 8-byte entry to the start or end of the image, pointing to the 500location of the FDT map. The format is a magic number followed by an offset 501from the start or end of the image, in twos-compliment format. 502 503This entry must be in the top-level part of the image. 504 505NOTE: If the location is at the start/end, you will probably need to specify 506sort-by-offset for the image, unless you actually put the image header 507first/last in the entry list. 508 509 510 511Entry: intel-cmc: Intel Chipset Micro Code (CMC) file 512----------------------------------------------------- 513 514Properties / Entry arguments: 515 - filename: Filename of file to read into entry 516 517This file contains microcode for some devices in a special format. An 518example filename is 'Microcode/C0_22211.BIN'. 519 520See README.x86 for information about x86 binary blobs. 521 522 523 524Entry: intel-descriptor: Intel flash descriptor block (4KB) 525----------------------------------------------------------- 526 527Properties / Entry arguments: 528 filename: Filename of file containing the descriptor. This is typically 529 a 4KB binary file, sometimes called 'descriptor.bin' 530 531This entry is placed at the start of flash and provides information about 532the SPI flash regions. In particular it provides the base address and 533size of the ME (Management Engine) region, allowing us to place the ME 534binary in the right place. 535 536With this entry in your image, the position of the 'intel-me' entry will be 537fixed in the image, which avoids you needed to specify an offset for that 538region. This is useful, because it is not possible to change the position 539of the ME region without updating the descriptor. 540 541See README.x86 for information about x86 binary blobs. 542 543 544 545Entry: intel-fit: Intel Firmware Image Table (FIT) 546-------------------------------------------------- 547 548This entry contains a dummy FIT as required by recent Intel CPUs. The FIT 549contains information about the firmware and microcode available in the 550image. 551 552At present binman only supports a basic FIT with no microcode. 553 554 555 556Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer 557-------------------------------------------------------------- 558 559This entry contains a pointer to the FIT. It is required to be at address 5600xffffffc0 in the image. 561 562 563 564Entry: intel-fsp: Intel Firmware Support Package (FSP) file 565----------------------------------------------------------- 566 567Properties / Entry arguments: 568 - filename: Filename of file to read into entry 569 570This file contains binary blobs which are used on some devices to make the 571platform work. U-Boot executes this code since it is not possible to set up 572the hardware using U-Boot open-source code. Documentation is typically not 573available in sufficient detail to allow this. 574 575An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 576 577See README.x86 for information about x86 binary blobs. 578 579 580 581Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init 582-------------------------------------------------------------------- 583 584Properties / Entry arguments: 585 - filename: Filename of file to read into entry 586 587This file contains a binary blob which is used on some devices to set up 588SDRAM. U-Boot executes this code in SPL so that it can make full use of 589memory. Documentation is typically not available in sufficient detail to 590allow U-Boot do this this itself.. 591 592An example filename is 'fsp_m.bin' 593 594See README.x86 for information about x86 binary blobs. 595 596 597 598Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init 599--------------------------------------------------------------------- 600 601Properties / Entry arguments: 602 - filename: Filename of file to read into entry 603 604This file contains a binary blob which is used on some devices to set up 605the silicon. U-Boot executes this code in U-Boot proper after SDRAM is 606running, so that it can make full use of memory. Documentation is typically 607not available in sufficient detail to allow U-Boot do this this itself. 608 609An example filename is 'fsp_s.bin' 610 611See README.x86 for information about x86 binary blobs. 612 613 614 615Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init 616---------------------------------------------------------------------- 617 618Properties / Entry arguments: 619 - filename: Filename of file to read into entry 620 621This file contains a binary blob which is used on some devices to set up 622temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so 623that it has access to memory for its stack and initial storage. 624 625An example filename is 'fsp_t.bin' 626 627See README.x86 for information about x86 binary blobs. 628 629 630 631Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file 632-------------------------------------------------------------- 633 634Properties / Entry arguments: 635 - filename: Filename of file to read into entry. This is either the 636 IFWI file itself, or a file that can be converted into one using a 637 tool 638 - convert-fit: If present this indicates that the ifwitool should be 639 used to convert the provided file into a IFWI. 640 641This file contains code and data used by the SoC that is required to make 642it work. It includes U-Boot TPL, microcode, things related to the CSE 643(Converged Security Engine, the microcontroller that loads all the firmware) 644and other items beyond the wit of man. 645 646A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a 647file that will be converted to an IFWI. 648 649The position of this entry is generally set by the intel-descriptor entry. 650 651The contents of the IFWI are specified by the subnodes of the IFWI node. 652Each subnode describes an entry which is placed into the IFWFI with a given 653sub-partition (and optional entry name). 654 655Properties for subnodes: 656 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP" 657 - ifwi-entry: entry name t use, e.g. "IBBL" 658 - ifwi-replace: if present, indicates that the item should be replaced 659 in the IFWI. Otherwise it is added. 660 661See README.x86 for information about x86 binary blobs. 662 663 664 665Entry: intel-me: Intel Management Engine (ME) file 666-------------------------------------------------- 667 668Properties / Entry arguments: 669 - filename: Filename of file to read into entry 670 671This file contains code used by the SoC that is required to make it work. 672The Management Engine is like a background task that runs things that are 673not clearly documented, but may include keyboard, display and network 674access. For platform that use ME it is not possible to disable it. U-Boot 675does not directly execute code in the ME binary. 676 677A typical filename is 'me.bin'. 678 679The position of this entry is generally set by the intel-descriptor entry. 680 681See README.x86 for information about x86 binary blobs. 682 683 684 685Entry: intel-mrc: Intel Memory Reference Code (MRC) file 686-------------------------------------------------------- 687 688Properties / Entry arguments: 689 - filename: Filename of file to read into entry 690 691This file contains code for setting up the SDRAM on some Intel systems. This 692is executed by U-Boot when needed early during startup. A typical filename 693is 'mrc.bin'. 694 695See README.x86 for information about x86 binary blobs. 696 697 698 699Entry: intel-refcode: Intel Reference Code file 700----------------------------------------------- 701 702Properties / Entry arguments: 703 - filename: Filename of file to read into entry 704 705This file contains code for setting up the platform on some Intel systems. 706This is executed by U-Boot when needed early during startup. A typical 707filename is 'refcode.bin'. 708 709See README.x86 for information about x86 binary blobs. 710 711 712 713Entry: intel-vbt: Intel Video BIOS Table (VBT) file 714--------------------------------------------------- 715 716Properties / Entry arguments: 717 - filename: Filename of file to read into entry 718 719This file contains code that sets up the integrated graphics subsystem on 720some Intel SoCs. U-Boot executes this when the display is started up. 721 722See README.x86 for information about Intel binary blobs. 723 724 725 726Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file 727--------------------------------------------------------- 728 729Properties / Entry arguments: 730 - filename: Filename of file to read into entry 731 732This file contains code that sets up the integrated graphics subsystem on 733some Intel SoCs. U-Boot executes this when the display is started up. 734 735This is similar to the VBT file but in a different format. 736 737See README.x86 for information about Intel binary blobs. 738 739 740 741Entry: mkimage: Binary produced by mkimage 742------------------------------------------ 743 744Properties / Entry arguments: 745 - datafile: Filename for -d argument 746 - args: Other arguments to pass 747 748The data passed to mkimage is collected from subnodes of the mkimage node, 749e.g.:: 750 751 mkimage { 752 args = "-n test -T imximage"; 753 754 u-boot-spl { 755 }; 756 }; 757 758This calls mkimage to create an imximage with u-boot-spl.bin as the input 759file. The output from mkimage then becomes part of the image produced by 760binman. 761 762 763 764Entry: opensbi: RISC-V OpenSBI fw_dynamic blob 765---------------------------------------------- 766 767Properties / Entry arguments: 768 - opensbi-path: Filename of file to read into entry. This is typically 769 called fw_dynamic.bin 770 771This entry holds the run-time firmware, typically started by U-Boot SPL. 772See the U-Boot README for your architecture or board for how to use it. See 773https://github.com/riscv/opensbi for more information about OpenSBI. 774 775 776 777Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot 778----------------------------------------------------------------------------------------- 779 780Properties / Entry arguments: 781 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin') 782 783This entry is valid for PowerPC mpc85xx cpus. This entry holds 784'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be 785placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'. 786 787 788 789Entry: scp: System Control Processor (SCP) firmware blob 790-------------------------------------------------------- 791 792Properties / Entry arguments: 793 - scp-path: Filename of file to read into the entry, typically scp.bin 794 795This entry holds firmware for an external platform-specific coprocessor. 796 797 798 799Entry: section: Entry that contains other entries 800------------------------------------------------- 801 802Properties / Entry arguments: (see binman README for more information): 803 pad-byte: Pad byte to use when padding 804 sort-by-offset: True if entries should be sorted by offset, False if 805 they must be in-order in the device tree description 806 807 end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 808 809 skip-at-start: Number of bytes before the first entry starts. These 810 effectively adjust the starting offset of entries. For example, 811 if this is 16, then the first entry would start at 16. An entry 812 with offset = 20 would in fact be written at offset 4 in the image 813 file, since the first 16 bytes are skipped when writing. 814 name-prefix: Adds a prefix to the name of every entry in the section 815 when writing out the map 816 align_default: Default alignment for this section, if no alignment is 817 given in the entry 818 819Properties: 820 allow_missing: True if this section permits external blobs to be 821 missing their contents. The second will produce an image but of 822 course it will not work. 823 824Properties: 825 _allow_missing: True if this section permits external blobs to be 826 missing their contents. The second will produce an image but of 827 course it will not work. 828 829Since a section is also an entry, it inherits all the properies of entries 830too. 831 832A section is an entry which can contain other entries, thus allowing 833hierarchical images to be created. See 'Sections and hierarchical images' 834in the binman README for more information. 835 836 837 838Entry: text: An entry which contains text 839----------------------------------------- 840 841The text can be provided either in the node itself or by a command-line 842argument. There is a level of indirection to allow multiple text strings 843and sharing of text. 844 845Properties / Entry arguments: 846 text-label: The value of this string indicates the property / entry-arg 847 that contains the string to place in the entry 848 <xxx> (actual name is the value of text-label): contains the string to 849 place in the entry. 850 <text>: The text to place in the entry (overrides the above mechanism). 851 This is useful when the text is constant. 852 853Example node:: 854 855 text { 856 size = <50>; 857 text-label = "message"; 858 }; 859 860You can then use: 861 862 binman -amessage="this is my message" 863 864and binman will insert that string into the entry. 865 866It is also possible to put the string directly in the node:: 867 868 text { 869 size = <8>; 870 text-label = "message"; 871 message = "a message directly in the node" 872 }; 873 874or just:: 875 876 text { 877 size = <8>; 878 text = "some text directly in the node" 879 }; 880 881The text is not itself nul-terminated. This can be achieved, if required, 882by setting the size of the entry to something larger than the text. 883 884 885 886Entry: u-boot: U-Boot flat binary 887--------------------------------- 888 889Properties / Entry arguments: 890 - filename: Filename of u-boot.bin (default 'u-boot.bin') 891 892This is the U-Boot binary, containing relocation information to allow it 893to relocate itself at runtime. The binary typically includes a device tree 894blob at the end of it. 895 896U-Boot can access binman symbols at runtime. See: 897 898 'Access to binman entry offsets at run time (fdt)' 899 900in the binman README for more information. 901 902Note that this entry is automatically replaced with u-boot-expanded unless 903--no-expanded is used or the node has a 'no-expanded' property. 904 905 906 907Entry: u-boot-dtb: U-Boot device tree 908------------------------------------- 909 910Properties / Entry arguments: 911 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 912 913This is the U-Boot device tree, containing configuration information for 914U-Boot. U-Boot needs this to know what devices are present and which drivers 915to activate. 916 917Note: This is mostly an internal entry type, used by others. This allows 918binman to know which entries contain a device tree. 919 920 921 922Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 923----------------------------------------------------------------------------------- 924 925Properties / Entry arguments: 926 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 927 928See Entry_u_boot_ucode for full details of the three entries involved in 929this process. This entry provides the U-Boot device-tree file, which 930contains the microcode. If the microcode is not being collated into one 931place then the offset and size of the microcode is recorded by this entry, 932for use by u-boot-with-ucode_ptr. If it is being collated, then this 933entry deletes the microcode from the device tree (to save space) and makes 934it available to u-boot-ucode. 935 936 937 938Entry: u-boot-elf: U-Boot ELF image 939----------------------------------- 940 941Properties / Entry arguments: 942 - filename: Filename of u-boot (default 'u-boot') 943 944This is the U-Boot ELF image. It does not include a device tree but can be 945relocated to any address for execution. 946 947 948 949Entry: u-boot-env: An entry which contains a U-Boot environment 950--------------------------------------------------------------- 951 952Properties / Entry arguments: 953 - filename: File containing the environment text, with each line in the 954 form var=value 955 956 957 958Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts 959------------------------------------------------------------------------------ 960 961This is a section containing the U-Boot binary and a devicetree. Using this 962entry type automatically creates this section, with the following entries 963in it: 964 965 u-boot-nodtb 966 u-boot-dtb 967 968Having the devicetree separate allows binman to update it in the final 969image, so that the entries positions are provided to the running U-Boot. 970 971 972 973Entry: u-boot-img: U-Boot legacy image 974-------------------------------------- 975 976Properties / Entry arguments: 977 - filename: Filename of u-boot.img (default 'u-boot.img') 978 979This is the U-Boot binary as a packaged image, in legacy format. It has a 980header which allows it to be loaded at the correct address for execution. 981 982You should use FIT (Flat Image Tree) instead of the legacy image for new 983applications. 984 985 986 987Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 988-------------------------------------------------------------------- 989 990Properties / Entry arguments: 991 - filename: Filename to include (default 'u-boot-nodtb.bin') 992 993This is the U-Boot binary, containing relocation information to allow it 994to relocate itself at runtime. It does not include a device tree blob at 995the end of it so normally cannot work without it. You can add a u-boot-dtb 996entry after this one, or use a u-boot entry instead, normally expands to a 997section containing u-boot and u-boot-dtb 998 999 1000 1001Entry: u-boot-spl: U-Boot SPL binary 1002------------------------------------ 1003 1004Properties / Entry arguments: 1005 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 1006 1007This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 1008binary which loads before U-Boot proper, typically into on-chip SRAM. It is 1009responsible for locating, loading and jumping to U-Boot. Note that SPL is 1010not relocatable so must be loaded to the correct address in SRAM, or written 1011to run from the correct address if direct flash execution is possible (e.g. 1012on x86 devices). 1013 1014SPL can access binman symbols at runtime. See: 1015 1016 'Access to binman entry offsets at run time (symbols)' 1017 1018in the binman README for more information. 1019 1020The ELF file 'spl/u-boot-spl' must also be available for this to work, since 1021binman uses that to look up symbols to write into the SPL binary. 1022 1023Note that this entry is automatically replaced with u-boot-spl-expanded 1024unless --no-expanded is used or the node has a 'no-expanded' property. 1025 1026 1027 1028Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 1029--------------------------------------------------------------------- 1030 1031Properties / Entry arguments: 1032 None 1033 1034This holds the padding added after the SPL binary to cover the BSS (Block 1035Started by Symbol) region. This region holds the various variables used by 1036SPL. It is set to 0 by SPL when it starts up. If you want to append data to 1037the SPL image (such as a device tree file), you must pad out the BSS region 1038to avoid the data overlapping with U-Boot variables. This entry is useful in 1039that case. It automatically pads out the entry size to cover both the code, 1040data and BSS. 1041 1042The contents of this entry will a certain number of zero bytes, determined 1043by __bss_size 1044 1045The ELF file 'spl/u-boot-spl' must also be available for this to work, since 1046binman uses that to look up the BSS address. 1047 1048 1049 1050Entry: u-boot-spl-dtb: U-Boot SPL device tree 1051--------------------------------------------- 1052 1053Properties / Entry arguments: 1054 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 1055 1056This is the SPL device tree, containing configuration information for 1057SPL. SPL needs this to know what devices are present and which drivers 1058to activate. 1059 1060 1061 1062Entry: u-boot-spl-elf: U-Boot SPL ELF image 1063------------------------------------------- 1064 1065Properties / Entry arguments: 1066 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl') 1067 1068This is the U-Boot SPL ELF image. It does not include a device tree but can 1069be relocated to any address for execution. 1070 1071 1072 1073Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts 1074-------------------------------------------------------------------------------------- 1075 1076Properties / Entry arguments: 1077 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to 1078 select) 1079 1080This is a section containing the U-Boot binary, BSS padding if needed and a 1081devicetree. Using this entry type automatically creates this section, with 1082the following entries in it: 1083 1084 u-boot-spl-nodtb 1085 u-boot-spl-bss-pad 1086 u-boot-dtb 1087 1088Having the devicetree separate allows binman to update it in the final 1089image, so that the entries positions are provided to the running U-Boot. 1090 1091This entry is selected based on the value of the 'spl-dtb' entryarg. If 1092this is non-empty (and not 'n' or '0') then this expanded entry is selected. 1093 1094 1095 1096Entry: u-boot-spl-nodtb: SPL binary without device tree appended 1097---------------------------------------------------------------- 1098 1099Properties / Entry arguments: 1100 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin') 1101 1102This is the U-Boot SPL binary, It does not include a device tree blob at 1103the end of it so may not be able to work without it, assuming SPL needs 1104a device tree to operate on your platform. You can add a u-boot-spl-dtb 1105entry after this one, or use a u-boot-spl entry instead' which normally 1106expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and 1107u-boot-spl-dtb 1108 1109SPL can access binman symbols at runtime. See: 1110 1111 'Access to binman entry offsets at run time (symbols)' 1112 1113in the binman README for more information. 1114 1115The ELF file 'spl/u-boot-spl' must also be available for this to work, since 1116binman uses that to look up symbols to write into the SPL binary. 1117 1118 1119 1120Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 1121---------------------------------------------------------------------------- 1122 1123This is used when SPL must set up the microcode for U-Boot. 1124 1125See Entry_u_boot_ucode for full details of the entries involved in this 1126process. 1127 1128 1129 1130Entry: u-boot-tpl: U-Boot TPL binary 1131------------------------------------ 1132 1133Properties / Entry arguments: 1134 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') 1135 1136This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small 1137binary which loads before SPL, typically into on-chip SRAM. It is 1138responsible for locating, loading and jumping to SPL, the next-stage 1139loader. Note that SPL is not relocatable so must be loaded to the correct 1140address in SRAM, or written to run from the correct address if direct 1141flash execution is possible (e.g. on x86 devices). 1142 1143SPL can access binman symbols at runtime. See: 1144 1145 'Access to binman entry offsets at run time (symbols)' 1146 1147in the binman README for more information. 1148 1149The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 1150binman uses that to look up symbols to write into the TPL binary. 1151 1152Note that this entry is automatically replaced with u-boot-tpl-expanded 1153unless --no-expanded is used or the node has a 'no-expanded' property. 1154 1155 1156 1157Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region 1158--------------------------------------------------------------------- 1159 1160Properties / Entry arguments: 1161 None 1162 1163This holds the padding added after the TPL binary to cover the BSS (Block 1164Started by Symbol) region. This region holds the various variables used by 1165TPL. It is set to 0 by TPL when it starts up. If you want to append data to 1166the TPL image (such as a device tree file), you must pad out the BSS region 1167to avoid the data overlapping with U-Boot variables. This entry is useful in 1168that case. It automatically pads out the entry size to cover both the code, 1169data and BSS. 1170 1171The contents of this entry will a certain number of zero bytes, determined 1172by __bss_size 1173 1174The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 1175binman uses that to look up the BSS address. 1176 1177 1178 1179Entry: u-boot-tpl-dtb: U-Boot TPL device tree 1180--------------------------------------------- 1181 1182Properties / Entry arguments: 1183 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') 1184 1185This is the TPL device tree, containing configuration information for 1186TPL. TPL needs this to know what devices are present and which drivers 1187to activate. 1188 1189 1190 1191Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer 1192---------------------------------------------------------------------------- 1193 1194This is used when TPL must set up the microcode for U-Boot. 1195 1196See Entry_u_boot_ucode for full details of the entries involved in this 1197process. 1198 1199 1200 1201Entry: u-boot-tpl-elf: U-Boot TPL ELF image 1202------------------------------------------- 1203 1204Properties / Entry arguments: 1205 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl') 1206 1207This is the U-Boot TPL ELF image. It does not include a device tree but can 1208be relocated to any address for execution. 1209 1210 1211 1212Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts 1213-------------------------------------------------------------------------------------- 1214 1215Properties / Entry arguments: 1216 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to 1217 select) 1218 1219This is a section containing the U-Boot binary, BSS padding if needed and a 1220devicetree. Using this entry type automatically creates this section, with 1221the following entries in it: 1222 1223 u-boot-tpl-nodtb 1224 u-boot-tpl-bss-pad 1225 u-boot-dtb 1226 1227Having the devicetree separate allows binman to update it in the final 1228image, so that the entries positions are provided to the running U-Boot. 1229 1230This entry is selected based on the value of the 'tpl-dtb' entryarg. If 1231this is non-empty (and not 'n' or '0') then this expanded entry is selected. 1232 1233 1234 1235Entry: u-boot-tpl-nodtb: TPL binary without device tree appended 1236---------------------------------------------------------------- 1237 1238Properties / Entry arguments: 1239 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin') 1240 1241This is the U-Boot TPL binary, It does not include a device tree blob at 1242the end of it so may not be able to work without it, assuming TPL needs 1243a device tree to operate on your platform. You can add a u-boot-tpl-dtb 1244entry after this one, or use a u-boot-tpl entry instead, which normally 1245expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and 1246u-boot-tpl-dtb 1247 1248TPL can access binman symbols at runtime. See: 1249 1250 'Access to binman entry offsets at run time (symbols)' 1251 1252in the binman README for more information. 1253 1254The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 1255binman uses that to look up symbols to write into the TPL binary. 1256 1257 1258 1259Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer 1260---------------------------------------------------------------------------- 1261 1262See Entry_u_boot_ucode for full details of the entries involved in this 1263process. 1264 1265 1266 1267Entry: u-boot-ucode: U-Boot microcode block 1268------------------------------------------- 1269 1270Properties / Entry arguments: 1271 None 1272 1273The contents of this entry are filled in automatically by other entries 1274which must also be in the image. 1275 1276U-Boot on x86 needs a single block of microcode. This is collected from 1277the various microcode update nodes in the device tree. It is also unable 1278to read the microcode from the device tree on platforms that use FSP 1279(Firmware Support Package) binaries, because the API requires that the 1280microcode is supplied before there is any SRAM available to use (i.e. 1281the FSP sets up the SRAM / cache-as-RAM but does so in the call that 1282requires the microcode!). To keep things simple, all x86 platforms handle 1283microcode the same way in U-Boot (even non-FSP platforms). This is that 1284a table is placed at _dt_ucode_base_size containing the base address and 1285size of the microcode. This is either passed to the FSP (for FSP 1286platforms), or used to set up the microcode (for non-FSP platforms). 1287This all happens in the build system since it is the only way to get 1288the microcode into a single blob and accessible without SRAM. 1289 1290There are two cases to handle. If there is only one microcode blob in 1291the device tree, then the ucode pointer it set to point to that. This 1292entry (u-boot-ucode) is empty. If there is more than one update, then 1293this entry holds the concatenation of all updates, and the device tree 1294entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 1295last step ensures that that the microcode appears in one contiguous 1296block in the image and is not unnecessarily duplicated in the device 1297tree. It is referred to as 'collation' here. 1298 1299Entry types that have a part to play in handling microcode: 1300 1301 Entry_u_boot_with_ucode_ptr: 1302 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 1303 It updates it with the address and size of the microcode so that 1304 U-Boot can find it early on start-up. 1305 Entry_u_boot_dtb_with_ucode: 1306 Contains u-boot.dtb. It stores the microcode in a 1307 'self.ucode_data' property, which is then read by this class to 1308 obtain the microcode if needed. If collation is performed, it 1309 removes the microcode from the device tree. 1310 Entry_u_boot_ucode: 1311 This class. If collation is enabled it reads the microcode from 1312 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 1313 contents of this entry. 1314 1315 1316 1317Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 1318-------------------------------------------------------------------- 1319 1320Properties / Entry arguments: 1321 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin') 1322 - optional-ucode: boolean property to make microcode optional. If the 1323 u-boot.bin image does not include microcode, no error will 1324 be generated. 1325 1326See Entry_u_boot_ucode for full details of the three entries involved in 1327this process. This entry updates U-Boot with the offset and size of the 1328microcode, to allow early x86 boot code to find it without doing anything 1329complicated. Otherwise it is the same as the u-boot entry. 1330 1331 1332 1333Entry: vblock: An entry which contains a Chromium OS verified boot block 1334------------------------------------------------------------------------ 1335 1336Properties / Entry arguments: 1337 - content: List of phandles to entries to sign 1338 - keydir: Directory containing the public keys to use 1339 - keyblock: Name of the key file to use (inside keydir) 1340 - signprivate: Name of provide key file to use (inside keydir) 1341 - version: Version number of the vblock (typically 1) 1342 - kernelkey: Name of the kernel key to use (inside keydir) 1343 - preamble-flags: Value of the vboot preamble flags (typically 0) 1344 1345Output files: 1346 - input.<unique_name> - input file passed to futility 1347 - vblock.<unique_name> - output file generated by futility (which is 1348 used as the entry contents) 1349 1350Chromium OS signs the read-write firmware and kernel, writing the signature 1351in this block. This allows U-Boot to verify that the next firmware stage 1352and kernel are genuine. 1353 1354 1355 1356Entry: x86-reset16: x86 16-bit reset code for U-Boot 1357---------------------------------------------------- 1358 1359Properties / Entry arguments: 1360 - filename: Filename of u-boot-x86-reset16.bin (default 1361 'u-boot-x86-reset16.bin') 1362 1363x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1364must be placed at a particular address. This entry holds that code. It is 1365typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1366for jumping to the x86-start16 code, which continues execution. 1367 1368For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead. 1369 1370 1371 1372Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot 1373-------------------------------------------------------- 1374 1375Properties / Entry arguments: 1376 - filename: Filename of u-boot-x86-reset16.bin (default 1377 'u-boot-x86-reset16.bin') 1378 1379x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1380must be placed at a particular address. This entry holds that code. It is 1381typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1382for jumping to the x86-start16 code, which continues execution. 1383 1384For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead. 1385 1386 1387 1388Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot 1389-------------------------------------------------------- 1390 1391Properties / Entry arguments: 1392 - filename: Filename of u-boot-x86-reset16.bin (default 1393 'u-boot-x86-reset16.bin') 1394 1395x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1396must be placed at a particular address. This entry holds that code. It is 1397typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible 1398for jumping to the x86-start16 code, which continues execution. 1399 1400For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead. 1401 1402 1403 1404Entry: x86-start16: x86 16-bit start-up code for U-Boot 1405------------------------------------------------------- 1406 1407Properties / Entry arguments: 1408 - filename: Filename of u-boot-x86-start16.bin (default 1409 'u-boot-x86-start16.bin') 1410 1411x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1412must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1413entry holds that code. It is typically placed at offset 1414CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1415and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1416U-Boot). 1417 1418For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 1419 1420 1421 1422Entry: x86-start16-spl: x86 16-bit start-up code for SPL 1423-------------------------------------------------------- 1424 1425Properties / Entry arguments: 1426 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default 1427 'spl/u-boot-x86-start16-spl.bin') 1428 1429x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1430must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1431entry holds that code. It is typically placed at offset 1432CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1433and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1434U-Boot). 1435 1436For 32-bit U-Boot, the 'x86-start16' entry type is used instead. 1437 1438 1439 1440Entry: x86-start16-tpl: x86 16-bit start-up code for TPL 1441-------------------------------------------------------- 1442 1443Properties / Entry arguments: 1444 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default 1445 'tpl/u-boot-x86-start16-tpl.bin') 1446 1447x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 1448must be placed in the top 64KB of the ROM. The reset code jumps to it. This 1449entry holds that code. It is typically placed at offset 1450CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode 1451and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit 1452U-Boot). 1453 1454If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types 1455may be used instead. 1456 1457 1458 1459
