bench51 — a TUI 8051 assembler, simulator & debugger

A small, Keil µVision-style IDE for the Intel 8051 that runs in your terminal. Write assembly in the built-in editor, assemble it, inspect the listing and Intel HEX output, then run, pause and single-step the program while watching registers, SFRs, memory, ports, timers, interrupts and the serial port.

Built in Rust with ratatui. It is a learning tool, not a cycle-exact replacement for a vendor simulator.

Features

• Editor with undo/redo, breakpoint and error markers in the gutter — or press Ctrl-G to edit in your own $EDITOR (vim, nvim, nano, …).
• Two-pass assembler for the full 8051 instruction set (all 255 opcodes):
  • labels, expressions (+ - * / MOD AND OR XOR NOT SHL SHR HIGH LOW, $)
  • number formats 42, 2Ah, 0x2A, 101010b, 52o, '*'
  • bit addressing (P1.3, ACC.7, 20h.0) and all predefined SFR/bit names
  • directives ORG DB DW DS END EQU SET BIT DATA IDATA XDATA CODE CSEG AT
  • generic JMP/CALL (assembled as LJMP/LCALL)
  • Keil-style .lst listing with symbol table, Intel HEX output
• Simulator
  • all instructions with correct flags (CY, AC, OV, P) and machine-cycle counts
  • 4 register banks, 256 bytes IRAM, SFRs, 64K code, 64K XRAM
  • ports P0–P3 with latch vs. pin semantics (read-modify-write reads the latch)
  • timers 0/1 in modes 0–3, gate and counter inputs
  • interrupts: INT0, T0, INT1, T1, serial; two priority levels; edge/level triggers
  • UART in modes 0–3 with baud rate timing from timer 1
  • idle and power-down modes (PCON)
• Debugger: run / pause, step into / over / out, run to cursor, breakpoints, changed-value highlighting, memory poke, adjustable speed.
• Open .hex files: they're disassembled into editable source that re-assembles to the identical image.

Usage

cargo install --path .                               # installs the `bench51` binary

cargo run --release -- examples/serial_hello.asm      # open in the TUI
cargo run --release                                   # start with a template
cargo run --release -- firmware.hex                   # disassemble & debug a HEX file

# Headless assembly: writes prog.hex and prog.lst
cargo run --release -- --assemble prog.asm
cargo run --release -- --assemble prog.asm -o out.hex --lst out.lst

--clock <MHz> sets the oscillator frequency used for the elapsed-time display (default 11.0592).

Keys

Edit mode: Alt-1/2/3 switch between Listing, HEX and Errors; Alt-↑/↓, Alt-PgUp/PgDn scroll them. The editor uses Emacs-style keys (Ctrl-U undo, Ctrl-R redo, Ctrl-Y paste).

Debug mode: Tab cycles focus between Source, Memory, Ports and Serial. Letter shortcuts work too, for terminals that swallow function keys: r run/pause, s step, n step over, o step out, g run to cursor, b breakpoint, x reset, i/f/d/c show IRAM/SFR/XRAM/CODE, p poke memory, +/- speed, . jump to PC, Esc pause / back to editor.

• Ports: select a pin and press Space to pull it low from outside (a button press); the program sees the pin as latch AND external level.
• Serial: type a line and press Enter to send it (followed by CR) to the 8051's receiver; everything the 8051 transmits appears above.

Examples

Notes and limitations

• Indirect addressing reaches all 256 bytes of IRAM (8052-style upper 128).
• Serial input has no 9th data bit; in modes 2/3 RB8 reads 0.
• No 8052 timer 2, external code memory or on-chip peripherals of derivatives.

Development

cargo test     # assembler, CPU, peripheral and example-program tests
cargo clippy

Code layout: src/isa.rs (opcode table shared by everything), src/asm/ (assembler, listing, Intel HEX), src/sim/ (CPU, peripherals, disassembler), src/ui/ (ratatui front end).