mtk-gpt-tool 0.1.0

Build, patch, and inspect MediaTek-style GPT partition tables from scatter XML files.

mtk-gpt-tool

Build, patch, inspect, and reverse-engineer MediaTek GPT partition images (PGPT.img / SGPT.img) from scatter XML files or plain partition-table text.

Install

git clone https://github.com/anomalyco/mtk-gpt-tool.git
cd mtk-gpt-tool
pip install -e .

Quick start

# Inspect a real device GPT
mtk-gpt inspect --pgpt PGPT.img --sector-size 4096

# Generate fresh GPT images from a scatter file
mtk-gpt generate --scatter MT6789_Android_scatter.xml --storage ufs \
  --disk-size 512GB -o ./out

# Patch existing GPT with new partition boundaries
mtk-gpt patch --scatter MT6789_Android_scatter.xml --storage ufs \
  --pgpt PGPT.img --sgpt SGPT.img --disk-size 512GB -o ./out

# Reconstruct scatter XML from a real device GPT
mtk-gpt to-scatter --scatter template.xml --storage ufs \
  --pgpt PGPT.img --sector-size 4096 -o ./reconstructed

Subcommands

Command	Description
generate	Build fresh PGPT.img/SGPT.img from scatter XML or partition table
patch	Rewrite partition entries in an existing GPT, preserving unique GUIDs
inspect	Print the layout found in an existing PGPT.img
to-scatter	Reconstruct a scatter XML from a real GPT, using another scatter as a field template
example	Run a full end-to-end demo against real firmware in bin/

Partition table file (--partitions)

Define partitions in a text file instead of a scatter XML. Two formats are supported and auto-detected.

3-column format

# name  first_lba  last_lba
boot    174592     190975
system  2717696    124956663
vendor  358400     2717695

Values can be decimal or hex (0x...).

sgdisk format

Paste sgdisk --print output directly — header and footer lines are auto-skipped:

Number  Start (sector)  End (sector)  Size       Code  Name
   1             174592         190975   64.0 MiB  0700  boot_a
   2             313856         330239   64.0 MiB  0700  boot_b
   3             358400        2717695   9216.0 MiB 0700  super
   4            2717696      124956663   477.5 GiB  0700  userdata

Lines starting with # or blank lines are also ignored.

Full workflow

# 1. Dump your device partition table
sgdisk --print /dev/block/sda > partitions.txt

# 2. Generate fresh GPT images
mtk-gpt generate --partitions partitions.txt \
  --disk-size 512GB --sector-size 4096 -o ./my_gpt

# 3. Flash
fastboot flash PGPT ./my_gpt/PGPT.img
fastboot flash SGPT ./my_gpt/SGPT.img

Built-in example

If you place firmware files in bin/ (or point MTK_FW_DIR at the directory containing PGPT.img, SGPT.img, and MT6789_Android_scatter.xml):

# Run the full demo
mtk-gpt example

# Or specify a custom firmware directory
MTK_FW_DIR=/path/to/firmware mtk-gpt example

The example walks through all 7 steps: inspect → generate → verify → partition-table input → exclude → to-scatter round-trip → patch → config file.

Excluding partitions (--exclude)

Place selected partition entries beyond disk capacity so the OS ignores them. Partition names and GUIDs stay in the table (passes preloader checks) but reads to those LBAs fail.

# Disable GenieZone partitions
mtk-gpt generate --scatter scatter.xml --storage ufs \
  --disk-size 512GB --exclude gz_a,gz_b -o ./out

# Disable via partition table file
mtk-gpt generate --partitions my_parts.txt \
  --disk-size 512GB --sector-size 4096 \
  --exclude gz_a,gz_b,gz1,gz2 -o ./out

# Also works with patch
mtk-gpt patch --scatter scatter.xml --storage ufs \
  --pgpt PGPT.img --sgpt SGPT.img --disk-size 512GB \
  --exclude gz_a -o ./out

TOML config file

Save CLI flags to a .toml file and pass --config:

# mtk-gpt-tool.toml
scatter = "./MT6789_Android_scatter.xml"
storage = "ufs"
sector_size = 4096
disk_size = 511839305728

mtk-gpt generate --config mtk-gpt-tool.toml -o ./out

The tool also auto-discovers ./mtk-gpt-tool.toml and ./.mtk-gpt-tool.toml without --config.

Options reference

Flag	Applies to	Description
--scatter <path>	generate, patch, to-scatter	MTK scatter XML input
--partitions <path>	generate, patch	Plain-text partition table (3-col or sgdisk)
--storage {ufs,emmc}	all	Storage type (default: ufs → 4096 sector)
--disk-size <size>	generate, patch	e.g. 512GB, 476GiB, or raw bytes
--sector-size <n>	all	Override sector size (default: 4096 ufs, 512 emmc)
--num-entries <n>	generate, patch	GPT entry slot count (default: exact count)
--first-usable-lba <n>	generate, patch	Override firstUsableLBA in the GPT header
--exclude <names>	generate, patch	Comma-separated partitions to disable
--pgpt <path>	inspect, patch, to-scatter	Path to PGPT.img
--sgpt <path>	patch	Path to SGPT.img
-o / --out-dir / --out <dir>	all	Output directory (default: ./out)
--out-filename <name>	to-scatter	Override output scatter filename
--config <path>	all	TOML config file with defaults

Common tasks

Task	Command
Inspect existing GPT	mtk-gpt inspect --pgpt PGPT.img --sector-size 4096
Generate from scatter	mtk-gpt generate --scatter s.xml --storage ufs --disk-size 512GB -o ./out
Generate from partition table	mtk-gpt generate --partitions parts.txt --disk-size 512GB --sector-size 4096 -o ./out
Patch	mtk-gpt patch --scatter s.xml --pgpt PGPT.img --sgpt SGPT.img --disk-size 512GB -o ./out
Disable partitions	Add --exclude gz_a,gz_b to generate or patch
Rebuild scatter	mtk-gpt to-scatter --scatter template.xml --pgpt PGPT.img --sector-size 4096 -o ./out
With config	mtk-gpt generate --config my.toml -o ./out
Full demo	mtk-gpt example (requires firmware in bin/)