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