How MagiskBoot Handles Different Boot Image Formats (AOSP, ChromeOS, DHTB, MTK)

MagiskBoot detects boot image formats by scanning for magic numbers in check_fmt, then sets format-specific flags like CHROMEOS_FLAG or DHTB_FLAG to control how the image is parsed, unpacked, and repacked.

MagiskBoot is the low-level boot image manipulation tool in the topjohnwu/Magisk repository. Understanding how MagiskBoot handles different boot image formats is essential for developers working with custom Android recoveries, kernels, or root solutions on devices using AOSP, ChromeOS, DHTB, or MediaTek structures.

Format Detection and Magic Number Identification

MagiskBoot identifies boot image formats through the check_fmt function in [native/src/boot/bootimg.cpp](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L69-L99). This function examines the raw file buffer for specific magic signatures and returns a FileFormat enum value.

The constructor boot_img::boot_img iterates through the image bytes, calling check_fmt at each offset until it recognizes a format. The detection logic handles four primary formats:

• AOSP: Identified by BOOT_MAGIC (typically "ANDROID!")
• ChromeOS: Identified by CHROMEOS_MAGIC
• DHTB: Identified by DHTB_MAGIC (Dynamic Header Boot)
• MTK: Identified by MTK_MAGIC (MediaTek proprietary headers)

AOSP Boot Image Handling

When check_fmt returns FileFormat::AOSP, MagiskBoot processes the image as a standard Android boot image. The code invokes parse_image with the detected format to extract the kernel, ramdisk, second stage bootloader, device tree blob (DTB), and recovery DTBO.

AOSP images use dynamic header parsing via parse_hdr, which creates concrete subclasses like dyn_img_v0 through dyn_img_v4 to handle different header versions. The standard AOSP path does not set special format flags, allowing the generic unpack/repack workflow to proceed without proprietary wrapper handling.

ChromeOS Boot Image Handling

ChromeOS boot images trigger the CHROMEOS_FLAG when detected. Unlike AOSP images, ChromeOS formats require external signing tools and do not follow the standard repackaging flow.

When MagiskBoot encounters a ChromeOS image, it sets flags[CHROMEOS_FLAG] = true, extracts the payload, and returns RETURN_CHROMEOS immediately after header parsing. This early exit prevents MagiskBoot from attempting to resign the image, deferring instead to ChromeOS-specific signing utilities.

# Unpacking a ChromeOS boot image

magiskboot unpack --chromeos boot.img

# Returns special code indicating ChromeOS format detected

DHTB (Dynamic Header Boot) Handling

DHTB format detection sets both DHTB_FLAG and SEANDROID_FLAG. This format includes a proprietary pre-header that must be preserved during modifications.

During unpacking, MagiskBoot parses and stores the DHTB header (dhtb_hdr), then strips it from the payload while preserving the original header size for repacking. During repack in boot_img::repack, the DHTB header is written first to the output image, followed by the payload. A SHA-256 checksum of the entire payload (including trailing SEANDROID magic) is calculated and written to the DHTB header at lines 1028-1034.

// DHTB header restoration during repack
if (flags[DHTB_FLAG]) {
    // Copy DHTB header back to output
    memcpy(out_buf, &dhtb_hdr, sizeof(dhtb_hdr));
}

MTK (MediaTek) Boot Image Handling

MediaTek devices use proprietary MTK headers for kernel and ramdisk partitions. When check_fmt identifies MTK_MAGIC, MagiskBoot sets MTK_KERNEL or MTK_RAMDISK flags accordingly.

The MTK handling process stores pointers to k_hdr (kernel header) or r_hdr (ramdisk header), prints header fields for debugging, and strips the MTK header before further processing. During repack at lines 765-773 and 106-108, MagiskBoot re-adds the original MTK headers to the beginning of kernel and ramdisk blocks to ensure MediaTek bootloaders can validate the image structure.

# MagiskBoot automatically detects and handles MTK headers

magiskboot unpack boot.img

# Output shows: MTK_KERNEL_HDR, SIZE, NAME

magiskboot repack boot.img new_boot.img

# MTK headers automatically prepended

Practical Code Examples

Unpacking automatically detected formats:

# Generic unpack - detects AOSP, DHTB, MTK automatically

magiskboot unpack boot.img

Handling ChromeOS specifically:

magiskboot unpack --chromeos chromeos_boot.img

# Check return code for RETURN_CHROMEOS

Repacking with format preservation:

# Edit kernel or ramdisk files, then repack

# DHTB headers and MTK headers are automatically preserved

magiskboot repack original_boot.img modified_boot.img

Key Source Files

Understanding MagiskBoot's format handling requires examining these specific files:

• [native/src/boot/bootimg.cpp](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp) - Core implementation containing check_fmt, format detection loop, and repack logic for DHTB and MTK formats
• [native/src/boot/bootimg.hpp](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.hpp) - Class declarations for boot_img, dyn_img_hdr, and format flags
• [native/src/boot/magiskboot.hpp](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/magiskboot.hpp) - Defines FileFormat enum and magic constants (CHROMEOS_MAGIC, DHTB_MAGIC, MTK_MAGIC)
• [docs/boot.md](https://github.com/topjohnwu/Magisk/blob/master/docs/boot.md) - Documentation covering boot image concepts and vendor-specific implementations

Summary

• MagiskBoot identifies boot image formats through magic number scanning in the check_fmt function
• AOSP images use standard parsing without special flags
• ChromeOS images set CHROMEOS_FLAG and require external signing tools after unpacking
• DHTB images preserve a proprietary pre-header and require SHA-256 checksum recalculation during repack
• MTK images strip and restore MediaTek-specific headers for kernel and ramdisk partitions
• All format-specific handling is centralized in native/src/boot/bootimg.cpp with flags controlling the repackaging workflow

Frequently Asked Questions

What is the difference between AOSP and vendor boot images in MagiskBoot?

AOSP images follow the standard Android boot image specification with headers containing "ANDROID!" magic. Vendor images like DHTB or MTK wrap the standard payload with proprietary headers. MagiskBoot detects these via additional magic numbers and sets flags (DHTB_FLAG, MTK_KERNEL) to ensure the proprietary structures are preserved during modification.

How does MagiskBoot preserve DHTB headers when repacking?

During unpacking, MagiskBoot stores the DHTB header separately and strips it from the payload. In the repack method, it writes the original DHTB header back to the output file first, then appends the modified payload. Finally, it calculates a new SHA-256 checksum of the entire image and updates the checksum field in the DHTB header at lines 1028-1034.

Why does ChromeOS boot image handling require external signing tools?

ChromeOS boot images use proprietary signing keys and verification mechanisms that MagiskBoot cannot replicate. When CHROMEOS_FLAG is set, MagiskBoot extracts the payload but returns RETURN_CHROMEOS to signal that the image requires ChromeOS-specific signing utilities to complete the repackaging process securely.

Can MagiskBoot handle combined MTK and DHTB formats?

Yes, MagiskBoot's flag-based architecture allows multiple format flags to be set simultaneously. If an image contains both MTK headers and DHTB wrappers, both MTK_KERNEL/MTK_RAMDISK and DHTB_FLAG will be active. The repack process restores both the MTK headers for individual partitions and the DHTB wrapper for the entire image.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}