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.
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.
- Compiler.
gccwith 32-bit multilib,as,ld,objcopy. - Kernel flags.
-m32 -march=i586 -ffreestanding -fno-pie -nostdlib -fno-stack-protector -mno-sse -mno-sse2 -mno-mmx -O2. - Warnings. The build uses
-Wall -Wextra; a new warning is a bug, not noise. - User commands. Linked at
0x40000000withucmd.ld, stripped, and packed asbin/<name>. - UEFI.
x86_64-w64-mingw32-gccbuildsBOOTX64.EFI;make alldoes not require it. - Images.
mtoolsbuildsroot.imgand the ESP. - WiFi firmware. The pack includes
firmware/iwlwifi-7265D-29.ucode(Chromebook) andfirmware/iwlwifi-6000-4.ucode(X201), decompressed withzstdfrom the host's linux-firmware (WIFI_FW_7265D=/WIFI_FW_6000=/path/to/file[.zst]override the search). A missing file only prints a note and leaves that card without firmware; the floppy images always use the firmware-lesscmds-lite.pack.
Build pipeline
Make targets
| Target | What it does |
|---|---|
make all | Build floppy.img, usb.img, final.bin and root.img. |
make run / run-smp | Boot the floppy in QEMU, optionally with four CPUs (Atom 330 topology). |
make run-usb | Boot usb.img as an IDE disk. |
make run-uhci / run-ehci / run-xhci | Exercise 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-asix | Pass through a real ASIX AX88772 dongle. |
make run-net | Add a PCI NE2000 on QEMU's slirp network with host port 8080 forwarded. |
make run-rndis | Boot with qemu-xhci and QEMU's full-speed usb-net RNDIS device on slirp; the tethering link gets DHCP from QEMU. |
make run-ahci | Add an ICH9 AHCI controller and a 512 MB SATA disk. |
make uefi / run-uefi / test-uefi | Build the dual-boot image, boot it under OVMF, or run the headless serial check. |
make rootfs | Rebuild cmds.img only. |
make nowm | Diagnostic kernel with the WM disabled; the boot console stays visible. |
make dev / kernel-dev | Serial reload of kernel + rootfs, or kernel only (keep the running rootfs). |
make net-dev / kernel-net-dev | RAM-only network reload of kernel + rootfs, or kernel only. |
make net-install | Persist kernel + full rootfs to P1/P2 over UDP, keeping /data; NETINSTALL_TARGET=auto selects the internal NebOS disk. |
make cmds-dev / net-cmds | Replace /ramfs at runtime over serial or UDP. |
make monitor / netmon | Open the serial console, or listen to the UDP console mirror. |
make flash | Write the dual-boot image to a USB stick (needs mingw and prompts for the device). |
make test-usb | Headless QEMU mouse/keyboard regression tests using QMP and screen dumps. |
make test-install | Boots 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-asan | Host image-decoder and blit tests, with an AddressSanitizer variant. |
make test-crypto | Host vectors for SHA-256, ChaCha20-Poly1305, X25519 and TLS helpers. |
make test-wpa | Host 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-store | Host 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-libc | Host tests for the ring-3 malloc, stdio/float formatting, math, 64-bit division helpers and setjmp/longjmp. |
make test-js | Host 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-asan | Host specimen test for the fixed-point TrueType parser/rasterizer and glyph cache, with an AddressSanitizer/UBSan variant. |
make test-svg | Host 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-touchpad | Host 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-chat | Host tests (ASan/UBSan) for the chat client's JSON parser, cookie jar and the OIDC login page/reply/config parsers. |
make test-chat-e2e | Boots 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-serve | Serve the browser compatibility ladder from testdata/browser/compat/ on port 8000 for the board or QEMU guest. |
make fonts | Regenerate 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]
- Full reload.
make devstages kernel and rootfs in one page-allocated buffer, copies the kernel to0x7E00and publishes the pack range in boot info. - Kernel only.
make kernel-devsendspack_size == 0; the new kernel keeps the running rootfs. - Pack only.
make cmds-devusesKXNPandramfs_replace(), without a kernel jump. - Monitor. Run
make monitorin a second terminal; each reload printsNebOS v0.2.0 bootedon COM1.
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, detects the KXN2/KXNP header and
pauses the auto-detect while a packet-level command owns the NIC or a
transfer is in progress. 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.
- Existing processes are unaffected. They already loaded their ELF.
- The next spawn sees the new files.
- RAM only. A cold boot uses the flashed rootfs; reflash after changing the bundle.
- Size. The raw pack is about 2 MB with the WiFi firmware, so
cmds-devover 115200 serial takes roughly three minutes; prefernet-cmds.
Tests
- USB regression.
make test-usbruns QMP cursor and keyboard tests against UHCI, OHCI, EHCI and xHCI, including hotplug. - Installer.
make test-installboots the dual image with its USB mass-storage source and a blank target, typesinstall ide1through QMP, verifies the clone and boots the target in BIOS and (under OVMF) UEFI. - Image library.
make test-imagesdecodes a corpus of PNG/JPEG/GIF/BMP/TGA/PNM/ICO/PAM files and checks blits; the ASan variant catches memory errors. - Crypto.
make test-cryptoruns host vectors for the freestanding crypto code. - WPA2.
make test-wparuns wpa_test.c against wpa_crypto.c and wpa.c.make test-wifi-storeruns the saved-network list against an in-memory FAT file: ordering, update, eviction, forget and the legacy/malformed formats. The WiFi driver itself has no QEMU model: test it on the Chromebook overmake net-devwith the RNDIS phone or ASIX dongle as the management link andmake netmonfor theiwl:/wifi:trail. - Ring-3 libc.
make test-libcruns the malloc stress test (64 MB simulated arena with poisoned pages), exactsnprintffloat/string checks against the host, x87 math values, the 64-bit division helpers and a 32-bit setjmp/longjmp test. - Fonts.
make test-fontparses the checked-in Arimo subset on the host, measures Latin-1 text, renders composites (for exampleÄé) and writes a specimen PPM. The browser must also be exercised across a navigation to verify detach/reattach aroundheap_reset(). - Touchpad gestures.
make test-touchpadfeeds synthetic contact frames to touchpad_gesture.c and checks one/two-finger taps, the corner and physical-button mapping, scroll start/direction, pointer freeze and re-anchoring, and the option switches. - Chat client.
make test-chatcovers the pure modules on the host.tools/mock_chat.pyis a two-origin mock of Cloudron Chat (port 18080) and the Cloudron OIDC login (18081) withtest,totp(code 123456),passkeyandconsentaccounts (passwordtest) and/debug/state,/debug/injectendpoints; run it alone and enterhttp://10.0.2.2:18080in a QEMU guest's chat, or letmake test-chat-e2edrive it. Screenshots land inchat-test-out/. - Browser compatibility.
make compat-serveserves the numbered A/B ladder intestdata/browser/compat/. Open the index on the board (or athttp://10.0.2.2:8000/from a QEMU guest with user networking) and compare each pair; the index table records the current status. - UEFI.
make test-uefiboots the dual image under OVMF headless and greps the serial log for the boot line. - Compositor stats. The ring-3 WM overwrites
/share/wmstatsevery two seconds withframes, total and worst compositing time in milliseconds, and the pixels drawn in the interval. Read it in a terminal or fetch it over WebDAV to measure a target.
Debugging
- Serial log.
make monitorshows the boot trace and printf-style driver output. TheNebOS v… bootedline is written before the framebuffer is ready. - Boot time. Timestamp COM1 on the host (QEMU
-serial stdio): the kernel starts atNebOS v… booted, the desktop atwm: first frame, and the terminal is on screen atwm: first window frame (term) at N ms(kernel uptime). On QEMU the USB image reaches it about 0.4 s after the kernel starts; USB, the NIC and the disks are probed after that ([boot] usb/net/storagelines). - Network console.
make netmonlistens to UDP 19290 for serial and terminal output;netconsole host <ip>narrows the target. - dbg. The ring-0 serial monitor accepts
r addr len,w addr b0 …,i port,o port val,handq. - Panic. A ring-0 fault dumps vector, error code, registers, CRs, EIP bytes and stack candidates to the LFB and COM1. Resolve addresses with
nm kernel.elf/addr2line -e kernel.elf. - Profiling.
gfxbenchtimes fill/copy/cell/canvas/flush;top,sched,sensors,powerinfo,powerandlspci/lsusbexpose live state. - Memory.
peek addr lenhex-dumps identity-mapped memory (MMIO too);poke addr valwrites one dword and prints the read-back.
Conventions & gotchas
- Freestanding C. The kernel has no libc,
mallocorprintf; useio_putstr,io_putcharandio_puthex. Ring-3 commands may linklibc.afrom libc/; link it explicitly and compile the app with-Ilibc/include. - Fresh memory is not zeroed. Clear structures whose fields are read before being written. QEMU starts RAM clear and hides the bug.
- Keep the memory map in sync. Hardcoded addresses appear in assembly, C headers and linker scripts; changing one without the others breaks boot or loading.
- Ring-3 data segments. An IRET to ring 3 nulls DS/ES/FS/GS whose DPL is below CPL 3. Kernel stubs must restore selector
0x23withIRQ_RETURN_DS. QEMU does not model this; only real hardware fails. - Paging is flat. Physical equals virtual everywhere; there is no process isolation.
- The BKL is not preemptible. A BKL holder can be in the middle of kernel structures; block points drop it, and
bkl_pause()is for long waits. - Kernel size wall.
_endmust stay below0x90000; the legacy staging gap also constrains the loaded image and the compressed pack.
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:
| Change | Update |
|---|---|
| Boot path, boot info, image layout | boot.html |
| Address map, allocator, paging, user arenas | memory.html |
| Scheduler, interrupts, SMP, BKL, power | cpu.html |
| PCI, storage, USB, input, sensors | drivers.html |
| VFS, FAT, ramfs, /share, WebDAV | filesystems.html |
| Framebuffer, WM, canvas, ngui, images | graphics.html |
| NIC, protocols, TLS, netconsole | network.html |
| Syscalls, shell, pack, apps | userland.html |
| Build targets, reload, tests, debugging | development.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
Makefile— targets and image ruleslibc/,libc.a— optional ring-3 libc and its host testthird_party/quickjs/(see itsVENDOR),js_mu.c/h,js_browser.c/h— vendored JavaScript engine, its MuJS-style stack API and the browser bindings;js_test.chost testsufont.c,ufont_ttf.c,fonts/— UI font engine and subsets;ufont_test.chost testkexec.c,kexec_send.c— serial reloadnetkexec.c,netkexec_send.c— network reloadnetlog.c,netmonitor.c— UDP consoledbg.c— serial debug monitorpanic.c— fatal exception dumpkernel.ld,ucmd.ld— link limitstools/— QMP USB and installer testswpa_test.c— WPA2 supplicant host test (make test-wpa)wifi_store_test.c— saved WiFi list host test (make test-wifi-store)AGENTS.md— developer notes and maintenance rule