| 1 | # bench51 — a TUI 8051 assembler, simulator & debugger |
| 2 | |
| 3 | A small, Keil µVision-style IDE for the Intel 8051 that runs in your terminal. |
| 4 | Write assembly in the built-in editor, assemble it, inspect the listing and |
| 5 | Intel HEX output, then run, pause and single-step the program while watching |
| 6 | registers, SFRs, memory, ports, timers, interrupts and the serial port. |
| 7 | |
| 8 | Built in Rust with [ratatui](https://ratatui.rs). It is a learning tool, not a |
| 9 | cycle-exact replacement for a vendor simulator. |
| 10 | |
| 11 |  |
| 12 | |
| 13 | <table> |
| 14 | <tr> |
| 15 | <td width="50%"><img src="docs/screenshots/listing.png" alt="Editor with the assembled Keil-style listing"></td> |
| 16 | <td width="50%"><img src="docs/screenshots/debug_breakpoint.png" alt="Stopped at a breakpoint inside the timer 0 ISR, SFR view"></td> |
| 17 | </tr> |
| 18 | <tr> |
| 19 | <td align="center"><sub>Editor + assembled listing</sub></td> |
| 20 | <td align="center"><sub>Breakpoint inside a timer ISR, SFR view</sub></td> |
| 21 | </tr> |
| 22 | <tr> |
| 23 | <td width="50%"><img src="docs/screenshots/errors.png" alt="Assembler errors marked in the gutter and listed in the Errors tab"></td> |
| 24 | <td width="50%"><img src="docs/screenshots/hex.png" alt="Intel HEX output tab"></td> |
| 25 | </tr> |
| 26 | <tr> |
| 27 | <td align="center"><sub>Assembler errors in the gutter and Errors tab</sub></td> |
| 28 | <td align="center"><sub>Intel HEX output</sub></td> |
| 29 | </tr> |
| 30 | </table> |
| 31 | |
| 32 | ## Why this exists |
| 33 | |
| 34 | I had microcontroller practicals to get through, and the course expects you to |
| 35 | use Keil µVision. Keil µVision doesn't run on Linux. Rather than fight with |
| 36 | Wine or a Windows VM every lab session, I wrote my own: bench51 does the parts |
| 37 | of µVision those practicals actually need (write the code, assemble it, look |
| 38 | at the listing and HEX, step through it and watch the registers) right in the |
| 39 | terminal. |
| 40 | |
| 41 | ----- |
| 42 | |
| 43 | ## Features |
| 44 | |
| 45 | - **Editor** with undo/redo, breakpoint and error markers in the gutter — |
| 46 | or press Ctrl-G to edit in your own `$EDITOR` (vim, nvim, nano, …). |
| 47 | - **Two-pass assembler** for the full 8051 instruction set (all 255 opcodes): |
| 48 | - labels, expressions (`+ - * / MOD AND OR XOR NOT SHL SHR HIGH LOW`, `$`) |
| 49 | - number formats `42`, `2Ah`, `0x2A`, `101010b`, `52o`, `'*'` |
| 50 | - bit addressing (`P1.3`, `ACC.7`, `20h.0`) and all predefined SFR/bit names |
| 51 | - directives `ORG DB DW DS END EQU SET BIT DATA IDATA XDATA CODE CSEG AT` |
| 52 | - generic `JMP`/`CALL` (assembled as `LJMP`/`LCALL`) |
| 53 | - Keil-style `.lst` listing with symbol table, Intel HEX output |
| 54 | - **Simulator** |
| 55 | - all instructions with correct flags (CY, AC, OV, P) and machine-cycle counts |
| 56 | - 4 register banks, 256 bytes IRAM, SFRs, 64K code, 64K XRAM |
| 57 | - ports P0–P3 with latch vs. pin semantics (read-modify-write reads the latch) |
| 58 | - timers 0/1 in modes 0–3, gate and counter inputs |
| 59 | - interrupts: INT0, T0, INT1, T1, serial; two priority levels; edge/level triggers |
| 60 | - UART in modes 0–3 with baud rate timing from timer 1 |
| 61 | - idle and power-down modes (PCON) |
| 62 | - **Debugger**: run / pause, step into / over / out, run to cursor, |
| 63 | breakpoints, changed-value highlighting, memory poke, adjustable speed. |
| 64 | - **Open `.hex` files**: they're disassembled into editable source that |
| 65 | re-assembles to the identical image. |
| 66 | |
| 67 | ## Usage |
| 68 | |
| 69 | ```bash |
| 70 | cargo install --path . # installs the `bench51` binary |
| 71 | |
| 72 | cargo run --release -- examples/serial_hello.asm # open in the TUI |
| 73 | cargo run --release # start with a template |
| 74 | cargo run --release -- firmware.hex # disassemble & debug a HEX file |
| 75 | |
| 76 | # Headless assembly: writes prog.hex and prog.lst |
| 77 | cargo run --release -- --assemble prog.asm |
| 78 | cargo run --release -- --assemble prog.asm -o out.hex --lst out.lst |
| 79 | ``` |
| 80 | |
| 81 | `--clock <MHz>` sets the oscillator frequency used for the elapsed-time display |
| 82 | (default 11.0592). |
| 83 | |
| 84 | ## Keys |
| 85 | |
| 86 | | Key | Action | |
| 87 | | --- | --- | |
| 88 | | F1 | help | |
| 89 | | F2 / Ctrl-S | save (assembling a saved file also writes `.lst` and `.hex` next to it) | |
| 90 | | F3 / Ctrl-O | open `.asm` or `.hex` | |
| 91 | | Ctrl-G | edit in `$EDITOR`; on save & exit the buffer reloads and reassembles | |
| 92 | | F4 | switch Edit ⇄ Debug | |
| 93 | | F7 | assemble, reset and load | |
| 94 | | F5 | run / pause (assembles first if the source changed) | |
| 95 | | F11 / F10 / F12 | step into / step over / step out | |
| 96 | | F8 | run to cursor | |
| 97 | | F9 | toggle breakpoint on the cursor line | |
| 98 | | F6 | reset | |
| 99 | | Ctrl-Q | quit | |
| 100 | |
| 101 | Edit mode: `Alt-1/2/3` switch between Listing, HEX and Errors; `Alt-↑/↓`, |
| 102 | `Alt-PgUp/PgDn` scroll them. The editor uses Emacs-style keys |
| 103 | (`Ctrl-U` undo, `Ctrl-R` redo, `Ctrl-Y` paste). |
| 104 | |
| 105 | Debug mode: `Tab` cycles focus between Source, Memory, Ports and Serial. |
| 106 | Letter shortcuts work too, for terminals that swallow function keys: |
| 107 | `r` run/pause, `s` step, `n` step over, `o` step out, `g` run to cursor, |
| 108 | `b` breakpoint, `x` reset, `i`/`f`/`d`/`c` show IRAM/SFR/XRAM/CODE, |
| 109 | `p` poke memory, `+`/`-` speed, `.` jump to PC, `Esc` pause / back to editor. |
| 110 | |
| 111 | - **Ports**: select a pin and press Space to pull it low from outside (a |
| 112 | button press); the program sees the pin as `latch AND external level`. |
| 113 | - **Serial**: type a line and press Enter to send it (followed by CR) to the |
| 114 | 8051's receiver; everything the 8051 transmits appears above. |
| 115 | |
| 116 | ## Examples |
| 117 | |
| 118 | | File | Shows | |
| 119 | | --- | --- | |
| 120 | | `examples/blink.asm` | port toggling, delay loops, `ACALL`/`RET` | |
| 121 | | `examples/timer_irq.asm` | timer 0 mode 1 interrupt | |
| 122 | | `examples/serial_hello.asm` | UART setup, string output with `MOVC`, echo | |
| 123 | | `examples/button_int0.asm` | edge-triggered INT0, idle mode | |
| 124 | | `examples/bcd_add.asm` | `ADDC` and `DA A` with packed BCD | |
| 125 | | `examples/lookup_movc.asm` | 7-segment table lookup | |
| 126 | |
| 127 | ## Notes and limitations |
| 128 | |
| 129 | - Indirect addressing reaches all 256 bytes of IRAM (8052-style upper 128). |
| 130 | - Serial input has no 9th data bit; in modes 2/3 `RB8` reads 0. |
| 131 | - No 8052 timer 2, external code memory or on-chip peripherals of derivatives. |
| 132 | |
| 133 | ## Development |
| 134 | |
| 135 | ```bash |
| 136 | cargo test # assembler, CPU, peripheral and example-program tests |
| 137 | cargo clippy |
| 138 | ``` |
| 139 | |
| 140 | Code layout: `src/isa.rs` (opcode table shared by everything), `src/asm/` |
| 141 | (assembler, listing, Intel HEX), `src/sim/` (CPU, peripherals, disassembler), |
| 142 | `src/ui/` (ratatui front end). |