Boot & firmware

Three ways into the same kernel.

A legacy BIOS floppy, a dual-boot USB image under UEFI, and a live serial or network reload all converge on kernel_entry. They must agree on three things: the low-memory boot structures, the rootfs pack location, and a 32-bit flat protected-mode environment.

512-byte boot sector real-mode VESA stage x86-64 UEFI loader kexec hot reload

Three paths, one entry point

The boot code is deliberately split by execution mode. The BIOS path starts in 16-bit real mode, the UEFI path starts in 64-bit long mode, and the kexec path starts in the running 32-bit kernel. All three end at kernel_entry in entry.S, which immediately re-points ESP at the new image's own boot stack before calling kernel_main.

Three NebOS boot paths BIOS boot sector to VESA stage to kernel entry; UEFI BOOTX64.EFI to trampoline to kernel entry; kexec receiver to trampoline to kernel entry. BIOS · floppy / USB boot.S at 0x7C00 → vesa_stage.S real mode → protected mode UEFI · usb-efi.img BOOTX64.EFI · x86-64 GOP + GetMemoryMap kexec · make dev / net-dev KXE2 serial · KXN2 UDP running kernel receives image VESA stage E820 · VBE mode · rootfs 0x500 / 0x600 / 0x1000 UEFI trampoline 0x800 · leave IA-32e kernel copy to 0x7E00 kexec trampoline APs parked · copy kernel keep framebuffer kernel_entry · entry.S ESP = __boot_stack_top jmp kernel_main 32-bit flat · paging off
Every path hands off in the same shape: flat 32-bit segments, paging off, the framebuffer block at 0x600, the boot-info block at 0x500, and the kernel loaded at 0x7E00.

BIOS path

boot.S — the 512-byte boot sector

The boot sector carries a FAT16 BPB, loads the contiguous kernel directly after itself to 0x7E00, and jumps there. Each INT 13h reads a run of sectors into ES:0 and then advances ES, so the offset never wraps: fixed disks use EDD LBA (AH=42h) with up to 64 sectors, floppies use CHS up to the end of the track and never across a 64 KB physical ISA DMA boundary. One call per sector used to make the kernel load ~700 BIOS calls, each of which can cost a floppy revolution. A failing run is tried three times, then the loader drops to one sector per call (the old behaviour) before it reports Disk read error. The sector count and the rootfs LBA are patched into the boot sector by the Makefile.

On the USB image, mbr.S runs first and loads the active partition's boot sector at LBA 63. From there the path is identical.

vesa_stage.S — the real-mode setup

The VESA stage is the busiest piece of the legacy chain. It runs in real mode at 0x7E00 and performs five jobs:

  1. Probe the INT 15h E820 memory map into 0x1000.
  2. Enable A20 and read the NBROOT1 rootfs header at the boot sector's pack_lba field.
  3. Copy the compressed pack directly to 0x900000 above the 8 MB VGA-shadow reserve, in 16 KB staging chunks at 0x3000 (one INT 13h per chunk: 32 sectors over EDD, or up to the end of the track over CHS, which never crosses a 64 KB DMA boundary; a BIOS that refuses a multi-sector request falls back to one sector per call), using a temporary flat protected-mode rep movsb. The X201 BIOS's INT 15h AH=87h block move silently copies zeros to this range, so the CPU copy is used instead.
  4. Pick the best VBE mode: at least 16 bpp, a linear framebuffer, it must fit the card's VRAM, and the width must be at most 1280 pixels. Mode information is written to 0x600; the 12-dword boot-info block goes to 0x500.
  5. Enter protected mode and jump to kernel_entry.

The pack no longer occupies the old 0x60000..0x9FBFF low gap, so the legacy cap is PACK_MAX (2 MB, raised from 1 MB for the WiFi firmware) and the kernel BSS/boot stack may use the gap. The kernel image only has to stay below 0x90000 so the top of low memory and the EBDA remain untouched; kernel.ld enforces that with a link-time assertion.

BIOS state after the move. The X201's BIOS historically left translation bits behind after AH=87h; paging.c still clears CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP and EFER.LME before it enables paging, because other BIOS protected-mode calls can do the same. The protected-mode copy keeps the pack safe until ramfs.c takes a private page-allocated copy and releases the boot region.

UEFI path

efi/main.c is a freestanding x86-64 PE32+ application built with x86_64-w64-mingw32-gcc. It does not execute any of the legacy boot chain. Instead it:

  1. Selects a GOP mode with BGRX or RGBX 32bpp, width at most 1280, pitch × height at most 8 MB, and a framebuffer below 4 GB.
  2. Calls GetMemoryMap and converts the firmware map into the kernel's E820 format at 0x1000.
  3. Locates the parent whole-disk Block I/O handle from the ESP device path, reads the P1 boot sector and P2 NBROOT1 header, and stages the kernel below 4 GB and the gzip pack below the 512 MB identity window. The kernel/pack embedded in BOOTX64.EFI are a fallback only.
  4. Writes the boot-info and framebuffer blocks, calls ExitBootServices, then copies a 192-byte trampoline to 0x800.
  5. Leaves IA-32e mode (clears CR0.PG, EFER.LME, CR4.PAE/PGE/PCIDE/SMEP/SMAP/LA57), copies the kernel to 0x7E00, and jumps to kernel_entry.

efi/payload.S still embeds the kernel, the gzip rootfs pack and the trampoline inside BOOTX64.EFI, but the installed P1/P2 image wins when it is valid. That makes the ESP a one-time artifact: later install/net-install/install self updates touch only P1/P2, and UEFI and legacy boots run the same build. Secure Boot must be off; the loader is unsigned.

No GOP, no video. If the loader cannot satisfy the mode constraints it still boots, but the kernel starts headless and only the serial log is available.

kexec path

kexec is the normal development loop: it replaces the running kernel without rebooting, reflashing or re-running the firmware. The framebuffer and its mode stay in place; only the image changes.

Before jumping, kexec.c calls smp_stop_aps(): every AP receives an INIT and is parked in the wait-for-SIPI state before the trampoline overwrites the kernel they were executing. The trampoline runs with interrupts off, resets sched_lock (an AP may have been inside a scheduler critical section), and jumps to kernel_entry.

Because entry.S re-points ESP before any stack use, a reload between builds with different memory maps cannot inherit a stale stack inside the new image.

Handoff contract

bootinfo.h defines the 12-dword block at 0x500. The checksum is chosen so all twelve words sum to zero; that keeps stale low memory from being mistaken for a valid block after a kexec or legacy boot.

OffsetFieldMeaning
+0magic0x4E425349 ("NBSI")
+4versionCurrently 2.
+8checksumMakes the 12-word sum zero.
+12rsdpACPI RSDP physical address; zero means scan.
+16flagsEFI, RGBX pixel order, retained network config.
+20pack_addrBoot-time rootfs pack address, zero if none.
+24pack_sizeExact gzip or raw pack byte count.
+28reserved[5]Reserved; the kexec path stores retained IP/mask/gateway/DNS here.

The framebuffer block at 0x600 is a struct vga_boot_fb_info (vga.h): valid flag, LFB base, pitch, width, height, bpp and the RGBX flag. The E820 map at 0x1000 is a struct e820_map (mm.h): magic, count and up to 32 entries.

Disk image layout

The build produces several images from the same boot sector, kernel and rootfs. The floppy images append the lite pack (rootfs.bin from cmds-lite.pack, everything but firmware/*) so they still fit 1.44 MB. The USB rootfs partition carries the full pack (about 1.3 MB gzip with the WiFi firmware), which now ends past the first 1.44 MB: a BIOS that boots the stick as a CHS-only floppy can no longer read all of it.

NebOS disk image layouts Floppy image: boot sector, kernel, rootfs, padding to 1.44 MB. USB image: MBR and boot partition, rootfs at LBA 1088, 9 MB total. Dual-boot image: the same 9 MB plus an 8 MB EFI system partition at LBA 18432. floppy.img 1.44 MB kernel rootfs.bin (lite) zero padding usb.img 9 MB P1 · boot + kernel partition 2 · rootfs · LBA 1088 · 8 MB usb-efi.img 17 MB partition 1 partition 2 · rootfs partition 3 · FAT16 ESP rootfs container 8 MB cmds.img header gzip command pack Schematic, not to scale. Floppy images carry the lite pack (no firmware); the USB rootfs carries the full pack.
Three images, one source tree. Partition 1 has an empty BPB, so neither UEFI firmware nor VFS mounts the raw kernel blob as a FAT volume and overwrites it.
ImageSizeUse
floppy.img1.44 MBFloppy boot; boot sector + kernel + appended rootfs.
usb.img9 MBLegacy BIOS USB/IDE disk; MBR, boot partition at LBA 63, rootfs at LBA 1088.
usb-efi.img17 MBDual boot; adds an 8 MB FAT16 ESP at LBA 18432 with BOOTX64.EFI.
final.binVariesRaw boot sector + kernel + rootfs, written directly to a device.
root.img1.44 MBFAT12 second floppy with the browser/gallery disk fallbacks and its test page/images.

Installing to a disk

The live system's install <target> [source] command clones P1..P3 (MBR through the end of the ESP) onto a target disk. It finds the source by the MBR plus the LBA-63 boot-sector signature and prefers usb0, the USB mass-storage view of the live stick. It reads the whole source image into RAM first (the unused LBA 1..62 gap is synthesized as zeros), prepares or keeps partition 4, writes the target from RAM, merges the data entry into the source MBR, writes the MBR last, flushes and verifies it. A source-read failure leaves the target untouched.

Partition 4 starts at LBA 34816 and fills the rest of the disk as a writable FAT volume labelled NEBOSDATA, mounted at /data. A first install creates and formats it; a later install or install <target> self keeps it. The data volume is not part of the flashed image, so usb.img and usb-efi.img remain 9 MB and 17 MB. A clone of usb-efi.img keeps the legacy MBR chain and the ESP/UEFI chain; a clone of usb.img is BIOS-only. Runtime cmds-dev pack updates are not part of the clone.

Kernel init order

kernel_main is a single linear bring-up. The order is constrained by what each step needs: GDT/TSS before current_proc(), paging before ACPI table access, process setup before the PIT can context-switch, and a ticking timer before AP bring-up can time out.

  1. Clear BSS; initialise the boot console straight into the framebuffer (8×16 text at the top-left, scrolling when full, with no heap, paging or shadow-buffer dependency).
  2. Bring up COM1 and the network-console ring buffer.
  3. Install the GDT/TSS and per-CPU GS base.
  4. Parse E820, build the frame bitmap and initialise kmalloc.
  5. Enable paging; keep a RAM copy of the boot log; enable SSE state if present.
  6. Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.
  7. Create the process table, then start the PIT and verify it ticks.
  8. Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).
  9. Initialise PS/2 (the I2C touchpad probe only on Airmont) and the VGA shadow buffer.
  10. Inflate the command pack into /ramfs (table-driven whole-buffer inflate); start the WM and the first frame.
  11. Publish vfs_scan_busy and call wm_server_boot_ready(); idle (1 s cap) until the first terminal has presented a frame.
  12. Bring up USB (controllers, HID, USB NICs/WiFi/disks) non-preemptibly, as before the WM existed; probe the NIC, restore retained network config, start the kworker.
  13. Start the bootscan kernel thread (storage probe + FAT mounts, then the /data WiFi autoconnect once the boot DHCP is done); run DHCP if needed.
  14. Enable scheduling on the APs and enter the kernel idle loop.

The terminal no longer waits for USB, the NIC or storage. The WM's network status poll does not trigger the NIC probe (it reports no NIC until kernel_main has probed), so the first frame never waits for a PHY reset. /ramfs and /share operations (including spawning commands from /ramfs/bin) skip the scan wait, a disk path waits for it, and the scan thread sleeps through its long probe timeouts. The end point of a boot measurement is the one-shot COM1 line wm: first window frame (term) at N ms (uptime), written by sys_wm.c when the first application window presents.

The boot trace lines written along the way (boot_trace, boot_val) go to the framebuffer console and COM1, so a machine without serial still shows where a boot stopped. The console uses the same 8×16 face and top-left origin as the loader text and the ring-3 terminal, and scrolls the framebuffer when the screen is full instead of wrapping. The WM disables it when it attaches; bootlog prints the saved text.

Failure modes to know

Source map