Android devices include several partitions that serve different functions in the
boot process. To support A/B
updates, the device will need one slot per partition for
- boot: The
bootpartition contains a kernel image and a RAM disk combined via
mkbootimg. In order to flash the kernel directly without flashing a new boot partition, a virtual partition can be used:
- kernel: The virtual
kernelpartition overwrites only the kernel (zImage, zImage-dtb, Image.gz-dtb) by writing the new image over the old one. To do this, it determines the start location of the existing kernel image in eMMC and copies to that location, keeping in mind that the new kernel image may be larger than the existing one. The bootloader can either make space by moving any data following it or abandoning the operation with an error. If the development kernel supplied is incompatible, you may need to update the dtb partition if present, or vendor or system partition with associated kernel modules.
- ramdisk: The virtual
ramdiskpartition overwrites only the RAM disk by writing the new image over the old one. To do this, it determines the start location of the existing
ramdisk.imgin eMMC and copies to that location, keeping in mind that the new RAM disk maybe be larger than the existing one. The bootloader can either make space by moving any data following it or abandon the operation with an error.
- kernel: The virtual
- system: The
systempartition mainly contains the Android framework.
- recovery: The
recoverypartition stores the recovery image, booted during the OTA process. If the device supports A/B updates, recovery can be a RAM disk contained in the boot image rather than a separate image.
- cache: The
cachepartition stores temporary data and is optional if a device uses A/B updates. The cache partition doesn't need to be writable from the bootloader, only erasable. The size depends on the device type and the availability of space on userdata. Currently 50MB-100MB should be ok.
- misc: The
miscpartition is used by recovery and is 4KB or larger.
- userdata: The
userdatapartition contains user-installed applications and data, including customization data.
- metadata: The
metadatapartition is used when device is encrypted and is 16MB or larger.
- vendor: The
vendorpartition contains any binary that is not distributable to the Android Open Source Project (AOSP). If there is no proprietary information, this partition may be omitted.
- radio: The
radiopartition contains the radio image. This partition is only necessary for devices that include a radio that have radio-specific software in a dedicated partition.
- tos: The
tospartition stores the binary image of the Trusty OS and is only used if the device includes Trusty.
Here is how the bootloader operates:
- The bootloader gets loaded first.
- The bootloader initializes memory.
- If A/B updates are used, determine the current slot to boot.
- Determine whether recovery mode should be booted instead as described in Supporting updates.
- The bootloader loads the image, which contains the kernel and RAM disk (and in Treble even more).
- The bootloader starts loading the kernel into memory as a self-executable compressed binary.
- The kernel decompresses itself and starts executing into memory.
- From there on, older devices load
initfrom the RAM disk and newer devices load it from the
initlaunches and starts mounting all the other partitions, such as
/odm, and then starts executing code to start the device
The bootloader relies upon these images.
Kernel images are created in a standard Linux format, such as zImage, Image, or Image.gz. Kernel images can be flashed independently, combined with RAM disk images, and flashed to the boot partition or booted from memory. When creating kernel images, concatenated device-tree binaries are recommended over using a separate partition for the device tree. When using multiple Device Tree Blobs (DTBs) for different board revisions, concatenate multiple DTBs in descending order of board revision.
RAM disk images
RAM disks should contain a root file system suitable for mounting as a rootfs. RAM disk images are combined with kernel images using mkbootfs and then flashed into the boot partition.
Boot images should contain a kernel and RAM disk combined using an unmodified
mkbootimg implementation can be found at:
The bootloader reads the
header file generated by mkbootimg and updates the kernel header to contain the
correct location and size of the RAM disk in flash, base address of the kernel,
command line parameters, and more. The bootloader then appends the command line
specified in the boot image to the end of the bootloader-generated command
File system images (system, userdata, recovery)
YAFFS2 image format
If using raw NAND storage, these images must be YAFFS2, generated by an unmodified mkyaffs2image, as found in the Android Open Source Project (AOSP) at
external/yaffs2/yaffs2/utils. They have the format:
| 2k bytes of data| yaffs extra data | padding | | 0 2048 | 0 64 | variable|
The bootloader is responsible for consuming these images and relocating the yaffs extra data into the appropriate location in the out-of-band area for the given nand hardware. If software ECC is required, the bootloader should also do that computation at this time.
Sparse image format
The sparse image format should be supported. It is described in the document
"ext4 compressed images" and in
it is implemented in:
If using a block-based storage device, ext4 or f2fs should be supported. To
quickly transfer and flash large, empty ext4 file systems (userdata), store the
image in a sparse format that contains information about which areas of the file
system can be left unwritten. The file format is written by the
mke2fs utility that is also used to create the images the file
format is read and flashed by the bootloader. See the sections below for
- All fields are unsigned little-endian
- The file contains a file header, followed by a series of chunks
- The file header, chunk header, and chunk data are all multiples of 4 bytes long
- 32-bit magic: 0xed26ff3a
- 16-bit major version (0x1) - reject images with higher major versions
- 16-bit minor version (0x0) - allow images with higher minor versions
- 16-bit file header size in bytes (28 in v1.0)
- 16-bit chunk header size in bytes (12 in v1.0)
- 32-bit block size in bytes, must be multiple of 4
- 32-bit total blocks in output file
- 32-bit total chunks in input file
32-bit CRC32 checksum of original data, counting "don't care" as 0 Standard 802.3 polynomial, use a public domain table implementation
- 16-bit chunk type:
- 0xCAC1 raw
- 0xCAC2 fill
- 0xCAC3 don't care
- 16 bits reserved (write as 0, ignore on read)
- 32-bit chunk size in blocks in output image
- 32-bit total size in bytes of chunk input file including chunk header and data
- for raw, raw data, size in blocks * block size in bytes
- for fill, 4 bytes of fill data
Implementing the writer
mke2fs utility already knows what areas of the image need
to be written, and will encode "don't care" chunks between them. Another tool,
img2simg, will convert regular (non-sparse) images to sparse
images. Regular images have no information about "don't care" areas; the best a
conversion can do is look for blocks of repeated data to reduce the resulting
Implementing the reader
Readers should reject images with unknown major versions and should accept images with unknown minor versions. Readers may reject images with chunk sizes they do not support.
Once the major version is validated, the reader should ignore chunks with unknown type fields. It should skip over the chunk in the file using the "chunk size in file" and skip "chunk size in blocks" blocks on the output.
A Cyclic Redundancy Check - 802.3 CRC32 - should be calculated for the data that
will be written to disk. Any area that is not written (don't care, or a skipped
chunk), should be counted as 0s in the CRC. The total number of blocks written
or skipped should be compared against the "total blocks" field in the header.
simg2img will convert the sparse image format to a
standard image, which will lose the sparse information.