Capabilities · 7 of 7
How boot hands out all free memory
Boot is the only time the kernel hands memory out. It gives the first process the machine’s free memory as untyped capabilities, and because each one names an aligned block, the machine’s memory fits in a fixed number of slots.
One handout
After boot the kernel allocates nothing. Every page a process will ever reach comes through a capability the root process was given at boot, or one derived from those. So boot has to describe all free memory in the root’s table, which is fixed in size, and it can, because one untyped capability names a whole aligned block of 2order pages.11 kernel_init in boot_kernel.rs. The design records are untyped-memory, capability-names-a-block and root-process-at-boot. In order, boot:
- checks the memory map the loader passes,
- sets aside the memory it keeps for itself and the root,
- breaks each remaining free run into aligned blocks,
- keeps the largest blocks, as many as the root has slots for, as untyped capabilities,
- and hands the root’s own program image over as frame capabilities.
The map is checked, then boot sets aside what it keeps
The loader passes the firmware’s free physical runs, and this is a trust boundary: the kernel checks them before anything verified sees them. Boot stops, naming the address, if a range is empty, is not aligned to a 4 KiB page, runs past the end of the address space or past the memory the kernel maps, overlaps another range, or claims memory inside the kernel’s image or the root’s reserved range. The root’s own loaded pieces get the same treatment.22 free_page_ranges in free_ranges.rs and mapped_runs in mapped_runs.rs. This code is outside the proof, and the design record trust-boundary places it.
Boot then takes what no untyped capability will cover. The lowest free stretch that is long enough holds the root’s process, its first table leaves, its thread, and the capability kernel’s own state. The page metadata, sized from the memory map, goes at the lowest address that fits clear of everything else. Every 2 MiB region the root’s image touches is kept too. What remains is what the root can receive.33 aligned_stretch in capability.rs and carve in free_ranges.rs. The design record for the metadata is page-metadata-sized-from-the-memory-map.
A free run becomes aligned blocks
One rule breaks a run into blocks. Starting from the run’s first page, take the largest order the page is aligned to that still fits in the pages left, up to order 36; that block is one capability. Then start again at the page after it.44 order_below and run_blocks in decompose.rs.
A run of 13 pages starting at page 3, in page units, for illustration. Page 3 is aligned to nothing larger than one page. Page 4 is aligned to four pages, and four fit. Page 8 is aligned to eight, and the eight pages left are exactly that. Three blocks cover the run.
The kernel proves that any run inside the pages it tracks breaks into at most 74 blocks. The root has 91 slots for untyped memory, so a single run always fits. Several runs together can need more.55 lemma_run_blocks in decompose.rs.
The largest blocks take the slots
The untyped capabilities go in the root’s first leaf, after the capabilities for its own process, its thread, the console, power and the processor cores: slots 37 through 127, which is 91.66 ROOT_UNTYPED_SLOT in boot.rs and ROOT_UNTYPED_SLOTS in boot_memory.rs. Boot breaks every remaining run into blocks and keeps the largest, biggest order first, at most 91 of them. What is left unused is the small fragments at the edges of runs. Each kept block carries only the retype right.
For instance, 91 runs of three pages each break into 182 blocks: 91 of two pages and 91 of one. Boot keeps the 91 two-page blocks and leaves 91 single pages unused.
The choice of blocks is made by unverified code; the verified step that places them checks the count. Given more blocks than slots, or none at all, it refuses and changes nothing, and boot stops with “the capability kernel refused the boot memory or root’s runs”. So the unverified selection keeps a real boot inside the slots, and the proof guarantees that a list that does not fit is never half-placed.77 largest_blocks in capability.rs chooses; boot_root_memory in boot_memory.rs places or refuses.
The first and largest block also pays for the root’s page tables: boot retypes eight-page pieces of it into the table pages that map the root’s image.88 untyped_tables and boot_root_tables in boot_table.rs. The design record is address-spaces-as-objects.
The root’s image arrives as frames
The root’s program image sits in memory boot reserved, so no untyped capability covers it. Instead each loaded piece is broken into blocks by the same rule, capped at 2 MiB so that each block lies inside one large page, and each block becomes one frame capability. A frame carries read, plus write and execute where the loader mapped the piece that way, and never the control right.99 image_blocks, IMAGE_ORDER and image_rights in boot_image.rs.
The frames fill the root’s second leaf, slots 129 through 255, 127 in all, and boot refuses an image that needs more. It also refuses one whose virtual addresses stray into the kernel’s part of the address space, or whose page tables would need more than the first untyped block can pay for.1010 ROOT_FRAME_SLOT and boot_root_image in boot_image.rs; image_virt_wf and image_tables_bound in boot_table.rs.
When boot finishes, the root holds the machine’s free memory, less the fragments at the edges of runs, in at most 91 capabilities, and its own image in at most 127 more. From there on, everything any process holds was derived or retyped from those.
Numbers on this page are from kernel commit 31399c5, 17 November 2026.