boot.html 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486
  1. <!doctype html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Boot | NebOS Architecture</title>
  7. <meta name="description" content="NebOS boot chain: BIOS boot sector and VESA stage, UEFI loader, kexec reload, boot-info handoff and disk image layout.">
  8. <link rel="icon" href="favicon.svg" type="image/svg+xml">
  9. <link rel="stylesheet" href="style.css">
  10. </head>
  11. <body>
  12. <a class="skip" href="#main">Skip to content</a>
  13. <header class="site-header">
  14. <a class="brand" href="index.html">
  15. <span class="brand-mark" aria-hidden="true"></span>
  16. <span>NebOS <span class="brand-sub">Architecture</span></span>
  17. </a>
  18. <nav class="site-nav" aria-label="Architecture sections">
  19. <a href="index.html">Overview</a>
  20. <a href="boot.html" aria-current="page">Boot</a>
  21. <a href="memory.html">Memory</a>
  22. <a href="cpu.html">CPU</a>
  23. <a href="drivers.html">Drivers</a>
  24. <a href="filesystems.html">Filesystems</a>
  25. <a href="graphics.html">Graphics</a>
  26. <a href="network.html">Network</a>
  27. <a href="userland.html">Userland</a>
  28. <a href="development.html">Development</a>
  29. </nav>
  30. </header>
  31. <main id="main" class="page">
  32. <div class="page-head">
  33. <p class="kicker">Boot &amp; firmware</p>
  34. <h1>Three ways into the same kernel.</h1>
  35. <p class="lede">
  36. A legacy BIOS floppy, a dual-boot USB image under UEFI, and a live
  37. serial or network reload all converge on <code>kernel_entry</code>.
  38. They must agree on three things: the low-memory boot structures, the
  39. rootfs pack location, and a 32-bit flat protected-mode environment.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">512-byte boot sector</span>
  43. <span class="pill">real-mode VESA stage</span>
  44. <span class="pill">x86-64 UEFI loader</span>
  45. <span class="pill">kexec hot reload</span>
  46. </div>
  47. </div>
  48. <nav class="toc" aria-label="On this page">
  49. <h2>On this page</h2>
  50. <ul>
  51. <li><a href="#overview">Boot paths</a></li>
  52. <li><a href="#bios">BIOS path</a></li>
  53. <li><a href="#uefi">UEFI path</a></li>
  54. <li><a href="#kexec">kexec path</a></li>
  55. <li><a href="#handoff">Handoff contract</a></li>
  56. <li><a href="#images">Image layout</a></li>
  57. <li><a href="#init">Kernel init order</a></li>
  58. <li><a href="#failures">Failure modes</a></li>
  59. <li><a href="#sources">Source map</a></li>
  60. </ul>
  61. </nav>
  62. <section id="overview">
  63. <h2>Three paths, one entry point</h2>
  64. <p>
  65. The boot code is deliberately split by execution mode. The BIOS path
  66. starts in 16-bit real mode, the UEFI path starts in 64-bit long mode,
  67. and the kexec path starts in the running 32-bit kernel. All three end
  68. at <code>kernel_entry</code> in <span class="file">entry.S</span>,
  69. which immediately re-points <code>ESP</code> at the new image's own
  70. boot stack before calling <code>kernel_main</code>.
  71. </p>
  72. <figure class="figure">
  73. <svg viewBox="0 0 920 390" role="img" aria-labelledby="paths-title paths-desc">
  74. <title id="paths-title">Three NebOS boot paths</title>
  75. <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>
  76. <rect class="svg-box blue" x="16" y="18" width="250" height="76" rx="8"/>
  77. <text class="svg-text" x="36" y="46">BIOS · floppy / USB</text>
  78. <text class="svg-sub" x="36" y="66">boot.S at 0x7C00 → vesa_stage.S</text>
  79. <text class="svg-sub" x="36" y="82">real mode → protected mode</text>
  80. <rect class="svg-box green" x="16" y="152" width="250" height="76" rx="8"/>
  81. <text class="svg-text" x="36" y="180">UEFI · usb-efi.img</text>
  82. <text class="svg-sub" x="36" y="200">BOOTX64.EFI · x86-64</text>
  83. <text class="svg-sub" x="36" y="216">GOP + GetMemoryMap</text>
  84. <rect class="svg-box amber" x="16" y="286" width="250" height="76" rx="8"/>
  85. <text class="svg-text" x="36" y="314">kexec · make dev / net-dev</text>
  86. <text class="svg-sub" x="36" y="334">KXE2 serial · KXN2 UDP</text>
  87. <text class="svg-sub" x="36" y="350">running kernel receives image</text>
  88. <path class="svg-line blue" d="M266 56h94"/>
  89. <path class="svg-line blue" d="M354 50l7 6-7 6"/>
  90. <path class="svg-line green" d="M266 190h94"/>
  91. <path class="svg-line green" d="M354 184l7 6-7 6"/>
  92. <path class="svg-line amber" d="M266 324h94"/>
  93. <path class="svg-line amber" d="M354 318l7 6-7 6"/>
  94. <rect class="svg-box" x="360" y="18" width="228" height="76" rx="8"/>
  95. <text class="svg-text" x="380" y="46">VESA stage</text>
  96. <text class="svg-sub" x="380" y="66">E820 · VBE mode · rootfs</text>
  97. <text class="svg-sub" x="380" y="82">0x500 / 0x600 / 0x1000</text>
  98. <rect class="svg-box" x="360" y="152" width="228" height="76" rx="8"/>
  99. <text class="svg-text" x="380" y="180">UEFI trampoline</text>
  100. <text class="svg-sub" x="380" y="200">0x800 · leave IA-32e</text>
  101. <text class="svg-sub" x="380" y="216">kernel copy to 0x7E00</text>
  102. <rect class="svg-box" x="360" y="286" width="228" height="76" rx="8"/>
  103. <text class="svg-text" x="380" y="314">kexec trampoline</text>
  104. <text class="svg-sub" x="380" y="334">APs parked · copy kernel</text>
  105. <text class="svg-sub" x="380" y="350">keep framebuffer</text>
  106. <path class="svg-line accent" d="M588 56h110v139"/>
  107. <path class="svg-line accent" d="M588 190h110v5"/>
  108. <path class="svg-line accent" d="M588 324h110v-129"/>
  109. <path class="svg-line accent" d="M692 188l6 7 6-7"/>
  110. <rect class="svg-box accent" x="620" y="136" width="280" height="108" rx="9"/>
  111. <text class="svg-text" x="642" y="166">kernel_entry · entry.S</text>
  112. <text class="svg-sub" x="642" y="188">ESP = __boot_stack_top</text>
  113. <text class="svg-sub" x="642" y="208">jmp kernel_main</text>
  114. <text class="svg-sub" x="642" y="228">32-bit flat · paging off</text>
  115. </svg>
  116. <figcaption>
  117. <strong>Every path hands off in the same shape:</strong> flat
  118. 32-bit segments, paging off, the framebuffer block at
  119. <code>0x600</code>, the boot-info block at <code>0x500</code>, and
  120. the kernel loaded at <code>0x7E00</code>.
  121. </figcaption>
  122. </figure>
  123. </section>
  124. <section id="bios">
  125. <h2>BIOS path</h2>
  126. <h3><span class="file">boot.S</span> — the 512-byte boot sector</h3>
  127. <p>
  128. The boot sector carries a FAT16 BPB, loads the contiguous kernel
  129. directly after itself to <code>0x7E00</code>, and jumps there.
  130. Each <code>INT 13h</code> reads a run of sectors into
  131. <code>ES:0</code> and then advances <code>ES</code>, so the offset
  132. never wraps: fixed disks use EDD LBA (<code>AH=42h</code>) with up to
  133. 64 sectors, floppies use CHS up to the end of the track and never
  134. across a 64 KB physical ISA DMA boundary. One call per sector used
  135. to make the kernel load ~700 BIOS calls, each of which can cost a
  136. floppy revolution. A failing run is tried three times, then the
  137. loader drops to one sector per call (the old behaviour) before it
  138. reports <code>Disk read error</code>. The sector count and the rootfs LBA are patched into the
  139. boot sector by the Makefile.
  140. </p>
  141. <p>
  142. On the USB image, <span class="file">mbr.S</span> runs first and
  143. loads the active partition's boot sector at LBA 63. From there the
  144. path is identical.
  145. </p>
  146. <h3><span class="file">vesa_stage.S</span> — the real-mode setup</h3>
  147. <p>
  148. The VESA stage is the busiest piece of the legacy chain. It runs in
  149. real mode at <code>0x7E00</code> and performs five jobs:
  150. </p>
  151. <ol>
  152. <li>Probe the <code>INT 15h</code> E820 memory map into <code>0x1000</code>.</li>
  153. <li>Enable A20 and read the <code>NBROOT1</code> rootfs header at the boot sector's <code>pack_lba</code> field.</li>
  154. <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>
  155. <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>
  156. <li>Enter protected mode and jump to <code>kernel_entry</code>.</li>
  157. </ol>
  158. <p>
  159. The pack no longer occupies the old <code>0x60000..0x9FBFF</code>
  160. low gap, so the legacy cap is <code>PACK_MAX</code> (4 MB, raised
  161. from 1 MB for the WiFi firmware and from 2 MB as the browser grew; the
  162. copy ends at <code>0xD00000</code>) and the
  163. kernel BSS/boot stack may use the gap. The kernel image only has to
  164. stay below <code>0x90000</code> so the top of low memory and the
  165. EBDA remain untouched; <span class="file">kernel.ld</span> enforces
  166. that with a link-time assertion.
  167. </p>
  168. <div class="note">
  169. <p><strong>BIOS state after the move.</strong> The X201's BIOS
  170. historically left translation bits behind after
  171. <code>AH=87h</code>; <span class="file">paging.c</span> still clears
  172. CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP and EFER.LME before it enables
  173. paging, because other BIOS protected-mode calls can do the same.
  174. The protected-mode copy keeps the pack safe until
  175. <span class="file">ramfs.c</span> takes a private page-allocated
  176. copy and releases the boot region.</p>
  177. </div>
  178. </section>
  179. <section id="uefi">
  180. <h2>UEFI path</h2>
  181. <p>
  182. <span class="file">efi/main.c</span> is a freestanding x86-64 PE32+
  183. application built with <code>x86_64-w64-mingw32-gcc</code>. It does
  184. not execute any of the legacy boot chain. Instead it:
  185. </p>
  186. <ol>
  187. <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>
  188. <li>Calls <code>GetMemoryMap</code> and converts the firmware map into the kernel's E820 format at <code>0x1000</code>.</li>
  189. <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>
  190. <li>Writes the boot-info and framebuffer blocks, calls <code>ExitBootServices</code>, then copies a 192-byte trampoline to <code>0x800</code>.</li>
  191. <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>
  192. </ol>
  193. <p>
  194. <span class="file">efi/payload.S</span> still embeds the kernel,
  195. the gzip rootfs pack and the trampoline inside
  196. <code>BOOTX64.EFI</code>, but the installed P1/P2 image wins when it
  197. is valid. That makes the ESP a one-time artifact: later
  198. <code>install</code>/<code>net-install</code>/<code>install self</code>
  199. updates touch only P1/P2, and UEFI and legacy boots run the same
  200. build. Secure Boot must be off; the loader is unsigned.
  201. </p>
  202. <div class="warn">
  203. <p><strong>No GOP, no video.</strong> If the loader cannot satisfy the
  204. mode constraints it still boots, but the kernel starts headless and
  205. only the serial log is available.</p>
  206. </div>
  207. </section>
  208. <section id="kexec">
  209. <h2>kexec path</h2>
  210. <p>
  211. kexec is the normal development loop: it replaces the running kernel
  212. without rebooting, reflashing or re-running the firmware. The
  213. framebuffer and its mode stay in place; only the image changes.
  214. </p>
  215. <ul>
  216. <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>
  217. <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>
  218. <li><strong>Runtime pack only.</strong> <code>KXNP</code> over serial or network replaces <code>/ramfs</code> in place without touching the kernel.</li>
  219. </ul>
  220. <p>
  221. Before jumping, <span class="file">kexec.c</span> calls
  222. <code>smp_stop_aps()</code>: every AP receives an INIT and is parked in
  223. the wait-for-SIPI state before the trampoline overwrites the kernel
  224. they were executing. The trampoline runs with interrupts off, resets
  225. <code>sched_lock</code> (an AP may have been inside a scheduler
  226. critical section), and jumps to <code>kernel_entry</code>.
  227. </p>
  228. <p>
  229. Because <span class="file">entry.S</span> re-points <code>ESP</code>
  230. before any stack use, a reload between builds with different memory
  231. maps cannot inherit a stale stack inside the new image.
  232. </p>
  233. </section>
  234. <section id="handoff">
  235. <h2>Handoff contract</h2>
  236. <p>
  237. <span class="file">bootinfo.h</span> defines the 12-dword block at
  238. <code>0x500</code>. The checksum is chosen so all twelve words sum to
  239. zero; that keeps stale low memory from being mistaken for a valid
  240. block after a kexec or legacy boot.
  241. </p>
  242. <div class="table-wrap">
  243. <table>
  244. <thead>
  245. <tr><th>Offset</th><th>Field</th><th>Meaning</th></tr>
  246. </thead>
  247. <tbody>
  248. <tr><td><code>+0</code></td><td><code>magic</code></td><td><code>0x4E425349</code> (<code>"NBSI"</code>)</td></tr>
  249. <tr><td><code>+4</code></td><td><code>version</code></td><td>Currently 2.</td></tr>
  250. <tr><td><code>+8</code></td><td><code>checksum</code></td><td>Makes the 12-word sum zero.</td></tr>
  251. <tr><td><code>+12</code></td><td><code>rsdp</code></td><td>ACPI RSDP physical address; zero means scan.</td></tr>
  252. <tr><td><code>+16</code></td><td><code>flags</code></td><td>EFI, RGBX pixel order, retained network config.</td></tr>
  253. <tr><td><code>+20</code></td><td><code>pack_addr</code></td><td>Boot-time rootfs pack address, zero if none.</td></tr>
  254. <tr><td><code>+24</code></td><td><code>pack_size</code></td><td>Exact gzip or raw pack byte count.</td></tr>
  255. <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>
  256. </tbody>
  257. </table>
  258. </div>
  259. <p>
  260. The framebuffer block at <code>0x600</code> is a
  261. <code>struct vga_boot_fb_info</code> (<span class="file">vga.h</span>):
  262. valid flag, LFB base, pitch, width, height, bpp and the RGBX flag.
  263. The E820 map at <code>0x1000</code> is a
  264. <code>struct e820_map</code> (<span class="file">mm.h</span>): magic,
  265. count and up to 32 entries.
  266. </p>
  267. </section>
  268. <section id="images">
  269. <h2>Disk image layout</h2>
  270. <p>
  271. The build produces several images from the same boot sector, kernel
  272. and rootfs. The floppy images append the <em>lite</em> pack
  273. (<code>rootfs.bin</code> from <code>cmds-lite.pack</code>, everything
  274. but <code>firmware/*</code>, the cursor bundle, the install kernel and
  275. <code>bin/browser.app</code>) so they still fit 1.44 MB; a floppy boot
  276. runs the browser from <code>BROWSER</code> on <code>root.img</code>. The USB
  277. rootfs partition carries the full pack (about 1.3 MB gzip with the
  278. WiFi firmware), which now ends past the first 1.44 MB: a BIOS that
  279. boots the stick as a CHS-only floppy can no longer read all of it.
  280. </p>
  281. <figure class="figure">
  282. <svg viewBox="0 0 920 342" role="img" aria-labelledby="images-title images-desc">
  283. <title id="images-title">NebOS disk image layouts</title>
  284. <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>
  285. <text class="svg-text" x="12" y="30">floppy.img</text>
  286. <text class="svg-tiny" x="908" y="30" text-anchor="end">1.44 MB</text>
  287. <rect class="svg-box accent" x="160" y="42" width="14" height="24" rx="3"/>
  288. <rect class="svg-box blue" x="178" y="42" width="250" height="24" rx="3"/>
  289. <rect class="svg-box green" x="432" y="42" width="210" height="24" rx="3"/>
  290. <rect class="svg-box" x="646" y="42" width="244" height="24" rx="3"/>
  291. <text class="svg-tiny" x="186" y="59">kernel</text>
  292. <text class="svg-tiny" x="440" y="59">rootfs.bin (lite)</text>
  293. <text class="svg-tiny" x="654" y="59">zero padding</text>
  294. <text class="svg-text" x="12" y="106">usb.img</text>
  295. <text class="svg-tiny" x="908" y="106" text-anchor="end">9 MB</text>
  296. <rect class="svg-box amber" x="160" y="118" width="184" height="24" rx="3"/>
  297. <rect class="svg-box green" x="416" y="118" width="474" height="24" rx="3"/>
  298. <text class="svg-tiny" x="176" y="135">P1 · boot + kernel</text>
  299. <text class="svg-tiny" x="424" y="135">partition 2 · rootfs · LBA 1088 · 8 MB</text>
  300. <text class="svg-text" x="12" y="182">usb-efi.img</text>
  301. <text class="svg-tiny" x="908" y="182" text-anchor="end">17 MB</text>
  302. <rect class="svg-box amber" x="160" y="194" width="184" height="24" rx="3"/>
  303. <rect class="svg-box green" x="416" y="194" width="250" height="24" rx="3"/>
  304. <rect class="svg-box accent" x="670" y="194" width="220" height="24" rx="3"/>
  305. <text class="svg-tiny" x="176" y="211">partition 1</text>
  306. <text class="svg-tiny" x="424" y="211">partition 2 · rootfs</text>
  307. <text class="svg-tiny" x="678" y="211">partition 3 · FAT16 ESP</text>
  308. <text class="svg-text" x="12" y="258">rootfs container</text>
  309. <text class="svg-tiny" x="908" y="258" text-anchor="end">8 MB cmds.img</text>
  310. <rect class="svg-box amber" x="160" y="270" width="56" height="26" rx="3"/>
  311. <rect class="svg-box green" x="220" y="270" width="670" height="26" rx="3"/>
  312. <text class="svg-tiny" x="172" y="288">header</text>
  313. <text class="svg-tiny" x="232" y="288">gzip command pack</text>
  314. <line class="svg-line" x1="160" y1="314" x2="890" y2="314"/>
  315. <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>
  316. </svg>
  317. <figcaption>
  318. <strong>Three images, one source tree.</strong> Partition 1 has
  319. an empty BPB, so neither UEFI firmware nor VFS mounts the raw
  320. kernel blob as a FAT volume and overwrites it.
  321. </figcaption>
  322. </figure>
  323. <div class="table-wrap">
  324. <table>
  325. <thead>
  326. <tr><th>Image</th><th>Size</th><th>Use</th></tr>
  327. </thead>
  328. <tbody>
  329. <tr><td><code>floppy.img</code></td><td>1.44 MB</td><td>Floppy boot; boot sector + kernel + appended rootfs.</td></tr>
  330. <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>
  331. <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>
  332. <tr><td><code>final.bin</code></td><td>Varies</td><td>Raw boot sector + kernel + rootfs, written directly to a device.</td></tr>
  333. <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>
  334. </tbody>
  335. </table>
  336. </div>
  337. <h3>Installing to a disk</h3>
  338. <p>
  339. The live system's <code>install &lt;target&gt; [source]</code>
  340. command clones P1..P3 (MBR through the end of the ESP) onto a target
  341. disk. It finds the source by the MBR plus the LBA-63 boot-sector
  342. signature and prefers <code>usb0</code>, the USB mass-storage view
  343. of the live stick. It reads the whole source image into RAM first
  344. (the unused LBA 1..62 gap is synthesized as zeros), prepares or
  345. keeps partition 4, writes the target from RAM, merges the data
  346. entry into the source MBR, writes the MBR last, flushes and verifies
  347. it. A source-read failure leaves the target untouched.
  348. </p>
  349. <p>
  350. Partition 4 starts at LBA 34816 and fills the rest of the disk as a
  351. writable FAT volume labelled <code>NEBOSDATA</code>, mounted at
  352. <code>/data</code>. A first install creates and formats it; a later
  353. install or <code>install &lt;target&gt; self</code> keeps it. The
  354. data volume is not part of the flashed image, so <code>usb.img</code>
  355. and <code>usb-efi.img</code> remain 9 MB and 17 MB. A clone of
  356. <code>usb-efi.img</code> keeps the legacy MBR chain and the ESP/UEFI
  357. chain; a clone of <code>usb.img</code> is BIOS-only. Runtime
  358. <code>cmds-dev</code> pack updates are not part of the clone.
  359. </p>
  360. </section>
  361. <section id="init">
  362. <h2>Kernel init order</h2>
  363. <p>
  364. <code>kernel_main</code> is a single linear bring-up. The order is
  365. constrained by what each step needs: GDT/TSS before <code>current_proc()</code>,
  366. paging before ACPI table access, process setup before the PIT can
  367. context-switch, and a ticking timer before AP bring-up can time out.
  368. </p>
  369. <ol>
  370. <li>Clear BSS; initialise the boot console straight into the
  371. framebuffer (8×16 text at the top-left, scrolling when full, with
  372. no heap, paging or shadow-buffer dependency).</li>
  373. <li>Bring up COM1 and the network-console ring buffer.</li>
  374. <li>Install the GDT/TSS and per-CPU GS base.</li>
  375. <li>Parse E820, build the frame bitmap and initialise <code>kmalloc</code>.</li>
  376. <li>Enable paging; keep a RAM copy of the boot log; enable SSE state if present.</li>
  377. <li>Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.</li>
  378. <li>Create the process table, then start the PIT and verify it ticks.</li>
  379. <li>Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).</li>
  380. <li>Initialise PS/2 (the I2C touchpad probe only on Airmont) and the VGA shadow buffer.</li>
  381. <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>
  382. <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>
  383. <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>
  384. <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>SYS_BOOTLOG</code> ring, which the <code>bootscan</code> window 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.</li>
  385. <li>Enable scheduling on the APs and enter the kernel idle loop.</li>
  386. </ol>
  387. <p>
  388. The terminal no longer waits for USB, the NIC or storage. The
  389. WM's network status poll does not trigger the NIC probe (it reports
  390. no NIC until <code>kernel_main</code> has probed), so the first frame
  391. never waits for a PHY reset. <code>/ramfs</code> and
  392. <code>/share</code> operations (including spawning commands from
  393. <code>/ramfs/bin</code>) skip the scan wait, a disk path waits for it,
  394. and the scan thread sleeps through its long probe timeouts. The
  395. end point of a boot measurement is the one-shot COM1 line
  396. <code>wm: first window frame (term) at N ms</code> (uptime), written
  397. by <span class="file">sys_wm.c</span> when the first terminal
  398. window presents (the bootscan window is skipped).
  399. </p>
  400. <p>
  401. The boot trace lines written along the way (<code>boot_trace</code>,
  402. <code>boot_val</code>) go to the framebuffer console and COM1, so a
  403. machine without serial still shows where a boot stopped. The
  404. console uses the same 8×16 face and top-left origin as the loader
  405. text and the ring-3 terminal, and scrolls the framebuffer when the
  406. screen is full instead of wrapping. The WM disables it when it
  407. attaches; <code>bootlog</code> prints the saved text.
  408. </p>
  409. </section>
  410. <section id="failures">
  411. <h2>Failure modes to know</h2>
  412. <ul>
  413. <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>
  414. <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 2.0 MB today, and inflating it adds roughly half a second to the boot.</li>
  415. <li><strong>PIT not ticking.</strong> <code>kernel_main</code> prints <code>*** PIT NOT TICKING ***</code> and halts; no process scheduling is possible.</li>
  416. <li><strong>UEFI Secure Boot.</strong> The unsigned <code>BOOTX64.EFI</code> is rejected before any NebOS code runs.</li>
  417. <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>
  418. </ul>
  419. </section>
  420. <section id="sources">
  421. <h2>Source map</h2>
  422. <ul class="filelist">
  423. <li><code>boot/boot.S</code> — boot sector</li>
  424. <li><code>boot/mbr.S</code> — USB/HDD MBR</li>
  425. <li><code>boot/vesa_stage.S</code> — real-mode VESA stage</li>
  426. <li><code>kernel/entry.S</code> — canonical kernel entry</li>
  427. <li><code>include/bootinfo.h</code> — 0x500 block</li>
  428. <li><code>kernel/vga.h</code> — 0x600 framebuffer block</li>
  429. <li><code>boot/efi/main.c</code> — UEFI loader</li>
  430. <li><code>boot/efi/tramp.S</code> — long-mode exit</li>
  431. <li><code>kernel/kexec.c</code>, <code>kernel/kexec_tramp.S</code> — serial reload</li>
  432. <li><code>kernel/netkexec.c</code> — network reload</li>
  433. <li><code>kernel/kernel.c</code> — init order</li>
  434. <li><code>kernel/init.c</code>, <code>kernel/init.h</code> — PID-1 init bootstrap and restart</li>
  435. <li><code>kernel/bootcon.c</code>, <code>common/font_8x16.c</code> — direct-to-LFB boot console and the <code>bootscan</code> thread's serial ring (<code>SYS_BOOTLOG</code>)</li>
  436. <li><code>kernel/install.c</code>, <code>kernel/install.h</code> — clone, self-update and net-install writer</li>
  437. <li><code>include/rootfs.h</code> — installed image geometry</li>
  438. <li><code>kernel/kernel.ld</code> — image limits</li>
  439. <li><code>Makefile</code> — image sizes and layout rules</li>
  440. </ul>
  441. </section>
  442. </main>
  443. <footer class="site-footer">
  444. <div class="inner">
  445. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  446. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  447. </div>
  448. </footer>
  449. </body>
  450. </html>