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.
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 (and storage on EHCI). |
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-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 | Network reload of kernel + rootfs, or kernel only. |
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-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-libc | Host stress test for the ring-3 malloc, realloc, calloc and heap_reset. |
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-dev # 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-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.
Tests
- USB regression.
make test-usbruns QMP cursor and keyboard tests against UHCI, OHCI, EHCI and xHCI, including hotplug. - 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. - Ring-3 libc.
make test-libcruns a deterministic allocation/free/realloc stress test and a browser-like large-buffer sequence; the backend simulates the fixed 32 MB arena and poisons new pages. - 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. - 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 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 testsAGENTS.md— developer notes and maintenance rule