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