doc/mkimage.1

.\" SPDX-License-Identifier: GPL-2.0
.\" Copyright (C) 2022 Sean Anderson <seanga2@gmail.com>
.\" Copyright (C) 2013-20 Simon Glass <sjg@chromium.org>
.\" Copyright (C) 2010 Nobuhiro Iwamatsu <iwamatsu@nigauri.org>
.\" Copyright (C) 2010 Wolfgang Denk <wd@denx.de>
.TH MKIMAGE 1 2022-06-11 U-Boot
.
.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
.TQ
.B \-\-help
Print a help message and exit.
.
.TP
.B \-l
.TQ
.B \-\-list
.B mkimage
lists the information contained in the header of an existing U-Boot image.
.
.TP
.B \-s
.TQ
.B \-\-no\-copy
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"
.TQ
.BI \-\-type " 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
.TQ
.B \-\-quiet
Quiet. Don't print the image header.
.
.TP
.B \-v
.TQ
.B \-\-verbose
Verbose. Print file names as they are added to the image.
.
.TP
.B \-V
.TQ
.B \-\-version
Print version information and exit.
.
.SS General image-creation options
.
.TP
.BI \-A " architecture"
.TQ
.BI \-\-architecture " 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"
.TQ
.BI \-\-os " 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"
.TQ
.BI \-\-compression " 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"
.TQ
.BI \-\-load\-address " 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"
.TQ
.BI \-\-entry\-point " 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"
.TQ
.BI \-\-primary\-image " image-name"
Set the image name to
.IR image-name .
.
.TP
.BI \-R " secondary-image-name"
.TQ
.BI \-\-secondary\-image " 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"
.TQ
.BI \-\-image " 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
.TQ
.B \-\-xip
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"
.TQ
.BI \-\-device\-tree " device-tree-file"
Appends the device tree binary file (.dtb) to the FIT.
.
.TP
.BI \-c " comment"
.TQ
.BI \-\-comment " 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"
.TQ
.BI \-\-dtcopts " 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
.TQ
.BI \-\-external
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"
.TQ
.BI \-\-alignment " 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"
.TQ
.BI \-\-position " 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
.TQ
\fB\-\-fit \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
.TQ
.B \-\-update
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"
.TQ
.BI \-\-initramfs " ramdisk-file"
Append a ramdisk or initramfs file to the image.
.
.TP
.BI \-k " key-directory"
.TQ
.BI \-\-key\-dir " 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"
.TQ
.BI \-\-key\-file " key-file"
Specifies the private key file to use when signing. This option may be used
instead of \-k.
.
.TP
.BI \-K " key-destination"
.TQ
.BI \-\-key\-dest " 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"
.TQ
.BI \-\-key\-name\-hint " 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
.TQ
.BI \-\-algo " 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
.TQ
.B \-\-key\-required
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"
.TQ
.BI \-\-engine " 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
.TQ
.B \-\-touch
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
.
.SH SEE ALSO
.BR dtc (1),
.BR dumpimage (1),
.BR openssl (1),
the\~
.UR https://\:u-boot\:.readthedocs\:.io/\:en/\:latest/\:index.html
U-Boot documentation
.UE