guestmem/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Interfaces to read and write guest memory.
5
6// UNSAFETY: This crate's whole purpose is manual memory mapping and management.
7#![expect(unsafe_code)]
8#![expect(missing_docs)]
9
10pub mod ranges;
11
12use self::ranges::PagedRange;
13use inspect::Inspect;
14use pal_event::Event;
15use sparse_mmap::AsMappableRef;
16use std::any::Any;
17use std::fmt::Debug;
18use std::io;
19use std::ops::Deref;
20use std::ops::DerefMut;
21use std::ops::Range;
22use std::ptr::NonNull;
23use std::sync::Arc;
24use std::sync::atomic::AtomicU8;
25use thiserror::Error;
26use zerocopy::FromBytes;
27use zerocopy::FromZeros;
28use zerocopy::Immutable;
29use zerocopy::IntoBytes;
30use zerocopy::KnownLayout;
31
32// Effective page size for page-related operations in this crate.
33pub const PAGE_SIZE: usize = 4096;
34const PAGE_SIZE64: u64 = 4096;
35
36/// A memory access error returned by one of the [`GuestMemory`] methods.
37#[derive(Debug, Error)]
38#[error(transparent)]
39pub struct GuestMemoryError(Box<GuestMemoryErrorInner>);
40
41impl GuestMemoryError {
42    fn new(
43        debug_name: &Arc<str>,
44        range: Option<Range<u64>>,
45        op: GuestMemoryOperation,
46        err: GuestMemoryBackingError,
47    ) -> Self {
48        GuestMemoryError(Box::new(GuestMemoryErrorInner {
49            op,
50            debug_name: debug_name.clone(),
51            range,
52            gpa: (err.gpa != INVALID_ERROR_GPA).then_some(err.gpa),
53            kind: err.kind,
54            err: err.err,
55        }))
56    }
57
58    /// Returns the kind of the error.
59    pub fn kind(&self) -> GuestMemoryErrorKind {
60        self.0.kind
61    }
62}
63
64#[derive(Debug, Copy, Clone)]
65enum GuestMemoryOperation {
66    Read,
67    Write,
68    Fill,
69    CompareExchange,
70    Lock,
71    Subrange,
72    Probe,
73}
74
75impl std::fmt::Display for GuestMemoryOperation {
76    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
77        f.pad(match self {
78            GuestMemoryOperation::Read => "read",
79            GuestMemoryOperation::Write => "write",
80            GuestMemoryOperation::Fill => "fill",
81            GuestMemoryOperation::CompareExchange => "compare exchange",
82            GuestMemoryOperation::Lock => "lock",
83            GuestMemoryOperation::Subrange => "subrange",
84            GuestMemoryOperation::Probe => "probe",
85        })
86    }
87}
88
89#[derive(Debug, Error)]
90struct GuestMemoryErrorInner {
91    op: GuestMemoryOperation,
92    debug_name: Arc<str>,
93    range: Option<Range<u64>>,
94    gpa: Option<u64>,
95    kind: GuestMemoryErrorKind,
96    #[source]
97    err: Box<dyn std::error::Error + Send + Sync>,
98}
99
100impl std::fmt::Display for GuestMemoryErrorInner {
101    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
102        write!(
103            f,
104            "guest memory '{debug_name}': {op} error: failed to access ",
105            debug_name = self.debug_name,
106            op = self.op
107        )?;
108        if let Some(range) = &self.range {
109            write!(f, "{:#x}-{:#x}", range.start, range.end)?;
110        } else {
111            f.write_str("memory")?;
112        }
113        // Include the precise GPA if provided and different from the start of
114        // the range.
115        if let Some(gpa) = self.gpa {
116            if self.range.as_ref().is_none_or(|range| range.start != gpa) {
117                write!(f, " at {:#x}", gpa)?;
118            }
119        }
120        Ok(())
121    }
122}
123
124/// A memory access error returned by a [`GuestMemoryAccess`] trait method.
125#[derive(Debug)]
126pub struct GuestMemoryBackingError {
127    gpa: u64,
128    kind: GuestMemoryErrorKind,
129    err: Box<dyn std::error::Error + Send + Sync>,
130}
131
132/// The kind of memory access error.
133#[derive(Debug, Copy, Clone, PartialEq, Eq)]
134#[non_exhaustive]
135pub enum GuestMemoryErrorKind {
136    /// An error that does not fit any other category.
137    Other,
138    /// The address is outside the valid range of the memory.
139    OutOfRange,
140    /// The memory has been protected by a higher virtual trust level.
141    VtlProtected,
142    /// The memory is shared but was accessed via a private address.
143    NotPrivate,
144    /// The memory is private but was accessed via a shared address.
145    NotShared,
146}
147
148/// An error returned by a page fault handler in [`GuestMemoryAccess::page_fault`].
149pub struct PageFaultError {
150    kind: GuestMemoryErrorKind,
151    err: Box<dyn std::error::Error + Send + Sync>,
152}
153
154impl PageFaultError {
155    /// Returns a new page fault error.
156    pub fn new(
157        kind: GuestMemoryErrorKind,
158        err: impl Into<Box<dyn std::error::Error + Send + Sync>>,
159    ) -> Self {
160        Self {
161            kind,
162            err: err.into(),
163        }
164    }
165
166    /// Returns a page fault error without an explicit kind.
167    pub fn other(err: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
168        Self::new(GuestMemoryErrorKind::Other, err)
169    }
170}
171
172/// Used to avoid needing an `Option` for [`GuestMemoryBackingError::gpa`], to
173/// save size in hot paths.
174const INVALID_ERROR_GPA: u64 = !0;
175
176impl GuestMemoryBackingError {
177    /// Returns a new error for a memory access failure at address `gpa`.
178    pub fn new(
179        kind: GuestMemoryErrorKind,
180        gpa: u64,
181        err: impl Into<Box<dyn std::error::Error + Send + Sync>>,
182    ) -> Self {
183        // `gpa` might incorrectly be INVALID_ERROR_GPA; this is harmless (just
184        // affecting the error message), so don't assert on it in case this is
185        // an untrusted value in some path.
186        Self {
187            kind,
188            gpa,
189            err: err.into(),
190        }
191    }
192
193    /// Returns a new error without an explicit kind.
194    pub fn other(gpa: u64, err: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
195        Self::new(GuestMemoryErrorKind::Other, gpa, err)
196    }
197
198    fn gpn(err: InvalidGpn) -> Self {
199        Self {
200            kind: GuestMemoryErrorKind::OutOfRange,
201            gpa: INVALID_ERROR_GPA,
202            err: err.into(),
203        }
204    }
205}
206
207#[derive(Debug, Error)]
208#[error("no memory at address")]
209struct OutOfRange;
210
211#[derive(Debug, Error)]
212#[error("memory not lockable")]
213struct NotLockable;
214
215#[derive(Debug, Error)]
216#[error("no fallback for this operation")]
217struct NoFallback;
218
219#[derive(Debug, Error)]
220#[error("the specified page is not mapped")]
221struct NotMapped;
222
223#[derive(Debug, Error)]
224#[error("page inaccessible in bitmap")]
225struct BitmapFailure;
226
227/// A trait for a guest memory backing that is fully available via a virtual
228/// address mapping, as opposed to the fallback functions such as
229/// [`GuestMemoryAccess::read_fallback`].
230///
231/// By implementing this trait, a type guarantees that its
232/// [`GuestMemoryAccess::mapping`] will return `Some(_)` and that all of its
233/// memory can be accessed through that mapping, without needing to call the
234/// fallback functions.
235pub trait LinearGuestMemory: GuestMemoryAccess {}
236
237// SAFETY: the allocation will stay valid for the lifetime of the object.
238unsafe impl GuestMemoryAccess for sparse_mmap::alloc::SharedMem {
239    fn mapping(&self) -> Option<NonNull<u8>> {
240        NonNull::new(self.as_ptr().cast_mut().cast())
241    }
242
243    fn max_address(&self) -> u64 {
244        self.len() as u64
245    }
246}
247
248impl LinearGuestMemory for sparse_mmap::alloc::SharedMem {}
249
250/// A page-aligned heap allocation for use with [`GuestMemory`].
251pub struct AlignedHeapMemory {
252    pages: Box<[AlignedPage]>,
253}
254
255impl Debug for AlignedHeapMemory {
256    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
257        f.debug_struct("AlignedHeapMemory")
258            .field("len", &self.len())
259            .finish()
260    }
261}
262
263#[repr(C, align(4096))]
264struct AlignedPage([AtomicU8; PAGE_SIZE]);
265
266impl AlignedHeapMemory {
267    /// Allocates a new memory of `size` bytes, rounded up to a page size.
268    pub fn new(size: usize) -> Self {
269        #[expect(clippy::declare_interior_mutable_const)] // <https://github.com/rust-lang/rust-clippy/issues/7665>
270        const ZERO: AtomicU8 = AtomicU8::new(0);
271        #[expect(clippy::declare_interior_mutable_const)]
272        const ZERO_PAGE: AlignedPage = AlignedPage([ZERO; PAGE_SIZE]);
273        let mut pages = Vec::new();
274        pages.resize_with(size.div_ceil(PAGE_SIZE), || ZERO_PAGE);
275        Self {
276            pages: pages.into(),
277        }
278    }
279
280    /// Returns the length of the memory in bytes.
281    pub fn len(&self) -> usize {
282        self.pages.len() * PAGE_SIZE
283    }
284
285    /// Returns an immutable slice of bytes.
286    ///
287    /// This must take `&mut self` since the buffer is mutable via interior
288    /// mutability with just `&self`.
289    pub fn as_bytes(&mut self) -> &[u8] {
290        self.as_mut()
291    }
292
293    /// Returns a mutable slice of bytes.
294    pub fn as_mut_bytes(&mut self) -> &mut [u8] {
295        self.as_mut()
296    }
297}
298
299impl Deref for AlignedHeapMemory {
300    type Target = [AtomicU8];
301
302    fn deref(&self) -> &Self::Target {
303        // SAFETY: the buffer has the correct size and validity.
304        unsafe { std::slice::from_raw_parts(self.pages.as_ptr().cast(), self.len()) }
305    }
306}
307
308impl DerefMut for AlignedHeapMemory {
309    fn deref_mut(&mut self) -> &mut Self::Target {
310        // SAFETY: the buffer is unaliased and valid.
311        unsafe { std::slice::from_raw_parts_mut(self.pages.as_mut_ptr().cast(), self.len()) }
312    }
313}
314
315impl AsRef<[AtomicU8]> for AlignedHeapMemory {
316    fn as_ref(&self) -> &[AtomicU8] {
317        self
318    }
319}
320
321impl AsMut<[AtomicU8]> for AlignedHeapMemory {
322    fn as_mut(&mut self) -> &mut [AtomicU8] {
323        self
324    }
325}
326
327impl AsMut<[u8]> for AlignedHeapMemory {
328    fn as_mut(&mut self) -> &mut [u8] {
329        // FUTURE: use AtomicU8::get_mut_slice once stabilized.
330        // SAFETY: the buffer is unaliased, so it is fine to cast away the atomicness of the
331        // slice.
332        unsafe { std::slice::from_raw_parts_mut(self.as_mut_ptr().cast(), self.len()) }
333    }
334}
335
336// SAFETY: the allocation remains alive and valid for the lifetime of the
337// object.
338unsafe impl GuestMemoryAccess for AlignedHeapMemory {
339    fn mapping(&self) -> Option<NonNull<u8>> {
340        NonNull::new(self.pages.as_ptr().cast_mut().cast())
341    }
342
343    fn max_address(&self) -> u64 {
344        (self.pages.len() * PAGE_SIZE) as u64
345    }
346}
347
348impl LinearGuestMemory for AlignedHeapMemory {}
349
350/// A trait for a guest memory backing.
351///
352/// Guest memory may be backed by a virtual memory mapping, in which case this
353/// trait can provide the VA and length of that mapping. Alternatively, it may
354/// be backed by some other means, in which case this trait can provide fallback
355/// methods for reading and writing memory.
356///
357/// Memory access should first be attempted via the virtual address mapping. If
358/// this fails or is not present, the caller should fall back to `read_fallback`
359/// or `write_fallback`. This allows an implementation to have a fast path using
360/// the mapping, and a slow path using the fallback functions.
361///
362/// # Safety
363///
364/// The implementor must follow the contract for each method.
365pub unsafe trait GuestMemoryAccess: 'static + Send + Sync {
366    /// Returns a stable VA mapping for guest memory.
367    ///
368    /// The size of the mapping is the same as `max_address`.
369    ///
370    /// The VA is guaranteed to remain reserved, but individual ranges may be
371    /// uncommitted.
372    fn mapping(&self) -> Option<NonNull<u8>>;
373
374    /// The maximum address that can be passed to the `*_fallback` methods, as
375    /// well as the maximum offset into the VA range described by `mapping`.
376    fn max_address(&self) -> u64;
377
378    /// The bitmaps to check for validity, one bit per page. If a bit is set,
379    /// then the page is valid to access via the mapping; if it is clear, then
380    /// the page will not be accessed.
381    ///
382    /// The bitmaps must be at least `ceil(bitmap_start + max_address() /
383    /// PAGE_SIZE)` bits long, and they must be valid for atomic read access for
384    /// the lifetime of this object from any thread.
385    ///
386    /// The bitmaps are only checked if there is a mapping. If the bitmap check
387    /// fails, then the associated `*_fallback` routine is called to handle the
388    /// error.
389    ///
390    /// Bitmap checks are performed under the [`rcu()`] RCU domain, with relaxed
391    /// accesses. After a thread updates the bitmap to be more restrictive, it
392    /// must call [`minircu::global().synchronize()`] to ensure that all threads
393    /// see the update before taking any action that depends on the bitmap
394    /// update being visible.
395    #[cfg(feature = "bitmap")]
396    fn access_bitmap(&self) -> Option<BitmapInfo> {
397        None
398    }
399
400    // Returns an accessor for a subrange, or `None` to use the default
401    // implementation.
402    fn subrange(
403        &self,
404        offset: u64,
405        len: u64,
406        allow_preemptive_locking: bool,
407    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError> {
408        let _ = (offset, len, allow_preemptive_locking);
409        Ok(None)
410    }
411
412    /// Called when access to memory via the mapped range fails, either due to a
413    /// bitmap failure or due to a failure when accessing the virtual address.
414    ///
415    /// `address` is the address where the access failed. `len` is the remainder
416    /// of the access; it is not necessarily the case that all `len` bytes are
417    /// inaccessible in the bitmap or mapping.
418    ///
419    /// Returns whether the faulting operation should be retried, failed, or that
420    /// one of the fallback operations (e.g. `read_fallback`) should be called.
421    fn page_fault(
422        &self,
423        address: u64,
424        len: usize,
425        write: bool,
426        bitmap_failure: bool,
427    ) -> PageFaultAction {
428        let _ = (address, len, write);
429        let err = if bitmap_failure {
430            PageFaultError::other(BitmapFailure)
431        } else {
432            PageFaultError::other(NotMapped)
433        };
434        PageFaultAction::Fail(err)
435    }
436
437    /// Fallback called if a read fails via direct access to `mapped_range`.
438    ///
439    /// This is only called if `mapping()` returns `None` or if `page_fault()`
440    /// returns `PageFaultAction::Fallback`.
441    ///
442    /// Implementors must ensure that `dest[..len]` is fully initialized on
443    /// successful return.
444    ///
445    /// # Safety
446    /// The caller must ensure that `dest[..len]` is valid for write. Note,
447    /// however, that `dest` might be aliased by other threads, the guest, or
448    /// the kernel.
449    unsafe fn read_fallback(
450        &self,
451        addr: u64,
452        dest: *mut u8,
453        len: usize,
454    ) -> Result<(), GuestMemoryBackingError> {
455        let _ = (dest, len);
456        Err(GuestMemoryBackingError::other(addr, NoFallback))
457    }
458
459    /// Fallback called if a write fails via direct access to `mapped_range`.
460    ///
461    /// This is only called if `mapping()` returns `None` or if `page_fault()`
462    /// returns `PageFaultAction::Fallback`.
463    ///
464    /// # Safety
465    /// The caller must ensure that `src[..len]` is valid for read. Note,
466    /// however, that `src` might be aliased by other threads, the guest, or
467    /// the kernel.
468    unsafe fn write_fallback(
469        &self,
470        addr: u64,
471        src: *const u8,
472        len: usize,
473    ) -> Result<(), GuestMemoryBackingError> {
474        let _ = (src, len);
475        Err(GuestMemoryBackingError::other(addr, NoFallback))
476    }
477
478    /// Fallback called if a fill fails via direct access to `mapped_range`.
479    ///
480    /// This is only called if `mapping()` returns `None` or if `page_fault()`
481    /// returns `PageFaultAction::Fallback`.
482    fn fill_fallback(&self, addr: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError> {
483        let _ = (val, len);
484        Err(GuestMemoryBackingError::other(addr, NoFallback))
485    }
486
487    /// Fallback called if a compare exchange fails via direct access to `mapped_range`.
488    ///
489    /// On compare failure, returns `Ok(false)` and updates `current`.
490    ///
491    /// This is only called if `mapping()` returns `None` or if `page_fault()`
492    /// returns `PageFaultAction::Fallback`.
493    fn compare_exchange_fallback(
494        &self,
495        addr: u64,
496        current: &mut [u8],
497        new: &[u8],
498    ) -> Result<bool, GuestMemoryBackingError> {
499        let _ = (current, new);
500        Err(GuestMemoryBackingError::other(addr, NoFallback))
501    }
502
503    /// Prepares a guest page for having its virtual address exposed as part of
504    /// a lock call.
505    ///
506    /// This is useful to ensure that the address is mapped in a way that it can
507    /// be passed to the kernel for DMA.
508    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError> {
509        let _ = (address, len);
510        Ok(())
511    }
512
513    /// Returns the base IO virtual address for the mapping.
514    ///
515    /// This is the base address that should be used for DMA from a user-mode
516    /// device driver whose device is not otherwise configured to go through an
517    /// IOMMU.
518    fn base_iova(&self) -> Option<u64> {
519        None
520    }
521
522    /// Locks the specified guest physical pages (GPNs), preventing any mapping
523    /// or permission changes until they are unlocked.
524    ///
525    /// Returns a boolean indicating whether unlocking is required.
526    fn lock_gpns(&self, gpns: &[u64]) -> Result<bool, GuestMemoryBackingError> {
527        let _ = gpns;
528        Ok(false)
529    }
530
531    /// Unlocks the specified guest physical pages (GPNs) after exclusive access.
532    ///
533    /// Panics if asked to unlock a page that was not previously locked. The
534    /// caller must ensure that the given slice has the same ordering as the
535    /// one passed to `lock_gpns`.
536    fn unlock_gpns(&self, gpns: &[u64]) {
537        let _ = gpns;
538    }
539}
540
541trait DynGuestMemoryAccess: 'static + Send + Sync + Any {
542    fn subrange(
543        &self,
544        offset: u64,
545        len: u64,
546        allow_preemptive_locking: bool,
547    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError>;
548
549    fn page_fault(
550        &self,
551        address: u64,
552        len: usize,
553        write: bool,
554        bitmap_failure: bool,
555    ) -> PageFaultAction;
556
557    /// # Safety
558    /// See [`GuestMemoryAccess::read_fallback`].
559    unsafe fn read_fallback(
560        &self,
561        addr: u64,
562        dest: *mut u8,
563        len: usize,
564    ) -> Result<(), GuestMemoryBackingError>;
565
566    /// # Safety
567    /// See [`GuestMemoryAccess::write_fallback`].
568    unsafe fn write_fallback(
569        &self,
570        addr: u64,
571        src: *const u8,
572        len: usize,
573    ) -> Result<(), GuestMemoryBackingError>;
574
575    fn fill_fallback(&self, addr: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError>;
576
577    fn compare_exchange_fallback(
578        &self,
579        addr: u64,
580        current: &mut [u8],
581        new: &[u8],
582    ) -> Result<bool, GuestMemoryBackingError>;
583
584    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError>;
585
586    fn lock_gpns(&self, gpns: &[u64]) -> Result<bool, GuestMemoryBackingError>;
587
588    fn unlock_gpns(&self, gpns: &[u64]);
589}
590
591impl<T: GuestMemoryAccess> DynGuestMemoryAccess for T {
592    fn subrange(
593        &self,
594        offset: u64,
595        len: u64,
596        allow_preemptive_locking: bool,
597    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError> {
598        self.subrange(offset, len, allow_preemptive_locking)
599    }
600
601    fn page_fault(
602        &self,
603        address: u64,
604        len: usize,
605        write: bool,
606        bitmap_failure: bool,
607    ) -> PageFaultAction {
608        self.page_fault(address, len, write, bitmap_failure)
609    }
610
611    unsafe fn read_fallback(
612        &self,
613        addr: u64,
614        dest: *mut u8,
615        len: usize,
616    ) -> Result<(), GuestMemoryBackingError> {
617        // SAFETY: guaranteed by caller.
618        unsafe { self.read_fallback(addr, dest, len) }
619    }
620
621    unsafe fn write_fallback(
622        &self,
623        addr: u64,
624        src: *const u8,
625        len: usize,
626    ) -> Result<(), GuestMemoryBackingError> {
627        // SAFETY: guaranteed by caller.
628        unsafe { self.write_fallback(addr, src, len) }
629    }
630
631    fn fill_fallback(&self, addr: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError> {
632        self.fill_fallback(addr, val, len)
633    }
634
635    fn compare_exchange_fallback(
636        &self,
637        addr: u64,
638        current: &mut [u8],
639        new: &[u8],
640    ) -> Result<bool, GuestMemoryBackingError> {
641        self.compare_exchange_fallback(addr, current, new)
642    }
643
644    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError> {
645        self.expose_va(address, len)
646    }
647
648    fn lock_gpns(&self, gpns: &[u64]) -> Result<bool, GuestMemoryBackingError> {
649        self.lock_gpns(gpns)
650    }
651
652    fn unlock_gpns(&self, gpns: &[u64]) {
653        self.unlock_gpns(gpns)
654    }
655}
656
657/// The action to take after [`GuestMemoryAccess::page_fault`] returns to
658/// continue the operation.
659pub enum PageFaultAction {
660    /// Fail the operation.
661    Fail(PageFaultError),
662    /// Retry the operation.
663    Retry,
664    /// Use the fallback method to access the memory.
665    Fallback,
666}
667
668/// Returned by [`GuestMemoryAccess::access_bitmap`].
669#[cfg(feature = "bitmap")]
670pub struct BitmapInfo {
671    /// A pointer to the bitmap for read access.
672    pub read_bitmap: NonNull<u8>,
673    /// A pointer to the bitmap for write access.
674    pub write_bitmap: NonNull<u8>,
675    /// The bit offset of the beginning of the bitmap.
676    ///
677    /// Typically this is zero, but it is needed to support subranges that are
678    /// not 8-page multiples.
679    pub bit_offset: u8,
680}
681
682// SAFETY: passing through guarantees from `T`.
683unsafe impl<T: GuestMemoryAccess> GuestMemoryAccess for Arc<T> {
684    fn mapping(&self) -> Option<NonNull<u8>> {
685        self.as_ref().mapping()
686    }
687
688    fn max_address(&self) -> u64 {
689        self.as_ref().max_address()
690    }
691
692    #[cfg(feature = "bitmap")]
693    fn access_bitmap(&self) -> Option<BitmapInfo> {
694        self.as_ref().access_bitmap()
695    }
696
697    fn subrange(
698        &self,
699        offset: u64,
700        len: u64,
701        allow_preemptive_locking: bool,
702    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError> {
703        self.as_ref()
704            .subrange(offset, len, allow_preemptive_locking)
705    }
706
707    fn page_fault(
708        &self,
709        addr: u64,
710        len: usize,
711        write: bool,
712        bitmap_failure: bool,
713    ) -> PageFaultAction {
714        self.as_ref().page_fault(addr, len, write, bitmap_failure)
715    }
716
717    unsafe fn read_fallback(
718        &self,
719        addr: u64,
720        dest: *mut u8,
721        len: usize,
722    ) -> Result<(), GuestMemoryBackingError> {
723        // SAFETY: passing through guarantees from caller.
724        unsafe { self.as_ref().read_fallback(addr, dest, len) }
725    }
726
727    unsafe fn write_fallback(
728        &self,
729        addr: u64,
730        src: *const u8,
731        len: usize,
732    ) -> Result<(), GuestMemoryBackingError> {
733        // SAFETY: passing through guarantees from caller.
734        unsafe { self.as_ref().write_fallback(addr, src, len) }
735    }
736
737    fn fill_fallback(&self, addr: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError> {
738        self.as_ref().fill_fallback(addr, val, len)
739    }
740
741    fn compare_exchange_fallback(
742        &self,
743        addr: u64,
744        current: &mut [u8],
745        new: &[u8],
746    ) -> Result<bool, GuestMemoryBackingError> {
747        self.as_ref().compare_exchange_fallback(addr, current, new)
748    }
749
750    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError> {
751        self.as_ref().expose_va(address, len)
752    }
753
754    fn base_iova(&self) -> Option<u64> {
755        self.as_ref().base_iova()
756    }
757}
758
759// SAFETY: the allocation will stay valid for the lifetime of the object.
760unsafe impl GuestMemoryAccess for sparse_mmap::SparseMapping {
761    fn mapping(&self) -> Option<NonNull<u8>> {
762        NonNull::new(self.as_ptr().cast())
763    }
764
765    fn max_address(&self) -> u64 {
766        self.len() as u64
767    }
768}
769
770/// Default guest memory range type, enforcing access boundaries.
771struct GuestMemoryAccessRange {
772    base: Arc<GuestMemoryInner>,
773    offset: u64,
774    len: u64,
775    region: usize,
776}
777
778impl GuestMemoryAccessRange {
779    fn adjust_range(&self, address: u64, len: u64) -> Result<u64, GuestMemoryBackingError> {
780        if address <= self.len && len <= self.len - address {
781            Ok(self.offset + address)
782        } else {
783            Err(GuestMemoryBackingError::new(
784                GuestMemoryErrorKind::OutOfRange,
785                address,
786                OutOfRange,
787            ))
788        }
789    }
790}
791
792// SAFETY: `mapping()` is guaranteed to be valid for the lifetime of the object.
793unsafe impl GuestMemoryAccess for GuestMemoryAccessRange {
794    fn mapping(&self) -> Option<NonNull<u8>> {
795        let region = &self.base.regions[self.region];
796        region.mapping.and_then(|mapping| {
797            let offset = self.offset & self.base.region_def.region_mask;
798            // This is guaranteed by construction.
799            assert!(region.len >= offset + self.len);
800            // SAFETY: this mapping is guaranteed to be within range by
801            // construction (and validated again via the assertion above).
802            NonNull::new(unsafe { mapping.0.as_ptr().add(offset as usize) })
803        })
804    }
805
806    fn max_address(&self) -> u64 {
807        self.len
808    }
809
810    #[cfg(feature = "bitmap")]
811    fn access_bitmap(&self) -> Option<BitmapInfo> {
812        let region = &self.base.regions[self.region];
813        region.bitmaps.map(|bitmaps| {
814            let offset = self.offset & self.base.region_def.region_mask;
815            let bit_offset = region.bitmap_start as u64 + offset / PAGE_SIZE64;
816            let [read_bitmap, write_bitmap] = bitmaps.map(|SendPtrU8(ptr)| {
817                // SAFETY: the bitmap is guaranteed to be big enough for the region
818                // by construction.
819                NonNull::new(unsafe { ptr.as_ptr().add((bit_offset / 8) as usize) }).unwrap()
820            });
821            let bitmap_start = (bit_offset % 8) as u8;
822            BitmapInfo {
823                read_bitmap,
824                write_bitmap,
825                bit_offset: bitmap_start,
826            }
827        })
828    }
829
830    fn subrange(
831        &self,
832        offset: u64,
833        len: u64,
834        _allow_preemptive_locking: bool,
835    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError> {
836        let address = self.adjust_range(offset, len)?;
837        Ok(Some(GuestMemory::new(
838            self.base.debug_name.clone(),
839            GuestMemoryAccessRange {
840                base: self.base.clone(),
841                offset: address,
842                len,
843                region: self.region,
844            },
845        )))
846    }
847
848    fn page_fault(
849        &self,
850        address: u64,
851        len: usize,
852        write: bool,
853        bitmap_failure: bool,
854    ) -> PageFaultAction {
855        let address = self
856            .adjust_range(address, len as u64)
857            .expect("the caller should have validated the range was in the mapping");
858
859        self.base
860            .imp
861            .page_fault(address, len, write, bitmap_failure)
862    }
863
864    unsafe fn write_fallback(
865        &self,
866        address: u64,
867        src: *const u8,
868        len: usize,
869    ) -> Result<(), GuestMemoryBackingError> {
870        let address = self.adjust_range(address, len as u64)?;
871        // SAFETY: guaranteed by caller.
872        unsafe { self.base.imp.write_fallback(address, src, len) }
873    }
874
875    fn fill_fallback(
876        &self,
877        address: u64,
878        val: u8,
879        len: usize,
880    ) -> Result<(), GuestMemoryBackingError> {
881        let address = self.adjust_range(address, len as u64)?;
882        self.base.imp.fill_fallback(address, val, len)
883    }
884
885    fn compare_exchange_fallback(
886        &self,
887        addr: u64,
888        current: &mut [u8],
889        new: &[u8],
890    ) -> Result<bool, GuestMemoryBackingError> {
891        let address = self.adjust_range(addr, new.len() as u64)?;
892        self.base
893            .imp
894            .compare_exchange_fallback(address, current, new)
895    }
896
897    unsafe fn read_fallback(
898        &self,
899        address: u64,
900        dest: *mut u8,
901        len: usize,
902    ) -> Result<(), GuestMemoryBackingError> {
903        let address = self.adjust_range(address, len as u64)?;
904        // SAFETY: guaranteed by caller.
905        unsafe { self.base.imp.read_fallback(address, dest, len) }
906    }
907
908    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError> {
909        let address = self.adjust_range(address, len)?;
910        self.base.imp.expose_va(address, len)
911    }
912
913    fn base_iova(&self) -> Option<u64> {
914        let region = &self.base.regions[self.region];
915        Some(region.base_iova? + (self.offset & self.base.region_def.region_mask))
916    }
917}
918
919/// Create a default guest memory subrange that verifies range limits and calls
920/// back into the base implementation.
921fn create_memory_subrange(
922    base: Arc<GuestMemoryInner>,
923    offset: u64,
924    len: u64,
925    _allow_preemptive_locking: bool,
926) -> Result<GuestMemory, GuestMemoryBackingError> {
927    let (_, _, region) = base.region(offset, len)?;
928    Ok(GuestMemory::new(
929        base.debug_name.clone(),
930        GuestMemoryAccessRange {
931            base,
932            offset,
933            len,
934            region,
935        },
936    ))
937}
938
939struct MultiRegionGuestMemoryAccess<T> {
940    imps: Vec<Option<T>>,
941    region_def: RegionDefinition,
942}
943
944impl<T> MultiRegionGuestMemoryAccess<T> {
945    fn region(&self, gpa: u64, len: u64) -> Result<(&T, u64), GuestMemoryBackingError> {
946        let (i, offset) = self.region_def.region(gpa, len)?;
947        let imp = self.imps[i].as_ref().ok_or(GuestMemoryBackingError::new(
948            GuestMemoryErrorKind::OutOfRange,
949            gpa,
950            OutOfRange,
951        ))?;
952        Ok((imp, offset))
953    }
954}
955
956// SAFETY: `mapping()` is unreachable and panics if called.
957impl<T: GuestMemoryAccess> DynGuestMemoryAccess for MultiRegionGuestMemoryAccess<T> {
958    fn subrange(
959        &self,
960        offset: u64,
961        len: u64,
962        allow_preemptive_locking: bool,
963    ) -> Result<Option<GuestMemory>, GuestMemoryBackingError> {
964        let (region, offset_in_region) = self.region(offset, len)?;
965        region.subrange(offset_in_region, len, allow_preemptive_locking)
966    }
967
968    unsafe fn read_fallback(
969        &self,
970        addr: u64,
971        dest: *mut u8,
972        len: usize,
973    ) -> Result<(), GuestMemoryBackingError> {
974        let (region, offset_in_region) = self.region(addr, len as u64)?;
975        // SAFETY: guaranteed by caller.
976        unsafe { region.read_fallback(offset_in_region, dest, len) }
977    }
978
979    unsafe fn write_fallback(
980        &self,
981        addr: u64,
982        src: *const u8,
983        len: usize,
984    ) -> Result<(), GuestMemoryBackingError> {
985        let (region, offset_in_region) = self.region(addr, len as u64)?;
986        // SAFETY: guaranteed by caller.
987        unsafe { region.write_fallback(offset_in_region, src, len) }
988    }
989
990    fn fill_fallback(&self, addr: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError> {
991        let (region, offset_in_region) = self.region(addr, len as u64)?;
992        region.fill_fallback(offset_in_region, val, len)
993    }
994
995    fn compare_exchange_fallback(
996        &self,
997        addr: u64,
998        current: &mut [u8],
999        new: &[u8],
1000    ) -> Result<bool, GuestMemoryBackingError> {
1001        let (region, offset_in_region) = self.region(addr, new.len() as u64)?;
1002        region.compare_exchange_fallback(offset_in_region, current, new)
1003    }
1004
1005    fn expose_va(&self, address: u64, len: u64) -> Result<(), GuestMemoryBackingError> {
1006        let (region, offset_in_region) = self.region(address, len)?;
1007        region.expose_va(offset_in_region, len)
1008    }
1009
1010    fn page_fault(
1011        &self,
1012        address: u64,
1013        len: usize,
1014        write: bool,
1015        bitmap_failure: bool,
1016    ) -> PageFaultAction {
1017        match self.region(address, len as u64) {
1018            Ok((region, offset_in_region)) => {
1019                region.page_fault(offset_in_region, len, write, bitmap_failure)
1020            }
1021            Err(err) => PageFaultAction::Fail(PageFaultError {
1022                kind: err.kind,
1023                err: err.err,
1024            }),
1025        }
1026    }
1027
1028    fn lock_gpns(&self, gpns: &[u64]) -> Result<bool, GuestMemoryBackingError> {
1029        let mut ret = false;
1030        for gpn in gpns {
1031            let (region, offset_in_region) = self.region(gpn * PAGE_SIZE64, PAGE_SIZE64)?;
1032            ret |= region.lock_gpns(&[offset_in_region / PAGE_SIZE64])?;
1033        }
1034        Ok(ret)
1035    }
1036
1037    fn unlock_gpns(&self, gpns: &[u64]) {
1038        for gpn in gpns {
1039            let (region, offset_in_region) = self.region(gpn * PAGE_SIZE64, PAGE_SIZE64).unwrap();
1040            region.unlock_gpns(&[offset_in_region / PAGE_SIZE64]);
1041        }
1042    }
1043}
1044
1045/// A wrapper around a `GuestMemoryAccess` that provides methods for safely
1046/// reading and writing guest memory.
1047// NOTE: this type uses `inspect(skip)`, as it end up being a dependency of
1048// _many_ objects, and littering the inspect graph with references to the same
1049// node would be silly.
1050#[derive(Debug, Clone, Inspect)]
1051#[inspect(skip)]
1052pub struct GuestMemory {
1053    inner: Arc<GuestMemoryInner>,
1054}
1055
1056struct GuestMemoryInner<T: ?Sized = dyn DynGuestMemoryAccess> {
1057    region_def: RegionDefinition,
1058    regions: Vec<MemoryRegion>,
1059    debug_name: Arc<str>,
1060    allocated: bool,
1061    imp: T,
1062}
1063
1064impl<T: ?Sized> Debug for GuestMemoryInner<T> {
1065    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1066        f.debug_struct("GuestMemoryInner")
1067            .field("region_def", &self.region_def)
1068            .field("regions", &self.regions)
1069            .finish()
1070    }
1071}
1072
1073#[derive(Debug, Copy, Clone, Default)]
1074struct MemoryRegion {
1075    mapping: Option<SendPtrU8>,
1076    #[cfg(feature = "bitmap")]
1077    bitmaps: Option<[SendPtrU8; 2]>,
1078    #[cfg(feature = "bitmap")]
1079    bitmap_start: u8,
1080    len: u64,
1081    base_iova: Option<u64>,
1082}
1083
1084/// The access type. The values correspond to bitmap indexes.
1085#[derive(Debug, Copy, Clone, PartialEq, Eq)]
1086enum AccessType {
1087    Read = 0,
1088    Write = 1,
1089}
1090
1091/// `NonNull<u8>` that implements `Send+Sync`.
1092///
1093/// Rust makes pointers `!Send+!Sync` by default to force you to think about the
1094/// ownership model and thread safety of types using pointers--there is nothing
1095/// safety-related about `Send`/`Sync` on pointers by themselves since all such
1096/// accesses to pointers require `unsafe` blocks anyway.
1097///
1098/// However, in practice, this leads to spurious manual `Send+Sync` impls on
1099/// types containing pointers, especially those containing generics. Define a
1100/// wrapping pointer type that implements `Send+Sync` so that the normal auto
1101/// trait rules apply to types containing these pointers.
1102#[derive(Debug, Copy, Clone)]
1103struct SendPtrU8(NonNull<u8>);
1104
1105// SAFETY: see type description.
1106unsafe impl Send for SendPtrU8 {}
1107// SAFETY: see type description.
1108unsafe impl Sync for SendPtrU8 {}
1109
1110impl MemoryRegion {
1111    fn new(imp: &impl GuestMemoryAccess) -> Self {
1112        #[cfg(feature = "bitmap")]
1113        let (bitmaps, bitmap_start) = {
1114            let bitmap_info = imp.access_bitmap();
1115            let bitmaps = bitmap_info
1116                .as_ref()
1117                .map(|bm| [SendPtrU8(bm.read_bitmap), SendPtrU8(bm.write_bitmap)]);
1118            let bitmap_start = bitmap_info.map_or(0, |bi| bi.bit_offset);
1119            (bitmaps, bitmap_start)
1120        };
1121        Self {
1122            mapping: imp.mapping().map(SendPtrU8),
1123            #[cfg(feature = "bitmap")]
1124            bitmaps,
1125            #[cfg(feature = "bitmap")]
1126            bitmap_start,
1127            len: imp.max_address(),
1128            base_iova: imp.base_iova(),
1129        }
1130    }
1131
1132    /// # Safety
1133    ///
1134    /// The caller must ensure that `offset + len` fits in this region, and that
1135    /// the object bitmap is currently valid for atomic read access from this
1136    /// thread.
1137    unsafe fn check_access(
1138        &self,
1139        access_type: AccessType,
1140        offset: u64,
1141        len: u64,
1142    ) -> Result<(), u64> {
1143        debug_assert!(self.len >= offset + len);
1144        #[cfg(not(feature = "bitmap"))]
1145        let _ = access_type;
1146
1147        #[cfg(feature = "bitmap")]
1148        if let Some(bitmaps) = &self.bitmaps {
1149            let SendPtrU8(bitmap) = bitmaps[access_type as usize];
1150            let start = offset / PAGE_SIZE64;
1151            let end = (offset + len - 1) / PAGE_SIZE64;
1152            // FUTURE: consider optimizing this separately for multi-page and
1153            // single-page accesses.
1154            for gpn in start..=end {
1155                let bit_offset = self.bitmap_start as u64 + gpn;
1156                // SAFETY: the caller ensures that the bitmap is big enough and
1157                // valid for atomic read access from this thread.
1158                let bit = unsafe {
1159                    (*bitmap
1160                        .as_ptr()
1161                        .cast_const()
1162                        .cast::<AtomicU8>()
1163                        .add(bit_offset as usize / 8))
1164                    .load(std::sync::atomic::Ordering::Relaxed)
1165                        & (1 << (bit_offset % 8))
1166                };
1167                if bit == 0 {
1168                    return Err((gpn * PAGE_SIZE64).saturating_sub(offset));
1169                }
1170            }
1171        }
1172        Ok(())
1173    }
1174}
1175
1176/// The default implementation is [`GuestMemory::empty`].
1177impl Default for GuestMemory {
1178    fn default() -> Self {
1179        Self::empty()
1180    }
1181}
1182
1183struct Empty;
1184
1185// SAFETY: the mapping is empty, so all requirements are trivially satisfied.
1186unsafe impl GuestMemoryAccess for Empty {
1187    fn mapping(&self) -> Option<NonNull<u8>> {
1188        None
1189    }
1190
1191    fn max_address(&self) -> u64 {
1192        0
1193    }
1194}
1195
1196#[derive(Debug, Error)]
1197pub enum MultiRegionError {
1198    #[error("region size {0:#x} is not a power of 2")]
1199    NotPowerOfTwo(u64),
1200    #[error("region size {0:#x} is smaller than a page")]
1201    RegionSizeTooSmall(u64),
1202    #[error(
1203        "too many regions ({region_count}) for region size {region_size:#x}; max is {max_region_count}"
1204    )]
1205    TooManyRegions {
1206        region_count: usize,
1207        max_region_count: usize,
1208        region_size: u64,
1209    },
1210    #[error("backing size {backing_size:#x} is too large for region size {region_size:#x}")]
1211    BackingTooLarge { backing_size: u64, region_size: u64 },
1212}
1213
1214/// The RCU domain memory accesses occur under. Updates to any memory access
1215/// bitmaps must be synchronized under this domain.
1216///
1217/// See [`GuestMemoryAccess::access_bitmap`] for more details.
1218///
1219/// This is currently the global domain, but this is reexported here to make
1220/// calling code clearer.
1221#[cfg(feature = "bitmap")]
1222pub fn rcu() -> minircu::RcuDomain {
1223    // Use the global domain unless we find a reason to do something else.
1224    minircu::global()
1225}
1226
1227impl GuestMemory {
1228    /// Returns a new instance using `imp` as the backing.
1229    ///
1230    /// `debug_name` is used to specify which guest memory is being accessed in
1231    /// error messages.
1232    pub fn new(debug_name: impl Into<Arc<str>>, imp: impl GuestMemoryAccess) -> Self {
1233        // Install signal handlers on unix if a mapping is present.
1234        //
1235        // Skip this on miri even when there is a mapping, since the mapping may
1236        // never be accessed by the code under test.
1237        if imp.mapping().is_some() && !cfg!(miri) {
1238            sparse_mmap::initialize_try_copy();
1239        }
1240        Self::new_inner(debug_name.into(), imp, false)
1241    }
1242
1243    fn new_inner(debug_name: Arc<str>, imp: impl GuestMemoryAccess, allocated: bool) -> Self {
1244        let regions = vec![MemoryRegion::new(&imp)];
1245        Self {
1246            inner: Arc::new(GuestMemoryInner {
1247                imp,
1248                debug_name,
1249                region_def: RegionDefinition {
1250                    invalid_mask: 1 << 63,
1251                    region_mask: !0 >> 1,
1252                    region_bits: 63, // right shift of 64 isn't valid, so restrict the space
1253                },
1254                regions,
1255                allocated,
1256            }),
1257        }
1258    }
1259
1260    /// Creates a new multi-region guest memory, made up of multiple mappings.
1261    /// This allows you to create a very large sparse layout (up to the limits
1262    /// of the VM's physical address space) without having to allocate an
1263    /// enormous amount of virtual address space.
1264    ///
1265    /// Each region will be `region_size` bytes and will start immediately after
1266    /// the last one. This must be a power of two, be at least a page in size,
1267    /// and cannot fill the full 64-bit address space.
1268    ///
1269    /// `imps` must be a list of [`GuestMemoryAccess`] implementations, one for
1270    /// each region. Use `None` if the corresponding region is empty.
1271    ///
1272    /// A region's mapping cannot fully fill the region. This is necessary to
1273    /// avoid callers expecting to be able to access a memory range that spans
1274    /// two regions.
1275    pub fn new_multi_region(
1276        debug_name: impl Into<Arc<str>>,
1277        region_size: u64,
1278        mut imps: Vec<Option<impl GuestMemoryAccess>>,
1279    ) -> Result<Self, MultiRegionError> {
1280        // Install signal handlers on unix.
1281        sparse_mmap::initialize_try_copy();
1282
1283        if !region_size.is_power_of_two() {
1284            return Err(MultiRegionError::NotPowerOfTwo(region_size));
1285        }
1286        if region_size < PAGE_SIZE64 {
1287            return Err(MultiRegionError::RegionSizeTooSmall(region_size));
1288        }
1289        let region_bits = region_size.trailing_zeros();
1290
1291        let max_region_count = 1 << (63 - region_bits);
1292
1293        let region_count = imps.len().next_power_of_two();
1294        if region_count > max_region_count {
1295            return Err(MultiRegionError::TooManyRegions {
1296                region_count,
1297                max_region_count,
1298                region_size,
1299            });
1300        }
1301
1302        let valid_bits = region_bits + region_count.trailing_zeros();
1303        assert!(valid_bits < 64);
1304        let invalid_mask = !0 << valid_bits;
1305
1306        let mut regions = vec![MemoryRegion::default(); region_count];
1307        for (imp, region) in imps.iter().zip(&mut regions) {
1308            let Some(imp) = imp else { continue };
1309            let backing_size = imp.max_address();
1310            if backing_size > region_size {
1311                return Err(MultiRegionError::BackingTooLarge {
1312                    backing_size,
1313                    region_size,
1314                });
1315            }
1316            *region = MemoryRegion::new(imp);
1317        }
1318
1319        let region_def = RegionDefinition {
1320            invalid_mask,
1321            region_mask: region_size - 1,
1322            region_bits,
1323        };
1324
1325        imps.resize_with(region_count, || None);
1326        let imp = MultiRegionGuestMemoryAccess { imps, region_def };
1327
1328        let inner = GuestMemoryInner {
1329            debug_name: debug_name.into(),
1330            region_def,
1331            regions,
1332            imp,
1333            allocated: false,
1334        };
1335
1336        Ok(Self {
1337            inner: Arc::new(inner),
1338        })
1339    }
1340
1341    /// Allocates a guest memory object on the heap with the given size in
1342    /// bytes.
1343    ///
1344    /// `size` will be rounded up to the page size. The backing buffer will be
1345    /// page aligned.
1346    ///
1347    /// The debug name in errors will be "heap". If you want to provide a
1348    /// different debug name, manually use `GuestMemory::new` with
1349    /// [`AlignedHeapMemory`].
1350    pub fn allocate(size: usize) -> Self {
1351        Self::new_inner("heap".into(), AlignedHeapMemory::new(size), true)
1352    }
1353
1354    /// If this memory is unaliased and was created via
1355    /// [`GuestMemory::allocate`], returns the backing buffer.
1356    ///
1357    /// Returns `Err(self)` if there are other references to this memory (via
1358    /// `clone()`).
1359    pub fn into_inner_buf(self) -> Result<AlignedHeapMemory, Self> {
1360        if !self.inner.allocated {
1361            return Err(self);
1362        }
1363        // FUTURE: consider using `Any` and `Arc::downcast` once trait upcasting is stable.
1364        // SAFETY: the inner implementation is guaranteed to be a `AlignedHeapMemory`.
1365        let inner = unsafe {
1366            Arc::<GuestMemoryInner<AlignedHeapMemory>>::from_raw(Arc::into_raw(self.inner).cast())
1367        };
1368        let inner = Arc::try_unwrap(inner).map_err(|inner| Self { inner })?;
1369        Ok(inner.imp)
1370    }
1371
1372    /// If this memory was created via [`GuestMemory::allocate`], returns a slice to
1373    /// the allocated buffer.
1374    pub fn inner_buf(&self) -> Option<&[AtomicU8]> {
1375        if !self.inner.allocated {
1376            return None;
1377        }
1378        // FUTURE: consider using `<dyn Any>::downcast` once trait upcasting is stable.
1379        // SAFETY: the inner implementation is guaranteed to be a `AlignedHeapMemory`.
1380        let inner = unsafe { &*core::ptr::from_ref(&self.inner.imp).cast::<AlignedHeapMemory>() };
1381        Some(inner)
1382    }
1383
1384    /// If this memory was created via [`GuestMemory::allocate`] and there are
1385    /// no other references to it, returns a mutable slice to the backing
1386    /// buffer.
1387    pub fn inner_buf_mut(&mut self) -> Option<&mut [u8]> {
1388        if !self.inner.allocated {
1389            return None;
1390        }
1391        let inner = Arc::get_mut(&mut self.inner)?;
1392        // FUTURE: consider using `<dyn Any>::downcast` once trait upcasting is stable.
1393        // SAFETY: the inner implementation is guaranteed to be a `AlignedHeapMemory`.
1394        let imp = unsafe { &mut *core::ptr::from_mut(&mut inner.imp).cast::<AlignedHeapMemory>() };
1395        Some(imp.as_mut())
1396    }
1397
1398    /// Returns an empty guest memory, which fails every operation.
1399    pub fn empty() -> Self {
1400        GuestMemory::new("empty", Empty)
1401    }
1402
1403    fn wrap_err(
1404        &self,
1405        gpa_len: Option<(u64, u64)>,
1406        op: GuestMemoryOperation,
1407        err: GuestMemoryBackingError,
1408    ) -> GuestMemoryError {
1409        let range = gpa_len.map(|(gpa, len)| (gpa..gpa.wrapping_add(len)));
1410        GuestMemoryError::new(&self.inner.debug_name, range, op, err)
1411    }
1412
1413    fn with_op<T>(
1414        &self,
1415        gpa_len: Option<(u64, u64)>,
1416        op: GuestMemoryOperation,
1417        f: impl FnOnce() -> Result<T, GuestMemoryBackingError>,
1418    ) -> Result<T, GuestMemoryError> {
1419        f().map_err(|err| self.wrap_err(gpa_len, op, err))
1420    }
1421
1422    /// Creates a smaller view into guest memory, constraining accesses within the new boundaries. For smaller ranges,
1423    /// some memory implementations (e.g. HDV) may choose to lock the pages into memory for faster access. Locking
1424    /// random guest memory may cause issues, so only opt in to this behavior when the range can be considered "owned"
1425    /// by the caller.
1426    pub fn subrange(
1427        &self,
1428        offset: u64,
1429        len: u64,
1430        allow_preemptive_locking: bool,
1431    ) -> Result<GuestMemory, GuestMemoryError> {
1432        self.with_op(Some((offset, len)), GuestMemoryOperation::Subrange, || {
1433            if let Some(guest_memory) =
1434                self.inner
1435                    .imp
1436                    .subrange(offset, len, allow_preemptive_locking)?
1437            {
1438                Ok(guest_memory)
1439            } else {
1440                create_memory_subrange(self.inner.clone(), offset, len, allow_preemptive_locking)
1441            }
1442        })
1443    }
1444
1445    /// Returns a subrange where pages from the subrange can be locked.
1446    pub fn lockable_subrange(
1447        &self,
1448        offset: u64,
1449        len: u64,
1450    ) -> Result<GuestMemory, GuestMemoryError> {
1451        // TODO: Enforce subrange is actually lockable.
1452        self.subrange(offset, len, true)
1453    }
1454
1455    /// Returns the mapping for all of guest memory.
1456    ///
1457    /// Returns `None` if there is more than one region or if the memory is not
1458    /// mapped.
1459    pub fn full_mapping(&self) -> Option<(*mut u8, usize)> {
1460        if let [region] = self.inner.regions.as_slice() {
1461            #[cfg(feature = "bitmap")]
1462            if region.bitmaps.is_some() {
1463                return None;
1464            }
1465            region
1466                .mapping
1467                .map(|SendPtrU8(ptr)| (ptr.as_ptr(), region.len as usize))
1468        } else {
1469            None
1470        }
1471    }
1472
1473    /// Gets the IO address for DMAing to `gpa` from a user-mode driver not
1474    /// going through an IOMMU.
1475    pub fn iova(&self, gpa: u64) -> Option<u64> {
1476        let (region, offset, _) = self.inner.region(gpa, 1).ok()?;
1477        Some(region.base_iova? + offset)
1478    }
1479
1480    /// Gets a pointer to the VA range for `gpa..gpa+len`.
1481    ///
1482    /// Returns `Ok(None)` if there is no mapping. Returns `Err(_)` if the
1483    /// memory is out of range.
1484    fn mapping_range(
1485        &self,
1486        access_type: AccessType,
1487        gpa: u64,
1488        len: usize,
1489    ) -> Result<Option<*mut u8>, GuestMemoryBackingError> {
1490        let (region, offset, _) = self.inner.region(gpa, len as u64)?;
1491        if let Some(SendPtrU8(ptr)) = region.mapping {
1492            loop {
1493                // SAFETY: offset + len is checked by `region()` to be inside the VA range.
1494                let fault_offset = unsafe {
1495                    match region.check_access(access_type, offset, len as u64) {
1496                        Ok(()) => return Ok(Some(ptr.as_ptr().add(offset as usize))),
1497                        Err(n) => n,
1498                    }
1499                };
1500
1501                // Resolve the fault and try again.
1502                match self.inner.imp.page_fault(
1503                    gpa + fault_offset,
1504                    len - fault_offset as usize,
1505                    access_type == AccessType::Write,
1506                    true,
1507                ) {
1508                    PageFaultAction::Fail(err) => {
1509                        return Err(GuestMemoryBackingError::new(
1510                            err.kind,
1511                            gpa + fault_offset,
1512                            err.err,
1513                        ));
1514                    }
1515                    PageFaultAction::Retry => {}
1516                    PageFaultAction::Fallback => break,
1517                }
1518            }
1519        }
1520        Ok(None)
1521    }
1522
1523    /// Runs `f` with a pointer to the mapped memory. If `f` fails, tries to
1524    /// resolve the fault (failing on error), then loops.
1525    ///
1526    /// If there is no mapping for the memory, or if the fault handler requests
1527    /// it, call `fallback` instead. `fallback` will not be called unless `gpa`
1528    /// and `len` are in range.
1529    fn run_on_mapping<T, P>(
1530        &self,
1531        access_type: AccessType,
1532        gpa: u64,
1533        len: usize,
1534        mut param: P,
1535        mut f: impl FnMut(&mut P, *mut u8) -> Result<T, sparse_mmap::MemoryError>,
1536        fallback: impl FnOnce(&mut P) -> Result<T, GuestMemoryBackingError>,
1537    ) -> Result<T, GuestMemoryBackingError> {
1538        let op = || {
1539            let Some(mapping) = self.mapping_range(access_type, gpa, len)? else {
1540                return fallback(&mut param);
1541            };
1542
1543            // Try until the fault fails to resolve.
1544            loop {
1545                match f(&mut param, mapping) {
1546                    Ok(t) => return Ok(t),
1547                    Err(fault) => {
1548                        match self.inner.imp.page_fault(
1549                            gpa + fault.offset() as u64,
1550                            len - fault.offset(),
1551                            access_type == AccessType::Write,
1552                            false,
1553                        ) {
1554                            PageFaultAction::Fail(err) => {
1555                                return Err(GuestMemoryBackingError::new(
1556                                    err.kind,
1557                                    gpa + fault.offset() as u64,
1558                                    err.err,
1559                                ));
1560                            }
1561                            PageFaultAction::Retry => {}
1562                            PageFaultAction::Fallback => return fallback(&mut param),
1563                        }
1564                    }
1565                }
1566            }
1567        };
1568        // If the `bitmap` feature is enabled, run the function in an RCU
1569        // critical section. This will allow callers to flush concurrent
1570        // accesses after bitmap updates.
1571        #[cfg(feature = "bitmap")]
1572        return rcu().run(op);
1573        #[cfg(not(feature = "bitmap"))]
1574        op()
1575    }
1576
1577    /// # Safety
1578    ///
1579    /// The caller must ensure that `src`..`src + len` is a valid buffer for reads.
1580    unsafe fn write_ptr(
1581        &self,
1582        gpa: u64,
1583        src: *const u8,
1584        len: usize,
1585    ) -> Result<(), GuestMemoryBackingError> {
1586        if len == 0 {
1587            return Ok(());
1588        }
1589        self.run_on_mapping(
1590            AccessType::Write,
1591            gpa,
1592            len,
1593            (),
1594            |(), dest| {
1595                // SAFETY: dest..dest+len is guaranteed to point to a reserved VA
1596                // range, and src..src+len is guaranteed by the caller to be a valid
1597                // buffer for reads.
1598                unsafe { sparse_mmap::try_copy(src, dest, len) }
1599            },
1600            |()| {
1601                // SAFETY: src..src+len is guaranteed by the caller to point to a valid
1602                // buffer for reads.
1603                unsafe { self.inner.imp.write_fallback(gpa, src, len) }
1604            },
1605        )
1606    }
1607
1608    /// Writes `src` into guest memory at address `gpa`.
1609    pub fn write_at(&self, gpa: u64, src: &[u8]) -> Result<(), GuestMemoryError> {
1610        self.with_op(
1611            Some((gpa, src.len() as u64)),
1612            GuestMemoryOperation::Write,
1613            || self.write_at_inner(gpa, src),
1614        )
1615    }
1616
1617    fn write_at_inner(&self, gpa: u64, src: &[u8]) -> Result<(), GuestMemoryBackingError> {
1618        // SAFETY: `src` is a valid buffer for reads.
1619        unsafe { self.write_ptr(gpa, src.as_ptr(), src.len()) }
1620    }
1621
1622    /// Writes `src` into guest memory at address `gpa`.
1623    pub fn write_from_atomic(&self, gpa: u64, src: &[AtomicU8]) -> Result<(), GuestMemoryError> {
1624        self.with_op(
1625            Some((gpa, src.len() as u64)),
1626            GuestMemoryOperation::Write,
1627            || {
1628                // SAFETY: `src` is a valid buffer for reads.
1629                unsafe { self.write_ptr(gpa, src.as_ptr().cast(), src.len()) }
1630            },
1631        )
1632    }
1633
1634    /// Writes `len` bytes of `val` into guest memory at address `gpa`.
1635    pub fn fill_at(&self, gpa: u64, val: u8, len: usize) -> Result<(), GuestMemoryError> {
1636        self.with_op(Some((gpa, len as u64)), GuestMemoryOperation::Fill, || {
1637            self.fill_at_inner(gpa, val, len)
1638        })
1639    }
1640
1641    fn fill_at_inner(&self, gpa: u64, val: u8, len: usize) -> Result<(), GuestMemoryBackingError> {
1642        if len == 0 {
1643            return Ok(());
1644        }
1645        self.run_on_mapping(
1646            AccessType::Write,
1647            gpa,
1648            len,
1649            (),
1650            |(), dest| {
1651                // SAFETY: dest..dest+len is guaranteed to point to a reserved VA range.
1652                unsafe { sparse_mmap::try_write_bytes(dest, val, len) }
1653            },
1654            |()| self.inner.imp.fill_fallback(gpa, val, len),
1655        )
1656    }
1657
1658    /// Reads from guest memory into `dest..dest+len`.
1659    ///
1660    /// # Safety
1661    /// The caller must ensure dest..dest+len is a valid buffer for writes.
1662    unsafe fn read_ptr(
1663        &self,
1664        gpa: u64,
1665        dest: *mut u8,
1666        len: usize,
1667    ) -> Result<(), GuestMemoryBackingError> {
1668        if len == 0 {
1669            return Ok(());
1670        }
1671        self.run_on_mapping(
1672            AccessType::Read,
1673            gpa,
1674            len,
1675            (),
1676            |(), src| {
1677                // SAFETY: src..src+len is guaranteed to point to a reserved VA
1678                // range, and dest..dest+len is guaranteed by the caller to be a
1679                // valid buffer for writes.
1680                unsafe { sparse_mmap::try_copy(src, dest, len) }
1681            },
1682            |()| {
1683                // SAFETY: dest..dest+len is guaranteed by the caller to point to a
1684                // valid buffer for writes.
1685                unsafe { self.inner.imp.read_fallback(gpa, dest, len) }
1686            },
1687        )
1688    }
1689
1690    fn read_at_inner(&self, gpa: u64, dest: &mut [u8]) -> Result<(), GuestMemoryBackingError> {
1691        // SAFETY: `dest` is a valid buffer for writes.
1692        unsafe { self.read_ptr(gpa, dest.as_mut_ptr(), dest.len()) }
1693    }
1694
1695    /// Reads from guest memory address `gpa` into `dest`.
1696    pub fn read_at(&self, gpa: u64, dest: &mut [u8]) -> Result<(), GuestMemoryError> {
1697        self.with_op(
1698            Some((gpa, dest.len() as u64)),
1699            GuestMemoryOperation::Read,
1700            || self.read_at_inner(gpa, dest),
1701        )
1702    }
1703
1704    /// Reads from guest memory address `gpa` into `dest`.
1705    pub fn read_to_atomic(&self, gpa: u64, dest: &[AtomicU8]) -> Result<(), GuestMemoryError> {
1706        self.with_op(
1707            Some((gpa, dest.len() as u64)),
1708            GuestMemoryOperation::Read,
1709            // SAFETY: `dest` is a valid buffer for writes.
1710            || unsafe { self.read_ptr(gpa, dest.as_ptr() as *mut u8, dest.len()) },
1711        )
1712    }
1713
1714    /// Writes an object to guest memory at address `gpa`.
1715    ///
1716    /// If the object is 1, 2, 4, or 8 bytes and the address is naturally
1717    /// aligned, then the write will be performed atomically. Here, this means
1718    /// that concurrent readers (via `read_plain`) cannot observe a torn write
1719    /// but will observe either the old or new value.
1720    ///
1721    /// The memory ordering of the write is unspecified.
1722    ///
1723    /// FUTURE: once we are on Rust 1.79, add a method specifically for atomic
1724    /// accesses that const asserts that the size is appropriate.
1725    pub fn write_plain<T: IntoBytes + Immutable + KnownLayout>(
1726        &self,
1727        gpa: u64,
1728        b: &T,
1729    ) -> Result<(), GuestMemoryError> {
1730        // Note that this is const, so the match below will compile out.
1731        let len = size_of::<T>();
1732        self.with_op(Some((gpa, len as u64)), GuestMemoryOperation::Write, || {
1733            self.run_on_mapping(
1734                AccessType::Write,
1735                gpa,
1736                len,
1737                (),
1738                |(), dest| {
1739                    match len {
1740                        1 | 2 | 4 | 8 => {
1741                            // SAFETY: dest..dest+len is guaranteed to point to
1742                            // a reserved VA range.
1743                            unsafe { sparse_mmap::try_write_volatile(dest.cast(), b) }
1744                        }
1745                        _ => {
1746                            // SAFETY: dest..dest+len is guaranteed to point to
1747                            // a reserved VA range.
1748                            unsafe { sparse_mmap::try_copy(b.as_bytes().as_ptr(), dest, len) }
1749                        }
1750                    }
1751                },
1752                |()| {
1753                    // SAFETY: b is a valid buffer for reads.
1754                    unsafe {
1755                        self.inner
1756                            .imp
1757                            .write_fallback(gpa, b.as_bytes().as_ptr(), len)
1758                    }
1759                },
1760            )
1761        })
1762    }
1763
1764    /// Attempts a sequentially-consistent compare exchange of the value at `gpa`.
1765    pub fn compare_exchange<T: IntoBytes + FromBytes + Immutable + KnownLayout + Copy>(
1766        &self,
1767        gpa: u64,
1768        current: T,
1769        new: T,
1770    ) -> Result<Result<T, T>, GuestMemoryError> {
1771        let len = size_of_val(&new);
1772        self.with_op(
1773            Some((gpa, len as u64)),
1774            GuestMemoryOperation::CompareExchange,
1775            || {
1776                // Assume that if write is allowed, then read is allowed.
1777                self.run_on_mapping(
1778                    AccessType::Write,
1779                    gpa,
1780                    len,
1781                    (),
1782                    |(), dest| {
1783                        // SAFETY: dest..dest+len is guaranteed by the caller to be a valid
1784                        // buffer for writes.
1785                        unsafe { sparse_mmap::try_compare_exchange(dest.cast(), current, new) }
1786                    },
1787                    |()| {
1788                        let mut current = current;
1789                        let success = self.inner.imp.compare_exchange_fallback(
1790                            gpa,
1791                            current.as_mut_bytes(),
1792                            new.as_bytes(),
1793                        )?;
1794
1795                        Ok(if success { Ok(new) } else { Err(current) })
1796                    },
1797                )
1798            },
1799        )
1800    }
1801
1802    /// Attempts a sequentially-consistent compare exchange of the value at `gpa`.
1803    pub fn compare_exchange_bytes<T: IntoBytes + FromBytes + Immutable + KnownLayout + ?Sized>(
1804        &self,
1805        gpa: u64,
1806        current: &mut T,
1807        new: &T,
1808    ) -> Result<bool, GuestMemoryError> {
1809        let len = size_of_val(new);
1810        assert_eq!(size_of_val(current), len);
1811        self.with_op(
1812            Some((gpa, len as u64)),
1813            GuestMemoryOperation::CompareExchange,
1814            || {
1815                // Assume that if write is allowed, then read is allowed.
1816                self.run_on_mapping(
1817                    AccessType::Write,
1818                    gpa,
1819                    len,
1820                    current,
1821                    |current, dest| {
1822                        // SAFETY: dest..dest+len is guaranteed by the caller to be a valid
1823                        // buffer for writes.
1824                        unsafe { sparse_mmap::try_compare_exchange_ref(dest, *current, new) }
1825                    },
1826                    |current| {
1827                        let success = self.inner.imp.compare_exchange_fallback(
1828                            gpa,
1829                            current.as_mut_bytes(),
1830                            new.as_bytes(),
1831                        )?;
1832
1833                        Ok(success)
1834                    },
1835                )
1836            },
1837        )
1838    }
1839
1840    /// Reads an object from guest memory at address `gpa`.
1841    ///
1842    /// If the object is 1, 2, 4, or 8 bytes and the address is naturally
1843    /// aligned, then the read will be performed atomically. Here, this means
1844    /// that when there is a concurrent writer, callers will observe either the
1845    /// old or new value, but not a torn read.
1846    ///
1847    /// The memory ordering of the read is unspecified.
1848    ///
1849    /// FUTURE: once we are on Rust 1.79, add a method specifically for atomic
1850    /// accesses that const asserts that the size is appropriate.
1851    pub fn read_plain<T: FromBytes + Immutable + KnownLayout>(
1852        &self,
1853        gpa: u64,
1854    ) -> Result<T, GuestMemoryError> {
1855        // Note that this is const, so the match below will compile out.
1856        let len = size_of::<T>();
1857        self.with_op(Some((gpa, len as u64)), GuestMemoryOperation::Read, || {
1858            self.run_on_mapping(
1859                AccessType::Read,
1860                gpa,
1861                len,
1862                (),
1863                |(), src| {
1864                    match len {
1865                        1 | 2 | 4 | 8 => {
1866                            // SAFETY: src..src+len is guaranteed to point to a reserved VA
1867                            // range.
1868                            unsafe { sparse_mmap::try_read_volatile(src.cast::<T>()) }
1869                        }
1870                        _ => {
1871                            let mut obj = std::mem::MaybeUninit::<T>::zeroed();
1872                            // SAFETY: src..src+len is guaranteed to point to a reserved VA
1873                            // range.
1874                            unsafe { sparse_mmap::try_copy(src, obj.as_mut_ptr().cast(), len)? };
1875                            // SAFETY: `obj` was fully initialized by `try_copy`.
1876                            Ok(unsafe { obj.assume_init() })
1877                        }
1878                    }
1879                },
1880                |()| {
1881                    let mut obj = std::mem::MaybeUninit::<T>::zeroed();
1882                    // SAFETY: dest..dest+len is guaranteed by the caller to point to a
1883                    // valid buffer for writes.
1884                    unsafe {
1885                        self.inner
1886                            .imp
1887                            .read_fallback(gpa, obj.as_mut_ptr().cast(), len)?;
1888                    }
1889                    // SAFETY: `obj` was fully initialized by `read_fallback`.
1890                    Ok(unsafe { obj.assume_init() })
1891                },
1892            )
1893        })
1894    }
1895
1896    fn probe_page_for_lock(
1897        &self,
1898        with_kernel_access: bool,
1899        gpa: u64,
1900    ) -> Result<*const AtomicU8, GuestMemoryBackingError> {
1901        let (region, offset, _) = self.inner.region(gpa, 1)?;
1902        let Some(SendPtrU8(ptr)) = region.mapping else {
1903            return Err(GuestMemoryBackingError::other(gpa, NotLockable));
1904        };
1905        // Ensure the virtual address can be exposed.
1906        if with_kernel_access {
1907            self.inner.imp.expose_va(gpa, 1)?;
1908        }
1909        let mut b = [0];
1910        // FUTURE: check the correct bitmap for the access type, which needs to
1911        // be passed in.
1912        self.read_at_inner(gpa, &mut b)?;
1913        // SAFETY: the read_at call includes a check that ensures that
1914        // `gpa` is in the VA range.
1915        let page = unsafe { ptr.as_ptr().add(offset as usize) };
1916        Ok(page.cast())
1917    }
1918
1919    pub fn lock_gpns(
1920        &self,
1921        with_kernel_access: bool,
1922        gpns: &[u64],
1923    ) -> Result<LockedPages, GuestMemoryError> {
1924        self.with_op(None, GuestMemoryOperation::Lock, || {
1925            let mut pages = Vec::with_capacity(gpns.len());
1926            for &gpn in gpns {
1927                let gpa = gpn_to_gpa(gpn).map_err(GuestMemoryBackingError::gpn)?;
1928                let page = self.probe_page_for_lock(with_kernel_access, gpa)?;
1929                pages.push(PagePtr(page));
1930            }
1931            let store_gpns = self.inner.imp.lock_gpns(gpns)?;
1932            Ok(LockedPages {
1933                pages: pages.into_boxed_slice(),
1934                gpns: store_gpns.then(|| gpns.to_vec().into_boxed_slice()),
1935                mem: self.inner.clone(),
1936            })
1937        })
1938    }
1939
1940    pub fn probe_gpns(&self, gpns: &[u64]) -> Result<(), GuestMemoryError> {
1941        self.with_op(None, GuestMemoryOperation::Probe, || {
1942            for &gpn in gpns {
1943                let mut b = [0];
1944                self.read_at_inner(
1945                    gpn_to_gpa(gpn).map_err(GuestMemoryBackingError::gpn)?,
1946                    &mut b,
1947                )?;
1948            }
1949            Ok(())
1950        })
1951    }
1952
1953    /// Check if a given GPA is readable or not.
1954    pub fn probe_gpa_readable(&self, gpa: u64) -> Result<(), GuestMemoryErrorKind> {
1955        let mut b = [0];
1956        self.read_at_inner(gpa, &mut b).map_err(|err| err.kind)
1957    }
1958
1959    /// Gets a slice of guest memory assuming the memory was already locked via
1960    /// [`GuestMemory::lock_gpns`].
1961    ///
1962    /// This is dangerous--if the pages have not been locked, then it could
1963    /// cause an access violation or guest memory corruption.
1964    ///
1965    /// Note that this is not `unsafe` since this cannot cause memory corruption
1966    /// in this process. Even if there is an access violation, the underlying VA
1967    /// space is known to be reserved.
1968    ///
1969    /// Panics if the requested buffer is out of range.
1970    fn dangerous_access_pre_locked_memory(&self, gpa: u64, len: usize) -> &[AtomicU8] {
1971        let addr = self
1972            .mapping_range(AccessType::Write, gpa, len)
1973            .unwrap()
1974            .unwrap();
1975        // SAFETY: addr..addr+len is checked above to be a valid VA range. It's
1976        // possible some of the pages aren't mapped and will cause AVs at
1977        // runtime when accessed, but, as discussed above, at a language level
1978        // this cannot cause any safety issues.
1979        unsafe { std::slice::from_raw_parts(addr.cast(), len) }
1980    }
1981
1982    fn op_range<F: FnMut(u64, Range<usize>) -> Result<(), GuestMemoryBackingError>>(
1983        &self,
1984        op: GuestMemoryOperation,
1985        range: &PagedRange<'_>,
1986        mut f: F,
1987    ) -> Result<(), GuestMemoryError> {
1988        self.with_op(None, op, || {
1989            let gpns = range.gpns();
1990            let offset = range.offset();
1991
1992            // Perform the operation in three phases: the first page (if it is not a
1993            // full page), the full pages, and the last page (if it is not a full
1994            // page).
1995            let mut byte_index = 0;
1996            let mut len = range.len();
1997            let mut page = 0;
1998            if offset % PAGE_SIZE != 0 {
1999                let head_len = std::cmp::min(len, PAGE_SIZE - (offset % PAGE_SIZE));
2000                let addr = gpn_to_gpa(gpns[page]).map_err(GuestMemoryBackingError::gpn)?
2001                    + offset as u64 % PAGE_SIZE64;
2002                f(addr, byte_index..byte_index + head_len)?;
2003                byte_index += head_len;
2004                len -= head_len;
2005                page += 1;
2006            }
2007            while len >= PAGE_SIZE {
2008                f(
2009                    gpn_to_gpa(gpns[page]).map_err(GuestMemoryBackingError::gpn)?,
2010                    byte_index..byte_index + PAGE_SIZE,
2011                )?;
2012                byte_index += PAGE_SIZE;
2013                len -= PAGE_SIZE;
2014                page += 1;
2015            }
2016            if len > 0 {
2017                f(
2018                    gpn_to_gpa(gpns[page]).map_err(GuestMemoryBackingError::gpn)?,
2019                    byte_index..byte_index + len,
2020                )?;
2021            }
2022
2023            Ok(())
2024        })
2025    }
2026
2027    pub fn write_range(&self, range: &PagedRange<'_>, data: &[u8]) -> Result<(), GuestMemoryError> {
2028        assert!(data.len() == range.len());
2029        self.op_range(GuestMemoryOperation::Write, range, move |addr, r| {
2030            self.write_at_inner(addr, &data[r])
2031        })
2032    }
2033
2034    pub fn fill_range(&self, range: &PagedRange<'_>, val: u8) -> Result<(), GuestMemoryError> {
2035        self.op_range(GuestMemoryOperation::Fill, range, move |addr, r| {
2036            self.fill_at_inner(addr, val, r.len())
2037        })
2038    }
2039
2040    pub fn zero_range(&self, range: &PagedRange<'_>) -> Result<(), GuestMemoryError> {
2041        self.op_range(GuestMemoryOperation::Fill, range, move |addr, r| {
2042            self.fill_at_inner(addr, 0, r.len())
2043        })
2044    }
2045
2046    pub fn read_range(
2047        &self,
2048        range: &PagedRange<'_>,
2049        data: &mut [u8],
2050    ) -> Result<(), GuestMemoryError> {
2051        assert!(data.len() == range.len());
2052        self.op_range(GuestMemoryOperation::Read, range, move |addr, r| {
2053            self.read_at_inner(addr, &mut data[r])
2054        })
2055    }
2056
2057    pub fn write_range_from_atomic(
2058        &self,
2059        range: &PagedRange<'_>,
2060        data: &[AtomicU8],
2061    ) -> Result<(), GuestMemoryError> {
2062        assert!(data.len() == range.len());
2063        self.op_range(GuestMemoryOperation::Write, range, move |addr, r| {
2064            let src = &data[r];
2065            // SAFETY: `src` is a valid buffer for reads.
2066            unsafe { self.write_ptr(addr, src.as_ptr().cast(), src.len()) }
2067        })
2068    }
2069
2070    pub fn read_range_to_atomic(
2071        &self,
2072        range: &PagedRange<'_>,
2073        data: &[AtomicU8],
2074    ) -> Result<(), GuestMemoryError> {
2075        assert!(data.len() == range.len());
2076        self.op_range(GuestMemoryOperation::Read, range, move |addr, r| {
2077            let dest = &data[r];
2078            // SAFETY: `dest` is a valid buffer for writes.
2079            unsafe { self.read_ptr(addr, dest.as_ptr().cast_mut().cast(), dest.len()) }
2080        })
2081    }
2082
2083    /// Locks the guest pages spanned by the specified `PagedRange` for the `'static` lifetime.
2084    ///
2085    /// # Arguments
2086    /// * 'paged_range' - The guest memory range to lock.
2087    /// * 'locked_range' - Receives a list of VA ranges to which each contiguous physical sub-range in `paged_range`
2088    ///   has been mapped. Must be initially empty.
2089    pub fn lock_range<T: LockedRange>(
2090        &self,
2091        paged_range: PagedRange<'_>,
2092        mut locked_range: T,
2093    ) -> Result<LockedRangeImpl<T>, GuestMemoryError> {
2094        self.with_op(None, GuestMemoryOperation::Lock, || {
2095            let gpns = paged_range.gpns();
2096            for &gpn in gpns {
2097                let gpa = gpn_to_gpa(gpn).map_err(GuestMemoryBackingError::gpn)?;
2098                self.probe_page_for_lock(true, gpa)?;
2099            }
2100            for range in paged_range.ranges() {
2101                let range = range.map_err(GuestMemoryBackingError::gpn)?;
2102                locked_range.push_sub_range(
2103                    self.dangerous_access_pre_locked_memory(range.start, range.len() as usize),
2104                );
2105            }
2106            let store_gpns = self.inner.imp.lock_gpns(paged_range.gpns())?;
2107            Ok(LockedRangeImpl {
2108                mem: self.inner.clone(),
2109                gpns: store_gpns.then(|| paged_range.gpns().to_vec().into_boxed_slice()),
2110                inner: locked_range,
2111            })
2112        })
2113    }
2114}
2115
2116#[derive(Debug, Error)]
2117#[error("invalid guest page number {0:#x}")]
2118pub struct InvalidGpn(u64);
2119
2120fn gpn_to_gpa(gpn: u64) -> Result<u64, InvalidGpn> {
2121    gpn.checked_mul(PAGE_SIZE64).ok_or(InvalidGpn(gpn))
2122}
2123
2124#[derive(Debug, Copy, Clone, Default)]
2125struct RegionDefinition {
2126    invalid_mask: u64,
2127    region_mask: u64,
2128    region_bits: u32,
2129}
2130
2131impl RegionDefinition {
2132    fn region(&self, gpa: u64, len: u64) -> Result<(usize, u64), GuestMemoryBackingError> {
2133        if (gpa | len) & self.invalid_mask != 0 {
2134            return Err(GuestMemoryBackingError::new(
2135                GuestMemoryErrorKind::OutOfRange,
2136                gpa,
2137                OutOfRange,
2138            ));
2139        }
2140        let offset = gpa & self.region_mask;
2141        if offset.wrapping_add(len) & !self.region_mask != 0 {
2142            return Err(GuestMemoryBackingError::new(
2143                GuestMemoryErrorKind::OutOfRange,
2144                gpa,
2145                OutOfRange,
2146            ));
2147        }
2148        let index = (gpa >> self.region_bits) as usize;
2149        Ok((index, offset))
2150    }
2151}
2152
2153impl GuestMemoryInner {
2154    fn region(
2155        &self,
2156        gpa: u64,
2157        len: u64,
2158    ) -> Result<(&MemoryRegion, u64, usize), GuestMemoryBackingError> {
2159        let (index, offset) = self.region_def.region(gpa, len)?;
2160        let region = &self.regions[index];
2161        if offset + len > region.len {
2162            return Err(GuestMemoryBackingError::new(
2163                GuestMemoryErrorKind::OutOfRange,
2164                gpa,
2165                OutOfRange,
2166            ));
2167        }
2168        Ok((&self.regions[index], offset, index))
2169    }
2170}
2171
2172#[derive(Clone)]
2173pub struct LockedPages {
2174    pages: Box<[PagePtr]>,
2175    gpns: Option<Box<[u64]>>,
2176    // maintain a reference to the backing memory
2177    mem: Arc<GuestMemoryInner>,
2178}
2179
2180impl Drop for LockedPages {
2181    fn drop(&mut self) {
2182        if let Some(gpns) = &self.gpns {
2183            self.mem.imp.unlock_gpns(gpns);
2184        }
2185    }
2186}
2187
2188impl Debug for LockedPages {
2189    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2190        f.debug_struct("LockedPages")
2191            .field("page_count", &self.pages.len())
2192            .finish()
2193    }
2194}
2195
2196#[derive(Copy, Clone, Debug)]
2197// Field is read via slice transmute and pointer casts, not actually dead.
2198struct PagePtr(#[expect(dead_code)] *const AtomicU8);
2199
2200// SAFETY: PagePtr is just a pointer with no methods and has no inherent safety
2201// constraints.
2202unsafe impl Send for PagePtr {}
2203// SAFETY: see above comment
2204unsafe impl Sync for PagePtr {}
2205
2206pub type Page = [AtomicU8; PAGE_SIZE];
2207
2208impl LockedPages {
2209    #[inline]
2210    pub fn pages(&self) -> &[&Page] {
2211        // SAFETY: PagePtr is just a pointer to a Page. The pages are kept alive by
2212        // the reference in _mem, and the lifetimes here ensure the LockedPages outlives
2213        // the slice.
2214        unsafe { std::slice::from_raw_parts(self.pages.as_ptr().cast::<&Page>(), self.pages.len()) }
2215    }
2216}
2217
2218impl<'a> AsRef<[&'a Page]> for &'a LockedPages {
2219    fn as_ref(&self) -> &[&'a Page] {
2220        self.pages()
2221    }
2222}
2223
2224/// Represents a range of locked guest pages as an ordered list of the VA sub-ranges
2225/// to which the guest pages are mapped.
2226/// The range may only partially span the first and last page and must fully span all
2227/// intermediate pages.
2228pub trait LockedRange {
2229    /// Adds a sub-range to this range.
2230    fn push_sub_range(&mut self, sub_range: &[AtomicU8]);
2231}
2232
2233pub struct LockedRangeImpl<T: LockedRange> {
2234    mem: Arc<GuestMemoryInner>,
2235    gpns: Option<Box<[u64]>>,
2236    inner: T,
2237}
2238
2239impl<T: LockedRange> LockedRangeImpl<T> {
2240    pub fn get(&self) -> &T {
2241        &self.inner
2242    }
2243}
2244
2245impl<T: LockedRange> Drop for LockedRangeImpl<T> {
2246    fn drop(&mut self) {
2247        if let Some(gpns) = &self.gpns {
2248            self.mem.imp.unlock_gpns(gpns);
2249        }
2250    }
2251}
2252
2253#[derive(Debug, Error)]
2254pub enum AccessError {
2255    #[error("memory access error")]
2256    Memory(#[from] GuestMemoryError),
2257    #[error("out of range: {0:#x} < {1:#x}")]
2258    OutOfRange(usize, usize),
2259    #[error("write attempted to read-only memory")]
2260    ReadOnly,
2261}
2262
2263pub trait MemoryRead {
2264    fn read(&mut self, data: &mut [u8]) -> Result<&mut Self, AccessError>;
2265    fn skip(&mut self, len: usize) -> Result<&mut Self, AccessError>;
2266    fn len(&self) -> usize;
2267
2268    fn read_plain<T: IntoBytes + FromBytes + Immutable + KnownLayout>(
2269        &mut self,
2270    ) -> Result<T, AccessError> {
2271        let mut value: T = FromZeros::new_zeroed();
2272        self.read(value.as_mut_bytes())?;
2273        Ok(value)
2274    }
2275
2276    fn read_n<T: IntoBytes + FromBytes + Immutable + KnownLayout + Copy>(
2277        &mut self,
2278        len: usize,
2279    ) -> Result<Vec<T>, AccessError> {
2280        let mut value = vec![FromZeros::new_zeroed(); len];
2281        self.read(value.as_mut_bytes())?;
2282        Ok(value)
2283    }
2284
2285    fn read_all(&mut self) -> Result<Vec<u8>, AccessError> {
2286        let mut value = vec![0; self.len()];
2287        self.read(&mut value)?;
2288        Ok(value)
2289    }
2290
2291    fn limit(self, len: usize) -> Limit<Self>
2292    where
2293        Self: Sized,
2294    {
2295        let len = len.min(self.len());
2296        Limit { inner: self, len }
2297    }
2298}
2299
2300/// A trait for sequentially updating a region of memory.
2301pub trait MemoryWrite {
2302    fn write(&mut self, data: &[u8]) -> Result<(), AccessError>;
2303    fn zero(&mut self, len: usize) -> Result<(), AccessError> {
2304        self.fill(0, len)
2305    }
2306    fn fill(&mut self, val: u8, len: usize) -> Result<(), AccessError>;
2307
2308    /// The space remaining in the memory region.
2309    fn len(&self) -> usize;
2310
2311    fn limit(self, len: usize) -> Limit<Self>
2312    where
2313        Self: Sized,
2314    {
2315        let len = len.min(self.len());
2316        Limit { inner: self, len }
2317    }
2318}
2319
2320impl MemoryRead for &'_ [u8] {
2321    fn read(&mut self, data: &mut [u8]) -> Result<&mut Self, AccessError> {
2322        if self.len() < data.len() {
2323            return Err(AccessError::OutOfRange(self.len(), data.len()));
2324        }
2325        let (source, rest) = self.split_at(data.len());
2326        data.copy_from_slice(source);
2327        *self = rest;
2328        Ok(self)
2329    }
2330
2331    fn skip(&mut self, len: usize) -> Result<&mut Self, AccessError> {
2332        if self.len() < len {
2333            return Err(AccessError::OutOfRange(self.len(), len));
2334        }
2335        *self = &self[len..];
2336        Ok(self)
2337    }
2338
2339    fn len(&self) -> usize {
2340        <[u8]>::len(self)
2341    }
2342}
2343
2344impl MemoryWrite for &mut [u8] {
2345    fn write(&mut self, data: &[u8]) -> Result<(), AccessError> {
2346        if self.len() < data.len() {
2347            return Err(AccessError::OutOfRange(self.len(), data.len()));
2348        }
2349        let (dest, rest) = std::mem::take(self).split_at_mut(data.len());
2350        dest.copy_from_slice(data);
2351        *self = rest;
2352        Ok(())
2353    }
2354
2355    fn fill(&mut self, val: u8, len: usize) -> Result<(), AccessError> {
2356        if self.len() < len {
2357            return Err(AccessError::OutOfRange(self.len(), len));
2358        }
2359        let (dest, rest) = std::mem::take(self).split_at_mut(len);
2360        dest.fill(val);
2361        *self = rest;
2362        Ok(())
2363    }
2364
2365    fn len(&self) -> usize {
2366        <[u8]>::len(self)
2367    }
2368}
2369
2370#[derive(Debug, Clone)]
2371pub struct Limit<T> {
2372    inner: T,
2373    len: usize,
2374}
2375
2376impl<T: MemoryRead> MemoryRead for Limit<T> {
2377    fn read(&mut self, data: &mut [u8]) -> Result<&mut Self, AccessError> {
2378        let len = data.len();
2379        if len > self.len {
2380            return Err(AccessError::OutOfRange(self.len, len));
2381        }
2382        self.inner.read(data)?;
2383        self.len -= len;
2384        Ok(self)
2385    }
2386
2387    fn skip(&mut self, len: usize) -> Result<&mut Self, AccessError> {
2388        if len > self.len {
2389            return Err(AccessError::OutOfRange(self.len, len));
2390        }
2391        self.inner.skip(len)?;
2392        self.len -= len;
2393        Ok(self)
2394    }
2395
2396    fn len(&self) -> usize {
2397        self.len
2398    }
2399}
2400
2401impl<T: MemoryWrite> MemoryWrite for Limit<T> {
2402    fn write(&mut self, data: &[u8]) -> Result<(), AccessError> {
2403        let len = data.len();
2404        if len > self.len {
2405            return Err(AccessError::OutOfRange(self.len, len));
2406        }
2407        self.inner.write(data)?;
2408        self.len -= len;
2409        Ok(())
2410    }
2411
2412    fn fill(&mut self, val: u8, len: usize) -> Result<(), AccessError> {
2413        if len > self.len {
2414            return Err(AccessError::OutOfRange(self.len, len));
2415        }
2416        self.inner.fill(val, len)?;
2417        self.len -= len;
2418        Ok(())
2419    }
2420
2421    fn len(&self) -> usize {
2422        self.len
2423    }
2424}
2425
2426/// Trait implemented to allow mapping and unmapping a region of memory at
2427/// a particular guest address.
2428pub trait MappableGuestMemory: Send + Sync {
2429    /// Maps the memory into the guest.
2430    ///
2431    /// `writable` specifies whether the guest can write to the memory region.
2432    /// If a guest tries to write to a non-writable region, the virtual
2433    /// processor will exit for MMIO handling.
2434    fn map_to_guest(&mut self, gpa: u64, writable: bool) -> io::Result<()>;
2435
2436    fn unmap_from_guest(&mut self);
2437}
2438
2439/// Trait implemented for a region of memory that can have memory mapped into
2440/// it.
2441pub trait MappedMemoryRegion: Send + Sync {
2442    /// Maps an object at `offset` in the region.
2443    ///
2444    /// Behaves like mmap--overwrites and splits existing mappings.
2445    fn map(
2446        &self,
2447        offset: usize,
2448        section: &dyn AsMappableRef,
2449        file_offset: u64,
2450        len: usize,
2451        writable: bool,
2452    ) -> io::Result<()>;
2453
2454    /// Unmaps any mappings in the specified range within the region.
2455    fn unmap(&self, offset: usize, len: usize) -> io::Result<()>;
2456}
2457
2458/// Trait implemented to allow the creation of memory regions.
2459pub trait MemoryMapper: Send + Sync {
2460    /// Creates a new memory region that can later be mapped into the guest.
2461    ///
2462    /// Returns both an interface for mapping/unmapping the region and for
2463    /// adding internal mappings.
2464    fn new_region(
2465        &self,
2466        len: usize,
2467        debug_name: String,
2468    ) -> io::Result<(Box<dyn MappableGuestMemory>, Arc<dyn MappedMemoryRegion>)>;
2469}
2470
2471/// Doorbell provides a mechanism to register for notifications on writes to specific addresses in guest memory.
2472pub trait DoorbellRegistration: Send + Sync {
2473    /// Register a doorbell event.
2474    fn register_doorbell(
2475        &self,
2476        guest_address: u64,
2477        value: Option<u64>,
2478        length: Option<u32>,
2479        event: &Event,
2480    ) -> io::Result<Box<dyn Send + Sync>>;
2481}
2482
2483/// Trait to map a ROM at one or more locations in guest memory.
2484pub trait MapRom: Send + Sync {
2485    /// Maps the specified portion of the ROM into guest memory at `gpa`.
2486    ///
2487    /// The returned object will implicitly unmap the ROM when dropped.
2488    fn map_rom(&self, gpa: u64, offset: u64, len: u64) -> io::Result<Box<dyn UnmapRom>>;
2489
2490    /// Returns the length of the ROM in bytes.
2491    fn len(&self) -> u64;
2492}
2493
2494/// Trait to unmap a ROM from guest memory.
2495pub trait UnmapRom: Send + Sync {
2496    /// Unmaps the ROM from guest memory.
2497    fn unmap_rom(self);
2498}
2499
2500#[cfg(test)]
2501#[expect(clippy::undocumented_unsafe_blocks)]
2502mod tests {
2503    use crate::GuestMemory;
2504    use crate::PAGE_SIZE64;
2505    use crate::PageFaultAction;
2506    use crate::PageFaultError;
2507    use sparse_mmap::SparseMapping;
2508    use std::ptr::NonNull;
2509    use std::sync::Arc;
2510    use thiserror::Error;
2511
2512    /// An implementation of a GuestMemoryAccess trait that expects all of
2513    /// guest memory to be mapped at a given base, with mmap or the Windows
2514    /// equivalent. Pages that are not backed by RAM will return failure
2515    /// when attempting to access them.
2516    pub struct GuestMemoryMapping {
2517        mapping: SparseMapping,
2518        #[cfg(feature = "bitmap")]
2519        bitmap: Option<Vec<u8>>,
2520    }
2521
2522    unsafe impl crate::GuestMemoryAccess for GuestMemoryMapping {
2523        fn mapping(&self) -> Option<NonNull<u8>> {
2524            NonNull::new(self.mapping.as_ptr().cast())
2525        }
2526
2527        fn max_address(&self) -> u64 {
2528            self.mapping.len() as u64
2529        }
2530
2531        #[cfg(feature = "bitmap")]
2532        fn access_bitmap(&self) -> Option<crate::BitmapInfo> {
2533            self.bitmap.as_ref().map(|bm| crate::BitmapInfo {
2534                read_bitmap: NonNull::new(bm.as_ptr().cast_mut()).unwrap(),
2535                write_bitmap: NonNull::new(bm.as_ptr().cast_mut()).unwrap(),
2536                bit_offset: 0,
2537            })
2538        }
2539    }
2540
2541    const PAGE_SIZE: usize = 4096;
2542    const SIZE_1MB: usize = 1048576;
2543
2544    /// Create a test guest layout:
2545    /// 0           -> 1MB          RAM
2546    /// 1MB         -> 2MB          empty
2547    /// 2MB         -> 3MB          RAM
2548    /// 3MB         -> 3MB + 4K     empty
2549    /// 3MB + 4K    -> 4MB          RAM
2550    fn create_test_mapping() -> GuestMemoryMapping {
2551        let mapping = SparseMapping::new(SIZE_1MB * 4).unwrap();
2552        mapping.alloc(0, SIZE_1MB).unwrap();
2553        mapping.alloc(2 * SIZE_1MB, SIZE_1MB).unwrap();
2554        mapping
2555            .alloc(3 * SIZE_1MB + PAGE_SIZE, SIZE_1MB - PAGE_SIZE)
2556            .unwrap();
2557
2558        GuestMemoryMapping {
2559            mapping,
2560            #[cfg(feature = "bitmap")]
2561            bitmap: None,
2562        }
2563    }
2564
2565    #[test]
2566    fn test_basic_read_write() {
2567        let mapping = create_test_mapping();
2568        let gm = GuestMemory::new("test", mapping);
2569
2570        // Test reading at 0.
2571        let addr = 0;
2572        let result = gm.read_plain::<u8>(addr);
2573        assert_eq!(result.unwrap(), 0);
2574
2575        // Test read/write to first page
2576        let write_buffer = [1, 2, 3, 4, 5];
2577        let mut read_buffer = [0; 5];
2578        gm.write_at(0, &write_buffer).unwrap();
2579        gm.read_at(0, &mut read_buffer).unwrap();
2580        assert_eq!(write_buffer, read_buffer);
2581        assert_eq!(gm.read_plain::<u8>(0).unwrap(), 1);
2582        assert_eq!(gm.read_plain::<u8>(1).unwrap(), 2);
2583        assert_eq!(gm.read_plain::<u8>(2).unwrap(), 3);
2584        assert_eq!(gm.read_plain::<u8>(3).unwrap(), 4);
2585        assert_eq!(gm.read_plain::<u8>(4).unwrap(), 5);
2586
2587        // Test read/write to page at 2MB
2588        let addr = 2 * SIZE_1MB as u64;
2589        let write_buffer: Vec<u8> = (0..PAGE_SIZE).map(|x| x as u8).collect();
2590        let mut read_buffer: Vec<u8> = (0..PAGE_SIZE).map(|_| 0).collect();
2591        gm.write_at(addr, write_buffer.as_slice()).unwrap();
2592        gm.read_at(addr, read_buffer.as_mut_slice()).unwrap();
2593        assert_eq!(write_buffer, read_buffer);
2594
2595        // Test read/write to first 1MB
2596        let write_buffer: Vec<u8> = (0..SIZE_1MB).map(|x| x as u8).collect();
2597        let mut read_buffer: Vec<u8> = (0..SIZE_1MB).map(|_| 0).collect();
2598        gm.write_at(addr, write_buffer.as_slice()).unwrap();
2599        gm.read_at(addr, read_buffer.as_mut_slice()).unwrap();
2600        assert_eq!(write_buffer, read_buffer);
2601
2602        // Test bad read at 1MB
2603        let addr = SIZE_1MB as u64;
2604        let result = gm.read_plain::<u8>(addr);
2605        assert!(result.is_err());
2606    }
2607
2608    #[test]
2609    fn test_multi() {
2610        let len = SIZE_1MB * 4;
2611        let mapping = SparseMapping::new(len).unwrap();
2612        mapping.alloc(0, len).unwrap();
2613        let mapping = Arc::new(GuestMemoryMapping {
2614            mapping,
2615            #[cfg(feature = "bitmap")]
2616            bitmap: None,
2617        });
2618        let region_len = 1 << 30;
2619        let gm = GuestMemory::new_multi_region(
2620            "test",
2621            region_len,
2622            vec![Some(mapping.clone()), None, Some(mapping.clone())],
2623        )
2624        .unwrap();
2625
2626        let mut b = [0];
2627        let len = len as u64;
2628        gm.read_at(0, &mut b).unwrap();
2629        gm.read_at(len, &mut b).unwrap_err();
2630        gm.read_at(region_len, &mut b).unwrap_err();
2631        gm.read_at(2 * region_len, &mut b).unwrap();
2632        gm.read_at(2 * region_len + len, &mut b).unwrap_err();
2633        gm.read_at(3 * region_len, &mut b).unwrap_err();
2634    }
2635
2636    #[cfg(feature = "bitmap")]
2637    #[test]
2638    fn test_bitmap() {
2639        let len = PAGE_SIZE * 4;
2640        let mapping = SparseMapping::new(len).unwrap();
2641        mapping.alloc(0, len).unwrap();
2642        let bitmap = vec![0b0101];
2643        let mapping = Arc::new(GuestMemoryMapping {
2644            mapping,
2645            bitmap: Some(bitmap),
2646        });
2647        let gm = GuestMemory::new("test", mapping);
2648
2649        gm.read_plain::<[u8; 1]>(0).unwrap();
2650        gm.read_plain::<[u8; 1]>(PAGE_SIZE64 - 1).unwrap();
2651        gm.read_plain::<[u8; 2]>(PAGE_SIZE64 - 1).unwrap_err();
2652        gm.read_plain::<[u8; 1]>(PAGE_SIZE64).unwrap_err();
2653        gm.read_plain::<[u8; 1]>(PAGE_SIZE64 * 2).unwrap();
2654        gm.read_plain::<[u8; PAGE_SIZE * 2]>(0).unwrap_err();
2655    }
2656
2657    struct FaultingMapping {
2658        mapping: SparseMapping,
2659    }
2660
2661    #[derive(Debug, Error)]
2662    #[error("fault")]
2663    struct Fault;
2664
2665    unsafe impl crate::GuestMemoryAccess for FaultingMapping {
2666        fn mapping(&self) -> Option<NonNull<u8>> {
2667            NonNull::new(self.mapping.as_ptr().cast())
2668        }
2669
2670        fn max_address(&self) -> u64 {
2671            self.mapping.len() as u64
2672        }
2673
2674        fn page_fault(
2675            &self,
2676            address: u64,
2677            _len: usize,
2678            write: bool,
2679            bitmap_failure: bool,
2680        ) -> PageFaultAction {
2681            assert!(!bitmap_failure);
2682            let qlen = self.mapping.len() as u64 / 4;
2683            if address < qlen || address >= 3 * qlen {
2684                return PageFaultAction::Fail(PageFaultError::other(Fault));
2685            }
2686            let page_address = (address as usize) & !(PAGE_SIZE - 1);
2687            if address >= 2 * qlen {
2688                if write {
2689                    return PageFaultAction::Fail(PageFaultError::other(Fault));
2690                }
2691                self.mapping.map_zero(page_address, PAGE_SIZE).unwrap();
2692            } else {
2693                self.mapping.alloc(page_address, PAGE_SIZE).unwrap();
2694            }
2695            PageFaultAction::Retry
2696        }
2697    }
2698
2699    impl FaultingMapping {
2700        fn new(len: usize) -> Self {
2701            let mapping = SparseMapping::new(len).unwrap();
2702            FaultingMapping { mapping }
2703        }
2704    }
2705
2706    #[test]
2707    fn test_fault() {
2708        let len = PAGE_SIZE * 4;
2709        let mapping = FaultingMapping::new(len);
2710        let gm = GuestMemory::new("test", mapping);
2711
2712        gm.write_plain::<u8>(0, &0).unwrap_err();
2713        gm.read_plain::<u8>(PAGE_SIZE64 - 1).unwrap_err();
2714        gm.read_plain::<u8>(PAGE_SIZE64).unwrap();
2715        gm.write_plain::<u8>(PAGE_SIZE64, &0).unwrap();
2716        gm.write_plain::<u16>(PAGE_SIZE64 * 3 - 1, &0).unwrap_err();
2717        gm.read_plain::<u16>(PAGE_SIZE64 * 3 - 1).unwrap_err();
2718        gm.read_plain::<u8>(PAGE_SIZE64 * 3 - 1).unwrap();
2719        gm.write_plain::<u8>(PAGE_SIZE64 * 3 - 1, &0).unwrap_err();
2720    }
2721
2722    #[test]
2723    fn test_allocated() {
2724        let mut gm = GuestMemory::allocate(0x10000);
2725        let pattern = [0x42; 0x10000];
2726        gm.write_at(0, &pattern).unwrap();
2727        assert_eq!(gm.inner_buf_mut().unwrap(), &pattern);
2728        gm.inner_buf().unwrap();
2729        let gm2 = gm.clone();
2730        assert!(gm.inner_buf_mut().is_none());
2731        gm.inner_buf().unwrap();
2732        let mut gm = gm.into_inner_buf().unwrap_err();
2733        drop(gm2);
2734        assert_eq!(gm.inner_buf_mut().unwrap(), &pattern);
2735        gm.into_inner_buf().unwrap();
2736    }
2737}