Krolyxon
Commit 35ed5a3

Branches

Tags

Refs →

bench5135ed5a3

README: lead with the GUI, present the TUI as the terminal version

Author
krolyxon
Date
2026-10-31 23:35 +0530
Parent
1504706
Commit
35ed5a31b32a0589e61c2d57852baa4ce3469147

+96 −84

1 file changed

Browse files Patch
−Context 3+
  1. M README.md +96 −84
M README.md View
@@ -1,34 +1,36 @@
11 # bench51 — an 8051 assembler, simulator & debugger
22
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.
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.
98
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.
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.
1311
14−![Debugging serial_hello.asm: source, registers, peripherals, IRAM and the UART console](docs/screenshots/debug_serial.png)
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+![Debug session: registers, source with the PC, disassembly, memory and UART #1](docs/screenshots/gui_debug.png)
1517
1618 <table>
1719 <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+ <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>
2022 </tr>
2123 <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+ <td align="center"><sub>Editor + build output</sub></td>
25+ <td align="center"><sub>Breakpoint in a timer ISR, light theme</sub></td>
2426 </tr>
2527 <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+ <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>
2830 </tr>
2931 <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+ <td align="center"><sub>Peripheral windows, rearranged</sub></td>
33+ <td align="center"><sub>Assembler errors</sub></td>
3234 </tr>
3335 </table>
3436
@@ -38,15 +40,20 @@ I had microcontroller practicals to get through, and the course expects you to
3840 use Keil µVision. Keil µVision doesn't run on Linux. Rather than fight with
3941 Wine or a Windows VM every lab session, I wrote my own: bench51 does the parts
4042 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+at the listing and HEX, step through it and watch the registers) natively on
44+Linux, in a window or right in the terminal.
4345
4446 -----
4547
4648 ## Features
4749
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+- **µ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.
5057 - **Two-pass assembler** for the full 8051 instruction set (all 255 opcodes):
5158 - labels, expressions (`+ - * / MOD AND OR XOR NOT SHL SHR HIGH LOW`, `$`)
5259 - number formats `42`, `2Ah`, `0x2A`, `101010b`, `52o`, `'*'`
@@ -66,66 +73,37 @@ terminal.
6673 breakpoints, changed-value highlighting, memory poke, adjustable speed.
6774 - **Open `.hex` files**: they're disassembled into editable source that
6875 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).
6978
7079 ## Usage
7180
7281 ```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
82+cargo install --path crates/bench51-gui # installs `bench51-gui`
7883
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
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
8288 ```
8389
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−![Debug session in the GUI: registers, source with the PC, disassembly, memory and UART #1](docs/screenshots/gui_debug.png)
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.
9993
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>
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:
11896
11997 ```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
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
125100 ```
126101
127−`--theme system|dark|light` overrides the theme chosen in View → Theme, and
128−`--clock <MHz>` the Xtal set in Project → Options for Target.
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
129107
130108 The keys are µVision's, with the TUI's as aliases:
131109
@@ -148,19 +126,51 @@ change it, click a pin in Ports to hold it low from outside, and click the
148126 bit chips in Registers, Timers and Interrupts to flip SFR bits. Files can be
149127 dropped onto the window.
150128
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:
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+![The TUI debugging serial_hello.asm: source, registers, peripherals, IRAM and the UART console](docs/screenshots/debug_serial.png)
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>
153157
154158 ```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
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
157168 ```
158169
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`.
170+`--clock <MHz>` sets the oscillator frequency used for the elapsed-time display
171+(default 11.0592).
162172
163−## Keys
173+### Terminal keys
164174
165175 | Key | Action |
166176 | --- | --- |
@@ -179,7 +189,8 @@ libxcb-xfixes0-dev libxkbcommon-dev libssl-dev`.
179189
180190 Edit mode: `Alt-1/2/3` switch between Listing, HEX and Errors; `Alt-↑/↓`,
181191 `Alt-PgUp/PgDn` scroll them. The editor uses Emacs-style keys
182−(`Ctrl-U` undo, `Ctrl-R` redo, `Ctrl-Y` paste).
192+(`Ctrl-U` undo, `Ctrl-R` redo, `Ctrl-Y` paste), or press Ctrl-G to edit in
193+your own `$EDITOR` (vim, nvim, nano, …).
183194
184195 Debug mode: `Tab` cycles focus between Source, Memory, Ports and Serial.
185196 Letter shortcuts work too, for terminals that swallow function keys:
@@ -218,9 +229,10 @@ cargo clippy --workspace --all-targets
218229
219230 Code layout:
220231
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).
226232 - `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)