Phase 16

Network

Add a minimal but real TCP/IP stack so the OS can send and receive packets over a network. A virtio-net NIC in QEMU is the hardware target. The end goal is a working `ping` and a simple TCP connection.

Complete

Learning goal

Understand the layered network model by implementing each layer from scratch.

Why this phase matters

Add a minimal but real TCP/IP stack so the OS can send and receive packets over a network. A virtio-net NIC in QEMU is the hardware target. The end goal is a working ping and a simple TCP connection.

How it works in m3OS

The roadmap entry defines the learning scope for this phase; a deeper implementation doc has not been matched yet.

How it builds on earlier phases

This phase builds on Hardware Discovery and turns that foundation into Network.

Implementation outline

Use the PCI device list from Phase 15 to find the virtio-net device.
Initialize the virtio device: feature negotiation, virtqueue setup.
Implement the Ethernet and ARP layers.
Implement IPv4 and ICMP; test with ping 10.0.2.2 (QEMU default gateway).
Implement UDP; test with a simple echo server.
Implement TCP state machine: SYN, SYN-ACK, ACK, data, FIN.
Expose socket syscalls through the POSIX compatibility layer, routing to net_server via IPC.

Task progress snapshot

No checklist tasks were discovered for this phase yet.

Documentation targets

Documentation deliverables have not been listed yet.

Deferred follow-on work

TCP retransmission timer and congestion control
IPv6
DNS resolution
TLS / DTLS
epoll / select / poll for non-blocking sockets
multiple simultaneous TCP connections
checksum offload via virtio features
DHCP client

Source materials

Important code

Code spotlight cards

(kernel/src/net/*) and runs as net_task. This is a temporary kernel-mode

View on GitHub

Key files

kernel/src/net/* — (kernel/src/net/*) and runs as net_task. This is a temporary kernel-mode

How real OSes differ

Production network stacks handle retransmission timers, SACK, TCP congestion control (CUBIC, BBR), scatter-gather DMA, checksum offload, VLAN tagging, IPv6, DNS, TLS, and non-blocking I/O via `epoll`. They are typically 50,000-200,000 lines of code. This phase implements a toy single-connection stack with no retransmit timer and no congestion control — enough to demonstrate every layer of the model but not suitable for real traffic.

Success criteria

`ping 10.0.2.2` receives ICMP echo replies from the QEMU gateway.
A UDP echo client can send a datagram and receive it back.
A TCP client can connect to a host listener, exchange a line of text, and close cleanly.
A TCP server running inside the OS can accept a connection from the host.

Related phases

Keep exploring the roadmap

Hardware Discovery

Replace the hardcoded, single-core interrupt model with proper hardware discovery via ACPI and PCI, and switch from the legacy 8259 PIC to the APIC. This unlocks multi-core support and arbitrary device discovery in later phases.

Memory Reclamation

Close the memory leaks that have accumulated since Phase 2. The bump frame allocator is replaced with a free-list allocator that can actually reclaim frames, the kernel heap grows on demand instead of being fixed at 1 MiB, kernel stacks are freed when processes exit, and `fork` switches from eager full-copy to copy-on-write so parent and child share physical pages until one of them writes.