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.