Krolyxon
Commit 88ae7ba

Branches

Tags

Refs →

bench51README.md

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