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.
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.
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:
- Probe the
INT 15hE820 memory map into0x1000. - Enable A20 and read the
NBROOT1rootfs header at the boot sector'spack_lbafield. - Copy the compressed pack directly to
0x900000above the 8 MB VGA-shadow reserve, in 16 KB staging chunks at0x3000, using the BIOS block moveINT 15h AH=87h. - 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 to0x500. - 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 (1 MB) 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:
- Selects a GOP mode with BGRX or RGBX 32bpp, width at most 1280,
pitch × heightat most 8 MB, and a framebuffer below 4 GB. - Calls
GetMemoryMapand converts the firmware map into the kernel's E820 format at0x1000. - Stages the kernel image below 4 GB and writes the boot-info and framebuffer blocks.
- Calls
ExitBootServices, copies the embedded rootfs pack to the top of RAM below 512 MB, and copies a 192-byte trampoline to0x800. - Leaves IA-32e mode (clears
CR0.PG,EFER.LME,CR4.PAE/PGE/PCIDE/SMEP/SMAP/LA57), copies the kernel to0x7E00, and jumps tokernel_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.
- Serial. The WM loop watches the COM1 ring buffer for the
KXE2magic. The header carries entry, kernel size, pack size and a checksum;pack_size == 0keeps the running rootfs. - Network. The same transfer runs over UDP port 19288 with the
KXN2magic. The board acknowledges every datagram with the next expected offset and verifies a 32-bit checksum. - Runtime pack only.
KXNPover serial or network replaces/ramfsin place without touching the kernel.
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.
| Offset | Field | Meaning |
|---|---|---|
+0 | magic | 0x4E425349 ("NBSI") |
+4 | version | Currently 2. |
+8 | checksum | Makes the 12-word sum zero. |
+12 | rsdp | ACPI RSDP physical address; zero means scan. |
+16 | flags | EFI, RGBX pixel order, retained network config. |
+20 | pack_addr | Boot-time rootfs pack address, zero if none. |
+24 | pack_size | Exact gzip or raw pack byte count. |
+28 | reserved[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.
| Image | Size | Use |
|---|---|---|
floppy.img | 1.44 MB | Floppy boot; boot sector + kernel + appended rootfs. |
usb.img | 9 MB | Legacy BIOS USB/IDE disk; MBR, boot partition at LBA 63, rootfs at LBA 1088. |
usb-efi.img | 17 MB | Dual boot; adds an 8 MB FAT16 ESP at LBA 18432 with BOOTX64.EFI. |
final.bin | Varies | Raw boot sector + kernel + rootfs, written directly to a device. |
root.img | 1.44 MB | FAT12 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.
- Clear BSS; initialise the boot console straight into the framebuffer.
- Bring up COM1 and the network-console ring buffer.
- Install the GDT/TSS and per-CPU GS base.
- Parse E820, build the frame bitmap and initialise
kmalloc. - Enable paging; keep a RAM copy of the boot log; enable SSE state if present.
- Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.
- Create the process table, then start the PIT and verify it ticks.
- Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).
- Initialise PS/2, USB HID and the VGA shadow buffer.
- Inflate the command pack into
/ramfs; start the WM and the first frame. - Probe the NIC, restore retained network config, start the kworker.
- Mount FAT devices; call
wm_server_boot_ready()so the WM spawns the first terminal; run DHCP if needed. - 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
- No VBE mode. The legacy stage cannot produce a framebuffer; the kernel may start headless or the boot stops in the stage.
- Pack larger than the cap. The legacy BIOS path caps the compressed pack at 1 MB
PACK_MAX; UEFI and kexec can carry larger packs up to the 8 MB ramfs cap. - PIT not ticking.
kernel_mainprints*** PIT NOT TICKING ***and halts; no process scheduling is possible. - UEFI Secure Boot. The unsigned
BOOTX64.EFIis rejected before any NebOS code runs. - Stale boot info. The checksum makes an invalid
0x500block read as absent rather than as a bogus pack or RSDP.
Source map
boot.S— boot sectormbr.S— USB/HDD MBRvesa_stage.S— real-mode VESA stageentry.S— canonical kernel entrybootinfo.h— 0x500 blockvga.h— 0x600 framebuffer blockefi/main.c— UEFI loaderefi/tramp.S— long-mode exitkexec.c,kexec_tramp.S— serial reloadnetkexec.c— network reloadkernel.c— init orderkernel.ld— image limitsMakefile— image sizes and layout rules