1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# 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).
*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.
|
