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

> Discover how MagiskBoot detects and handles diverse boot image formats like AOSP, ChromeOS, DHTB, and MTK. Learn its magic number scanning and format-specific flag system for parsing, unpacking, and repacking.

- Repository: [John Wu/Magisk](https://github.com/topjohnwu/Magisk)
- Tags: internals
- Published: 2026-03-05

---

**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](https://github.com/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/main/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`](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L111-L132) 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.

```bash

# 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`](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L749-L756), 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](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L1028-L1034).

```cpp
// 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](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L765-L773) and [106-108](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L106-L108), MagiskBoot re-adds the original MTK headers to the beginning of kernel and ramdisk blocks to ensure MediaTek bootloaders can validate the image structure.

```bash

# 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:**

```bash

# Generic unpack - detects AOSP, DHTB, MTK automatically

magiskboot unpack boot.img

```

**Handling ChromeOS specifically:**

```bash
magiskboot unpack --chromeos chromeos_boot.img

# Check return code for RETURN_CHROMEOS

```

**Repacking with format preservation:**

```bash

# 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/main/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/main/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/main/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/main/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`](https://github.com/topjohnwu/Magisk/blob/main/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`](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L749-L756) 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](https://github.com/topjohnwu/Magisk/blob/master/native/src/boot/bootimg.cpp#L1028-L1034).

### 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.