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. Floppy drives use CHS; fixed disks use INT 13h AH=42h (EDD LBA). 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, using the BIOS block move INT 15h AH=87h.
  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 (512 KB) 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 leaves translation bits behind after AH=87h; paging.c clears CR4.PAE/PGE/LA57/PCIDE/ SMEP/SMAP and EFER.LME before it enables paging. The block move 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. Stages the kernel image below 4 GB and writes the boot-info and framebuffer blocks.
  4. Calls ExitBootServices, copies the embedded rootfs pack to the top of RAM below 128 MB, and 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 embeds the compressed kernel, the gzip rootfs pack and the trampoline inside BOOTX64.EFI, so the ESP is self-contained. 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 layouts are intentionally conservative: the first 1.44 MB must remain readable by a CHS-only BIOS.

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 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. The first 1.44 MB keeps the pack reachable by CHS-only USB BIOSes.
Three images, one source tree. The dual-boot image clears one BPB byte in the fake FAT16 header of partition 1 so UEFI firmware does not mount the raw kernel blob as a volume and overwrite 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.

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.
  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, USB HID and the VGA shadow buffer.
  10. Inflate the command pack into /ramfs; start the WM and the first frame.
  11. Probe the NIC, restore retained network config, start the kworker.
  12. Mount FAT devices; call wm_server_boot_ready() so the WM spawns the first terminal; run DHCP if needed.
  13. Enable scheduling on the APs and enter the kernel idle loop.

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 WM disables the boot console when it attaches; bootlog prints the saved text.

Failure modes to know

Source map