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.

i586 · 32-bit freestanding kernel · ring-3 libc BIOS + UEFI serial + net hot reload

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.

NebOS software stack Five layers: ring-3 commands and GUI apps, the int 0x80 syscall boundary, kernel services, drivers and platform support, and firmware and hardware. Ring 3 · commands & GUI apps ls · cat · edit · view · files · process · bootscan · browser · chat · gallery · solitaire 0x40000000 Syscall boundary · int 0x80 SYS_* services · one string argument · canvas mapped at 0x50000000 Kernel services CFS-lite scheduler · VFS · FAT + ramfs · TCP/IP + TLS window server · file / info / memory services Drivers & platform PCI · PATA/SATA · FDC · USB UHCI/OHCI/EHCI/xHCI · NICs PS/2 + USB HID · serial · ACPI/MADT · thermal · power Firmware & hardware · BIOS or UEFI · i586 CPU · VGA/VBE · RAM user kernel drivers firmware
The layering is real, not just conceptual. Ring-3 commands enter the kernel only through 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.

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:

  1. Boot — the real-mode stage, the UEFI loader and the 0x500/0x600 handoff contract.
  2. Memory — the fixed low-memory map and the 4 KB frame allocator it feeds.
  3. CPU & scheduling — interrupt setup, the CFS-lite scheduler and the big kernel lock.
  4. Drivers — how storage, USB, input and sensors are discovered.
  5. 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.html

Memory & paging

E820 map, 4 KB frame bitmap, kmalloc, process stacks, the ring-3 arena and libc malloc, and the hardcoded address ladder.

memory.html

CPU & scheduling

GDT/TSS, interrupts, AP bring-up, CFS-lite weights, wait queues, the BKL, idle and power states.

cpu.html

Drivers & 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.html

Storage & 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.

filesystems.html

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.html

Networking

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.html

WiFi

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#wifi

Chat 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#chat

Userland

Ring-3 address space, ELF loading, syscall groups, the optional libc and malloc, PATH dispatch, the command pack and GUI apps.

userland.html

Ring-3 libc

Optional static libc.a: boundary-tag malloc/free/realloc, strings, stdlib and heap_reset over the 64 MB SYS_MEM arena.

userland.html#libc

Development

Toolchain, build images, QEMU targets, serial/network reload, tests and low-level debugging tools.

development.html

Repository 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.

AreaImportant 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.