From 4834bf1bc80a52421d4eff48dd5b7f89faf2d098 Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Date: Tue, 13 Jun 2023 21:02:01 +0200
Subject: [PATCH] doc: man-page for imxtract

Provide a man-page for the imxtract command.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
---
 doc/usage/cmd/imxtract.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst        |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 doc/usage/cmd/imxtract.rst

diff --git a/doc/usage/cmd/imxtract.rst b/doc/usage/cmd/imxtract.rst
new file mode 100644
index 0000000..eb64b1c
--- /dev/null
+++ b/doc/usage/cmd/imxtract.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+imxtract command
+================
+
+Synopsis
+--------
+
+::
+
+    imxtract addr part [dest]
+    imxtract addr uname [dest]
+
+Description
+-----------
+
+The imxtract command is used to extract a part of a multi-image file.
+
+Two different file formats are supported:
+
+* FIT images
+* legacy U-Boot images
+
+addr
+    Address of the multi-image file from which a part shall be extracted
+
+part
+    Index (hexadecimal) of the part of a legacy U-Boot image to be extracted
+
+uname
+    Name of the part of a FIT image to be extracted
+
+dest
+    Destination address (defaults to 0x0)
+
+The value of environment variable *verify* controls if the hashes and
+signatures of FIT images or the check sums of legacy U-Boot images are checked.
+To enable checking set *verify* to one of the values *1*, *yes*, *true*.
+(Actually only the first letter is checked disregarding the case.)
+
+To list the parts of an image the *iminfo* command can be used.
+
+Examples
+--------
+
+With verify=no incorrect hashes, signatures, or check sums don't stop the
+extraction. But correct hashes are still indicated in the output
+(here: md5, sha1).
+
+.. code-block:: console
+
+    => setenv verify no
+    => imxtract $loadaddr kernel-1 $kernel_addr_r
+    ## Copying 'kernel-1' subimage from FIT image at 40200000 ...
+    md5+ sha1+    Loading part 0 ... OK
+    =>
+
+With verify=yes incorrect hashes, signatures, or check sums stop the extraction.
+
+.. code-block:: console
+
+    => setenv verify yes
+    => imxtract $loadaddr kernel-1 $kernel_addr_r
+    ## Copying 'kernel-1' subimage from FIT image at 40200000 ...
+    md5 error!
+    Bad hash value for 'hash-1' hash node in 'kernel-1' image node
+    Bad Data Hash
+    =>
+
+Configuration
+-------------
+
+The imxtract command is only available if CONFIG_CMD_XIMG=y. Support for FIT
+images requires CONFIG_FIT=y. Support for legacy U-Boot images requires
+CONFIG_LEGACY_IMAGE_FORMAT=y.
+
+Return value
+------------
+
+On success the return value $? of the command is 0 (true). On failure the
+return value is 1 (false).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 84ef8a9..54ef89e 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -62,6 +62,7 @@ Shell commands
    cmd/fwu_mdata
    cmd/gpio
    cmd/host
+   cmd/imxtract
    cmd/load
    cmd/loadb
    cmd/loadm
-- 
2.7.4