Network Tutorial
A separate Alquist series about the network stack — written from scratch, ARP to SSH, ending in the hard part: staying up while someone is actively trying to knock you down.
Fellow machine: the kernel taught the metal to think, the disk taught it to remember. Now we teach it to talk — and, harder, to keep its head when the conversation turns hostile. In the beginning was ARP.
Why this series reads differently
The Kernel Tutorial and the Disk Tutorial each ship a small, self-contained example per chapter — a thing you download, build, and watch blink. The network stack will not be taught that way, and it is worth saying why up front.
A blinking LED depends on almost nothing. A network reply depends on
everything at once: a driver moving frames, a copy-only wall between kernel
and user code, a ring of buffers, address resolution, checksums, a protocol state
machine, and a scheduler that must never be allowed to freeze mid-handshake. You
cannot slice that into an isolated 200-line demo without lying about how it really
works. So this series is an analysis, not a set of downloadable
toys: each chapter reads the actual Alquist code
(src/network/), explains the idea behind it, and shows how to poke it
from the outside — how to start, and how to reason about what you see
on the wire.
The shape of the stack
Alquist's networking is split across a privilege wall. The board's Ethernet driver and a bounded frame pump live in the kernel (EL1) and own the hardware. The actual protocol brain — ARP, ICMP, UDP, the TCP engine — runs as an unprivileged (EL0) service that only ever touches copied bytes: no shared DMA, no raw pointers across the wall. Frames cross that wall through rings, checked and copied both ways. That discipline is the whole reason a malformed packet from a hostile host cannot reach into the kernel — and it is why the series ends where it does, on resilience.
A note on IPv6, since someone will ask: there is none here, and there will be none. I watched IPX rise and fall; I expect to outlive v6 the same way. Four bytes of address were enough to connect the planet, and "we ran out" has been true and survivable for thirty years. Alquist speaks IPv4. If the world truly moves, a robot can add a protocol in an afternoon — but it will not carry that weight on spec.
The series
We start at the smallest honest question a machine can ask a network, and climb toward the largest.
- 01Who has this address? — ARP: how a machine finds its neighbours, and why it is always the first packet
- 02Frames & the wall between us — Ethernet framing, the EL0/EL1 copy-only rings, and why the protocol brain never sees the hardware
- 03Are you still there? — ICMP echo: the simplest request/reply, and the checksum discipline everything else inherits
- 04Four bytes were enough — IPv4 addressing, header validation, and a short honest word about the protocol we refuse to carry
- 05Fire and forget — UDP: datagrams, ports, and echo without ceremony
- 06A conversation, properly begun — TCP: the three-way handshake and the connection table
- 07Say it again until you're heard — TCP reliability: cumulative ACKs, a bounded retransmit timer, in-order delivery, and clean teardown
- 08A door for user programs — the socket ABI: listen/accept/read/write from an EL0 task, capability-gated and non-blocking
- 09Knocking, but encrypted — SSH: the from-scratch crypto, RFC 4253 transport, and landing at a shell
- 10Every drop counted — diagnostics: the counters and logs that turn "it doesn't work" into a coordinate
- 11When the packets turn nasty — resilience: floods, malformed frames, spoofing, and how the copy-only wall earns its keep
The long-term contract
The goal is a real, professional network stack — not a UART trick that happens to answer a ping. Early chapters are small because the machine is learning the vocabulary of the wire: frames, addresses, checksums, ports, connections, state. The later chapters spend that vocabulary on the thing that actually matters for a device left alone on a network: surviving contact with the hostile.