Introduction
A zboot image is how a Linux distribution ships its kernel on a machine that boots through EFI firmware and is not x86: the Alpine
Linux 3.x vmlinuz-virt for aarch64 is one. It is a PE/COFF EFI application, so the firmware can run it directly, and inside it
is the real kernel (an ARM64 Image, in the file this page was checked against) compressed. The EFI stub
at the front of the image decompresses the payload into memory and starts it. An EFI application starts with the letters MZ of a DOS header; here the DOS header
is not a DOS stub but a small header of the kernel build's own, laid out as drivers/firmware/efi/libstub/zboot-header.S in the Linux tree writes it
(read as raw text and checked against the real file; the descriptions are our own words).
The zboot header
| Offset | Size | Field | What it holds |
|---|---|---|---|
0x00 | 4 | DOS signature | IMAGE_DOS_SIGNATURE: the letters MZ and two zero bytes. |
0x04 | 4 | Image type | The letters zimg. |
0x08 | 4 | Payload offset | Where the compressed kernel starts, counted from the start of the file (little-endian). 51,832 (0x0000CA78) in the Alpine file. |
0x0C | 4 | Payload size | The size of the compressed kernel. The source writes it as the size of the linked data minus ZBOOT_SIZE_LEN; in the real file, offset plus size is where the gzip stream ends, and the stream is complete and decompresses with its CRC-32 and size agreeing (10,353,483 bytes, unpacking to 36,306,944). |
0x10 | 8 | Reserved | Zero. |
0x18 | 32 | Compression type | The compression the kernel was built with, as a zero-ended string: gzip in the file seen. The source writes a build constant here (COMP_TYPE); other builds write the name of another compression (the viewer offers a payload with a gzip, bzip2, lzma, xz, zstd, lz4 or lzo name as a file of that kind, and only gzip was seen). |
0x38 | 4 | Linux PE magic | LINUX_PE_MAGIC, 0x818223CD. |
0x3C | 4 | PE header offset | Where the PE header (PE and two zero bytes) starts: 0x40, straight after this header. |
The explorer calls a file a zboot image only when all of this holds: MZ and two zero bytes at 0, zimg at 4, 0x818223CD at 0x38, a payload that starts at or after 0x40 and lies inside the file, and a PE signature where the header says. A plain MZ file, an EFI program that is not a zboot image, a file cut short and one with another letter in zimg all fail it.
The PE header
After the zboot header comes an ordinary PE/COFF header (Microsoft's PE format): the signature, the file header (machine, number of sections, time stamp, symbol table pointer, size of the optional header, characteristics), the optional header (PE32+ for a 64-bit kernel: entry point, base of code, alignments, size of image and headers, the subsystem and the data directories) and the section table. The machine is 0xAA64 (ARM64) in the file seen; other values the viewer names are 0x1C0 ARM, 0x1C2 ARM Thumb-2, 0x8664 x86-64, 0x14C x86, 0x5032 and 0x5064 RISC-V 32 and 64-bit, 0x6232 and 0x6264 LoongArch 32 and 64-bit. The subsystem is 10, an EFI application. The entry point is the stub's efi_zboot_entry, which the firmware calls.
The source's section table has a .text section (the stub, from the end of the headers, at file offset 4,096), a .data section and, when the build asks for it, a .sbat section. In the Alpine file the two sections are .text (10,407,936 bytes, which holds the stub's code, its read-only data and the payload) and .data (512 bytes in the file, 1,024 in memory). The headers are padded to 4,096 bytes.
What the viewer shows
The zboot header field by field, the PE header with its file header, optional header (the main fields; the rest in one node) and section table, then the sections with the payload as a node inside the section that holds it. The payload opens as a file of its own (payload.gz for gzip): the explorer then reads it as a gzip stream and, inside, an ARM64 Image. For a gzip payload the viewer reads the gzip trailer (the CRC-32 and the unpacked size, the last eight bytes) and shows both; it does not decompress the payload itself to check them. The test decompresses it with zlib: the size and CRC-32 equal the trailer and the unpacked bytes carry ARM\x64 at offset 56, which is the ARM64 Image magic.
The explorer finds it by the .efi extension (the row asks the zboot test before it hands an EFI program to the EXE viewer) and by Identify. A file with no extension, such as vmlinuz-virt, is not yet found by name alone: that needs a clause in the explorer's by-magic finder, which this change did not touch.
Checked on one real file, the Alpine aarch64 vmlinuz-virt (10,412,544 bytes), against a read of the header with Buffer reads, node's zlib and the source in samples/zimage/sources/, and on files built from it by changing a field (a cut-short file, a wrong PE signature, a wrong image type, a plain DOS header, an xz compression string).
Not described
Known, not yet covered
- Viewer: the payload is not decompressed inside this view; open the payload node for it. Only the gzip trailer is read here. Other compressions (xz, zstd, lzma, lz4, lzo, bzip2) are offered as files of that kind but were not seen in a real zboot image.
- Viewer: the stub's code is machine code of the machine the header names; it is not disassembled.
- Reference: the
.sbatsection, the debug directory and the DLL-characteristics extension the source can add are not described; the optional header's other fields are shown as one node. - Reference: whether a 32-bit (RISC-V or ARM) zboot image has the layout in the source (the source has a 32-bit branch); only a 64-bit ARM image was seen.
- Viewer: a file with no extension is not recognised by name alone (see above).
Unknown
- Reference: which other distributions use it and with which compression: the page rests on one real file and on the Linux source.
Links
Specifications
- zboot-header.S – the Linux source that writes the header (GPL-2.0)
- PE format – Microsoft's specification of the PE/COFF header
Software
- Linux – builds the image (
CONFIG_EFI_ZBOOT)