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.
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:
- 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(oneINT 13hper 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-moderep movsb. The X201 BIOS'sINT 15h AH=87hblock move silently copies zeros to this range, so the CPU copy is used instead. - Pick the best VBE mode: at least 16 bpp, a linear framebuffer, it must fit the card's VRAM, at most 1920 pixels wide, its pitch × height must fit the 8 MB VGA-shadow reserve, and it must stay within 2 M pixels so a full-screen RGB565 canvas fits the 4 MB window slot. 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 (4 MB, raised
from 1 MB for the WiFi firmware and from 2 MB as the browser grew; the
copy ends at 0xD00000) 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:
- Selects a GOP mode with BGRX or RGBX 32bpp, width at most 1920,
pitch × heightat most 8 MB (1920×1080 fits at 8.29 MB), and a framebuffer below 4 GB. With 32bpp, that size limit also keeps a full-screen RGB565 canvas inside the 4 MB window slot; the VBE stage additionally checks 2 M pixels because a 24bpp 1920×1200 mode would otherwise pass the shadow check. - Calls
GetMemoryMapand converts the firmware map into the kernel's E820 format at0x1000. - Locates the parent whole-disk Block I/O handle from the ESP device path, reads the P1 boot sector and P2
NBROOT1header, and stages the kernel below 4 GB and the gzip pack below the 1 GB identity window, and synthesizes the E820 map for all RAM below 4 GB. The kernel/pack embedded inBOOTX64.EFIare a fallback only. - Writes the boot-info and framebuffer blocks, calls
ExitBootServices, then 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 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.
- 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 floppy images append the lite pack
(rootfs.bin from cmds-lite.pack, everything
but firmware/*, the cursor bundle, the install kernel and
bin/browser.app) so they still fit 1.44 MB; a floppy boot
runs the browser from BROWSER on root.img. 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.
| 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. |
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.
- 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).
- 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 (the I2C touchpad probe only on Airmont) and the VGA shadow buffer.
- Inflate the command pack into
/ramfs(table-driven whole-buffer inflate); start the WM and the first frame. - Publish
vfs_scan_busyand callwm_server_boot_ready(); the WM spawns thebootscanlog window first and the first terminal after it, then idle (1 s cap) until the terminal presents. - 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.
- Start the
bootscankernel thread (non-USB storage probe + FAT mounts, then the deferred USB mounts after the scan window closes, then the/dataWiFi autoconnect once the boot DHCP is done); its COM1 output is captured into theSYS_BOOTLOGring, which thebootscanwindow tails live. The deferred USB pass can wait seconds for a slow card reader without holding up the desktop, the scan window or the other volumes. Run DHCP if needed. - 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 terminal
window presents (the bootscan window is skipped).
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
- 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 compressed pack is capped at 4 MB:
PACK_MAXin vesa_stage.S,CMDS_GZ_MAXin the Makefile and the embedded-pack check in boot/efi/main.c must agree. Hot reloads stage kernel + pack, or a raw runtime pack, in at mostKEXEC_MAX(8 MB, kexec.h), matching the 8 MB ramfs cap. The full pack is about 2.0 MB today, and inflating it adds roughly half a second to the boot. - 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/boot.S— boot sectorboot/mbr.S— USB/HDD MBRboot/vesa_stage.S— real-mode VESA stagekernel/entry.S— canonical kernel entryinclude/bootinfo.h— 0x500 blockkernel/vga.h— 0x600 framebuffer blockboot/efi/main.c— UEFI loaderboot/efi/tramp.S— long-mode exitkernel/kexec.c,kernel/kexec_tramp.S— serial reloadkernel/netkexec.c— network reloadkernel/kernel.c— init orderkernel/bootcon.c,common/font_8x16.c— direct-to-LFB boot console and thebootscanthread's serial ring (SYS_BOOTLOG)kernel/install.c,kernel/install.h— clone, self-update and net-install writerinclude/rootfs.h— installed image geometrykernel/kernel.ld— image limitsMakefile— image sizes and layout rules