Introduction
An Android device's boot loader reads a boot image from the boot partition (or recovery, and init_boot, which holds only the generic ramdisk: from memory, introduced with Android 13, not checked against a source). It starts with the eight letters ANDROID! and a header, followed by the kernel, the ramdisk and, in some versions, more parts, each padded to a page. The header is defined in bootimg.h of AOSP's system/tools/mkbootimg, read as raw text for this page (a copy is in samples/androidboot/sources; the descriptions are our own words). All numbers are little-endian.
Five header versions exist (0 to 4). The version is a 32-bit number at offset 40 in all of them. Versions 0 to 2 grow one structure into the next; version 3 is a new layout with a fixed 4096-byte page and no load addresses, which moved to the vendor boot image.
Layout of the file
Versions 0 to 2: the header, padded to one page (page_size, usually 2048 or 4096); the kernel; the ramdisk; the second stage (optional); in version 1 and later the recovery DTBO (at the offset the header gives); in version 2 the DTB. Every part is padded to a multiple of the page size: a part of n bytes takes (n + page_size − 1) / page_size pages. The loader puts each part at its physical address from the header, builds the kernel tags at tags_addr and jumps to the second stage when there is one, otherwise to the kernel.
Versions 3 and 4: the header (4096 bytes), the kernel, the ramdisk, and in version 4 the boot signature, each padded to 4096. The vendor's ramdisk, the DTB and the load addresses are in the vendor boot image, which a version 3 or 4 boot image requires; the loader loads the generic ramdisk straight after the vendor ramdisk in memory.
A partition image can also carry an AVB footer in its last 64 bytes, pointing at a vbmeta image placed after the parts.
The header, version 0
| Offset | Size | Field | What it holds |
|---|---|---|---|
| 0 | 8 | magic | ANDROID! |
| 8 | 4 | kernel_size | The kernel in bytes. |
| 12 | 4 | kernel_addr | Its physical load address. |
| 16 | 4 | ramdisk_size | The ramdisk in bytes. |
| 20 | 4 | ramdisk_addr | Its load address. |
| 24 | 4 | second_size | The second stage in bytes (0: none). |
| 28 | 4 | second_addr | Its load address. |
| 32 | 4 | tags_addr | Where the loader prepares the kernel tags. |
| 36 | 4 | page_size | The flash page size. |
| 40 | 4 | header_version | 0 here. |
| 44 | 4 | os_version | The OS version and security patch level in one word: for version A.B.C and patch level Y-M, bits 31 to 25 are A, 24 to 18 are B, 17 to 11 are C, 10 to 4 are Y − 2000 and 3 to 0 are M (all 7 bits except the month's 4). Zero means not set. |
| 48 | 16 | name | The product name, zero-ended. |
| 64 | 512 | cmdline | The kernel command line, zero-ended. |
| 576 | 32 | id | "timestamp / checksum / sha1 / etc" in the header. mkbootimg writes the SHA-1 of the kernel, ramdisk, second stage (and, for versions 1 and 2, the recovery DTBO and DTB), each followed by its size as a 32-bit little-endian number (0 for a missing part), in the first 20 bytes and zeros after. The viewer works that out and says whether the field equals it; another tool may write another value, and that is not an error. |
| 608 | 1024 | extra_cmdline | More command line, kept for compatibility. The header is 1632 bytes long. |
Versions 1 and 2
| Offset | Size | Version | Field | What it holds |
|---|---|---|---|---|
| 1632 | 4 | 1 | recovery_dtbo_size | The recovery DTBO or ACPIO image, in bytes (needed in recovery.img of a non-A/B device). |
| 1636 | 8 | 1 | recovery_dtbo_offset | Its offset in the boot image. |
| 1644 | 4 | 1 | header_size | The size of the header: 1648 in version 1, 1660 in version 2 (as mkbootimg writes them). |
| 1648 | 4 | 2 | dtb_size | The device tree blob, in bytes (required in version 2). |
| 1652 | 8 | 2 | dtb_addr | Its physical load address. |
Versions 3 and 4
| Offset | Size | Field | What it holds |
|---|---|---|---|
| 0 | 8 | magic | ANDROID! |
| 8 | 4 | kernel_size | The kernel in bytes. |
| 12 | 4 | ramdisk_size | The generic ramdisk in bytes. |
| 16 | 4 | os_version | As above. |
| 20 | 4 | header_size | The size of the header: 1580 in version 3, 1584 in version 4. |
| 24 | 16 | reserved | Four words, zero. |
| 40 | 4 | header_version | 3 or 4. |
| 44 | 1536 | cmdline | The kernel command line (the 512 and 1024 bytes of the old layout joined), zero-ended. |
| 1580 | 4 | signature_size | Version 4 only: the boot signature after the ramdisk, in bytes. |
The boot signature of a version 4 image is described by the header only as a size. The viewer opens it as an AVB vbmeta image when it starts with AVB0 and says so when it does not (our reading, not stated in the header: Google's generic kernel images sign this way).
The parts
The kernel, the ramdisk, the second stage and the DTB are ordinary files; the viewer reads the first bytes of each and offers it as a file of its own: gzip, LZ4, XZ, Zstandard, bzip2 and LZMA streams by their signature, an ARM64 Image by ARM\x64 at 56, a devicetree blob by D0 0D FE ED. A ramdisk is a cpio archive, usually compressed; the explorer has no cpio viewer yet. The recovery DTBO is the Android DT table format, not described here.
What the viewer shows
The header field by field with the OS version and patch level spelled out, the command line and the product name; the layout as nodes (header, padding, kernel, ramdisk, second stage, recovery DTBO, DTB or boot signature, the AVB footer and its vbmeta image) that tile the file exactly; and, for versions 0 to 2, whether the id is the SHA-1 mkbootimg writes. Parts that run past the end of the file, a zero kernel size and a header size field that differs from the structure are reported.
The explorer calls a file an Android boot image when it starts with ANDROID!, the header version at offset 40 is 0 to 4 and, for versions 0 to 2, the page size is a power of two between 512 and 16 MiB. The .img row asks for it by magic. A file with no extension is not found by name alone.
Checked on one real file, the boot image of a Nexus 5X (bullhead, version 0, 11,744,486 bytes) from the public Android_boot_image_editor repository's test data: the header numbers equal a read with Buffer; the kernel and ramdisk are gzip; and the SHA-1 id field equals the one worked out from the kernel and ramdisk, which confirms the part offsets and the rule above on a file not made by us. The other versions rest on built images, since no real image of them was found.
Not described
Known, not yet covered
- Viewer: the kernel, ramdisk and DTB are not unpacked inside this view; open the node. The ramdisk's cpio archive has no viewer.
- Reference: the recovery DTBO / ACPIO table format and the GKI boot signature's own structure are not described; vendor-specific headers of other boot loaders (Samsung, MediaTek and others append or change the layout) are not described.
- Viewer: the
idcheck covers versions 0 to 2 only (versions 3 and 4 have noid). - Viewer: a file with no extension is not recognised by name alone (the by-magic finder has no clause for it).
Unknown
- Reference: versions 1 to 4 were not checked against a real image, only against built ones and the header text.
Links
Specifications
- bootimg.h – the header structures (AOSP, BSD licence)
- Boot image header – Android's documentation of the versions
Software
- mkbootimg – makes and unpacks boot images (
mkbootimg.py,unpack_bootimg.py)