Partitions and Images

Partitions

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, system, vendor, and
radio.

boot: The boot partition 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 kernel partition
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 ramdisk partition
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.img
in 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.

system: The system partition mainly contains
the Android framework.

recovery: The recovery partition 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 cache partition 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.

Flow

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 init from the RAM disk and
newer devices load it from the /system partition.

From /system, init launches and starts mounting
all the other partitions, such as /vendor, /oem, and
/odm, and then starts executing code to start the device

Images

The bootloader relies upon these images.

Kernel 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

Boot images should contain a kernel and RAM disk combined using an unmodified
mkbootimg.

The bootloader reads the bootimg.h
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
line.

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:

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.

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
attributes:

File format

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

Header

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

Chunk

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

Data

for raw, raw data, size in blocks * block size in bytes

for fill, 4 bytes of fill data

Implementing the writer

The 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
image size.

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.
The tool simg2img will convert the sparse image format to a
standard image, which will lose the sparse information.

Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.