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