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>

doc/develop/index.rst

@@ -26,6 +26,14 @@ Debugging
    crash_dumps
    trace
 
+Packaging
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   package/index
+
 Testing
 -------
 

doc/develop/package/binman.rst

@@ -0,0 +1 @@
+../../../tools/binman/binman.rst

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

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

doc/usage/index.rst

@@ -5,6 +5,7 @@ Use U-Boot
    :maxdepth: 1
 
    fdt_overlays
+   fit
    netconsole
    partitions
 

tools/binman/README.rst

@@ -0,0 +1 @@
+binman.rst

tools/binman/binman.rst

@@ -1,5 +1,5 @@
-# SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0+
-# Copyright (c) 2016 Google, Inc
+.. Copyright (c) 2016 Google, Inc
 
 Introduction
 ------------
@@ -67,18 +67,19 @@ standard format, we can support making valid images for any board without
 manual effort, lots of READMEs, etc.
 
 Benefits:
-- Each binary can have its own build system and tool chain without creating
+
-any dependencies between them
+  - Each binary can have its own build system and tool chain without creating
-- Avoids the need for a single-shot build: individual parts can be updated
+    any dependencies between them
-and brought in as needed
+  - Avoids the need for a single-shot build: individual parts can be updated
-- Provides for a standard image description available in the build and at
+    and brought in as needed
-run-time
+  - Provides for a standard image description available in the build and at
-- SoC-specific image-signing tools can be accommodated
+    run-time
-- Avoids cluttering the U-Boot build system with image-building code
+  - SoC-specific image-signing tools can be accommodated
-- The image description is automatically available at run-time in U-Boot,
+  - Avoids cluttering the U-Boot build system with image-building code
-SPL. It can be made available to other software also
+  - The image description is automatically available at run-time in U-Boot,
-- The image description is easily readable (it's a text file in device-tree
+    SPL. It can be made available to other software also
-format) and permits flexible packing of binaries
+  - 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
+  #. It uses a custom mksunxiboot tool to build an SPL image called
-sunxi-spl.bin. This should probably move into mkimage.
+     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
+  #. 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.
+     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
+  #. 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.
+     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 \
+    sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
-		liblz4-tool
+        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>),)
+    ifneq ($(CONFIG_ARCH_<something>),)
-u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
+    u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
-	$(call if_changed,binman)
+        $(call if_changed,binman)
-endif
+    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 {
+    binman {
-		filename = "u-boot-sunxi-with-spl.bin";
+        filename = "u-boot-sunxi-with-spl.bin";
-		pad-byte = <0xff>;
+        pad-byte = <0xff>;
-		blob {
+        blob {
-			filename = "spl/sunxi-spl.bin";
+            filename = "spl/sunxi-spl.bin";
-		};
+        };
-		u-boot {
+        u-boot {
-			offset = <CONFIG_SPL_PAD_TO>;
+            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
+    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
+    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
+    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
+    start of the image's entry area (normally 0) if there is no previous
-	region.
+    region.
 
 align:
-	This sets the alignment of the entry. The entry offset is adjusted
+    This sets the alignment of the entry. The entry offset is adjusted
-	so that the entry starts on an aligned boundary within the containing
+    so that the entry starts on an aligned boundary within the containing
-	section or image. For example 'align = <16>' means that the entry will
+    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
+    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
+    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
+    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
+    the entry starts. Alignment should be a power of 2. If 'align' is not
-	provided, no alignment is performed.
+    provided, no alignment is performed.
 
 size:
-	This sets the size of the entry. The contents will be padded out to
+    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
+    this size. If this is not provided, it will be set to the size of the
-	contents.
+    contents.
 
 pad-before:
-	Padding before the contents of the entry. Normally this is 0, meaning
+    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
+    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
+    to offset the entry contents a little. While this does not affect the
-	contents of the entry within binman itself (the padding is performed
+    contents of the entry within binman itself (the padding is performed
-	only when its parent section is assembled), the end result will be that
+    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.
+    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
+    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
+    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
+    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
+    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
+    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
+    parent section is assembled), the end result will be that the entry ends
-	with the padding bytes, so may grow. Defaults to 0.
+    with the padding bytes, so may grow. Defaults to 0.
 
 align-size:
-	This sets the alignment of the entry size. For example, to ensure
+    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.
+    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
+    While this does not affect the contents of the entry within binman
-	itself (the padding is performed only when its parent section is
+    itself (the padding is performed only when its parent section is
-	assembled), the end result is that the entry ends with the padding
+    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
+    bytes, so may grow. If 'align-size' is not provided, no alignment is
-	performed.
+    performed.
 
 align-end:
-	This sets the alignment of the end of an entry with respect to the
+    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
+    containing section. Some entries require that they end on an alignment
-	boundary, regardless of where they start. This does not move the start
+    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
+    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
+    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
+    affect the contents of the entry within binman itself (the padding is
-	performed only when its parent section is assembled), the end result
+    performed only when its parent section is assembled), the end result
-	is that the entry ends with the padding bytes, so may grow.
+    is that the entry ends with the padding bytes, so may grow.
-	If 'align-end' is not provided, no alignment is performed.
+    If 'align-end' is not provided, no alignment is performed.
 
 filename:
-	For 'blob' types this provides the filename containing the binary to
+    For 'blob' types this provides the filename containing the binary to
-	put into the entry. If binman knows about the entry type (like
+    put into the entry. If binman knows about the entry type (like
-	u-boot-bin), then there is no need to specify this.
+    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
+    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"'
+    possible to use any name, and then add (for example) 'type = "u-boot"'
-	to specify the type.
+    to specify the type.
 
 offset-unset:
-	Indicates that the offset of this entry should not be set by placing
+    Indicates that the offset of this entry should not be set by placing
-	it immediately after the entry before. Instead, is set by another
+    it immediately after the entry before. Instead, is set by another
-	entry which knows where this entry should go. When this boolean
+    entry which knows where this entry should go. When this boolean
-	property is present, binman will give an error if another entry does
+    property is present, binman will give an error if another entry does
-	not set the offset (with the GetOffsets() method).
+    not set the offset (with the GetOffsets() method).
 
 image-pos:
-	This cannot be set on entry (or at least it is ignored if it is), but
+    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
+    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
+    for each entry. This makes it easy to find out exactly where the entry
-	ended up in the image, regardless of parent sections, etc.
+    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
+    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
+    limited by the size of the image/section and the position of the next
-	entry.
+    entry.
 
 compress:
-	Sets the compression algortihm to use (for blobs only). See the entry
+    Sets the compression algortihm to use (for blobs only). See the entry
-	documentation for details.
+    documentation for details.
 
 missing-msg:
-	Sets the tag of the message to show if this entry is missing. This is
+    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
+    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
+    information about what needs to be fixed. See missing-blob-help for the
-	message for each tag.
+    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
+    Sets the image size in bytes, for example 'size = <0x100000>' for a
-	1MB image.
+    1MB image.
 
 offset:
-	This is similar to 'offset' in entries, setting the offset of a section
+    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
+    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
+    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
+    the end of the previous region, or the start of the image's entry area
-	(normally 0) if there is no previous region.
+    (normally 0) if there is no previous region.
 
 align-size:
-	This sets the alignment of the image size. For example, to ensure
+    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>'.
+    that the image ends on a 512-byte boundary, use 'align-size = <512>'.
-	If 'align-size' is not provided, no alignment is performed.
+    If 'align-size' is not provided, no alignment is performed.
 
 pad-before:
-	This sets the padding before the image entries. The first entry will
+    This sets the padding before the image entries. The first entry will
-	be positioned after the padding. This defaults to 0.
+    be positioned after the padding. This defaults to 0.
 
 pad-after:
-	This sets the padding after the image entries. The padding will be
+    This sets the padding after the image entries. The padding will be
-	placed after the last entry. This defaults to 0.
+    placed after the last entry. This defaults to 0.
 
 pad-byte:
-	This specifies the pad byte to use when padding in the image. It
+    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>'.
+    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
+    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
+    are in increasing positional order. This can be used when your entry
-	order may not match the positional order. A common situation is where
+    order may not match the positional order. A common situation is where
-	the 'offset' properties are set by CONFIG options, so their ordering is
+    the 'offset' properties are set by CONFIG options, so their ordering is
-	not known a priori.
+    not known a priori.
 
-	This is a boolean property so needs no value. To enable it, add a
+    This is a boolean property so needs no value. To enable it, add a
-	line 'sort-by-offset;' to your description.
+    line 'sort-by-offset;' to your description.
 
 multiple-images:
-	Normally only a single image is generated. To create more than one
+    Normally only a single image is generated. To create more than one
-	image, put this property in the binman node. For example, this will
+    image, put this property in the binman node. For example, this will
-	create image1.bin containing u-boot.bin, and image2.bin containing
+    create image1.bin containing u-boot.bin, and image2.bin containing
-	both spl/u-boot-spl.bin and u-boot.bin:
+    both spl/u-boot-spl.bin and u-boot.bin::
 
-	binman {
+        binman {
-		multiple-images;
+            multiple-images;
-		image1 {
+            image1 {
-			u-boot {
+                u-boot {
-			};
+                };
-		};
+            };
 
-		image2 {
+            image2 {
-			spl {
+                spl {
-			};
+                };
-			u-boot {
+                u-boot {
-			};
+                };
-		};
+            };
-	};
+        };
 
 end-at-4gb:
-	For x86 machines the ROM offsets start just before 4GB and extend
+    For x86 machines the ROM offsets start just before 4GB and extend
-	up so that the image finished at the 4GB boundary. This boolean
+    up so that the image finished at the 4GB boundary. This boolean
-	option can be enabled to support this. The image size must be
+    option can be enabled to support this. The image size must be
-	provided so that binman knows when the image should start. For an
+    provided so that binman knows when the image should start. For an
-	8MB ROM, the offset of the first entry would be 0xfff80000 with
+    8MB ROM, the offset of the first entry would be 0xfff80000 with
-	this option, instead of 0 without this option.
+    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
+    For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
-	offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
+    offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
-	nor flash boot, 0x201000 for sd boot etc.
+    nor flash boot, 0x201000 for sd boot etc.
 
-	'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
+    'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
-	Image size != 4gb.
+    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:
+and can be programmed::
 
-	binman {
+    binman {
-		section@0 {
+        section@0 {
-			read-only;
+            read-only;
-			name-prefix = "ro-";
+            name-prefix = "ro-";
-			size = <0x100000>;
+            size = <0x100000>;
-			u-boot {
+            u-boot {
-			};
+            };
-		};
+        };
-		section@1 {
+        section@1 {
-			name-prefix = "rw-";
+            name-prefix = "rw-";
-			size = <0x100000>;
+            size = <0x100000>;
-			u-boot {
+            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
+    Indicates that this section is read-only. This has no impact on binman's
-	operation, but his property can be read at run time.
+    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
+    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
+    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
+    renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
-	distinguish binaries with otherwise identical names.
+    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
+    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
+    case of multiple images <nodename>.bin where <nodename> is the name of
-	the image node.
+    the image node.
 
 allow-repack:
-	Create an image that can be repacked. With this option it is possible
+    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
+    to change anything in the image after it is created, including updating
-	the position and size of image components. By default this is not
+    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
+    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
+    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
+    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).
+    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
+    Adding this property causes the original offset and size values in the
-	image description to be stored in the FDT and fdtmap.
+    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 {
+    binman {
-		u-boot {
+        u-boot {
-			hash {
+            hash {
-				algo = "sha256";
+                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

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
 

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
 

tools/binman/index.rst

@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Binman
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   README

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'])