legacy-firmware-reversing

A field-tested Agent Skill + DSH plugin for reverse engineering, localizing, and safely re-flashing black-box legacy embedded firmware.

Distilled from a multi-agent, 26-firmware-cycle live campaign against a 2004 Sharp MP-B300 (SigmaTel STMP3560 SoC · Motorola DSP56004 core · Sanyo LV24002 FM tuner) — a device with no source code, no public flashing docs, and a vendor that no longer exists.

中文说明（README.zh-CN.md） · CREDITS · License: MIT

---

What's inside

├── SKILL.md                  Agent Skill entry (open Agent-Skills frontmatter format)
├── references/               Deep-dive guides for the five methodology pillars
│   ├── protocol_and_safe_flashing.md        BOT short-packet trap, sector-tail integrity, zero-brick gates
│   ├── font_and_resource_injection.md       24-bit resource tree, private glyph dictionary, GB2312 full injection
│   ├── dsp_and_jit_emulation.md             DSP56004 disasm, surrogate stubs, peripheral mocking, whole-memory diff
│   ├── hardware_vs_software_falsification.md  single-variable falsification, the do-a0 trap, 4-step hardware-boundary test
│   └── multi_agent_collaboration_protocol.md  PROJECT-STATE.md single-source-of-truth discipline
├── templates/
│   ├── PROJECT-STATE.template.md   multi-agent single source of truth
│   ├── EXPERIMENTS.template.md     falsification logbook discipline
│   ├── safe_flasher.py             zero-brick flashing skeleton (asserts BEFORE touching the device)
│   └── surrogate_stub.S            DSP56300 stub template (div/message-log/blanket-rts) + known landmines
├── package.json              dsh-fw-recon — installable DSH plugin package (dsh.bundle.patch)
├── cordis.patch.yml          bundle patch: mounts the plugin when installed
├── lib/core.js               safety gate / twin-image diff / experiment formatter (pure functions)
├── lib/index.js              cordis service registration
├── bin/cli.js                standalone CLI: fw-recon check|diff|log
├── case-studies/MP-B300.md   the campaign this came from
└── CREDITS.md                real-name attributions (see below)

The five pillars

1. Protocol reverse engineering with a zero-brick guarantee — vendor SCSI commands, the USB BOT short-packet termination trap, flash sector-tail whitelisting, protected-page assertions, and a rollback chain that is preset before every flash.
2. Proprietary resource-tree reconstruction & full localization — 24-bit binary descriptors, glyph-ID recovery by visual anchoring, zero-growth full-charset injection (6,763 GB2312 glyphs injected into a Japanese font with zero byte-size change).
3. Heterogeneous DSP disassembly + PC JIT emulation with surrogate stubs — don't reverse the whole kernel; stub its call sites, run the extracted module on xemu-project/dsp56300, and diff entire memory spaces between two critical inputs (89.9 vs 90.0 MHz → one variable).
4. Falsification over inference — 26 firmware cycles, every hypothesis tested by a single-variable change and a human-observed result; the discipline that separates "the cliff moved" from "the cliff is physical".
5. Multi-agent anti-drift collaboration — a PROJECT-STATE.md single source of truth with a falsification matrix, so three different AI agents (DeepSeek, Gemini, GLM) could relay the same campaign without repeating each other's dead ends.

Using it

As an Agent Skill (Claude / ZCode / any Agent-Skills-compatible harness)

Copy or symlink this repo into your skills directory, or just feed SKILL.md to your agent as context when facing a black-box firmware task. The references are loaded on demand.

As a DSH plugin

# installs the package and mounts it through its bundled cordis.patch.yml
dsh plugin --profile <profile> add github:Gladess1102/legacy-firmware-reversing

# from a local checkout
dsh plugin --profile <profile> add /absolute/path/to/legacy-firmware-reversing

Desktop App users: since DSH 0.2.1-rc.2 the CLI hard-rejects the desktop profile (profile "desktop" is managed exclusively by the Electron application), so dsh plugin --profile desktop … cannot work. Install through the App's GUI plugin page instead, or run pnpm add inside ~/.dsh/profiles/desktop and add the package to that profile's dsh.profile.bundles. Restart the App afterwards either way.

Restart DSH afterwards. The plugin registers an fw-recon cordis service for other plugins to consume via ctx.get("fw-recon"); it does not add tools to the model's tool list. The CLI below works with or without DSH.

Experiment logging writes into the configured workDir, which is unset by default — no directory is ever created on your Desktop. Set FW_RECON_WORKDIR or fill in the plugin's settings card before the first logExperiment.

As a standalone CLI (no DSH needed)

# safety gate before any flash — asserts size, protected pages, sector-tail whitelist
fw-recon check  --img new.bin --baseline factory.bin

# twin-image diff, sector tails stripped so code diffs stay clean
fw-recon diff   v10.bin v27.bin --strip

# falsification logbook (enforces expected-before-observed discipline)
fw-recon log    --id E27 --hypothesis "upper-limit checks gate the mute" \
                --action "NOP 2 jlt at 0x16b03/0x16b2d" \
                --expected "cliff moves above 108MHz" \
                --observed "cliff still at 90.0, boot normal" \
                --verdict falsified

Results this methodology delivered (MP-B300)

• Full Chinese localization (280 UI strings + 6,763-glyph GB2312 font) with zero image growth
• 1 GB full-NAND dump and 431 MB user-music recovery
• Complete SCSI vendor-command protocol, 3-wire tuner pinout, tuning-formula and AFC-model recovery
• A definitive verdict: the 90 MHz cliff's handler lives in a runtime-constructed RAM table — out of reach of any static patch, documented with a hardware escape route

Full campaign log: case-studies/MP-B300.md.

Attribution

This stands on real people's work: mborgerson (DSP56300 JIT emulator), Ivan Zupan (Rockbox LV24020LP driver), the Rockbox community (hosting Sanyo's AN2400S04 appnote), and public SigmaTel/Sanyo documentation — plus three AI agents (DSH/DeepSeek, Antigravity/Gemini, ZCode/GLM) and one human operator who ran every experiment. Full real-name credits: CREDITS.md — please keep them intact in forks.

Author

gladess (小G) — device owner, campaign lead, and the human hands behind all 26 flash cycles (GitHub: Gladess1102). The three AI agents (DSH/DeepSeek, Antigravity/Gemini, ZCode/GLM) did the analysis; every brick-risk decision and every listening test was his. Full team credits in CREDITS.md.

License

MIT — see LICENSE. Not affiliated with Sharp, SigmaTel/Freescale, or Sanyo. Vendor documents are cited, not redistributed.