| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491 |
- <!doctype html>
- <html lang="en">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Boot | NebOS Architecture</title>
- <meta name="description" content="NebOS boot chain: BIOS boot sector and VESA stage, UEFI loader, kexec reload, boot-info handoff and disk image layout.">
- <link rel="icon" href="favicon.svg" type="image/svg+xml">
- <link rel="stylesheet" href="style.css">
- </head>
- <body>
- <a class="skip" href="#main">Skip to content</a>
- <header class="site-header">
- <a class="brand" href="index.html">
- <span class="brand-mark" aria-hidden="true"></span>
- <span>NebOS <span class="brand-sub">Architecture</span></span>
- </a>
- <nav class="site-nav" aria-label="Architecture sections">
- <a href="index.html">Overview</a>
- <a href="boot.html" aria-current="page">Boot</a>
- <a href="memory.html">Memory</a>
- <a href="cpu.html">CPU</a>
- <a href="drivers.html">Drivers</a>
- <a href="filesystems.html">Filesystems</a>
- <a href="graphics.html">Graphics</a>
- <a href="network.html">Network</a>
- <a href="userland.html">Userland</a>
- <a href="development.html">Development</a>
- </nav>
- </header>
- <main id="main" class="page">
- <div class="page-head">
- <p class="kicker">Boot & firmware</p>
- <h1>Three ways into the same kernel.</h1>
- <p class="lede">
- A legacy BIOS floppy, a dual-boot USB image under UEFI, and a live
- serial or network reload all converge on <code>kernel_entry</code>.
- They must agree on three things: the low-memory boot structures, the
- rootfs pack location, and a 32-bit flat protected-mode environment.
- </p>
- <div class="meta">
- <span class="pill">512-byte boot sector</span>
- <span class="pill">real-mode VESA stage</span>
- <span class="pill">x86-64 UEFI loader</span>
- <span class="pill">kexec hot reload</span>
- </div>
- </div>
- <nav class="toc" aria-label="On this page">
- <h2>On this page</h2>
- <ul>
- <li><a href="#overview">Boot paths</a></li>
- <li><a href="#bios">BIOS path</a></li>
- <li><a href="#uefi">UEFI path</a></li>
- <li><a href="#kexec">kexec path</a></li>
- <li><a href="#handoff">Handoff contract</a></li>
- <li><a href="#images">Image layout</a></li>
- <li><a href="#init">Kernel init order</a></li>
- <li><a href="#failures">Failure modes</a></li>
- <li><a href="#sources">Source map</a></li>
- </ul>
- </nav>
- <section id="overview">
- <h2>Three paths, one entry point</h2>
- <p>
- 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 <code>kernel_entry</code> in <span class="file">entry.S</span>,
- which immediately re-points <code>ESP</code> at the new image's own
- boot stack before calling <code>kernel_main</code>.
- </p>
- <figure class="figure">
- <svg viewBox="0 0 920 390" role="img" aria-labelledby="paths-title paths-desc">
- <title id="paths-title">Three NebOS boot paths</title>
- <desc id="paths-desc">BIOS boot sector to VESA stage to kernel entry; UEFI BOOTX64.EFI to trampoline to kernel entry; kexec receiver to trampoline to kernel entry.</desc>
- <rect class="svg-box blue" x="16" y="18" width="250" height="76" rx="8"/>
- <text class="svg-text" x="36" y="46">BIOS · floppy / USB</text>
- <text class="svg-sub" x="36" y="66">boot.S at 0x7C00 → vesa_stage.S</text>
- <text class="svg-sub" x="36" y="82">real mode → protected mode</text>
- <rect class="svg-box green" x="16" y="152" width="250" height="76" rx="8"/>
- <text class="svg-text" x="36" y="180">UEFI · usb-efi.img</text>
- <text class="svg-sub" x="36" y="200">BOOTX64.EFI · x86-64</text>
- <text class="svg-sub" x="36" y="216">GOP + GetMemoryMap</text>
- <rect class="svg-box amber" x="16" y="286" width="250" height="76" rx="8"/>
- <text class="svg-text" x="36" y="314">kexec · make dev / net-dev</text>
- <text class="svg-sub" x="36" y="334">KXE2 serial · KXN2 UDP</text>
- <text class="svg-sub" x="36" y="350">running kernel receives image</text>
- <path class="svg-line blue" d="M266 56h94"/>
- <path class="svg-line blue" d="M354 50l7 6-7 6"/>
- <path class="svg-line green" d="M266 190h94"/>
- <path class="svg-line green" d="M354 184l7 6-7 6"/>
- <path class="svg-line amber" d="M266 324h94"/>
- <path class="svg-line amber" d="M354 318l7 6-7 6"/>
- <rect class="svg-box" x="360" y="18" width="228" height="76" rx="8"/>
- <text class="svg-text" x="380" y="46">VESA stage</text>
- <text class="svg-sub" x="380" y="66">E820 · VBE mode · rootfs</text>
- <text class="svg-sub" x="380" y="82">0x500 / 0x600 / 0x1000</text>
- <rect class="svg-box" x="360" y="152" width="228" height="76" rx="8"/>
- <text class="svg-text" x="380" y="180">UEFI trampoline</text>
- <text class="svg-sub" x="380" y="200">0x800 · leave IA-32e</text>
- <text class="svg-sub" x="380" y="216">kernel copy to 0x7E00</text>
- <rect class="svg-box" x="360" y="286" width="228" height="76" rx="8"/>
- <text class="svg-text" x="380" y="314">kexec trampoline</text>
- <text class="svg-sub" x="380" y="334">APs parked · copy kernel</text>
- <text class="svg-sub" x="380" y="350">keep framebuffer</text>
- <path class="svg-line accent" d="M588 56h110v139"/>
- <path class="svg-line accent" d="M588 190h110v5"/>
- <path class="svg-line accent" d="M588 324h110v-129"/>
- <path class="svg-line accent" d="M692 188l6 7 6-7"/>
- <rect class="svg-box accent" x="620" y="136" width="280" height="108" rx="9"/>
- <text class="svg-text" x="642" y="166">kernel_entry · entry.S</text>
- <text class="svg-sub" x="642" y="188">ESP = __boot_stack_top</text>
- <text class="svg-sub" x="642" y="208">jmp kernel_main</text>
- <text class="svg-sub" x="642" y="228">32-bit flat · paging off</text>
- </svg>
- <figcaption>
- <strong>Every path hands off in the same shape:</strong> flat
- 32-bit segments, paging off, the framebuffer block at
- <code>0x600</code>, the boot-info block at <code>0x500</code>, and
- the kernel loaded at <code>0x7E00</code>.
- </figcaption>
- </figure>
- </section>
- <section id="bios">
- <h2>BIOS path</h2>
- <h3><span class="file">boot.S</span> — the 512-byte boot sector</h3>
- <p>
- The boot sector carries a FAT16 BPB, loads the contiguous kernel
- directly after itself to <code>0x7E00</code>, and jumps there.
- Each <code>INT 13h</code> reads a run of sectors into
- <code>ES:0</code> and then advances <code>ES</code>, so the offset
- never wraps: fixed disks use EDD LBA (<code>AH=42h</code>) 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 <code>Disk read error</code>. The sector count and the rootfs LBA are patched into the
- boot sector by the Makefile.
- </p>
- <p>
- On the USB image, <span class="file">mbr.S</span> runs first and
- loads the active partition's boot sector at LBA 63. From there the
- path is identical.
- </p>
- <h3><span class="file">vesa_stage.S</span> — the real-mode setup</h3>
- <p>
- The VESA stage is the busiest piece of the legacy chain. It runs in
- real mode at <code>0x7E00</code> and performs five jobs:
- </p>
- <ol>
- <li>Probe the <code>INT 15h</code> E820 memory map into <code>0x1000</code>.</li>
- <li>Enable A20 and read the <code>NBROOT1</code> rootfs header at the boot sector's <code>pack_lba</code> field.</li>
- <li>Copy the compressed pack directly to <code>0x900000</code> above the 8 MB VGA-shadow reserve, in 16 KB staging chunks at <code>0x3000</code> (one <code>INT 13h</code> 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 <code>rep movsb</code>. The X201 BIOS's <code>INT 15h AH=87h</code> block move silently copies zeros to this range, so the CPU copy is used instead.</li>
- <li>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 <code>0x600</code>; the 12-dword boot-info block goes to <code>0x500</code>.</li>
- <li>Enter protected mode and jump to <code>kernel_entry</code>.</li>
- </ol>
- <p>
- The pack no longer occupies the old <code>0x60000..0x9FBFF</code>
- low gap, so the legacy cap is <code>PACK_MAX</code> (4 MB, raised
- from 1 MB for the WiFi firmware and from 2 MB as the browser grew; the
- copy ends at <code>0xD00000</code>) and the
- kernel BSS/boot stack may use the gap. The kernel image only has to
- stay below <code>0x90000</code> so the top of low memory and the
- EBDA remain untouched; <span class="file">kernel.ld</span> enforces
- that with a link-time assertion.
- </p>
- <div class="note">
- <p><strong>BIOS state after the move.</strong> The X201's BIOS
- historically left translation bits behind after
- <code>AH=87h</code>; <span class="file">paging.c</span> 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
- <span class="file">ramfs.c</span> takes a private page-allocated
- copy and releases the boot region.</p>
- </div>
- </section>
- <section id="uefi">
- <h2>UEFI path</h2>
- <p>
- <span class="file">efi/main.c</span> is a freestanding x86-64 PE32+
- application built with <code>x86_64-w64-mingw32-gcc</code>. It does
- not execute any of the legacy boot chain. Instead it:
- </p>
- <ol>
- <li>Selects a GOP mode with BGRX or RGBX 32bpp, width at most 1920, <code>pitch × height</code> at 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.</li>
- <li>Calls <code>GetMemoryMap</code> and converts the firmware map into the kernel's E820 format at <code>0x1000</code>.</li>
- <li>Locates the parent whole-disk Block I/O handle from the ESP device path, reads the P1 boot sector and P2 <code>NBROOT1</code> header, 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 in <code>BOOTX64.EFI</code> are a fallback only.</li>
- <li>Writes the boot-info and framebuffer blocks, calls <code>ExitBootServices</code>, then copies a 192-byte trampoline to <code>0x800</code>.</li>
- <li>Leaves IA-32e mode (clears <code>CR0.PG</code>, <code>EFER.LME</code>, <code>CR4.PAE/PGE/PCIDE/SMEP/SMAP/LA57</code>), copies the kernel to <code>0x7E00</code>, and jumps to <code>kernel_entry</code>.</li>
- </ol>
- <p>
- <span class="file">efi/payload.S</span> still embeds the kernel,
- the gzip rootfs pack and the trampoline inside
- <code>BOOTX64.EFI</code>, but the installed P1/P2 image wins when it
- is valid. That makes the ESP a one-time artifact: later
- <code>install</code>/<code>net-install</code>/<code>install self</code>
- updates touch only P1/P2, and UEFI and legacy boots run the same
- build. Secure Boot must be off; the loader is unsigned.
- </p>
- <div class="warn">
- <p><strong>No GOP, no video.</strong> If the loader cannot satisfy the
- mode constraints it still boots, but the kernel starts headless and
- only the serial log is available.</p>
- </div>
- </section>
- <section id="kexec">
- <h2>kexec path</h2>
- <p>
- 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.
- </p>
- <ul>
- <li><strong>Serial.</strong> The WM loop watches the COM1 ring buffer for the <code>KXE2</code> magic. The header carries entry, kernel size, pack size and a checksum; <code>pack_size == 0</code> keeps the running rootfs.</li>
- <li><strong>Network.</strong> The same transfer runs over UDP port 19288 with the <code>KXN2</code> magic. The board acknowledges every datagram with the next expected offset and verifies a 32-bit checksum.</li>
- <li><strong>Runtime pack only.</strong> <code>KXNP</code> over serial or network replaces <code>/ramfs</code> in place without touching the kernel.</li>
- </ul>
- <p>
- Before jumping, <span class="file">kexec.c</span> calls
- <code>smp_stop_aps()</code>: 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
- <code>sched_lock</code> (an AP may have been inside a scheduler
- critical section), and jumps to <code>kernel_entry</code>.
- </p>
- <p>
- Because <span class="file">entry.S</span> re-points <code>ESP</code>
- before any stack use, a reload between builds with different memory
- maps cannot inherit a stale stack inside the new image.
- </p>
- </section>
- <section id="handoff">
- <h2>Handoff contract</h2>
- <p>
- <span class="file">bootinfo.h</span> defines the 12-dword block at
- <code>0x500</code>. 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.
- </p>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Offset</th><th>Field</th><th>Meaning</th></tr>
- </thead>
- <tbody>
- <tr><td><code>+0</code></td><td><code>magic</code></td><td><code>0x4E425349</code> (<code>"NBSI"</code>)</td></tr>
- <tr><td><code>+4</code></td><td><code>version</code></td><td>Currently 2.</td></tr>
- <tr><td><code>+8</code></td><td><code>checksum</code></td><td>Makes the 12-word sum zero.</td></tr>
- <tr><td><code>+12</code></td><td><code>rsdp</code></td><td>ACPI RSDP physical address; zero means scan.</td></tr>
- <tr><td><code>+16</code></td><td><code>flags</code></td><td>EFI, RGBX pixel order, retained network config.</td></tr>
- <tr><td><code>+20</code></td><td><code>pack_addr</code></td><td>Boot-time rootfs pack address, zero if none.</td></tr>
- <tr><td><code>+24</code></td><td><code>pack_size</code></td><td>Exact gzip or raw pack byte count.</td></tr>
- <tr><td><code>+28</code></td><td><code>reserved[5]</code></td><td>Reserved; the kexec path stores retained IP/mask/gateway/DNS here.</td></tr>
- </tbody>
- </table>
- </div>
- <p>
- The framebuffer block at <code>0x600</code> is a
- <code>struct vga_boot_fb_info</code> (<span class="file">vga.h</span>):
- valid flag, LFB base, pitch, width, height, bpp and the RGBX flag.
- The E820 map at <code>0x1000</code> is a
- <code>struct e820_map</code> (<span class="file">mm.h</span>): magic,
- count and up to 32 entries.
- </p>
- </section>
- <section id="images">
- <h2>Disk image layout</h2>
- <p>
- The build produces several images from the same boot sector, kernel
- and rootfs. The floppy images append the <em>lite</em> pack
- (<code>rootfs.bin</code> from <code>cmds-lite.pack</code>, everything
- but <code>firmware/*</code>, the cursor bundle, the install kernel and
- <code>bin/browser.app</code>) so they still fit 1.44 MB; a floppy boot
- runs the browser from <code>BROWSER</code> on <code>root.img</code>. 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.
- </p>
- <figure class="figure">
- <svg viewBox="0 0 920 342" role="img" aria-labelledby="images-title images-desc">
- <title id="images-title">NebOS disk image layouts</title>
- <desc id="images-desc">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.</desc>
- <text class="svg-text" x="12" y="30">floppy.img</text>
- <text class="svg-tiny" x="908" y="30" text-anchor="end">1.44 MB</text>
- <rect class="svg-box accent" x="160" y="42" width="14" height="24" rx="3"/>
- <rect class="svg-box blue" x="178" y="42" width="250" height="24" rx="3"/>
- <rect class="svg-box green" x="432" y="42" width="210" height="24" rx="3"/>
- <rect class="svg-box" x="646" y="42" width="244" height="24" rx="3"/>
- <text class="svg-tiny" x="186" y="59">kernel</text>
- <text class="svg-tiny" x="440" y="59">rootfs.bin (lite)</text>
- <text class="svg-tiny" x="654" y="59">zero padding</text>
- <text class="svg-text" x="12" y="106">usb.img</text>
- <text class="svg-tiny" x="908" y="106" text-anchor="end">9 MB</text>
- <rect class="svg-box amber" x="160" y="118" width="184" height="24" rx="3"/>
- <rect class="svg-box green" x="416" y="118" width="474" height="24" rx="3"/>
- <text class="svg-tiny" x="176" y="135">P1 · boot + kernel</text>
- <text class="svg-tiny" x="424" y="135">partition 2 · rootfs · LBA 1088 · 8 MB</text>
- <text class="svg-text" x="12" y="182">usb-efi.img</text>
- <text class="svg-tiny" x="908" y="182" text-anchor="end">17 MB</text>
- <rect class="svg-box amber" x="160" y="194" width="184" height="24" rx="3"/>
- <rect class="svg-box green" x="416" y="194" width="250" height="24" rx="3"/>
- <rect class="svg-box accent" x="670" y="194" width="220" height="24" rx="3"/>
- <text class="svg-tiny" x="176" y="211">partition 1</text>
- <text class="svg-tiny" x="424" y="211">partition 2 · rootfs</text>
- <text class="svg-tiny" x="678" y="211">partition 3 · FAT16 ESP</text>
- <text class="svg-text" x="12" y="258">rootfs container</text>
- <text class="svg-tiny" x="908" y="258" text-anchor="end">8 MB cmds.img</text>
- <rect class="svg-box amber" x="160" y="270" width="56" height="26" rx="3"/>
- <rect class="svg-box green" x="220" y="270" width="670" height="26" rx="3"/>
- <text class="svg-tiny" x="172" y="288">header</text>
- <text class="svg-tiny" x="232" y="288">gzip command pack</text>
- <line class="svg-line" x1="160" y1="314" x2="890" y2="314"/>
- <text class="svg-tiny" x="160" y="334">Schematic, not to scale. Floppy images carry the lite pack (no firmware); the USB rootfs carries the full pack.</text>
- </svg>
- <figcaption>
- <strong>Three images, one source tree.</strong> Partition 1 has
- an empty BPB, so neither UEFI firmware nor VFS mounts the raw
- kernel blob as a FAT volume and overwrites it.
- </figcaption>
- </figure>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Image</th><th>Size</th><th>Use</th></tr>
- </thead>
- <tbody>
- <tr><td><code>floppy.img</code></td><td>1.44 MB</td><td>Floppy boot; boot sector + kernel + appended rootfs.</td></tr>
- <tr><td><code>usb.img</code></td><td>9 MB</td><td>Legacy BIOS USB/IDE disk; MBR, boot partition at LBA 63, rootfs at LBA 1088.</td></tr>
- <tr><td><code>usb-efi.img</code></td><td>17 MB</td><td>Dual boot; adds an 8 MB FAT16 ESP at LBA 18432 with <code>BOOTX64.EFI</code>.</td></tr>
- <tr><td><code>final.bin</code></td><td>Varies</td><td>Raw boot sector + kernel + rootfs, written directly to a device.</td></tr>
- <tr><td><code>root.img</code></td><td>1.44 MB</td><td>FAT12 second floppy with the browser/gallery disk fallbacks and its test page/images.</td></tr>
- </tbody>
- </table>
- </div>
- <h3>Installing to a disk</h3>
- <p>
- The live system's <code>install <target> [source]</code>
- 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 <code>usb0</code>, 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.
- </p>
- <p>
- Partition 4 starts at LBA 34816 and fills the rest of the disk as a
- writable FAT volume labelled <code>NEBOSDATA</code>, mounted at
- <code>/data</code>. A first install creates and formats it; a later
- install or <code>install <target> self</code> keeps it. The
- data volume is not part of the flashed image, so <code>usb.img</code>
- and <code>usb-efi.img</code> remain 9 MB and 17 MB. A clone of
- <code>usb-efi.img</code> keeps the legacy MBR chain and the ESP/UEFI
- chain; a clone of <code>usb.img</code> is BIOS-only. Runtime
- <code>cmds-dev</code> pack updates are not part of the clone.
- </p>
- </section>
- <section id="init">
- <h2>Kernel init order</h2>
- <p>
- <code>kernel_main</code> is a single linear bring-up. The order is
- constrained by what each step needs: GDT/TSS before <code>current_proc()</code>,
- paging before ACPI table access, process setup before the PIT can
- context-switch, and a ticking timer before AP bring-up can time out.
- </p>
- <ol>
- <li>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).</li>
- <li>Bring up COM1 and the network-console ring buffer.</li>
- <li>Install the GDT/TSS and per-CPU GS base.</li>
- <li>Parse E820, build the frame bitmap and initialise <code>kmalloc</code>.</li>
- <li>Keep RAM copies of the boot console text and the COM1 capture as soon as the frame allocator is up (the first serial bytes were held in a small BSS buffer until then); enable paging; enable SSE state if present.</li>
- <li>Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.</li>
- <li>Create the process table, then start the PIT and verify it ticks.</li>
- <li>Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).</li>
- <li>Initialise PS/2 and the I2C touchpad (the Elan on Airmont, the Synaptics on Sunrise Point-LP), then the VGA shadow buffer.</li>
- <li>Inflate the command pack into <code>/ramfs</code> (table-driven whole-buffer inflate), initialize the kernel window server and start <code>/ramfs/bin/init</code> as PID 1. Init spawns <code>/ramfs/bin/wm</code>; the kernel never starts a WM and the boot console stays if init is absent.</li>
- <li>Publish <code>vfs_scan_busy</code> and call <code>wm_server_boot_ready()</code>; the WM spawns the <code>bootscan</code> log window first and the first terminal after it, then idle (1 s cap) until the terminal presents.</li>
- <li>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.</li>
- <li>Start the <code>bootscan</code> kernel thread (non-USB storage probe + FAT mounts, then the deferred USB mounts after the scan window closes, then the <code>/data</code> WiFi autoconnect once the boot DHCP is done); its COM1 output is captured into the <code>Scan</code> source of <code>SYS_BOOTLOG</code>. The <code>bootscan</code> window also tabs the boot console text and the complete COM1 capture (which starts at the first kernel line and keeps tailing after the scan). 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.</li>
- <li>Enable scheduling on the APs and enter the kernel idle loop.</li>
- </ol>
- <p>
- 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 <code>kernel_main</code> has probed), so the first frame
- never waits for a PHY reset. <code>/ramfs</code> and
- <code>/share</code> operations (including spawning commands from
- <code>/ramfs/bin</code>) 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
- <code>wm: first window frame (term) at N ms</code> (uptime), written
- by <span class="file">sys_wm.c</span> when the first terminal
- window presents (the bootscan window is skipped).
- </p>
- <p>
- The boot trace lines written along the way (<code>boot_trace</code>,
- <code>boot_val</code>) go to the framebuffer console and COM1, so a
- machine without serial still shows where a boot stopped. The boot
- console also prints <code>com1: absent</code> when
- <code>serial_init()</code> finds no UART, brackets the timer bring-up
- with <code>timer: pic|idt|lapic|pit|sti</code> and the first
- <code>tick</code>, and labels each AP as <code>smp: ap N</code>. 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; <code>bootlog</code>
- prints the saved text.
- </p>
- </section>
- <section id="failures">
- <h2>Failure modes to know</h2>
- <ul>
- <li><strong>No VBE mode.</strong> The legacy stage cannot produce a framebuffer; the kernel may start headless or the boot stops in the stage.</li>
- <li><strong>Pack larger than the cap.</strong> The compressed pack is capped at 4 MB: <code>PACK_MAX</code> in <span class="file">vesa_stage.S</span>, <code>CMDS_GZ_MAX</code> in the Makefile and the embedded-pack check in <span class="file">boot/efi/main.c</span> must agree. Hot reloads stage kernel + pack, or a raw runtime pack, in at most <code>KEXEC_MAX</code> (8 MB, <span class="file">kexec.h</span>), matching the 8 MB ramfs cap. The full pack is about 3.2 MB today (7265D + 8265 firmware), inflating to about 7.3 MB and adding roughly a second to the boot.</li>
- <li><strong>PIT not ticking.</strong> <code>kernel_main</code> prints <code>*** PIT NOT TICKING ***</code> and halts; no process scheduling is possible.</li>
- <li><strong>UEFI Secure Boot.</strong> The unsigned <code>BOOTX64.EFI</code> is rejected before any NebOS code runs.</li>
- <li><strong>Stale boot info.</strong> The checksum makes an invalid <code>0x500</code> block read as absent rather than as a bogus pack or RSDP.</li>
- </ul>
- </section>
- <section id="sources">
- <h2>Source map</h2>
- <ul class="filelist">
- <li><code>boot/boot.S</code> — boot sector</li>
- <li><code>boot/mbr.S</code> — USB/HDD MBR</li>
- <li><code>boot/vesa_stage.S</code> — real-mode VESA stage</li>
- <li><code>kernel/entry.S</code> — canonical kernel entry</li>
- <li><code>include/bootinfo.h</code> — 0x500 block</li>
- <li><code>kernel/vga.h</code> — 0x600 framebuffer block</li>
- <li><code>boot/efi/main.c</code> — UEFI loader</li>
- <li><code>boot/efi/tramp.S</code> — long-mode exit</li>
- <li><code>kernel/kexec.c</code>, <code>kernel/kexec_tramp.S</code> — serial reload</li>
- <li><code>kernel/netkexec.c</code> — network reload</li>
- <li><code>kernel/kernel.c</code> — init order</li>
- <li><code>kernel/init.c</code>, <code>kernel/init.h</code> — PID-1 init bootstrap and restart</li>
- <li><code>kernel/bootcon.c</code>, <code>common/font_8x16.c</code> — direct-to-LFB boot console, its text log, the always-on COM1 capture and the <code>bootscan</code> thread's serial ring (the three <code>SYS_BOOTLOG</code> sources)</li>
- <li><code>kernel/install.c</code>, <code>kernel/install.h</code> — clone, self-update and net-install writer</li>
- <li><code>include/rootfs.h</code> — installed image geometry</li>
- <li><code>kernel/kernel.ld</code> — image limits</li>
- <li><code>Makefile</code> — image sizes and layout rules</li>
- </ul>
- </section>
- </main>
- <footer class="site-footer">
- <div class="inner">
- <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
- <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
- </div>
- </footer>
- </body>
- </html>
|