User virtual address layout (x86_64)

Canonical layout for user mappings under the P1 kernel. Kernel code and identity maps live elsewhere; this page is only what userland should assume for brk, mmap, and compositor present slots.

Note

For the actively maintained contract, cross-check newdocs/memory-and-address-spaces.md and newdocs/system-architecture.md.

Per-process regions

VA range (inclusive base)

Purpose

0 … 0x0000_7FFF_FFFF

Executable + data + brk heap. Code, rodata, .bss, and the grow-down brk arena. Do not put multi-megabyte RGBA framebuffers here — use sys_mmap_anon (syscall 9) instead.

0x7000_0000_0000 … 0x77FF_FFFF_FFFF

Anonymous mmap arena. sys_mmap grows mmap_current downward from 0x7800_0000_0000. Mappings must stay within this band. sys_munmap (syscall 11) only accepts bases in this range and frees backing physical frames.

0x7800_0000_0000 … 0x7800_0000_0FFF

Compositor present slot (per window). The WM maps a small shared page here for present / present_rgba handoff. Not general-purpose mmap space.

Syscalls (user-facing)

  • SYS_BRK (12) — adjusts the program break in the low VA heap only.

  • SYS_MMAP_ANON (9) — rdi = length in bytes (page-aligned, non-zero). Returns mapped base or !0 on error. Uses the mmap arena above.

  • SYS_MUNMAP (11) — rdi = base, rsi = length (both page-aligned, non-zero). Base must lie in the mmap arena; unmaps and frees physical pages.

Client guidance

  • Large RGBA surfaces: use p1_alloc_framebuffer / p1_free_framebuffer (or RgbaPingPong in p1_graphics) so buffers never sit on brk.

  • mmap_current is copied on spawn_thread when sharing CR3 with the parent, so threads in the same address space share one mmap cursor.

Graphical allocations vs brk (platform rule)

If a buffer is both graphical (pixels, glyph caches, GPU-style blobs) and larger than 64 KiB, it must live in the anonymous mmap arena — use sys_mmap_anon (9) and sys_munmap (11), or the p1_graphics / p1_framebuffer helpers. brk / malloc are for smaller working set data, stacks, strings, and non-scanout buffers.

  • WM ping-pong client framebuffers always use mmap (Compositor contract), even when the logical client area would fit under 64 KiB.

  • Other textures, atlases, and scratch RGBA: if byte_len > 64 * 1024, mmap; at or below that threshold, staying on the heap is acceptable if you accept relocation pressure — when in doubt, mmap.

SDK: see P1_GRAPHICAL_USE_MMAP_THRESHOLD_BYTES and p1_graphical_bytes_prefers_mmap in cstd::p1_graphics.