u-boot-tools (mkimage & friends)

What it is

The u-boot-tools package provides host-side utilities for U-Boot images: mkimage (wrap kernels/ramdisks/scripts into U-Boot's legacy/FIT formats), mkenvimage (binary environment images), dumpimage, and fw_printenv / fw_setenv (read/write the U-Boot environment from Linux).

Install

Debian/Ubuntu:

sudo apt install u-boot-tools

(For device-tree work also grab device-tree-compiler.)

Authenticate

None — local file manipulation tools.

Configure for this environment

Common lab uses:

# legacy uImage for a kernel
mkimage -A arm -O linux -T kernel -C none -a 0x80008000 -e 0x80008000 \
  -n "lab-kernel" -d zImage uImage

# FIT image (kernel + dtb + ramdisk) — preferred on modern boards
mkimage -f image.its fitImage.itb

# boot script
mkimage -A arm -T script -C none -n "boot script" -d boot.cmd boot.scr

# environment image
mkenvimage -s 0x20000 -o uboot.env env.txt

FIT source files (.its) and board-specific addresses live with the board bring-up docs in the firmware repo on Forgejo — don't guess addresses, copy them from the vendor BSP.

Self-hosted equivalent

Fully local tooling; no cloud equivalent exists or is needed. For OTA / A-B updates on deployed boards, the self-hosted stack is SWUpdate (swupdate on the target, update artifacts served from any LAN HTTP server or MinIO at http://192.168.0.40:9000) — that is our cloud-free alternative to managed update services like Mender cloud.

Aurélio integration

The embedded-linux skill uses mkimage when packaging kernels/ramdisks for U-Boot boards, and mentions swupdate for field update flows. No connector-registry entry — local build tooling.

Verify

mkimage -V
# mkimage version 20xx.xx ...
mkimage -l uImage        # on a real image
# Image Name:   lab-kernel
# Image Type:   ARM Linux Kernel Image (uncompressed)
# ...

Troubleshooting

mkimage: Can't open ... — input path wrong; remember -d <datafile> is the payload, output is the last positional argument.
Board rejects the image (Bad Magic Number) — wrong architecture -A or load/entry addresses; take them from the vendor BSP, not another board.
FIT fails to boot with "hash mismatch" — the .its referenced files changed after mkimage ran, or signing keys differ; rebuild the FIT and check sign-images config in U-Boot.
fw_printenv CRC error — environment not yet saved on the board (saveenv once from U-Boot), or /etc/fw_env.config offsets don't match the partition layout.

2.6 KiB Raw Blame History