reclaiming uefi memory

docs/frame-allocator.md

@@ -100,12 +100,25 @@ The `free frames` MiB agreeing with the memory map's `usable RAM`, the three
 distinct consecutive addresses, and the count returning to its start after freeing
 are the three signals that init, alloc and free are all correct.
 
+## Boot-services memory comes pre-reclaimed
+
+The UEFI boot-services memory (~44 MiB) is defunct and free once
+`ExitBootServices` runs, taking usable RAM from ~76 MiB up to ~121 MiB. The frame
+allocator does **nothing special** to get it: the loader already classified it as
+`usable` (see [memory-map.md](memory-map.md)), so it's just part of the `usable`
+regions `init` frees. Keeping that boot-protocol knowledge on the loader side is
+deliberate — the kernel has no notion of "reclaimable" or of UEFI at all.
+
+The one live piece in that memory is the boot stack the kernel starts on; the loader
+leaves the single region containing it `reserved`, so `init` won't hand it out. A
+later step will move task 0 onto a kernel-owned stack, freeing that last ~1 MiB
+region too (and giving user mode the clean stack it wants).
+
 ## What's next (not done here)
 
 - **Contiguous allocation** — scan for N consecutive free bits — for callers that
   need physically adjacent frames.
-- **Consumers**: the virtual memory manager / page tables and then the kernel heap
-  will be the first real users, each asking `alloc()` for frames.
-- **Reclaiming `reclaimable`** (UEFI boot-services) memory, and eventually the
-  `reserved` `loader_data` (kernel image, boot buffers) once nothing needs it —
-  see the deferred list in [memory-map.md](memory-map.md).
+- **A kernel stack for task 0**, so the boot stack's region can be freed too (and
+  for the clean stack user mode wants).
+- **Freeing the `reserved` `loader_data`** (the boot-time map buffers) once the
+  kernel is done reading the memory map.

docs/memory-map.md

@@ -32,8 +32,7 @@ Defined in `src/root.zig`, the shared loader↔kernel contract:
 ```zig
 pub const MemoryKind = enum(u32) {
     usable,       // free RAM the kernel may allocate
-    reserved,     // firmware / kernel image — real RAM, but never hand out
-    reclaimable,  // usable once boot-time structures are done with
+    reserved,     // firmware / kernel image / boot stack — real RAM, never hand out
     acpi_tables,  // parse, then reclaim
     acpi_nvs,     // preserve across sleep
     mmio,         // device registers / reserved address space — not RAM at all
@@ -72,11 +71,19 @@ pub const BootInfo = extern struct {
 Two functions in `src/efi.zig`, called from `exitBootServices`:
 
 - **`classify`** maps each UEFI descriptor to a `MemoryKind`:
-  `conventional_memory → usable`; `boot_services_code`/`boot_services_data →
-  reclaimable` (free once we've exited); `acpi_reclaim_memory → acpi_tables`;
-  `acpi_memory_nvs → acpi_nvs`; **everything else → reserved** (the safe default).
-  Our own `loader_data` — the kernel image and these buffers — falls into
-  `reserved`, so it won't be handed out until the kernel deliberately reclaims it.
+  `conventional_memory` **and** `boot_services_code`/`boot_services_data → usable`;
+  `acpi_reclaim_memory → acpi_tables`; `acpi_memory_nvs → acpi_nvs`; **everything
+  else → reserved** (the safe default). Our own `loader_data` — the kernel image and
+  these buffers — falls into `reserved`.
+
+  Folding boot-services memory into `usable` is deliberate: we've already called
+  ExitBootServices, so it's free RAM now, and doing the classification *here* (in
+  the loader) means the kernel never learns about a UEFI-specific "reclaimable"
+  state — it just sees usable RAM. The one catch is that our stack lives in
+  boot-services memory and the kernel starts out running on it, so
+  `convertMemoryMap` keeps the single region containing the current stack pointer
+  `reserved`. All the boot-protocol knowledge stays on the loader side of the
+  boundary; the kernel's frame allocator has no idea any of this happened.
 
   One subtlety: **a region that isn't writeback-cacheable (the descriptor's `wb`
   attribute) is classified `mmio` regardless of type.** UEFI overloads
@@ -126,18 +133,17 @@ for (regions) |r| {
 ```
 danos: physical memory
   total RAM  : 0.12 GiB (127 MiB) - RAM the firmware reported
-  usable     : 77 MiB - free now; owned by the frame allocator
-  reclaimable: 44 MiB - UEFI boot-services memory, free after exit
-  reserved   : 6 MiB - kernel image, ACPI, runtime services
-  regions    : 35 - entries in the firmware memory map
+  usable     : 121 MiB - free RAM (incl. reclaimed boot-services memory)
+  reserved   : 6 MiB - kernel image, boot stack, ACPI, runtime services
+  regions    : 28 - entries in the firmware memory map
 ```
 
-The `usable` figure is only ~77 of ~127 MiB because most of the rest is
-`reclaimable` boot-services memory — real RAM we'll take back once we implement
-reclaiming, not memory that's gone. `total` counts only writeback-cacheable RAM,
-so the ~12 GiB PCIe address hole is excluded (it's `mmio`), and the three RAM
-categories summing back to the firmware's total is the sanity check that nothing
-was dropped.
+`usable` is ~121 of ~127 MiB because the loader already folded the boot-services
+memory into it — so the frame allocator gets it all with no special step. The ~6 MiB
+`reserved` is the kernel image, the boot stack's region, ACPI, and runtime services.
+`total` counts only writeback-cacheable RAM, so the ~12 GiB PCIe address hole is
+excluded (it's `mmio`), and the RAM categories summing back to the firmware's total
+is the sanity check that nothing was dropped.
 
 ## How Raspberry Pi will fit
 
@@ -150,11 +156,13 @@ never knows the difference.
 ## What's next
 
 This page is plumbing plus classification only. The map's first consumer, the
-**physical frame allocator**, is built directly on the `usable` regions here —
-see [frame-allocator.md](frame-allocator.md). Still to come after that:
+**physical frame allocator**, is built directly on the `usable` regions here — which
+already include the reclaimed boot-services memory the loader folded in (see
+[frame-allocator.md](frame-allocator.md)). Still to come:
 
-- Reclaiming `reclaimable` regions, and carefully freeing `reserved` `loader_data`
-  (kernel image, these buffers) once the kernel is done reading them.
-- Paging / the kernel's own page tables, then a heap.
+- Freeing the `reserved` `loader_data` (these boot-time buffers) once the kernel is
+  done reading the map.
+- Capturing the ACPI RSDP from the UEFI configuration table before exit (the same
+  "grab it before ExitBootServices" pattern), for when ACPI parsing arrives.
 
 See the roadmap in [efi.md](efi.md) for where this sits in the boot flow.