Metadata-Version: 2.4
Name: mtk-gpt-tool
Version: 0.1.0
Summary: Build, patch, and inspect MediaTek-style GPT partition tables from scatter XML files.
Author: mtk-gpt-tool contributors
License-Expression: MPL-2.0
Project-URL: Homepage, https://github.com/anomalyco/mtk-gpt-tool
Project-URL: Source, https://github.com/anomalyco/mtk-gpt-tool
Project-URL: BugTracker, https://github.com/anomalyco/mtk-gpt-tool/issues
Keywords: mtk,mediatek,gpt,partition,scatter,ufs,emmc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

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

## Quick start

```bash
# 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

```bash
# 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`):

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

```bash
# 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`:

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

```bash
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/`) |
