binman: Add documentation for the command line args

Add command-line documentation for binman.

Signed-off-by: Simon Glass <sjg@chromium.org>

1 files changed, 299 insertions, 1 deletions

diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
index 92b21b1c01..e7b231e071 100644
--- a/tools/binman/binman.rst
+++ b/tools/binman/binman.rst
@@ -505,7 +505,6 @@ be located anywhere in the image. An image header (typically at the start or end
 of the image) can be used to point to the FDT map. See fdtmap and image-header
 entries for more information.
 
-
 Map files
 ---------
 
@@ -1339,6 +1338,305 @@ generated from the source code using:
 
    bintools
 
+Binman commands and arguments
+=============================
+
+Usage::
+
+    binman [-h] [-B BUILD_DIR] [-D] [-H] [--toolpath TOOLPATH] [-T THREADS]
+        [--test-section-timeout] [-v VERBOSITY] [-V]
+        {build,bintool-docs,entry-docs,ls,extract,replace,test,tool} ...
+
+Binman provides the following commands:
+
+- **build** - build images
+- **bintools-docs** - generate documentation about bintools
+- **entry-docs** - generate documentation about entry types
+- **ls** - list an image
+- **extract** - extract files from an image
+- **replace** - replace one or more entries in an image
+- **test** - run tests
+- **tool** - manage bintools
+
+Options:
+
+-h, --help
+    Show help message and exit
+
+-B BUILD_DIR, --build-dir BUILD_DIR
+    Directory containing the build output
+
+-D, --debug
+    Enabling debugging (provides a full traceback on error)
+
+-H, --full-help
+    Display the README file
+
+--toolpath TOOLPATH
+    Add a path to the directories containing tools
+
+-T THREADS, --threads THREADS
+    Number of threads to use (0=single-thread). Note that -T0 is useful for
+    debugging since everything runs in one thread.
+
+-v VERBOSITY, --verbosity VERBOSITY
+    Control verbosity: 0=silent, 1=warnings, 2=notices, 3=info, 4=detail,
+    5=debug
+
+-V, --version
+    Show the binman version
+
+Test options:
+
+--test-section-timeout
+    Use a zero timeout for section multi-threading (for testing)
+
+Commands are described below.
+
+binman build
+------------
+
+This builds one or more images using the provided image description.
+
+Usage::
+
+    binman build [-h] [-a ENTRY_ARG] [-b BOARD] [-d DT] [--fake-dtb]
+        [--fake-ext-blobs] [--force-missing-bintools FORCE_MISSING_BINTOOLS]
+        [-i IMAGE] [-I INDIR] [-m] [-M] [-n] [-O OUTDIR] [-p] [-u]
+        [--update-fdt-in-elf UPDATE_FDT_IN_ELF] [-W]
+
+Options:
+
+-h, --help
+    Show help message and exit
+
+-a ENTRY_ARG, --entry-arg ENTRY_ARG
+    Set argument value `arg=value`. See
+    `Passing command-line arguments to entries`_.
+
+-b BOARD, --board BOARD
+    Board name to build. This can be used instead of `-d`, in which case the
+    file `u-boot.dtb` is used, within the build directory's board subdirectory.
+
+-d DT, --dt DT
+    Configuration file (.dtb) to use. This must have a top-level node called
+    `binman`. See `Image description format`_.
+
+-i IMAGE, --image IMAGE
+    Image filename to build (if not specified, build all)
+
+-I INDIR, --indir INDIR
+    Add a path to the list of directories to use for input files. This can be
+    specified multiple times to add more than one path.
+
+-m, --map
+    Output a map file for each image. See `Map files`_.
+
+-M, --allow-missing
+    Allow external blobs and bintools to be missing. See `External blobs`_.
+
+-n, --no-expanded
+    Don't use 'expanded' versions of entries where available; normally 'u-boot'
+    becomes 'u-boot-expanded', for example. See `Expanded entries`_.
+
+-O OUTDIR, --outdir OUTDIR
+    Path to directory to use for intermediate and output files
+
+-p, --preserve
+    Preserve temporary output directory even if option -O is not given
+
+-u, --update-fdt
+    Update the binman node with offset/size info. See
+    `Access to binman entry offsets at run time (fdt)`_.
+
+--update-fdt-in-elf UPDATE_FDT_IN_ELF
+    Update an ELF file with the output dtb. The argument is a string consisting
+    of four parts, separated by commas. See `Updating an ELF file`_.
+
+-W, --ignore-missing
+    Return success even if there are missing blobs/bintools (requires -M)
+
+Options used only for testing:
+
+--fake-dtb
+    Use fake device tree contents
+
+--fake-ext-blobs
+    Create fake ext blobs with dummy content
+
+--force-missing-bintools FORCE_MISSING_BINTOOLS
+    Comma-separated list of bintools to consider missing
+
+binman bintool-docs
+-------------------
+
+Usage::
+
+    binman bintool-docs [-h]
+
+This outputs documentation for the bintools in rST format. See
+`Bintool Documentation`_.
+
+binman entry-docs
+-----------------
+
+Usage::
+
+    binman entry-docs [-h]
+
+This outputs documentation for the entry types in rST format. See
+`Entry Documentation`_.
+
+binman ls
+---------
+
+Usage::
+
+    binman ls [-h] -i IMAGE [paths ...]
+
+Positional arguments:
+
+paths
+    Paths within file to list (wildcard)
+
+Pptions:
+
+-h, --help
+    show help message and exit
+
+-i IMAGE, --image IMAGE
+    Image filename to list
+
+This lists an image, showing its contents. See `Listing images`_.
+
+binman extract
+--------------
+
+Usage::
+
+    binman extract [-h] [-F FORMAT] -i IMAGE [-f FILENAME] [-O OUTDIR] [-U]
+        [paths ...]
+
+Positional arguments:
+
+Paths
+    Paths within file to extract (wildcard)
+
+Options:
+
+-h, --help
+    show help message and exit
+
+-F FORMAT, --format FORMAT
+    Select an alternative format for extracted data
+
+-i IMAGE, --image IMAGE
+    Image filename to extract
+
+-f FILENAME, --filename FILENAME
+    Output filename to write to
+
+-O OUTDIR, --outdir OUTDIR
+    Path to directory to use for output files
+
+-U, --uncompressed
+    Output raw uncompressed data for compressed entries
+
+This extracts the contents of entries from an image. See
+`Extracting files from images`_.
+
+binman replace
+--------------
+
+Usage::
+
+    binman replace [-h] [-C] -i IMAGE [-f FILENAME] [-F] [-I INDIR] [-m]
+        [paths ...]
+
+Positional arguments:
+
+paths
+    Paths within file to replace (wildcard)
+
+Options:
+
+-h, --help
+    show help message and exit
+
+-C, --compressed
+    Input data is already compressed if needed for the entry
+
+-i IMAGE, --image IMAGE
+    Image filename to update
+
+-f FILENAME, --filename FILENAME
+    Input filename to read from
+
+-F, --fix-size
+    Don't allow entries to be resized
+
+-I INDIR, --indir INDIR
+    Path to directory to use for input files
+
+-m, --map
+    Output a map file for the updated image
+
+This replaces one or more entries in an existing image. See
+`Replacing files in an image`_.
+
+binman test
+-----------
+
+Usage::
+
+    binman test [-h] [-P PROCESSES] [-T] [-X] [tests ...]
+
+Positional arguments:
+
+tests
+    Test names to run (omit for all)
+
+Options:
+
+-h, --help
+    show help message and exit
+
+-P PROCESSES, --processes PROCESSES
+    set number of processes to use for running tests. This defaults to the
+    number of CPUs on the machine
+
+-T, --test-coverage
+    run tests and check for 100% coverage
+
+-X, --test-preserve-dirs
+    Preserve and display test-created input directories; also preserve the
+    output directory if a single test is run (pass test name at the end of the
+    command line
+
+binman tool
+-----------
+
+Usage::
+
+    binman tool [-h] [-l] [-f] [bintools ...]
+
+Positional arguments:
+
+bintools
+    Bintools to process
+
+Options:
+
+-h, --help
+    show help message and exit
+
+-l, --list
+    List all known bintools
+
+-f, --fetch
+    Fetch a bintool from a known location. Use `all` to fetch all and `missing`
+    to fetch any missing tools.
+
 
 Technical details
 =================