From 24a015ff047d4b7bb955ba4bc61d5793d7492878 Mon Sep 17 00:00:00 2001 From: gbc dev Date: Wed, 15 Jul 2026 23:44:28 +0200 Subject: serial: headless mode tying serial port to stdio for OS debugging - --headless: no rendering/TUI; serial TX -> stdout, RX <- stdin (nonblocking) - generalize serial: serial_out_fd/serial_in_fd on the GB; internal-clock transfer now shifts in a real RX byte (from stdin) instead of always 0xFF - paced to native speed by default, --uncapped for turbo; pipes/scripts cleanly - README: document headless serial console --- README.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index b93446d..e03aedc 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,38 @@ over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint. ```sh make ./build/gbc path/to/rom.gb # interactive -./build/gbc rom.gb --test 30 # headless: run 30s, log serial (test roms) +./build/gbc rom.gb --test 30 # run 30s, log serial to stderr (test roms) ./build/gbc rom.gb --shot 60 out.ppm # run 60 frames, dump a PPM screenshot ./build/gbc rom.gb --sixel 3 # sixel graphics output at 3x zoom ./build/gbc rom.gb --sock # open a control/debug socket (/tmp/gbc.sock) +./build/gbc rom.gb --headless # no video; serial <-> stdio (OS console) ``` +### Headless serial console (`--headless`) + +For bring-up and debugging of an OS/monitor running on the emulated Game Boy, +`--headless` disables all rendering and the terminal UI and instead wires the +**serial port straight to stdio**: + +- transmitted bytes (the GB writing `SB`/`SC` with the internal clock) go to **stdout** +- **stdin** is fed back as the received byte on each transfer (non-blocking; + `0xFF` open-bus when nothing is waiting) + +Emulation is paced to native speed by default; add `--uncapped` to run flat out. +Because it's plain stdio it pipes and scripts cleanly: + +```sh +./build/gbc os.gb --headless # interactive byte console +./build/gbc os.gb --headless --uncapped # as fast as possible +printf 'ls\n' | ./build/gbc os.gb --headless # feed input, capture output +./build/gbc os.gb --headless | tee session.log +``` + +The serial console model matches what a GB program expects: write the byte to +`SB` (`$FF01`), then kick a transfer with `SC = $81` (`$FF02`, start + internal +clock). Output appears immediately; the transfer-complete serial interrupt still +fires. (`--test` keeps its old behavior, logging serial to **stderr**.) + Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least 160 columns wide. -- cgit v1.3.1-sl0p