boot.html 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484
  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> (2 MB, raised
  161. from 1 MB for the WiFi firmware) and the
  162. kernel BSS/boot stack may use the gap. The kernel image only has to
  163. stay below <code>0x90000</code> so the top of low memory and the
  164. EBDA remain untouched; <span class="file">kernel.ld</span> enforces
  165. that with a link-time assertion.
  166. </p>
  167. <div class="note">
  168. <p><strong>BIOS state after the move.</strong> The X201's BIOS
  169. historically left translation bits behind after
  170. <code>AH=87h</code>; <span class="file">paging.c</span> still clears
  171. CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP and EFER.LME before it enables
  172. paging, because other BIOS protected-mode calls can do the same.
  173. The protected-mode copy keeps the pack safe until
  174. <span class="file">ramfs.c</span> takes a private page-allocated
  175. copy and releases the boot region.</p>
  176. </div>
  177. </section>
  178. <section id="uefi">
  179. <h2>UEFI path</h2>
  180. <p>
  181. <span class="file">efi/main.c</span> is a freestanding x86-64 PE32+
  182. application built with <code>x86_64-w64-mingw32-gcc</code>. It does
  183. not execute any of the legacy boot chain. Instead it:
  184. </p>
  185. <ol>
  186. <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>
  187. <li>Calls <code>GetMemoryMap</code> and converts the firmware map into the kernel's E820 format at <code>0x1000</code>.</li>
  188. <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 512 MB identity window. The kernel/pack embedded in <code>BOOTX64.EFI</code> are a fallback only.</li>
  189. <li>Writes the boot-info and framebuffer blocks, calls <code>ExitBootServices</code>, then copies a 192-byte trampoline to <code>0x800</code>.</li>
  190. <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>
  191. </ol>
  192. <p>
  193. <span class="file">efi/payload.S</span> still embeds the kernel,
  194. the gzip rootfs pack and the trampoline inside
  195. <code>BOOTX64.EFI</code>, but the installed P1/P2 image wins when it
  196. is valid. That makes the ESP a one-time artifact: later
  197. <code>install</code>/<code>net-install</code>/<code>install self</code>
  198. updates touch only P1/P2, and UEFI and legacy boots run the same
  199. build. Secure Boot must be off; the loader is unsigned.
  200. </p>
  201. <div class="warn">
  202. <p><strong>No GOP, no video.</strong> If the loader cannot satisfy the
  203. mode constraints it still boots, but the kernel starts headless and
  204. only the serial log is available.</p>
  205. </div>
  206. </section>
  207. <section id="kexec">
  208. <h2>kexec path</h2>
  209. <p>
  210. kexec is the normal development loop: it replaces the running kernel
  211. without rebooting, reflashing or re-running the firmware. The
  212. framebuffer and its mode stay in place; only the image changes.
  213. </p>
  214. <ul>
  215. <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>
  216. <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>
  217. <li><strong>Runtime pack only.</strong> <code>KXNP</code> over serial or network replaces <code>/ramfs</code> in place without touching the kernel.</li>
  218. </ul>
  219. <p>
  220. Before jumping, <span class="file">kexec.c</span> calls
  221. <code>smp_stop_aps()</code>: every AP receives an INIT and is parked in
  222. the wait-for-SIPI state before the trampoline overwrites the kernel
  223. they were executing. The trampoline runs with interrupts off, resets
  224. <code>sched_lock</code> (an AP may have been inside a scheduler
  225. critical section), and jumps to <code>kernel_entry</code>.
  226. </p>
  227. <p>
  228. Because <span class="file">entry.S</span> re-points <code>ESP</code>
  229. before any stack use, a reload between builds with different memory
  230. maps cannot inherit a stale stack inside the new image.
  231. </p>
  232. </section>
  233. <section id="handoff">
  234. <h2>Handoff contract</h2>
  235. <p>
  236. <span class="file">bootinfo.h</span> defines the 12-dword block at
  237. <code>0x500</code>. The checksum is chosen so all twelve words sum to
  238. zero; that keeps stale low memory from being mistaken for a valid
  239. block after a kexec or legacy boot.
  240. </p>
  241. <div class="table-wrap">
  242. <table>
  243. <thead>
  244. <tr><th>Offset</th><th>Field</th><th>Meaning</th></tr>
  245. </thead>
  246. <tbody>
  247. <tr><td><code>+0</code></td><td><code>magic</code></td><td><code>0x4E425349</code> (<code>"NBSI"</code>)</td></tr>
  248. <tr><td><code>+4</code></td><td><code>version</code></td><td>Currently 2.</td></tr>
  249. <tr><td><code>+8</code></td><td><code>checksum</code></td><td>Makes the 12-word sum zero.</td></tr>
  250. <tr><td><code>+12</code></td><td><code>rsdp</code></td><td>ACPI RSDP physical address; zero means scan.</td></tr>
  251. <tr><td><code>+16</code></td><td><code>flags</code></td><td>EFI, RGBX pixel order, retained network config.</td></tr>
  252. <tr><td><code>+20</code></td><td><code>pack_addr</code></td><td>Boot-time rootfs pack address, zero if none.</td></tr>
  253. <tr><td><code>+24</code></td><td><code>pack_size</code></td><td>Exact gzip or raw pack byte count.</td></tr>
  254. <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>
  255. </tbody>
  256. </table>
  257. </div>
  258. <p>
  259. The framebuffer block at <code>0x600</code> is a
  260. <code>struct vga_boot_fb_info</code> (<span class="file">vga.h</span>):
  261. valid flag, LFB base, pitch, width, height, bpp and the RGBX flag.
  262. The E820 map at <code>0x1000</code> is a
  263. <code>struct e820_map</code> (<span class="file">mm.h</span>): magic,
  264. count and up to 32 entries.
  265. </p>
  266. </section>
  267. <section id="images">
  268. <h2>Disk image layout</h2>
  269. <p>
  270. The build produces several images from the same boot sector, kernel
  271. and rootfs. The floppy images append the <em>lite</em> pack
  272. (<code>rootfs.bin</code> from <code>cmds-lite.pack</code>, everything
  273. but <code>firmware/*</code>, the cursor bundle, the install kernel and
  274. <code>bin/browser.app</code>) so they still fit 1.44 MB; a floppy boot
  275. runs the browser from <code>BROWSER</code> on <code>root.img</code>. The USB
  276. rootfs partition carries the full pack (about 1.3 MB gzip with the
  277. WiFi firmware), which now ends past the first 1.44 MB: a BIOS that
  278. boots the stick as a CHS-only floppy can no longer read all of it.
  279. </p>
  280. <figure class="figure">
  281. <svg viewBox="0 0 920 342" role="img" aria-labelledby="images-title images-desc">
  282. <title id="images-title">NebOS disk image layouts</title>
  283. <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>
  284. <text class="svg-text" x="12" y="30">floppy.img</text>
  285. <text class="svg-tiny" x="908" y="30" text-anchor="end">1.44 MB</text>
  286. <rect class="svg-box accent" x="160" y="42" width="14" height="24" rx="3"/>
  287. <rect class="svg-box blue" x="178" y="42" width="250" height="24" rx="3"/>
  288. <rect class="svg-box green" x="432" y="42" width="210" height="24" rx="3"/>
  289. <rect class="svg-box" x="646" y="42" width="244" height="24" rx="3"/>
  290. <text class="svg-tiny" x="186" y="59">kernel</text>
  291. <text class="svg-tiny" x="440" y="59">rootfs.bin (lite)</text>
  292. <text class="svg-tiny" x="654" y="59">zero padding</text>
  293. <text class="svg-text" x="12" y="106">usb.img</text>
  294. <text class="svg-tiny" x="908" y="106" text-anchor="end">9 MB</text>
  295. <rect class="svg-box amber" x="160" y="118" width="184" height="24" rx="3"/>
  296. <rect class="svg-box green" x="416" y="118" width="474" height="24" rx="3"/>
  297. <text class="svg-tiny" x="176" y="135">P1 · boot + kernel</text>
  298. <text class="svg-tiny" x="424" y="135">partition 2 · rootfs · LBA 1088 · 8 MB</text>
  299. <text class="svg-text" x="12" y="182">usb-efi.img</text>
  300. <text class="svg-tiny" x="908" y="182" text-anchor="end">17 MB</text>
  301. <rect class="svg-box amber" x="160" y="194" width="184" height="24" rx="3"/>
  302. <rect class="svg-box green" x="416" y="194" width="250" height="24" rx="3"/>
  303. <rect class="svg-box accent" x="670" y="194" width="220" height="24" rx="3"/>
  304. <text class="svg-tiny" x="176" y="211">partition 1</text>
  305. <text class="svg-tiny" x="424" y="211">partition 2 · rootfs</text>
  306. <text class="svg-tiny" x="678" y="211">partition 3 · FAT16 ESP</text>
  307. <text class="svg-text" x="12" y="258">rootfs container</text>
  308. <text class="svg-tiny" x="908" y="258" text-anchor="end">8 MB cmds.img</text>
  309. <rect class="svg-box amber" x="160" y="270" width="56" height="26" rx="3"/>
  310. <rect class="svg-box green" x="220" y="270" width="670" height="26" rx="3"/>
  311. <text class="svg-tiny" x="172" y="288">header</text>
  312. <text class="svg-tiny" x="232" y="288">gzip command pack</text>
  313. <line class="svg-line" x1="160" y1="314" x2="890" y2="314"/>
  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>
  315. </svg>
  316. <figcaption>
  317. <strong>Three images, one source tree.</strong> Partition 1 has
  318. an empty BPB, so neither UEFI firmware nor VFS mounts the raw
  319. kernel blob as a FAT volume and overwrites it.
  320. </figcaption>
  321. </figure>
  322. <div class="table-wrap">
  323. <table>
  324. <thead>
  325. <tr><th>Image</th><th>Size</th><th>Use</th></tr>
  326. </thead>
  327. <tbody>
  328. <tr><td><code>floppy.img</code></td><td>1.44 MB</td><td>Floppy boot; boot sector + kernel + appended rootfs.</td></tr>
  329. <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>
  330. <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>
  331. <tr><td><code>final.bin</code></td><td>Varies</td><td>Raw boot sector + kernel + rootfs, written directly to a device.</td></tr>
  332. <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>
  333. </tbody>
  334. </table>
  335. </div>
  336. <h3>Installing to a disk</h3>
  337. <p>
  338. The live system's <code>install &lt;target&gt; [source]</code>
  339. command clones P1..P3 (MBR through the end of the ESP) onto a target
  340. disk. It finds the source by the MBR plus the LBA-63 boot-sector
  341. signature and prefers <code>usb0</code>, the USB mass-storage view
  342. of the live stick. It reads the whole source image into RAM first
  343. (the unused LBA 1..62 gap is synthesized as zeros), prepares or
  344. keeps partition 4, writes the target from RAM, merges the data
  345. entry into the source MBR, writes the MBR last, flushes and verifies
  346. it. A source-read failure leaves the target untouched.
  347. </p>
  348. <p>
  349. Partition 4 starts at LBA 34816 and fills the rest of the disk as a
  350. writable FAT volume labelled <code>NEBOSDATA</code>, mounted at
  351. <code>/data</code>. A first install creates and formats it; a later
  352. install or <code>install &lt;target&gt; self</code> keeps it. The
  353. data volume is not part of the flashed image, so <code>usb.img</code>
  354. and <code>usb-efi.img</code> remain 9 MB and 17 MB. A clone of
  355. <code>usb-efi.img</code> keeps the legacy MBR chain and the ESP/UEFI
  356. chain; a clone of <code>usb.img</code> is BIOS-only. Runtime
  357. <code>cmds-dev</code> pack updates are not part of the clone.
  358. </p>
  359. </section>
  360. <section id="init">
  361. <h2>Kernel init order</h2>
  362. <p>
  363. <code>kernel_main</code> is a single linear bring-up. The order is
  364. constrained by what each step needs: GDT/TSS before <code>current_proc()</code>,
  365. paging before ACPI table access, process setup before the PIT can
  366. context-switch, and a ticking timer before AP bring-up can time out.
  367. </p>
  368. <ol>
  369. <li>Clear BSS; initialise the boot console straight into the
  370. framebuffer (8×16 text at the top-left, scrolling when full, with
  371. no heap, paging or shadow-buffer dependency).</li>
  372. <li>Bring up COM1 and the network-console ring buffer.</li>
  373. <li>Install the GDT/TSS and per-CPU GS base.</li>
  374. <li>Parse E820, build the frame bitmap and initialise <code>kmalloc</code>.</li>
  375. <li>Enable paging; keep a RAM copy of the boot log; enable SSE state if present.</li>
  376. <li>Parse ACPI/MADT; initialise I/O, power, idle, thermal and board sensors.</li>
  377. <li>Create the process table, then start the PIT and verify it ticks.</li>
  378. <li>Start APs through INIT-SIPI-SIPI (they idle until scheduling is enabled).</li>
  379. <li>Initialise PS/2 (the I2C touchpad probe only on Airmont) and the VGA shadow buffer.</li>
  380. <li>Inflate the command pack into <code>/ramfs</code> (table-driven whole-buffer inflate); start the WM and the first frame.</li>
  381. <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>
  382. <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>
  383. <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>
  384. <li>Enable scheduling on the APs and enter the kernel idle loop.</li>
  385. </ol>
  386. <p>
  387. The terminal no longer waits for USB, the NIC or storage. The
  388. WM's network status poll does not trigger the NIC probe (it reports
  389. no NIC until <code>kernel_main</code> has probed), so the first frame
  390. never waits for a PHY reset. <code>/ramfs</code> and
  391. <code>/share</code> operations (including spawning commands from
  392. <code>/ramfs/bin</code>) skip the scan wait, a disk path waits for it,
  393. and the scan thread sleeps through its long probe timeouts. The
  394. end point of a boot measurement is the one-shot COM1 line
  395. <code>wm: first window frame (term) at N ms</code> (uptime), written
  396. by <span class="file">sys_wm.c</span> when the first application
  397. window presents.
  398. </p>
  399. <p>
  400. The boot trace lines written along the way (<code>boot_trace</code>,
  401. <code>boot_val</code>) go to the framebuffer console and COM1, so a
  402. machine without serial still shows where a boot stopped. The
  403. console uses the same 8×16 face and top-left origin as the loader
  404. text and the ring-3 terminal, and scrolls the framebuffer when the
  405. screen is full instead of wrapping. The WM disables it when it
  406. attaches; <code>bootlog</code> prints the saved text.
  407. </p>
  408. </section>
  409. <section id="failures">
  410. <h2>Failure modes to know</h2>
  411. <ul>
  412. <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>
  413. <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>
  414. <li><strong>PIT not ticking.</strong> <code>kernel_main</code> prints <code>*** PIT NOT TICKING ***</code> and halts; no process scheduling is possible.</li>
  415. <li><strong>UEFI Secure Boot.</strong> The unsigned <code>BOOTX64.EFI</code> is rejected before any NebOS code runs.</li>
  416. <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>
  417. </ul>
  418. </section>
  419. <section id="sources">
  420. <h2>Source map</h2>
  421. <ul class="filelist">
  422. <li><code>boot/boot.S</code> — boot sector</li>
  423. <li><code>boot/mbr.S</code> — USB/HDD MBR</li>
  424. <li><code>boot/vesa_stage.S</code> — real-mode VESA stage</li>
  425. <li><code>kernel/entry.S</code> — canonical kernel entry</li>
  426. <li><code>include/bootinfo.h</code> — 0x500 block</li>
  427. <li><code>kernel/vga.h</code> — 0x600 framebuffer block</li>
  428. <li><code>boot/efi/main.c</code> — UEFI loader</li>
  429. <li><code>boot/efi/tramp.S</code> — long-mode exit</li>
  430. <li><code>kernel/kexec.c</code>, <code>kernel/kexec_tramp.S</code> — serial reload</li>
  431. <li><code>kernel/netkexec.c</code> — network reload</li>
  432. <li><code>kernel/kernel.c</code> — init order</li>
  433. <li><code>kernel/bootcon.c</code>, <code>common/font_8x16.c</code> — direct-to-LFB boot console</li>
  434. <li><code>kernel/install.c</code>, <code>kernel/install.h</code> — clone, self-update and net-install writer</li>
  435. <li><code>include/rootfs.h</code> — installed image geometry</li>
  436. <li><code>kernel/kernel.ld</code> — image limits</li>
  437. <li><code>Makefile</code> — image sizes and layout rules</li>
  438. </ul>
  439. </section>
  440. </main>
  441. <footer class="site-footer">
  442. <div class="inner">
  443. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  444. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  445. </div>
  446. </footer>
  447. </body>
  448. </html>