Development

Edit, reload, watch the boot line.

A normal iteration does not reflash anything. The board receives a new kernel and rootfs over serial or UDP, parks its APs, jumps into the new image and prints the same version line on COM1. A runtime command-pack update can skip even the kernel reload.

gcc · as · ld · objcopy QEMU + real hardware KXE2 · KXN2 · KXNP headless tests

Toolchain

NebOS builds with a normal GNU toolchain for 32-bit x86, plus mtools for FAT images and QEMU for testing. The UEFI loader is the only 64-bit component and needs the mingw cross compiler.

Source tree

One top-level Makefile builds every directory. Intermediate objects go to build/, mirroring the source paths, with compiler-generated header dependencies (-MMD); the images and the files the dev workflow sends or inspects (kernel.elf, kernel.bin, floppy.img, usb.img, usb-efi.img, BOOTX64.EFI, cmds.pack, cmds_pack_gz.bin, browser.elf, gallery.elf) stay at the top level.

DirectoryContentsInclude path
boot/Boot sector, MBR, VESA stage; boot/efi/ UEFI loaderinclude/, kernel/ (EFI: vga.h)
kernel/Kernel, drivers, services, kernel.ld; host tests for ccmp and the touchpad gesturesinclude/, common/, kernel/
common/Freestanding code linked into both kernel and userland: inflate.c, font_8x16.citself
include/Shared ABI headers: syscall.h, wm_abi.h, bootinfo.h, phys.h, rootfs.h, version.h, wifi_cfg.h, rtl8821a_tbl.h—
user/ucmd_lib.h, ucmd.ldinclude/, common/, user/, every user/lib/*; libc headers by default
user/apps/<name>/One ring-3 program each, entry file ucmd_<name>.c plus its private modules (the browser, chat, gallery)as user/
user/lib/<lib>/libc, ngui, ufont, img, tls (crypto + TLS), uhttp, ujson, uwm, wifi (saved networks, WPA2), each with its host testsas user/
tools/Host tools (mkpack, mkrootfs, mkrtwtbl, kexec_send, netkexec_send, netmonitor, flash.sh) and the QMP test scriptsinclude/
host/Linux SDL3 browser harnessas user/

The kernel never includes a userland header. The one userland file that reaches into the kernel is user/apps/term/ucmd_term.c (IO_KEY_* and VFS_PATH_MAX), which gets -Ikernel explicitly. A new command is a directory user/apps/<name>/ with ucmd_<name>.c and an entry in UCMDS; one that links libraries gets an explicit .elf rule in the Makefile. Per-object flags (-Os, function sections, no libc headers) are target-specific variables on the .o, and make does not track them: after changing one, delete the object or run make clean.

Build pipeline

NebOS build pipeline Kernel sources become kernel.bin and boot.bin; ring-3 sources become cmds.pack and a gzip rootfs; the UEFI loader embeds kernel, pack and trampoline. The outputs feed floppy, USB and dual-boot images. kernel sources boot/ · kernel/ · common/ ring-3 sources user/apps/* · user/lib/* UEFI loader boot/efi/*.c · tramp.S gcc · as · ld · objcopy kernel.elf → kernel.bin mkpack · gzip · mkrootfs cmds.pack → NBROOT1 mingw gcc BOOTX64.EFI floppy.img · final.bin boot sector + kernel + rootfs usb.img MBR + boot + 8 MB rootfs usb-efi.img · 17 MB usb.img + 8 MB FAT16 ESP Hot reload skips the image step: make dev / net-dev sends kernel.bin + cmds_pack_gz.bin; cmds-dev / net-cmds sends cmds.pack.
Two independent products. The kernel image and the rootfs container have separate lifetimes: a kernel reload can keep the running rootfs, and a pack update can keep the kernel.

Make targets

TargetWhat it does
make allBuild floppy.img, usb.img, final.bin and root.img.
make run / run-smpBoot the floppy in QEMU, optionally with four CPUs (Atom 330 topology).
make run-usbBoot usb.img as an IDE disk.
make run-uhci / run-ehci / run-xhciExercise the USB backends with a mouse/keyboard; the EHCI target also attaches a USB mass-storage disk, and the installer test covers EHCI and xHCI storage.
make run-ehci-asix / run-xhci-asixPass through a real ASIX AX88772 dongle.
make run-netAdd a PCI NE2000 on QEMU's slirp network with host port 8080 forwarded.
make run-rndisBoot with qemu-xhci and QEMU's full-speed usb-net RNDIS device on slirp; the tethering link gets DHCP from QEMU.
make run-ahciAdd an ICH9 AHCI controller and a 512 MB SATA disk.
make run-amd / test-amdBoot QEMU with -cpu Opteron_G5 -smp 6 (the FX-6350's family 15h model 2), OHCI, six CPUs and an e1000; the headless test also checks ioapic: masked, smp cpus: 6 and the PIT.
make uefi / run-uefi / test-uefiBuild the dual-boot image, boot it under OVMF, or run the headless serial check.
make rootfsRebuild cmds.img only.
make nowmDiagnostic kernel with the WM disabled; the boot console stays visible.
make dev / kernel-devSerial reload of kernel + rootfs, or kernel only (keep the running rootfs).
make net-dev / kernel-net-devRAM-only network reload of kernel + rootfs, or kernel only.
make net-installPersist kernel + full rootfs to P1/P2 over UDP, keeping /data; NETINSTALL_TARGET=auto selects the internal NebOS disk.
make cmds-dev / net-cmdsReplace /ramfs at runtime over serial or UDP.
make monitor / netmonOpen the serial console, or listen to the UDP console mirror.
make flashWrite the dual-boot image to a USB stick (needs mingw and prompts for the device).
make test-usbHeadless QEMU mouse/keyboard regression tests using QMP and screen dumps.
make test-installBoots the dual image with a USB mass-storage source and a blank target, types install ide1, verifies the clone and boots the target in BIOS and UEFI.
make test-images / test-images-asanHost image-decoder and blit tests, including reduced-IDCT JPEG decode against a box-filtered reference; AddressSanitizer variant included.
make test-cryptoHost vectors for SHA-256, ChaCha20-Poly1305, X25519, AES-128-GCM, P-256, the TLS 1.2 PRF and TLS helpers.
make test-wpaHost vectors for the WPA2 supplicant: SHA-1, RFC 6070 PBKDF2, the 802.11 PSK and PRF examples, FIPS-197 AES, RFC 3394 unwrap, plus a simulated 4-way handshake, group rekey, replay and wrong-passphrase case.
make test-wifi-storeHost test for the saved-network file: newest-first ordering, passphrase update, LRU eviction at the 16-entry cap, per-SSID forget, the old one-record format and malformed or duplicate lists.
make test-libcHost tests for the ring-3 malloc, stdio/float formatting, math, 64-bit division helpers and setjmp/longjmp.
make test-jsHost tests (ASan/UBSan) for the vendored QuickJS engine through the js_mu stack API: modern syntax (classes, arrows, templates, destructuring, spread, async/await, BigInt, named regex groups), Promise jobs, C functions and new, thrown TypeErrors, userdata hooks and expandos, registry refs and the wall-clock interrupt.
make test-font / test-font-asanHost specimen test for the fixed-point TrueType parser/rasterizer and glyph cache, with an AddressSanitizer/UBSan variant.
make test-svgHost tests (ASan/UBSan) for the inline-SVG rasterizer: exact rect coverage, antialiased edges, relative commands, nonzero vs even-odd, circle area, curves and arcs, transforms, number grammar and strokes; ./svg_test out.ppm writes a specimen.
make test-touchpadHost tests for the device-independent contact gesture engine: taps, right-click zones, physical-button latch, two-finger scroll, direction and pointer re-anchoring.
make test-chatHost tests (ASan/UBSan) for the chat client's JSON parser, cookie jar and the OIDC login page/reply/config parsers.
make test-chat-e2eBoots QEMU with an NE2000 on slirp, starts tools/mock_chat.py and drives chat through QMP: native login, send, live poll, read marker, older paging, browse/join, new DM, saved-session resume and sign-out. CHAT_E2E=--totp|--consent|--passkey|--wrong runs a login variant.
make compat-serveServe the browser compatibility ladder from testdata/browser/compat/ on port 8000 for the board or QEMU guest.
make browser-hostBuild the Linux SDL3 development harness (browser-host and its host-curl helper). It implements the ring-3 SYS_* ABI with host files, BSD sockets, fork/exec and an SDL3 window, so pages render and accept input without QEMU. Run ./browser-host [--size WxH] [--root DIR] URL|FILE; --headless --wait 3000 --shot out.ppm writes the canvas without a display, and --keys 'clo{down}{enter}' types into it (one key per 100 ms; {enter}, {esc}, {tab}, {bs}, {del}, arrows, {ctrl-l}, {wait}). Needs the 32-bit SDL3/Wayland libraries (lib32-sdl3, lib32-wayland, lib32-libxkbcommon).
make fontsRegenerate the checked-in Arimo/Liberation Mono subsets with pyftsubset.

QEMU guests default to 512 MB, matching MM_MAX_PHYS in phys.h. Override the size with QEMU_MEM, for example make run QEMU_MEM=1G; all run and UEFI targets pass it through.

Serial reload

COM1 runs at 115200 8N1. The WM idle loop watches the receive ring for the KXE2 magic and auto-spawns the reload, so a plain make dev is enough. The manual kexec command is a fallback that waits for the same image.

[magic "KXE2"][entry u32][kernel_size u32][pack_size u32]
[kernel][rootfs gzip][checksum u8]

The serial receive drops the BKL while it waits for bytes, so the WM and the other CPU's syscalls stay responsive during a reload.

Network reload

For boards without a serial port, the same reload runs over UDP port 19288 with the KXN2 magic. The host tool sends the kernel and rootfs as one stop-and-wait stream; the board acknowledges every datagram with the next expected offset and verifies a 32-bit checksum before jumping.

make net-install uses KXI2 instead. It sends the kernel plus a full NBROOT1 rootfs image (rootfs-full.bin) and a 16-byte target name; the board writes P2, the P1 kernel, patches the exact kernel_sectors, verifies the result, acks ACK_INSTALLED and jumps. It never touches P4 (/data) or the MBR, so it is the persistent counterpart to the RAM-only net-dev. NETINSTALL_TARGET=auto selects the only non-USB NebOS disk.

make net-dev                    # RAM-only kernel + rootfs to 192.168.178.240
make net-dev BOARD_IP=192.168.178.42
make kernel-net-dev             # kernel only; keep the rootfs
make net-install                # persist kernel + full rootfs, keep /data
make net-install NETINSTALL_TARGET=sata0
make net-cmds                   # replace /ramfs only

The board must be idle at a shell prompt. The WM loop answers ARP/ICMP while idle, detects the KXN2/KXNP header and pauses the auto-detect while a packet-level command owns the NIC or a transfer is in progress. During the transfer the receive loop keeps answering ARP/ICMP itself, so the host's neighbour entry cannot expire mid-upload. Datagrams are at most 1400 bytes.

The board address comes from DHCP when a server is present; use make net-dev BOARD_IP=<leased-address>, or pin an address with netip on the board.

Runtime command pack

make cmds-dev sends the raw cmds.pack with the KXNP magic. The receiver validates the pack before the swap, so a truncated transfer leaves the running commands untouched. A good pack is installed by ramfs_replace() and the old heap copy is freed.

Tests

Debugging

Conventions & gotchas

Keeping docs current

This site is static HTML with one shared stylesheet, no JavaScript and no build step. It is part of the tree, not generated output. When a subsystem changes, update the matching page and the overview card in the same change:

ChangeUpdate
Boot path, boot info, image layoutboot.html
Address map, allocator, paging, user arenasmemory.html
Scheduler, interrupts, SMP, BKL, powercpu.html
PCI, storage, USB, input, sensorsdrivers.html
VFS, FAT, ramfs, /share, WebDAVfilesystems.html
Framebuffer, WM, canvas, ngui, imagesgraphics.html
NIC, protocols, TLS, netconsolenetwork.html
Syscalls, shell, pack, appsuserland.html
Build targets, reload, tests, debuggingdevelopment.html

AGENTS.md repeats the rule and lists the same page map. Numbers in charts must come from a source constant or table; if a constant moves, update the chart caption and the source file that defines it.

Source map