Memory & paging
A fixed ladder and a 4 KB frame allocator.
NebOS identity-maps the first 1 GB of RAM (lowmem) with 4 MB pages
and hands out 4 KB frames from a bitmap; RAM from 1 GB up to 4 GB
(highmem) backs ring-3 pages and is reached by the kernel through
per-CPU kmap slots. A small set of low-memory addresses is
fixed by the boot path and the ABI; everything else — process stacks,
window canvases, the ring-3 heap and the rootfs copy — is dynamic.
Physical memory
The real-mode stage probes INT 15h E820 and writes the
map to 0x1000; the UEFI loader synthesises the same
structure from GetMemoryMap. mm.c
starts with every page marked used, frees the E820 “usable RAM”
ranges, then reserves the regions the kernel already owns.
MM_MAX_PHYS,
include/phys.h). The identity map covers
[0, 0x40000000) and ring-3 space starts at
USER_BASE = 0x40000000; paging.c
statically asserts the two never overlap. RAM above 1 GB (up to
MM_HIGH_LIMIT, 4 GB) is highmem: tracked by the same
bitmap, never identity-mapped, used only for ring-3 pages. Highmem that the firmware's variable MTRRs leave non-write-back (a BIOS short of MTRRs on a 3–4 GB board) is never handed out: mm_init asks mtrr_mem_type() for every MB of free RAM, withholds such highmem, logs mm: RAM not write-back by MTRR, and meminfo shows the counts. Ring-3 code whose heap sits in uncached RAM runs many times slower (a browser's JavaScript heap, for example). The VGA shadow reserve is conservative: the
actual buffer is smaller, but the gap keeps a future resolution bump
from colliding with allocated pages.
Address landmarks
These addresses are part of the boot contract or the kernel ABI. Changing one requires updating the assembly, linker scripts, headers and this table together.
| Address | Purpose | Written by / notes |
|---|---|---|
0x500 | Boot info, 12 dwords | VESA stage, UEFI loader or kexec; bootinfo.h |
0x600 | Boot framebuffer info | VESA stage or UEFI loader; vga.h |
0x7C00 | Boot-sector load address / UEFI handoff stack top | BIOS and UEFI trampoline |
0x7E00 | Kernel load address and VESA-stage entry | kernel.ld |
0x800 | kexec and UEFI trampoline | Relocated at runtime; below the kernel |
0x900 | kexec/UEFI flat GDT and GDTR | Built at runtime; below the kernel |
0x1000 | E820 memory map | VESA stage, UEFI loader or kexec; parsed by mm.c |
0x3000 | UHCI frame list | 1024 × 4 bytes, 4 KB aligned |
0x4000 | ISA DMA buffer | One sector, used by the floppy driver |
0x6000 | AP real/protected-mode trampoline | SIPI vector 0x06; image ends below 0x6C00 |
0x6C00 | AP trampoline real-mode stack top | Grows down |
0x6F00 | AP startup info block | CR3, stack top, C entry, CPU index |
0x60000 | Former rootfs staging | No longer used by the loader; kernel BSS/stack may use it |
_end | Kernel end | kernel.ld asserts _end ≤ 0x90000 |
0x900000 | Boot pack (written directly by the legacy stage), then the frame bitmap right after it; dynamic stacks and kexec staging | The pack is freed after ramfs_init takes its copy; the bitmap stays |
0x100000 | VGA shadow buffer base | VGA_SHADOW_BASE; 8 MB reserved |
0x40000000 | Ring-3 ELF link/load address | USER_BASE, 4 MB window up to 0x40400000 |
0x4FC00000 | kmap window (virtual) | MM_KMAP_VA; supervisor page table shared by every directory, 4 slots per CPU |
0x50000000 | Ring-3 window canvas | USER_WIN_BASE, 4 MB slot |
0x58000000 | WM shadow mapping | WM_SHADOW_VA; ring-3 WM only |
0x59000000 | WM content slots | WM_CONTENT_VA_BASE + index × 4 MB (WM_CONTENT_SLOT) |
0x60000000 | Ring-3 anonymous heap | USER_HEAP_BASE, up to 64 MB |
0xC0000000 | ioremap window (virtual) | IOMAP_BASE to 4 GB: MMIO, firmware tables, LFB; kernel-only, 4 KB pages |
Paging & caching
paging.c builds an identity map of RAM with
4 MB pages through CR4.PSE, adds the framebuffer's LFB
range (in lowmem; otherwise through the ioremap window), and enables
CR0.PG and CR0.WP. Before
switching, it clears translation controls a BIOS protected-mode call
can leave behind: CR4.PAE/PGE/LA57/PCIDE/SMEP/SMAP and
EFER.LME.
- Identity map. Physical and virtual addresses are equal below 1 GB (lowmem). Page-directory entries are shared with every process.
- kmap window. The 4 MB slot at
MM_KMAP_VA(0x4FC00000, in the unused gap belowUSER_WIN_BASE) has one supervisor page table that every process directory shares.kmap(phys)returns the identity address for lowmem, and for a highmem frame takes this CPU's next slot (4 per CPU, nesting LIFO) with preemption disabled untilkunmap(); only the local TLB entry is flushed, because no other CPU uses that slot. It is not the last lowmem slot, because firmware puts the ACPI tables at the top of RAM, and not the top of the address space, where a VBE LFB may sit. - ioremap window. Nothing above lowmem is mapped at its physical address. Device registers, ACPI/SMBIOS tables and the LFB go through
ioremap(phys, size, type): lowmem returns its identity address (an MMIO range there gets uncacheable 4 MB pages), everything else gets 4 KB pages in the kernel-only window[0xC0000000, 4 GB)(IOMAP_BASE). Its page tables are allocated on first use and copied into every live process directory (process_sync_kernel_pde); a range already covered by a same-type mapping is reused, and one that runs past the newest mapping grows it in place. MMIO pages are uncached except the pages the LFB's WC MTRR covers, which are cacheable in every alias;IOREMAP_RAMpages are write-back. Drivers keep the physical BAR for logs and use the returned pointer.peek,pokeanddbgreach any physical byte throughpaging_debug_map(). - Kernel stacks mapped everywhere. Each process gets a page directory cloned from the kernel identity map, so CR3 can switch while still running on the old kernel stack.
- LFB is uncacheable by default. If
mtrr_set_wc()successfully covers the framebuffer, the LFB pages are mapped cacheable so the shadow-buffer flush can write-combine. - No process isolation. 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.
There is no cross-CPU TLB shootdown. MMIO mappings for another CPU's running process rely on not-present TLB entries not being cached; normal process teardown is unaffected because no two processes share an address space.
NVIDIA ION special case. On the ION the framebuffer is stolen DRAM and the VBE LFB is a BAR3 window into it. The BIOS leaves a 512 MB uncacheable MTRR over the PCIe apertures, so nvidia.c locates the framebuffer in the stolen VRAM and writes through that alias once a WC MTRR covers the stolen range. Everything else keeps the uncacheable LFB.
Frame allocator
mm.c keeps one bit per 4 KB page for the
RAM below 4 GB: the bitmap is sized to the highest E820 RAM
address (32 KB at 1 GB, 96 KB at 3 GB) and is not part of the kernel
image. mm_init places it in the first lowmem E820 RAM run at or above
0x900000 that avoids the boot rootfs pack and the LFB, and
marks its own pages used (legacy boots put it right after the pack;
a 16 MB static fallback covers a missing E820 map). The allocators
disable interrupts around the bitmap and hand out the lowest free
frames of a zone: each zone has a first-free word hint that skips its
full low part, single pages are found with bsf, and
mm_alloc_pages(n) steps over full and empty words 32 pages
at a time. Everything the kernel dereferences by physical address
(page tables, DMA buffers, canvases, kernel stacks, kmalloc)
comes from lowmem; ring-3 program, stack and heap frames prefer
highmem. The allocator returns:
mm_alloc_page()— one lowmem page (physical address 0 means failure).mm_alloc_user_page()— one frame for a ring-3 mapping: highmem first, lowmem when highmem is exhausted. Touch it only throughkmap()or the user mapping (elf.c, the user stack in process.c, the heap in sys_mem.c).mm_alloc_pages(n)—ncontiguous lowmem pages.mm_free_page()/mm_free_range()— release a page or a page-aligned boot reservation.
At boot, mm_init reserves the low 1 MB, the 8 MB VGA
shadow region, any LFB that overlaps RAM, the bitmap itself and the
boot-time rootfs pack. The pack reservation is released by
ramfs_init after it copies/inflates the pack into fresh
pages.
Fresh pages are not zeroed. Structures whose fields are read
before being written must be cleared explicitly; clear_proc()
in process.c exists because a stale
cr3 faulted on real hardware while QEMU's cleared RAM hid
the bug.
kmalloc
kmalloc.c is a power-of-two heap allocator on top of the frame allocator. It is intentionally simple: allocation rounds to a size class, free lists are per class, and large objects become contiguous page runs. PCBs, command context and sys_fs.c file loads use it.
The kernel heap is separate from userspace. Ring-3 processes get one
anonymous arena through SYS_MEM_ALLOC,
SYS_MEM_GROW and SYS_MEM_FREE;
commands manage it with malloc/free
from libc/malloc.c. The syscalls are the
backend in libc/ucmd_mem.c and are not
called by application code.
Ring-3 memory
A ring-3 ELF is linked at 0x40000000. The image and its
32-page (128 KB) user stack live in a 4 MB window ending at
0x40400000. The kernel window server maps a window's
RGB565 back buffer at 0x50000000, and the anonymous heap
starts at 0x60000000.
USER_HEAP_MAX in process.h; the browser's
DOM arenas and QuickJS heap use ~30 MB before images).
| Range | Size | Contents |
|---|---|---|
0x40000000–0x40400000 | 4 MB | ELF segments, user stack top at 0x40400000 (32 pages / 128 KB, grows down); highmem frames when available |
0x50000000–0x50400000 | 4 MB | One window canvas mapping (RW, per window) |
0x60000000–0x64000000 | up to 64 MB | Anonymous heap (highmem frames when available, zeroed through kmap); initial allocation zeroed, growth pages are not |
Ring-3 commands treat that arena as a real heap:
libc/malloc.c maps 64 KB on
first use, grows in page-rounded steps with 64 KB slack, and uses
boundary-tag blocks with a first-fit free list and immediate
coalescing. heap_reset() discards everything and unmaps
the arena; the browser calls it on navigation, so page-scoped
allocations (body, rules, image bitmaps and decode arenas) go back
to the frame allocator. A single allocation near 64 MB fails because
block headers count against the same cap.
Kernel stacks are 4 KB pages from the frame allocator, with an 8-stack
static fallback pool in BSS. The idle/bootstrap context uses the
in-image 8 KB .stack section. The user stack is separate:
32 pages just below 0x40400000.
Rootfs pack lifetime
- The compressed pack is at most 4 MB (
PACK_MAX), so the legacy copy ends below0xD00000, still inside the 16 MB no-E820 fallback; inflated it is about 4.35 MB with the WiFi firmware (the 8 MBRAMFS_MAX_DECOMPRESSEDcap applies). - The boot path places the gzip pack in RAM: the legacy stage copies it directly to
0x900000with a protected-moderep movsb, UEFI into a loader-data buffer below 1 GB, kexec in its staging buffer. mm_initreserves[pack_addr, pack_addr + pack_size)so the frame allocator cannot reuse it.ramfs_inittakes a private page-allocated copy, validates theNBROOT1header and inflates the pack into it.mm_free_rangereleases the boot region when it is above the VGA shadow reserve. The private copy lives untilramfs_replaceor reboot.
The ramfs holds at most 128 files and 8 MB of decompressed pack. A larger pack fails to load rather than partially mounting.
Limits & leaks
- No per-process address spaces. Paging is identity-mapped; there is no memory protection between processes.
- 4 GB ceiling, 64 MB per process. RAM above 4 GB is ignored (it would need PAE). Highmem raises the system total, but one process still has a 64 MB heap and a 4 MB image/stack window;
[USER_BASE, IOMAP_BASE)is free for demand paging. A wild kernel pointer between the identity map and the user windows is an instant#PF. - ioremap is append-only. 1 GB of window, 96 mapping records and no unmap: a driver that remaps repeatedly would exhaust it (
ioremaplogswindow fulland returns 0). - Highmem is user-only. Contiguous kernel buffers and every kernel structure stay in the 1 GB lowmem zone, so a machine with 4 GB can still run out of lowmem first.
- Kernel heap fragmentation.
kmalloc'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. - No TLB shootdown. Cross-CPU mapping changes rely on not-present entries not being cached.
Source map
kernel/mm.c,kernel/mm.h— E820 + bitmap allocatorinclude/phys.h— lowmem ceiling, kmap window, highmem limitkernel/kmalloc.c,kernel/kmalloc.h— kernel heapuser/lib/libc/malloc.c,user/lib/libc/ucmd_mem.c— ring-3 heap andSYS_MEM_*backenduser/lib/libc/string.c,user/lib/libc/stdlib.c— ring-3 libc supportkernel/paging.c,kernel/paging.h— identity map, kmap window, ioremap window, debug physical accesskernel/mtrr.c— write-combining MTRRskernel/process.c,kernel/process.h— stacks and user layoutkernel/ramfs.c— pack copy / inflateboot/efi/main.c— firmware map conversionkernel/kernel.ld— low-memory image limits