nub_program/abi.rs
1//! PVM2 guest virtual-address-space layout (ABI constants).
2//!
3//! These constants define where a linked program's code and data
4//! regions map in the guest's 32-bit address space. They are part of
5//! the PVM2 ABI contract: the linker bakes `PC = CODE_BASE +
6//! byte_offset` into endpoint entry PCs and native `auipc`/`jalr`
7//! resolution and lays data regions from [`DATA_BASE`] up, and every
8//! runtime maps code read-only at [`CODE_BASE`] and data at
9//! [`DATA_BASE`].
10//!
11//! Code placement is a fixed protocol constant rather than a
12//! program-supplied mapping entry: an untrusted program must not get
13//! to choose where its code lands.
14//!
15//! ```text
16//! [0, CODE_BASE) unmapped — NULL guard (catch PC=0 / null deref)
17//! [CODE_BASE, DATA_BASE) CODE — RO, ≤ MAX_CODE_SIZE bytes
18//! [DATA_BASE, 4 GiB) DATA — stack / ro / rw / heap, RO|RW
19//! ```
20//!
21//! Code low (4 MiB) gives the null guard; data high (256 MiB) keeps the
22//! whole data region contiguous above code instead of wrapping around
23//! it. Both `[0, CODE_BASE)` and `[CODE_BASE + code, DATA_BASE)` are
24//! unmapped, so a stray fetch or load there faults.
25
26/// Guest virtual address where the (single) code region maps read-only.
27/// A PVM PC is `CODE_BASE + byte_offset`. Sits at 4 MiB so `[0, 4 MiB)`
28/// is an unmapped null guard.
29pub const CODE_BASE: u32 = 0x0040_0000;
30
31/// Guest virtual address where the data region begins. All data regions
32/// (stack / ro / rw / heap) and instance overlays live in `[DATA_BASE,
33/// 4 GiB)`. At 256 MiB, well clear of the largest permitted code region.
34pub const DATA_BASE: u32 = 0x1000_0000;
35
36/// Maximum byte length of the code region. Code occupies `[CODE_BASE,
37/// CODE_BASE + code_len)` and must stay below `DATA_BASE`, so
38/// `code_len ≤ DATA_BASE − CODE_BASE` = 252 MiB.
39pub const MAX_CODE_SIZE: u32 = DATA_BASE - CODE_BASE;
40
41/// PVM page size in bytes. Every region is a whole number of pages.
42pub const PAGE_SIZE: u32 = 4096;
43
44/// PVM register index holding the RISC-V stack pointer (φ\[1\] = x2).
45/// The linker seeds it with [`Regions::stack_top`] in every endpoint's
46/// `initial_regs`.
47///
48/// [`Regions::stack_top`]: crate::Regions::stack_top
49pub const SP_REG: u8 = 1;
50
51/// One past the highest guest address: the 4 GiB limit of the 32-bit
52/// PVM2 address space.
53pub const ADDRESS_SPACE_END: u64 = 1u64 << 32;