Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
etype/ | H | 07-Mar-2021 | - | 1,904 | 1,218 | |
test/ | H | 07-Mar-2021 | - | 2,116 | 1,639 | |
.gitignore | H A D | 07-Mar-2021 | 6 | 2 | 1 | |
README | H A D | 07-Mar-2021 | 29 KiB | 781 | 576 | |
README.entries | H A D | 07-Mar-2021 | 24.8 KiB | 699 | 445 | |
binman | H A D | 07-Mar-2021 | 4.6 KiB | 158 | 119 | |
binman.py | H A D | 07-Mar-2021 | 4.6 KiB | 158 | 119 | |
bsection.py | H A D | 07-Mar-2021 | 17 KiB | 465 | 394 | |
cmdline.py | H A D | 07-Mar-2021 | 3 KiB | 67 | 54 | |
control.py | H A D | 07-Mar-2021 | 6.6 KiB | 196 | 141 | |
elf.py | H A D | 07-Mar-2021 | 4.3 KiB | 131 | 104 | |
elf_test.py | H A D | 07-Mar-2021 | 4.8 KiB | 141 | 108 | |
entry.py | H A D | 07-Mar-2021 | 18.2 KiB | 533 | 414 | |
entry_test.py | H A D | 07-Mar-2021 | 2.6 KiB | 85 | 65 | |
fdt_test.py | H A D | 07-Mar-2021 | 2.8 KiB | 87 | 65 | |
fmap_util.py | H A D | 07-Mar-2021 | 3.2 KiB | 114 | 82 | |
ftest.py | H A D | 07-Mar-2021 | 72.2 KiB | 1,777 | 1,460 | |
image.py | H A D | 07-Mar-2021 | 5 KiB | 154 | 116 | |
image_test.py | H A D | 07-Mar-2021 | 1.8 KiB | 49 | 37 | |
state.py | H A D | 07-Mar-2021 | 7 KiB | 254 | 184 |
README
1# SPDX-License-Identifier: GPL-2.0+ 2# Copyright (c) 2016 Google, Inc 3 4Introduction 5------------ 6 7Firmware often consists of several components which must be packaged together. 8For example, we may have SPL, U-Boot, a device tree and an environment area 9grouped together and placed in MMC flash. When the system starts, it must be 10able to find these pieces. 11 12So far U-Boot has not provided a way to handle creating such images in a 13general way. Each SoC does what it needs to build an image, often packing or 14concatenating images in the U-Boot build system. 15 16Binman aims to provide a mechanism for building images, from simple 17SPL + U-Boot combinations, to more complex arrangements with many parts. 18 19 20What it does 21------------ 22 23Binman reads your board's device tree and finds a node which describes the 24required image layout. It uses this to work out what to place where. The 25output file normally contains the device tree, so it is in principle possible 26to read an image and extract its constituent parts. 27 28 29Features 30-------- 31 32So far binman is pretty simple. It supports binary blobs, such as 'u-boot', 33'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can 34place entries at a fixed location in the image, or fit them together with 35suitable padding and alignment. It provides a way to process binaries before 36they are included, by adding a Python plug-in. The device tree is available 37to U-Boot at run-time so that the images can be interpreted. 38 39Binman does not yet update the device tree with the final location of 40everything when it is done. A simple C structure could be generated for 41constrained environments like SPL (using dtoc) but this is also not 42implemented. 43 44Binman can also support incorporating filesystems in the image if required. 45For example x86 platforms may use CBFS in some cases. 46 47Binman is intended for use with U-Boot but is designed to be general enough 48to be useful in other image-packaging situations. 49 50 51Motivation 52---------- 53 54Packaging of firmware is quite a different task from building the various 55parts. In many cases the various binaries which go into the image come from 56separate build systems. For example, ARM Trusted Firmware is used on ARMv8 57devices but is not built in the U-Boot tree. If a Linux kernel is included 58in the firmware image, it is built elsewhere. 59 60It is of course possible to add more and more build rules to the U-Boot 61build system to cover these cases. It can shell out to other Makefiles and 62build scripts. But it seems better to create a clear divide between building 63software and packaging it. 64 65At present this is handled by manual instructions, different for each board, 66on how to create images that will boot. By turning these instructions into a 67standard format, we can support making valid images for any board without 68manual effort, lots of READMEs, etc. 69 70Benefits: 71- Each binary can have its own build system and tool chain without creating 72any dependencies between them 73- Avoids the need for a single-shot build: individual parts can be updated 74and brought in as needed 75- Provides for a standard image description available in the build and at 76run-time 77- SoC-specific image-signing tools can be accomodated 78- Avoids cluttering the U-Boot build system with image-building code 79- The image description is automatically available at run-time in U-Boot, 80SPL. It can be made available to other software also 81- The image description is easily readable (it's a text file in device-tree 82format) and permits flexible packing of binaries 83 84 85Terminology 86----------- 87 88Binman uses the following terms: 89 90- image - an output file containing a firmware image 91- binary - an input binary that goes into the image 92 93 94Relationship to FIT 95------------------- 96 97FIT is U-Boot's official image format. It supports multiple binaries with 98load / execution addresses, compression. It also supports verification 99through hashing and RSA signatures. 100 101FIT was originally designed to support booting a Linux kernel (with an 102optional ramdisk) and device tree chosen from various options in the FIT. 103Now that U-Boot supports configuration via device tree, it is possible to 104load U-Boot from a FIT, with the device tree chosen by SPL. 105 106Binman considers FIT to be one of the binaries it can place in the image. 107 108Where possible it is best to put as much as possible in the FIT, with binman 109used to deal with cases not covered by FIT. Examples include initial 110execution (since FIT itself does not have an executable header) and dealing 111with device boundaries, such as the read-only/read-write separation in SPI 112flash. 113 114For U-Boot, binman should not be used to create ad-hoc images in place of 115FIT. 116 117 118Relationship to mkimage 119----------------------- 120 121The mkimage tool provides a means to create a FIT. Traditionally it has 122needed an image description file: a device tree, like binman, but in a 123different format. More recently it has started to support a '-f auto' mode 124which can generate that automatically. 125 126More relevant to binman, mkimage also permits creation of many SoC-specific 127image types. These can be listed by running 'mkimage -T list'. Examples 128include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often 129called from the U-Boot build system for this reason. 130 131Binman considers the output files created by mkimage to be binary blobs 132which it can place in an image. Binman does not replace the mkimage tool or 133this purpose. It would be possible in some situations to create a new entry 134type for the images in mkimage, but this would not add functionality. It 135seems better to use the mkimage tool to generate binaries and avoid blurring 136the boundaries between building input files (mkimage) and packaging then 137into a final image (binman). 138 139 140Example use of binman in U-Boot 141------------------------------- 142 143Binman aims to replace some of the ad-hoc image creation in the U-Boot 144build system. 145 146Consider sunxi. It has the following steps: 147 1481. It uses a custom mksunxiboot tool to build an SPL image called 149sunxi-spl.bin. This should probably move into mkimage. 150 1512. It uses mkimage to package U-Boot into a legacy image file (so that it can 152hold the load and execution address) called u-boot.img. 153 1543. It builds a final output image called u-boot-sunxi-with-spl.bin which 155consists of sunxi-spl.bin, some padding and u-boot.img. 156 157Binman is intended to replace the last step. The U-Boot build system builds 158u-boot.bin and sunxi-spl.bin. Binman can then take over creation of 159sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any 160case, it would then create the image from the component parts. 161 162This simplifies the U-Boot Makefile somewhat, since various pieces of logic 163can be replaced by a call to binman. 164 165 166Example use of binman for x86 167----------------------------- 168 169In most cases x86 images have a lot of binary blobs, 'black-box' code 170provided by Intel which must be run for the platform to work. Typically 171these blobs are not relocatable and must be placed at fixed areas in the 172firmware image. 173 174Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA 175BIOS, reference code and Intel ME binaries into a u-boot.rom file. 176 177Binman is intended to replace all of this, with ifdtool left to handle only 178the configuration of the Intel-format descriptor. 179 180 181Running binman 182-------------- 183 184Type: 185 186 binman -b <board_name> 187 188to build an image for a board. The board name is the same name used when 189configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox'). 190Binman assumes that the input files for the build are in ../b/<board_name>. 191 192Or you can specify this explicitly: 193 194 binman -I <build_path> 195 196where <build_path> is the build directory containing the output of the U-Boot 197build. 198 199(Future work will make this more configurable) 200 201In either case, binman picks up the device tree file (u-boot.dtb) and looks 202for its instructions in the 'binman' node. 203 204Binman has a few other options which you can see by running 'binman -h'. 205 206 207Enabling binman for a board 208--------------------------- 209 210At present binman is invoked from a rule in the main Makefile. Typically you 211will have a rule like: 212 213ifneq ($(CONFIG_ARCH_<something>),) 214u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE 215 $(call if_changed,binman) 216endif 217 218This assumes that u-boot-<your_suffix>.bin is a target, and is the final file 219that you need to produce. You can make it a target by adding it to ALL-y 220either in the main Makefile or in a config.mk file in your arch subdirectory. 221 222Once binman is executed it will pick up its instructions from a device-tree 223file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. 224You can use other, more specific CONFIG options - see 'Automatic .dtsi 225inclusion' below. 226 227 228Image description format 229------------------------ 230 231The binman node is called 'binman'. An example image description is shown 232below: 233 234 binman { 235 filename = "u-boot-sunxi-with-spl.bin"; 236 pad-byte = <0xff>; 237 blob { 238 filename = "spl/sunxi-spl.bin"; 239 }; 240 u-boot { 241 offset = <CONFIG_SPL_PAD_TO>; 242 }; 243 }; 244 245 246This requests binman to create an image file called u-boot-sunxi-with-spl.bin 247consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the 248normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The 249padding comes from the fact that the second binary is placed at 250CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would 251immediately follow the SPL binary. 252 253The binman node describes an image. The sub-nodes describe entries in the 254image. Each entry represents a region within the overall image. The name of 255the entry (blob, u-boot) tells binman what to put there. For 'blob' we must 256provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'. 257 258Entries are normally placed into the image sequentially, one after the other. 259The image size is the total size of all entries. As you can see, you can 260specify the start offset of an entry using the 'offset' property. 261 262Note that due to a device tree requirement, all entries must have a unique 263name. If you want to put the same binary in the image multiple times, you can 264use any unique name, with the 'type' property providing the type. 265 266The attributes supported for entries are described below. 267 268offset: 269 This sets the offset of an entry within the image or section containing 270 it. The first byte of the image is normally at offset 0. If 'offset' is 271 not provided, binman sets it to the end of the previous region, or the 272 start of the image's entry area (normally 0) if there is no previous 273 region. 274 275align: 276 This sets the alignment of the entry. The entry offset is adjusted 277 so that the entry starts on an aligned boundary within the image. For 278 example 'align = <16>' means that the entry will start on a 16-byte 279 boundary. Alignment shold be a power of 2. If 'align' is not 280 provided, no alignment is performed. 281 282size: 283 This sets the size of the entry. The contents will be padded out to 284 this size. If this is not provided, it will be set to the size of the 285 contents. 286 287pad-before: 288 Padding before the contents of the entry. Normally this is 0, meaning 289 that the contents start at the beginning of the entry. This can be 290 offset the entry contents a little. Defaults to 0. 291 292pad-after: 293 Padding after the contents of the entry. Normally this is 0, meaning 294 that the entry ends at the last byte of content (unless adjusted by 295 other properties). This allows room to be created in the image for 296 this entry to expand later. Defaults to 0. 297 298align-size: 299 This sets the alignment of the entry size. For example, to ensure 300 that the size of an entry is a multiple of 64 bytes, set this to 64. 301 If 'align-size' is not provided, no alignment is performed. 302 303align-end: 304 This sets the alignment of the end of an entry. Some entries require 305 that they end on an alignment boundary, regardless of where they 306 start. This does not move the start of the entry, so the contents of 307 the entry will still start at the beginning. But there may be padding 308 at the end. If 'align-end' is not provided, no alignment is performed. 309 310filename: 311 For 'blob' types this provides the filename containing the binary to 312 put into the entry. If binman knows about the entry type (like 313 u-boot-bin), then there is no need to specify this. 314 315type: 316 Sets the type of an entry. This defaults to the entry name, but it is 317 possible to use any name, and then add (for example) 'type = "u-boot"' 318 to specify the type. 319 320offset-unset: 321 Indicates that the offset of this entry should not be set by placing 322 it immediately after the entry before. Instead, is set by another 323 entry which knows where this entry should go. When this boolean 324 property is present, binman will give an error if another entry does 325 not set the offset (with the GetOffsets() method). 326 327image-pos: 328 This cannot be set on entry (or at least it is ignored if it is), but 329 with the -u option, binman will set it to the absolute image position 330 for each entry. This makes it easy to find out exactly where the entry 331 ended up in the image, regardless of parent sections, etc. 332 333expand-size: 334 Expand the size of this entry to fit available space. This space is only 335 limited by the size of the image/section and the position of the next 336 entry. 337 338The attributes supported for images and sections are described below. Several 339are similar to those for entries. 340 341size: 342 Sets the image size in bytes, for example 'size = <0x100000>' for a 343 1MB image. 344 345align-size: 346 This sets the alignment of the image size. For example, to ensure 347 that the image ends on a 512-byte boundary, use 'align-size = <512>'. 348 If 'align-size' is not provided, no alignment is performed. 349 350pad-before: 351 This sets the padding before the image entries. The first entry will 352 be positioned after the padding. This defaults to 0. 353 354pad-after: 355 This sets the padding after the image entries. The padding will be 356 placed after the last entry. This defaults to 0. 357 358pad-byte: 359 This specifies the pad byte to use when padding in the image. It 360 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'. 361 362filename: 363 This specifies the image filename. It defaults to 'image.bin'. 364 365sort-by-offset: 366 This causes binman to reorder the entries as needed to make sure they 367 are in increasing positional order. This can be used when your entry 368 order may not match the positional order. A common situation is where 369 the 'offset' properties are set by CONFIG options, so their ordering is 370 not known a priori. 371 372 This is a boolean property so needs no value. To enable it, add a 373 line 'sort-by-offset;' to your description. 374 375multiple-images: 376 Normally only a single image is generated. To create more than one 377 image, put this property in the binman node. For example, this will 378 create image1.bin containing u-boot.bin, and image2.bin containing 379 both spl/u-boot-spl.bin and u-boot.bin: 380 381 binman { 382 multiple-images; 383 image1 { 384 u-boot { 385 }; 386 }; 387 388 image2 { 389 spl { 390 }; 391 u-boot { 392 }; 393 }; 394 }; 395 396end-at-4gb: 397 For x86 machines the ROM offsets start just before 4GB and extend 398 up so that the image finished at the 4GB boundary. This boolean 399 option can be enabled to support this. The image size must be 400 provided so that binman knows when the image should start. For an 401 8MB ROM, the offset of the first entry would be 0xfff80000 with 402 this option, instead of 0 without this option. 403 404skip-at-start: 405 This property specifies the entry offset of the first entry. 406 407 For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry 408 offset of the first entry. It can be 0xeff40000 or 0xfff40000 for 409 nor flash boot, 0x201000 for sd boot etc. 410 411 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE + 412 Image size != 4gb. 413 414Examples of the above options can be found in the tests. See the 415tools/binman/test directory. 416 417It is possible to have the same binary appear multiple times in the image, 418either by using a unit number suffix (u-boot@0, u-boot@1) or by using a 419different name for each and specifying the type with the 'type' attribute. 420 421 422Sections and hierachical images 423------------------------------- 424 425Sometimes it is convenient to split an image into several pieces, each of which 426contains its own set of binaries. An example is a flash device where part of 427the image is read-only and part is read-write. We can set up sections for each 428of these, and place binaries in them independently. The image is still produced 429as a single output file. 430 431This feature provides a way of creating hierarchical images. For example here 432is an example image with two copies of U-Boot. One is read-only (ro), intended 433to be written only in the factory. Another is read-write (rw), so that it can be 434upgraded in the field. The sizes are fixed so that the ro/rw boundary is known 435and can be programmed: 436 437 binman { 438 section@0 { 439 read-only; 440 name-prefix = "ro-"; 441 size = <0x100000>; 442 u-boot { 443 }; 444 }; 445 section@1 { 446 name-prefix = "rw-"; 447 size = <0x100000>; 448 u-boot { 449 }; 450 }; 451 }; 452 453This image could be placed into a SPI flash chip, with the protection boundary 454set at 1MB. 455 456A few special properties are provided for sections: 457 458read-only: 459 Indicates that this section is read-only. This has no impact on binman's 460 operation, but his property can be read at run time. 461 462name-prefix: 463 This string is prepended to all the names of the binaries in the 464 section. In the example above, the 'u-boot' binaries which actually be 465 renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to 466 distinguish binaries with otherwise identical names. 467 468 469Entry Documentation 470------------------- 471 472For details on the various entry types supported by binman and how to use them, 473see README.entries. This is generated from the source code using: 474 475 binman -E >tools/binman/README.entries 476 477 478Hashing Entries 479--------------- 480 481It is possible to ask binman to hash the contents of an entry and write that 482value back to the device-tree node. For example: 483 484 binman { 485 u-boot { 486 hash { 487 algo = "sha256"; 488 }; 489 }; 490 }; 491 492Here, a new 'value' property will be written to the 'hash' node containing 493the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole 494sections can be hased if desired, by adding the 'hash' node to the section. 495 496The has value can be chcked at runtime by hashing the data actually read and 497comparing this has to the value in the device tree. 498 499 500Order of image creation 501----------------------- 502 503Image creation proceeds in the following order, for each entry in the image. 504 5051. AddMissingProperties() - binman can add calculated values to the device 506tree as part of its processing, for example the offset and size of each 507entry. This method adds any properties associated with this, expanding the 508device tree as needed. These properties can have placeholder values which are 509set later by SetCalculatedProperties(). By that stage the size of sections 510cannot be changed (since it would cause the images to need to be repacked), 511but the correct values can be inserted. 512 5132. ProcessFdt() - process the device tree information as required by the 514particular entry. This may involve adding or deleting properties. If the 515processing is complete, this method should return True. If the processing 516cannot complete because it needs the ProcessFdt() method of another entry to 517run first, this method should return False, in which case it will be called 518again later. 519 5203. GetEntryContents() - the contents of each entry are obtained, normally by 521reading from a file. This calls the Entry.ObtainContents() to read the 522contents. The default version of Entry.ObtainContents() calls 523Entry.GetDefaultFilename() and then reads that file. So a common mechanism 524to select a file to read is to override that function in the subclass. The 525functions must return True when they have read the contents. Binman will 526retry calling the functions a few times if False is returned, allowing 527dependencies between the contents of different entries. 528 5294. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can 530return a dict containing entries that need updating. The key should be the 531entry name and the value is a tuple (offset, size). This allows an entry to 532provide the offset and size for other entries. The default implementation 533of GetEntryOffsets() returns {}. 534 5355. PackEntries() - calls Entry.Pack() which figures out the offset and 536size of an entry. The 'current' image offset is passed in, and the function 537returns the offset immediately after the entry being packed. The default 538implementation of Pack() is usually sufficient. 539 5406. CheckSize() - checks that the contents of all the entries fits within 541the image size. If the image does not have a defined size, the size is set 542large enough to hold all the entries. 543 5447. CheckEntries() - checks that the entries do not overlap, nor extend 545outside the image. 546 5478. SetCalculatedProperties() - update any calculated properties in the device 548tree. This sets the correct 'offset' and 'size' vaues, for example. 549 5509. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry. 551The default implementatoin does nothing. This can be overriden to adjust the 552contents of an entry in some way. For example, it would be possible to create 553an entry containing a hash of the contents of some other entries. At this 554stage the offset and size of entries should not be adjusted. 555 55610. WriteSymbols() - write the value of symbols into the U-Boot SPL binary. 557See 'Access to binman entry offsets at run time' below for a description of 558what happens in this stage. 559 56011. BuildImage() - builds the image and writes it to a file. This is the final 561step. 562 563 564Automatic .dtsi inclusion 565------------------------- 566 567It is sometimes inconvenient to add a 'binman' node to the .dts file for each 568board. This can be done by using #include to bring in a common file. Another 569approach supported by the U-Boot build system is to automatically include 570a common header. You can then put the binman node (and anything else that is 571specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header 572file. 573 574Binman will search for the following files in arch/<arch>/dts: 575 576 <dts>-u-boot.dtsi where <dts> is the base name of the .dts file 577 <CONFIG_SYS_SOC>-u-boot.dtsi 578 <CONFIG_SYS_CPU>-u-boot.dtsi 579 <CONFIG_SYS_VENDOR>-u-boot.dtsi 580 u-boot.dtsi 581 582U-Boot will only use the first one that it finds. If you need to include a 583more general file you can do that from the more specific file using #include. 584If you are having trouble figuring out what is going on, you can uncomment 585the 'warning' line in scripts/Makefile.lib to see what it has found: 586 587 # Uncomment for debugging 588 # This shows all the files that were considered and the one that we chose. 589 # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw) 590 591 592Access to binman entry offsets at run time (symbols) 593---------------------------------------------------- 594 595Binman assembles images and determines where each entry is placed in the image. 596This information may be useful to U-Boot at run time. For example, in SPL it 597is useful to be able to find the location of U-Boot so that it can be executed 598when SPL is finished. 599 600Binman allows you to declare symbols in the SPL image which are filled in 601with their correct values during the build. For example: 602 603 binman_sym_declare(ulong, u_boot_any, offset); 604 605declares a ulong value which will be assigned to the offset of any U-Boot 606image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. 607You can access this value with something like: 608 609 ulong u_boot_offset = binman_sym(ulong, u_boot_any, offset); 610 611Thus u_boot_offset will be set to the offset of U-Boot in memory, assuming that 612the whole image has been loaded, or is available in flash. You can then jump to 613that address to start U-Boot. 614 615At present this feature is only supported in SPL. In principle it is possible 616to fill in such symbols in U-Boot proper, as well. 617 618 619Access to binman entry offsets at run time (fdt) 620------------------------------------------------ 621 622Binman can update the U-Boot FDT to include the final position and size of 623each entry in the images it processes. The option to enable this is -u and it 624causes binman to make sure that the 'offset', 'image-pos' and 'size' properties 625are set correctly for every entry. Since it is not necessary to specify these in 626the image definition, binman calculates the final values and writes these to 627the device tree. These can be used by U-Boot at run-time to find the location 628of each entry. 629 630 631Compression 632----------- 633 634Binman support compression for 'blob' entries (those of type 'blob' and 635derivatives). To enable this for an entry, add a 'compression' property: 636 637 blob { 638 filename = "datafile"; 639 compression = "lz4"; 640 }; 641 642The entry will then contain the compressed data, using the 'lz4' compression 643algorithm. Currently this is the only one that is supported. 644 645 646 647Map files 648--------- 649 650The -m option causes binman to output a .map file for each image that it 651generates. This shows the offset and size of each entry. For example: 652 653 Offset Size Name 654 00000000 00000028 main-section 655 00000000 00000010 section@0 656 00000000 00000004 u-boot 657 00000010 00000010 section@1 658 00000000 00000004 u-boot 659 660This shows a hierarchical image with two sections, each with a single entry. The 661offsets of the sections are absolute hex byte offsets within the image. The 662offsets of the entries are relative to their respective sections. The size of 663each entry is also shown, in bytes (hex). The indentation shows the entries 664nested inside their sections. 665 666 667Passing command-line arguments to entries 668----------------------------------------- 669 670Sometimes it is useful to pass binman the value of an entry property from the 671command line. For example some entries need access to files and it is not 672always convenient to put these filenames in the image definition (device tree). 673 674The-a option supports this: 675 676 -a<prop>=<value> 677 678where 679 680 <prop> is the property to set 681 <value> is the value to set it to 682 683Not all properties can be provided this way. Only some entries support it, 684typically for filenames. 685 686 687Code coverage 688------------- 689 690Binman is a critical tool and is designed to be very testable. Entry 691implementations target 100% test coverage. Run 'binman -T' to check this. 692 693To enable Python test coverage on Debian-type distributions (e.g. Ubuntu): 694 695 $ sudo apt-get install python-coverage python-pytest 696 697 698Advanced Features / Technical docs 699---------------------------------- 700 701The behaviour of entries is defined by the Entry class. All other entries are 702a subclass of this. An important subclass is Entry_blob which takes binary 703data from a file and places it in the entry. In fact most entry types are 704subclasses of Entry_blob. 705 706Each entry type is a separate file in the tools/binman/etype directory. Each 707file contains a class called Entry_<type> where <type> is the entry type. 708New entry types can be supported by adding new files in that directory. 709These will automatically be detected by binman when needed. 710 711Entry properties are documented in entry.py. The entry subclasses are free 712to change the values of properties to support special behaviour. For example, 713when Entry_blob loads a file, it sets content_size to the size of the file. 714Entry classes can adjust other entries. For example, an entry that knows 715where other entries should be positioned can set up those entries' offsets 716so they don't need to be set in the binman decription. It can also adjust 717entry contents. 718 719Most of the time such essoteric behaviour is not needed, but it can be 720essential for complex images. 721 722If you need to specify a particular device-tree compiler to use, you can define 723the DTC environment variable. This can be useful when the system dtc is too 724old. 725 726To enable a full backtrace and other debugging features in binman, pass 727BINMAN_DEBUG=1 to your build: 728 729 make sandbox_defconfig 730 make BINMAN_DEBUG=1 731 732 733History / Credits 734----------------- 735 736Binman takes a lot of inspiration from a Chrome OS tool called 737'cros_bundle_firmware', which I wrote some years ago. That tool was based on 738a reasonably simple and sound design but has expanded greatly over the 739years. In particular its handling of x86 images is convoluted. 740 741Quite a few lessons have been learned which are hopefully applied here. 742 743 744Design notes 745------------ 746 747On the face of it, a tool to create firmware images should be fairly simple: 748just find all the input binaries and place them at the right place in the 749image. The difficulty comes from the wide variety of input types (simple 750flat binaries containing code, packaged data with various headers), packing 751requirments (alignment, spacing, device boundaries) and other required 752features such as hierarchical images. 753 754The design challenge is to make it easy to create simple images, while 755allowing the more complex cases to be supported. For example, for most 756images we don't much care exactly where each binary ends up, so we should 757not have to specify that unnecessarily. 758 759New entry types should aim to provide simple usage where possible. If new 760core features are needed, they can be added in the Entry base class. 761 762 763To do 764----- 765 766Some ideas: 767- Use of-platdata to make the information available to code that is unable 768 to use device tree (such as a very small SPL image) 769- Allow easy building of images by specifying just the board name 770- Produce a full Python binding for libfdt (for upstream). This is nearing 771 completion but some work remains 772- Add an option to decode an image into the constituent binaries 773- Support building an image for a board (-b) more completely, with a 774 configurable build directory 775- Consider making binman work with buildman, although if it is used in the 776 Makefile, this will be automatic 777 778-- 779Simon Glass <sjg@chromium.org> 7807/7/2016 781
README.entries
1Binman Entry Documentation 2=========================== 3 4This file describes the entry types supported by binman. These entry types can 5be placed in an image one by one to build up a final firmware image. It is 6fairly easy to create new entry types. Just add a new file to the 'etype' 7directory. You can use the existing entries as examples. 8 9Note that some entries are subclasses of others, using and extending their 10features to produce new behaviours. 11 12 13 14Entry: blob: Entry containing an arbitrary binary blob 15------------------------------------------------------ 16 17Note: This should not be used by itself. It is normally used as a parent 18class by other entry types. 19 20Properties / Entry arguments: 21 - filename: Filename of file to read into entry 22 - compress: Compression algorithm to use: 23 none: No compression 24 lz4: Use lz4 compression (via 'lz4' command-line utility) 25 26This entry reads data from a file and places it in the entry. The 27default filename is often specified specified by the subclass. See for 28example the 'u_boot' entry which provides the filename 'u-boot.bin'. 29 30If compression is enabled, an extra 'uncomp-size' property is written to 31the node (if enabled with -u) which provides the uncompressed size of the 32data. 33 34 35 36Entry: blob-dtb: A blob that holds a device tree 37------------------------------------------------ 38 39This is a blob containing a device tree. The contents of the blob are 40obtained from the list of available device-tree files, managed by the 41'state' module. 42 43 44 45Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 46----------------------------------------------------------------------------------------- 47 48Properties / Entry arguments: 49 - <xxx>-path: Filename containing the contents of this entry (optional, 50 defaults to 0) 51 52where <xxx> is the blob_fname argument to the constructor. 53 54This entry cannot be used directly. Instead, it is used as a parent class 55for another entry, which defined blob_fname. This parameter is used to 56set the entry-arg or property containing the filename. The entry-arg or 57property is in turn used to set the actual filename. 58 59See cros_ec_rw for an example of this. 60 61 62 63Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 64-------------------------------------------------------------------------------- 65 66Properties / Entry arguments: 67 - cros-ec-rw-path: Filename containing the EC image 68 69This entry holds a Chromium OS EC (embedded controller) image, for use in 70updating the EC on startup via software sync. 71 72 73 74Entry: files: Entry containing a set of files 75--------------------------------------------- 76 77Properties / Entry arguments: 78 - pattern: Filename pattern to match the files to include 79 - compress: Compression algorithm to use: 80 none: No compression 81 lz4: Use lz4 compression (via 'lz4' command-line utility) 82 83This entry reads a number of files and places each in a separate sub-entry 84within this entry. To access these you need to enable device-tree updates 85at run-time so you can obtain the file positions. 86 87 88 89Entry: fill: An entry which is filled to a particular byte value 90---------------------------------------------------------------- 91 92Properties / Entry arguments: 93 - fill-byte: Byte to use to fill the entry 94 95Note that the size property must be set since otherwise this entry does not 96know how large it should be. 97 98You can often achieve the same effect using the pad-byte property of the 99overall image, in that the space between entries will then be padded with 100that byte. But this entry is sometimes useful for explicitly setting the 101byte value of a region. 102 103 104 105Entry: fmap: An entry which contains an Fmap section 106---------------------------------------------------- 107 108Properties / Entry arguments: 109 None 110 111FMAP is a simple format used by flashrom, an open-source utility for 112reading and writing the SPI flash, typically on x86 CPUs. The format 113provides flashrom with a list of areas, so it knows what it in the flash. 114It can then read or write just a single area, instead of the whole flash. 115 116The format is defined by the flashrom project, in the file lib/fmap.h - 117see www.flashrom.org/Flashrom for more information. 118 119When used, this entry will be populated with an FMAP which reflects the 120entries in the current image. Note that any hierarchy is squashed, since 121FMAP does not support this. 122 123 124 125Entry: gbb: An entry which contains a Chromium OS Google Binary Block 126--------------------------------------------------------------------- 127 128Properties / Entry arguments: 129 - hardware-id: Hardware ID to use for this build (a string) 130 - keydir: Directory containing the public keys to use 131 - bmpblk: Filename containing images used by recovery 132 133Chromium OS uses a GBB to store various pieces of information, in particular 134the root and recovery keys that are used to verify the boot process. Some 135more details are here: 136 137 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts 138 139but note that the page dates from 2013 so is quite out of date. See 140README.chromium for how to obtain the required keys and tools. 141 142 143 144Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file 145------------------------------------------------------------------------- 146 147Properties / Entry arguments: 148 - filename: Filename of file to read into entry 149 150This file contains microcode for some devices in a special format. An 151example filename is 'Microcode/C0_22211.BIN'. 152 153See README.x86 for information about x86 binary blobs. 154 155 156 157Entry: intel-descriptor: Intel flash descriptor block (4KB) 158----------------------------------------------------------- 159 160Properties / Entry arguments: 161 filename: Filename of file containing the descriptor. This is typically 162 a 4KB binary file, sometimes called 'descriptor.bin' 163 164This entry is placed at the start of flash and provides information about 165the SPI flash regions. In particular it provides the base address and 166size of the ME (Management Engine) region, allowing us to place the ME 167binary in the right place. 168 169With this entry in your image, the position of the 'intel-me' entry will be 170fixed in the image, which avoids you needed to specify an offset for that 171region. This is useful, because it is not possible to change the position 172of the ME region without updating the descriptor. 173 174See README.x86 for information about x86 binary blobs. 175 176 177 178Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file 179------------------------------------------------------------------------------- 180 181Properties / Entry arguments: 182 - filename: Filename of file to read into entry 183 184This file contains binary blobs which are used on some devices to make the 185platform work. U-Boot executes this code since it is not possible to set up 186the hardware using U-Boot open-source code. Documentation is typically not 187available in sufficient detail to allow this. 188 189An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 190 191See README.x86 for information about x86 binary blobs. 192 193 194 195Entry: intel-me: Entry containing an Intel Management Engine (ME) file 196---------------------------------------------------------------------- 197 198Properties / Entry arguments: 199 - filename: Filename of file to read into entry 200 201This file contains code used by the SoC that is required to make it work. 202The Management Engine is like a background task that runs things that are 203not clearly documented, but may include keyboard, deplay and network 204access. For platform that use ME it is not possible to disable it. U-Boot 205does not directly execute code in the ME binary. 206 207A typical filename is 'me.bin'. 208 209See README.x86 for information about x86 binary blobs. 210 211 212 213Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file 214---------------------------------------------------------------------------- 215 216Properties / Entry arguments: 217 - filename: Filename of file to read into entry 218 219This file contains code for setting up the SDRAM on some Intel systems. This 220is executed by U-Boot when needed early during startup. A typical filename 221is 'mrc.bin'. 222 223See README.x86 for information about x86 binary blobs. 224 225 226 227Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file 228----------------------------------------------------------------------- 229 230Properties / Entry arguments: 231 - filename: Filename of file to read into entry 232 233This file contains code that sets up the integrated graphics subsystem on 234some Intel SoCs. U-Boot executes this when the display is started up. 235 236See README.x86 for information about Intel binary blobs. 237 238 239 240Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file 241----------------------------------------------------------------------------- 242 243Properties / Entry arguments: 244 - filename: Filename of file to read into entry 245 246This file contains code that sets up the integrated graphics subsystem on 247some Intel SoCs. U-Boot executes this when the display is started up. 248 249This is similar to the VBT file but in a different format. 250 251See README.x86 for information about Intel binary blobs. 252 253 254 255Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot 256----------------------------------------------------------------------------------------- 257 258Properties / Entry arguments: 259 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin') 260 261This enrty is valid for PowerPC mpc85xx cpus. This entry holds 262'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be 263placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'. 264 265 266 267Entry: section: Entry that contains other entries 268------------------------------------------------- 269 270Properties / Entry arguments: (see binman README for more information) 271 - size: Size of section in bytes 272 - align-size: Align size to a particular power of two 273 - pad-before: Add padding before the entry 274 - pad-after: Add padding after the entry 275 - pad-byte: Pad byte to use when padding 276 - sort-by-offset: Reorder the entries by offset 277 - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 278 - name-prefix: Adds a prefix to the name of every entry in the section 279 when writing out the map 280 281A section is an entry which can contain other entries, thus allowing 282hierarchical images to be created. See 'Sections and hierarchical images' 283in the binman README for more information. 284 285 286 287Entry: text: An entry which contains text 288----------------------------------------- 289 290The text can be provided either in the node itself or by a command-line 291argument. There is a level of indirection to allow multiple text strings 292and sharing of text. 293 294Properties / Entry arguments: 295 text-label: The value of this string indicates the property / entry-arg 296 that contains the string to place in the entry 297 <xxx> (actual name is the value of text-label): contains the string to 298 place in the entry. 299 300Example node: 301 302 text { 303 size = <50>; 304 text-label = "message"; 305 }; 306 307You can then use: 308 309 binman -amessage="this is my message" 310 311and binman will insert that string into the entry. 312 313It is also possible to put the string directly in the node: 314 315 text { 316 size = <8>; 317 text-label = "message"; 318 message = "a message directly in the node" 319 }; 320 321The text is not itself nul-terminated. This can be achieved, if required, 322by setting the size of the entry to something larger than the text. 323 324 325 326Entry: u-boot: U-Boot flat binary 327--------------------------------- 328 329Properties / Entry arguments: 330 - filename: Filename of u-boot.bin (default 'u-boot.bin') 331 332This is the U-Boot binary, containing relocation information to allow it 333to relocate itself at runtime. The binary typically includes a device tree 334blob at the end of it. Use u_boot_nodtb if you want to package the device 335tree separately. 336 337U-Boot can access binman symbols at runtime. See: 338 339 'Access to binman entry offsets at run time (fdt)' 340 341in the binman README for more information. 342 343 344 345Entry: u-boot-dtb: U-Boot device tree 346------------------------------------- 347 348Properties / Entry arguments: 349 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 350 351This is the U-Boot device tree, containing configuration information for 352U-Boot. U-Boot needs this to know what devices are present and which drivers 353to activate. 354 355Note: This is mostly an internal entry type, used by others. This allows 356binman to know which entries contain a device tree. 357 358 359 360Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 361----------------------------------------------------------------------------------- 362 363Properties / Entry arguments: 364 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 365 366See Entry_u_boot_ucode for full details of the three entries involved in 367this process. This entry provides the U-Boot device-tree file, which 368contains the microcode. If the microcode is not being collated into one 369place then the offset and size of the microcode is recorded by this entry, 370for use by u_boot_with_ucode_ptr. If it is being collated, then this 371entry deletes the microcode from the device tree (to save space) and makes 372it available to u_boot_ucode. 373 374 375 376Entry: u-boot-elf: U-Boot ELF image 377----------------------------------- 378 379Properties / Entry arguments: 380 - filename: Filename of u-boot (default 'u-boot') 381 382This is the U-Boot ELF image. It does not include a device tree but can be 383relocated to any address for execution. 384 385 386 387Entry: u-boot-img: U-Boot legacy image 388-------------------------------------- 389 390Properties / Entry arguments: 391 - filename: Filename of u-boot.img (default 'u-boot.img') 392 393This is the U-Boot binary as a packaged image, in legacy format. It has a 394header which allows it to be loaded at the correct address for execution. 395 396You should use FIT (Flat Image Tree) instead of the legacy image for new 397applications. 398 399 400 401Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 402-------------------------------------------------------------------- 403 404Properties / Entry arguments: 405 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin') 406 407This is the U-Boot binary, containing relocation information to allow it 408to relocate itself at runtime. It does not include a device tree blob at 409the end of it so normally cannot work without it. You can add a u_boot_dtb 410entry after this one, or use a u_boot entry instead (which contains both 411U-Boot and the device tree). 412 413 414 415Entry: u-boot-spl: U-Boot SPL binary 416------------------------------------ 417 418Properties / Entry arguments: 419 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 420 421This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 422binary which loads before U-Boot proper, typically into on-chip SRAM. It is 423responsible for locating, loading and jumping to U-Boot. Note that SPL is 424not relocatable so must be loaded to the correct address in SRAM, or written 425to run from the correct address if direct flash execution is possible (e.g. 426on x86 devices). 427 428SPL can access binman symbols at runtime. See: 429 430 'Access to binman entry offsets at run time (symbols)' 431 432in the binman README for more information. 433 434The ELF file 'spl/u-boot-spl' must also be available for this to work, since 435binman uses that to look up symbols to write into the SPL binary. 436 437 438 439Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 440--------------------------------------------------------------------- 441 442Properties / Entry arguments: 443 None 444 445This is similar to u_boot_spl except that padding is added after the SPL 446binary to cover the BSS (Block Started by Symbol) region. This region holds 447the various used by SPL. It is set to 0 by SPL when it starts up. If you 448want to append data to the SPL image (such as a device tree file), you must 449pad out the BSS region to avoid the data overlapping with U-Boot variables. 450This entry is useful in that case. It automatically pads out the entry size 451to cover both the code, data and BSS. 452 453The ELF file 'spl/u-boot-spl' must also be available for this to work, since 454binman uses that to look up the BSS address. 455 456 457 458Entry: u-boot-spl-dtb: U-Boot SPL device tree 459--------------------------------------------- 460 461Properties / Entry arguments: 462 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 463 464This is the SPL device tree, containing configuration information for 465SPL. SPL needs this to know what devices are present and which drivers 466to activate. 467 468 469 470Entry: u-boot-spl-elf: U-Boot SPL ELF image 471------------------------------------------- 472 473Properties / Entry arguments: 474 - filename: Filename of SPL u-boot (default 'spl/u-boot') 475 476This is the U-Boot SPL ELF image. It does not include a device tree but can 477be relocated to any address for execution. 478 479 480 481Entry: u-boot-spl-nodtb: SPL binary without device tree appended 482---------------------------------------------------------------- 483 484Properties / Entry arguments: 485 - filename: Filename of spl/u-boot-spl-nodtb.bin (default 486 'spl/u-boot-spl-nodtb.bin') 487 488This is the U-Boot SPL binary, It does not include a device tree blob at 489the end of it so may not be able to work without it, assuming SPL needs 490a device tree to operation on your platform. You can add a u_boot_spl_dtb 491entry after this one, or use a u_boot_spl entry instead (which contains 492both SPL and the device tree). 493 494 495 496Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 497---------------------------------------------------------------------------- 498 499This is used when SPL must set up the microcode for U-Boot. 500 501See Entry_u_boot_ucode for full details of the entries involved in this 502process. 503 504 505 506Entry: u-boot-tpl: U-Boot TPL binary 507------------------------------------ 508 509Properties / Entry arguments: 510 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin') 511 512This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small 513binary which loads before SPL, typically into on-chip SRAM. It is 514responsible for locating, loading and jumping to SPL, the next-stage 515loader. Note that SPL is not relocatable so must be loaded to the correct 516address in SRAM, or written to run from the correct address if direct 517flash execution is possible (e.g. on x86 devices). 518 519SPL can access binman symbols at runtime. See: 520 521 'Access to binman entry offsets at run time (symbols)' 522 523in the binman README for more information. 524 525The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since 526binman uses that to look up symbols to write into the TPL binary. 527 528 529 530Entry: u-boot-tpl-dtb: U-Boot TPL device tree 531--------------------------------------------- 532 533Properties / Entry arguments: 534 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb') 535 536This is the TPL device tree, containing configuration information for 537TPL. TPL needs this to know what devices are present and which drivers 538to activate. 539 540 541 542Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer 543---------------------------------------------------------------------------- 544 545This is used when TPL must set up the microcode for U-Boot. 546 547See Entry_u_boot_ucode for full details of the entries involved in this 548process. 549 550 551 552Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer 553---------------------------------------------------------------------------- 554 555See Entry_u_boot_ucode for full details of the entries involved in this 556process. 557 558 559 560Entry: u-boot-ucode: U-Boot microcode block 561------------------------------------------- 562 563Properties / Entry arguments: 564 None 565 566The contents of this entry are filled in automatically by other entries 567which must also be in the image. 568 569U-Boot on x86 needs a single block of microcode. This is collected from 570the various microcode update nodes in the device tree. It is also unable 571to read the microcode from the device tree on platforms that use FSP 572(Firmware Support Package) binaries, because the API requires that the 573microcode is supplied before there is any SRAM available to use (i.e. 574the FSP sets up the SRAM / cache-as-RAM but does so in the call that 575requires the microcode!). To keep things simple, all x86 platforms handle 576microcode the same way in U-Boot (even non-FSP platforms). This is that 577a table is placed at _dt_ucode_base_size containing the base address and 578size of the microcode. This is either passed to the FSP (for FSP 579platforms), or used to set up the microcode (for non-FSP platforms). 580This all happens in the build system since it is the only way to get 581the microcode into a single blob and accessible without SRAM. 582 583There are two cases to handle. If there is only one microcode blob in 584the device tree, then the ucode pointer it set to point to that. This 585entry (u-boot-ucode) is empty. If there is more than one update, then 586this entry holds the concatenation of all updates, and the device tree 587entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 588last step ensures that that the microcode appears in one contiguous 589block in the image and is not unnecessarily duplicated in the device 590tree. It is referred to as 'collation' here. 591 592Entry types that have a part to play in handling microcode: 593 594 Entry_u_boot_with_ucode_ptr: 595 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 596 It updates it with the address and size of the microcode so that 597 U-Boot can find it early on start-up. 598 Entry_u_boot_dtb_with_ucode: 599 Contains u-boot.dtb. It stores the microcode in a 600 'self.ucode_data' property, which is then read by this class to 601 obtain the microcode if needed. If collation is performed, it 602 removes the microcode from the device tree. 603 Entry_u_boot_ucode: 604 This class. If collation is enabled it reads the microcode from 605 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 606 contents of this entry. 607 608 609 610Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 611-------------------------------------------------------------------- 612 613Properties / Entry arguments: 614 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 615 - optional-ucode: boolean property to make microcode optional. If the 616 u-boot.bin image does not include microcode, no error will 617 be generated. 618 619See Entry_u_boot_ucode for full details of the three entries involved in 620this process. This entry updates U-Boot with the offset and size of the 621microcode, to allow early x86 boot code to find it without doing anything 622complicated. Otherwise it is the same as the u_boot entry. 623 624 625 626Entry: vblock: An entry which contains a Chromium OS verified boot block 627------------------------------------------------------------------------ 628 629Properties / Entry arguments: 630 - keydir: Directory containing the public keys to use 631 - keyblock: Name of the key file to use (inside keydir) 632 - signprivate: Name of provide key file to use (inside keydir) 633 - version: Version number of the vblock (typically 1) 634 - kernelkey: Name of the kernel key to use (inside keydir) 635 - preamble-flags: Value of the vboot preamble flags (typically 0) 636 637Output files: 638 - input.<unique_name> - input file passed to futility 639 - vblock.<unique_name> - output file generated by futility (which is 640 used as the entry contents) 641 642Chromium OS signs the read-write firmware and kernel, writing the signature 643in this block. This allows U-Boot to verify that the next firmware stage 644and kernel are genuine. 645 646 647 648Entry: x86-start16: x86 16-bit start-up code for U-Boot 649------------------------------------------------------- 650 651Properties / Entry arguments: 652 - filename: Filename of u-boot-x86-16bit.bin (default 653 'u-boot-x86-16bit.bin') 654 655x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 656must be placed at a particular address. This entry holds that code. It is 657typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 658for changing to 32-bit mode and jumping to U-Boot's entry point, which 659requires 32-bit mode (for 32-bit U-Boot). 660 661For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 662 663 664 665Entry: x86-start16-spl: x86 16-bit start-up code for SPL 666-------------------------------------------------------- 667 668Properties / Entry arguments: 669 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 670 'spl/u-boot-x86-16bit-spl.bin') 671 672x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 673must be placed at a particular address. This entry holds that code. It is 674typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 675for changing to 32-bit mode and starting SPL, which in turn changes to 67664-bit mode and jumps to U-Boot (for 64-bit U-Boot). 677 678For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 679 680 681 682Entry: x86-start16-tpl: x86 16-bit start-up code for TPL 683-------------------------------------------------------- 684 685Properties / Entry arguments: 686 - filename: Filename of tpl/u-boot-x86-16bit-tpl.bin (default 687 'tpl/u-boot-x86-16bit-tpl.bin') 688 689x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 690must be placed at a particular address. This entry holds that code. It is 691typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 692for changing to 32-bit mode and starting TPL, which in turn jumps to SPL. 693 694If TPL is not being used, the 'x86_start16_spl or 'x86_start16' entry types 695may be used instead. 696 697 698 699