288 lines
8.3 KiB
Groff
288 lines
8.3 KiB
Groff
.TH MKIMAGE 1 "2022-02-07"
|
|
|
|
.SH NAME
|
|
mkimage \- Generate image for U-Boot
|
|
.SH SYNOPSIS
|
|
.B mkimage
|
|
.RB [ \-T " \fItype\fP] " \-l " [\fIuimage file name\fP]"
|
|
|
|
.B mkimage
|
|
.RB [\fIoptions\fP] " \-f [" "image tree source file" "]" " [" "uimage file name" "]"
|
|
|
|
.B mkimage
|
|
.RB [\fIoptions\fP] " \-F [" "uimage file name" "]"
|
|
|
|
.B mkimage
|
|
.RB [\fIoptions\fP] " (legacy mode)"
|
|
|
|
.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.
|
|
|
|
.B mkimage
|
|
supports two different formats:
|
|
|
|
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 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"
|
|
|
|
.B List image information:
|
|
|
|
.TP
|
|
.BI "\-l [" "uimage file name" "]"
|
|
mkimage lists the information contained in the header of an existing U-Boot image.
|
|
|
|
.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.
|
|
|
|
.TP
|
|
.BI "\-q"
|
|
Quiet. Don't print the image header on successful verification.
|
|
|
|
.P
|
|
.B Create old legacy image:
|
|
|
|
.TP
|
|
.BI "\-A [" "architecture" "]"
|
|
Set architecture. Pass \-h as the architecture to see the list of supported architectures.
|
|
|
|
.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.
|
|
|
|
.TP
|
|
.BI "\-T [" "image type" "]"
|
|
Set image type.
|
|
Pass \-h as the image to see the list of supported image type.
|
|
|
|
.TP
|
|
.BI "\-C [" "compression type" "]"
|
|
Set compression type.
|
|
Pass \-h as the compression to see the list of supported compression type.
|
|
|
|
.TP
|
|
.BI "\-a [" "load address" "]"
|
|
Set load address with a hex number.
|
|
|
|
.TP
|
|
.BI "\-e [" "entry point" "]"
|
|
Set entry point with a hex number.
|
|
|
|
.TP
|
|
.BI "\-l"
|
|
List the contents of an image.
|
|
|
|
.TP
|
|
.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.
|
|
|
|
.TP
|
|
.BI "\-d [" "image data file" "]"
|
|
Use image data from 'image data file'.
|
|
|
|
.TP
|
|
.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).
|
|
|
|
.TP
|
|
.BI "\-v"
|
|
Verbose. Print file names as they are added to the image.
|
|
|
|
.P
|
|
.B Create FIT image:
|
|
|
|
.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 useful
|
|
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.
|
|
|
|
.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.
|
|
|
|
.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
|
|
FIT image.
|
|
|
|
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.
|
|
|
|
.TP
|
|
.BI "\-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.
|
|
|
|
.TP
|
|
.BI "\-i [" "ramdisk_file" "]"
|
|
Appends the ramdisk file to the FIT.
|
|
|
|
.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.
|
|
|
|
.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_file" "]"
|
|
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
|
|
taken from the signature node's 'algo' property.
|
|
|
|
.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.
|
|
|
|
.TP
|
|
.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).
|
|
|
|
.TP
|
|
.BI "\-t
|
|
Update the timestamp in the FIT.
|
|
|
|
Normally the FIT timestamp is created the first time mkimage is run on a FIT,
|
|
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.
|
|
|
|
.SH EXAMPLES
|
|
|
|
List image information:
|
|
.nf
|
|
.B mkimage -l uImage
|
|
.fi
|
|
.P
|
|
Create legacy image with compressed PowerPC Linux kernel:
|
|
.nf
|
|
.B mkimage -A powerpc -O linux -T kernel -C gzip \\\\
|
|
.br
|
|
.B -a 0 -e 0 -n Linux -d vmlinux.gz uImage
|
|
.fi
|
|
.P
|
|
Create FIT image with compressed PowerPC Linux kernel:
|
|
.nf
|
|
.B mkimage -f kernel.its kernel.itb
|
|
.fi
|
|
.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.
|
|
.nf
|
|
.B mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \\\\
|
|
.br
|
|
.B -c """Kernel 3.8 image for production devices""" kernel.itb
|
|
.fi
|
|
|
|
.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.
|
|
.nf
|
|
.B mkimage -F -k /secret/signing-keys -K u-boot.dtb \\\\
|
|
.br
|
|
.B -c """Kernel 3.8 image for production devices""" kernel.itb
|
|
.fi
|
|
|
|
.P
|
|
Create a FIT image containing a kernel, using automatic mode. No .its file
|
|
is required.
|
|
.nf
|
|
.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\
|
|
.br
|
|
.B -c """Kernel 4.4 image for production devices""" -d vmlinuz kernel.itb
|
|
.fi
|
|
.P
|
|
Create a FIT image containing a kernel and some device tree files, using
|
|
automatic mode. No .its file is required.
|
|
.nf
|
|
.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\
|
|
.br
|
|
.B -c """Kernel 4.4 image for production devices""" -d vmlinuz \\\\
|
|
.B -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb
|
|
.fi
|
|
|
|
.SH HOMEPAGE
|
|
http://www.denx.de/wiki/U-Boot/WebHome
|
|
.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>.
|