1# SPDX-License-Identifier: GPL-2.0+
2# Copyright (c) 2016 Google, Inc
3
4Introduction
5------------
6
7Firmware often consists of several components which must be packaged together.
8For example, we may have SPL, U-Boot, a device tree and an environment area
9grouped together and placed in MMC flash. When the system starts, it must be
10able to find these pieces.
11
12So far U-Boot has not provided a way to handle creating such images in a
13general way. Each SoC does what it needs to build an image, often packing or
14concatenating images in the U-Boot build system.
15
16Binman aims to provide a mechanism for building images, from simple
17SPL + U-Boot combinations, to more complex arrangements with many parts.
18
19
20What it does
21------------
22
23Binman reads your board's device tree and finds a node which describes the
24required image layout. It uses this to work out what to place where. The
25output file normally contains the device tree, so it is in principle possible
26to read an image and extract its constituent parts.
27
28
29Features
30--------
31
32So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
33'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can
34place entries at a fixed location in the image, or fit them together with
35suitable padding and alignment. It provides a way to process binaries before
36they are included, by adding a Python plug-in. The device tree is available
37to U-Boot at run-time so that the images can be interpreted.
38
39Binman can update the device tree with the final location of everything when it
40is done. Entry positions can be provided to U-Boot SPL as run-time symbols,
41avoiding device-tree code overhead.
42
43Binman can also support incorporating filesystems in the image if required.
44For example x86 platforms may use CBFS in some cases.
45
46Binman is intended for use with U-Boot but is designed to be general enough
47to be useful in other image-packaging situations.
48
49
50Motivation
51----------
52
53Packaging of firmware is quite a different task from building the various
54parts. In many cases the various binaries which go into the image come from
55separate build systems. For example, ARM Trusted Firmware is used on ARMv8
56devices but is not built in the U-Boot tree. If a Linux kernel is included
57in the firmware image, it is built elsewhere.
58
59It is of course possible to add more and more build rules to the U-Boot
60build system to cover these cases. It can shell out to other Makefiles and
61build scripts. But it seems better to create a clear divide between building
62software and packaging it.
63
64At present this is handled by manual instructions, different for each board,
65on how to create images that will boot. By turning these instructions into a
66standard format, we can support making valid images for any board without
67manual effort, lots of READMEs, etc.
68
69Benefits:
70- Each binary can have its own build system and tool chain without creating
71any dependencies between them
72- Avoids the need for a single-shot build: individual parts can be updated
73and brought in as needed
74- Provides for a standard image description available in the build and at
75run-time
76- SoC-specific image-signing tools can be accommodated
77- Avoids cluttering the U-Boot build system with image-building code
78- The image description is automatically available at run-time in U-Boot,
79SPL. It can be made available to other software also
80- The image description is easily readable (it's a text file in device-tree
81format) and permits flexible packing of binaries
82
83
84Terminology
85-----------
86
87Binman uses the following terms:
88
89- image - an output file containing a firmware image
90- binary - an input binary that goes into the image
91
92
93Relationship to FIT
94-------------------
95
96FIT is U-Boot's official image format. It supports multiple binaries with
97load / execution addresses, compression. It also supports verification
98through hashing and RSA signatures.
99
100FIT was originally designed to support booting a Linux kernel (with an
101optional ramdisk) and device tree chosen from various options in the FIT.
102Now that U-Boot supports configuration via device tree, it is possible to
103load U-Boot from a FIT, with the device tree chosen by SPL.
104
105Binman considers FIT to be one of the binaries it can place in the image.
106
107Where possible it is best to put as much as possible in the FIT, with binman
108used to deal with cases not covered by FIT. Examples include initial
109execution (since FIT itself does not have an executable header) and dealing
110with device boundaries, such as the read-only/read-write separation in SPI
111flash.
112
113For U-Boot, binman should not be used to create ad-hoc images in place of
114FIT.
115
116
117Relationship to mkimage
118-----------------------
119
120The mkimage tool provides a means to create a FIT. Traditionally it has
121needed an image description file: a device tree, like binman, but in a
122different format. More recently it has started to support a '-f auto' mode
123which can generate that automatically.
124
125More relevant to binman, mkimage also permits creation of many SoC-specific
126image types. These can be listed by running 'mkimage -T list'. Examples
127include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often
128called from the U-Boot build system for this reason.
129
130Binman considers the output files created by mkimage to be binary blobs
131which it can place in an image. Binman does not replace the mkimage tool or
132this purpose. It would be possible in some situations to create a new entry
133type for the images in mkimage, but this would not add functionality. It
134seems better to use the mkimage tool to generate binaries and avoid blurring
135the boundaries between building input files (mkimage) and packaging then
136into a final image (binman).
137
138
139Example use of binman in U-Boot
140-------------------------------
141
142Binman aims to replace some of the ad-hoc image creation in the U-Boot
143build system.
144
145Consider sunxi. It has the following steps:
146
1471. It uses a custom mksunxiboot tool to build an SPL image called
148sunxi-spl.bin. This should probably move into mkimage.
149
1502. It uses mkimage to package U-Boot into a legacy image file (so that it can
151hold the load and execution address) called u-boot.img.
152
1533. It builds a final output image called u-boot-sunxi-with-spl.bin which
154consists of sunxi-spl.bin, some padding and u-boot.img.
155
156Binman is intended to replace the last step. The U-Boot build system builds
157u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
158sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
159case, it would then create the image from the component parts.
160
161This simplifies the U-Boot Makefile somewhat, since various pieces of logic
162can be replaced by a call to binman.
163
164
165Example use of binman for x86
166-----------------------------
167
168In most cases x86 images have a lot of binary blobs, 'black-box' code
169provided by Intel which must be run for the platform to work. Typically
170these blobs are not relocatable and must be placed at fixed areas in the
171firmware image.
172
173Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
174BIOS, reference code and Intel ME binaries into a u-boot.rom file.
175
176Binman is intended to replace all of this, with ifdtool left to handle only
177the configuration of the Intel-format descriptor.
178
179
180Running binman
181--------------
182
183First install prerequisites, e.g.
184
185 sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
186 liblz4-tool
187
188Type:
189
190 binman build -b <board_name>
191
192to build an image for a board. The board name is the same name used when
193configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
194Binman assumes that the input files for the build are in ../b/<board_name>.
195
196Or you can specify this explicitly:
197
198 binman build -I <build_path>
199
200where <build_path> is the build directory containing the output of the U-Boot
201build.
202
203(Future work will make this more configurable)
204
205In either case, binman picks up the device tree file (u-boot.dtb) and looks
206for its instructions in the 'binman' node.
207
208Binman has a few other options which you can see by running 'binman -h'.
209
210
211Enabling binman for a board
212---------------------------
213
214At present binman is invoked from a rule in the main Makefile. Typically you
215will have a rule like:
216
217ifneq ($(CONFIG_ARCH_<something>),)
218u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
219 $(call if_changed,binman)
220endif
221
222This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
223that you need to produce. You can make it a target by adding it to ALL-y
224either in the main Makefile or in a config.mk file in your arch subdirectory.
225
226Once binman is executed it will pick up its instructions from a device-tree
227file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
228You can use other, more specific CONFIG options - see 'Automatic .dtsi
229inclusion' below.
230
231
232Image description format
233------------------------
234
235The binman node is called 'binman'. An example image description is shown
236below:
237
238 binman {
239 filename = "u-boot-sunxi-with-spl.bin";
240 pad-byte = <0xff>;
241 blob {
242 filename = "spl/sunxi-spl.bin";
243 };
244 u-boot {
245 offset = <CONFIG_SPL_PAD_TO>;
246 };
247 };
248
249
250This requests binman to create an image file called u-boot-sunxi-with-spl.bin
251consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
252normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
253padding comes from the fact that the second binary is placed at
254CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
255immediately follow the SPL binary.
256
257The binman node describes an image. The sub-nodes describe entries in the
258image. Each entry represents a region within the overall image. The name of
259the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
260provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
261
262Entries are normally placed into the image sequentially, one after the other.
263The image size is the total size of all entries. As you can see, you can
264specify the start offset of an entry using the 'offset' property.
265
266Note that due to a device tree requirement, all entries must have a unique
267name. If you want to put the same binary in the image multiple times, you can
268use any unique name, with the 'type' property providing the type.
269
270The attributes supported for entries are described below.
271
272offset:
273 This sets the offset of an entry within the image or section containing
274 it. The first byte of the image is normally at offset 0. If 'offset' is
275 not provided, binman sets it to the end of the previous region, or the
276 start of the image's entry area (normally 0) if there is no previous
277 region.
278
279align:
280 This sets the alignment of the entry. The entry offset is adjusted
281 so that the entry starts on an aligned boundary within the image. For
282 example 'align = <16>' means that the entry will start on a 16-byte
283 boundary. Alignment shold be a power of 2. If 'align' is not
284 provided, no alignment is performed.
285
286size:
287 This sets the size of the entry. The contents will be padded out to
288 this size. If this is not provided, it will be set to the size of the
289 contents.
290
291pad-before:
292 Padding before the contents of the entry. Normally this is 0, meaning
293 that the contents start at the beginning of the entry. This can be
294 offset the entry contents a little. Defaults to 0.
295
296pad-after:
297 Padding after the contents of the entry. Normally this is 0, meaning
298 that the entry ends at the last byte of content (unless adjusted by
299 other properties). This allows room to be created in the image for
300 this entry to expand later. Defaults to 0.
301
302align-size:
303 This sets the alignment of the entry size. For example, to ensure
304 that the size of an entry is a multiple of 64 bytes, set this to 64.
305 If 'align-size' is not provided, no alignment is performed.
306
307align-end:
308 This sets the alignment of the end of an entry. Some entries require
309 that they end on an alignment boundary, regardless of where they
310 start. This does not move the start of the entry, so the contents of
311 the entry will still start at the beginning. But there may be padding
312 at the end. If 'align-end' is not provided, no alignment is performed.
313
314filename:
315 For 'blob' types this provides the filename containing the binary to
316 put into the entry. If binman knows about the entry type (like
317 u-boot-bin), then there is no need to specify this.
318
319type:
320 Sets the type of an entry. This defaults to the entry name, but it is
321 possible to use any name, and then add (for example) 'type = "u-boot"'
322 to specify the type.
323
324offset-unset:
325 Indicates that the offset of this entry should not be set by placing
326 it immediately after the entry before. Instead, is set by another
327 entry which knows where this entry should go. When this boolean
328 property is present, binman will give an error if another entry does
329 not set the offset (with the GetOffsets() method).
330
331image-pos:
332 This cannot be set on entry (or at least it is ignored if it is), but
333 with the -u option, binman will set it to the absolute image position
334 for each entry. This makes it easy to find out exactly where the entry
335 ended up in the image, regardless of parent sections, etc.
336
337expand-size:
338 Expand the size of this entry to fit available space. This space is only
339 limited by the size of the image/section and the position of the next
340 entry.
341
342compress:
343 Sets the compression algortihm to use (for blobs only). See the entry
344 documentation for details.
345
346The attributes supported for images and sections are described below. Several
347are similar to those for entries.
348
349size:
350 Sets the image size in bytes, for example 'size = <0x100000>' for a
351 1MB image.
352
353offset:
354 This is similar to 'offset' in entries, setting the offset of a section
355 within the image or section containing it. The first byte of the section
356 is normally at offset 0. If 'offset' is not provided, binman sets it to
357 the end of the previous region, or the start of the image's entry area
358 (normally 0) if there is no previous region.
359
360align-size:
361 This sets the alignment of the image size. For example, to ensure
362 that the image ends on a 512-byte boundary, use 'align-size = <512>'.
363 If 'align-size' is not provided, no alignment is performed.
364
365pad-before:
366 This sets the padding before the image entries. The first entry will
367 be positioned after the padding. This defaults to 0.
368
369pad-after:
370 This sets the padding after the image entries. The padding will be
371 placed after the last entry. This defaults to 0.
372
373pad-byte:
374 This specifies the pad byte to use when padding in the image. It
375 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
376
377filename:
378 This specifies the image filename. It defaults to 'image.bin'.
379
380sort-by-offset:
381 This causes binman to reorder the entries as needed to make sure they
382 are in increasing positional order. This can be used when your entry
383 order may not match the positional order. A common situation is where
384 the 'offset' properties are set by CONFIG options, so their ordering is
385 not known a priori.
386
387 This is a boolean property so needs no value. To enable it, add a
388 line 'sort-by-offset;' to your description.
389
390multiple-images:
391 Normally only a single image is generated. To create more than one
392 image, put this property in the binman node. For example, this will
393 create image1.bin containing u-boot.bin, and image2.bin containing
394 both spl/u-boot-spl.bin and u-boot.bin:
395
396 binman {
397 multiple-images;
398 image1 {
399 u-boot {
400 };
401 };
402
403 image2 {
404 spl {
405 };
406 u-boot {
407 };
408 };
409 };
410
411end-at-4gb:
412 For x86 machines the ROM offsets start just before 4GB and extend
413 up so that the image finished at the 4GB boundary. This boolean
414 option can be enabled to support this. The image size must be
415 provided so that binman knows when the image should start. For an
416 8MB ROM, the offset of the first entry would be 0xfff80000 with
417 this option, instead of 0 without this option.
418
419skip-at-start:
420 This property specifies the entry offset of the first entry.
421
422 For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
423 offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
424 nor flash boot, 0x201000 for sd boot etc.
425
426 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
427 Image size != 4gb.
428
429Examples of the above options can be found in the tests. See the
430tools/binman/test directory.
431
432It is possible to have the same binary appear multiple times in the image,
433either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
434different name for each and specifying the type with the 'type' attribute.
435
436
437Sections and hierachical images
438-------------------------------
439
440Sometimes it is convenient to split an image into several pieces, each of which
441contains its own set of binaries. An example is a flash device where part of
442the image is read-only and part is read-write. We can set up sections for each
443of these, and place binaries in them independently. The image is still produced
444as a single output file.
445
446This feature provides a way of creating hierarchical images. For example here
447is an example image with two copies of U-Boot. One is read-only (ro), intended
448to be written only in the factory. Another is read-write (rw), so that it can be
449upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
450and can be programmed:
451
452 binman {
453 section@0 {
454 read-only;
455 name-prefix = "ro-";
456 size = <0x100000>;
457 u-boot {
458 };
459 };
460 section@1 {
461 name-prefix = "rw-";
462 size = <0x100000>;
463 u-boot {
464 };
465 };
466 };
467
468This image could be placed into a SPI flash chip, with the protection boundary
469set at 1MB.
470
471A few special properties are provided for sections:
472
473read-only:
474 Indicates that this section is read-only. This has no impact on binman's
475 operation, but his property can be read at run time.
476
477name-prefix:
478 This string is prepended to all the names of the binaries in the
479 section. In the example above, the 'u-boot' binaries which actually be
480 renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
481 distinguish binaries with otherwise identical names.
482
483
484Image Properties
485----------------
486
487Image nodes act like sections but also have a few extra properties:
488
489filename:
490 Output filename for the image. This defaults to image.bin (or in the
491 case of multiple images <nodename>.bin where <nodename> is the name of
492 the image node.
493
494allow-repack:
495 Create an image that can be repacked. With this option it is possible
496 to change anything in the image after it is created, including updating
497 the position and size of image components. By default this is not
498 permitted since it is not possibly to know whether this might violate a
499 constraint in the image description. For example, if a section has to
500 increase in size to hold a larger binary, that might cause the section
501 to fall out of its allow region (e.g. read-only portion of flash).
502
503 Adding this property causes the original offset and size values in the
504 image description to be stored in the FDT and fdtmap.
505
506
507Entry Documentation
508-------------------
509
510For details on the various entry types supported by binman and how to use them,
511see README.entries. This is generated from the source code using:
512
513 binman entry-docs >tools/binman/README.entries
514
515
516Listing images
517--------------
518
519It is possible to list the entries in an existing firmware image created by
520binman, provided that there is an 'fdtmap' entry in the image. For example:
521
522 $ binman ls -i image.bin
523 Name Image-pos Size Entry-type Offset Uncomp-size
524 ----------------------------------------------------------------------
525 main-section c00 section 0
526 u-boot 0 4 u-boot 0
527 section 5fc section 4
528 cbfs 100 400 cbfs 0
529 u-boot 138 4 u-boot 38
530 u-boot-dtb 180 108 u-boot-dtb 80 3b5
531 u-boot-dtb 500 1ff u-boot-dtb 400 3b5
532 fdtmap 6fc 381 fdtmap 6fc
533 image-header bf8 8 image-header bf8
534
535This shows the hierarchy of the image, the position, size and type of each
536entry, the offset of each entry within its parent and the uncompressed size if
537the entry is compressed.
538
539It is also possible to list just some files in an image, e.g.
540
541 $ binman ls -i image.bin section/cbfs
542 Name Image-pos Size Entry-type Offset Uncomp-size
543 --------------------------------------------------------------------
544 cbfs 100 400 cbfs 0
545 u-boot 138 4 u-boot 38
546 u-boot-dtb 180 108 u-boot-dtb 80 3b5
547
548or with wildcards:
549
550 $ binman ls -i image.bin "*cb*" "*head*"
551 Name Image-pos Size Entry-type Offset Uncomp-size
552 ----------------------------------------------------------------------
553 cbfs 100 400 cbfs 0
554 u-boot 138 4 u-boot 38
555 u-boot-dtb 180 108 u-boot-dtb 80 3b5
556 image-header bf8 8 image-header bf8
557
558
559Extracting files from images
560----------------------------
561
562You can extract files from an existing firmware image created by binman,
563provided that there is an 'fdtmap' entry in the image. For example:
564
565 $ binman extract -i image.bin section/cbfs/u-boot
566
567which will write the uncompressed contents of that entry to the file 'u-boot' in
568the current directory. You can also extract to a particular file, in this case
569u-boot.bin:
570
571 $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin
572
573It is possible to extract all files into a destination directory, which will
574put files in subdirectories matching the entry hierarchy:
575
576 $ binman extract -i image.bin -O outdir
577
578or just a selection:
579
580 $ binman extract -i image.bin "*u-boot*" -O outdir
581
582
583Replacing files in an image
584---------------------------
585
586You can replace files in an existing firmware image created by binman, provided
587that there is an 'fdtmap' entry in the image. For example:
588
589 $ binman replace -i image.bin section/cbfs/u-boot
590
591which will write the contents of the file 'u-boot' from the current directory
592to the that entry, compressing if necessary. If the entry size changes, you must
593add the 'allow-repack' property to the original image before generating it (see
594above), otherwise you will get an error.
595
596You can also use a particular file, in this case u-boot.bin:
597
598 $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin
599
600It is possible to replace all files from a source directory which uses the same
601hierarchy as the entries:
602
603 $ binman replace -i image.bin -I indir
604
605Files that are missing will generate a warning.
606
607You can also replace just a selection of entries:
608
609 $ binman replace -i image.bin "*u-boot*" -I indir
610
611
612Logging
613-------
614
615Binman normally operates silently unless there is an error, in which case it
616just displays the error. The -D/--debug option can be used to create a full
617backtrace when errors occur.
618
619Internally binman logs some output while it is running. This can be displayed
620by increasing the -v/--verbosity from the default of 1:
621
622 0: silent
623 1: warnings only
624 2: notices (important messages)
625 3: info about major operations
626 4: detailed information about each operation
627 5: debug (all output)
628
629
630Hashing Entries
631---------------
632
633It is possible to ask binman to hash the contents of an entry and write that
634value back to the device-tree node. For example:
635
636 binman {
637 u-boot {
638 hash {
639 algo = "sha256";
640 };
641 };
642 };
643
644Here, a new 'value' property will be written to the 'hash' node containing
645the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
646sections can be hased if desired, by adding the 'hash' node to the section.
647
648The has value can be chcked at runtime by hashing the data actually read and
649comparing this has to the value in the device tree.
650
651
652Order of image creation
653-----------------------
654
655Image creation proceeds in the following order, for each entry in the image.
656
6571. AddMissingProperties() - binman can add calculated values to the device
658tree as part of its processing, for example the offset and size of each
659entry. This method adds any properties associated with this, expanding the
660device tree as needed. These properties can have placeholder values which are
661set later by SetCalculatedProperties(). By that stage the size of sections
662cannot be changed (since it would cause the images to need to be repacked),
663but the correct values can be inserted.
664
6652. ProcessFdt() - process the device tree information as required by the
666particular entry. This may involve adding or deleting properties. If the
667processing is complete, this method should return True. If the processing
668cannot complete because it needs the ProcessFdt() method of another entry to
669run first, this method should return False, in which case it will be called
670again later.
671
6723. GetEntryContents() - the contents of each entry are obtained, normally by
673reading from a file. This calls the Entry.ObtainContents() to read the
674contents. The default version of Entry.ObtainContents() calls
675Entry.GetDefaultFilename() and then reads that file. So a common mechanism
676to select a file to read is to override that function in the subclass. The
677functions must return True when they have read the contents. Binman will
678retry calling the functions a few times if False is returned, allowing
679dependencies between the contents of different entries.
680
6814. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
682return a dict containing entries that need updating. The key should be the
683entry name and the value is a tuple (offset, size). This allows an entry to
684provide the offset and size for other entries. The default implementation
685of GetEntryOffsets() returns {}.
686
6875. PackEntries() - calls Entry.Pack() which figures out the offset and
688size of an entry. The 'current' image offset is passed in, and the function
689returns the offset immediately after the entry being packed. The default
690implementation of Pack() is usually sufficient.
691
6926. CheckSize() - checks that the contents of all the entries fits within
693the image size. If the image does not have a defined size, the size is set
694large enough to hold all the entries.
695
6967. CheckEntries() - checks that the entries do not overlap, nor extend
697outside the image.
698
6998. SetImagePos() - sets the image position of every entry. This is the absolute
700position 'image-pos', as opposed to 'offset' which is relative to the containing
701section. This must be done after all offsets are known, which is why it is quite
702late in the ordering.
703
7049. SetCalculatedProperties() - update any calculated properties in the device
705tree. This sets the correct 'offset' and 'size' vaues, for example.
706
70710. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
708The default implementatoin does nothing. This can be overriden to adjust the
709contents of an entry in some way. For example, it would be possible to create
710an entry containing a hash of the contents of some other entries. At this
711stage the offset and size of entries should not be adjusted unless absolutely
712necessary, since it requires a repack (going back to PackEntries()).
713
71411. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry
715has changed its size, then there is no alternative but to go back to step 5 and
716try again, repacking the entries with the updated size. ResetForPack() removes
717the fixed offset/size values added by binman, so that the packing can start from
718scratch.
719
72012. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
721See 'Access to binman entry offsets at run time' below for a description of
722what happens in this stage.
723
72413. BuildImage() - builds the image and writes it to a file
725
72614. WriteMap() - writes a text file containing a map of the image. This is the
727final step.
728
729
730Automatic .dtsi inclusion
731-------------------------
732
733It is sometimes inconvenient to add a 'binman' node to the .dts file for each
734board. This can be done by using #include to bring in a common file. Another
735approach supported by the U-Boot build system is to automatically include
736a common header. You can then put the binman node (and anything else that is
737specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
738file.
739
740Binman will search for the following files in arch/<arch>/dts:
741
742 <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
743 <CONFIG_SYS_SOC>-u-boot.dtsi
744 <CONFIG_SYS_CPU>-u-boot.dtsi
745 <CONFIG_SYS_VENDOR>-u-boot.dtsi
746 u-boot.dtsi
747
748U-Boot will only use the first one that it finds. If you need to include a
749more general file you can do that from the more specific file using #include.
750If you are having trouble figuring out what is going on, you can uncomment
751the 'warning' line in scripts/Makefile.lib to see what it has found:
752
753 # Uncomment for debugging
754 # This shows all the files that were considered and the one that we chose.
755 # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
756
757
758Access to binman entry offsets at run time (symbols)
759----------------------------------------------------
760
761Binman assembles images and determines where each entry is placed in the image.
762This information may be useful to U-Boot at run time. For example, in SPL it
763is useful to be able to find the location of U-Boot so that it can be executed
764when SPL is finished.
765
766Binman allows you to declare symbols in the SPL image which are filled in
767with their correct values during the build. For example:
768
769 binman_sym_declare(ulong, u_boot_any, image_pos);
770
771declares a ulong value which will be assigned to the image-pos of any U-Boot
772image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
773You can access this value with something like:
774
775 ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
776
777Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming
778that the whole image has been loaded, or is available in flash. You can then
779jump to that address to start U-Boot.
780
781At present this feature is only supported in SPL and TPL. In principle it is
782possible to fill in such symbols in U-Boot proper, as well, but a future C
783library is planned for this instead, to read from the device tree.
784
785As well as image-pos, it is possible to read the size of an entry and its
786offset (which is the start position of the entry within its parent).
787
788A small technical note: Binman automatically adds the base address of the image
789(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the
790image is loaded to its linked address, the value will be correct and actually
791point into the image.
792
793For example, say SPL is at the start of the image and linked to start at address
79480108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos
795for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded
796to 80108000, with SPL at 80108000 and U-Boot at 80110000.
797
798For x86 devices (with the end-at-4gb property) this base address is not added
799since it is assumed that images are XIP and the offsets already include the
800address.
801
802
803Access to binman entry offsets at run time (fdt)
804------------------------------------------------
805
806Binman can update the U-Boot FDT to include the final position and size of
807each entry in the images it processes. The option to enable this is -u and it
808causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
809are set correctly for every entry. Since it is not necessary to specify these in
810the image definition, binman calculates the final values and writes these to
811the device tree. These can be used by U-Boot at run-time to find the location
812of each entry.
813
814Alternatively, an FDT map entry can be used to add a special FDT containing
815just the information about the image. This is preceded by a magic string so can
816be located anywhere in the image. An image header (typically at the start or end
817of the image) can be used to point to the FDT map. See fdtmap and image-header
818entries for more information.
819
820
821Compression
822-----------
823
824Binman support compression for 'blob' entries (those of type 'blob' and
825derivatives). To enable this for an entry, add a 'compress' property:
826
827 blob {
828 filename = "datafile";
829 compress = "lz4";
830 };
831
832The entry will then contain the compressed data, using the 'lz4' compression
833algorithm. Currently this is the only one that is supported. The uncompressed
834size is written to the node in an 'uncomp-size' property, if -u is used.
835
836
837
838Map files
839---------
840
841The -m option causes binman to output a .map file for each image that it
842generates. This shows the offset and size of each entry. For example:
843
844 Offset Size Name
845 00000000 00000028 main-section
846 00000000 00000010 section@0
847 00000000 00000004 u-boot
848 00000010 00000010 section@1
849 00000000 00000004 u-boot
850
851This shows a hierarchical image with two sections, each with a single entry. The
852offsets of the sections are absolute hex byte offsets within the image. The
853offsets of the entries are relative to their respective sections. The size of
854each entry is also shown, in bytes (hex). The indentation shows the entries
855nested inside their sections.
856
857
858Passing command-line arguments to entries
859-----------------------------------------
860
861Sometimes it is useful to pass binman the value of an entry property from the
862command line. For example some entries need access to files and it is not
863always convenient to put these filenames in the image definition (device tree).
864
865The-a option supports this:
866
867 -a<prop>=<value>
868
869where
870
871 <prop> is the property to set
872 <value> is the value to set it to
873
874Not all properties can be provided this way. Only some entries support it,
875typically for filenames.
876
877
878External tools
879--------------
880
881Binman can make use of external command-line tools to handle processing of
882entry contents or to generate entry contents. These tools are executed using
883the 'tools' module's Run() method. The tools generally must exist on the PATH,
884but the --toolpath option can be used to specify additional search paths to
885use. This option can be specified multiple times to add more than one path.
886
887
888Code coverage
889-------------
890
891Binman is a critical tool and is designed to be very testable. Entry
892implementations target 100% test coverage. Run 'binman test -T' to check this.
893
894To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
895
896 $ sudo apt-get install python-coverage python3-coverage python-pytest
897
898
899Concurrent tests
900----------------
901
902Binman tries to run tests concurrently. This means that the tests make use of
903all available CPUs to run.
904
905 To enable this:
906
907 $ sudo apt-get install python-subunit python3-subunit
908
909Use '-P 1' to disable this. It is automatically disabled when code coverage is
910being used (-T) since they are incompatible.
911
912
913Debugging tests
914---------------
915
916Sometimes when debugging tests it is useful to keep the input and output
917directories so they can be examined later. Use -X or --test-preserve-dirs for
918this.
919
920
921Advanced Features / Technical docs
922----------------------------------
923
924The behaviour of entries is defined by the Entry class. All other entries are
925a subclass of this. An important subclass is Entry_blob which takes binary
926data from a file and places it in the entry. In fact most entry types are
927subclasses of Entry_blob.
928
929Each entry type is a separate file in the tools/binman/etype directory. Each
930file contains a class called Entry_<type> where <type> is the entry type.
931New entry types can be supported by adding new files in that directory.
932These will automatically be detected by binman when needed.
933
934Entry properties are documented in entry.py. The entry subclasses are free
935to change the values of properties to support special behaviour. For example,
936when Entry_blob loads a file, it sets content_size to the size of the file.
937Entry classes can adjust other entries. For example, an entry that knows
938where other entries should be positioned can set up those entries' offsets
939so they don't need to be set in the binman decription. It can also adjust
940entry contents.
941
942Most of the time such essoteric behaviour is not needed, but it can be
943essential for complex images.
944
945If you need to specify a particular device-tree compiler to use, you can define
946the DTC environment variable. This can be useful when the system dtc is too
947old.
948
949To enable a full backtrace and other debugging features in binman, pass
950BINMAN_DEBUG=1 to your build:
951
952 make qemu-x86_defconfig
953 make BINMAN_DEBUG=1
954
955To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which
956adds a -v<level> option to the call to binman:
957
958 make qemu-x86_defconfig
959 make BINMAN_VERBOSE=5
960
961
962History / Credits
963-----------------
964
965Binman takes a lot of inspiration from a Chrome OS tool called
966'cros_bundle_firmware', which I wrote some years ago. That tool was based on
967a reasonably simple and sound design but has expanded greatly over the
968years. In particular its handling of x86 images is convoluted.
969
970Quite a few lessons have been learned which are hopefully applied here.
971
972
973Design notes
974------------
975
976On the face of it, a tool to create firmware images should be fairly simple:
977just find all the input binaries and place them at the right place in the
978image. The difficulty comes from the wide variety of input types (simple
979flat binaries containing code, packaged data with various headers), packing
980requirments (alignment, spacing, device boundaries) and other required
981features such as hierarchical images.
982
983The design challenge is to make it easy to create simple images, while
984allowing the more complex cases to be supported. For example, for most
985images we don't much care exactly where each binary ends up, so we should
986not have to specify that unnecessarily.
987
988New entry types should aim to provide simple usage where possible. If new
989core features are needed, they can be added in the Entry base class.
990
991
992To do
993-----
994
995Some ideas:
996- Use of-platdata to make the information available to code that is unable
997 to use device tree (such as a very small SPL image)
998- Allow easy building of images by specifying just the board name
999- Support building an image for a board (-b) more completely, with a
1000 configurable build directory
1001- Support adding FITs to an image
1002- Support for ARM Trusted Firmware (ATF)
1003- Detect invalid properties in nodes
1004- Sort the fdtmap by offset
1005
1006--
1007Simon Glass <sjg@chromium.org>
10087/7/2016
1009
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 - compress: Compression algorithm to use:
23 none: No compression
24 lz4: Use lz4 compression (via 'lz4' command-line utility)
25
26This entry reads data from a file and places it in the entry. The
27default filename is often specified specified by the subclass. See for
28example the 'u_boot' entry which provides the filename 'u-boot.bin'.
29
30If compression is enabled, an extra 'uncomp-size' property is written to
31the node (if enabled with -u) which provides the uncompressed size of the
32data.
33
34
35
36Entry: blob-dtb: A blob that holds a device tree
37------------------------------------------------
38
39This is a blob containing a device tree. The contents of the blob are
40obtained from the list of available device-tree files, managed by the
41'state' module.
42
43
44
45Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
46-----------------------------------------------------------------------------------------
47
48Properties / Entry arguments:
49 - <xxx>-path: Filename containing the contents of this entry (optional,
50 defaults to 0)
51
52where <xxx> is the blob_fname argument to the constructor.
53
54This entry cannot be used directly. Instead, it is used as a parent class
55for another entry, which defined blob_fname. This parameter is used to
56set the entry-arg or property containing the filename. The entry-arg or
57property is in turn used to set the actual filename.
58
59See cros_ec_rw for an example of this.
60
61
62
63Entry: cbfs: Entry containing a Coreboot Filesystem (CBFS)
64----------------------------------------------------------
65
66A CBFS provides a way to group files into a group. It has a simple directory
67structure and allows the position of individual files to be set, since it is
68designed to support execute-in-place in an x86 SPI-flash device. Where XIP
69is not used, it supports compression and storing ELF files.
70
71CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
72
73The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:
74
75 cbfs {
76 size = <0x100000>;
77 u-boot {
78 cbfs-type = "raw";
79 };
80 u-boot-dtb {
81 cbfs-type = "raw";
82 };
83 };
84
85This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
86Note that the size is required since binman does not support calculating it.
87The contents of each entry is just what binman would normally provide if it
88were not a CBFS node. A blob type can be used to import arbitrary files as
89with the second subnode below:
90
91 cbfs {
92 size = <0x100000>;
93 u-boot {
94 cbfs-name = "BOOT";
95 cbfs-type = "raw";
96 };
97
98 dtb {
99 type = "blob";
100 filename = "u-boot.dtb";
101 cbfs-type = "raw";
102 cbfs-compress = "lz4";
103 cbfs-offset = <0x100000>;
104 };
105 };
106
107This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
108u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
109
110
111Properties supported in the top-level CBFS node:
112
113cbfs-arch:
114 Defaults to "x86", but you can specify the architecture if needed.
115
116
117Properties supported in the CBFS entry subnodes:
118
119cbfs-name:
120 This is the name of the file created in CBFS. It defaults to the entry
121 name (which is the node name), but you can override it with this
122 property.
123
124cbfs-type:
125 This is the CBFS file type. The following are supported:
126
127 raw:
128 This is a 'raw' file, although compression is supported. It can be
129 used to store any file in CBFS.
130
131 stage:
132 This is an ELF file that has been loaded (i.e. mapped to memory), so
133 appears in the CBFS as a flat binary. The input file must be an ELF
134 image, for example this puts "u-boot" (the ELF image) into a 'stage'
135 entry:
136
137 cbfs {
138 size = <0x100000>;
139 u-boot-elf {
140 cbfs-name = "BOOT";
141 cbfs-type = "stage";
142 };
143 };
144
145 You can use your own ELF file with something like:
146
147 cbfs {
148 size = <0x100000>;
149 something {
150 type = "blob";
151 filename = "cbfs-stage.elf";
152 cbfs-type = "stage";
153 };
154 };
155
156 As mentioned, the file is converted to a flat binary, so it is
157 equivalent to adding "u-boot.bin", for example, but with the load and
158 start addresses specified by the ELF. At present there is no option
159 to add a flat binary with a load/start address, similar to the
160 'add-flat-binary' option in cbfstool.
161
162cbfs-offset:
163 This is the offset of the file's data within the CBFS. It is used to
164 specify where the file should be placed in cases where a fixed position
165 is needed. Typical uses are for code which is not relocatable and must
166 execute in-place from a particular address. This works because SPI flash
167 is generally mapped into memory on x86 devices. The file header is
168 placed before this offset so that the data start lines up exactly with
169 the chosen offset. If this property is not provided, then the file is
170 placed in the next available spot.
171
172The current implementation supports only a subset of CBFS features. It does
173not support other file types (e.g. payload), adding multiple files (like the
174'files' entry with a pattern supported by binman), putting files at a
175particular offset in the CBFS and a few other things.
176
177Of course binman can create images containing multiple CBFSs, simply by
178defining these in the binman config:
179
180
181 binman {
182 size = <0x800000>;
183 cbfs {
184 offset = <0x100000>;
185 size = <0x100000>;
186 u-boot {
187 cbfs-type = "raw";
188 };
189 u-boot-dtb {
190 cbfs-type = "raw";
191 };
192 };
193
194 cbfs2 {
195 offset = <0x700000>;
196 size = <0x100000>;
197 u-boot {
198 cbfs-type = "raw";
199 };
200 u-boot-dtb {
201 cbfs-type = "raw";
202 };
203 image {
204 type = "blob";
205 filename = "image.jpg";
206 };
207 };
208 };
209
210This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
211both of size 1MB.
212
213
214
215Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
216--------------------------------------------------------------------------------
217
218Properties / Entry arguments:
219 - cros-ec-rw-path: Filename containing the EC image
220
221This entry holds a Chromium OS EC (embedded controller) image, for use in
222updating the EC on startup via software sync.
223
224
225
226Entry: fdtmap: An entry which contains an FDT map
227-------------------------------------------------
228
229Properties / Entry arguments:
230 None
231
232An FDT map is just a header followed by an FDT containing a list of all the
233entries in the image. The root node corresponds to the image node in the
234original FDT, and an image-name property indicates the image name in that
235original tree.
236
237The header is the string _FDTMAP_ followed by 8 unused bytes.
238
239When used, this entry will be populated with an FDT map which reflects the
240entries in the current image. Hierarchy is preserved, and all offsets and
241sizes are included.
242
243Note that the -u option must be provided to ensure that binman updates the
244FDT with the position of each entry.
245
246Example output for a simple image with U-Boot and an FDT map:
247
248/ {
249 image-name = "binman";
250 size = <0x00000112>;
251 image-pos = <0x00000000>;
252 offset = <0x00000000>;
253 u-boot {
254 size = <0x00000004>;
255 image-pos = <0x00000000>;
256 offset = <0x00000000>;
257 };
258 fdtmap {
259 size = <0x0000010e>;
260 image-pos = <0x00000004>;
261 offset = <0x00000004>;
262 };
263};
264
265If allow-repack is used then 'orig-offset' and 'orig-size' properties are
266added as necessary. See the binman README.
267
268
269
270Entry: files: Entry containing a set of files
271---------------------------------------------
272
273Properties / Entry arguments:
274 - pattern: Filename pattern to match the files to include
275 - compress: Compression algorithm to use:
276 none: No compression
277 lz4: Use lz4 compression (via 'lz4' command-line utility)
278
279This entry reads a number of files and places each in a separate sub-entry
280within this entry. To access these you need to enable device-tree updates
281at run-time so you can obtain the file positions.
282
283
284
285Entry: fill: An entry which is filled to a particular byte value
286----------------------------------------------------------------
287
288Properties / Entry arguments:
289 - fill-byte: Byte to use to fill the entry
290
291Note that the size property must be set since otherwise this entry does not
292know how large it should be.
293
294You can often achieve the same effect using the pad-byte property of the
295overall image, in that the space between entries will then be padded with
296that byte. But this entry is sometimes useful for explicitly setting the
297byte value of a region.
298
299
300
301Entry: fmap: An entry which contains an Fmap section
302----------------------------------------------------
303
304Properties / Entry arguments:
305 None
306
307FMAP is a simple format used by flashrom, an open-source utility for
308reading and writing the SPI flash, typically on x86 CPUs. The format
309provides flashrom with a list of areas, so it knows what it in the flash.
310It can then read or write just a single area, instead of the whole flash.
311
312The format is defined by the flashrom project, in the file lib/fmap.h -
313see www.flashrom.org/Flashrom for more information.
314
315When used, this entry will be populated with an FMAP which reflects the
316entries in the current image. Note that any hierarchy is squashed, since
317FMAP does not support this. Also, CBFS entries appear as a single entry -
318the sub-entries are ignored.
319
320
321
322Entry: gbb: An entry which contains a Chromium OS Google Binary Block
323---------------------------------------------------------------------
324
325Properties / Entry arguments:
326 - hardware-id: Hardware ID to use for this build (a string)
327 - keydir: Directory containing the public keys to use
328 - bmpblk: Filename containing images used by recovery
329
330Chromium OS uses a GBB to store various pieces of information, in particular
331the root and recovery keys that are used to verify the boot process. Some
332more details are here:
333
334 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
335
336but note that the page dates from 2013 so is quite out of date. See
337README.chromium for how to obtain the required keys and tools.
338
339
340
341Entry: image-header: An entry which contains a pointer to the FDT map
342---------------------------------------------------------------------
343
344Properties / Entry arguments:
345 location: Location of header ("start" or "end" of image). This is
346 optional. If omitted then the entry must have an offset property.
347
348This adds an 8-byte entry to the start or end of the image, pointing to the
349location of the FDT map. The format is a magic number followed by an offset
350from the start or end of the image, in twos-compliment format.
351
352This entry must be in the top-level part of the image.
353
354NOTE: If the location is at the start/end, you will probably need to specify
355sort-by-offset for the image, unless you actually put the image header
356first/last in the entry list.
357
358
359
360Entry: intel-cmc: Entry containing an Intel Chipset Micro Code (CMC) file
361-------------------------------------------------------------------------
362
363Properties / Entry arguments:
364 - filename: Filename of file to read into entry
365
366This file contains microcode for some devices in a special format. An
367example filename is 'Microcode/C0_22211.BIN'.
368
369See README.x86 for information about x86 binary blobs.
370
371
372
373Entry: intel-descriptor: Intel flash descriptor block (4KB)
374-----------------------------------------------------------
375
376Properties / Entry arguments:
377 filename: Filename of file containing the descriptor. This is typically
378 a 4KB binary file, sometimes called 'descriptor.bin'
379
380This entry is placed at the start of flash and provides information about
381the SPI flash regions. In particular it provides the base address and
382size of the ME (Management Engine) region, allowing us to place the ME
383binary in the right place.
384
385With this entry in your image, the position of the 'intel-me' entry will be
386fixed in the image, which avoids you needed to specify an offset for that
387region. This is useful, because it is not possible to change the position
388of the ME region without updating the descriptor.
389
390See README.x86 for information about x86 binary blobs.
391
392
393
394Entry: intel-fit: Intel Firmware Image Table (FIT)
395--------------------------------------------------
396
397This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
398contains information about the firmware and microcode available in the
399image.
400
401At present binman only supports a basic FIT with no microcode.
402
403
404
405Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
406--------------------------------------------------------------
407
408This entry contains a pointer to the FIT. It is required to be at address
4090xffffffc0 in the image.
410
411
412
413Entry: intel-fsp: Entry containing an Intel Firmware Support Package (FSP) file
414-------------------------------------------------------------------------------
415
416Properties / Entry arguments:
417 - filename: Filename of file to read into entry
418
419This file contains binary blobs which are used on some devices to make the
420platform work. U-Boot executes this code since it is not possible to set up
421the hardware using U-Boot open-source code. Documentation is typically not
422available in sufficient detail to allow this.
423
424An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
425
426See README.x86 for information about x86 binary blobs.
427
428
429
430Entry: intel-fsp-m: Entry containing Intel Firmware Support Package (FSP) memory init
431-------------------------------------------------------------------------------------
432
433Properties / Entry arguments:
434 - filename: Filename of file to read into entry
435
436This file contains a binary blob which is used on some devices to set up
437SDRAM. U-Boot executes this code in SPL so that it can make full use of
438memory. Documentation is typically not available in sufficient detail to
439allow U-Boot do this this itself..
440
441An example filename is 'fsp_m.bin'
442
443See README.x86 for information about x86 binary blobs.
444
445
446
447Entry: intel-fsp-s: Entry containing Intel Firmware Support Package (FSP) silicon init
448--------------------------------------------------------------------------------------
449
450Properties / Entry arguments:
451 - filename: Filename of file to read into entry
452
453This file contains a binary blob which is used on some devices to set up
454the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
455running, so that it can make full use of memory. Documentation is typically
456not available in sufficient detail to allow U-Boot do this this itself.
457
458An example filename is 'fsp_s.bin'
459
460See README.x86 for information about x86 binary blobs.
461
462
463
464Entry: intel-fsp-t: Entry containing Intel Firmware Support Package (FSP) temp ram init
465---------------------------------------------------------------------------------------
466
467Properties / Entry arguments:
468 - filename: Filename of file to read into entry
469
470This file contains a binary blob which is used on some devices to set up
471temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
472that it has access to memory for its stack and initial storage.
473
474An example filename is 'fsp_t.bin'
475
476See README.x86 for information about x86 binary blobs.
477
478
479
480Entry: intel-ifwi: Entry containing an Intel Integrated Firmware Image (IFWI) file
481----------------------------------------------------------------------------------
482
483Properties / Entry arguments:
484 - filename: Filename of file to read into entry. This is either the
485 IFWI file itself, or a file that can be converted into one using a
486 tool
487 - convert-fit: If present this indicates that the ifwitool should be
488 used to convert the provided file into a IFWI.
489
490This file contains code and data used by the SoC that is required to make
491it work. It includes U-Boot TPL, microcode, things related to the CSE
492(Converged Security Engine, the microcontroller that loads all the firmware)
493and other items beyond the wit of man.
494
495A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
496file that will be converted to an IFWI.
497
498The position of this entry is generally set by the intel-descriptor entry.
499
500The contents of the IFWI are specified by the subnodes of the IFWI node.
501Each subnode describes an entry which is placed into the IFWFI with a given
502sub-partition (and optional entry name).
503
504Properties for subnodes:
505 ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP"
506 ifwi-entry - entry name t use, e.g. "IBBL"
507 ifwi-replace - if present, indicates that the item should be replaced
508 in the IFWI. Otherwise it is added.
509
510See README.x86 for information about x86 binary blobs.
511
512
513
514Entry: intel-me: Entry containing an Intel Management Engine (ME) file
515----------------------------------------------------------------------
516
517Properties / Entry arguments:
518 - filename: Filename of file to read into entry
519
520This file contains code used by the SoC that is required to make it work.
521The Management Engine is like a background task that runs things that are
522not clearly documented, but may include keyboard, display and network
523access. For platform that use ME it is not possible to disable it. U-Boot
524does not directly execute code in the ME binary.
525
526A typical filename is 'me.bin'.
527
528The position of this entry is generally set by the intel-descriptor entry.
529
530See README.x86 for information about x86 binary blobs.
531
532
533
534Entry: intel-mrc: Entry containing an Intel Memory Reference Code (MRC) file
535----------------------------------------------------------------------------
536
537Properties / Entry arguments:
538 - filename: Filename of file to read into entry
539
540This file contains code for setting up the SDRAM on some Intel systems. This
541is executed by U-Boot when needed early during startup. A typical filename
542is 'mrc.bin'.
543
544See README.x86 for information about x86 binary blobs.
545
546
547
548Entry: intel-refcode: Entry containing an Intel Reference Code file
549-------------------------------------------------------------------
550
551Properties / Entry arguments:
552 - filename: Filename of file to read into entry
553
554This file contains code for setting up the platform on some Intel systems.
555This is executed by U-Boot when needed early during startup. A typical
556filename is 'refcode.bin'.
557
558See README.x86 for information about x86 binary blobs.
559
560
561
562Entry: intel-vbt: Entry containing an Intel Video BIOS Table (VBT) file
563-----------------------------------------------------------------------
564
565Properties / Entry arguments:
566 - filename: Filename of file to read into entry
567
568This file contains code that sets up the integrated graphics subsystem on
569some Intel SoCs. U-Boot executes this when the display is started up.
570
571See README.x86 for information about Intel binary blobs.
572
573
574
575Entry: intel-vga: Entry containing an Intel Video Graphics Adaptor (VGA) file
576-----------------------------------------------------------------------------
577
578Properties / Entry arguments:
579 - filename: Filename of file to read into entry
580
581This file contains code that sets up the integrated graphics subsystem on
582some Intel SoCs. U-Boot executes this when the display is started up.
583
584This is similar to the VBT file but in a different format.
585
586See README.x86 for information about Intel binary blobs.
587
588
589
590Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
591-----------------------------------------------------------------------------------------
592
593Properties / Entry arguments:
594 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
595
596This entry is valid for PowerPC mpc85xx cpus. This entry holds
597'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
598placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
599
600
601
602Entry: section: Entry that contains other entries
603-------------------------------------------------
604
605Properties / Entry arguments: (see binman README for more information)
606 pad-byte: Pad byte to use when padding
607 sort-by-offset: True if entries should be sorted by offset, False if
608 they must be in-order in the device tree description
609 end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)
610 skip-at-start: Number of bytes before the first entry starts. These
611 effectively adjust the starting offset of entries. For example,
612 if this is 16, then the first entry would start at 16. An entry
613 with offset = 20 would in fact be written at offset 4 in the image
614 file, since the first 16 bytes are skipped when writing.
615 name-prefix: Adds a prefix to the name of every entry in the section
616 when writing out the map
617
618Since a section is also an entry, it inherits all the properies of entries
619too.
620
621A section is an entry which can contain other entries, thus allowing
622hierarchical images to be created. See 'Sections and hierarchical images'
623in the binman README for more information.
624
625
626
627Entry: text: An entry which contains text
628-----------------------------------------
629
630The text can be provided either in the node itself or by a command-line
631argument. There is a level of indirection to allow multiple text strings
632and sharing of text.
633
634Properties / Entry arguments:
635 text-label: The value of this string indicates the property / entry-arg
636 that contains the string to place in the entry
637 <xxx> (actual name is the value of text-label): contains the string to
638 place in the entry.
639 <text>: The text to place in the entry (overrides the above mechanism).
640 This is useful when the text is constant.
641
642Example node:
643
644 text {
645 size = <50>;
646 text-label = "message";
647 };
648
649You can then use:
650
651 binman -amessage="this is my message"
652
653and binman will insert that string into the entry.
654
655It is also possible to put the string directly in the node:
656
657 text {
658 size = <8>;
659 text-label = "message";
660 message = "a message directly in the node"
661 };
662
663or just:
664
665 text {
666 size = <8>;
667 text = "some text directly in the node"
668 };
669
670The text is not itself nul-terminated. This can be achieved, if required,
671by setting the size of the entry to something larger than the text.
672
673
674
675Entry: u-boot: U-Boot flat binary
676---------------------------------
677
678Properties / Entry arguments:
679 - filename: Filename of u-boot.bin (default 'u-boot.bin')
680
681This is the U-Boot binary, containing relocation information to allow it
682to relocate itself at runtime. The binary typically includes a device tree
683blob at the end of it. Use u_boot_nodtb if you want to package the device
684tree separately.
685
686U-Boot can access binman symbols at runtime. See:
687
688 'Access to binman entry offsets at run time (fdt)'
689
690in the binman README for more information.
691
692
693
694Entry: u-boot-dtb: U-Boot device tree
695-------------------------------------
696
697Properties / Entry arguments:
698 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
699
700This is the U-Boot device tree, containing configuration information for
701U-Boot. U-Boot needs this to know what devices are present and which drivers
702to activate.
703
704Note: This is mostly an internal entry type, used by others. This allows
705binman to know which entries contain a device tree.
706
707
708
709Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
710-----------------------------------------------------------------------------------
711
712Properties / Entry arguments:
713 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
714
715See Entry_u_boot_ucode for full details of the three entries involved in
716this process. This entry provides the U-Boot device-tree file, which
717contains the microcode. If the microcode is not being collated into one
718place then the offset and size of the microcode is recorded by this entry,
719for use by u_boot_with_ucode_ptr. If it is being collated, then this
720entry deletes the microcode from the device tree (to save space) and makes
721it available to u_boot_ucode.
722
723
724
725Entry: u-boot-elf: U-Boot ELF image
726-----------------------------------
727
728Properties / Entry arguments:
729 - filename: Filename of u-boot (default 'u-boot')
730
731This is the U-Boot ELF image. It does not include a device tree but can be
732relocated to any address for execution.
733
734
735
736Entry: u-boot-img: U-Boot legacy image
737--------------------------------------
738
739Properties / Entry arguments:
740 - filename: Filename of u-boot.img (default 'u-boot.img')
741
742This is the U-Boot binary as a packaged image, in legacy format. It has a
743header which allows it to be loaded at the correct address for execution.
744
745You should use FIT (Flat Image Tree) instead of the legacy image for new
746applications.
747
748
749
750Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
751--------------------------------------------------------------------
752
753Properties / Entry arguments:
754 - filename: Filename of u-boot.bin (default 'u-boot-nodtb.bin')
755
756This is the U-Boot binary, containing relocation information to allow it
757to relocate itself at runtime. It does not include a device tree blob at
758the end of it so normally cannot work without it. You can add a u_boot_dtb
759entry after this one, or use a u_boot entry instead (which contains both
760U-Boot and the device tree).
761
762
763
764Entry: u-boot-spl: U-Boot SPL binary
765------------------------------------
766
767Properties / Entry arguments:
768 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
769
770This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
771binary which loads before U-Boot proper, typically into on-chip SRAM. It is
772responsible for locating, loading and jumping to U-Boot. Note that SPL is
773not relocatable so must be loaded to the correct address in SRAM, or written
774to run from the correct address if direct flash execution is possible (e.g.
775on x86 devices).
776
777SPL can access binman symbols at runtime. See:
778
779 'Access to binman entry offsets at run time (symbols)'
780
781in the binman README for more information.
782
783The ELF file 'spl/u-boot-spl' must also be available for this to work, since
784binman uses that to look up symbols to write into the SPL binary.
785
786
787
788Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
789---------------------------------------------------------------------
790
791Properties / Entry arguments:
792 None
793
794This is similar to u_boot_spl except that padding is added after the SPL
795binary to cover the BSS (Block Started by Symbol) region. This region holds
796the various used by SPL. It is set to 0 by SPL when it starts up. If you
797want to append data to the SPL image (such as a device tree file), you must
798pad out the BSS region to avoid the data overlapping with U-Boot variables.
799This entry is useful in that case. It automatically pads out the entry size
800to cover both the code, data and BSS.
801
802The ELF file 'spl/u-boot-spl' must also be available for this to work, since
803binman uses that to look up the BSS address.
804
805
806
807Entry: u-boot-spl-dtb: U-Boot SPL device tree
808---------------------------------------------
809
810Properties / Entry arguments:
811 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
812
813This is the SPL device tree, containing configuration information for
814SPL. SPL needs this to know what devices are present and which drivers
815to activate.
816
817
818
819Entry: u-boot-spl-elf: U-Boot SPL ELF image
820-------------------------------------------
821
822Properties / Entry arguments:
823 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
824
825This is the U-Boot SPL ELF image. It does not include a device tree but can
826be relocated to any address for execution.
827
828
829
830Entry: u-boot-spl-nodtb: SPL binary without device tree appended
831----------------------------------------------------------------
832
833Properties / Entry arguments:
834 - filename: Filename of spl/u-boot-spl-nodtb.bin (default
835 'spl/u-boot-spl-nodtb.bin')
836
837This is the U-Boot SPL binary, It does not include a device tree blob at
838the end of it so may not be able to work without it, assuming SPL needs
839a device tree to operation on your platform. You can add a u_boot_spl_dtb
840entry after this one, or use a u_boot_spl entry instead (which contains
841both SPL and the device tree).
842
843
844
845Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
846----------------------------------------------------------------------------
847
848This is used when SPL must set up the microcode for U-Boot.
849
850See Entry_u_boot_ucode for full details of the entries involved in this
851process.
852
853
854
855Entry: u-boot-tpl: U-Boot TPL binary
856------------------------------------
857
858Properties / Entry arguments:
859 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
860
861This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
862binary which loads before SPL, typically into on-chip SRAM. It is
863responsible for locating, loading and jumping to SPL, the next-stage
864loader. Note that SPL is not relocatable so must be loaded to the correct
865address in SRAM, or written to run from the correct address if direct
866flash execution is possible (e.g. on x86 devices).
867
868SPL can access binman symbols at runtime. See:
869
870 'Access to binman entry offsets at run time (symbols)'
871
872in the binman README for more information.
873
874The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
875binman uses that to look up symbols to write into the TPL binary.
876
877
878
879Entry: u-boot-tpl-dtb: U-Boot TPL device tree
880---------------------------------------------
881
882Properties / Entry arguments:
883 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
884
885This is the TPL device tree, containing configuration information for
886TPL. TPL needs this to know what devices are present and which drivers
887to activate.
888
889
890
891Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
892----------------------------------------------------------------------------
893
894This is used when TPL must set up the microcode for U-Boot.
895
896See Entry_u_boot_ucode for full details of the entries involved in this
897process.
898
899
900
901Entry: u-boot-tpl-elf: U-Boot TPL ELF image
902-------------------------------------------
903
904Properties / Entry arguments:
905 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
906
907This is the U-Boot TPL ELF image. It does not include a device tree but can
908be relocated to any address for execution.
909
910
911
912Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
913----------------------------------------------------------------------------
914
915See Entry_u_boot_ucode for full details of the entries involved in this
916process.
917
918
919
920Entry: u-boot-ucode: U-Boot microcode block
921-------------------------------------------
922
923Properties / Entry arguments:
924 None
925
926The contents of this entry are filled in automatically by other entries
927which must also be in the image.
928
929U-Boot on x86 needs a single block of microcode. This is collected from
930the various microcode update nodes in the device tree. It is also unable
931to read the microcode from the device tree on platforms that use FSP
932(Firmware Support Package) binaries, because the API requires that the
933microcode is supplied before there is any SRAM available to use (i.e.
934the FSP sets up the SRAM / cache-as-RAM but does so in the call that
935requires the microcode!). To keep things simple, all x86 platforms handle
936microcode the same way in U-Boot (even non-FSP platforms). This is that
937a table is placed at _dt_ucode_base_size containing the base address and
938size of the microcode. This is either passed to the FSP (for FSP
939platforms), or used to set up the microcode (for non-FSP platforms).
940This all happens in the build system since it is the only way to get
941the microcode into a single blob and accessible without SRAM.
942
943There are two cases to handle. If there is only one microcode blob in
944the device tree, then the ucode pointer it set to point to that. This
945entry (u-boot-ucode) is empty. If there is more than one update, then
946this entry holds the concatenation of all updates, and the device tree
947entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
948last step ensures that that the microcode appears in one contiguous
949block in the image and is not unnecessarily duplicated in the device
950tree. It is referred to as 'collation' here.
951
952Entry types that have a part to play in handling microcode:
953
954 Entry_u_boot_with_ucode_ptr:
955 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
956 It updates it with the address and size of the microcode so that
957 U-Boot can find it early on start-up.
958 Entry_u_boot_dtb_with_ucode:
959 Contains u-boot.dtb. It stores the microcode in a
960 'self.ucode_data' property, which is then read by this class to
961 obtain the microcode if needed. If collation is performed, it
962 removes the microcode from the device tree.
963 Entry_u_boot_ucode:
964 This class. If collation is enabled it reads the microcode from
965 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
966 contents of this entry.
967
968
969
970Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
971--------------------------------------------------------------------
972
973Properties / Entry arguments:
974 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
975 - optional-ucode: boolean property to make microcode optional. If the
976 u-boot.bin image does not include microcode, no error will
977 be generated.
978
979See Entry_u_boot_ucode for full details of the three entries involved in
980this process. This entry updates U-Boot with the offset and size of the
981microcode, to allow early x86 boot code to find it without doing anything
982complicated. Otherwise it is the same as the u_boot entry.
983
984
985
986Entry: vblock: An entry which contains a Chromium OS verified boot block
987------------------------------------------------------------------------
988
989Properties / Entry arguments:
990 - content: List of phandles to entries to sign
991 - keydir: Directory containing the public keys to use
992 - keyblock: Name of the key file to use (inside keydir)
993 - signprivate: Name of provide key file to use (inside keydir)
994 - version: Version number of the vblock (typically 1)
995 - kernelkey: Name of the kernel key to use (inside keydir)
996 - preamble-flags: Value of the vboot preamble flags (typically 0)
997
998Output files:
999 - input.<unique_name> - input file passed to futility
1000 - vblock.<unique_name> - output file generated by futility (which is
1001 used as the entry contents)
1002
1003Chromium OS signs the read-write firmware and kernel, writing the signature
1004in this block. This allows U-Boot to verify that the next firmware stage
1005and kernel are genuine.
1006
1007
1008
1009Entry: x86-reset16: x86 16-bit reset code for U-Boot
1010----------------------------------------------------
1011
1012Properties / Entry arguments:
1013 - filename: Filename of u-boot-x86-reset16.bin (default
1014 'u-boot-x86-reset16.bin')
1015
1016x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1017must be placed at a particular address. This entry holds that code. It is
1018typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
1019for jumping to the x86-start16 code, which continues execution.
1020
1021For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
1022
1023
1024
1025Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
1026--------------------------------------------------------
1027
1028Properties / Entry arguments:
1029 - filename: Filename of u-boot-x86-reset16.bin (default
1030 'u-boot-x86-reset16.bin')
1031
1032x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1033must be placed at a particular address. This entry holds that code. It is
1034typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
1035for jumping to the x86-start16 code, which continues execution.
1036
1037For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
1038
1039
1040
1041Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
1042--------------------------------------------------------
1043
1044Properties / Entry arguments:
1045 - filename: Filename of u-boot-x86-reset16.bin (default
1046 'u-boot-x86-reset16.bin')
1047
1048x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1049must be placed at a particular address. This entry holds that code. It is
1050typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
1051for jumping to the x86-start16 code, which continues execution.
1052
1053For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
1054
1055
1056
1057Entry: x86-start16: x86 16-bit start-up code for U-Boot
1058-------------------------------------------------------
1059
1060Properties / Entry arguments:
1061 - filename: Filename of u-boot-x86-start16.bin (default
1062 'u-boot-x86-start16.bin')
1063
1064x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1065must be placed in the top 64KB of the ROM. The reset code jumps to it. This
1066entry holds that code. It is typically placed at offset
1067CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
1068and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
1069U-Boot).
1070
1071For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
1072
1073
1074
1075Entry: x86-start16-spl: x86 16-bit start-up code for SPL
1076--------------------------------------------------------
1077
1078Properties / Entry arguments:
1079 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
1080 'spl/u-boot-x86-start16-spl.bin')
1081
1082x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1083must be placed in the top 64KB of the ROM. The reset code jumps to it. This
1084entry holds that code. It is typically placed at offset
1085CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
1086and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
1087U-Boot).
1088
1089For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
1090
1091
1092
1093Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
1094--------------------------------------------------------
1095
1096Properties / Entry arguments:
1097 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
1098 'tpl/u-boot-x86-start16-tpl.bin')
1099
1100x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
1101must be placed in the top 64KB of the ROM. The reset code jumps to it. This
1102entry holds that code. It is typically placed at offset
1103CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
1104and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
1105U-Boot).
1106
1107If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
1108may be used instead.
1109
1110
1111
1112