Skip to main content

kh_runtime/mem/
registry.rs

1//! Guest address-space tracking for trap-path validation and dynamic maps.
2//!
3//! [`AddressSpace`] owns the region list for one guest process. Image and stack
4//! regions are registered as **borrowed** (owned by `GuestMemory` / the stack
5//! `MappedRegion`). Guest `mmap` registers **owned** regions that the space
6//! unmaps on `munmap` / `clear`.
7//!
8//! Trap handlers and BSD syscalls use a process-wide **active** address space
9//! installed before guest entry (see [`install_active`] / free-function
10//! wrappers). Unit tests can exercise a local [`AddressSpace`] without touching
11//! the active slot, or use the wrappers under [`test_lock`].
12
13use std::cell::Cell;
14use std::sync::RwLock;
15
16use crate::host;
17
18use super::map::{MappedRegion, VM_PROT_READ, VM_PROT_WRITE};
19
20/// Per-thread last hit for [`check_range`] (archive I/O is highly sequential).
21#[derive(Clone, Copy)]
22struct RangeCache {
23    guest_addr: u64,
24    len: usize,
25    prot: u32,
26}
27
28impl RangeCache {
29    fn contains(self, addr: u64, len: usize) -> bool {
30        if len == 0 {
31            return addr >= self.guest_addr
32                && addr
33                    <= self
34                        .guest_addr
35                        .saturating_add(u64::try_from(self.len).unwrap_or(u64::MAX));
36        }
37        let Some(end) = addr.checked_add(u64::try_from(len).unwrap_or(u64::MAX)) else {
38            return false;
39        };
40        let reg_end = self
41            .guest_addr
42            .saturating_add(u64::try_from(self.len).unwrap_or(u64::MAX));
43        addr >= self.guest_addr && end <= reg_end
44    }
45
46    fn allows(self, need_write: bool) -> bool {
47        if need_write {
48            self.prot & VM_PROT_WRITE != 0
49        } else {
50            self.prot & (VM_PROT_READ | VM_PROT_WRITE) != 0
51        }
52    }
53}
54
55thread_local! {
56    static LAST_RANGE: Cell<Option<RangeCache>> = const { Cell::new(None) };
57}
58
59/// One live guest mapping visible to the syscall layer.
60#[derive(Debug)]
61struct RegRegion {
62    /// Guest VA of the mapping base (identity with host in the current model).
63    guest_addr: u64,
64    /// Host mapping length in bytes.
65    len: usize,
66    /// Host base pointer.
67    ptr: *mut u8,
68    /// Darwin `VM_PROT_*` bits.
69    prot: u32,
70    /// When true, [`AddressSpace::clear`] / `munmap` will `munmap` the host pages.
71    owned: bool,
72}
73
74// SAFETY: regions are only mutated while the owning `AddressSpace` is locked
75// (active slot mutex or exclusive local borrow); pointers uniquely refer to
76// live maps for the single guest process model.
77unsafe impl Send for RegRegion {}
78
79impl RegRegion {
80    /// Exclusive end guest address (`guest_addr + len`), saturating.
81    #[must_use]
82    fn guest_end(&self) -> u64 {
83        self.guest_addr
84            .saturating_add(u64::try_from(self.len).unwrap_or(u64::MAX))
85    }
86
87    /// Whether `[addr, addr+len)` is fully contained in this region.
88    #[must_use]
89    fn contains_range(&self, addr: u64, len: usize) -> bool {
90        if len == 0 {
91            return addr >= self.guest_addr && addr <= self.guest_end();
92        }
93        let Some(end) = addr.checked_add(u64::try_from(len).unwrap_or(u64::MAX)) else {
94            return false;
95        };
96        addr >= self.guest_addr && end <= self.guest_end()
97    }
98}
99
100/// Tracked guest VA ranges for one process (borrowed images + owned mmaps).
101///
102/// Independent of the active trap slot: build and test locally, then
103/// [`install_active`] before jumping to guest code.
104#[derive(Debug, Default)]
105pub struct AddressSpace {
106    regions: Vec<RegRegion>,
107}
108
109// SAFETY: regions are only mutated under the active write lock; concurrent
110// readers only call pure range checks. Raw host pointers are not shared for
111// mutation across threads without that lock.
112unsafe impl Sync for AddressSpace {}
113
114impl AddressSpace {
115    /// Empty address space (no tracked regions).
116    #[must_use]
117    pub const fn new() -> Self {
118        Self {
119            regions: Vec::new(),
120        }
121    }
122
123    /// True when at least one region is registered.
124    #[must_use]
125    pub fn is_active(&self) -> bool {
126        !self.regions.is_empty()
127    }
128
129    /// Clears all regions. Owned mappings are `munmap`'d; borrowed ones are not.
130    pub fn clear(&mut self) {
131        for region in self.regions.drain(..) {
132            if region.owned {
133                let _ = host::munmap(region.ptr, region.len);
134            }
135        }
136    }
137
138    /// Registers a borrowed region (image / stack). Does not take ownership.
139    pub fn register_borrowed(&mut self, region: &MappedRegion) {
140        self.regions.push(RegRegion {
141            guest_addr: region.guest_addr,
142            len: region.host_len(),
143            ptr: host_ptr_from_addr(region.host_addr()),
144            prot: region.prot,
145            owned: false,
146        });
147    }
148
149    /// Registers an owned mapping created by a guest `mmap`.
150    pub fn register_owned(&mut self, guest_addr: u64, ptr: *mut u8, len: usize, prot: u32) {
151        self.regions.push(RegRegion {
152            guest_addr,
153            len,
154            ptr,
155            prot,
156            owned: true,
157        });
158    }
159
160    /// Validates that `[addr, addr+len)` lies in a registered region with the
161    /// requested access. When empty (unit tests without maps), returns `true`
162    /// so pure dispatch tests do not need a full map setup.
163    #[must_use]
164    pub fn check_range(&self, addr: u64, len: usize, need_write: bool) -> bool {
165        if len == 0 {
166            return true;
167        }
168        if addr == 0 {
169            return false;
170        }
171        if self.regions.is_empty() {
172            return true;
173        }
174        for region in &self.regions {
175            if !region.contains_range(addr, len) {
176                continue;
177            }
178            if need_write {
179                return region.prot & VM_PROT_WRITE != 0;
180            }
181            // Readable if any of R/W is set (writable maps are readable for load).
182            return region.prot & (VM_PROT_READ | VM_PROT_WRITE) != 0;
183        }
184        false
185    }
186
187    /// Finds the region that fully contains `[addr, addr+len)`, if any.
188    #[must_use]
189    pub fn find_covering(&self, addr: u64, len: usize) -> Option<RegRegionSnapshot> {
190        for region in &self.regions {
191            if region.contains_range(addr, len) {
192                return Some(RegRegionSnapshot {
193                    guest_addr: region.guest_addr,
194                    len: region.len,
195                    ptr: region.ptr,
196                    prot: region.prot,
197                    owned: region.owned,
198                });
199            }
200        }
201        None
202    }
203
204    /// Updates protection bits on the region covering `addr`.
205    pub fn update_prot(&mut self, addr: u64, len: usize, prot: u32) -> bool {
206        for region in &mut self.regions {
207            if region.contains_range(addr, len) {
208                region.prot = prot;
209                return true;
210            }
211        }
212        false
213    }
214
215    /// Removes and optionally unmaps an owned region that fully covers the range.
216    ///
217    /// Borrowed regions are removed from tracking **without** `munmap`.
218    pub fn remove_range(&mut self, addr: u64, len: usize) -> RemoveOutcome {
219        let idx = self
220            .regions
221            .iter()
222            .position(|r| r.contains_range(addr, len));
223        let Some(i) = idx else {
224            return RemoveOutcome::NotFound;
225        };
226        let region = self.regions.remove(i);
227        if region.owned {
228            if host::munmap(region.ptr, region.len) {
229                RemoveOutcome::Unmapped
230            } else {
231                RemoveOutcome::UnmapFailed
232            }
233        } else {
234            RemoveOutcome::Untracked
235        }
236    }
237
238    /// Test/helper: push a raw region (used by unit tests for RX-only maps).
239    #[cfg(test)]
240    fn push_raw(&mut self, region: RegRegion) {
241        self.regions.push(region);
242    }
243}
244
245impl Drop for AddressSpace {
246    fn drop(&mut self) {
247        self.clear();
248    }
249}
250
251/// Active address space for the trap / syscall path (single guest process).
252///
253/// `RwLock`: concurrent `check_range` on the I/O hot path must not serialize
254/// all guest threads behind a single exclusive mutex.
255static ACTIVE: RwLock<AddressSpace> = RwLock::new(AddressSpace::new());
256
257/// Installs `space` as the active trap-path address space.
258///
259/// Returns the previous active space (caller may drop it to unmap owned regions).
260pub fn install_active(space: AddressSpace) -> AddressSpace {
261    match ACTIVE.write() {
262        Ok(mut guard) => std::mem::replace(&mut *guard, space),
263        Err(poisoned) => {
264            let mut guard = poisoned.into_inner();
265            std::mem::replace(&mut *guard, space)
266        }
267    }
268}
269
270/// Takes the active address space, leaving an empty one installed.
271#[must_use]
272pub fn take_active() -> AddressSpace {
273    install_active(AddressSpace::new())
274}
275
276/// Runs `f` with exclusive access to the active address space.
277pub fn with_active_mut<R>(f: impl FnOnce(&mut AddressSpace) -> R) -> R {
278    match ACTIVE.write() {
279        Ok(mut guard) => f(&mut guard),
280        Err(poisoned) => f(&mut poisoned.into_inner()),
281    }
282}
283
284/// Runs `f` with shared access to the active address space.
285pub fn with_active<R>(f: impl FnOnce(&AddressSpace) -> R) -> R {
286    match ACTIVE.read() {
287        Ok(guard) => f(&guard),
288        Err(poisoned) => f(&poisoned.into_inner()),
289    }
290}
291
292/// Clears the active address space. Owned mappings are `munmap`'d.
293pub fn clear() {
294    LAST_RANGE.with(|c| c.set(None));
295    with_active_mut(AddressSpace::clear);
296}
297
298/// Registers a borrowed region on the active address space.
299pub fn register_borrowed(region: &MappedRegion) {
300    with_active_mut(|space| space.register_borrowed(region));
301}
302
303/// Registers an owned anonymous mapping on the active address space.
304pub fn register_owned(guest_addr: u64, ptr: *mut u8, len: usize, prot: u32) {
305    with_active_mut(|space| space.register_owned(guest_addr, ptr, len, prot));
306}
307
308/// True when the active space has at least one region.
309#[must_use]
310pub fn is_active() -> bool {
311    with_active(AddressSpace::is_active)
312}
313
314/// Validates a range against the active address space.
315///
316/// Hot path: thread-local last-hit cache (no `RwLock`) for sequential
317/// read/write into the same mapping.
318#[must_use]
319pub fn check_range(addr: u64, len: usize, need_write: bool) -> bool {
320    if len == 0 {
321        return true;
322    }
323    if addr == 0 {
324        return false;
325    }
326    if LAST_RANGE.with(|c| {
327        c.get()
328            .is_some_and(|r| r.contains(addr, len) && r.allows(need_write))
329    }) {
330        return true;
331    }
332    with_active(|space| {
333        if space.regions.is_empty() {
334            return true;
335        }
336        for region in &space.regions {
337            if !region.contains_range(addr, len) {
338                continue;
339            }
340            let ok = if need_write {
341                region.prot & VM_PROT_WRITE != 0
342            } else {
343                region.prot & (VM_PROT_READ | VM_PROT_WRITE) != 0
344            };
345            if ok {
346                LAST_RANGE.with(|c| {
347                    c.set(Some(RangeCache {
348                        guest_addr: region.guest_addr,
349                        len: region.len,
350                        prot: region.prot,
351                    }));
352                });
353            }
354            return ok;
355        }
356        false
357    })
358}
359
360/// Finds a covering region in the active address space.
361#[must_use]
362pub fn find_covering(addr: u64, len: usize) -> Option<RegRegionSnapshot> {
363    with_active(|space| space.find_covering(addr, len))
364}
365
366/// Updates protection on a region in the active address space.
367pub fn update_prot(addr: u64, len: usize, prot: u32) -> bool {
368    with_active_mut(|space| space.update_prot(addr, len, prot))
369}
370
371/// Removes a range from the active address space.
372pub fn remove_range(addr: u64, len: usize) -> RemoveOutcome {
373    with_active_mut(|space| space.remove_range(addr, len))
374}
375
376/// Snapshot of a registry entry (no ownership).
377#[derive(Debug, Clone, Copy)]
378pub struct RegRegionSnapshot {
379    /// Guest base.
380    pub guest_addr: u64,
381    /// Host length.
382    pub len: usize,
383    /// Host pointer.
384    pub ptr: *mut u8,
385    /// Darwin prot.
386    pub prot: u32,
387    /// Owned by the address space.
388    pub owned: bool,
389}
390
391// SAFETY: snapshot is a POD copy of pointers managed under the active mutex
392// during the syscall that uses it.
393unsafe impl Send for RegRegionSnapshot {}
394
395/// Result of [`AddressSpace::remove_range`] / [`remove_range`].
396#[derive(Debug, Clone, Copy, PartialEq, Eq)]
397pub enum RemoveOutcome {
398    /// No covering region.
399    NotFound,
400    /// Owned region unmapped successfully.
401    Unmapped,
402    /// Borrowed region dropped from tracking only.
403    Untracked,
404    /// `munmap` failed.
405    UnmapFailed,
406}
407
408fn host_ptr_from_addr(addr: u64) -> *mut u8 {
409    let u = usize::try_from(addr).unwrap_or(0);
410    std::ptr::with_exposed_provenance_mut(u)
411}
412
413/// Serializes tests that mutate process-wide active space / process state.
414#[cfg(test)]
415pub(crate) fn test_lock() -> std::sync::MutexGuard<'static, ()> {
416    crate::process::test_lock()
417}
418
419#[cfg(test)]
420#[allow(clippy::expect_used)]
421mod tests {
422    use super::*;
423    use crate::mem::HostPageSize;
424    use crate::mem::map::{VM_PROT_EXECUTE, map_stack};
425
426    #[test]
427    fn empty_local_space_allows_checks() {
428        let space = AddressSpace::new();
429        assert!(!space.is_active());
430        assert!(space.check_range(0x1000, 16, false));
431    }
432
433    #[test]
434    fn empty_active_registry_allows_checks() {
435        let _g = test_lock();
436        clear();
437        assert!(!is_active());
438        assert!(check_range(0x1000, 16, false));
439    }
440
441    #[test]
442    fn local_stack_region_validates() {
443        let host = HostPageSize::detect().expect("host page");
444        let stack = map_stack(host, 64 * 1024).expect("stack");
445        let mut space = AddressSpace::new();
446        space.register_borrowed(&stack);
447        assert!(space.is_active());
448        let base = stack.guest_addr;
449        assert!(space.check_range(base, 64, true));
450        assert!(space.check_range(base, 64, false));
451        assert!(!space.check_range(0, 8, false));
452        let outside = base.wrapping_add(u64::try_from(stack.host_len()).unwrap_or(0));
453        assert!(!space.check_range(outside, 8, false));
454        space.clear();
455        drop(stack);
456    }
457
458    #[test]
459    fn stack_region_validates_via_active() {
460        let _g = test_lock();
461        clear();
462        let host = HostPageSize::detect().expect("host page");
463        let stack = map_stack(host, 64 * 1024).expect("stack");
464        register_borrowed(&stack);
465        assert!(is_active());
466        let base = stack.guest_addr;
467        assert!(check_range(base, 64, true));
468        assert!(check_range(base, 64, false));
469        assert!(!check_range(0, 8, false));
470        let outside = base.wrapping_add(u64::try_from(stack.host_len()).unwrap_or(0));
471        assert!(!check_range(outside, 8, false));
472        clear();
473        drop(stack);
474    }
475
476    #[test]
477    fn execute_only_not_writable() {
478        let host = HostPageSize::detect().expect("host page");
479        let stack = map_stack(host, u64::from(host.bytes())).expect("stack");
480        let mut space = AddressSpace::new();
481        space.push_raw(RegRegion {
482            guest_addr: stack.guest_addr,
483            len: stack.host_len(),
484            ptr: host_ptr_from_addr(stack.host_addr()),
485            prot: VM_PROT_READ | VM_PROT_EXECUTE,
486            owned: false,
487        });
488        assert!(space.check_range(stack.guest_addr, 8, false));
489        assert!(!space.check_range(stack.guest_addr, 8, true));
490        space.clear();
491        drop(stack);
492    }
493
494    #[test]
495    fn install_active_swaps_spaces() {
496        let _g = test_lock();
497        clear();
498        let host = HostPageSize::detect().expect("host page");
499        let stack = map_stack(host, 64 * 1024).expect("stack");
500        let mut space = AddressSpace::new();
501        space.register_borrowed(&stack);
502        let prev = install_active(space);
503        assert!(!prev.is_active());
504        assert!(is_active());
505        assert!(check_range(stack.guest_addr, 8, false));
506        let taken = take_active();
507        assert!(taken.is_active());
508        assert!(!is_active());
509        drop(taken);
510        drop(stack);
511    }
512}