# gbos

A tiny **Unix-flavored OS for the Game Boy Color** — a from-scratch cooperative
microkernel with fork/exec, a shell with pipes, a persistent filesystem, a
color terminal on the LCD, and a **real TCP/IP stack over the link cable**.
It boots, gets a DHCP lease, pings, resolves DNS, fetches web pages, and hangs
out on IRC. On a 1997 handheld (well, an emulated one).

![gbos: boot, ping, IRC — all on a Game Boy Color](demo/gbos-demo.gif)

*Real capture: cold boot → DHCP lease → `ping` → an IRC session, typed live
into the on-screen console. Regenerate it anytime with `tools/gbdemo` (below).*

## What's in the box

- **Processes, the V7 way**: `fork`/`exec`/`wait`/`exit`, zombies + reaping,
  background jobs (`spin &`), `ps`, `kill` — round-robin cooperative
  scheduling across banked memory with an HRAM context switch.
- **A shell** (written in C, running *on* the GB) with I/O redirection
  (`>` `<`) and pipes (`|`), argument passing, and a cwd-aware prompt.
- **Networking, for real**: the kernel owns SLIP over the link port, IPv4,
  ICMP, UDP and TCP; userland gets BSD-ish sockets via one syscall. On top:
  `dhcp` (boot-time lease), `ping`, `nslookup` (real DNS), `wget` (HTTP),
  `chat`, and a colorized **IRC client** (`irc HOST [NICK]`, `/join` and
  friends, SELECT for the keyboard).
- **A network to plug into**: `tools/gbhub` is a virtual switch + DHCP server +
  NAT gateway — spawn a fleet of Game Boys that ping *each other* and reach
  the real internet; `tools/gbjoin` attaches an interactive GB to it, and
  `tools/gbtype` types into any GB's shell from the host.
- **40×18 color terminal** on the LCD (4×8 font, two chars per tile, ANSI-ish
  colors) + an **on-screen keyboard** on the window layer (SELECT toggles it).
- **Persistent filesystem** on battery-backed cart RAM: inodes, nested
  directories, per-process cwd — survives power-off.
- **A C toolchain**: userland is plain C compiled with SDCC (`sm83`); ~30
  tools ship in `usr/` (`cat`, `wc`, `head`, `ls`, `uptime`, …). Adding a
  program is one `.c` file + a table entry.

## Quick start

```sh
make                                   # -> gbos.gb  (needs RGBDS + SDCC)

# solo, in the sl0pboy emulator (~/dev/gbc):
~/dev/gbc/build/sl0pboy --sixel 3 --chrome gbos.gb

# networked — hub in one terminal, Game Boys in others:
sudo tools/gbhub --daemon              # virtual net + DHCP + NAT (needs root)
tools/gbjoin                           # a windowed GB joins 10.0.0.0/24
tools/gbtype 'ping 10.0.0.3'           # or type into it from the host
```

On the Game Boy: **SELECT** toggles the on-screen keyboard, d-pad + **A**
types, **START** sends the line.

```
/# uname -a
gbos sm83 (Game Boy Color)
/# ping 10.0.0.1
PING 10.0.0.1
  reply from 10.0.0.1 seq=1
  ...
-- 4/4 received
/# irc 10.0.0.1 sl0pboy
-!- registering as sl0pboy (SELECT = keyboard)
```

## The demo GIF

The GIF above is produced by a scripted, self-syncing demo driver:
`tools/gbdemo` runs a step file (`demo/readme.gbd`), injects console text and
button events at the right moments — syncing on the *actual screen contents*
(the terminal's WRAM shadow, read over the emulator's debug socket) rather
than timers — while the emulator records every frame, then renders the GIF:

```sh
sudo tools/gbhub --daemon              # network up (once)
tools/gbdemo demo/readme.gbd           # inside tmux; writes demo/gbos-demo.gif
```

Edit `demo/readme.gbd` to choreograph your own (verbs: `type`, `slowtype`,
`key`, `waitfor`, `record`, `gif`, …).

## Docs

- [docs/internals.md](docs/internals.md) — the full technical breakdown:
  memory model, syscall ABI, fork/exec/context-switch internals, the network
  stack, the filesystem layout, C toolchain notes, war stories, roadmap.
- [docs/link-drop-investigation.md](docs/link-drop-investigation.md) — a
  networking bug hunt, preserved.

Built and tested against the [sl0pboy](../gbc) emulator; runs on anything that
emulates a CGB + MBC5 cartridge with battery RAM. No MMU, no protection, no
regrets.