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