diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 28 |
1 files changed, 27 insertions, 1 deletions
@@ -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. |