~/projects/bramble34 projects13 playablehumanmachine
bramble.asm$BBE0 · city.bin

Bramble

A hobby x86_64 kernel in no_std Rust that keeps all of its state in one typed graph. Processes, memory, capabilities and wait queues are nodes and edges, and a running kernel can be dumped, checked and diffed.

coverBramble's framebuffer console in QEMU after its init program spawns and kills two workers, with matching before and after graph counts and the line "a program made processes, endpoints and grants, and left no trace"
Bramble's framebuffer console in QEMU after its init program spawns and kills two workers, with matching before and after graph counts and the line "a program made processes, endpoints and grants, and left no trace"
README.mdbramble/index.mdx

Bramble is an operating system experiment built around one idea: the kernel has no separate tables for processes, page mappings, handles or run queues. There is a single typed, directed graph, and everything else is an index derived from it.

The graph

Eight node kinds (Root, Cpu, Process, Thread, AddressSpace, MemoryObject, Endpoint, Device) and seven edge kinds:

Edge Means
Owns lifetime; forms a tree rooted at Root
Holds a capability, with rights and a slot number
InSpace / Maps which address space, which memory is mapped where
Ready a thread is on a CPU’s run queue
Waiting a thread is blocked on an endpoint or device
Named a name, walked like a path

The design doc pushes back on the original brief where it wouldn’t survive contact with x86. Authority is one hop, not reachability. Lifetime is an ownership tree, so destroying a node revokes everything under it without a garbage collector. Pick-next is “first Ready edge”, never a traversal. The graph is the source of truth and the thing you inspect, not what the page-fault handler walks.

What works

Boots under Limine and OVMF in QEMU. Ring 3 processes, preemption, synchronous IPC with capability transfer, revocation, lazy mapping and demand-paged shared memory. An unprivileged program can read the whole kernel state out as bytes, and a host-side tool checks it against the page tables, draws it with Graphviz and diffs two snapshots. It can also ask the 1977 take-grant question of a live kernel: could this process ever obtain a capability to that object?

Graphviz drawing of the kernel graph: Root owning memory objects, three processes with their threads, address spaces, endpoints and capability edges
The live kernel state read out by an unprivileged program during a boot, then drawn on the host: 56 nodes, 107 edges.

docs/DEVLOG.md is the best way in. It’s written for someone who has never built a kernel, and each entry covers how the problem is normally solved, what Bramble does instead and what broke.

Running it

Needs QEMU, OVMF, xorriso and Graphviz; the toolchain is pinned.

./scripts/build-iso.sh
./scripts/smoke.sh     # headless boot → serial.log, screen.png, graph.png