From 9637345d8eebbd9a916c49a712f9745190b19f53 Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Fri, 31 Jul 2026 15:51:37 +0200
Subject: docs: CONTEXT.md — paging adoption, heap growth, shell additions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- paging strategy: adopt_tables() rebuilds the firmware map into the
  kernel's own tables (UEFI maps its tables read-only) and switches CR3
- physical memory: heap grows into the page allocator on demand
- milestones: paging helpers, heap growth, mmap/stress commands
- project layout: paging.rs entry
---
 CONTEXT.md | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

(limited to 'CONTEXT.md')

diff --git a/CONTEXT.md b/CONTEXT.md
index c1c5781..d509b0c 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -30,16 +30,29 @@ structs are hand-defined (not from `uefi-rs` crate) to stay lightweight.
 ## Paging strategy
 
 Long mode mandates paging (`CR0.PG = 1`), so we accept that tax but keep it
-simple.  Retain UEFI's identity-mapped 4-level page tables.  No higher-half,
-no demand paging, no guard pages.  When the kernel needs more physical pages,
-entries are added 1:1 to the existing page tables.
+simple.  Identity-mapped 4-level tables, no higher-half, no demand paging,
+no guard pages.  `paging.rs` provides identity map/unmap/query helpers.  At
+boot the kernel runs on UEFI's tables; `adopt_tables()` rebuilds that map
+into the kernel's own tables and switches CR3 — needed because UEFI maps its
+page-table pages read-only, so the firmware tree can't be modified in place.
+Firmware large pages (2 MB / 1 GB) are split into 4 KB tables on demand;
+page-table pages come from the physical page allocator.
 
 ## Physical memory
 
 Before `ExitBootServices`, the kernel reads the UEFI memory map to know
-which physical regions are free.  Post-`ExitBootServices`, a simple physical
-page allocator (bitmap or free-stack) manages free pages.  A bump allocator
-serves as the initial kernel heap.
+which physical regions are free.  The heap is a first-fit **free-list
+allocator** with splitting and coalescing: blocks carry a 16-byte header
+(size + free flag), free blocks are linked in address order, and an 8-byte
+back-pointer before each payload lets `free` find its block even when
+alignment left a gap.  When the free list is exhausted, the heap **grows**
+by taking pages from the page allocator (proportional to the request),
+keeping the two allocators cooperating.  A **bitmap page allocator** manages
+physical pages: one bit per 4 KB page spanning the conventional regions, so
+MMIO holes and firmware-reserved gaps are never handed out, and the heap
+region itself is reserved to keep the allocators from double-allocating the
+same RAM.  Contiguous runs with power-of-two alignment are supported
+(`alloc_pages_aligned`).
 
 ## Input strategy
 
@@ -79,7 +92,9 @@ Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
 - `uefi.rs` — UEFI protocol type definitions
 - `serial.rs` — UART 16550 driver
 - `paging.rs` — identity page table helpers
-- `memory.rs` — physical page allocator + heap
+- `memory.rs` — UEFI memory map, free-list heap allocator (grows from page
+  allocator), bitmap page allocator
+- `paging.rs` — identity page-table helpers (map/unmap/query, large-page split)
 - `gop.rs` — framebuffer access and text rendering
 - `font.rs` — 8×16 bitmap font data
 - `ps2.rs` — PS/2 keyboard driver (polling)
@@ -94,6 +109,14 @@ Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
 ✅ **Framebuffer** — GOP located, 8×16 bitmap font renders text
 ✅ **Keyboard** — PS/2 polling, scancode set 1, US QWERTY
 ✅ **Shell** — commands: `help`, `echo`, `clear`, `hello`, `info`, `mem`, `halt`
+✅ **Heap allocator** — first-fit free-list with splitting + coalescing, `alloc`/`free`
+  (boot-time self-test verifies alignment, reuse, and full coalescing)
+✅ **Physical pages** — bitmap allocator over conventional regions, contiguous
+  runs, heap reservation, page-0 trap guard (boot-time self-test included)
+✅ **Paging helpers** — identity map/unmap/query, 2 MB/1 GB large-page split,
+  own tables adopted at boot (boot-time self-test included)
+✅ **Heap growth** — heap expands into the page allocator when exhausted
+✅ **Shell** — `mmap` dumps the UEFI map, `stress` exercises alloc/free + growth
 
 ## Target audience
 
-- 
cgit v1.2.3