doc: mkimage: Edit options for style and consistency

This makes a variety of changes for the options to make them
typographically consistent, clarify their meaning, and fix grammatical (or
other) errors. Many of the changes here are stylistic, though there are a
few fixes. The main changes I made across the board were:

- All options are bolded and parameters italicised
- All single quotes are properly matched (instead of using apostrophes)
- Minor background info has been added to clarify many underdocumented
  options
- Default values for options are documented

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

1 files changed, 207 insertions, 70 deletions

diff --git a/doc/mkimage.1 b/doc/mkimage.1
index ee5d0dd0ef4..6416b4ad5e8 100644
--- a/doc/mkimage.1
+++ b/doc/mkimage.1
@@ -29,26 +29,25 @@ mkimage \- generate images for U-Boot
 .SH DESCRIPTION
 The
 .B mkimage
-command is used to create images for use with the U-Boot boot loader.
-These images can contain the linux kernel, device tree blob, root file
-system image, firmware images etc., either separate or combined.
+command is used to create images for use with the U-Boot boot loader.  These
+images can contain the Linux kernel, device tree blob, root file system image,
+firmware images etc., either separate or combined.
 .P
 .B mkimage
-supports two different formats:
+supports many image formats. Some of these formats may be used by embedded boot
+firmware to load U-Boot. Others may be used by U-Boot to load Linux (or some
+other kernel):
 .P
-The old
-.I legacy image
-format concatenates the individual parts (for example, kernel image,
-device tree blob and ramdisk image) and adds a 64 bytes header
-containing information about target architecture, operating system,
-image type, compression method, entry points, time stamp, checksums,
-etc.
+The legacy image format concatenates the individual parts (for example, kernel
+image, device tree blob and ramdisk image) and adds a 64 byte header containing
+information about the target architecture, operating system, image type,
+compression method, entry points, time stamp, checksums, etc.
 .P
 The new
-.I FIT (Flattened Image Tree) format
-allows for more flexibility in handling images of various types and also
-enhances integrity protection of images with stronger checksums. It also
-supports verified boot.
+.I FIT
+(Flattened Image Tree) format allows for more flexibility in handling images of
+various types and also enhances integrity protection of images with stronger
+checksums. It also supports verified boot.
 .
 .SH OPTIONS
 .
@@ -60,8 +59,8 @@ Print a help message and exit.
 .
 .TP
 .B \-l
-mkimage lists the information contained in the header of an existing U-Boot
-image.
+.B mkimage
+lists the information contained in the header of an existing U-Boot image.
 .
 .TP
 .B \-s
@@ -70,9 +69,34 @@ just the header, everything but the image data, or nothing at all.
 .
 .TP
 .BI \-T " image-type"
-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.
+Parse image file as
+.IR image-type .
+Pass
+.B list
+as
+.I image-type
+to see the list of supported image types. If this option is absent, then it
+defaults to
+.B kernel
+(legacy image). If this option is absent when
+.B \-l
+is passed, then
+.B mkimage
+will attempt to automatically detect the image type. Not all image types support
+automatic detection, so it may be necessary to pass
+.B \-T
+explicitly.
+.IP
+When creating a FIT image with
+.BR \-f ,
+the image type is always set to
+.BR flat_dt .
+In this case,
+.B \-T
+specifies the image node's \(oqtype\(cq property. If
+.B \-T
+is absent, then the \(oqtype\(cq property will default to
+.BR kernel .
 .
 .TP
 .B \-q
@@ -90,35 +114,67 @@ Print version information and exit.
 .
 .TP
 .BI \-A " architecture"
-Set architecture. Pass \-h as the architecture to see the list of supported
-architectures.
+Set the architecture. Pass
+.B \-h
+as the architecture to see the list of supported architectures. If
+.B \-A
+is absent, it defaults to
+.BR ppc .
 .
 .TP
 .BI \-O " os"
-Set operating system. bootm command of u-boot changes boot method by os type.
-Pass \-h as the OS to see the list of supported OS.
+Set the operating system. The U-Boot
+.I bootm
+command changes boot method based on the OS type.
+Pass
+.B \-h
+as the
+.I os
+to see the list of supported OSs. If
+.B \-O
+is absent, it defaults to
+.BR linux .
 .
 .TP
 .BI \-C " compression-type"
-Set compression type.
-Pass \-h as the compression to see the list of supported compression type.
+Set the compression type. The image data should have already been compressed
+using this compression type.
+.B mkimage
+will not automatically compress image data.
+Pass
+.B \-h
+as the
+.I compression-type
+to see the list of supported compression types. If
+.B \-C
+is absent, it defaults to
+.BR gzip .
 .
 .TP
 .BI \-a " load-address"
-Set load address with a hex number.
+Set the absolute address to load the image data to.
+.I load-address
+will be interpreted as a hexadecimal number.
 .
 .TP
 .BI \-e " entry-point"
-Set entry point with a hex number.
+Set the absolute address of the image entry point. The U-Boot
+.I bootm
+command will jump to this address after loading the image.
+.I entry-point
+will be interpreted as a hexadecimal number.
 .
 .TP
 .BI \-n " image-name"
-Set image name to 'image name'.
+Set the image name to
+.IR 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.
+use
+.B \-R
+to specify this second image.
 .TS
 allbox;
 lb lbx
@@ -146,11 +202,26 @@ T}
 .
 .TP
 .BI \-d " image-data-file"
-Use image data from 'image data file'.
+Use image data from
+.IR image-data-file .
+If the
+.I image-type
+is
+.BR multi ,
+then multiple images may be specified, separated by colons:
+.RS
+.IP
+.IR image-data-file [\fB:\fP image-data-file .\|.\|.]
+.RE
 .
 .TP
 .B \-x
-Set XIP (execute in place) flag.
+Set the
+.I XIP
+(execute in place) flag. The U-Boot
+.I bootm
+command will not load the image data, and instead will assume it is already
+accessible at the load address (such as via memory-mapped flash).
 .
 .SS Options for creating FIT images
 .
@@ -160,23 +231,27 @@ Appends the device tree binary file (.dtb) to the FIT.
 .
 .TP
 .BI \-c " comment"
-Specifies a comment to be added when signing. This is typically a useful
-message which describes how the image was signed or some other useful
-information.
+Specifies a comment to be added when signing. This is typically a message which
+describes how the image was signed or some other useful information.
 .
 .TP
 .BI \-D " dtc-options"
-Provide special options to the device tree compiler that is used to
-create the image.
+Provide additional options to the device tree compiler when creating the image.
+See
+.BR dtc (1)
+for documentation of possible options. If
+.B \-D
+is absent, it defaults to
+.BR "\-I dts \-O dtb \-p 500" .
 .
 .TP
 .BI \-E
 After processing, move the image data outside the FIT and store a data offset
-in the FIT. Images will be placed one after the other immediately after the
-FIT, with each one aligned to a 4-byte boundary. The existing 'data' property
-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.
+in the FIT. Images will be placed one after the other immediately after the FIT,
+with each one aligned to a 4-byte boundary. The existing \(oqdata\(cq property
+in each image will be replaced with \(oqdata-offset\(cq and \(oqdata-size\(cq
+properties.  A \(oqdata-offset\(cq of 0 indicates that it starts in the first
+(4-byte-aligned) byte after the FIT.
 .
 .TP
 .BI \-B " alignment"
@@ -185,36 +260,62 @@ option only has an effect when \-E is specified.
 .
 .TP
 .BI \-p " external-position"
-Place external data at a static external position. See \-E. Instead of writing
-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.
+Place external data at a static external position. Instead of writing a
+\(oqdata-offset\(cq property defining the offset from the end of the FIT,
+.B \-p
+will use \(oqdata-position\(cq as the absolute position from the base of the
+FIT. See
+.B \-E
+for details on using external data.
 .
 .TP
-.BI \-f " image-tree-source-file"
+\fB\-f \fIimage-tree-source-file\fR | \fBauto
 Image tree source file that describes the structure and contents of the
 FIT image.
 .IP
-This can be automatically generated for some simple cases.
-Use "-f auto" for this. In that case the arguments -d, -A, -O, -T, -C, -a
-and -e are used to specify the image to include in the FIT and its attributes.
-No .its file is required.
+In some simple cases, the image tree source can be generated automatically. To
+use this feature, pass
+.BR "\-f auto" .
+The
+.BR \-d ,
+.BR \-A ,
+.BR \-O ,
+.BR \-T ,
+.BR \-C ,
+.BR \-a ,
+and
+.B \-e
+options may be used to specify the image to include in the FIT and its
+attributes. No
+.I image-tree-source-file
+is required.
 .
 .TP
 .B \-F
-Indicates that an existing FIT image should be modified. No dtc
-compilation is performed and the \-f flag should not be given.
-This can be used to sign images with additional keys after initial image
-creation.
+Indicates that an existing FIT image should be modified. No dtc compilation will
+be performed and
+.B \-f
+should not be passed. This can be used to sign images with additional keys
+after initial image creation.
 .
 .TP
 .BI \-i " ramdisk-file"
-Appends the ramdisk file to the FIT.
+Append a ramdisk or initramfs file to the image.
 .
 .TP
 .BI \-k " key-directory"
 Specifies the directory containing keys to use for signing. This directory
-should contain a private key file <name>.key for use with signing and a
-certificate <name>.crt (containing the public key) for use with verification.
+should contain a private key file
+.IR name .key
+for use with signing, and a certificate
+.IR name .crt
+(containing the public key) for use with verification. The public key is only
+necessary when embedding it into another device tree using
+.BR \-K .
+.I name
+defaults to the value of the signature node's \(oqkey-name-hint\(cq property,
+but may be overridden using
+.BR \-g .
 .
 .TP
 .BI \-G " key-file"
@@ -231,15 +332,49 @@ CONFIG_OF_CONTROL in U-Boot.
 .
 .TP
 .BI \-g " key-name-hint"
-Sets the key-name-hint property when used with \-f auto. This is the <name>
-part of the key. The directory part is set by \-k. This option also indicates
-that the images included in the FIT should be signed. If this option is
-specified, \-o must be specified as well.
-.
-.TP
-.BI \-o " signing-algorithm"
+Overrides the signature node's \(oqkey-name-hint\(cq property. This is
+especially useful when signing an image with
+.BR "\-f auto" .
+This is the
+.I name
+part of the key. The directory part is set by
+.BR \-k .
+This option also indicates that the images included in the FIT should be signed.
+If this option is specified, then
+.B \-o
+must be specified as well.
+.
+.TP
+.BI \-o " crypto" , checksum
 Specifies the algorithm to be used for signing a FIT image. The default is
-taken from the signature node's 'algo' property.
+taken from the signature node's \(oqalgo\(cq property.
+The valid values for
+.I crypto
+are:
+.RS
+.IP
+.TS
+lb.
+rsa2048
+rsa3072
+rsa4096
+ecdsa256
+.TE
+.RE
+.IP
+The valid values for
+.I checksum
+are
+.RS
+.IP
+.TS
+lb.
+sha1
+sha256
+sha384
+sha512
+.TE
+.RE
 .
 .TP
 .B \-r
@@ -249,18 +384,20 @@ 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
+The openssl engine to use when signing and verifying the image. For a complete
+list of available engines, refer to
 .BR engine (1).
 .
 .TP
 .B \-t
 Update the timestamp in the FIT.
 .IP
-Normally the FIT timestamp is created the first time mkimage is run on a FIT,
+Normally the FIT timestamp is created the first time mkimage runs,
 when converting the source .its to the binary .fit file. This corresponds to
-using the -f flag. But if the original input to mkimage is a binary file
-(already compiled) then the timestamp is assumed to have been set previously.
+using
+.BR -f .
+But if the original input to mkimage is a binary file (already compiled), then
+the timestamp is assumed to have been set previously.
 .
 .SH EXAMPLES
 .\" Reduce the width of the tab stops to something reasonable