Architecture

VirelaiOS is a layered, freestanding kernel with no libc and no heap in the boot-critical paths — bounded fixed-BSS storage is the norm. This page is the map; the satellites below carry the detail.

The stack, top to bottom

┌───────────────────────────────────────────────┐
│  EL0 user programs + desktop apps (GOCALC.ELF, │
│  GOTABWM.ELF, GO* Go apps, …)                 │
│  runtime linker LD.SO + LIBUI.SO/LIBFONT.SO   │
│  syscalls: 80 implemented slots (of 128):     │
│  IPC/window/events/files/net/time/memory …    │
├───────────────────────────────────────────────┤
│  Monitor + shell (virelai>)                   │
│  Road Pops terminal · Driving Award compositor │
├───────────────────────────────────────────────┤
│  SMP scheduler (round-robin, 2 cores)         │
│  EFI-map allocator · MMU (per-process roots,  │
│  demand-zero paging + copy-on-write; no swap) │
├───────────────────────────────────────────────┤
│  Drivers: virtio console/entropy/gpu/net/snd/  │
│  custom + USB XHCI (HID + MSC) · GICv3 · timer │
├───────────────────────────────────────────────┤
│  UEFI boot loader (BOOTAA64.EFI)              │
└───────────────────────────────────────────────┘

What owns what

• Kernel overview — boot, ExitBootServices, exception vectors, the monitor and command registry.
• Memory model — the physical allocator, identity-map page tables, per-task address spaces.
• Userspace & syscalls — EL0, the frozen syscall ABI, fault-safe uaccess, exec and processes.
• Device drivers — the virtio surface, the XHCI USB controller, and the MMIO contracts.

Design discipline

Three rules show up everywhere:

1. Bounded static storage. Rings, FIFOs, window tables, and frame buffers use fixed-capacity storage. There is no general heap in the device paths; full queues refuse work or apply their documented overflow policy rather than growing.
2. Per-device contracts. Queue capacity, request concurrency, and completion handling vary by device. Hardware behavior is observed rather than generalized, then recorded in docs/hardware-contract.md.
3. Evidence over assertion. Every subsystem has host tests (deterministic) and, where hardware is involved, a live Virtualization.framework gate. See Evidence & testing.

Subsystem boundaries in one line each