Capabilities · 2 of 7
How one slot names a block of memory
A capability to memory does not name a page. It names an aligned block of pages, so one slot of a process’s table can cover anything from 4 KiB to the whole address space.
A slot names a block, not a page
A capability that names memory names a block: a base address and a number of pages that is a power of two, the power being the capability’s order. The base is aligned to the block’s size, and the block lies inside the address space. The table does not list the block’s pages, so a block of a million pages takes the same one slot as a block of one.11 The design record is capability-names-a-block. In table.rs, block_bytes is the size an order names and payload_wf keeps the base aligned and the block in bounds.
Four kinds name no memory: a device, the console, power and a processor core. Each names an object outside the address space, so no memory capability covers it.
How many slots a table holds
A process keeps its capabilities in a table of two levels. The root is the first page of the process object and holds 512 pointers. A new process’s root points at nothing, so it starts with no slots at all.22 TableRoot in table.rs; its 512 entries are ROOT_ENTRIES, which is ENTRIES in define.rs.
Slots arrive in leaves. A leaf is a block of two pages, 8 KiB, retyped from untyped memory into an empty root entry. Its first page holds 128 list nodes and its second holds 128 payloads, the same position on each page making one slot. The first node of every leaf is reserved as the leaf’s own hidden node, so a leaf has 127 slots and a full table, with a leaf under every root entry, has 512 × 127 = 65,024.33 A leaf is LEAF_BYTES in table.rs, and the 128 nodes a page holds are NODES_PER_PAGE in list.rs. index_ok excludes each leaf’s first node.
An index into the table picks a root entry and a position inside that entry’s leaf. The slot is the node and the payload at that position, and the payload names the block.
What one slot holds
The node is the capability’s place in the depth-first list that revoke walks: whether it is live, its kind, its depth, and the links to the nodes before and after it. A node does not store its parent; a node’s children are simply the deeper run after it. The payload says what the capability is: its kind, its order, its rights, its base, a badge, and, for a processor core, the highest priority a thread placed through it may run at.44 Node is in list.rs and Payload in table.rs. Each is 32 bytes, so 128 fit on a 4 KiB page.
Finding a slot is a fixed number of loads, with no search: the root, the leaf pointer in it, the leaf’s hidden node, and the payload. An index from user space is checked first, and one past the end of the table, or naming a leaf’s hidden node, is refused.55 Tables::lookup in table.rs.
The sizes a block can take
Untyped memory may take any order up to 36. A child cut from it may take any lower order, as long as it names a whole aligned block inside its parent. Whether a cut fits is decided in constant time.66 block_within and is_block_within in derive.rs.
A frame, the memory a process maps, is retyped at one of the sizes the page table maps: one page of 4 KiB, or a large frame of 2 MiB, order 9. The kernel’s retype accepts 1 GiB, order 18, as well, but the system call does not yet ask for it; that size waits until the page table can map it. A frame can then derive children of any lower order inside it, down to one page, and each child takes a slot of its own while the frame’s own slot stays one slot.77 can_retype_frame and can_retype_large in retype.rs, and the arms of allows_retype in operation.rs.
Retype takes those three sizes, and not any order, because the kernel’s page metadata can check whether a block is free in one read at 4 KiB, 2 MiB and 1 GiB. A range that was not a power of two would lose that. Deriving pieces of a larger frame, rather than holding one capability per page, keeps a pager’s slot count proportional to what it has handed out.88 The design records capability-names-a-block and teardown-driven-by-retype.
The largest block is the whole address space
An order-36 block is 236 pages of 4 KiB, which is 256 TiB: exactly the 48-bit address space. One untyped capability of that order, based at address zero, names every byte the space holds, and the kernel’s invariant accepts it. So the number of slots a process holds does not bound how much memory it can hold; the next pages show where the count does bind.99 MAX_ORDER in table.rs and NODE_SPACE in list.rs.
Numbers on this page are from kernel commit 31399c5, 17 November 2026.