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.
- 512 MB physical ceiling. The frame bitmap covers 512 MB; anything above that is unmapped.
- 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.
rebootandpoweroffuse legacy ports; 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, the USB core and four host controllers, HID, the I2C touchpad, serial and board sensors.
drivers.htmlStorage & filesystems
VFS vtable, FAT12/16/32, the ramfs pack pipeline, /share and the WebDAV view of the VFS.
Graphics & UI
VBE framebuffer, shadow buffer, damage rectangles, compositor, canvas ABI, ngui, the fixed-point TrueType text engine and image codecs.
graphics.htmlNetworking
NIC registry, ARP/ICMP/UDP, DHCP, DNS, TCP client and listener, TLS 1.3, netconsole and netkexec.
network.htmlUserland
Ring-3 address space, ELF loading, syscall groups, the optional libc and malloc, PATH dispatch, the command pack and GUI apps.
userland.htmlRing-3 libc
Optional static libc.a: boundary-tag malloc/free/realloc, strings, stdlib and heap_reset over the 32 MB SYS_MEM arena.
Development
Toolchain, build images, QEMU targets, serial/network reload, tests and low-level debugging tools.
development.htmlRepository tour
NebOS is deliberately flat: the kernel, the freestanding libraries and the ring-3 commands live side by side at the repository root. The linker scripts and the Makefile are the map.
| Area | Important files |
|---|---|
| Boot chain | boot.S mbr.S vesa_stage.S entry.S efi/ |
| Kernel core | kernel.c sched.c process.c mm.c paging.c syscall.c |
| Devices | usb.c uhci.c ohci.c ehci.c xhci.c ata.c ahci.c |
| Services | sys_fs.c sys_net.c gfx.c sys_wm.c sys_info.c |
| Userland | ucmd_*.c ucmd_lib.h libc/ third_party/mujs/ ngui.c ufont.c ufont_ttf.c fonts/ browser.c js_browser.c gallery.c |
| Build & pack | Makefile mkpack.c mkrootfs.c kernel.ld 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.