mtk-wifi-fw/README.md

# mtk-wifi-fw (working name)

Tooling, documentation, and update tracking for MediaTek Connac2 WiFi
firmware blobs (`mt7915/7916/7981/7986_{wm,wa,rom_patch}.bin` as shipped in
linux-firmware) — the WiFi firmware running on Filogic 820/830 routers
(GL.iNet, Banana Pi, Xiaomi, Netgear, TP-Link, ...).

MTK strips version strings from these blobs (`fw_ver = "____000000"`) and
ships silent updates; this project recovers the version metadata, documents
the container formats, and diffs builds so changes are visible.

## What's here

- `tools/mtk_fw_extract.py` — carve containers into regions + manifest
  (plaintext NDS32 code/data at true load addresses)
- `tools/mtk_fw_elf.py` — emit `EM_NDS32` ELF per blob (Ghidra-ready,
  PT_LOAD per region)
- `tools/fw_history.py` — walk a linux-firmware git checkout and recover
  every revision's build metadata → `dataset/history.jsonl`
- `tools/fw_diff.py` — version diff: region-aligned byte equality +
  plausible string-set changes (the human-readable changelog)
- `docs/format.md` — container format spec, cited to kernel source
- `docs/boot.md` — the four images / three cores, load sequence, cited
- `docs/findings.md` — verified-claims log + unknowns registry
- `docs/reports/` — pilot version-diff reports (mt7981 2022→2024→2026)
- `tests/` — golden-manifest + emitter tests

## Quickstart

    # any host with linux-firmware's mediatek blobs (or set MTK_FW_DIR):
    make extract     # carve every mt79xx wm/wa/patch blob found
    make elf         # emit ELFs into extracted/<blob>/<blob>.elf
    make test        # golden tests (skips if no blobs present)

    # full dataset from linux-firmware history (~5 min clone):
    git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git firmware/linux-firmware
    python3 tools/fw_history.py firmware/linux-firmware -o dataset/history.jsonl
    python3 tools/fw_diff.py old.bin new.bin --md report.md

No proprietary firmware bytes are committed to this repository. Tools operate
on blobs from your own linux-firmware copy. Derived artifacts under
`extracted*/` and `firmware/` are gitignored.

## Conventions

Every documented claim cites evidence (kernel source line, blob offset) or is
marked unknown — see `docs/findings.md`. When a golden test fails against a
newer snapshot, the blob changed: update the golden *and* record the diff.

License: MIT (code), CC-BY-SA-4.0 (docs). Project log and decision function:
[PLAN.md](PLAN.md).