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

3 files changed, 58 insertions, 4 deletions

diff --git a/src/gb.c b/src/gb.c
index afdcb89..05429fd 100644
--- a/src/gb.c
+++ b/src/gb.c
@@ -4,6 +4,7 @@
 #include "cpu.h"
 #include <string.h>
 #include <stdio.h>
+#include <unistd.h>
 
 void gb_request_interrupt(GB *gb, u8 flag) {
     gb->iff |= flag;
@@ -116,9 +117,21 @@ void gb_write(GB *gb, u16 addr, u8 val) {
     if (addr == 0xFF02) {
         gb->sc = val;
         if ((val & 0x81) == 0x81) {
-            // transfer with internal clock: log & complete instantly
-            if (gb->serial_log) { fputc(gb->sb, stderr); fflush(stderr); }
-            gb->sb = 0xFF;
+            // transfer with internal clock (GB is master): shift out gb->sb,
+            // shift in a byte from the peer. Completes instantly.
+            u8 outb = gb->sb;
+            if (gb->serial_log) { fputc(outb, stderr); fflush(stderr); }
+            if (gb->serial_out_fd >= 0) {
+                unsigned char c = outb;
+                (void)!write(gb->serial_out_fd, &c, 1);
+            }
+            // received byte: from serial_in_fd if available, else open-bus 0xFF
+            u8 inb = 0xFF;
+            if (gb->serial_in_fd >= 0) {
+                unsigned char c;
+                if (read(gb->serial_in_fd, &c, 1) == 1) inb = c;
+            }
+            gb->sb = inb;
             gb->sc &= ~0x80;
             gb_request_interrupt(gb, INT_SERIAL);
         }
@@ -204,6 +217,8 @@ void gb_reset(GB *gb) {
         c->af = 0x01B0; c->bc = 0x0013; c->de = 0x00D8; c->hl = 0x014D;
     }
     c->ime = false;
+    gb->serial_out_fd = -1;
+    gb->serial_in_fd = -1;
     gb->wram_bank = 1;
     gb->joyp_sel = 0x30;
     gb->iff = 0xE1;
diff --git a/src/gb.h b/src/gb.h
index 7439615..7218648 100644
--- a/src/gb.h
+++ b/src/gb.h
@@ -114,6 +114,8 @@ struct GB {
 
     u64 cycles;        // total T-cycles elapsed
     bool serial_log;   // print serial output to stderr (blargg tests)
+    int  serial_out_fd; // if >=0, transmitted serial bytes written here (stdout)
+    int  serial_in_fd;  // if >=0, received serial bytes read here (stdin), else 0xFF
 };
 
 void gb_init(GB *gb);
diff --git a/src/main.c b/src/main.c
index ecd818e..f0709c2 100644
--- a/src/main.c
+++ b/src/main.c
@@ -7,6 +7,8 @@
 #include <string.h>
 #include <time.h>
 #include <signal.h>
+#include <fcntl.h>
+#include <unistd.h>
 
 static volatile sig_atomic_t running = 1;
 static void on_sig(int s) { (void)s; running = 0; }
@@ -29,7 +31,7 @@ int main(int argc, char **argv) {
     if (argc < 2) {
         fprintf(stderr, "usage: %s <rom> [--test seconds] [--sixel [scale]] "
                 "[--frameskip n] [--fps n] [--uncapped] [--fifo [path]] "
-                "[--sock [path]]\n",
+                "[--sock [path]] [--headless]\n",
                 argv[0]);
         return 1;
     }
@@ -44,6 +46,7 @@ int main(int argc, char **argv) {
     int    frameskip = 0;        // draw 1 of every (frameskip+1) frames
     bool   sixel = false;        // use sixel graphics output
     int    sixel_scale = 2;      // integer pixel zoom for sixel
+    bool   headless = false;     // no video; serial <-> stdio (OS debug console)
     for (int i = 2; i < argc; i++) {
         if (!strcmp(argv[i], "--test")) {
             test = true;
@@ -66,6 +69,8 @@ int main(int argc, char **argv) {
             if (i + 1 < argc && argv[i+1][0] != '-') sixel_scale = atoi(argv[++i]);
         } else if (!strcmp(argv[i], "--uncapped") || !strcmp(argv[i], "--turbo")) {
             target_fps = 0;
+        } else if (!strcmp(argv[i], "--headless")) {
+            headless = true;
         }
     }
     if (frameskip < 0) frameskip = 0;
@@ -84,6 +89,38 @@ int main(int argc, char **argv) {
         return 0;
     }
 
+    // Headless: no rendering, no terminal UI. Tie the serial port to stdio so
+    // an OS on the GB gets a plain byte console (TX -> stdout, RX <- stdin).
+    // Paced to native speed unless --uncapped. Piping works for scripted tests:
+    //   printf 'ls\n' | gbc rom.gb --headless
+    if (headless) {
+        gb->serial_out_fd = STDOUT_FILENO;
+        gb->serial_in_fd  = STDIN_FILENO;
+        int fl = fcntl(STDIN_FILENO, F_GETFL, 0);
+        if (fl != -1) fcntl(STDIN_FILENO, F_SETFL, fl | O_NONBLOCK);
+        signal(SIGINT, on_sig);
+        signal(SIGTERM, on_sig);
+        bool uncapped = (target_fps <= 0);
+        double start_t = now_sec();
+        u64 start_cyc = gb->cycles;
+        const double HZ = 4194304.0;
+        while (running) {
+            run_frame(gb);              // advance ~a frame's worth of cycles
+            if (!uncapped) {
+                double target = start_t + (gb->cycles - start_cyc) / HZ;
+                double sleep = target - now_sec();
+                if (sleep > 0) {
+                    struct timespec ts = { (time_t)sleep,
+                        (long)((sleep - (time_t)sleep) * 1e9) };
+                    nanosleep(&ts, NULL);
+                } else if (sleep < -0.5) {
+                    start_t = now_sec(); start_cyc = gb->cycles; // resync
+                }
+            }
+        }
+        cart_free(&gb->cart); free(gb); return 0;
+    }
+
     if (shot_frames >= 0) {
         for (int f = 0; f < shot_frames; f++) run_frame(gb);
         FILE *pf = fopen(shot_path, "wb");