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