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.

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 *.c · *.S · linker scripts ring-3 sources ucmd_*.c · ngui · browser UEFI loader 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 (and storage on EHCI).
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-ahciAdd an ICH9 AHCI controller and a 512 MB SATA disk.
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-devNetwork reload of kernel + rootfs, or kernel only.
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-images / test-images-asanHost image-decoder and blit tests, with an AddressSanitizer variant.
make test-cryptoHost vectors for SHA-256, ChaCha20-Poly1305, X25519 and TLS helpers.

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

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