1Binman Entry Documentation 2=========================== 3 4This file describes the entry types supported by binman. These entry types can 5be placed in an image one by one to build up a final firmware image. It is 6fairly easy to create new entry types. Just add a new file to the 'etype' 7directory. You can use the existing entries as examples. 8 9Note that some entries are subclasses of others, using and extending their 10features to produce new behaviours. 11 12 13 14Entry: blob: Entry containing an arbitrary binary blob 15------------------------------------------------------ 16 17Note: This should not be used by itself. It is normally used as a parent 18class by other entry types. 19 20Properties / Entry arguments: 21 - filename: Filename of file to read into entry 22 23This entry reads data from a file and places it in the entry. The 24default filename is often specified specified by the subclass. See for 25example the 'u_boot' entry which provides the filename 'u-boot.bin'. 26 27 28 29Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass 30----------------------------------------------------------------------------------------- 31 32Properties / Entry arguments: 33 - <xxx>-path: Filename containing the contents of this entry (optional, 34 defaults to 0) 35 36where <xxx> is the blob_fname argument to the constructor. 37 38This entry cannot be used directly. Instead, it is used as a parent class 39for another entry, which defined blob_fname. This parameter is used to 40set the entry-arg or property containing the filename. The entry-arg or 41property is in turn used to set the actual filename. 42 43See cros_ec_rw for an example of this. 44 45 46 47Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image 48-------------------------------------------------------------------------------- 49 50Properties / Entry arguments: 51 - cros-ec-rw-path: Filename containing the EC image 52 53This entry holds a Chromium OS EC (embedded controller) image, for use in 54updating the EC on startup via software sync. 55 56 57 58Entry: fill: An entry which is filled to a particular byte value 59---------------------------------------------------------------- 60 61Properties / Entry arguments: 62 - fill-byte: Byte to use to fill the entry 63 64Note that the size property must be set since otherwise this entry does not 65know how large it should be. 66 67You can often achieve the same effect using the pad-byte property of the 68overall image, in that the space between entries will then be padded with 69that byte. But this entry is sometimes useful for explicitly setting the 70byte value of a region. 71 72 73 74Entry: fmap: An entry which contains an Fmap section 75---------------------------------------------------- 76 77Properties / Entry arguments: 78 None 79 80FMAP is a simple format used by flashrom, an open-source utility for 81reading and writing the SPI flash, typically on x86 CPUs. The format 82provides flashrom with a list of areas, so it knows what it in the flash. 83It can then read or write just a single area, instead of the whole flash. 84 85The format is defined by the flashrom project, in the file lib/fmap.h - 86see www.flashrom.org/Flashrom for more information. 87 88When used, this entry will be populated with an FMAP which reflects the 89entries in the current image. Note that any hierarchy is squashed, since 90FMAP does not support this. 91 92 93 94Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file 95------------------------------------------------------------------------- 96 97Properties / Entry arguments: 98 - filename: Filename of file to read into entry 99 100This file contains microcode for some devices in a special format. An 101example filename is 'Microcode/C0_22211.BIN'. 102 103See README.x86 for information about x86 binary blobs. 104 105 106 107Entry: intel-descriptor: Intel flash descriptor block (4KB) 108----------------------------------------------------------- 109 110Properties / Entry arguments: 111 filename: Filename of file containing the descriptor. This is typically 112 a 4KB binary file, sometimes called 'descriptor.bin' 113 114This entry is placed at the start of flash and provides information about 115the SPI flash regions. In particular it provides the base address and 116size of the ME (Management Engine) region, allowing us to place the ME 117binary in the right place. 118 119With this entry in your image, the position of the 'intel-me' entry will be 120fixed in the image, which avoids you needed to specify an offset for that 121region. This is useful, because it is not possible to change the position 122of the ME region without updating the descriptor. 123 124See README.x86 for information about x86 binary blobs. 125 126 127 128Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file 129------------------------------------------------------------------------------- 130 131Properties / Entry arguments: 132 - filename: Filename of file to read into entry 133 134This file contains binary blobs which are used on some devices to make the 135platform work. U-Boot executes this code since it is not possible to set up 136the hardware using U-Boot open-source code. Documentation is typically not 137available in sufficient detail to allow this. 138 139An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd' 140 141See README.x86 for information about x86 binary blobs. 142 143 144 145Entry: intel-me: Entry containing an Intel Management Engine (ME) file 146---------------------------------------------------------------------- 147 148Properties / Entry arguments: 149 - filename: Filename of file to read into entry 150 151This file contains code used by the SoC that is required to make it work. 152The Management Engine is like a background task that runs things that are 153not clearly documented, but may include keyboard, deplay and network 154access. For platform that use ME it is not possible to disable it. U-Boot 155does not directly execute code in the ME binary. 156 157A typical filename is 'me.bin'. 158 159See README.x86 for information about x86 binary blobs. 160 161 162 163Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file 164---------------------------------------------------------------------------- 165 166Properties / Entry arguments: 167 - filename: Filename of file to read into entry 168 169This file contains code for setting up the SDRAM on some Intel systems. This 170is executed by U-Boot when needed early during startup. A typical filename 171is 'mrc.bin'. 172 173See README.x86 for information about x86 binary blobs. 174 175 176 177Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file 178----------------------------------------------------------------------- 179 180Properties / Entry arguments: 181 - filename: Filename of file to read into entry 182 183This file contains code that sets up the integrated graphics subsystem on 184some Intel SoCs. U-Boot executes this when the display is started up. 185 186See README.x86 for information about Intel binary blobs. 187 188 189 190Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file 191----------------------------------------------------------------------------- 192 193Properties / Entry arguments: 194 - filename: Filename of file to read into entry 195 196This file contains code that sets up the integrated graphics subsystem on 197some Intel SoCs. U-Boot executes this when the display is started up. 198 199This is similar to the VBT file but in a different format. 200 201See README.x86 for information about Intel binary blobs. 202 203 204 205Entry: section: Entry that contains other entries 206------------------------------------------------- 207 208Properties / Entry arguments: (see binman README for more information) 209 - size: Size of section in bytes 210 - align-size: Align size to a particular power of two 211 - pad-before: Add padding before the entry 212 - pad-after: Add padding after the entry 213 - pad-byte: Pad byte to use when padding 214 - sort-by-offset: Reorder the entries by offset 215 - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) 216 - name-prefix: Adds a prefix to the name of every entry in the section 217 when writing out the map 218 219A section is an entry which can contain other entries, thus allowing 220hierarchical images to be created. See 'Sections and hierarchical images' 221in the binman README for more information. 222 223 224 225Entry: text: An entry which contains text 226----------------------------------------- 227 228The text can be provided either in the node itself or by a command-line 229argument. There is a level of indirection to allow multiple text strings 230and sharing of text. 231 232Properties / Entry arguments: 233 text-label: The value of this string indicates the property / entry-arg 234 that contains the string to place in the entry 235 <xxx> (actual name is the value of text-label): contains the string to 236 place in the entry. 237 238Example node: 239 240 text { 241 size = <50>; 242 text-label = "message"; 243 }; 244 245You can then use: 246 247 binman -amessage="this is my message" 248 249and binman will insert that string into the entry. 250 251It is also possible to put the string directly in the node: 252 253 text { 254 size = <8>; 255 text-label = "message"; 256 message = "a message directly in the node" 257 }; 258 259The text is not itself nul-terminated. This can be achieved, if required, 260by setting the size of the entry to something larger than the text. 261 262 263 264Entry: u-boot: U-Boot flat binary 265--------------------------------- 266 267Properties / Entry arguments: 268 - filename: Filename of u-boot.bin (default 'u-boot.bin') 269 270This is the U-Boot binary, containing relocation information to allow it 271to relocate itself at runtime. The binary typically includes a device tree 272blob at the end of it. Use u_boot_nodtb if you want to package the device 273tree separately. 274 275U-Boot can access binman symbols at runtime. See: 276 277 'Access to binman entry offsets at run time (fdt)' 278 279in the binman README for more information. 280 281 282 283Entry: u-boot-dtb: U-Boot device tree 284------------------------------------- 285 286Properties / Entry arguments: 287 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 288 289This is the U-Boot device tree, containing configuration information for 290U-Boot. U-Boot needs this to know what devices are present and which drivers 291to activate. 292 293 294 295Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed 296----------------------------------------------------------------------------------- 297 298Properties / Entry arguments: 299 - filename: Filename of u-boot.dtb (default 'u-boot.dtb') 300 301See Entry_u_boot_ucode for full details of the three entries involved in 302this process. This entry provides the U-Boot device-tree file, which 303contains the microcode. If the microcode is not being collated into one 304place then the offset and size of the microcode is recorded by this entry, 305for use by u_boot_with_ucode_ptr. If it is being collated, then this 306entry deletes the microcode from the device tree (to save space) and makes 307it available to u_boot_ucode. 308 309 310 311Entry: u-boot-img: U-Boot legacy image 312-------------------------------------- 313 314Properties / Entry arguments: 315 - filename: Filename of u-boot.img (default 'u-boot.img') 316 317This is the U-Boot binary as a packaged image, in legacy format. It has a 318header which allows it to be loaded at the correct address for execution. 319 320You should use FIT (Flat Image Tree) instead of the legacy image for new 321applications. 322 323 324 325Entry: u-boot-nodtb: U-Boot flat binary without device tree appended 326-------------------------------------------------------------------- 327 328Properties / Entry arguments: 329 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin') 330 331This is the U-Boot binary, containing relocation information to allow it 332to relocate itself at runtime. It does not include a device tree blob at 333the end of it so normally cannot work without it. You can add a u_boot_dtb 334entry after this one, or use a u_boot entry instead (which contains both 335U-Boot and the device tree). 336 337 338 339Entry: u-boot-spl: U-Boot SPL binary 340------------------------------------ 341 342Properties / Entry arguments: 343 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin') 344 345This is the U-Boot SPL (Secondary Program Loader) binary. This is a small 346binary which loads before U-Boot proper, typically into on-chip SRAM. It is 347responsible for locating, loading and jumping to U-Boot. Note that SPL is 348not relocatable so must be loaded to the correct address in SRAM, or written 349to run from the correct address is direct flash execution is possible (e.g. 350on x86 devices). 351 352SPL can access binman symbols at runtime. See: 353 354 'Access to binman entry offsets at run time (symbols)' 355 356in the binman README for more information. 357 358The ELF file 'spl/u-boot-spl' must also be available for this to work, since 359binman uses that to look up symbols to write into the SPL binary. 360 361 362 363Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region 364--------------------------------------------------------------------- 365 366Properties / Entry arguments: 367 None 368 369This is similar to u_boot_spl except that padding is added after the SPL 370binary to cover the BSS (Block Started by Symbol) region. This region holds 371the various used by SPL. It is set to 0 by SPL when it starts up. If you 372want to append data to the SPL image (such as a device tree file), you must 373pad out the BSS region to avoid the data overlapping with U-Boot variables. 374This entry is useful in that case. It automatically pads out the entry size 375to cover both the code, data and BSS. 376 377The ELF file 'spl/u-boot-spl' must also be available for this to work, since 378binman uses that to look up the BSS address. 379 380 381 382Entry: u-boot-spl-dtb: U-Boot SPL device tree 383--------------------------------------------- 384 385Properties / Entry arguments: 386 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb') 387 388This is the SPL device tree, containing configuration information for 389SPL. SPL needs this to know what devices are present and which drivers 390to activate. 391 392 393 394Entry: u-boot-spl-nodtb: SPL binary without device tree appended 395---------------------------------------------------------------- 396 397Properties / Entry arguments: 398 - filename: Filename of spl/u-boot-spl-nodtb.bin (default 399 'spl/u-boot-spl-nodtb.bin') 400 401This is the U-Boot SPL binary, It does not include a device tree blob at 402the end of it so may not be able to work without it, assuming SPL needs 403a device tree to operation on your platform. You can add a u_boot_spl_dtb 404entry after this one, or use a u_boot_spl entry instead (which contains 405both SPL and the device tree). 406 407 408 409Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer 410---------------------------------------------------------------------------- 411 412See Entry_u_boot_ucode for full details of the entries involved in this 413process. 414 415 416 417Entry: u-boot-ucode: U-Boot microcode block 418------------------------------------------- 419 420Properties / Entry arguments: 421 None 422 423The contents of this entry are filled in automatically by other entries 424which must also be in the image. 425 426U-Boot on x86 needs a single block of microcode. This is collected from 427the various microcode update nodes in the device tree. It is also unable 428to read the microcode from the device tree on platforms that use FSP 429(Firmware Support Package) binaries, because the API requires that the 430microcode is supplied before there is any SRAM available to use (i.e. 431the FSP sets up the SRAM / cache-as-RAM but does so in the call that 432requires the microcode!). To keep things simple, all x86 platforms handle 433microcode the same way in U-Boot (even non-FSP platforms). This is that 434a table is placed at _dt_ucode_base_size containing the base address and 435size of the microcode. This is either passed to the FSP (for FSP 436platforms), or used to set up the microcode (for non-FSP platforms). 437This all happens in the build system since it is the only way to get 438the microcode into a single blob and accessible without SRAM. 439 440There are two cases to handle. If there is only one microcode blob in 441the device tree, then the ucode pointer it set to point to that. This 442entry (u-boot-ucode) is empty. If there is more than one update, then 443this entry holds the concatenation of all updates, and the device tree 444entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This 445last step ensures that that the microcode appears in one contiguous 446block in the image and is not unnecessarily duplicated in the device 447tree. It is referred to as 'collation' here. 448 449Entry types that have a part to play in handling microcode: 450 451 Entry_u_boot_with_ucode_ptr: 452 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree). 453 It updates it with the address and size of the microcode so that 454 U-Boot can find it early on start-up. 455 Entry_u_boot_dtb_with_ucode: 456 Contains u-boot.dtb. It stores the microcode in a 457 'self.ucode_data' property, which is then read by this class to 458 obtain the microcode if needed. If collation is performed, it 459 removes the microcode from the device tree. 460 Entry_u_boot_ucode: 461 This class. If collation is enabled it reads the microcode from 462 the Entry_u_boot_dtb_with_ucode entry, and uses it as the 463 contents of this entry. 464 465 466 467Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer 468-------------------------------------------------------------------- 469 470Properties / Entry arguments: 471 - filename: Filename of u-boot-nodtb.dtb (default 'u-boot-nodtb.dtb') 472 473See Entry_u_boot_ucode for full details of the three entries involved in 474this process. This entry updates U-Boot with the offset and size of the 475microcode, to allow early x86 boot code to find it without doing anything 476complicated. Otherwise it is the same as the u_boot entry. 477 478 479 480Entry: x86-start16: x86 16-bit start-up code for U-Boot 481------------------------------------------------------- 482 483Properties / Entry arguments: 484 - filename: Filename of u-boot-x86-16bit.bin (default 485 'u-boot-x86-16bit.bin') 486 487x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code 488must be placed at a particular address. This entry holds that code. It is 489typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 490for changing to 32-bit mode and jumping to U-Boot's entry point, which 491requires 32-bit mode (for 32-bit U-Boot). 492 493For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead. 494 495 496 497Entry: x86-start16-spl: x86 16-bit start-up code for SPL 498-------------------------------------------------------- 499 500Properties / Entry arguments: 501 - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default 502 'spl/u-boot-x86-16bit-spl.bin') 503 504x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code 505must be placed at a particular address. This entry holds that code. It is 506typically placed at offset CONFIG_SYS_X86_START16. The code is responsible 507for changing to 32-bit mode and starting SPL, which in turn changes to 50864-bit mode and jumps to U-Boot (for 64-bit U-Boot). 509 510For 32-bit U-Boot, the 'x86_start16' entry type is used instead. 511 512 513 514