Capabilities · 4 of 7
What takes a slot, and what does not
A process’s table fills with the capabilities it holds, not with the memory they cover. Mapping pages and building page tables take no slot; grants, the objects a process creates, and the frames a pager cuts up front do.
Takes one slot
- A capability derived for someone, while it stays in the deriver’s table
- A capability moved in from another table, which leaves the other slot empty
- A frame retyped from untyped memory, of 4 KiB or 2 MiB
- A thread or a process the caller creates
- An endpoint, a notification, a reply or an address space
Takes none
- Mapping a page of a frame already held, however many times
- A page-table page
- A leaf of the table itself, which adds 127 slots
- Mapping into a device’s address space
Boot fills the root process’s table with what it starts with; how it fits all of free memory in is the last page of this section. This page is about what a process fills afterwards.11 The design record root-process-at-boot lists what boot places, and boot.rs places it.
What takes no slot
A mapping names a frame capability and a page offset, so one capability covers every page of its block, and the map adds a mapping node rather than a capability. How one frame backs many mappings covers it in detail.
A page-table page is paid for by whoever maps, out of untyped memory they hold, and its retype names no destination slot.22 CapKernel::retype_table_page in space.rs. The design record is address-spaces-as-objects.
A leaf is how a table gains slots, and no capability names it. Retyping one into a root entry of the caller’s table, or of a live process the caller controls, creates 127 slots rather than spending one. The leaf’s hidden node is a child of the untyped it came from, so revoking that untyped takes the leaf back.33 CapKernel::retype_leaf in retype.rs.
A device mapping grants what a device’s address space maps to whoever can see that space, and also fills no slot. The kernel proves it, but no system call reaches it yet.44 CapKernel::map_device in device_space.rs. invoke_map calls only map_at.
Where a shared capability lands
Derive is the only way to share a capability, and the child takes a slot wherever it is put: in the deriver’s own table, or in a live process the deriver holds a control capability to. In either table the child stays its parent’s child, so the deriver can revoke it. Its rights and its block lie inside its parent’s, which is how one frame hands out a smaller piece for one slot.55 CapKernel::derive in derive.rs, with narrows and block_within. A destination is a Position in position.rs. The design record is sharing-by-derive.
The design has one more place a child can land: a slot the receiver names, in a grant over an endpoint. The kernel’s model of reach includes that delivery, but the system calls that would carry it, send, receive, call and reply, are refused today and change nothing. Until they land, a server with no control over its client keeps each child it derives in its own table, one slot per grant.66 Effect::Deliver in reach.rs. The operation numbers are in operation.rs, and CapKernel::dispatch answers them with STATUS_REFUSED.
A move fills its destination and empties its source, so it adds no capability. A move into a controlled process’s table is refused if that process is dead, since nothing is given to a process that cannot use it. A move out of one succeeds even when the process is dead, which is how a supervisor claims a dead service’s capabilities.77 CapKernel::move_cap in moving.rs.
Objects that take one slot each
Creating an object retypes a block of untyped memory the caller holds, and writes the new object’s capability into an empty slot of the caller’s own table. The capability stays there until a derive or a move puts one somewhere else.88 retype_slots in retype.rs refuses a destination that is not an empty slot of the caller’s table.
- A thread is a two-page block. Its control capability is one slot, in the table of whoever created it, and the thread itself holds no slots: a process holds capabilities and its threads share them.99
CapKernel::retype_threadinthread.rs. The creator keeps the capability because the creator sets the thread’s registers and starts it, thread-bound-at-retype. - A process is an eight-page block holding its table’s root, its record and its address space. Its control capability is one slot. Its own table starts with no leaf, so it holds nothing until someone retypes a leaf into it.1010
CapKernel::retype_processinprocess.rs. - An endpoint, a notification or a reply is one page, and a device’s address space is an eight-page block; each is one slot. The kernel proves these retypes, but the system call does not reach them yet.1111
retype_endpointandretype_notificationinendpoint.rs,retype_replyinreply.rs,retype_spaceinspace.rs.invoke_retypeinoperation.rsrefuses their kinds.
A pager decides how fast the table fills
The kernel allocates nothing after boot, so a pager hands out memory by retyping frames from untyped memory it holds. One 4 KiB frame is one slot. A 2 MiB frame is one slot too, filled on the step that finishes zeroing it; until then the retype answers “again”.1212 CapKernel::retype_frame and CapKernel::retype_large_frame in retype.rs, and RetypeStep::Again. The design record is untyped-memory.
So the pager’s habits set the count. A pager that retypes a separate frame for every page before anything asks, or derives a child for every page of a frame it could map by offset, spends a slot per page. A pager that retypes when a page is asked for, and maps by offset inside frames it already holds, spends a slot per frame it has handed out. Where the budget runs out puts numbers on the difference.
This page describes kernel commit 31399c5, 17 November 2026.