| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484 |
- <!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> (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 <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>Enable paging; keep a RAM copy of the boot log; 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 (the I2C touchpad probe only on Airmont) and the VGA shadow buffer.</li>
- <li>Inflate the command pack into <code>/ramfs</code> (table-driven whole-buffer inflate); start the WM and the first frame.</li>
- <li>Publish <code>vfs_scan_busy</code> and call <code>wm_server_boot_ready()</code>; idle (1 s cap) until the first terminal has presented a frame.</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 (storage probe + FAT mounts, then the <code>/data</code> WiFi autoconnect once the boot DHCP is done); 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 application
- window presents.
- </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
- 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 legacy BIOS path caps the compressed pack at 2 MB <code>PACK_MAX</code> (<code>CMDS_GZ_MAX</code> in 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.</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/bootcon.c</code>, <code>common/font_8x16.c</code> — direct-to-LFB boot console</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>
|