[PATCH 16/20] binman: doc: Add documentation to htmldocs
Heinrich Schuchardt
xypron.glpk at gmx.de
Sun Mar 7 21:02:55 CET 2021
On 3/7/21 8:31 PM, Simon Glass wrote:
> 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 at chromium.org>
> ---
>
> doc/index.rst | 1 +
> doc/package/binman | 1 +
> doc/package/fit.rst | 8 +
This information is only of interest for developers, not for end-users.
Please, place that information in /doc/develop/.
> doc/package/index.rst | 20 ++
> tools/binman/{README => README.rst} | 480 ++++++++++++++--------------
tools/binman/ is the wrong path for documentation. Please, put the file
in /doc/develop/binman.rst or /doc/develop/tools/binman.rst so that it
becomes available online.
Best regards
Heinrich
> tools/binman/control.py | 2 +-
> tools/binman/ftest.py | 4 +-
> tools/binman/index.rst | 9 +
> tools/binman/setup.py | 2 +-
> 9 files changed, 284 insertions(+), 243 deletions(-)
> create mode 120000 doc/package/binman
> create mode 100644 doc/package/fit.rst
> create mode 100644 doc/package/index.rst
> rename tools/binman/{README => README.rst} (73%)
> create mode 100644 tools/binman/index.rst
>
> diff --git a/doc/index.rst b/doc/index.rst
> index cdcc0a9e60a..26be4be5b3c 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -25,6 +25,7 @@ trying to get it to work optimally on a given system.
> :maxdepth: 2
>
> build/index
> + package/index
> usage/index
>
> Developer-oriented documentation
> diff --git a/doc/package/binman b/doc/package/binman
> new file mode 120000
> index 00000000000..94916117605
> --- /dev/null
> +++ b/doc/package/binman
> @@ -0,0 +1 @@
> +../../tools/binman
> \ No newline at end of file
> diff --git a/doc/package/fit.rst b/doc/package/fit.rst
> new file mode 100644
> index 00000000000..70374340577
> --- /dev/null
> +++ b/doc/package/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/package/index.rst b/doc/package/index.rst
> new file mode 100644
> index 00000000000..ca1f7fe2f97
> --- /dev/null
> +++ b/doc/package/index.rst
> @@ -0,0 +1,20 @@
> +.. 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
> +
> + fit
> + binman/index
> diff --git a/tools/binman/README b/tools/binman/README.rst
> similarity index 73%
> rename from tools/binman/README
> rename to tools/binman/README.rst
> index 1de703cc653..8d06aa91287 100644
> --- a/tools/binman/README
> +++ b/tools/binman/README.rst
> @@ -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 at 0 {
> - read-only;
> - name-prefix = "ro-";
> - size = <0x100000>;
> - u-boot {
> - };
> - };
> - section at 1 {
> - name-prefix = "rw-";
> - size = <0x100000>;
> - u-boot {
> - };
> - };
> - };
> +and can be programmed::
> +
> + binman {
> + section at 0 {
> + read-only;
> + name-prefix = "ro-";
> + size = <0x100000>;
> + u-boot {
> + };
> + };
> + section at 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
> diff --git a/tools/binman/control.py b/tools/binman/control.py
> index 9709aa9a2b2..f57e34daaaa 100644
> --- a/tools/binman/control.py
> +++ b/tools/binman/control.py
> @@ -569,7 +569,7 @@ def Binman(args):
> 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 2638408246f..df72bb89604 100644
> --- a/tools/binman/ftest.py
> +++ b/tools/binman/ftest.py
> @@ -631,7 +631,7 @@ class TestFunctional(unittest.TestCase):
> 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 @@ class TestFunctional(unittest.TestCase):
> 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 00000000000..6eef7b5d050
> --- /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 fe408ed6911..2dad43d4937 100644
> --- a/tools/binman/setup.py
> +++ b/tools/binman/setup.py
> @@ -7,6 +7,6 @@ setup(name='binman',
> 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'])
>
More information about the U-Boot
mailing list