83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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.
|