{
  "added_at": "2026-11-02",
  "additional_evidence_urls": [
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/README.md#L99-L134",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/README.md#L136-L282",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/Makefile",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/dbg.asm",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/symbolify.py",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/.gdbinit",
    "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/LICENSE",
    "https://github.com/Theldus/bread/commit/700807ef312db8bb765f88eb4f702bc22b7b2858"
  ],
  "category": "dynamic-analysis",
  "description_en": "Injectable real-mode x86 debugger for legacy BIOS code, boot code and DOS programs on real hardware or in a virtual machine. A small 16-bit assembly stub placed in the target code installs interrupt handlers, single-steps the processor and talks over a serial line to a Linux bridge, which translates its simple packets into the GDB remote protocol so GDB can read and write memory and registers, step, continue and set one hardware breakpoint and one watchpoint at a time. A companion script turns an address–label list into a minimal ELF symbol file for GDB.",
  "description_zh": "可注入的 x86 实模式调试器，用于在真实硬件或虚拟机上调试传统 BIOS 代码、引导代码和 DOS 程序。放入目标代码中的 16 位汇编小程序会安装中断处理程序、让处理器单步执行，并通过串口与 Linux 上的桥接程序通信；桥接程序把这些简化报文转换为 GDB 远程协议，使 GDB 能读写内存和寄存器、单步、继续执行，并可同时设置一个硬件断点和一个观察点。配套脚本可将地址与标签列表转换为供 GDB 加载的最小 ELF 符号文件。",
  "entry_url": "https://awesomerea.org/resources/bread-bios-debugger/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/bread-bios-debugger/",
  "evidence_url": "https://github.com/Theldus/bread/blob/700807ef312db8bb765f88eb4f702bc22b7b2858/README.md",
  "group": "tools",
  "id": "bread-bios-debugger",
  "json_url": "https://awesomerea.org/resources/bread-bios-debugger/record.json",
  "kind": "tool",
  "markdown_url": "https://awesomerea.org/resources/bread-bios-debugger/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/bread-bios-debugger/index.md",
  "name": "BREAD",
  "name_zh": "BREAD BIOS 实模式调试器",
  "record_type": "resource",
  "relationship": "foundation",
  "requirements": [
    "No releases are published. The reviewed master commit of 2025-10-21 fixes EIP handling in the interrupt-based mode; the previous code change, adding the symbolify tool, dates from 2023-10-19. Building needs a Linux host with GNU Make, a C compiler such as GCC, Clang or TCC, and NASM. The default build polls the UART at full CPU load, while UART_POLLING=no selects the interrupt-based mode, which is not the default because interrupts are not always enabled.",
    "dbg.asm must be edited for each target, changing its ORG and return path and restoring any instructions replaced by the call into it, and the assembled dbg.bin then goes into the user’s own BIOS ROM image or runs as a DOS .COM program from a minimal FreeDOS or DOS boot floppy. Real hardware needs a serial connection to the Linux host. The repository ships no ROM; symbols/ami_ipm41d3.txt holds the author’s symbol names for one PCWare IPM41-D3 AMI legacy BIOS, which its header calls the author’s interpretation, not official or leaked symbols.",
    "The README lists limits: the debugged code is unaware of the debugger, so a switch to protected mode, a changed IDT or a missing stack stops it from working, and BIOS code cannot be followed from the boot block because RAM must already be set up; a warm reboot can replay initialisation but may take a different path from a cold boot. Virtual machines need debug-register support, from a Bochs build with its x86 debugger enabled or QEMU with KVM, which the bundled qemu target uses with a floppy built from the included boot sector and debugger.",
    "The repository has no tests or CI; the README links a demonstration video that changes the CPU name string. MIT license by Davidson Francis; firmware and programs being debugged keep their own rights."
  ],
  "requirements_zh": [
    "项目未发布任何版本。所审阅的 master 提交（2025-10-21）修复了中断模式下的 EIP 处理问题；上一次代码改动是 2023-10-19 加入 symbolify 工具。构建需要 Linux 主机、GNU Make、GCC、Clang 或 TCC 等 C 编译器以及 NASM。默认构建以轮询方式读取 UART，会占满 CPU；UART_POLLING=no 可改为中断模式，但由于中断并非总是启用，该模式不是默认选项。",
    "每个目标都需要修改 dbg.asm：调整 ORG 和返回方式，并恢复为调用调试器而被替换的指令；汇编得到的 dbg.bin 随后放入使用者自有的 BIOS ROM 镜像，或作为 DOS .COM 程序在最小 FreeDOS 或 DOS 启动软盘中运行。在真实硬件上调试需通过串口连接 Linux 主机。仓库不附带任何 ROM；symbols/ami_ipm41d3.txt 是作者为一款 PCWare IPM41-D3 AMI 传统 BIOS 整理的符号名，文件头说明这只是作者自己的理解，并非官方或泄露的符号。",
    "README 列出的限制包括：被调试代码并不知道调试器存在，因此切换到保护模式、修改 IDT 或缺少可用栈都会使调试器失效；BIOS 代码无法从启动块开始跟踪，因为调试器需要内存已完成初始化；热重启虽可重新走一遍初始化流程，但路径可能与冷启动不同。虚拟机需支持调试寄存器：Bochs 需启用其 x86 调试器编译，QEMU 需启用 KVM；仓库自带的 qemu 目标即启用 KVM，并使用由随附引导扇区和调试器生成的软盘镜像。",
    "仓库没有测试或 CI；README 链接了一段修改 CPU 名称字符串的演示视频。采用 MIT 许可证，作者为 Davidson Francis；被调试的固件和程序仍有各自权利。"
  ],
  "targets": [
    "binary",
    "firmware"
  ],
  "url": "https://github.com/Theldus/bread",
  "verification": "source-reviewed",
  "verified_at": "2026-10-20"
}