Krolyxon
Commit 83c841a

Branches

Tags

Refs →

bench51README.md

250 lines · 11.9 KB · Markdown

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