Ubuntu Manpage: mkimage - generate images for U-Boot

Provided by: u-boot-tools_2022.10+dfsg-1ubuntu1_amd64

NAME

       mkimage - generate images for U-Boot

SYNOPSIS

       mkimage [-T type] -l image-file-name

       mkimage [option ...] [-T type] image-file-name

       mkimage [option ...] -f image-tree-source-file|auto image-file-name

       mkimage [option ...] -F image-file-name

DESCRIPTION

       The  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.

       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):

       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.

       The new 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.

OPTIONS

General options
-h
--help Print a help message and exit.

-l
--list mkimage lists the information contained in the header of an existing U-Boot image.

-s
--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.

-T image-type
--type image-type
Parse image file as image-type. Pass list as image-type to see the list of
supported image types. If this option is absent, then it defaults to kernel (legacy
image). If this option is absent when -l is passed, then mkimage will attempt to
automatically detect the image type. Not all image types support automatic
detection, so it may be necessary to pass -T explicitly.

When creating a FIT image with -f, the image type is always set to flat_dt. In
this case, -T specifies the image node's ‘type’ property. If -T is absent, then the
‘type’ property will default to kernel.

-q
--quiet
Quiet. Don't print the image header.

-v
--verbose
Verbose. Print file names as they are added to the image.

-V
--version
Print version information and exit.

General image-creation options
-A architecture
--architecture architecture
Set the architecture. Pass -h as the architecture to see the list of supported
architectures. If -A is absent, it defaults to ppc.

-O os
--os os
Set the operating system. The U-Boot bootm command changes boot method based on the
OS type. Pass -h as the os to see the list of supported OSs. If -O is absent, it
defaults to linux.

-C compression-type
--compression compression-type
Set the compression type. The image data should have already been compressed using
this compression type. mkimage will not automatically compress image data. Pass
-h as the compression-type to see the list of supported compression types. If -C is
absent, it defaults to gzip.

-a load-address
--load-address load-address
Set the absolute address to load the image data to. load-address will be
interpreted as a hexadecimal number.

-e entry-point
--entry-point entry-point
Set the absolute address of the image entry point. The U-Boot bootm command will
jump to this address after loading the image. entry-point will be interpreted as a
hexadecimal number.

-n primary-configuration
--config primary-configuration
Images may require additional configuration not specified with other options, often
in a image-type-specific format. The image types which support this option and the
format of their configuration are listed in CONFIGURATION.

-R secondary-configuration
--secondary-config secondary-configuration
Some image types support a second set of configuration data. The image types which
support secondary configuration and the formap of their configuration are listed in
CONFIGURATION.

-d image-data-file
--image image-data-file
Use image data from image-data-file. If the image-type is multi, then multiple
images may be specified, separated by colons:

image-data-file[:image-data-file...]

-x
--xip Set the XIP (execute in place) flag. The U-Boot 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).

Options for creating FIT images
-b device-tree-file
--device-tree device-tree-file
Appends the device tree binary file (.dtb) to the FIT.

-c comment
--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.

-D dtc-options
--dtcopts dtc-options
Provide additional options to the device tree compiler when creating the image.
See dtc(1) for documentation of possible options. If -D is absent, it defaults to
-I dts -O dtb -p 500.

-E
--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 ‘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.

-B alignment
--alignment alignment
The alignment, in hexadecimal, that external data will be aligned to. This option
only has an effect when -E is specified.

-p external-position
--position external-position
Place external data at a static external position. 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. See -E for details on
using external data.

-f image-tree-source-file | auto
--fit image-tree-source-file | auto
Image tree source file that describes the structure and contents of the FIT image.

In some simple cases, the image tree source can be generated automatically. To use
this feature, pass -f auto. The -d, -A, -O, -T, -C, -a, and -e options may be used
to specify the image to include in the FIT and its attributes. No image-tree-
source-file is required.

-F
--update
Indicates that an existing FIT image should be modified. No dtc compilation will be
performed and -f should not be passed. This can be used to sign images with
additional keys after initial image creation.

-i ramdisk-file
--initramfs ramdisk-file
Append a ramdisk or initramfs file to the image.

-k key-directory
--key-dir 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. The public key is
only necessary when embedding it into another device tree using -K. name defaults
to the value of the signature node's ‘key-name-hint’ property, but may be
overridden using -g.

-G key-file
--key-file key-file
Specifies the private key file to use when signing. This option may be used instead
of -k.

-K key-destination
--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.

-g key-name-hint
--key-name-hint key-name-hint
Overrides the signature node's ‘key-name-hint’ property. This is especially useful
when signing an image 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, then -o must be
specified as well.

-o crypto,checksum
--algo crypto,checksum
Specifies the algorithm to be used for signing a FIT image. The default is taken
from the signature node's ‘algo’ property. The valid values for crypto are:

rsa2048
rsa3072
rsa4096
ecdsa256

The valid values for checksum are

sha1
sha256
sha384
sha512

-r
--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).

-N engine
--engine engine
The openssl engine to use when signing and verifying the image. For a complete list
of available engines, refer to engine(1).

-t
--touch
Update the timestamp in the 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 -f. But if the
original input to mkimage is a binary file (already compiled), then the timestamp
is assumed to have been set previously.

CONFIGURATION

This section documents the formats of the primary and secondary configuration options for
each image type which supports them.

aisimage
The primary configuration is a file containing a series of AIS (Application Image Script)
commands, one per line. Each command has the form

command argument ...

See TI application report SPRAAG0E ⟨https://www.ti.com/lit/pdf/spraag0⟩ for details.

atmelimage
The primary configuration is a comma-separated list of NAND Flash parameters of the form

parameter=value[,parameter=value...]

Valid parameters are

usePmecc
nbSectorPerPage

spareSize
eccBitReq
sectorSize
eccOffset

and valid values are decimal numbers. See section 11.4.4.1 of the SAMA5D3 Series Data
Sheet for valid values for each parameter.

imximage
The primary configuration is a file containing configuration commands, as documented in
doc/imx/mkimage/imximage.txt of the U-Boot source.

imx8image and imx8mimage
The primary configuration is a file containing configuration commands, as documented in
doc/imx/mkimage/imx8image.txt of the U-Boot source.

kwbimage
The primary configuration is a file containing configuration commands, as documented in
doc/imx/mkimage/kwbimage.txt of the U-Boot source.

mtk_image
The primary configuration is a semicolon-separated list of header options of the form

key=value[;key=value...]

where the valid keys are:

Key Description
────────────────────────────────────────────────────────────────────────────────────
lk If 1, then an LK (legacy) image header is used. Otherwise, a BootROM
image header is used.
lkname The name of the LK image header. The maximum length is 32 ASCII
characters. If not specified, the default value is U-Boot.
media The boot device. See below for valid values.
nandinfo The desired NAND device type. See below for valid values.
arm64 If 1, then this denotes an AArch64 image.
hdroffset Increase the reported size of the BRLYT header by this amount.

Valid values for media are:

Value Description
─────────────────────────────────────────
nand Parallel NAND flash
snand Serial NAND flash
nor Serial NOR flash
emmc eMMC (Embedded Multi-Media Card)
sdmmc SD (Secure Digital) card

Valid values for nandinfo are:

Value NAND type Page size OOB size Total size
──────────────────────────────────────────────────────────
2k+64 Serial 2KiB 64B
2k+120 Serial 2KiB 120B
2k+128 Serial 2KiB 128B
4k+256 Serial 4KiB 256B
1g:2k+64 Parallel 2KiB 64B 1Gbit
2g:2k+64 Parallel 2KiB 64B 2Gbit
4g:2k+64 Parallel 2KiB 64B 4Gbit
2g:2k+128 Parallel 2KiB 128B 2Gbit
4g:2k+128 Parallel 2KiB 128B 4Gbit

mxsimage
The primary configuration is a file containing configuration commands, as documented in
doc/imx/mkimage/mxsimage.txt of the U-Boot source.

omapimage
The primary configuration is the optional value byteswap. If present, each 32-bit word of
the image will have its bytes swapped (converting from little-endian to big-endian, or
vice versa).

pblimage
The primary configuration is a file containing the PBI (Pre-Boot Image) header. Each line
of the configuration has the format

value[ value...]

Where value is a 32-bit hexadecimal integer. Each value will, after being converted to raw
bytes, be literally prepended to the PBI.

The secondary configuration is a file with the same format as the primary configuration
file. It will be inserted into the image after the primary configuration data and before
the image data.

It is traditional to use the primary configuration file for the RCW (Reset Configuration
Word), and the secondary configuration file for any additional PBI commands. However, it
is also possible to convert an existing PBI to the above format and “chain” additional
data onto the end of the image. This may be especially useful for creating secure boot
images.

rkimage
The primary configuration is the name of the processor to generate the image for. Valid
values are:

px30
rk3036
rk3066
rk3128
rk3188
rk322x
rk3288
rk3308
rk3328
rk3368
rk3399
rv1108
rk3568

sunxi_egon
The primary configuration is the name to use for the device tree.

ublimage
The primary configuration is a file containing configuration commands, as documented in
doc/README.ublimage of the U-Boot source.

zynqimage and zynqmpimage
For zynqmpimage, the primary configuration is a file containing the PMUFW (Power
Management Unit Firmware). zynqimage does not use the primary configuration.

For both image types, the secondary configuration is a file containinig initialization
parameters, one per line. Each parameter has the form

address data

where address and data are hexadecimal integers. The boot ROM will write each data to
address when loading the image. At most 256 parameters may be specified in this manner.

BUGS

       Please  report  bugs  to  the  U-Boot  bug  tracker ⟨https://source.denx.de/u-boot/u-boot/
       issues⟩.

EXAMPLES

List image information:

mkimage -l uImage

Create legacy image with compressed PowerPC Linux kernel:

mkimage -A powerpc -O linux -T kernel -C gzip \
-a 0 -e 0 -n Linux -d vmlinux.gz uImage

Create FIT image with compressed PowerPC Linux kernel:

mkimage -f kernel.its kernel.itb

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.

mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \
-c "Kernel 3.8 image for production devices" kernel.itb

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.

mkimage -f auto -d /dev/null -k /public/signing-keys -g dev \
-o sha256,rsa2048 -K u-boot.dtb unused.itb

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.

mkimage -F -k /secret/signing-keys -K u-boot.dtb \
-c "Kernel 3.8 image for production devices" kernel.itb

Create a FIT image containing a kernel, using automatic mode. No .its file is required.

mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
-c "Kernel 4.4 image for production devices" -d vmlinuz kernel.itb

Create a FIT image containing a kernel and some device tree files, using automatic mode.
No .its file is required.

mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
-c "Kernel 4.4 image for production devices" -d vmlinuz \
-b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb

Create a FIT image containing a signed kernel, using automatic mode. No .its file is
required.

mkimage -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