| 1 | # bench51 — an 8051 assembler, simulator & debugger |
| 2 | |
| 3 | A small, Keil µVision-style IDE for the Intel 8051, in two flavours: a TUI |
| 4 | that runs in your terminal, and a desktop GUI (`bench51-gui`) laid out like |
| 5 | µVision. Write assembly in the built-in editor, assemble it, inspect the |
| 6 | listing and Intel HEX output, then run, pause and single-step the program |
| 7 | while watching registers, SFRs, memory, ports, timers, interrupts and the |
| 8 | serial port. |
| 9 | |
| 10 | Built in Rust with [ratatui](https://ratatui.rs) and |
| 11 | [egui](https://github.com/emilk/egui). It is a learning tool, not a |
| 12 | cycle-exact replacement for a vendor simulator. |
| 13 | |
| 14 |  |
| 15 | |
| 16 | <table> |
| 17 | <tr> |
| 18 | <td width="50%"><img src="docs/screenshots/listing.png" alt="Editor with the assembled Keil-style listing"></td> |
| 19 | <td width="50%"><img src="docs/screenshots/debug_breakpoint.png" alt="Stopped at a breakpoint inside the timer 0 ISR, SFR view"></td> |
| 20 | </tr> |
| 21 | <tr> |
| 22 | <td align="center"><sub>Editor + assembled listing</sub></td> |
| 23 | <td align="center"><sub>Breakpoint inside a timer ISR, SFR view</sub></td> |
| 24 | </tr> |
| 25 | <tr> |
| 26 | <td width="50%"><img src="docs/screenshots/errors.png" alt="Assembler errors marked in the gutter and listed in the Errors tab"></td> |
| 27 | <td width="50%"><img src="docs/screenshots/hex.png" alt="Intel HEX output tab"></td> |
| 28 | </tr> |
| 29 | <tr> |
| 30 | <td align="center"><sub>Assembler errors in the gutter and Errors tab</sub></td> |
| 31 | <td align="center"><sub>Intel HEX output</sub></td> |
| 32 | </tr> |
| 33 | </table> |
| 34 | |
| 35 | ## Why this exists |
| 36 | |
| 37 | I had microcontroller practicals to get through, and the course expects you to |
| 38 | use Keil µVision. Keil µVision doesn't run on Linux. Rather than fight with |
| 39 | Wine or a Windows VM every lab session, I wrote my own: bench51 does the parts |
| 40 | of µVision those practicals actually need (write the code, assemble it, look |
| 41 | at the listing and HEX, step through it and watch the registers) right in the |
| 42 | terminal. |
| 43 | |
| 44 | ----- |
| 45 | |
| 46 | ## Features |
| 47 | |
| 48 | - **Editor** with undo/redo, breakpoint and error markers in the gutter — |
| 49 | or press Ctrl-G to edit in your own `$EDITOR` (vim, nvim, nano, …). |
| 50 | - **Two-pass assembler** for the full 8051 instruction set (all 255 opcodes): |
| 51 | - labels, expressions (`+ - * / MOD AND OR XOR NOT SHL SHR HIGH LOW`, `$`) |
| 52 | - number formats `42`, `2Ah`, `0x2A`, `101010b`, `52o`, `'*'` |
| 53 | - bit addressing (`P1.3`, `ACC.7`, `20h.0`) and all predefined SFR/bit names |
| 54 | - directives `ORG DB DW DS END EQU SET BIT DATA IDATA XDATA CODE CSEG AT` |
| 55 | - generic `JMP`/`CALL` (assembled as `LJMP`/`LCALL`) |
| 56 | - Keil-style `.lst` listing with symbol table, Intel HEX output |
| 57 | - **Simulator** |
| 58 | - all instructions with correct flags (CY, AC, OV, P) and machine-cycle counts |
| 59 | - 4 register banks, 256 bytes IRAM, SFRs, 64K code, 64K XRAM |
| 60 | - ports P0–P3 with latch vs. pin semantics (read-modify-write reads the latch) |
| 61 | - timers 0/1 in modes 0–3, gate and counter inputs |
| 62 | - interrupts: INT0, T0, INT1, T1, serial; two priority levels; edge/level triggers |
| 63 | - UART in modes 0–3 with baud rate timing from timer 1 |
| 64 | - idle and power-down modes (PCON) |
| 65 | - **Debugger**: run / pause, step into / over / out, run to cursor, |
| 66 | breakpoints, changed-value highlighting, memory poke, adjustable speed. |
| 67 | - **Open `.hex` files**: they're disassembled into editable source that |
| 68 | re-assembles to the identical image. |
| 69 | |
| 70 | ## Usage |
| 71 | |
| 72 | ```bash |
| 73 | cargo install --path . # installs the `bench51` binary |
| 74 | |
| 75 | cargo run --release -- examples/serial_hello.asm # open in the TUI |
| 76 | cargo run --release # start with a template |
| 77 | cargo run --release -- firmware.hex # disassemble & debug a HEX file |
| 78 | |
| 79 | # Headless assembly: writes prog.hex and prog.lst |
| 80 | cargo run --release -- --assemble prog.asm |
| 81 | cargo run --release -- --assemble prog.asm -o out.hex --lst out.lst |
| 82 | ``` |
| 83 | |
| 84 | `--clock <MHz>` sets the oscillator frequency used for the elapsed-time display |
| 85 | (default 11.0592). |
| 86 | |
| 87 | ## Desktop GUI |
| 88 | |
| 89 | `bench51-gui` is the same assembler and simulator behind a µVision-style |
| 90 | window: menus and toolbar, a Project window, the editor with breakpoint |
| 91 | gutter, Build Output, and in a debug session the Registers, Disassembly, |
| 92 | Memory, Symbols, UART #1, Ports, Timers and Interrupts windows. Every window |
| 93 | docks and tabs wherever you drag it; the edit and debug layouts are |
| 94 | remembered separately, as in µVision. It follows a monochrome, |
| 95 | dot-matrix design (Space Grotesk, Space Mono and Doto, bundled) in a dark and |
| 96 | a light theme. |
| 97 | |
| 98 |  |
| 99 | |
| 100 | <table> |
| 101 | <tr> |
| 102 | <td width="50%"><img src="docs/screenshots/gui_edit.png" alt="Editor and Keil-style build output"></td> |
| 103 | <td width="50%"><img src="docs/screenshots/gui_breakpoint_light.png" alt="Stopped at a breakpoint in a timer ISR, light theme"></td> |
| 104 | </tr> |
| 105 | <tr> |
| 106 | <td align="center"><sub>Editor + build output</sub></td> |
| 107 | <td align="center"><sub>Breakpoint in a timer ISR, light theme</sub></td> |
| 108 | </tr> |
| 109 | <tr> |
| 110 | <td width="50%"><img src="docs/screenshots/gui_peripherals.png" alt="Ports, timers and interrupts windows docked side by side"></td> |
| 111 | <td width="50%"><img src="docs/screenshots/gui_errors.png" alt="Assembler errors in the gutter and Build Output"></td> |
| 112 | </tr> |
| 113 | <tr> |
| 114 | <td align="center"><sub>Peripheral windows, rearranged</sub></td> |
| 115 | <td align="center"><sub>Assembler errors</sub></td> |
| 116 | </tr> |
| 117 | </table> |
| 118 | |
| 119 | ```bash |
| 120 | cargo install --path crates/bench51-gui # installs `bench51-gui` |
| 121 | |
| 122 | cargo run --release -p bench51-gui # welcome screen |
| 123 | cargo run --release -p bench51-gui -- examples/*.asm # open several files |
| 124 | cargo run --release -p bench51-gui -- --theme light firmware.hex |
| 125 | ``` |
| 126 | |
| 127 | `--theme system|dark|light` overrides the theme chosen in View → Theme, and |
| 128 | `--clock <MHz>` the Xtal set in Project → Options for Target. |
| 129 | |
| 130 | The keys are µVision's, with the TUI's as aliases: |
| 131 | |
| 132 | | Key | Action | |
| 133 | | --- | --- | |
| 134 | | F7 | build target (also writes `.lst` and `.hex` next to a saved file) | |
| 135 | | Ctrl-F5 / F4 | start / stop the debug session | |
| 136 | | F5 | run / stop | |
| 137 | | F11 / F10 | step into / step over | |
| 138 | | Ctrl-F11 / F12 | step out | |
| 139 | | Ctrl-F10 / F8 | run to the cursor line | |
| 140 | | F9 / Ctrl-Shift-F9 | toggle breakpoint / remove all breakpoints | |
| 141 | | F6 | reset the CPU | |
| 142 | | Ctrl-N / Ctrl-O / Ctrl-S / Ctrl-W | new / open / save / close | |
| 143 | | Ctrl-F | find | |
| 144 | | F1 | all shortcuts | |
| 145 | |
| 146 | Click the gutter to toggle a breakpoint, double-click a byte in Memory to |
| 147 | change it, click a pin in Ports to hold it low from outside, and click the |
| 148 | bit chips in Registers, Timers and Interrupts to flip SFR bits. Files can be |
| 149 | dropped onto the window. |
| 150 | |
| 151 | On Linux it runs on Wayland and X11 and uses the XDG desktop portal for file |
| 152 | dialogs. To add it to your application launcher: |
| 153 | |
| 154 | ```bash |
| 155 | install -Dm644 crates/bench51-gui/assets/bench51-gui.desktop ~/.local/share/applications/bench51-gui.desktop |
| 156 | install -Dm644 crates/bench51-gui/assets/bench51-gui.svg ~/.local/share/icons/hicolor/scalable/apps/bench51-gui.svg |
| 157 | ``` |
| 158 | |
| 159 | It also builds for Windows and macOS. On Debian or Ubuntu, first install the |
| 160 | packages egui needs: `libxcb-render0-dev libxcb-shape0-dev |
| 161 | libxcb-xfixes0-dev libxkbcommon-dev libssl-dev`. |
| 162 | |
| 163 | ## Keys |
| 164 | |
| 165 | | Key | Action | |
| 166 | | --- | --- | |
| 167 | | F1 | help | |
| 168 | | F2 / Ctrl-S | save (assembling a saved file also writes `.lst` and `.hex` next to it) | |
| 169 | | F3 / Ctrl-O | open `.asm` or `.hex` | |
| 170 | | Ctrl-G | edit in `$EDITOR`; on save & exit the buffer reloads and reassembles | |
| 171 | | F4 | switch Edit ⇄ Debug | |
| 172 | | F7 | assemble, reset and load | |
| 173 | | F5 | run / pause (assembles first if the source changed) | |
| 174 | | F11 / F10 / F12 | step into / step over / step out | |
| 175 | | F8 | run to cursor | |
| 176 | | F9 | toggle breakpoint on the cursor line | |
| 177 | | F6 | reset | |
| 178 | | Ctrl-Q | quit | |
| 179 | |
| 180 | Edit mode: `Alt-1/2/3` switch between Listing, HEX and Errors; `Alt-↑/↓`, |
| 181 | `Alt-PgUp/PgDn` scroll them. The editor uses Emacs-style keys |
| 182 | (`Ctrl-U` undo, `Ctrl-R` redo, `Ctrl-Y` paste). |
| 183 | |
| 184 | Debug mode: `Tab` cycles focus between Source, Memory, Ports and Serial. |
| 185 | Letter shortcuts work too, for terminals that swallow function keys: |
| 186 | `r` run/pause, `s` step, `n` step over, `o` step out, `g` run to cursor, |
| 187 | `b` breakpoint, `x` reset, `i`/`f`/`d`/`c` show IRAM/SFR/XRAM/CODE, |
| 188 | `p` poke memory, `+`/`-` speed, `.` jump to PC, `Esc` pause / back to editor. |
| 189 | |
| 190 | - **Ports**: select a pin and press Space to pull it low from outside (a |
| 191 | button press); the program sees the pin as `latch AND external level`. |
| 192 | - **Serial**: type a line and press Enter to send it (followed by CR) to the |
| 193 | 8051's receiver; everything the 8051 transmits appears above. |
| 194 | |
| 195 | ## Examples |
| 196 | |
| 197 | | File | Shows | |
| 198 | | --- | --- | |
| 199 | | `examples/blink.asm` | port toggling, delay loops, `ACALL`/`RET` | |
| 200 | | `examples/timer_irq.asm` | timer 0 mode 1 interrupt | |
| 201 | | `examples/serial_hello.asm` | UART setup, string output with `MOVC`, echo | |
| 202 | | `examples/button_int0.asm` | edge-triggered INT0, idle mode | |
| 203 | | `examples/bcd_add.asm` | `ADDC` and `DA A` with packed BCD | |
| 204 | | `examples/lookup_movc.asm` | 7-segment table lookup | |
| 205 | |
| 206 | ## Notes and limitations |
| 207 | |
| 208 | - Indirect addressing reaches all 256 bytes of IRAM (8052-style upper 128). |
| 209 | - Serial input has no 9th data bit; in modes 2/3 `RB8` reads 0. |
| 210 | - No 8052 timer 2, external code memory or on-chip peripherals of derivatives. |
| 211 | |
| 212 | ## Development |
| 213 | |
| 214 | ```bash |
| 215 | cargo test --workspace # assembler, CPU, peripheral, session and example-program tests |
| 216 | cargo clippy --workspace --all-targets |
| 217 | ``` |
| 218 | |
| 219 | Code layout: |
| 220 | |
| 221 | - `crates/bench51-core/`, shared by both front ends: `isa.rs` (opcode |
| 222 | table), `asm/` (assembler, listing, Intel HEX), `sim/` (CPU, peripherals, |
| 223 | disassembler), `session.rs` (build, run, step and breakpoints), |
| 224 | `syntax.rs` (highlighting tokens), `files.rs` (HEX loading) |
| 225 | - `src/` is the `bench51` TUI (ratatui). |
| 226 | - `crates/bench51-gui/` is the `bench51-gui` desktop app (egui). |