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.
• misc: The misc partition is used by recovery and is 4KB or larger.
• userdata: The userdata partition contains user-installed applications and data, including customization data.
• metadata: The metadata partition is used when device is encrypted and is 16MB or larger.
• vendor: The vendor partition 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 radio partition 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 tos partition stores the binary image of the Trusty OS and is only used if the device includes Trusty.

Flow

Here is how the bootloader operates:

1. The bootloader gets loaded first.
2. The bootloader initializes memory.
3. If A/B updates are used, determine the current slot to boot.
4. Determine whether recovery mode should be booted instead as described in Supporting updates.
5. The bootloader loads the image, which contains the kernel and RAM disk (and in Treble even more).
6. The bootloader starts loading the kernel into memory as a self-executable compressed binary.
7. The kernel decompresses itself and starts executing into memory.
8. From there on, older devices load init from the RAM disk and newer devices load it from the /system partition.
9. 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 mkbootimg implementation can be found at: system/core/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:

| 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 system/core/libsparse/sparse_format.h; it is implemented in: system/core/libsparse/sparse_read.cpp

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.