AwesomeREA.org

Tool

BREAD

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.

Requirements & limits

  • 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. This review built and ran nothing. MIT license by Davidson Francis; firmware and programs being debugged keep their own rights, and the reviewed sources establish no REA connection.

About this entry

Type
Tool
Category
Debugging and dynamic analysis
Relationship
Foundation tool
Targets
Binary · Firmware

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · Theldus/bread · Revision 700807e
  2. README.md#L99-L134 GitHub · Theldus/bread · Revision 700807e
  3. README.md#L136-L282 GitHub · Theldus/bread · Revision 700807e
  4. Makefile GitHub · Theldus/bread · Revision 700807e
  5. dbg.asm GitHub · Theldus/bread · Revision 700807e
  6. symbolify.py GitHub · Theldus/bread · Revision 700807e
  7. .gdbinit GitHub · Theldus/bread · Revision 700807e
  8. LICENSE GitHub · Theldus/bread · Revision 700807e
  9. https://github.com/Theldus/bread/commit/700807ef312db8bb765f88eb4f702bc22b7b2858

More in Native binaries

All 105 entries in Native binaries