From mboxrd@z Thu Jan 1 00:00:00 1970 From: Heinrich Schuchardt Date: Sun, 7 Mar 2021 21:02:55 +0100 Subject: [PATCH 16/20] binman: doc: Add documentation to htmldocs In-Reply-To: <20210307193148.1513733-17-sjg@chromium.org> References: <20210307193148.1513733-1-sjg@chromium.org> <20210307193148.1513733-17-sjg@chromium.org> Message-ID: <96767601-ebd7-567b-e583-ca4c00032984@gmx.de> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de 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 > --- > > 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 > + binman build -b > > 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/. > > -Or you can specify this explicitly: > +Or you can specify this explicitly:: > > - binman build -I > + binman build -I > > where 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_),) > -u-boot-.bin: checkbinman FORCE > - $(call if_changed,binman) > -endif > + ifneq ($(CONFIG_ARCH_),) > + u-boot-.bin: checkbinman FORCE > + $(call if_changed,binman) > + endif > > This assumes that u-boot-.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 = ; > - }; > - }; > + binman { > + filename = "u-boot-sunxi-with-spl.bin"; > + pad-byte = <0xff>; > + blob { > + filename = "spl/sunxi-spl.bin"; > + }; > + u-boot { > + offset = ; > + }; > + }; > > > 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 .bin where is the name of > - the image node. > + Output filename for the image. This defaults to image.bin (or in the > + case of multiple images .bin where 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//dts: > +Binman will search for the following files in arch//dts:: > > -u-boot.dtsi where is the base name of the .dts file > -u-boot.dtsi > @@ -770,7 +771,7 @@ Binman will search for the following files in 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= > > -where > +where:: > > is the property to set > 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 option to the call to binman: > +adds a -v 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']) >