[PATCH 1/2] mkimage: Document misc options

[Sean Anderson]

On 4/8/22 5:59 PM, Heinrich Schuchardt wrote:
> 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.

Will update. At the moment it seems to just be pblimage/zynqimage/zynqmpimage.

>> +
>>   .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.

Actually, I'm not really sure if the whole thing is correct. It doesn't seem to
apply to FITs at the very least.

>> +
>> +.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.

OK.

>> +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.

This is a reference to the engine(1) manual page.

--Sean