danos/docs/frame-allocator.md

# The physical frame allocator

Once the kernel knows what RAM exists ([memory-map.md](memory-map.md)), it needs a
way to *hand out* that RAM: give me a free page of physical memory, and later,
here's one back. That's the **physical frame allocator** (a "physical memory
manager", hence `src/pmm.zig`). It deals only in fixed 4 KiB **frames** — the
natural unit because that's the granularity the CPU's paging hardware maps — and
it is the primitive everything above it stands on: page tables, the kernel heap,
per-process memory all ultimately ask the frame allocator for pages.

It's **generic kernel code**: it operates on the neutral `danos.MemoryRegion`
array, so there's no UEFI in it and nothing architecture-specific beyond the 4 KiB
page. (Contrast [arch.md](arch.md), which is where CPU-specific code lives.)

## Why a bitmap

There are a few classic designs; danos starts with the simplest that still
supports freeing:

- **Bitmap** (chosen): one bit per frame, `1 = used`, `0 = free`. Freeing is
  trivial (clear a bit), it's very compact, and you can later extend it to
  allocate *contiguous* runs by scanning for consecutive zero bits. Allocation is
  a linear scan, but that's cheap and easy to reason about.
- **Intrusive free-list / stack**: store the "next free frame" pointer inside each
  free frame; O(1) alloc and free. Elegant, but it can't satisfy contiguous
  multi-frame requests and can't answer "is *this* frame free?".
- **Buddy allocator**: great for contiguous power-of-two blocks, but more
  machinery than a first allocator needs.

Compactness matters less than clarity here, but it's a nice property: 128 MiB of
RAM is 32768 frames — a **4 KiB bitmap, a single frame**. Even 64 GiB needs only
2 MiB of bitmap.

## How it works

State lives in `src/pmm.zig`: the `bitmap` slice, `total_frames`, `used_frames`,
and a `next_hint` marking where the next allocation scan should start.

### init(map) — building it from the memory map

1. **Size it.** Find the highest address across all `usable` regions;
   `total_frames = highest / page_size`. Reserved and MMIO spans above that
   (remember the ~12 GiB of MMIO from [memory-map.md](memory-map.md)) sit *outside*
   the bitmap and are simply never allocatable.
2. **Place it (the bootstrap).** The bitmap needs storage before an allocator
   exists — a chicken-and-egg. Solution: pick the first `usable` region big enough
   to hold the bitmap and put it there, addressing it directly as a pointer. That
   last part relies on the firmware's **identity mapping** still being in effect
   (physical address == virtual address), which holds until the kernel installs
   its own page tables.
3. **Mark, then free.** Set the whole bitmap to `used` (`0xff`), then walk the
   `usable` regions clearing their bits. Doing it in that direction means every
   gap, reserved span, and hole is unallocatable *by default* — we only ever hand
   back memory the firmware explicitly called usable.
4. **Take back the essentials.** Re-reserve the frames the bitmap itself occupies
   (they're inside a usable region we just freed), plus **frame 0**, so an address
   of `0` can keep meaning "no frame".

### alloc() → ?u64

Scan the bitmap from `next_hint` (wrapping once) for the first free bit, mark it
used, advance the hint, and return `frame * page_size`. Returns `null` when no
frame is free — genuine out-of-memory. The hint avoids rescanning the low,
long-since-allocated frames on every call.

### free(addr)

Clear the frame's bit and, if it's below `next_hint`, pull the hint back so the
reclaimed frame gets reused soon. Bogus or double frees (a frame already marked
free, or one out of range) are ignored rather than corrupting the used count.

## Correctness points worth remembering

- **Generic walk.** Because `MemoryRegion` is danos's own type, the map is a plain
  slice — none of the variable descriptor-stride from the raw UEFI map.
- **Identity mapping assumption.** Placing the bitmap by physical address only
  works while the firmware's identity map is live. When danos sets up its own
  paging, the bitmap (and any other physical pointer) will need an explicit
  mapping. This is a deliberate, documented dependency of this stage.
- **Frame 0 is reserved** so `0` stays a safe "none" sentinel — and the bitmap is
  never placed there. (An early bug did exactly that: a `usable` region at physical
  address 0 collided with a `0`-means-not-found sentinel and tripped a panic. The
  fix was an optional plus starting the bitmap at least one page in.)
- **Everything non-usable is unallocatable by construction** — the "mark all used,
  then free usable" order gives that for free, so the kernel image, the loader's
  buffers, MMIO and firmware memory can never be handed out.

## Verifying it

`kmain` brings the allocator up and self-tests it. Booted in QEMU with 128 MiB:

```
danos: frame allocator online
  free frames: 19751 (77 MiB)      <- matches the map's 77 MiB usable
  alloc x3   : 0x2000 0x3000 0x4000 <- frame 0 reserved, bitmap at 0x1000, so allocs start at 0x2000
  after free : 19751 frames free    <- three freed, count restored
```

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.

## 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).