How BoxOS is shaped.
A visual tour: the parts of the kernel, how a userspace request actually reaches the metal, and what changes when there is more than one CPU. The full reference lives in the docs.
the whole map
one userspace request, end to end
How a notify becomes a Manifest, an op, a driver call, a result.
single core
One CPU does everything. The kernel takes the syscall, runs the Manifest, calls the driver, writes the result, then returns to user code on the same CPU. No IPI, no cross-core handoff.
multi core
One core is a K-Core (the boot CPU): it runs the scheduler and the Manifest dispatcher. The others are App-Cores: they only run user processes. Work crosses cores through the rings — no shared run-queue.
One CPU or many — same shape.
BoxOS is asymmetric. In a multi-core boot, the boot CPU plays the role of K-Core — it runs the scheduler, the dispatcher and the storage path. The rest are App-Cores running user processes. A single-core boot folds both roles into one CPU; the data path through the rings stays the same.
single core
One CPU does both.
Kernel work and user work share the same core, switching at every syscall and interrupt. There is no IPI and no cross-core handoff to think about.
multi core
One K-Core, the rest are App-Cores.
The boot CPU runs the scheduler and the Manifest dispatcher. Other cores run user processes only. Work crosses cores through the rings — each core has its own run-queue and can steal work when idle.
The five Decks.
A Deck is a logically isolated module that owns a vocabulary of named operations. There are five of them, each registers its ops with the OpRegistry at boot. They are passive — userspace never calls a Deck directly; it submits a Manifest, the engine resolves each op to its handler, and that handler lives in a Deck.
decks · what each one owns
Five Decks. Ninety-six ops. One registry.
A Deck is not a place where data lives — it's a logically isolated module that owns a set of named operations. Each Deck registers its ops with the OpRegistry at boot. Userspace never talks to a Deck directly: it submits a Manifest, the engine looks the op up, the matching handler runs.
Operations
10 opsbytewise primitives
- move
- fill
- xor
- hash
- cmp
- find
- pack
- unpack
- bswap
- vadd
Hardware
54 opsmetal-facing
- timer
- rtc
- port
- irq
- disk
- keyboard
- vga
- usb
- halt
- reboot
System
18 opsprocess · ipc · tags
- proc.spawn
- proc.kill
- ipc.route
- ipc.broadcast
- tag.add
- ctx.use
Storage
13 opsfiles in TagFS
- read
- write
- query
- create
- delete
- rename
- tag.set
- ctx.set
Execution
1 opresult writer
- result
One notify, end to end.
A userspace function call ends up as a Pocket on a per-process ring, picked up by the K-Core, dispatched through the Manifest engine, authorized, looked up, executed, and answered with a Result on the paired ring. No hidden hops.
one notify · seven steps
The path of one Pocket.
From a userspace function call to a result the same process reads back. Nothing is hidden — each step is a real piece of code in the tree.
Boot path.
From the first 512 bytes on disk to a shell prompt. There's also a UEFI route — TagBoot — that skips Stage 1 / 2 and gives the kernel a GOP framebuffer and an e820 memory map directly.
boot · stage by stage
From the first 512 bytes to a running kernel.
Where things live in memory.
x86_64 with 4-level paging. Each Cabin owns its own page table for the lower half; the kernel half is shared by every process so a notify doesn't need to switch page tables.
virtual address space · per process
Where things live in memory.
x86_64 with 4-level paging. The lower half is private to the process; the upper half is the kernel, mapped into every process so syscalls don't need a page-table switch.
Source layout.
The repository is one shallow tree. Almost everything you can see on this page maps to a folder you can read.
boxos/
├── src/
│ ├── boot/
│ │ ├── stage1/ # 512-byte MBR — loads Stage 2
│ │ ├── stage2/ # real → long mode, loads kernel
│ │ └── uefi/ # TagBoot — UEFI path
│ ├── kernel/
│ │ ├── arch/ # x86-64: GDT, IDT, AMP, notify MSRs
│ │ ├── core/ # scheduler, vmm, pmm, ipc, manifest, decks, op-registry
│ │ ├── drivers/ # ATA, AHCI, xHCI, PIT, RTC, GOP, PS/2, PCI, ACPI, COM1
│ │ ├── tagfs/ # filesystem — tag registry, file table, BoxHash, BCDC
│ │ └── main.c
│ ├── userspace/
│ │ ├── boxlib/ # pocket, manifest, result, notify, vga, file, system, ...
│ │ ├── shell/ # interactive shell + builtins
│ │ ├── apps/ # proca, procb, today, memtest, mtest, chain, decks, bench
│ │ └── display/ # display daemon
│ └── include/ # shared headers (boxos_*.h)
├── tools/ # qemu wrappers, automation scripts
├── build/ # produced by `make` (gitignored)
└── MakefileGoing deeper.
The documentation walks every Deck, every driver, the userspace library and the shell — one section per piece. The changelog is the actual commit history of the kernel; the forum is where design changes get discussed.