NebOS 0.2.0 · Architecture notes
One small OS, from boot sector to browser.
NebOS is a from-scratch, freestanding 32-bit x86 operating system written in C and assembly. It targets a first-generation Pentium, boots from a floppy, a USB disk or x86-64 UEFI firmware, and carries its own scheduler, filesystems, window manager, TCP/IP stack and ring-3 command pack.
The system stack
Almost everything is built in-tree: the boot sectors, the physical memory manager, the scheduler, the FAT driver, the USB host controllers, the TCP client, the TLS implementation and the applications. The only runtime contract with the outside world is the PC firmware and the x86 instruction set.
int 0x80;
the kernel owns the devices and exposes narrow services.
At a glance
8 CPUs
BSP plus up to seven APs, discovered through ACPI/MADT and started with INIT-SIPI-SIPI. Without ACPI the machine stays on the uniprocessor path.
64 process slots
Kernel threads and ring-3 processes share a sparse, stable PCB table. Kernel threads are pinned to the BSP; user work can run on any AP.
8 windows
Terminal and canvas windows are composited by the window manager, with per-window RGB565 canvases mapped into the owning process.
8 MB rootfs
The command pack travels as a compressed NBROOT1 image and is inflated into a read-only ramfs at boot. Runtime replacement needs no reboot.
Design constraints
The unusual parts of the architecture follow from a few hard rules.
They explain why the code uses fixed low-memory blocks, why the kernel
is linked below 0x90000, and why so much care goes into
keeping the kernel image small.
- Freestanding C. The kernel has no libc,
mallocorprintf; ring-3 commands can link the in-treelibc.a(malloc, strings, stdlib). Formatting and allocation are in-tree either way. - i586 baseline. Builds use
-march=i586 -mno-sse -mno-sse2 -mno-mmx; SSE2 drawing paths are probed at runtime. - Identity-mapped paging. Physical and virtual addresses are equal. There is no per-process address space or isolation.
- 1 GB lowmem, 4 GB highmem. The identity map ends where ring-3 space starts (
0x40000000); RAM up to 4 GB backs ring-3 pages through per-CPUkmapslots. - Hardcoded low memory. Boot info, the E820 map, the framebuffer block and the AP trampoline have fixed addresses that every boot path must honour.
- No firmware runtime.
rebootuses the ACPI reset register (with PCH/KBC fallbacks) andpoweroffwrites ACPI S5 from the FADT/DSDT; UEFI runtime services are not called afterExitBootServices.
Fresh memory is not zeroed. mm_alloc_page and kmalloc return whatever RAM contained. Every structure read before it is written must be cleared on allocation; QEMU hides this because its RAM starts clear.
Reading path
If you are new to the tree, follow the machine through a boot:
- Boot — the real-mode stage, the UEFI loader and the
0x500/0x600handoff contract. - Memory — the fixed low-memory map and the 4 KB frame allocator it feeds.
- CPU & scheduling — interrupt setup, the CFS-lite scheduler and the big kernel lock.
- Drivers — how storage, USB, input and sensors are discovered.
- Graphics — the shadow buffer, compositor and ring-3 canvas model.
The remaining pages cover the filesystem and command-pack pipeline, the network stack, the ring-3 ABI and the development workflow.
Subsystem map
Boot & firmware
BIOS boot sector, VESA stage, MBR, UEFI loader, kexec trampoline and the boot-info block.
boot.htmlMemory & paging
E820 map, 4 KB frame bitmap, kmalloc, process stacks, the ring-3 arena and libc malloc, and the hardcoded address ladder.
memory.htmlCPU & scheduling
GDT/TSS, interrupts, AP bring-up, CFS-lite weights, wait queues, the BKL, idle and power states.
cpu.htmlDrivers & buses
PCI enumeration, FDC/PATA/SATA/eMMC, the USB core and four host controllers, HID, the I2C touchpad, serial, board sensors and the ThinkPad/Chrome EC power sources.
drivers.htmlStorage & filesystems
VFS vtable, FAT12/16/32, the ramfs pack pipeline, persistent /data, /share, the disks manager with its mount policies and the WebDAV view of the VFS.
Graphics & UI
VBE framebuffer, shadow buffer, damage rectangles, compositor, canvas ABI, ngui, the Adwaita UI icons and mouse cursors, the fixed-point TrueType text engine and image codecs.
graphics.htmlNetworking
NIC registry, ARP/ICMP/UDP, DHCP, DNS, NTP, TCP client and listener, TLS 1.3/1.2, USB tethering, WiFi, the top-bar control panel, netconsole and netkexec.
network.htmlWiFi
Intel 7265D/3165 (Chromebook, MVM firmware) and 6200/6300 (ThinkPad X201, DVM firmware) on one PCIe transport, plus Realtek RTL8821AU USB sticks; firmware from the command pack, open and WPA2-PSK/CCMP with the handshake in ring 3.
drivers.html#wifiChat client
Native Cloudron Chat app: OIDC username/password/TOTP login without a browser, a uhttp cookie jar, an arena JSON parser and REST polling.
network.html#chatUserland
Ring-3 address space, ELF loading, syscall groups, the optional libc and malloc, PATH dispatch, the command pack and GUI apps.
userland.htmlInit & services
PID 1 init, the WM and service lifecycle, per-service tty logs and state, the service CLI/GUI, and the parent-death process tree with explicit detached spawns.
Ring-3 libc
Optional static libc.a: boundary-tag malloc/free/realloc, strings, stdlib and heap_reset over the 64 MB SYS_MEM arena.
Development
Toolchain, build images, QEMU targets, serial/network reload, tests and low-level debugging tools.
development.htmlRepository tour
The tree is split by privilege and lifetime: boot/ holds the boot stages (boot sector, MBR, VESA stage, UEFI loader), kernel/ the ring-0 kernel, and user/ the ring-3 world, with one directory per program under user/apps/ and one per library under user/lib/. include/ holds the ABI headers every side shares (syscall numbers, the WM ABI, boot info, the rootfs header), common/ the few freestanding sources linked into both kernel and userland, and tools/ the host-side tools. The top-level Makefile builds everything; objects go to build/ and the images stay at the top.
| Area | Important files |
|---|---|
| Boot chain | boot/boot.S boot/mbr.S boot/vesa_stage.S boot/efi/ kernel/entry.S |
| Kernel core | kernel/kernel.c kernel/sched.c kernel/process.c kernel/mm.c kernel/paging.c kernel/syscall.c include/syscall.h |
| Devices | kernel/: usb.c uhci.c ohci.c ehci.c xhci.c usbmsc.c ata.c ahci.c |
| Services | kernel/: sys_fs.c sys_net.c gfx.c sys_wm.c sys_info.c install.c |
| Userland | user/apps/<name>/ucmd_<name>.c user/ucmd_lib.h user/lib/libc/ user/lib/ngui/ user/lib/ufont/ user/lib/img/ user/lib/tls/ user/lib/uhttp/ user/lib/ujson/ user/apps/browser/ user/apps/chat/ third_party/quickjs/ fonts/ |
| Build & pack | Makefile tools/mkpack.c tools/mkrootfs.c kernel/kernel.ld user/ucmd.ld |
| Documentation | AGENTS.md and this docs/ folder |
Keep both maps current. Architecture changes belong in AGENTS.md and in the matching page under docs/. The maintenance rule is repeated in AGENTS.md.