{
  "added_at": "2026-11-02",
  "additional_evidence_urls": [
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/COPYING",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/Makefile",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/requirements.txt",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/docker/Dockerfile",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/patches/firmware.py",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/patches/amalgam.py",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/tools/re/README.md",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/tools/emu/README.md",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/tests/test_golden.py",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/tests/golden.json",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/docs/journal.md",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/docs/mario.md",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/.pre-commit-config.yaml",
    "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/CLAUDE.md",
    "https://github.com/BrianPugh/game-and-watch-patch/releases/tag/v0.12"
  ],
  "category": "reconstruction-cases",
  "description_en": "Custom firmware for the Mario and Zelda Game & Watch consoles that patches new C code into the user's own stock firmware backups, so the original firmware runs alongside the retro-go emulator. A Python patcher hooks stock function calls, relocates and LZMA-compresses stock code and data to free flash, and can merge both models' firmware into one image. Committed symbol maps, a cross-reference mapper and an analysis-ELF builder support the reverse engineering, and a journal records the author's first firmware-patching work.",
  "description_zh": "面向马里奥和塞尔达两款 Game & Watch 掌机的自定义固件：把新编写的 C 代码修补进使用者自己的原厂固件备份，使原厂固件可与 retro-go 模拟器并存。Python 补丁工具会挂接原厂函数调用，重新定位原厂代码与数据并以 LZMA 压缩以腾出闪存，还能把两款机型的固件合并为一个镜像。仓库提交的符号表、交叉引用分析脚本和分析用 ELF 生成器支撑逆向工作，另有一份日志记录作者首次修补固件的过程。",
  "entry_url": "https://awesomerea.org/resources/game-and-watch-patch-cfw-case/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/game-and-watch-patch-cfw-case/",
  "evidence_url": "https://github.com/BrianPugh/game-and-watch-patch/blob/857bb80fe77b60b6dabbadeae703577cc50f8645/README.md",
  "group": "cases",
  "id": "game-and-watch-patch-cfw-case",
  "json_url": "https://awesomerea.org/resources/game-and-watch-patch-cfw-case/record.json",
  "kind": "case-study",
  "markdown_url": "https://awesomerea.org/resources/game-and-watch-patch-cfw-case/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/game-and-watch-patch-cfw-case/index.md",
  "name": "game-and-watch-patch: Nintendo Game & Watch custom firmware",
  "name_zh": "game-and-watch-patch：任天堂 Game & Watch 自定义固件",
  "reconstruction_method": "other",
  "record_type": "resource",
  "relationship": "independent-reconstruction",
  "requirements": [
    "The reviewed main commit (2026-10-19) is 111 commits past the last tag, v0.12 of 2025-02-25, and no release attaches binaries; the relocation, merged-image, analysis tooling and most tests arrived after that tag. The README lists more Mario features (whole firmware in internal flash, removable song and sleep illustrations, timeouts, clock graphics mods) than Zelda ones and says Zelda's external-flash savings are still to come.",
    "Requires the user's own internal and external flash backups of a Mario or Zelda unit, placed as internal_flash_backup_<device>.bin and flash_backup_<device>.bin; the patcher rejects images whose SHA-1 does not match the stock firmware. The repository commits no firmware, ROMs or keys: tools/re/README.md says the .syms files hold only the project's annotations and that ELFs derived from Nintendo's firmware must never be committed, and docs/mario.md says no ROMs or ROM-hack patches are hosted.",
    "Targets the consoles' STM32H7B0 microcontroller. Builds need GNU Make, the arm-none-eabi GCC toolchain and Python 3.6+ with Pillow, NumPy, pycryptodome, pyelftools, capstone and colorama; flashing uses gnwmanager, and the Mario internal-only mode also needs a patched OpenOCD for an undocumented extra 128 KB of internal flash. An Ubuntu 22.04 Dockerfile installs gnwmanager's OpenOCD and Arm toolchain for x86-64 Linux hosts.",
    "tests/test_golden.py rebuilds fixed option sets and compares output SHA-1 hashes with tests/golden.json, recorded for Arm GNU Toolchain 15.2.Rel1; it skips without the stock backups or under another GCC version. Other unit tests cover relocation, Thumb assembly, layout and symbols, and tools/emu runs patched images through menu tests in the GWemu emulator. CI only runs pre-commit lint checks and builds the Docker image.",
    "COPYING is BSD-3-Clause (2020, Konrad Beckmann, Thomas Roth, STMicroelectronics); the vendored ST CMSIS and HAL sources keep their own notices, and the stock firmware and games remain Nintendo's. The repository's CLAUDE.md is guidance for Claude Code."
  ],
  "requirements_zh": [
    "所审阅的 main 提交（2026-10-19）比最后一个标签 v0.12（2025-02-25）多 111 个提交，各版本均未附带二进制文件；代码重定位、合并镜像、分析工具和大部分测试都是在该标签之后加入的。README 列出的马里奥版功能（整个固件放入内部闪存、可移除歌曲彩蛋和睡眠插图、超时设置、时钟图形修改）多于塞尔达版，并称塞尔达版节省外部闪存的功能尚待实现。",
    "需要使用者自己马里奥或塞尔达机型的内部与外部闪存备份，命名为 internal_flash_backup_<device>.bin 和 flash_backup_<device>.bin 放入仓库；补丁工具会拒绝 SHA-1 与原厂固件不符的镜像。仓库未提交任何固件、ROM 或密钥：tools/re/README.md 说明 .syms 文件只含项目自己的注释，并要求绝不提交由任天堂固件派生的 ELF；docs/mario.md 也说明仓库不托管任何 ROM 或 ROM 修改补丁。",
    "目标硬件是掌机所用的 STM32H7B0 微控制器。构建需要 GNU Make、arm-none-eabi GCC 工具链和 Python 3.6+，以及 Pillow、NumPy、pycryptodome、pyelftools、capstone 和 colorama；烧录使用 gnwmanager，马里奥版的仅内部闪存模式还需要打过补丁的 OpenOCD，以使用未公开的额外 128 KB 内部闪存。基于 Ubuntu 22.04 的 Dockerfile 会为 x86-64 Linux 主机安装 gnwmanager 提供的 OpenOCD 和 Arm 工具链。",
    "tests/test_golden.py 按固定选项组合重新构建，并将输出的 SHA-1 与 tests/golden.json 比对；这些哈希针对 Arm GNU Toolchain 15.2.Rel1 记录，缺少原厂备份或 GCC 版本不同时会跳过。其他单元测试涵盖重定位、Thumb 汇编、布局和符号，tools/emu 则在 GWemu 模拟器中对修补后的镜像运行菜单测试。CI 只运行 pre-commit 代码检查并构建 Docker 镜像。",
    "COPYING 为 BSD-3-Clause（2020，Konrad Beckmann、Thomas Roth、STMicroelectronics）；随仓库提供的 ST CMSIS 与 HAL 源码保留各自声明，原厂固件和游戏仍归任天堂所有。仓库中的 CLAUDE.md 是写给 Claude Code 的指引。"
  ],
  "targets": [
    "firmware",
    "game"
  ],
  "url": "https://github.com/BrianPugh/game-and-watch-patch",
  "verification": "source-reviewed",
  "verified_at": "2026-10-20"
}