Introduction
A uImage is a file with a 64-byte header put in front of it by U-Boot’s mkimage tool, so that the boot loader knows what it
is loading, where to put it and where to start. The file inside is usually a Linux kernel (a zImage,
or an uncompressed or compressed kernel), but it can be a RAM disk, a devicetree, a script or a standalone program. This is U-Boot’s legacy
format; the newer one is a FIT image, which is a devicetree with the files inside it.
The header and its code tables are from U-Boot’s include/image.h (struct legacy_img_hdr, read through a page summary:
the tables are as that summary gave them, and the descriptions are in our words).
Header
All numbers are big-endian.
| Offset | Size | Field | What it holds |
|---|---|---|---|
0x00 | 4 | ih_magic | 0x27051956. |
0x04 | 4 | ih_hcrc | The CRC-32 of the header. See checksums. |
0x08 | 4 | ih_time | When the image was made: seconds since 1 January 1970, UTC. |
0x0C | 4 | ih_size | The size of the data after the header. |
0x10 | 4 | ih_load | The address the data is loaded to. |
0x14 | 4 | ih_ep | The entry point address. |
0x18 | 4 | ih_dcrc | The CRC-32 of the data. |
0x1C | 1 | ih_os | The operating system, a code from the tables. |
0x1D | 1 | ih_arch | The CPU architecture. |
0x1E | 1 | ih_type | The kind of image. |
0x1F | 1 | ih_comp | How the data is compressed. |
0x20 | 32 | ih_name | The image name, padded with zero bytes. |
Checksums
Both checksums are the CRC-32 that zlib, gzip and PNG use (the polynomial 0xEDB88320, reflected, starting from all ones and
inverted at the end). The header CRC is worked out over the 64 header bytes with the ih_hcrc field taken as zero, and the data
CRC over the ih_size bytes after the header. This is how U-Boot checks them, in our words. The viewer works out both and says whether they match;
when the file is shorter than the header says, the data CRC is not checked.
Data and compression
The data after the header is the file. If ih_comp is 1 (gzip), 2 (bzip2) or 3 (lzma) the explorer opens it with the extension of that
compression, so a gzip kernel opens as a gzip file and its unpacked bytes are read as a zImage or an Image by their magic. A type 8 image is read
as a devicetree. The other compressions (lzo, lz4, zstd) open as bytes.
Multi-file images
An image of type 4 holds several files. Its data starts with a list of 32-bit sizes, ended by a zero, and then the files follow one after another, each starting on a 4-byte boundary (our reading of how U-Boot walks it). The viewer shows each file as a node that opens on its own. A size list that is not ended by a zero is reported.
The code tables
Operating system (ih_os), from 0:
- Invalid OS
- OpenBSD
- NetBSD
- FreeBSD
- 4.4BSD
- Linux
- SVR4
- Esix
- Solaris
- Irix
- SCO
- Dell
- NCR
- LynxOS
- VxWorks
- pSOS
- QNX
- U-Boot (firmware)
- RTEMS
- ARTOS
- Unity OS
- INTEGRITY
- OSE
- Plan 9
- OpenRTOS
- ARM Trusted Firmware
- Trusted Execution Environment
- RISC-V OpenSBI
- EFI firmware
- ELF image
Architecture (ih_arch), from 0:
- Invalid CPU
- Alpha
- ARM
- Intel x86
- IA64
- MIPS
- MIPS 64-bit
- PowerPC
- IBM S390
- SuperH
- Sparc
- Sparc 64-bit
- M68K
- Nios-32
- MicroBlaze
- Nios-II
- Blackfin
- AVR32
- STMicroelectronics ST200
- Sandbox
- ANDES NDS32
- OpenRISC 1000
- ARM64
- Synopsys ARC
- x86_64
- Xtensa
- RISC-V
Image type (ih_type), from 0:
- Invalid image
- Standalone program
- OS kernel image
- RAM disk image
- Multi-file image
- Firmware image
- Script file
- Filesystem image
- Flat device tree blob
- Kirkwood boot image
- Freescale IMXBoot image
- Davinci UBL image
- TI OMAP config header image
- TI Davinci AIS image
- OS kernel image, can run from any load address
- Freescale PBL boot image
- Freescale MXSBoot image
- TI Keystone GPHeader image
- ATMEL ROM bootable image
- Altera SOCFPGA CV/AV preloader
- x86 setup.bin image
- LPC32XX image
- A list of typeless images
- Rockchip boot image
- Rockchip SD card
- Rockchip SPI image
- Xilinx Zynq boot image
- Xilinx ZynqMP boot image
- Xilinx ZynqMP boot image (bif)
- FPGA image
- VYBRID .vyb image
- Trusted Execution Environment OS image
- Firmware image with HABv4 IVT
- TI power management micro-controller firmware
- STMicroelectronics STM32 image
- Altera SOCFPGA A10 preloader
- MediaTek BootROM loadable image
- Freescale IMX8MBoot image
- Freescale IMX8Boot image
- Coprocessor image for remoteproc
- Allwinner eGON boot image
- Allwinner TOC0 boot image
- Flat device tree blob in a legacy image
- Renesas SPKG image
- StarFive SPL image
- TFA BL31 image
- STMicroelectronics STM32 image V2.0
- Amlogic boot image
Compression (ih_comp), from 0:
- none
- gzip
- bzip2
- lzma
- lzo
- lz4
- zstd
U-Boot adds codes over time. A code beyond these is shown as unknown and reported.
Not described
Known, not yet covered
- Viewer: the data is not disassembled here; open it (the Data node) and the explorer reads it as the file it is. Script images (type 6) have a small header of their own that is not read.
- Reference: the types that belong to particular chips (Kirkwood, i.MX, Rockchip and the others in the type table) are named but their payload formats are not described.
- Viewer: no real uImage was available for these pages. The checks were made on built images, with Node’s own zlib CRC-32 as the second route for the checksums.