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