tools/binman/README.entries

15 ------------------------------------------------------
21     - filename: Filename of file to read into entry
22     - compress: Compression algorithm to use:
24         lz4: Use lz4 compression (via 'lz4' command-line utility)
28 example the 'u_boot' entry which provides the filename 'u-boot.bin'.
30 If compression is enabled, an extra 'uncomp-size' property is written to
31 the node (if enabled with -u) which provides the uncompressed size of the
36 Entry: blob-dtb: A blob that holds a device tree
37 ------------------------------------------------
40 obtained from the list of available device-tree files, managed by the
45 Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
46 -----------------------------------------------------------------------------------------
49     - <xxx>-path: Filename containing the contents of this entry (optional,
56 set the entry-arg or property containing the filename. The entry-arg or
63 Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
64 --------------------------------------------------------------------------------
67     - cros-ec-rw-path: Filename containing the EC image
75 ---------------------------------------------
78     - pattern: Filename pattern to match the files to include
79     - compress: Compression algorithm to use:
81         lz4: Use lz4 compression (via 'lz4' command-line utility)
83 This entry reads a number of files and places each in a separate sub-entry
84 within this entry. To access these you need to enable device-tree updates
85 at run-time so you can obtain the file positions.
90 ----------------------------------------------------------------
93     - fill-byte: Byte to use to fill the entry
98 You can often achieve the same effect using the pad-byte property of the
106 ----------------------------------------------------
111 FMAP is a simple format used by flashrom, an open-source utility for
116 The format is defined by the flashrom project, in the file lib/fmap.h -
121 FMAP does not support this.
126 ---------------------------------------------------------------------
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
137     https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
144 Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file
145 -------------------------------------------------------------------------
148     - filename: Filename of file to read into entry
157 Entry: intel-descriptor: Intel flash descriptor block (4KB)
158 -----------------------------------------------------------
169 With this entry in your image, the position of the 'intel-me' entry will be
178 Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file
179 -------------------------------------------------------------------------------
182     - filename: Filename of file to read into entry
185 platform work. U-Boot executes this code since it is not possible to set up
186 the hardware using U-Boot open-source code. Documentation is typically not
189 An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
195 Entry: intel-me: Entry containing an Intel Management Engine (ME) file
196 ----------------------------------------------------------------------
199     - filename: Filename of file to read into entry
204 access. For platform that use ME it is not possible to disable it. U-Boot
213 Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file
214 ----------------------------------------------------------------------------
217     - filename: Filename of file to read into entry
220 is executed by U-Boot when needed early during startup. A typical filename
227 Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file
228 -----------------------------------------------------------------------
231     - filename: Filename of file to read into entry
234 some Intel SoCs. U-Boot executes this when the display is started up.
240 Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file
241 -----------------------------------------------------------------------------
244     - filename: Filename of file to read into entry
247 some Intel SoCs. U-Boot executes this when the display is started up.
255 Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
256 -----------------------------------------------------------------------------------------
259     - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
263 placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
268 -------------------------------------------------
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
288 -----------------------------------------
290 The text can be provided either in the node itself or by a command-line
295     text-label: The value of this string indicates the property / entry-arg
297     <xxx> (actual name is the value of text-label): contains the string to
304         text-label = "message";
309     binman -amessage="this is my message"
317         text-label = "message";
321 The text is not itself nul-terminated. This can be achieved, if required,
326 Entry: u-boot: U-Boot flat binary
327 ---------------------------------
330     - filename: Filename of u-boot.bin (default 'u-boot.bin')
332 This is the U-Boot binary, containing relocation information to allow it
337 U-Boot can access binman symbols at runtime. See:
345 Entry: u-boot-dtb: U-Boot device tree
346 -------------------------------------
349     - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
351 This is the U-Boot device tree, containing configuration information for
352 U-Boot. U-Boot needs this to know what devices are present and which drivers
360 Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
361 -----------------------------------------------------------------------------------
364     - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
367 this process. This entry provides the U-Boot device-tree file, which
376 Entry: u-boot-elf: U-Boot ELF image
377 -----------------------------------
380     - filename: Filename of u-boot (default 'u-boot')
382 This is the U-Boot ELF image. It does not include a device tree but can be
387 Entry: u-boot-img: U-Boot legacy image
388 --------------------------------------
391     - filename: Filename of u-boot.img (default 'u-boot.img')
393 This is the U-Boot binary as a packaged image, in legacy format. It has a
401 Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
402 --------------------------------------------------------------------
405     - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin')
407 This is the U-Boot binary, containing relocation information to allow it
411 U-Boot and the device tree).
415 Entry: u-boot-spl: U-Boot SPL binary
416 ------------------------------------
419     - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
421 This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
422 binary which loads before U-Boot proper, typically into on-chip SRAM. It is
423 responsible for locating, loading and jumping to U-Boot. Note that SPL is
434 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
439 Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
440 ---------------------------------------------------------------------
449 pad out the BSS region to avoid the data overlapping with U-Boot variables.
453 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
458 Entry: u-boot-spl-dtb: U-Boot SPL device tree
459 ---------------------------------------------
462     - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
470 Entry: u-boot-spl-elf: U-Boot SPL ELF image
471 -------------------------------------------
474     - filename: Filename of SPL u-boot (default 'spl/u-boot')
476 This is the U-Boot SPL ELF image. It does not include a device tree but can
481 Entry: u-boot-spl-nodtb: SPL binary without device tree appended
482 ----------------------------------------------------------------
485     - filename: Filename of spl/u-boot-spl-nodtb.bin (default
486         'spl/u-boot-spl-nodtb.bin')
488 This is the U-Boot SPL binary, It does not include a device tree blob at
496 Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
497 ----------------------------------------------------------------------------
499 This is used when SPL must set up the microcode for U-Boot.
506 Entry: u-boot-tpl: U-Boot TPL binary
507 ------------------------------------
510     - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
512 This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
513 binary which loads before SPL, typically into on-chip SRAM. It is
514 responsible for locating, loading and jumping to SPL, the next-stage
525 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
526 binman uses that to look up symbols to write into the TPL binary.
530 Entry: u-boot-tpl-dtb: U-Boot TPL device tree
531 ---------------------------------------------
534     - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
536 This is the TPL device tree, containing configuration information for
537 TPL. TPL needs this to know what devices are present and which drivers
542 Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
543 ----------------------------------------------------------------------------
545 This is used when TPL must set up the microcode for U-Boot.
552 Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
553 ----------------------------------------------------------------------------
560 Entry: u-boot-ucode: U-Boot microcode block
561 -------------------------------------------
569 U-Boot on x86 needs a single block of microcode. This is collected from
572 (Firmware Support Package) binaries, because the API requires that the
574 the FSP sets up the SRAM / cache-as-RAM but does so in the call that
576 microcode the same way in U-Boot (even non-FSP platforms). This is that
579 platforms), or used to set up the microcode (for non-FSP platforms).
585 entry (u-boot-ucode) is empty. If there is more than one update, then
587 entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
595         Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
597         U-Boot can find it early on start-up.
599         Contains u-boot.dtb. It stores the microcode in a
610 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
611 --------------------------------------------------------------------
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
620 this process. This entry updates U-Boot with the offset and size of the
627 ------------------------------------------------------------------------
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)
638     - input.<unique_name> - input file passed to futility
639     - vblock.<unique_name> - output file generated by futility (which is
642 Chromium OS signs the read-write firmware and kernel, writing the signature
643 in this block. This allows U-Boot to verify that the next firmware stage
648 Entry: x86-start16: x86 16-bit start-up code for U-Boot
649 -------------------------------------------------------
652     - filename: Filename of u-boot-x86-16bit.bin (default
653         'u-boot-x86-16bit.bin')
655 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
658 for changing to 32-bit mode and jumping to U-Boot's entry point, which
659 requires 32-bit mode (for 32-bit U-Boot).
661 For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
665 Entry: x86-start16-spl: x86 16-bit start-up code for SPL
666 --------------------------------------------------------
669     - filename: Filename of spl/u-boot-x86-16bit-spl.bin (default
670         'spl/u-boot-x86-16bit-spl.bin')
672 x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code
675 for changing to 32-bit mode and starting SPL, which in turn changes to
676 64-bit mode and jumps to U-Boot (for 64-bit U-Boot).
678 For 32-bit U-Boot, the 'x86_start16' entry type is used instead.
682 Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
683 --------------------------------------------------------
686     - filename: Filename of tpl/u-boot-x86-16bit-tpl.bin (default
687         'tpl/u-boot-x86-16bit-tpl.bin')
689 x86 CPUs start up in 16-bit mode, even if they are 64-bit CPUs. This code
692 for changing to 32-bit mode and starting TPL, which in turn jumps to SPL.
694 If TPL is not being used, the 'x86_start16_spl or 'x86_start16' entry types