they are included, by adding a Python plug-in. The device tree is available
to U-Boot at run-time so that the images can be interpreted.
-Binman does not yet update the device tree with the final location of
-everything when it is done. A simple C structure could be generated for
-constrained environments like SPL (using dtoc) but this is also not
-implemented.
+Binman can update the device tree with the final location of everything when it
+is done. Entry positions can be provided to U-Boot SPL as run-time symbols,
+avoiding device-tree code overhead.
Binman can also support incorporating filesystems in the image if required.
For example x86 platforms may use CBFS in some cases.
Binman considers the output files created by mkimage to be binary blobs
which it can place in an image. Binman does not replace the mkimage tool or
-this purpose. It would be possible in some situtions to create a new entry
+this purpose. It would be possible in some situations to create a new entry
type for the images in mkimage, but this would not add functionality. It
-seems better to use the mkiamge tool to generate binaries and avoid blurring
+seems better to use the mkimage tool to generate binaries and avoid blurring
the boundaries between building input files (mkimage) and packaging then
into a final image (binman).
In most cases x86 images have a lot of binary blobs, 'black-box' code
provided by Intel which must be run for the platform to work. Typically
these blobs are not relocatable and must be placed at fixed areas in the
-firmare image.
+firmware image.
Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
BIOS, reference code and Intel ME binaries into a u-boot.rom file.
Running binman
--------------
+First install prerequisites, e.g.
+
+ sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
+ liblz4-tool
+
Type:
- binman -b <board_name>
+ binman build -b <board_name>
to build an image for a board. The board name is the same name used when
configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
Or you can specify this explicitly:
- binman -I <build_path>
+ binman build -I <build_path>
where <build_path> is the build directory containing the output of the U-Boot
build.
filename = "spl/sunxi-spl.bin";
};
u-boot {
- pos = <CONFIG_SPL_PAD_TO>;
+ offset = <CONFIG_SPL_PAD_TO>;
};
};
Entries are normally placed into the image sequentially, one after the other.
The image size is the total size of all entries. As you can see, you can
-specify the start position of an entry using the 'pos' property.
+specify the start offset of an entry using the 'offset' property.
Note that due to a device tree requirement, all entries must have a unique
name. If you want to put the same binary in the image multiple times, you can
The attributes supported for entries are described below.
-pos:
- This sets the position of an entry within the image. The first byte
- of the image is normally at position 0. If 'pos' is not provided,
- binman sets it to the end of the previous region, or the start of
- the image's entry area (normally 0) if there is no previous region.
+offset:
+ This sets the offset of an entry within the image or section containing
+ it. The first byte of the image is normally at offset 0. If 'offset' is
+ not provided, binman sets it to the end of the previous region, or the
+ start of the image's entry area (normally 0) if there is no previous
+ region.
align:
- This sets the alignment of the entry. The entry position is adjusted
+ This sets the alignment of the entry. The entry offset is adjusted
so that the entry starts on an aligned boundary within the image. For
example 'align = <16>' means that the entry will start on a 16-byte
boundary. Alignment shold be a power of 2. If 'align' is not
align-end:
This sets the alignment of the end of an entry. Some entries require
that they end on an alignment boundary, regardless of where they
- start. If 'align-end' is not provided, no alignment is performed.
-
- Note: This is not yet implemented in binman.
+ start. This does not move the start of the entry, so the contents of
+ the entry will still start at the beginning. But there may be padding
+ at the end. If 'align-end' is not provided, no alignment is performed.
filename:
For 'blob' types this provides the filename containing the binary to
possible to use any name, and then add (for example) 'type = "u-boot"'
to specify the type.
-pos-unset:
- Indicates that the position of this entry should not be set by placing
+offset-unset:
+ Indicates that the offset of this entry should not be set by placing
it immediately after the entry before. Instead, is set by another
entry which knows where this entry should go. When this boolean
property is present, binman will give an error if another entry does
- not set the position (with the GetPositions() method).
+ not set the offset (with the GetOffsets() method).
+
+image-pos:
+ This cannot be set on entry (or at least it is ignored if it is), but
+ with the -u option, binman will set it to the absolute image position
+ for each entry. This makes it easy to find out exactly where the entry
+ ended up in the image, regardless of parent sections, etc.
+expand-size:
+ Expand the size of this entry to fit available space. This space is only
+ limited by the size of the image/section and the position of the next
+ entry.
-The attributes supported for images are described below. Several are similar
-to those for entries.
+compress:
+ Sets the compression algortihm to use (for blobs only). See the entry
+ documentation for details.
+
+The attributes supported for images and sections are described below. Several
+are similar to those for entries.
size:
Sets the image size in bytes, for example 'size = <0x100000>' for a
1MB image.
+offset:
+ This is similar to 'offset' in entries, setting the offset of a section
+ within the image or section containing it. The first byte of the section
+ is normally at offset 0. If 'offset' is not provided, binman sets it to
+ the end of the previous region, or the start of the image's entry area
+ (normally 0) if there is no previous region.
+
align-size:
This sets the alignment of the image size. For example, to ensure
that the image ends on a 512-byte boundary, use 'align-size = <512>'.
pad-before:
This sets the padding before the image entries. The first entry will
- be positionad after the padding. This defaults to 0.
+ be positioned after the padding. This defaults to 0.
pad-after:
This sets the padding after the image entries. The padding will be
filename:
This specifies the image filename. It defaults to 'image.bin'.
-sort-by-pos:
+sort-by-offset:
This causes binman to reorder the entries as needed to make sure they
are in increasing positional order. This can be used when your entry
order may not match the positional order. A common situation is where
- the 'pos' properties are set by CONFIG options, so their ordering is
+ the 'offset' properties are set by CONFIG options, so their ordering is
not known a priori.
This is a boolean property so needs no value. To enable it, add a
- line 'sort-by-pos;' to your description.
+ line 'sort-by-offset;' to your description.
multiple-images:
Normally only a single image is generated. To create more than one
};
end-at-4gb:
- For x86 machines the ROM positions start just before 4GB and extend
+ For x86 machines the ROM offsets start just before 4GB and extend
up so that the image finished at the 4GB boundary. This boolean
option can be enabled to support this. The image size must be
provided so that binman knows when the image should start. For an
- 8MB ROM, the position of the first entry would be 0xfff80000 with
+ 8MB ROM, the offset of the first entry would be 0xfff80000 with
this option, instead of 0 without this option.
+skip-at-start:
+ This property specifies the entry offset of the first entry.
+
+ For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
+ offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
+ nor flash boot, 0x201000 for sd boot etc.
+
+ 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
+ Image size != 4gb.
Examples of the above options can be found in the tests. See the
tools/binman/test directory.
different name for each and specifying the type with the 'type' attribute.
-Sections and hiearchical images
+Sections and hierachical images
-------------------------------
Sometimes it is convenient to split an image into several pieces, each of which
as a single output file.
This feature provides a way of creating hierarchical images. For example here
-is an example with two copies of U-Boot. One is read-only (ro), intended to be
-written only in the factory. Another is read-write (rw), so that it can be
+is an example image with two copies of U-Boot. One is read-only (ro), intended
+to be written only in the factory. Another is read-write (rw), so that it can be
upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
and can be programmed:
binman {
section@0 {
read-only;
+ name-prefix = "ro-";
size = <0x100000>;
u-boot {
};
};
section@1 {
+ name-prefix = "rw-";
size = <0x100000>;
u-boot {
};
Indicates that this section is read-only. This has no impact on binman's
operation, but his property can be read at run time.
+name-prefix:
+ This string is prepended to all the names of the binaries in the
+ section. In the example above, the 'u-boot' binaries which actually be
+ renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
+ distinguish binaries with otherwise identical names.
+
+
+Image Properties
+----------------
+
+Image nodes act like sections but also have a few extra properties:
+
+filename:
+ Output filename for the image. This defaults to image.bin (or in the
+ case of multiple images <nodename>.bin where <nodename> is the name of
+ the image node.
+
+allow-repack:
+ Create an image that can be repacked. With this option it is possible
+ to change anything in the image after it is created, including updating
+ the position and size of image components. By default this is not
+ permitted since it is not possibly to know whether this might violate a
+ constraint in the image description. For example, if a section has to
+ increase in size to hold a larger binary, that might cause the section
+ to fall out of its allow region (e.g. read-only portion of flash).
+
+ Adding this property causes the original offset and size values in the
+ image description to be stored in the FDT and fdtmap.
+
+
+Entry Documentation
+-------------------
+
+For details on the various entry types supported by binman and how to use them,
+see README.entries. This is generated from the source code using:
+
+ binman entry-docs >tools/binman/README.entries
+
+
+Listing images
+--------------
+
+It is possible to list the entries in an existing firmware image created by
+binman, provided that there is an 'fdtmap' entry in the image. For example:
+
+ $ binman ls -i image.bin
+ Name Image-pos Size Entry-type Offset Uncomp-size
+ ----------------------------------------------------------------------
+ main-section c00 section 0
+ u-boot 0 4 u-boot 0
+ section 5fc section 4
+ cbfs 100 400 cbfs 0
+ u-boot 138 4 u-boot 38
+ u-boot-dtb 180 108 u-boot-dtb 80 3b5
+ u-boot-dtb 500 1ff u-boot-dtb 400 3b5
+ fdtmap 6fc 381 fdtmap 6fc
+ image-header bf8 8 image-header bf8
+
+This shows the hierarchy of the image, the position, size and type of each
+entry, the offset of each entry within its parent and the uncompressed size if
+the entry is compressed.
+
+It is also possible to list just some files in an image, e.g.
+
+ $ binman ls -i image.bin section/cbfs
+ Name Image-pos Size Entry-type Offset Uncomp-size
+ --------------------------------------------------------------------
+ cbfs 100 400 cbfs 0
+ u-boot 138 4 u-boot 38
+ u-boot-dtb 180 108 u-boot-dtb 80 3b5
+
+or with wildcards:
+
+ $ binman ls -i image.bin "*cb*" "*head*"
+ Name Image-pos Size Entry-type Offset Uncomp-size
+ ----------------------------------------------------------------------
+ cbfs 100 400 cbfs 0
+ u-boot 138 4 u-boot 38
+ u-boot-dtb 180 108 u-boot-dtb 80 3b5
+ image-header bf8 8 image-header bf8
+
+
+Extracting files from images
+----------------------------
+
+You can extract files from an existing firmware image created by binman,
+provided that there is an 'fdtmap' entry in the image. For example:
+
+ $ binman extract -i image.bin section/cbfs/u-boot
+
+which will write the uncompressed contents of that entry to the file 'u-boot' in
+the current directory. You can also extract to a particular file, in this case
+u-boot.bin:
+
+ $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin
+
+It is possible to extract all files into a destination directory, which will
+put files in subdirectories matching the entry hierarchy:
+
+ $ binman extract -i image.bin -O outdir
+
+or just a selection:
+
+ $ binman extract -i image.bin "*u-boot*" -O outdir
+
+
+Replacing files in an image
+---------------------------
+
+You can replace files in an existing firmware image created by binman, provided
+that there is an 'fdtmap' entry in the image. For example:
+
+ $ binman replace -i image.bin section/cbfs/u-boot
+
+which will write the contents of the file 'u-boot' from the current directory
+to the that entry, compressing if necessary. If the entry size changes, you must
+add the 'allow-repack' property to the original image before generating it (see
+above), otherwise you will get an error.
+
+You can also use a particular file, in this case u-boot.bin:
+
+ $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin
+
+It is possible to replace all files from a source directory which uses the same
+hierarchy as the entries:
+
+ $ binman replace -i image.bin -I indir
+
+Files that are missing will generate a warning.
+
+You can also replace just a selection of entries:
+
+ $ binman replace -i image.bin "*u-boot*" -I indir
+
+
+Logging
+-------
+
+Binman normally operates silently unless there is an error, in which case it
+just displays the error. The -D/--debug option can be used to create a full
+backtrace when errors occur.
-Special properties
-------------------
+Internally binman logs some output while it is running. This can be displayed
+by increasing the -v/--verbosity from the default of 1:
-Some entries support special properties, documented here:
+ 0: silent
+ 1: warnings only
+ 2: notices (important messages)
+ 3: info about major operations
+ 4: detailed information about each operation
+ 5: debug (all output)
-u-boot-with-ucode-ptr:
- optional-ucode: boolean property to make microcode optional. If the
- u-boot.bin image does not include microcode, no error will
- be generated.
+
+Hashing Entries
+---------------
+
+It is possible to ask binman to hash the contents of an entry and write that
+value back to the device-tree node. For example:
+
+ binman {
+ u-boot {
+ hash {
+ algo = "sha256";
+ };
+ };
+ };
+
+Here, a new 'value' property will be written to the 'hash' node containing
+the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
+sections can be hased if desired, by adding the 'hash' node to the section.
+
+The has value can be chcked at runtime by hashing the data actually read and
+comparing this has to the value in the device tree.
Order of image creation
Image creation proceeds in the following order, for each entry in the image.
-1. GetEntryContents() - the contents of each entry are obtained, normally by
+1. AddMissingProperties() - binman can add calculated values to the device
+tree as part of its processing, for example the offset and size of each
+entry. This method adds any properties associated with this, expanding the
+device tree as needed. These properties can have placeholder values which are
+set later by SetCalculatedProperties(). By that stage the size of sections
+cannot be changed (since it would cause the images to need to be repacked),
+but the correct values can be inserted.
+
+2. ProcessFdt() - process the device tree information as required by the
+particular entry. This may involve adding or deleting properties. If the
+processing is complete, this method should return True. If the processing
+cannot complete because it needs the ProcessFdt() method of another entry to
+run first, this method should return False, in which case it will be called
+again later.
+
+3. GetEntryContents() - the contents of each entry are obtained, normally by
reading from a file. This calls the Entry.ObtainContents() to read the
contents. The default version of Entry.ObtainContents() calls
Entry.GetDefaultFilename() and then reads that file. So a common mechanism
retry calling the functions a few times if False is returned, allowing
dependencies between the contents of different entries.
-2. GetEntryPositions() - calls Entry.GetPositions() for each entry. This can
+4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
return a dict containing entries that need updating. The key should be the
-entry name and the value is a tuple (pos, size). This allows an entry to
-provide the position and size for other entries. The default implementation
-of GetEntryPositions() returns {}.
+entry name and the value is a tuple (offset, size). This allows an entry to
+provide the offset and size for other entries. The default implementation
+of GetEntryOffsets() returns {}.
-3. PackEntries() - calls Entry.Pack() which figures out the position and
-size of an entry. The 'current' image position is passed in, and the function
-returns the position immediately after the entry being packed. The default
+5. PackEntries() - calls Entry.Pack() which figures out the offset and
+size of an entry. The 'current' image offset is passed in, and the function
+returns the offset immediately after the entry being packed. The default
implementation of Pack() is usually sufficient.
-4. CheckSize() - checks that the contents of all the entries fits within
+6. CheckSize() - checks that the contents of all the entries fits within
the image size. If the image does not have a defined size, the size is set
large enough to hold all the entries.
-5. CheckEntries() - checks that the entries do not overlap, nor extend
+7. CheckEntries() - checks that the entries do not overlap, nor extend
outside the image.
-6. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
+8. SetImagePos() - sets the image position of every entry. This is the absolute
+position 'image-pos', as opposed to 'offset' which is relative to the containing
+section. This must be done after all offsets are known, which is why it is quite
+late in the ordering.
+
+9. SetCalculatedProperties() - update any calculated properties in the device
+tree. This sets the correct 'offset' and 'size' vaues, for example.
+
+10. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
The default implementatoin does nothing. This can be overriden to adjust the
contents of an entry in some way. For example, it would be possible to create
an entry containing a hash of the contents of some other entries. At this
-stage the position and size of entries should not be adjusted.
+stage the offset and size of entries should not be adjusted unless absolutely
+necessary, since it requires a repack (going back to PackEntries()).
+
+11. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry
+has changed its size, then there is no alternative but to go back to step 5 and
+try again, repacking the entries with the updated size. ResetForPack() removes
+the fixed offset/size values added by binman, so that the packing can start from
+scratch.
+
+12. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
+See 'Access to binman entry offsets at run time' below for a description of
+what happens in this stage.
-6. WriteEntryInfo()
+13. BuildImage() - builds the image and writes it to a file
-7. BuildImage() - builds the image and writes it to a file. This is the final
-step.
+14. WriteMap() - writes a text file containing a map of the image. This is the
+final step.
Automatic .dtsi inclusion
# u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
-Access to binman entry positions at run time
---------------------------------------------
+Access to binman entry offsets at run time (symbols)
+----------------------------------------------------
Binman assembles images and determines where each entry is placed in the image.
This information may be useful to U-Boot at run time. For example, in SPL it
Binman allows you to declare symbols in the SPL image which are filled in
with their correct values during the build. For example:
- binman_sym_declare(ulong, u_boot_any, pos);
+ binman_sym_declare(ulong, u_boot_any, offset);
-declares a ulong value which will be assigned to the position of any U-Boot
+declares a ulong value which will be assigned to the offset of any U-Boot
image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
You can access this value with something like:
- ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
+ ulong u_boot_offset = binman_sym(ulong, u_boot_any, offset);
-Thus u_boot_pos will be set to the position of U-Boot in memory, assuming that
+Thus u_boot_offset will be set to the offset of U-Boot in memory, assuming that
the whole image has been loaded, or is available in flash. You can then jump to
that address to start U-Boot.
to fill in such symbols in U-Boot proper, as well.
+Access to binman entry offsets at run time (fdt)
+------------------------------------------------
+
+Binman can update the U-Boot FDT to include the final position and size of
+each entry in the images it processes. The option to enable this is -u and it
+causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
+are set correctly for every entry. Since it is not necessary to specify these in
+the image definition, binman calculates the final values and writes these to
+the device tree. These can be used by U-Boot at run-time to find the location
+of each entry.
+
+Alternatively, an FDT map entry can be used to add a special FDT containing
+just the information about the image. This is preceded by a magic string so can
+be located anywhere in the image. An image header (typically at the start or end
+of the image) can be used to point to the FDT map. See fdtmap and image-header
+entries for more information.
+
+
+Compression
+-----------
+
+Binman support compression for 'blob' entries (those of type 'blob' and
+derivatives). To enable this for an entry, add a 'compress' property:
+
+ blob {
+ filename = "datafile";
+ compress = "lz4";
+ };
+
+The entry will then contain the compressed data, using the 'lz4' compression
+algorithm. Currently this is the only one that is supported. The uncompressed
+size is written to the node in an 'uncomp-size' property, if -u is used.
+
+
+
+Map files
+---------
+
+The -m option causes binman to output a .map file for each image that it
+generates. This shows the offset and size of each entry. For example:
+
+ Offset Size Name
+ 00000000 00000028 main-section
+ 00000000 00000010 section@0
+ 00000000 00000004 u-boot
+ 00000010 00000010 section@1
+ 00000000 00000004 u-boot
+
+This shows a hierarchical image with two sections, each with a single entry. The
+offsets of the sections are absolute hex byte offsets within the image. The
+offsets of the entries are relative to their respective sections. The size of
+each entry is also shown, in bytes (hex). The indentation shows the entries
+nested inside their sections.
+
+
+Passing command-line arguments to entries
+-----------------------------------------
+
+Sometimes it is useful to pass binman the value of an entry property from the
+command line. For example some entries need access to files and it is not
+always convenient to put these filenames in the image definition (device tree).
+
+The-a option supports this:
+
+ -a<prop>=<value>
+
+where
+
+ <prop> is the property to set
+ <value> is the value to set it to
+
+Not all properties can be provided this way. Only some entries support it,
+typically for filenames.
+
+
+External tools
+--------------
+
+Binman can make use of external command-line tools to handle processing of
+entry contents or to generate entry contents. These tools are executed using
+the 'tools' module's Run() method. The tools generally must exist on the PATH,
+but the --toolpath option can be used to specify additional search paths to
+use. This option can be specified multiple times to add more than one path.
+
+
Code coverage
-------------
Binman is a critical tool and is designed to be very testable. Entry
-implementations target 100% test coverage. Run 'binman -T' to check this.
+implementations target 100% test coverage. Run 'binman test -T' to check this.
To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
- $ sudo apt-get install python-pip python-pytest
- $ sudo pip install coverage
+ $ sudo apt-get install python-coverage python3-coverage python-pytest
+
+
+Concurrent tests
+----------------
+
+Binman tries to run tests concurrently. This means that the tests make use of
+all available CPUs to run.
+
+ To enable this:
+
+ $ sudo apt-get install python-subunit python3-subunit
+
+Use '-P 1' to disable this. It is automatically disabled when code coverage is
+being used (-T) since they are incompatible.
+
+
+Debugging tests
+---------------
+
+Sometimes when debugging tests it is useful to keep the input and output
+directories so they can be examined later. Use -X or --test-preserve-dirs for
+this.
Advanced Features / Technical docs
to change the values of properties to support special behaviour. For example,
when Entry_blob loads a file, it sets content_size to the size of the file.
Entry classes can adjust other entries. For example, an entry that knows
-where other entries should be positioned can set up those entries' positions
+where other entries should be positioned can set up those entries' offsets
so they don't need to be set in the binman decription. It can also adjust
entry contents.
the DTC environment variable. This can be useful when the system dtc is too
old.
+To enable a full backtrace and other debugging features in binman, pass
+BINMAN_DEBUG=1 to your build:
+
+ make sandbox_defconfig
+ make BINMAN_DEBUG=1
+
+To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which
+adds a -v<level> option to the call to binman:
+
+ make sandbox_defconfig
+ make BINMAN_VERBOSE=5
+
History / Credits
-----------------
a reasonably simple and sound design but has expanded greatly over the
years. In particular its handling of x86 images is convoluted.
-Quite a few lessons have been learned which are hopefully be applied here.
+Quite a few lessons have been learned which are hopefully applied here.
Design notes
-----
Some ideas:
-- Fill out the device tree to include the final position and size of each
- entry (since the input file may not always specify these). See also
- 'Access to binman entry positions at run time' above
- Use of-platdata to make the information available to code that is unable
to use device tree (such as a very small SPL image)
-- Write an image map to a text file
- Allow easy building of images by specifying just the board name
-- Produce a full Python binding for libfdt (for upstream)
-- Add an option to decode an image into the constituent binaries
- Support building an image for a board (-b) more completely, with a
configurable build directory
-- Consider making binman work with buildman, although if it is used in the
- Makefile, this will be automatic
-- Implement align-end
+- Support adding FITs to an image
+- Support for ARM Trusted Firmware (ATF)
+- Detect invalid properties in nodes
+- Sort the fdtmap by offset
--
Simon Glass <sjg@chromium.org>
projects / oweals / u-boot.git / blobdiff