binman: doc: Add documentation to htmldocs
Add a link to binman's documentation and adjust the files so that it is
accessible. Use the name README.rst so it is easy to discover when binman
is installed without U-Boot.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 444df67..3edffbc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -26,6 +26,14 @@
crash_dumps
trace
+Packaging
+---------
+
+.. toctree::
+ :maxdepth: 1
+
+ package/index
+
Testing
-------
diff --git a/doc/develop/package/binman.rst b/doc/develop/package/binman.rst
new file mode 120000
index 0000000..2e26e84
--- /dev/null
+++ b/doc/develop/package/binman.rst
@@ -0,0 +1 @@
+../../../tools/binman/binman.rst
\ No newline at end of file
diff --git a/doc/develop/package/index.rst b/doc/develop/package/index.rst
new file mode 100644
index 0000000..9374be2
--- /dev/null
+++ b/doc/develop/package/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Package U-Boot
+==============
+
+U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
+images that it it reads and boots. Documentation about FIT is available at
+doc/uImage.FIT
+
+U-Boot also provides binman for cases not covered by FIT. Examples include
+initial execution (since FIT itself does not have an executable header) and
+dealing with device boundaries, such as the read-only/read-write separation in
+SPI flash.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ binman
diff --git a/doc/usage/fit.rst b/doc/usage/fit.rst
new file mode 100644
index 0000000..7037434
--- /dev/null
+++ b/doc/usage/fit.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Flat Image Tree (FIT)
+=====================
+
+U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
+images that it it reads and boots. Documentation about FIT is available at
+doc/uImage.FIT
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 637b73c..35c515f 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -5,6 +5,7 @@
:maxdepth: 1
fdt_overlays
+ fit
netconsole
partitions
diff --git a/tools/binman/README.rst b/tools/binman/README.rst
new file mode 120000
index 0000000..b734f54
--- /dev/null
+++ b/tools/binman/README.rst
@@ -0,0 +1 @@
+binman.rst
\ No newline at end of file
diff --git a/tools/binman/README b/tools/binman/binman.rst
similarity index 72%
rename from tools/binman/README
rename to tools/binman/binman.rst
index 1de703c..fd6308b 100644
--- a/tools/binman/README
+++ b/tools/binman/binman.rst
@@ -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,19 +67,20 @@
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 @@
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 @@
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 @@
---------------------------
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 @@
------------------------
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 @@
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:
+ 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 {
- };
- };
+ binman {
+ multiple-images;
+ image1 {
+ u-boot {
+ };
+ };
- image2 {
- spl {
- };
- 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 @@
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:
+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 {
- };
- };
- };
+ 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 @@
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 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 @@
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 @@
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 @@
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 @@
----------------------------
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 @@
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 @@
---------------
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 @@
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 @@
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 @@
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 @@
----------------
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 @@
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 @@
-----------
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 @@
---------
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
-----
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
diff --git a/tools/binman/control.py b/tools/binman/control.py
index 9709aa9..f57e34d 100644
--- a/tools/binman/control.py
+++ b/tools/binman/control.py
@@ -569,7 +569,7 @@
if not pager:
pager = 'more'
fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
- 'README')
+ 'README.rst')
command.Run(pager, fname)
return 0
diff --git a/tools/binman/ftest.py b/tools/binman/ftest.py
index 432c463..81c213a 100644
--- a/tools/binman/ftest.py
+++ b/tools/binman/ftest.py
@@ -631,7 +631,7 @@
def testFullHelp(self):
"""Test that the full help is displayed with -H"""
result = self._RunBinman('-H')
- help_file = os.path.join(self._binman_dir, 'README')
+ help_file = os.path.join(self._binman_dir, 'README.rst')
# Remove possible extraneous strings
extra = '::::::::::::::\n' + help_file + '\n::::::::::::::\n'
gothelp = result.stdout.replace(extra, '')
@@ -644,7 +644,7 @@
try:
command.test_result = command.CommandResult()
result = self._DoBinman('-H')
- help_file = os.path.join(self._binman_dir, 'README')
+ help_file = os.path.join(self._binman_dir, 'README.rst')
finally:
command.test_result = None
diff --git a/tools/binman/index.rst b/tools/binman/index.rst
new file mode 100644
index 0000000..6eef7b5
--- /dev/null
+++ b/tools/binman/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Binman
+======
+
+.. toctree::
+ :maxdepth: 2
+
+ README
diff --git a/tools/binman/setup.py b/tools/binman/setup.py
index fe408ed..2dad43d 100644
--- a/tools/binman/setup.py
+++ b/tools/binman/setup.py
@@ -7,6 +7,6 @@
scripts=['binman'],
packages=['binman', 'binman.etype'],
package_dir={'binman': ''},
- package_data={'binman': ['README', 'README.entries']},
+ package_data={'binman': ['README.rst', 'README.entries']},
classifiers=['Environment :: Console',
'Topic :: Software Development :: Embedded Systems'])