memory.html 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343
  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>Memory | NebOS Architecture</title>
  7. <meta name="description" content="NebOS memory architecture: fixed low-memory addresses, E820 parsing, bitmap frame allocator, identity paging, MTRR write-combining, user arenas and boot-pack lifetime.">
  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">Boot</a>
  21. <a href="memory.html" aria-current="page">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">Memory &amp; paging</p>
  34. <h1>A fixed ladder and a 4 KB frame allocator.</h1>
  35. <p class="lede">
  36. NebOS identity-maps physical RAM with 4 MB pages and hands out
  37. 4 KB frames from a bitmap. A small set of low-memory addresses is
  38. fixed by the boot path and the ABI; everything else — process stacks,
  39. window canvases, the ring-3 heap and the rootfs copy — is dynamic.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">512 MB physical ceiling</span>
  43. <span class="pill">4 KB frames</span>
  44. <span class="pill">4 MB PSE pages</span>
  45. <span class="pill">identity map</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="#physical">Physical memory</a></li>
  52. <li><a href="#landmarks">Address landmarks</a></li>
  53. <li><a href="#paging">Paging &amp; caching</a></li>
  54. <li><a href="#frame">Frame allocator</a></li>
  55. <li><a href="#heap">kmalloc</a></li>
  56. <li><a href="#user">Ring-3 memory</a></li>
  57. <li><a href="#pack">Rootfs pack lifetime</a></li>
  58. <li><a href="#limits">Limits &amp; leaks</a></li>
  59. <li><a href="#sources">Source map</a></li>
  60. </ul>
  61. </nav>
  62. <section id="physical">
  63. <h2>Physical memory</h2>
  64. <p>
  65. The real-mode stage probes <code>INT 15h</code> E820 and writes the
  66. map to <code>0x1000</code>; the UEFI loader synthesises the same
  67. structure from <code>GetMemoryMap</code>. <span class="file">mm.c</span>
  68. starts with every page marked used, frees the E820 “usable RAM”
  69. ranges, then reserves the regions the kernel already owns.
  70. </p>
  71. <figure class="figure">
  72. <svg viewBox="0 0 920 180" role="img" aria-labelledby="phys-title phys-desc">
  73. <title id="phys-title">Physical memory composition</title>
  74. <desc id="phys-desc">Of the 512 MB addressable window, the low 1 MB and an 8 MB VGA shadow reserve are unavailable, leaving about 503 MB for the frame allocator.</desc>
  75. <text class="svg-text" x="20" y="28">0x00000000</text>
  76. <text class="svg-text" x="900" y="28" text-anchor="end">0x20000000 · 512 MB</text>
  77. <rect class="svg-box blue" x="40" y="44" width="2" height="34" rx="1"/>
  78. <rect class="svg-box accent" x="42" y="44" width="13.5" height="34" rx="1"/>
  79. <rect class="svg-box green" x="55.5" y="44" width="844.5" height="34" rx="2"/>
  80. <text class="svg-tiny" x="40" y="100">low 1 MB</text>
  81. <text class="svg-tiny" x="64" y="100">VGA shadow · 8 MB</text>
  82. <text class="svg-tiny" x="477" y="100" text-anchor="middle">frame allocator · ~503 MB</text>
  83. <line class="svg-line" x1="41" y1="78" x2="41" y2="88"/>
  84. <line class="svg-line" x1="48" y1="78" x2="48" y2="88"/>
  85. <line class="svg-line" x1="490" y1="78" x2="490" y2="88"/>
  86. <text class="svg-tiny" x="40" y="130">boot structures · kernel image · BIOS/UMA · DMA buffers</text>
  87. <text class="svg-tiny" x="40" y="150">The 8 MB reserve protects the shadow buffer; the allocator starts at 0x900000.</text>
  88. </svg>
  89. <figcaption>
  90. <strong>512 MB is a hard ceiling.</strong> The frame bitmap covers
  91. <code>[0, 0x20000000)</code>; addresses above it are not mapped by
  92. the kernel page tables. The VGA shadow reserve is conservative: the
  93. actual buffer is smaller, but the gap keeps a future resolution bump
  94. from colliding with allocated pages.
  95. </figcaption>
  96. </figure>
  97. </section>
  98. <section id="landmarks">
  99. <h2>Address landmarks</h2>
  100. <p>
  101. These addresses are part of the boot contract or the kernel ABI.
  102. Changing one requires updating the assembly, linker scripts, headers
  103. and this table together.
  104. </p>
  105. <div class="table-wrap">
  106. <table>
  107. <thead>
  108. <tr><th>Address</th><th>Purpose</th><th>Written by / notes</th></tr>
  109. </thead>
  110. <tbody>
  111. <tr><td><code>0x500</code></td><td>Boot info, 12 dwords</td><td>VESA stage, UEFI loader or kexec; <code>bootinfo.h</code></td></tr>
  112. <tr><td><code>0x600</code></td><td>Boot framebuffer info</td><td>VESA stage or UEFI loader; <code>vga.h</code></td></tr>
  113. <tr><td><code>0x7C00</code></td><td>Boot-sector load address / UEFI handoff stack top</td><td>BIOS and UEFI trampoline</td></tr>
  114. <tr><td><code>0x7E00</code></td><td>Kernel load address and VESA-stage entry</td><td><code>kernel.ld</code></td></tr>
  115. <tr><td><code>0x800</code></td><td>kexec and UEFI trampoline</td><td>Relocated at runtime; below the kernel</td></tr>
  116. <tr><td><code>0x900</code></td><td>kexec/UEFI flat GDT and GDTR</td><td>Built at runtime; below the kernel</td></tr>
  117. <tr><td><code>0x1000</code></td><td>E820 memory map</td><td>VESA stage, UEFI loader or kexec; parsed by <code>mm.c</code></td></tr>
  118. <tr><td><code>0x3000</code></td><td>UHCI frame list</td><td>1024 × 4 bytes, 4 KB aligned</td></tr>
  119. <tr><td><code>0x4000</code></td><td>ISA DMA buffer</td><td>One sector, used by the floppy driver</td></tr>
  120. <tr><td><code>0x6000</code></td><td>AP real/protected-mode trampoline</td><td>SIPI vector <code>0x06</code>; image ends below <code>0x6C00</code></td></tr>
  121. <tr><td><code>0x6C00</code></td><td>AP trampoline real-mode stack top</td><td>Grows down</td></tr>
  122. <tr><td><code>0x6F00</code></td><td>AP startup info block</td><td>CR3, stack top, C entry, CPU index</td></tr>
  123. <tr><td><code>0x60000</code></td><td>Former rootfs staging</td><td>No longer used by the loader; kernel BSS/stack may use it</td></tr>
  124. <tr><td><code>_end</code></td><td>Kernel end</td><td><code>kernel.ld</code> asserts <code>_end ≤ 0x90000</code></td></tr>
  125. <tr><td><code>0x900000</code></td><td>Boot pack (written directly by the legacy stage); dynamic stacks and kexec staging</td><td>Freed after <code>ramfs_init</code> takes its copy</td></tr>
  126. <tr><td><code>0x100000</code></td><td>VGA shadow buffer base</td><td><code>VGA_SHADOW_BASE</code>; 8 MB reserved</td></tr>
  127. <tr><td><code>0x40000000</code></td><td>Ring-3 ELF link/load address</td><td><code>USER_BASE</code>, 4 MB window up to <code>0x40400000</code></td></tr>
  128. <tr><td><code>0x50000000</code></td><td>Ring-3 window canvas</td><td><code>USER_WIN_BASE</code>, 4 MB slot</td></tr>
  129. <tr><td><code>0x58000000</code></td><td>WM shadow mapping</td><td><code>WM_SHADOW_VA</code>; ring-3 WM only</td></tr>
  130. <tr><td><code>0x59000000</code></td><td>WM content slots</td><td><code>WM_CONTENT_VA_BASE</code> + index × 4 MB (<code>WM_CONTENT_SLOT</code>)</td></tr>
  131. <tr><td><code>0x60000000</code></td><td>Ring-3 anonymous heap</td><td><code>USER_HEAP_BASE</code>, up to 32 MB</td></tr>
  132. </tbody>
  133. </table>
  134. </div>
  135. </section>
  136. <section id="paging">
  137. <h2>Paging &amp; caching</h2>
  138. <p>
  139. <span class="file">paging.c</span> builds an identity map of RAM with
  140. 4 MB pages through <code>CR4.PSE</code>, adds the framebuffer's LFB
  141. range, and enables <code>CR0.PG</code> and <code>CR0.WP</code>. Before
  142. switching, it clears translation controls a BIOS protected-mode call
  143. can leave behind: <code>CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP</code> and
  144. <code>EFER.LME</code>.
  145. </p>
  146. <ul>
  147. <li><strong>Identity map.</strong> Physical and virtual addresses are equal. Page-directory entries are shared with every process.</li>
  148. <li><strong>Kernel stacks mapped everywhere.</strong> Each process gets a page directory cloned from the kernel identity map, so CR3 can switch while still running on the old kernel stack.</li>
  149. <li><strong>LFB is uncacheable by default.</strong> If <code>mtrr_set_wc()</code> successfully covers the framebuffer, the LFB pages are mapped cacheable so the shadow-buffer flush can write-combine.</li>
  150. <li><strong>No process isolation.</strong> There is one address space with per-process page directories only for mappings; a wild ring-0 or ring-3 pointer can reach any mapped physical page.</li>
  151. </ul>
  152. <p>
  153. There is no cross-CPU TLB shootdown. MMIO mappings for another CPU's
  154. running process rely on not-present TLB entries not being cached;
  155. normal process teardown is unaffected because no two processes share
  156. an address space.
  157. </p>
  158. <div class="note">
  159. <p><strong>NVIDIA ION special case.</strong> On the ION the framebuffer is
  160. stolen DRAM and the VBE LFB is a BAR3 window into it. The BIOS leaves a
  161. 512 MB uncacheable MTRR over the PCIe apertures, so <span class="file">nvidia.c</span>
  162. locates the framebuffer in the stolen VRAM and writes through that
  163. alias once a WC MTRR covers the stolen range. Everything else keeps
  164. the uncacheable LFB.</p>
  165. </div>
  166. </section>
  167. <section id="frame">
  168. <h2>Frame allocator</h2>
  169. <p>
  170. <span class="file">mm.c</span> keeps one bit per 4 KB page for the
  171. whole 512 MB window. The bitmap is not IRQ-safe; callers save and
  172. disable interrupts around allocations. The allocator returns:
  173. </p>
  174. <ul>
  175. <li><code>mm_alloc_page()</code> — one zero-address-ambiguous page (physical address 0 means failure).</li>
  176. <li><code>mm_alloc_pages(n)</code> — <code>n</code> contiguous pages.</li>
  177. <li><code>mm_free_page()</code> / <code>mm_free_range()</code> — release a page or a page-aligned boot reservation.</li>
  178. </ul>
  179. <p>
  180. At boot, <code>mm_init</code> reserves the low 1 MB, the 8 MB VGA
  181. shadow region, any LFB that happens to live below 512 MB, and the
  182. boot-time rootfs pack. The pack reservation is released by
  183. <code>ramfs_init</code> after it copies/inflates the pack into fresh
  184. pages.
  185. </p>
  186. <p>
  187. Fresh pages are <em>not</em> zeroed. Structures whose fields are read
  188. before being written must be cleared explicitly; <code>clear_proc()</code>
  189. in <span class="file">process.c</span> exists because a stale
  190. <code>cr3</code> faulted on real hardware while QEMU's cleared RAM hid
  191. the bug.
  192. </p>
  193. </section>
  194. <section id="heap">
  195. <h2>kmalloc</h2>
  196. <p>
  197. <span class="file">kmalloc.c</span> is a power-of-two heap allocator
  198. on top of the frame allocator. It is intentionally simple: allocation
  199. rounds to a size class, free lists are per class, and large objects
  200. become contiguous page runs. PCBs, command context and
  201. <span class="file">sys_fs.c</span> file loads use it.
  202. </p>
  203. <p>
  204. The kernel heap is separate from userspace. Ring-3 processes get one
  205. anonymous arena through <code>SYS_MEM_ALLOC</code>,
  206. <code>SYS_MEM_GROW</code> and <code>SYS_MEM_FREE</code>;
  207. commands manage it with <code>malloc</code>/<code>free</code>
  208. from <span class="file">libc/malloc.c</span>. The syscalls are the
  209. backend in <span class="file">libc/ucmd_mem.c</span> and are not
  210. called by application code.
  211. </p>
  212. </section>
  213. <section id="user">
  214. <h2>Ring-3 memory</h2>
  215. <p>
  216. A ring-3 ELF is linked at <code>0x40000000</code>. The image and its
  217. 32-page (128 KB) user stack live in a 4 MB window ending at
  218. <code>0x40400000</code>. The kernel window server maps a window's
  219. RGB565 back buffer at <code>0x50000000</code>, and the anonymous heap
  220. starts at <code>0x60000000</code>.
  221. </p>
  222. <figure class="figure">
  223. <div class="bars" role="img" aria-label="Ring-3 arena sizes relative to the 32 MB heap cap: image and stack 4 MB, canvas slot 4 MB, heap up to 32 MB.">
  224. <div class="bar-row">
  225. <span class="bar-label">image + stack</span>
  226. <div class="bar-track"><span class="bar-fill blue" style="--w:12.5%"></span></div>
  227. <span class="bar-value">4 MB</span>
  228. </div>
  229. <div class="bar-row">
  230. <span class="bar-label">canvas slot</span>
  231. <div class="bar-track"><span class="bar-fill" style="--w:12.5%"></span></div>
  232. <span class="bar-value">4 MB</span>
  233. </div>
  234. <div class="bar-row">
  235. <span class="bar-label">anonymous heap</span>
  236. <div class="bar-track"><span class="bar-fill green" style="--w:100%"></span></div>
  237. <span class="bar-value">32 MB</span>
  238. </div>
  239. </div>
  240. <figcaption>
  241. <strong>Three separate rings.</strong> The image/stack window is
  242. fixed at link time; the canvas slot is one 4 MB mapping; the heap is
  243. a growable arena. Bar widths are relative to the 32 MB heap cap.
  244. </figcaption>
  245. </figure>
  246. <div class="table-wrap">
  247. <table>
  248. <thead>
  249. <tr><th>Range</th><th>Size</th><th>Contents</th></tr>
  250. </thead>
  251. <tbody>
  252. <tr><td><code>0x40000000</code>–<code>0x40400000</code></td><td>4 MB</td><td>ELF segments, user stack top at <code>0x40400000</code> (32 pages / 128 KB, grows down)</td></tr>
  253. <tr><td><code>0x50000000</code>–<code>0x50400000</code></td><td>4 MB</td><td>One window canvas mapping (RW, per window)</td></tr>
  254. <tr><td><code>0x60000000</code>–<code>0x62000000</code></td><td>up to 32 MB</td><td>Anonymous heap; initial allocation zeroed, growth pages are not</td></tr>
  255. </tbody>
  256. </table>
  257. </div>
  258. <p>
  259. Ring-3 commands treat that arena as a real heap:
  260. <span class="file">libc/malloc.c</span> maps 64 KB on
  261. first use, grows in page-rounded steps with 64 KB slack, and uses
  262. boundary-tag blocks with a first-fit free list and immediate
  263. coalescing. <code>heap_reset()</code> discards everything and unmaps
  264. the arena; the browser calls it on navigation, so page-scoped
  265. allocations (body, rules, image bitmaps and decode arenas) go back
  266. to the frame allocator. A single allocation near 32 MB fails because
  267. block headers count against the same cap.
  268. </p>
  269. <p>
  270. Kernel stacks are 4 KB pages from the frame allocator, with an 8-stack
  271. static fallback pool in BSS. The idle/bootstrap context uses the
  272. in-image 8 KB <code>.stack</code> section. The user stack is separate:
  273. 32 pages just below <code>0x40400000</code>.
  274. </p>
  275. </section>
  276. <section id="pack">
  277. <h2>Rootfs pack lifetime</h2>
  278. <ol>
  279. <li>The boot path places the gzip pack in RAM: the legacy stage copies it directly to <code>0x900000</code> with <code>INT 15h AH=87h</code>, UEFI at the top of RAM below 512 MB, kexec in its staging buffer.</li>
  280. <li><code>mm_init</code> reserves <code>[pack_addr, pack_addr + pack_size)</code> so the frame allocator cannot reuse it.</li>
  281. <li><code>ramfs_init</code> takes a private page-allocated copy, validates the <code>NBROOT1</code> header and inflates the pack into it.</li>
  282. <li><code>mm_free_range</code> releases the boot region when it is above the VGA shadow reserve. The private copy lives until <code>ramfs_replace</code> or reboot.</li>
  283. </ol>
  284. <p>
  285. The ramfs holds at most 128 files and 8 MB of decompressed pack. A
  286. larger pack fails to load rather than partially mounting.
  287. </p>
  288. </section>
  289. <section id="limits">
  290. <h2>Limits &amp; leaks</h2>
  291. <ul>
  292. <li><strong>No per-process address spaces.</strong> Paging is identity-mapped; there is no memory protection between processes.</li>
  293. <li><strong>512 MB ceiling.</strong> Physical memory above <code>0x20000000</code> is unmapped. A wild pointer there is an instant <code>#PF</code>.</li>
  294. <li><strong>User page leak on reap.</strong> Killing a ring-3 process frees its kernel stack and page directory but not all user pages mapped into it; a few pages leak per command run.</li>
  295. <li><strong>Kernel heap fragmentation.</strong> <code>kmalloc</code>'s power-of-two size classes make long-running mixed-size kernel allocation wasteful; ring-3 commands use the separate first-fit libc heap described above.</li>
  296. <li><strong>No TLB shootdown.</strong> Cross-CPU mapping changes rely on not-present entries not being cached.</li>
  297. </ul>
  298. </section>
  299. <section id="sources">
  300. <h2>Source map</h2>
  301. <ul class="filelist">
  302. <li><code>mm.c</code>, <code>mm.h</code> — E820 + bitmap allocator</li>
  303. <li><code>phys.h</code> — shared 512 MB physical ceiling</li>
  304. <li><code>kmalloc.c</code>, <code>kmalloc.h</code> — kernel heap</li>
  305. <li><code>libc/malloc.c</code>, <code>libc/ucmd_mem.c</code> — ring-3 heap and <code>SYS_MEM_*</code> backend</li>
  306. <li><code>libc/string.c</code>, <code>libc/stdlib.c</code> — ring-3 libc support</li>
  307. <li><code>paging.c</code>, <code>paging.h</code> — identity map</li>
  308. <li><code>mtrr.c</code> — write-combining MTRRs</li>
  309. <li><code>process.c</code>, <code>process.h</code> — stacks and user layout</li>
  310. <li><code>ramfs.c</code> — pack copy / inflate</li>
  311. <li><code>efi/main.c</code> — firmware map conversion</li>
  312. <li><code>kernel.ld</code> — low-memory image limits</li>
  313. </ul>
  314. </section>
  315. </main>
  316. <footer class="site-footer">
  317. <div class="inner">
  318. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  319. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  320. </div>
  321. </footer>
  322. </body>
  323. </html>