|
@@ -1,5 +1,5 @@
|
|
|
-# SPDX-License-Identifier: GPL-2.0+
|
|
|
-# Copyright (c) 2016 Google, Inc
|
|
|
+.. SPDX-License-Identifier: GPL-2.0+
|
|
|
+.. Copyright (c) 2016 Google, Inc
|
|
|
|
|
|
Introduction
|
|
|
------------
|
|
@@ -67,18 +67,19 @@ standard format, we can support making valid images for any board without
|
|
|
manual effort, lots of READMEs, etc.
|
|
|
|
|
|
Benefits:
|
|
|
-- Each binary can have its own build system and tool chain without creating
|
|
|
-any dependencies between them
|
|
|
-- Avoids the need for a single-shot build: individual parts can be updated
|
|
|
-and brought in as needed
|
|
|
-- Provides for a standard image description available in the build and at
|
|
|
-run-time
|
|
|
-- SoC-specific image-signing tools can be accommodated
|
|
|
-- Avoids cluttering the U-Boot build system with image-building code
|
|
|
-- The image description is automatically available at run-time in U-Boot,
|
|
|
-SPL. It can be made available to other software also
|
|
|
-- The image description is easily readable (it's a text file in device-tree
|
|
|
-format) and permits flexible packing of binaries
|
|
|
+
|
|
|
+ - Each binary can have its own build system and tool chain without creating
|
|
|
+ any dependencies between them
|
|
|
+ - Avoids the need for a single-shot build: individual parts can be updated
|
|
|
+ and brought in as needed
|
|
|
+ - Provides for a standard image description available in the build and at
|
|
|
+ run-time
|
|
|
+ - SoC-specific image-signing tools can be accommodated
|
|
|
+ - Avoids cluttering the U-Boot build system with image-building code
|
|
|
+ - The image description is automatically available at run-time in U-Boot,
|
|
|
+ SPL. It can be made available to other software also
|
|
|
+ - The image description is easily readable (it's a text file in device-tree
|
|
|
+ format) and permits flexible packing of binaries
|
|
|
|
|
|
|
|
|
Terminology
|
|
@@ -144,14 +145,14 @@ build system.
|
|
|
|
|
|
Consider sunxi. It has the following steps:
|
|
|
|
|
|
-1. It uses a custom mksunxiboot tool to build an SPL image called
|
|
|
-sunxi-spl.bin. This should probably move into mkimage.
|
|
|
+ #. It uses a custom mksunxiboot tool to build an SPL image called
|
|
|
+ sunxi-spl.bin. This should probably move into mkimage.
|
|
|
|
|
|
-2. It uses mkimage to package U-Boot into a legacy image file (so that it can
|
|
|
-hold the load and execution address) called u-boot.img.
|
|
|
+ #. It uses mkimage to package U-Boot into a legacy image file (so that it can
|
|
|
+ hold the load and execution address) called u-boot.img.
|
|
|
|
|
|
-3. It builds a final output image called u-boot-sunxi-with-spl.bin which
|
|
|
-consists of sunxi-spl.bin, some padding and u-boot.img.
|
|
|
+ #. It builds a final output image called u-boot-sunxi-with-spl.bin which
|
|
|
+ consists of sunxi-spl.bin, some padding and u-boot.img.
|
|
|
|
|
|
Binman is intended to replace the last step. The U-Boot build system builds
|
|
|
u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
|
|
@@ -180,22 +181,22 @@ the configuration of the Intel-format descriptor.
|
|
|
Running binman
|
|
|
--------------
|
|
|
|
|
|
-First install prerequisites, e.g.
|
|
|
+First install prerequisites, e.g::
|
|
|
|
|
|
- sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
|
|
|
- liblz4-tool
|
|
|
+ sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
|
|
|
+ liblz4-tool
|
|
|
|
|
|
-Type:
|
|
|
+Type::
|
|
|
|
|
|
- binman build -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').
|
|
|
Binman assumes that the input files for the build are in ../b/<board_name>.
|
|
|
|
|
|
-Or you can specify this explicitly:
|
|
|
+Or you can specify this explicitly::
|
|
|
|
|
|
- binman build -I <build_path>
|
|
|
+ binman build -I <build_path>
|
|
|
|
|
|
where <build_path> is the build directory containing the output of the U-Boot
|
|
|
build.
|
|
@@ -212,12 +213,12 @@ Enabling binman for a board
|
|
|
---------------------------
|
|
|
|
|
|
At present binman is invoked from a rule in the main Makefile. Typically you
|
|
|
-will have a rule like:
|
|
|
+will have a rule like::
|
|
|
|
|
|
-ifneq ($(CONFIG_ARCH_<something>),)
|
|
|
-u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
|
|
|
- $(call if_changed,binman)
|
|
|
-endif
|
|
|
+ ifneq ($(CONFIG_ARCH_<something>),)
|
|
|
+ u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
|
|
|
+ $(call if_changed,binman)
|
|
|
+ endif
|
|
|
|
|
|
This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
|
|
|
that you need to produce. You can make it a target by adding it to INPUTS-y
|
|
@@ -233,18 +234,18 @@ Image description format
|
|
|
------------------------
|
|
|
|
|
|
The binman node is called 'binman'. An example image description is shown
|
|
|
-below:
|
|
|
+below::
|
|
|
|
|
|
- binman {
|
|
|
- filename = "u-boot-sunxi-with-spl.bin";
|
|
|
- pad-byte = <0xff>;
|
|
|
- blob {
|
|
|
- filename = "spl/sunxi-spl.bin";
|
|
|
- };
|
|
|
- u-boot {
|
|
|
- offset = <CONFIG_SPL_PAD_TO>;
|
|
|
- };
|
|
|
- };
|
|
|
+ binman {
|
|
|
+ filename = "u-boot-sunxi-with-spl.bin";
|
|
|
+ pad-byte = <0xff>;
|
|
|
+ blob {
|
|
|
+ filename = "spl/sunxi-spl.bin";
|
|
|
+ };
|
|
|
+ u-boot {
|
|
|
+ offset = <CONFIG_SPL_PAD_TO>;
|
|
|
+ };
|
|
|
+ };
|
|
|
|
|
|
|
|
|
This requests binman to create an image file called u-boot-sunxi-with-spl.bin
|
|
@@ -270,184 +271,184 @@ use any unique name, with the 'type' property providing the type.
|
|
|
The attributes supported for entries are described below.
|
|
|
|
|
|
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.
|
|
|
+ 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 offset is adjusted
|
|
|
- so that the entry starts on an aligned boundary within the containing
|
|
|
- section or image. For example 'align = <16>' means that the entry will
|
|
|
- start on a 16-byte boundary. This may mean that padding is added before
|
|
|
- the entry. The padding is part of the containing section but is not
|
|
|
- included in the entry, meaning that an empty space may be created before
|
|
|
- the entry starts. Alignment should be a power of 2. If 'align' is not
|
|
|
- provided, no alignment is performed.
|
|
|
+ This sets the alignment of the entry. The entry offset is adjusted
|
|
|
+ so that the entry starts on an aligned boundary within the containing
|
|
|
+ section or image. For example 'align = <16>' means that the entry will
|
|
|
+ start on a 16-byte boundary. This may mean that padding is added before
|
|
|
+ the entry. The padding is part of the containing section but is not
|
|
|
+ included in the entry, meaning that an empty space may be created before
|
|
|
+ the entry starts. Alignment should be a power of 2. If 'align' is not
|
|
|
+ provided, no alignment is performed.
|
|
|
|
|
|
size:
|
|
|
- This sets the size of the entry. The contents will be padded out to
|
|
|
- this size. If this is not provided, it will be set to the size of the
|
|
|
- contents.
|
|
|
+ This sets the size of the entry. The contents will be padded out to
|
|
|
+ this size. If this is not provided, it will be set to the size of the
|
|
|
+ contents.
|
|
|
|
|
|
pad-before:
|
|
|
- Padding before the contents of the entry. Normally this is 0, meaning
|
|
|
- that the contents start at the beginning of the entry. This can be used
|
|
|
- to offset the entry contents a little. While this does not affect the
|
|
|
- contents of the entry within binman itself (the padding is performed
|
|
|
- only when its parent section is assembled), the end result will be that
|
|
|
- the entry starts with the padding bytes, so may grow. Defaults to 0.
|
|
|
+ Padding before the contents of the entry. Normally this is 0, meaning
|
|
|
+ that the contents start at the beginning of the entry. This can be used
|
|
|
+ to offset the entry contents a little. While this does not affect the
|
|
|
+ contents of the entry within binman itself (the padding is performed
|
|
|
+ only when its parent section is assembled), the end result will be that
|
|
|
+ the entry starts with the padding bytes, so may grow. Defaults to 0.
|
|
|
|
|
|
pad-after:
|
|
|
- Padding after the contents of the entry. Normally this is 0, meaning
|
|
|
- that the entry ends at the last byte of content (unless adjusted by
|
|
|
- other properties). This allows room to be created in the image for
|
|
|
- this entry to expand later. While this does not affect the contents of
|
|
|
- the entry within binman itself (the padding is performed only when its
|
|
|
- parent section is assembled), the end result will be that the entry ends
|
|
|
- with the padding bytes, so may grow. Defaults to 0.
|
|
|
+ Padding after the contents of the entry. Normally this is 0, meaning
|
|
|
+ that the entry ends at the last byte of content (unless adjusted by
|
|
|
+ other properties). This allows room to be created in the image for
|
|
|
+ this entry to expand later. While this does not affect the contents of
|
|
|
+ the entry within binman itself (the padding is performed only when its
|
|
|
+ parent section is assembled), the end result will be that the entry ends
|
|
|
+ with the padding bytes, so may grow. Defaults to 0.
|
|
|
|
|
|
align-size:
|
|
|
- This sets the alignment of the entry size. For example, to ensure
|
|
|
- that the size of an entry is a multiple of 64 bytes, set this to 64.
|
|
|
- While this does not affect the contents of the entry within binman
|
|
|
- itself (the padding is performed only when its parent section is
|
|
|
- assembled), the end result is that the entry ends with the padding
|
|
|
- bytes, so may grow. If 'align-size' is not provided, no alignment is
|
|
|
- performed.
|
|
|
+ This sets the alignment of the entry size. For example, to ensure
|
|
|
+ that the size of an entry is a multiple of 64 bytes, set this to 64.
|
|
|
+ While this does not affect the contents of the entry within binman
|
|
|
+ itself (the padding is performed only when its parent section is
|
|
|
+ assembled), the end result is that the entry ends with the padding
|
|
|
+ bytes, so may grow. If 'align-size' is not provided, no alignment is
|
|
|
+ performed.
|
|
|
|
|
|
align-end:
|
|
|
- This sets the alignment of the end of an entry with respect to the
|
|
|
- containing section. Some entries require that they end on an alignment
|
|
|
- boundary, regardless of where they 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. While this does not
|
|
|
- affect the contents of the entry within binman itself (the padding is
|
|
|
- performed only when its parent section is assembled), the end result
|
|
|
- is that the entry ends with the padding bytes, so may grow.
|
|
|
- If 'align-end' is not provided, no alignment is performed.
|
|
|
+ This sets the alignment of the end of an entry with respect to the
|
|
|
+ containing section. Some entries require that they end on an alignment
|
|
|
+ boundary, regardless of where they 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. While this does not
|
|
|
+ affect the contents of the entry within binman itself (the padding is
|
|
|
+ performed only when its parent section is assembled), the end result
|
|
|
+ is that the entry ends with the padding bytes, so may grow.
|
|
|
+ If 'align-end' is not provided, no alignment is performed.
|
|
|
|
|
|
filename:
|
|
|
- For 'blob' types this provides the filename containing the binary to
|
|
|
- put into the entry. If binman knows about the entry type (like
|
|
|
- u-boot-bin), then there is no need to specify this.
|
|
|
+ For 'blob' types this provides the filename containing the binary to
|
|
|
+ put into the entry. If binman knows about the entry type (like
|
|
|
+ u-boot-bin), then there is no need to specify this.
|
|
|
|
|
|
type:
|
|
|
- Sets the type of an entry. This defaults to the entry name, but it is
|
|
|
- possible to use any name, and then add (for example) 'type = "u-boot"'
|
|
|
- to specify the type.
|
|
|
+ Sets the type of an entry. This defaults to the entry name, but it is
|
|
|
+ possible to use any name, and then add (for example) 'type = "u-boot"'
|
|
|
+ to specify the type.
|
|
|
|
|
|
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 offset (with the GetOffsets() method).
|
|
|
+ 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 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.
|
|
|
+ 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.
|
|
|
+ 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.
|
|
|
|
|
|
compress:
|
|
|
- Sets the compression algortihm to use (for blobs only). See the entry
|
|
|
- documentation for details.
|
|
|
+ Sets the compression algortihm to use (for blobs only). See the entry
|
|
|
+ documentation for details.
|
|
|
|
|
|
missing-msg:
|
|
|
- Sets the tag of the message to show if this entry is missing. This is
|
|
|
- used for external blobs. When they are missing it is helpful to show
|
|
|
- information about what needs to be fixed. See missing-blob-help for the
|
|
|
- message for each tag.
|
|
|
+ Sets the tag of the message to show if this entry is missing. This is
|
|
|
+ used for external blobs. When they are missing it is helpful to show
|
|
|
+ information about what needs to be fixed. See missing-blob-help for the
|
|
|
+ message for each tag.
|
|
|
|
|
|
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.
|
|
|
+ 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.
|
|
|
+ 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>'.
|
|
|
- If 'align-size' is not provided, no alignment is performed.
|
|
|
+ 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>'.
|
|
|
+ If 'align-size' is not provided, no alignment is performed.
|
|
|
|
|
|
pad-before:
|
|
|
- This sets the padding before the image entries. The first entry will
|
|
|
- be positioned after the padding. This defaults to 0.
|
|
|
+ This sets the padding before the image entries. The first entry will
|
|
|
+ be positioned after the padding. This defaults to 0.
|
|
|
|
|
|
pad-after:
|
|
|
- This sets the padding after the image entries. The padding will be
|
|
|
- placed after the last entry. This defaults to 0.
|
|
|
+ This sets the padding after the image entries. The padding will be
|
|
|
+ placed after the last entry. This defaults to 0.
|
|
|
|
|
|
pad-byte:
|
|
|
- This specifies the pad byte to use when padding in the image. It
|
|
|
- defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
|
|
|
+ This specifies the pad byte to use when padding in the image. It
|
|
|
+ defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
|
|
|
|
|
|
filename:
|
|
|
- This specifies the image filename. It defaults to 'image.bin'.
|
|
|
+ This specifies the image filename. It defaults to 'image.bin'.
|
|
|
|
|
|
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 'offset' properties are set by CONFIG options, so their ordering is
|
|
|
- not known a priori.
|
|
|
+ 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 '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-offset;' to your description.
|
|
|
+ This is a boolean property so needs no value. To enable it, add a
|
|
|
+ line 'sort-by-offset;' to your description.
|
|
|
|
|
|
multiple-images:
|
|
|
- Normally only a single image is generated. To create more than one
|
|
|
- image, put this property in the binman node. For example, this will
|
|
|
- create image1.bin containing u-boot.bin, and image2.bin containing
|
|
|
- both spl/u-boot-spl.bin and u-boot.bin:
|
|
|
-
|
|
|
- binman {
|
|
|
- multiple-images;
|
|
|
- image1 {
|
|
|
- u-boot {
|
|
|
- };
|
|
|
- };
|
|
|
-
|
|
|
- image2 {
|
|
|
- spl {
|
|
|
- };
|
|
|
- u-boot {
|
|
|
- };
|
|
|
- };
|
|
|
- };
|
|
|
+ Normally only a single image is generated. To create more than one
|
|
|
+ image, put this property in the binman node. For example, this will
|
|
|
+ create image1.bin containing u-boot.bin, and image2.bin containing
|
|
|
+ both spl/u-boot-spl.bin and u-boot.bin::
|
|
|
+
|
|
|
+ binman {
|
|
|
+ multiple-images;
|
|
|
+ image1 {
|
|
|
+ u-boot {
|
|
|
+ };
|
|
|
+ };
|
|
|
+
|
|
|
+ image2 {
|
|
|
+ spl {
|
|
|
+ };
|
|
|
+ u-boot {
|
|
|
+ };
|
|
|
+ };
|
|
|
+ };
|
|
|
|
|
|
end-at-4gb:
|
|
|
- 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 offset of the first entry would be 0xfff80000 with
|
|
|
- this option, instead of 0 without this option.
|
|
|
+ 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 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.
|
|
|
+ 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.
|
|
|
+ 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.
|
|
|
+ '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.
|
|
@@ -470,23 +471,23 @@ This feature provides a way of creating hierarchical images. For example here
|
|
|
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 {
|
|
|
- };
|
|
|
- };
|
|
|
- };
|
|
|
+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 {
|
|
|
+ };
|
|
|
+ };
|
|
|
+ };
|
|
|
|
|
|
This image could be placed into a SPI flash chip, with the protection boundary
|
|
|
set at 1MB.
|
|
@@ -494,14 +495,14 @@ set at 1MB.
|
|
|
A few special properties are provided for sections:
|
|
|
|
|
|
read-only:
|
|
|
- Indicates that this section is read-only. This has no impact on binman's
|
|
|
- operation, but his property can be read at run time.
|
|
|
+ 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.
|
|
|
+ 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
|
|
@@ -510,21 +511,21 @@ 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.
|
|
|
+ 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).
|
|
|
+ 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.
|
|
|
+ Adding this property causes the original offset and size values in the
|
|
|
+ image description to be stored in the FDT and fdtmap.
|
|
|
|
|
|
|
|
|
Entry Documentation
|
|
@@ -533,14 +534,14 @@ 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
|
|
|
+ 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, 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
|
|
@@ -559,7 +560,7 @@ 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.
|
|
|
+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
|
|
@@ -568,7 +569,7 @@ It is also possible to list just some files in an image, e.g.
|
|
|
u-boot 138 4 u-boot 38
|
|
|
u-boot-dtb 180 108 u-boot-dtb 80 3b5
|
|
|
|
|
|
-or with wildcards:
|
|
|
+or with wildcards::
|
|
|
|
|
|
$ binman ls -i image.bin "*cb*" "*head*"
|
|
|
Name Image-pos Size Entry-type Offset Uncomp-size
|
|
@@ -583,22 +584,22 @@ 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:
|
|
|
+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:
|
|
|
+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:
|
|
|
+put files in subdirectories matching the entry hierarchy::
|
|
|
|
|
|
$ binman extract -i image.bin -O outdir
|
|
|
|
|
|
-or just a selection:
|
|
|
+or just a selection::
|
|
|
|
|
|
$ binman extract -i image.bin "*u-boot*" -O outdir
|
|
|
|
|
@@ -616,18 +617,18 @@ 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:
|
|
|
+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:
|
|
|
+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:
|
|
|
+You can also replace just a selection of entries::
|
|
|
|
|
|
$ binman replace -i image.bin "*u-boot*" -I indir
|
|
|
|
|
@@ -656,15 +657,15 @@ 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:
|
|
|
+value back to the device-tree node. For example::
|
|
|
|
|
|
- binman {
|
|
|
- u-boot {
|
|
|
- hash {
|
|
|
- algo = "sha256";
|
|
|
- };
|
|
|
- };
|
|
|
- };
|
|
|
+ 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
|
|
@@ -759,7 +760,7 @@ a common header. You can then put the binman node (and anything else that is
|
|
|
specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
|
|
|
file.
|
|
|
|
|
|
-Binman will search for the following files in arch/<arch>/dts:
|
|
|
+Binman will search for the following files in arch/<arch>/dts::
|
|
|
|
|
|
<dts>-u-boot.dtsi where <dts> is the base name of the .dts file
|
|
|
<CONFIG_SYS_SOC>-u-boot.dtsi
|
|
@@ -770,7 +771,7 @@ Binman will search for the following files in arch/<arch>/dts:
|
|
|
U-Boot will only use the first one that it finds. If you need to include a
|
|
|
more general file you can do that from the more specific file using #include.
|
|
|
If you are having trouble figuring out what is going on, you can uncomment
|
|
|
-the 'warning' line in scripts/Makefile.lib to see what it has found:
|
|
|
+the 'warning' line in scripts/Makefile.lib to see what it has found::
|
|
|
|
|
|
# Uncomment for debugging
|
|
|
# This shows all the files that were considered and the one that we chose.
|
|
@@ -786,13 +787,13 @@ is useful to be able to find the location of U-Boot so that it can be executed
|
|
|
when SPL is finished.
|
|
|
|
|
|
Binman allows you to declare symbols in the SPL image which are filled in
|
|
|
-with their correct values during the build. For example:
|
|
|
+with their correct values during the build. For example::
|
|
|
|
|
|
binman_sym_declare(ulong, u_boot_any, image_pos);
|
|
|
|
|
|
declares a ulong value which will be assigned to the image-pos 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:
|
|
|
+You can access this value with something like::
|
|
|
|
|
|
ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
|
|
|
|
|
@@ -844,18 +845,18 @@ Expanded entries
|
|
|
----------------
|
|
|
|
|
|
Binman automatically replaces 'u-boot' with an expanded version of that, i.e.
|
|
|
-'u-boot-expanded'. This means that when you write:
|
|
|
+'u-boot-expanded'. This means that when you write::
|
|
|
|
|
|
u-boot {
|
|
|
};
|
|
|
|
|
|
-you actually get:
|
|
|
+you actually get::
|
|
|
|
|
|
u-boot {
|
|
|
type = "u-boot-expanded';
|
|
|
};
|
|
|
|
|
|
-which in turn expands to:
|
|
|
+which in turn expands to::
|
|
|
|
|
|
u-boot {
|
|
|
type = "section";
|
|
@@ -879,19 +880,19 @@ U-Boot executable and can be updated separately by binman as needed. It can be
|
|
|
disabled with the --no-expanded flag if required.
|
|
|
|
|
|
The same applies for u-boot-spl and u-boot-spl. In those cases, the expansion
|
|
|
-includes the BSS padding, so for example:
|
|
|
+includes the BSS padding, so for example::
|
|
|
|
|
|
spl {
|
|
|
type = "u-boot-spl"
|
|
|
};
|
|
|
|
|
|
-you actually get:
|
|
|
+you actually get::
|
|
|
|
|
|
spl {
|
|
|
type = "u-boot-expanded';
|
|
|
};
|
|
|
|
|
|
-which in turn expands to:
|
|
|
+which in turn expands to::
|
|
|
|
|
|
spl {
|
|
|
type = "section";
|
|
@@ -921,7 +922,7 @@ Compression
|
|
|
-----------
|
|
|
|
|
|
Binman support compression for 'blob' entries (those of type 'blob' and
|
|
|
-derivatives). To enable this for an entry, add a 'compress' property:
|
|
|
+derivatives). To enable this for an entry, add a 'compress' property::
|
|
|
|
|
|
blob {
|
|
|
filename = "datafile";
|
|
@@ -946,7 +947,7 @@ 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:
|
|
|
+generates. This shows the offset and size of each entry. For example::
|
|
|
|
|
|
Offset Size Name
|
|
|
00000000 00000028 main-section
|
|
@@ -969,11 +970,11 @@ 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:
|
|
|
+The-a option supports this::
|
|
|
|
|
|
-a<prop>=<value>
|
|
|
|
|
|
-where
|
|
|
+where::
|
|
|
|
|
|
<prop> is the property to set
|
|
|
<value> is the value to set it to
|
|
@@ -1004,7 +1005,7 @@ Code coverage
|
|
|
Binman is a critical tool and is designed to be very testable. Entry
|
|
|
implementations target 100% test coverage. Run 'binman test -T' to check this.
|
|
|
|
|
|
-To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
|
|
|
+To enable Python test coverage on Debian-type distributions (e.g. Ubuntu)::
|
|
|
|
|
|
$ sudo apt-get install python-coverage python3-coverage python-pytest
|
|
|
|
|
@@ -1015,7 +1016,7 @@ Concurrent tests
|
|
|
Binman tries to run tests concurrently. This means that the tests make use of
|
|
|
all available CPUs to run.
|
|
|
|
|
|
- To enable this:
|
|
|
+ To enable this::
|
|
|
|
|
|
$ sudo apt-get install python-subunit python3-subunit
|
|
|
|
|
@@ -1038,11 +1039,11 @@ Binman's tests have been written under the assumption that they'll be run on a
|
|
|
x86-like host and there hasn't been an attempt to make them portable yet.
|
|
|
However, it's possible to run the tests by cross-compiling to x86.
|
|
|
|
|
|
-To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu):
|
|
|
+To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu)::
|
|
|
|
|
|
$ sudo apt-get install gcc-x86-64-linux-gnu
|
|
|
|
|
|
-Then, you can run the tests under cross-compilation:
|
|
|
+Then, you can run the tests under cross-compilation::
|
|
|
|
|
|
$ CROSS_COMPILE=x86_64-linux-gnu- binman test -T
|
|
|
|
|
@@ -1078,13 +1079,13 @@ 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:
|
|
|
+BINMAN_DEBUG=1 to your build::
|
|
|
|
|
|
make qemu-x86_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:
|
|
|
+adds a -v<level> option to the call to binman::
|
|
|
|
|
|
make qemu-x86_defconfig
|
|
|
make BINMAN_VERBOSE=5
|
|
@@ -1124,6 +1125,7 @@ To do
|
|
|
-----
|
|
|
|
|
|
Some ideas:
|
|
|
+
|
|
|
- Use of-platdata to make the information available to code that is unable
|
|
|
to use device tree (such as a very small SPL image)
|
|
|
- Allow easy building of images by specifying just the board name
|