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+
-# Copyright (c) 2016 Google, Inc
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2016 Google, Inc
 
 Introduction
 ------------
@@ -67,6 +67,7 @@ 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
@@ -144,13 +145,13 @@ 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.
 
-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.
 
-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.
 
 Binman is intended to replace the last step. The U-Boot build system builds
@@ -180,12 +181,12 @@ 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
 
-Type:
+Type::
 
     binman build -b <board_name>
 
@@ -193,7 +194,7 @@ 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>
 
@@ -212,7 +213,7 @@ 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
@@ -233,7 +234,7 @@ 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";
@@ -414,7 +415,7 @@ 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:
+    both spl/u-boot-spl.bin and u-boot.bin::
 
         binman {
             multiple-images;
@@ -470,7 +471,7 @@ 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 {
         section@0 {
@@ -540,7 +541,7 @@ 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,7 +657,7 @@ 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 {
@@ -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'])