135 lines
7.2 KiB
Markdown
135 lines
7.2 KiB
Markdown
# 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 `system/kernel/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 `boot_handoff.MemoryRegion`
|
|
array, so there's no UEFI in it and nothing architecture-specific beyond the 4 KiB
|
|
page. (Contrast [architecture.md](architecture.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 `system/kernel/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 RAM regions — every kind
|
|
*except* `mmio` — so reserved and ACPI spans sit *inside* the bitmap, marked
|
|
used but trackable (e.g. so the boot buffers can be freed later);
|
|
`total_frames = highest / page_size`. Only MMIO (device address space —
|
|
remember the ~12 GiB of it from [memory-map.md](memory-map.md)) sits outside
|
|
the bitmap and is 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 through the **physmap**
|
|
(`boot_handoff.physicalToVirtual`). The loader's bootstrap page tables already
|
|
provide the physmap and the kernel's own tables keep it, so the pointer stays
|
|
valid across the paging switch.
|
|
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.
|
|
- **Physmap addressing.** The bitmap (and the region array) is reached through
|
|
the physmap via `boot_handoff.physicalToVirtual`, which both the loader's
|
|
bootstrap tables and the kernel's own tables provide — no remapping is needed
|
|
when danos switches to its own paging. The one invariant: the bitmap must sit
|
|
under the bootstrap physmap's reach (4 GiB), which holds because the placement
|
|
scan (step 2 above) runs from the lowest usable region up and takes the first
|
|
one big enough — on the supported configurations that lands well under 4 GiB.
|
|
- **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:
|
|
|
|
```
|
|
/system/kernel: frame allocator online
|
|
free frames: 30520 (119 MiB) <- matches the map's 119 MiB usable
|
|
alloc x3 : 0x3000 0x4000 0x5000 <- frame 0 reserved, bitmap at 0x1000, AP trampoline at 0x2000
|
|
after free : 30520 frames free <- three freed, count restored
|
|
```
|
|
|
|
(The AP-trampoline page is claimed with `allocBelow` right after `init`, before
|
|
the demo allocations — hence they start at 0x3000.)
|
|
|
|
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 ~119 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 (partly done since)
|
|
|
|
- **Contiguous allocation** — done: `allocContiguous` scans for a run of clear
|
|
bits, with an optional physical ceiling for DMA (`dma_alloc` is its user), and
|
|
`allocBelow` serves the SMP trampoline.
|
|
- **A kernel stack for task 0** — still open: the boot processor's idle task runs
|
|
on the boot stack to this day, so that region can't be freed.
|
|
- **Freeing the `reserved` `loader_data`** (the boot-time map buffers) — still
|
|
open: the bitmap deliberately tracks those frames so they *can* be freed, but
|
|
nothing frees them yet.
|