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, 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 (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:
- 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. - 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 512 MB identity window. 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/*) 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.
| 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.
- 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(); idle (1 s cap) until the first terminal has presented a frame. - 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 (storage probe + FAT mounts, then the/dataWiFi autoconnect once the boot DHCP is done); 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 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 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 2 MB
PACK_MAX(CMDS_GZ_MAXin the Makefile); UEFI and kexec can carry larger packs up to the 8 MB ramfs cap. The WiFi firmware and the bundled install kernel make the full pack about 1.3 MB, 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.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 orderinstall.c,install.h— clone, self-update and net-install writerrootfs.h— installed image geometrykernel.ld— image limitsMakefile— image sizes and layout rules