[PATCH 1/2] mkimage: Document misc options

[Heinrich Schuchardt]

On 4/8/22 22:08, Sean Anderson wrote:
> Over the years, several options have not made it into the help message.
> Document them. Do the same for the man page.
>
> Signed-off-by: Sean Anderson <sean.anderson at seco.com>
> ---
>
>   doc/mkimage.1   | 36 +++++++++++++++++++++++++++++++++++-
>   tools/mkimage.c | 15 +++++++++++----
>   2 files changed, 46 insertions(+), 5 deletions(-)
>
> diff --git a/doc/mkimage.1 b/doc/mkimage.1
> index 287006279f..c92e133732 100644
> --- a/doc/mkimage.1
> +++ b/doc/mkimage.1
> @@ -53,6 +53,10 @@ Parse image file as type.
>   Pass \-h as the image to see the list of supported image type.
>   Without this option image type is autodetected.
>
> +.TP
> +.BI "\-q"
> +Quiet. Don't print the image header on successful verification.
> +
>   .P
>   .B Create old legacy image:
>
> @@ -91,6 +95,11 @@ List the contents of an image.
>   .BI "\-n [" "image name" "]"
>   Set image name to 'image name'.
>
> +.TP
> +.BI "\-R [" "secondary image name" "]"
> +Some image types support a second image for additional data. For these types,
> +use \-R to specify this second image.

A user needs to know which image types require or support a second
image. We need more text here.

> +
>   .TP
>   .BI "\-d [" "image data file" "]"
>   Use image data from 'image data file'.
> @@ -99,6 +108,15 @@ Use image data from 'image data file'.
>   .BI "\-x"
>   Set XIP (execute in place) flag.
>
> +.TP
> +.BI "\-s"
> +Create an image with no data. The header will be created, but the image itself
> +will not contain data (such as U-Boot or any specified kernel).

The text in parentheses seems superfluous.

> +
> +.TP
> +.BI "\-v"
> +Verbose. Print file names as they are added to the image.
> +
>   .P
>   .B Create FIT image:
>
> @@ -126,6 +144,11 @@ in each image will be replaced with 'data-offset' and 'data-size' properties.
>   A 'data-offset' of 0 indicates that it starts in the first (4-byte aligned)
>   byte after the FIT.
>
> +.TP
> +.BI "\-B [" "alignment" "]"
> +The alignment, in hexadecimal, that external data will be aligned to. This
> +option only has an effect when \-E is specified.
> +
>   .TP
>   .BI "\-f [" "image tree source file" " | " "auto" "]"
>   Image tree source file that describes the structure and contents of the
> @@ -161,6 +184,11 @@ the corresponding public key is written into this file for for run-time
>   verification. Typically the file here is the device tree binary used by
>   CONFIG_OF_CONTROL in U-Boot.
>
> +.TP
> +.BI "\-G [" "key_file" "]"

This should directly follow -k as it is related.

> +Specifies the private key file to use when signing. This option may be used
> +instead of \-k.
> +
>   .TP
>   .BI "\-o [" "signing algorithm" "]"
>   Specifies the algorithm to be used for signing a FIT image. The default is
> @@ -173,11 +201,17 @@ a 'data-offset' property defining the offset from the end of the FIT, \-p will
>   use 'data-position' as the absolute position from the base of the FIT.
>
>   .TP
> -.BI "\-r
> +.BI "\-r"
>   Specifies that keys used to sign the FIT are required. This means that they
>   must be verified for the image to boot. Without this option, the verification
>   will be optional (useful for testing but not for release).
>
> +.TP
> +.BI "\-N [" "engine" "]"
> +The openssl engine to use when signing and verifying the image. For a complete list of
> +available engines, refer to
> +.BR engine (1).

I can't find a reference (1) in your patch.

Best regards

Heinrich

> +
>   .TP
>   .BI "\-t
>   Update the timestamp in the FIT.
> diff --git a/tools/mkimage.c b/tools/mkimage.c
> index 74bd072832..c12d5932fc 100644
> --- a/tools/mkimage.c
> +++ b/tools/mkimage.c
> @@ -84,7 +84,8 @@ static void usage(const char *msg)
>   	fprintf(stderr, "Error: %s\n", msg);
>   	fprintf(stderr, "Usage: %s [-T type] -l image\n"
>   			 "          -l ==> list image header information\n"
> -			 "          -T ==> parse image file as 'type'\n",
> +			 "          -T ==> parse image file as 'type'\n"
> +			 "          -q ==> quiet\n",
>   		params.cmdname);
>   	fprintf(stderr,
>   		"       %s [-x] -A arch -O os -T type -C comp -a addr -e ep -n name -d data_file[:data_file...] image\n"
> @@ -95,8 +96,11 @@ static void usage(const char *msg)
>   		"          -a ==> set load address to 'addr' (hex)\n"
>   		"          -e ==> set entry point to 'ep' (hex)\n"
>   		"          -n ==> set image name to 'name'\n"
> +		"          -R ==> set second image name to 'name'\n"
>   		"          -d ==> use image data from 'datafile'\n"
> -		"          -x ==> set XIP (execute in place)\n",
> +		"          -x ==> set XIP (execute in place)\n"
> +		"          -s ==> create an image with no data\n"
> +		"          -v ==> verbose\n",
>   		params.cmdname);
>   	fprintf(stderr,
>   		"       %s [-D dtc_options] [-f fit-image.its|-f auto|-F] [-b <dtb> [-b <dtb>]] [-E] [-B size] [-i <ramdisk.cpio.gz>] fit-image\n"
> @@ -107,7 +111,9 @@ static void usage(const char *msg)
>   		"          -f => input filename for FIT source\n"
>   		"          -i => input filename for ramdisk file\n"
>   		"          -E => place data outside of the FIT structure\n"
> -		"          -B => align size in hex for FIT structure and header\n");
> +		"          -B => align size in hex for FIT structure and header\n"
> +		"          -b => append the device tree binary to the FIT\n"
> +		"          -t => update the timestamp in the FIT\n");
>   #ifdef CONFIG_FIT_SIGNATURE
>   	fprintf(stderr,
>   		"Signing / verified boot options: [-k keydir] [-K dtb] [ -c <comment>] [-p addr] [-r] [-N engine]\n"
> @@ -118,7 +124,8 @@ static void usage(const char *msg)
>   		"          -F => re-sign existing FIT image\n"
>   		"          -p => place external data at a static position\n"
>   		"          -r => mark keys used as 'required' in dtb\n"
> -		"          -N => openssl engine to use for signing\n");
> +		"          -N => openssl engine to use for signing\n"
> +		"          -o => algorithm to use for signing\n");
>   #else
>   	fprintf(stderr,
>   		"Signing / verified boot not supported (CONFIG_FIT_SIGNATURE undefined)\n");