mirror of
https://source.denx.de/u-boot/u-boot.git
synced 2026-05-05 12:46:14 +02:00
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>
This commit is contained in:
Sean Anderson
Heinrich Schuchardt
parent
e9927c2664
commit
9cc4000cf2
273
doc/mkimage.1
273
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.
|
||||
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 " signing-algorithm"
|
||||
.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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user