mirror of
https://github.com/smaeul/u-boot.git
synced 2025-10-17 22:28:17 +01:00
d048718a44
In leiu of a non-standard HOMEPAGE section, add a BUGS section with a link to the issue tracker. Signed-off-by: Sean Anderson <seanga2@gmail.com> Reviewed-by: Simon Glass <sjg@chromium.org>
504 lines
12 KiB
Groff
504 lines
12 KiB
Groff
.TH MKIMAGE 1 "2022-02-07"
|
|
.
|
|
.SH NAME
|
|
mkimage \- generate images for U-Boot
|
|
.SH SYNOPSIS
|
|
.SY mkimage
|
|
.OP \-T type
|
|
.BI \-l\~ image-file-name
|
|
.YS
|
|
.
|
|
.SY mkimage
|
|
.RI [ option\~ .\|.\|.\&]
|
|
.OP \-T type
|
|
.I image-file-name
|
|
.YS
|
|
.
|
|
.SY mkimage
|
|
.RI [ option\~ .\|.\|.\&]
|
|
.BI \-f\~ image-tree-source-file\c
|
|
.RB | auto
|
|
.I image-file-name
|
|
.YS
|
|
.
|
|
.SY mkimage
|
|
.RI [ option\~ .\|.\|.\&]
|
|
.BI \-F\~ image-file-name
|
|
.YS
|
|
.
|
|
.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.
|
|
.P
|
|
.B mkimage
|
|
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 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.
|
|
.
|
|
.SH OPTIONS
|
|
.
|
|
.SS General options
|
|
.
|
|
.TP
|
|
.B \-h
|
|
Print a help message and exit.
|
|
.
|
|
.TP
|
|
.B \-l
|
|
.B mkimage
|
|
lists the information contained in the header of an existing U-Boot image.
|
|
.
|
|
.TP
|
|
.B \-s
|
|
Don't copy in the image data. Depending on the image type, this may create
|
|
just the header, everything but the image data, or nothing at all.
|
|
.
|
|
.TP
|
|
.BI \-T " image-type"
|
|
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
|
|
Quiet. Don't print the image header.
|
|
.
|
|
.TP
|
|
.B \-v
|
|
Verbose. Print file names as they are added to the image.
|
|
.
|
|
.TP
|
|
.B \-V
|
|
Print version information and exit.
|
|
.
|
|
.SS General image-creation options
|
|
.
|
|
.TP
|
|
.BI \-A " architecture"
|
|
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 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 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 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 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 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
|
|
.B \-R
|
|
to specify this second image.
|
|
.TS
|
|
allbox;
|
|
lb lbx
|
|
l l.
|
|
Image Type Secondary Image Description
|
|
pblimage Additional RCW-style header, typically used for PBI commands.
|
|
zynqimage, zynqmpimage T{
|
|
Initialization parameters, one per line. Each parameter has the form
|
|
.sp
|
|
.ti 4
|
|
.I address data
|
|
.sp
|
|
where
|
|
.I address
|
|
and
|
|
.I data
|
|
are hexadecimal integers. The boot ROM will write each
|
|
.I data
|
|
to
|
|
.I address
|
|
when loading the image. At most 256 parameters may be specified in this
|
|
manner.
|
|
T}
|
|
.TE
|
|
.
|
|
.TP
|
|
.BI \-d " 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 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
|
|
.
|
|
.TP
|
|
.BI \-b " device-tree-file"
|
|
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 message which
|
|
describes how the image was signed or some other useful information.
|
|
.
|
|
.TP
|
|
.BI \-D " dtc-options"
|
|
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 \(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"
|
|
The alignment, in hexadecimal, that external data will be aligned to. This
|
|
option only has an effect when \-E is specified.
|
|
.
|
|
.TP
|
|
.BI \-p " external-position"
|
|
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
|
|
\fB\-f \fIimage-tree-source-file\fR | \fBauto
|
|
Image tree source file that describes the structure and contents of the
|
|
FIT image.
|
|
.IP
|
|
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 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"
|
|
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
|
|
.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"
|
|
Specifies the private key file to use when signing. This option may be used
|
|
instead of \-k.
|
|
.
|
|
.TP
|
|
.BI \-K " key-destination"
|
|
Specifies a compiled device tree binary file (typically .dtb) to write
|
|
public key information into. When a private key is used to sign an image,
|
|
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-name-hint"
|
|
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 \(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
|
|
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).
|
|
.
|
|
.TP
|
|
.B \-t
|
|
Update the timestamp in the FIT.
|
|
.IP
|
|
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
|
|
.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 BUGS
|
|
Please report bugs to the
|
|
.UR https://\:source\:.denx\:.de/\:u-boot/\:u-boot/\:issues
|
|
U-Boot bug tracker
|
|
.UE .
|
|
.SH EXAMPLES
|
|
.\" Reduce the width of the tab stops to something reasonable
|
|
.ta T 1i
|
|
List image information:
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-l uImage
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create legacy image with compressed PowerPC Linux kernel:
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-A powerpc \-O linux \-T kernel \-C gzip \\
|
|
\-a 0 \-e 0 \-n Linux \-d vmlinux.gz uImage
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create FIT image with compressed PowerPC Linux kernel:
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f kernel.its kernel.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create FIT image with compressed kernel and sign it with keys in the
|
|
/public/signing\-keys directory. Add corresponding public keys into u\-boot.dtb,
|
|
skipping those for which keys cannot be found. Also add a comment.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f kernel.its \-k /public/signing\-keys \-K u\-boot.dtb \\
|
|
\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Add public keys to u\-boot.dtb without needing a FIT to sign. This will also
|
|
create a FIT containing an images node with no data named unused.itb.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f auto \-d /dev/null \-k /public/signing\-keys \-g dev \\
|
|
\-o sha256,rsa2048 \-K u\-boot.dtb unused.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Update an existing FIT image, signing it with additional keys.
|
|
Add corresponding public keys into u\-boot.dtb. This will resign all images
|
|
with keys that are available in the new directory. Images that request signing
|
|
with unavailable keys are skipped.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-F \-k /secret/signing\-keys \-K u\-boot.dtb \\
|
|
\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create a FIT image containing a kernel, using automatic mode. No .its file
|
|
is required.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
|
|
\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz kernel.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create a FIT image containing a kernel and some device tree files, using
|
|
automatic mode. No .its file is required.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
|
|
\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz \\
|
|
\-b /path/to/rk3288\-firefly.dtb \-b /path/to/rk3288\-jerry.dtb kernel.itb
|
|
.EE
|
|
.RE
|
|
.P
|
|
Create a FIT image containing a signed kernel, using automatic mode. No .its
|
|
file is required.
|
|
.RS
|
|
.P
|
|
.EX
|
|
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
|
|
\-d vmlinuz \-k /secret/signing\-keys \-g dev \-o sha256,rsa2048 kernel.itb
|
|
.EE
|
|
.RE
|
|
.
|
|
.PP
|
|
.SH AUTHOR
|
|
This manual page was written by Nobuhiro Iwamatsu <iwamatsu@nigauri.org>
|
|
and Wolfgang Denk <wd@denx.de>. It was updated for image signing by
|
|
Simon Glass <sjg@chromium.org>.
|