Orus

Capabilities · 3 of 7

How one frame backs many mappings

Mapping memory names a frame capability and a page offset inside its block. Each mapping is an entry in a page table, not a capability, so one slot can back every page a process maps from that frame.

What one map writes

A map names five things: the address space to write, the virtual address, the level of the page table, the frame capability, and a page offset inside the frame’s block. It writes one page-table entry pointing at that page of the block. The entry is where the per-page state lives, so the map takes no slot.11 CapKernel::map_at in map.rs, reached from the system call through invoke_map in operation.rs. The register positions are in the design record syscall-abi-in-registers.

The space is named through a process capability with the control right, since a process’s address space is part of the process. The frame must be a live capability in the caller’s own table with the read right, and the offset must lie inside its block. Addresses the kernel keeps for itself in every space are refused.22 may_write_space and is_kernel_slot in link.rs; can_map in map.rs.

Two levels can be written. At the lowest, one entry maps one 4 KiB page. At the next, one entry maps 2 MiB, 512 pages, from an offset that is a multiple of 512. A level whose entry would span 1 GiB is not written: there is no mapping of a whole 1 GiB block yet.

The map records itself as a mapping node, a child of the frame capability in the depth-first list, so revoking the frame reaches every mapping made through it, in any process’s address space. The node is not a capability and fills no slot; it lives inside the page-table page’s own block. It does hold a reference on the frame’s block, which keeps the block from being retyped while it is mapped, and a map that would pass the reference limit is refused and changes nothing.33 is_cap in table.rs counts only live capabilities. lemma_mapping_node_place in mapping.rs places the node, and holders_wf in refs.rs counts it as a holder of the block.

One frame capability names a block of eight pages. Three entries of a page table map pages of that block: one maps the first page and two map the fourth. The capability takes one slot; the table page and its entries take none. frame capability one slot page-table page offset 0 offset 3 offset 3 typed from untyped: no slot the frame’s block page 0 page 1 page 2 page 3 page 4 page 5 page 6 page 7 the capability names the whole block

The same offset can be mapped into more than one entry, and each entry adds its own reference. A different offset is a different page of the same block. However many entries there are, the frame is still one slot.

How many mappings one frame backs

A frame backs one 4 KiB mapping for each page of its block, and one 2 MiB mapping for each aligned 512 pages, when its order is one the large map accepts.44 can_map_large in map.rs accepts order 9 and order 18 only.

FrameOrder4 KiB mappings2 MiB mappings
4 KiB01none
2 MiB95121
1 GiB18262,144512

The last row is what the map would admit. The system call does not yet retype a 1 GiB frame, so no process holds one today.

A frame of any other order backs as many 4 KiB mappings as it has pages, and no 2 MiB mapping. That covers a smaller piece derived from a larger frame, and a block of the root’s boot image cut below 2 MiB. Deriving such a piece takes a slot of its own; mapping a page of a frame already held takes none.55 block_within in derive.rs and image_blocks in boot_image.rs. Why a derived piece is its own slot is in sharing-by-derive.

The page table holds no slot either

Whoever maps pays for the page table, out of untyped memory they hold. A page-table page is retyped as a 32 KiB block, order 3, and the retype names the untyped, a base and a level, and no destination slot. The new page is recorded as a hidden node under the untyped, so revoking the untyped reaches it, but it is not a capability. It starts empty, and a separate link writes it into the space; after that, maps write its entries.66 CapKernel::retype_table_page in space.rs, where TABLE_PAGE_BYTES is the block’s size, and link_at in map.rs. The design record is address-spaces-as-objects.

So a process that maps a great deal of memory holds one slot per frame, however many pages it maps from each, and none for the tables that map them.

Numbers on this page are from kernel commit 31399c5, 17 November 2026.