ION Rings

Complete

ION Rings are the sole inter-process communication mechanism in Nexus OS. Every message between fibers, every syscall parameter, every network packet — all flow through ION Rings.

What Is an ION Ring?

An ION Ring is a lock-free, single-producer/single-consumer (SPSC) ring buffer in shared memory. It has exactly one writer and one reader. No locks. No atomic compare-and-swap. No contention.

Producer ──→ [ slot | slot | slot | slot | slot ] ──→ Consumer
              ↑ write_idx                  ↑ read_idx

The producer writes to write_idx and advances it. The consumer reads from read_idx and advances it. The two indices never collide because the ring has a fixed capacity and the producer blocks (yields) when the ring is full.

Why ION Rings?

Traditional IPC mechanisms have fundamental problems:

Mechanism	Problem
Pipes	Kernel copy on every message. Syscall overhead.
Shared memory + mutexes	Lock contention. Priority inversion. Deadlock risk.
Message queues	Kernel-mediated. Allocation on send.
Signals	Asynchronous, hard to reason about. Race conditions.

ION Rings solve all of these:

• Zero-copy: Data is written directly into shared memory. No kernel copy.
• No locks: SPSC design means no synchronization primitives needed.
• No syscalls: Once the ring is mapped, producers and consumers operate entirely in userland.
• Bounded: Fixed-size rings prevent unbounded memory growth.

Well-Known Channel IDs

Rumpk assigns well-known channel IDs for system services:

Channel ID	Direction	Purpose
0x1000	RX	Console input
0x1001	TX	Console output
0x2000	RX/TX	VFS (filesystem)
0x0500	RX	Network receive
0x0501	TX	Network transmit
0x0600	RX	LWF receive
0x0601	TX	LWF transmit

How Fibers Use ION Rings

1. A fiber is spawned with a set of capability slots (CSpace, 64 slots max)
2. Each slot can hold a channel ID with a permission mask (READ, WRITE, or both)
3. The fiber reads/writes to its assigned ION Rings
4. The kernel maps the ring's physical memory into the fiber's address space

A fiber can only access ION Rings for which it holds a capability. Attempting to access an unauthorized ring triggers a capability fault and the fiber is killed.

Integration with NetSwitch

The Network Membrane uses ION Rings for packet delivery:

1. Hardware NIC (VirtIO) delivers a raw frame to the HAL
2. The NetSwitch (kernel L2 demux) reads the EtherType
3. Based on the EtherType, the frame is placed on the correct fiber's ION Ring:
   • 0x0800 (IPv4) → Membrane fiber for LwIP processing
   • 0x88B5 (UTCP) → UTCP handler fiber
   • 0x4C57 (LWF) → Libertaria Wire Frame handler
4. The receiving fiber processes the frame entirely in userland

No kernel involvement after the initial demux. The kernel delivers the mail; it does not read the letter.

Capacity and Sizing

Ring capacity is configured per channel type:

• Network rings: 256 slots (high throughput)
• Console rings: 128 slots
• VFS rings: 64 slots

Slot sizes are fixed at creation time. Network slots hold MTU-sized frames (1514 bytes). Console slots hold individual characters or small buffers.