MKIMAGE(1)

📦
version 2026.07 · 6 versions
, in arch rolling, fedora 44, nixos 26.05, nixpkgs unstable

MKIMAGE(1) 💖 General Commands Manual 💖

okay bestie, welcome to mkimage, the U-Boot image-making machine 🫶 this is the MKIMAGE(1) page and we are gonna get so cozy with it.

✨ 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|auto-conf image-
        file-name

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

like… four whole ways to show up 💅 pick your fighter.

🦋 DESCRIPTION 🦋

So the mkimage command is literally the thing you use to create images for the U-Boot boot loader. That's the whole vibe. 🌈

And these images? They can hold the Linux kernel, a device tree blob, a root file system image, firmware images, etc. — either separate, or combined into one gorgeous little bundle. no cap. 🎀

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). both lanes, she's flexible. ✨

🧚 the legacy image format

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.

(it's giving "everything you need to know, stapled to the front" 😌)

💜 the new FIT format

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

bestie. stronger checksums + verified boot = the glow-up of the century. the legacy format could never. 💅

more parts coming, don't go anywhere 👀

✨ OPTIONS ✨

okay bestie, this is the part where mkimage shows you every little knob and switch it has. it’s giving control freak in the best way 💅. every option, every default, every “pls don’t do this unless you know what you’re doing” — it’s all here. no cap.

💖 General options 💖

  • -h, --help — print a help message and exit. literally the “bestie explain” button 🫶.
  • -l, --list — mkimage lists the information contained in the header of an existing U-Boot image. like a vibe check for your image header ✨.
  • -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. so… unpredictable? kinda iconic, kinda scary 💀.
  • -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. autodetect is not giving universal, bestie.

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. shhh 🤫.
  • -v, --verbose — verbose. print file names as they are added to the image. yap mode: on 📣.
  • -V, --version — print version information and exit. the classic “what version am i” moment 👑.

🌸 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. okay default ppc, noted 📝.
  • -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. default linux, slay 🐧.
  • -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. so do the zip yourself, bestie, mkimage is not your compressor 😭.
  • -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. hex girl summer 🔢.
  • -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 an 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 format 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). XIP: not loading, just vibing at the address 💅.
  • -y, --tfa-bl31-file — append TFA BL31 file to the image.
  • -Y, --tfa-bl31-addr — set TFA BL31 file load and entry point address.
  • -z, --tee-file — append raw TEE file to the image.
  • -Z, --tee-addr — set raw TEE file load and entry point address, in hexadecimal.

🦋 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. cute little signature note 🎀.
  • -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 | auto-conf, --fit image-tree-source-file | auto | auto-conf — 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. the -g, -o, and -k or -G options may be used to get ‘images’ signed subnodes in the generated auto FIT. instead, to get ‘configurations’ signed subnodes and ‘images’ hashed subnodes, pass -f auto-conf. in this case -g, -o, and -k or -G are mandatory options.

  • -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 is the value of the signature node's ‘key-name-hint’ property.
  • -G key-file, --key-file key-file — specifies the private key file to use when signing. this option may be used instead of -k. useful when the private key file basename does not match ‘key-name-hint’ value. but note that it may lead to unexpected results when used together with -K and/or -k options.
⚠️ bestie, unexpected results? be careful with mixing this one.
  • -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 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 — specifies the value of signature node ‘key-name-hint’ property for an automatically generated FIT image. it makes sense only when used with -f auto or -f auto-conf. this option also indicates that the images or configurations included in the FIT should be signed. if this option is specified, then -o must be specified as well.
  • -o checksum,crypto, --algo checksum,crypto — specifies the algorithm to be used for signing a FIT image, overriding value taken from the signature node ‘algo’ property in the image-tree-source-file. it is mandatory for automatically generated FIT.

the valid values for checksum are:

  • sha1
  • sha256
  • sha384
  • sha512

the valid values for crypto are:

  • rsa2048
  • rsa3072
  • rsa4096
  • ecdsa256
  • -r, --key-required — specifies that keys used to sign the FIT are required. this means that images or configurations signatures must be verified before using them (i.e. to boot). without this option, the verification will be optional (useful for testing but not for release). it makes sense only when used with -K. when both, images and configurations, are signed, ‘required’ property value will be "conf".
  • -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 🛠️

Okay bestie, this section is the ✨lore✨ — it documents the formats of the primary and secondary configuration options for every image type that supports them. Different image, different vibe, different config format. Let's go one by one. 💅

🌸 aisimage 🌸

The primary configuration is a file containing a series of AIS (Application Image Script) commands, one per line. Every command looks like this:

command argument ...

For the deets, go read TI application report SPRAAG0E. It's giving homework, but it's the source of truth. 📚

🌸 atmelimage 🌸

The primary configuration is a comma-separated list of NAND Flash parameters, and the format is:

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

The valid parameters are:

  • usePmecc
  • nbSectorPerPage
  • spareSize
  • eccBitReq
  • sectorSize
  • eccOffset

And the valid values are decimal numbers. Want to know what values each parameter actually accepts? Section 11.4.4.1 of the SAMA5D3 Series Data Sheet, babes. That's the plug. 🔌

🌸 imximage 🌸

The primary configuration is a file containing configuration commands, and they're documented in doc/imx/mkimage/imximage.txt of the U-Boot source. Go read the file, it ate. 💖

🌸 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. Same energy, different i.MX generation. 👑

🌸 kwbimage 🌸

The primary configuration is a file containing configuration commands, as documented in doc/imx/mkimage/kwbimage.txt of the U-Boot source. Kirkwood girlies, this one's for you. 🦋

🌸 mtk_image 🌸

The primary configuration is a semicolon-separated list of header options, formatted like:

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

And the valid keys are:

  • lk — if it's 1, then an LK (legacy) image header gets used. Otherwise, a BootROM image header is used instead.
  • lkname — the name of the LK image header. Maximum length is 32 ASCII characters. If you don't specify it, the default value is U-Boot.
  • media — the boot device. Valid values are listed below, keep scrolling. ⬇️
  • nandinfo — the NAND device type you want. Valid values below too.
  • arm64 — if it's 1, then this denotes an AArch64 image.
  • hdroffset — increase the reported size of the BRLYT header by this amount.

Valid values for media 💫

  • 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 💫

  • 2k+64 — Serial, page size 2KiB, OOB size 64B
  • 2k+120 — Serial, page size 2KiB, OOB size 120B
  • 2k+128 — Serial, page size 2KiB, OOB size 128B
  • 4k+256 — Serial, page size 4KiB, OOB size 256B
  • 1g:2k+64 — Parallel, page size 2KiB, OOB size 64B, total size 1Gbit
  • 2g:2k+64 — Parallel, page size 2KiB, OOB size 64B, total size 2Gbit
  • 4g:2k+64 — Parallel, page size 2KiB, OOB size 64B, total size 4Gbit
  • 2g:2k+128 — Parallel, page size 2KiB, OOB size 128B, total size 2Gbit
  • 4g:2k+128 — Parallel, page size 2KiB, OOB size 128B, total size 4Gbit

🌸 mxsimage 🌸

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

🌸 omapimage 🌸

The primary configuration is the optional value byteswap. If it's present, each 32-bit word of the image will have its bytes swapped — converting from little-endian to big-endian, or the other way around. Flip it and reverse it. 🔄

🌸 pblimage 🌸

The primary configuration is a file containing the PBI (Pre-Boot Image) header. Every line of the config has this format:

value[ value...]

Where value is a 32-bit hexadecimal integer. Each value, after being converted to raw bytes, gets literally prepended to the PBI. No cap, it's just glued on the front. ✨

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

It's traditional to use the primary config file for the RCW (Reset Configuration Word), and the secondary config file for any additional PBI commands. But — and this is the fun part — you can also convert an existing PBI to the above format and "chain" additional data onto the end of the image. That's especially useful for creating secure boot images. 🔐

🌸 rkimage 🌸

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

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

Rockchip stans, assemble. 🪨

🌸 spkgimage 🌸

The primary configuration file consists of lines containing key/value pairs, delimited by whitespace. Here's an example, mwah:

# Comments and blank lines may be used
key1 value1
key2 value2

The supported key types are as follows:

  • VERSION
  • NAND_ECC_BLOCK_SIZE
  • NAND_ECC_ENABLE
  • NAND_ECC_SCHEME
  • NAND_BYTES_PER_ECC_BLOCK

All of these take a positive integer value as their argument. That value gets copied directly into the respective field of the SPKG header structure. For all the details on what these values should be, refer to Section 7.4 of the Renesas RZ/N1 User's Manual. 📖

  • ADD_DUMMY_BLP — takes a numeric argument, which is treated as a boolean. Any nonzero value will cause a fake BLp security header to be included in the SPKG output. Fake it till you make it, bestie. 💀
  • PADDING — takes a positive integer value, with an optional K or M suffix, indicating KiB / MiB respectively. The output SPKG file will be padded to a multiple of this value. Padding is self-care. 🎀

🌸 sunxi_egon 🌸

The primary configuration is the name to use for the device tree. Short and sweet, we love that. 🌞

🌸 ublimage 🌸

The primary configuration is a file containing configuration commands, as documented in doc/README.ublimage of the U-Boot source. Yes, it's a README, and yes, it counts. 📄

🌸 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. Different strokes. 🤷

For both image types, the secondary configuration is a file containing initialization parameters, one per line. Every 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. And heads up: at most 256 parameters may be specified this way. Don't try to sneak in a 257th, it's not happening. 🚫

🐛 BUGS 🐛

Found a bug? Please report bugs to the U-Boot bug tracker. Don't suffer in silence, bestie, tell the maintainers. 🙈

✨ EXAMPLES ✨

Okay this is the fun part — real commands you can copy-paste and feel powerful about. 💅

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

Add public key with required = "conf" property to u-boot.dtb without needing a FIT to sign. This will also create a useless FIT named unused.itb.

mkimage -f auto-conf -d /dev/null -k /public/signing-keys -g dev \
          -o sha256,rsa2048 -K u-boot.dtb -r 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

Create a FIT image containing a kernel and some device tree files, signing each configuration, using automatic mode. Moreover, the public key needed to verify signatures is added to u-boot.dtb with required = "conf" property.

mkimage -f auto-conf -A arm -O linux -T kernel -C none -a 43e00000 \
          -e 0 -d vmlinuz -b /path/to/file-1.dtb -b /path/to/file-2.dtb \
          -k /folder/with/signing-keys -g dev -o sha256,rsa2048 \
          -K u-boot.dtb -r kernel.itb

Convert an existing FIT image from any of the three types of data storage (internal, external data-offset or external data-position) to another type of data storage.

// convert FIT from internal data to data-position
mkimage -p 0x20000 -F internal_data.itb
// convert FIT from data-position to data-offset
mkimage -E -F external_data-position.itb
// convert FIT from data-offset to internal data
mkimage -F external_data-offset.itb

👀 SEE ALSO 👀

And that's the whole page, bestie!! 🎉 You made it to the end — that's main character energy fr fr. 💖

This page came from the U-Boot source, dated 2022-06-11, and it's MKIMAGE(1). Slay, go build some images. 💅✨

📦 where this page comes from