[RFC 23/26] rust/memory: Implement vm_memory::GuestMemory for FlatView

[Zhao Liu <zhao1.liu@intel.com>]

Implement vm_memory::GuestMemory for FlafView, and provide memory
write/read/store/load bindings.

At the meanwhile, add a RAII guard to help protect FlatView's life
time at Rust side.

Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 rust/qemu-api/src/memory.rs | 433 +++++++++++++++++++++++++++++++++++-
 1 file changed, 429 insertions(+), 4 deletions(-)

diff --git a/rust/qemu-api/src/memory.rs b/rust/qemu-api/src/memory.rs
index c8faa3b9c1e9..23347f35e5da 100644
--- a/rust/qemu-api/src/memory.rs
+++ b/rust/qemu-api/src/memory.rs
@@ -2,8 +2,8 @@
 // Author(s): Paolo Bonzini <pbonzini@redhat.com>
 // SPDX-License-Identifier: GPL-2.0-or-later
 
-//! Bindings for `MemoryRegion`, `MemoryRegionOps`, `MemTxAttrs` and
-//! `MemoryRegionSection`.
+//! Bindings for `MemoryRegion`, `MemoryRegionOps`, `MemTxAttrs`
+//! `MemoryRegionSection` and `FlatView`.
 
 use std::{
     ffi::{c_uint, c_void, CStr, CString},
@@ -11,6 +11,7 @@
     marker::PhantomData,
     mem::size_of,
     ops::Deref,
+    ptr::NonNull,
     sync::atomic::Ordering,
 };
 
@@ -18,13 +19,14 @@
 pub use bindings::{hwaddr, MemTxAttrs};
 pub use vm_memory::GuestAddress;
 use vm_memory::{
-    bitmap::BS, Address, AtomicAccess, Bytes, GuestMemoryError, GuestMemoryRegion,
+    bitmap::BS, Address, AtomicAccess, Bytes, GuestMemory, GuestMemoryError, GuestMemoryRegion,
     GuestMemoryResult, GuestUsize, MemoryRegionAddress, ReadVolatile, VolatileSlice, WriteVolatile,
 };
 
 use crate::{
     bindings::{
-        self, device_endian, memory_region_init_io, section_access_allowed,
+        self, address_space_lookup_section, device_endian, flatview_ref,
+        flatview_translate_section, flatview_unref, memory_region_init_io, section_access_allowed,
         section_covers_region_addr, section_fuzz_dma_read, section_get_host_addr,
         section_rust_load, section_rust_read_continue_step, section_rust_store,
         section_rust_write_continue_step, MEMTX_OK,
@@ -591,3 +593,426 @@ fn get_slice(
         unimplemented!()
     }
 }
+
+/// A safe wrapper around [`bindings::FlatView`].
+///
+/// [`Flaftview`] represents a collection of memory regions, and maps to
+/// [`GuestMemoryRegion`](vm_memory::GuestMemoryRegion).
+///
+/// The memory details are hidden beneath this wrapper. Direct memory access
+/// is not allowed.  Instead, memory access, e.g., write/read/store/load
+/// should process through [`Bytes<GuestAddress>`].
+#[repr(transparent)]
+#[derive(qemu_api_macros::Wrapper)]
+pub struct FlatView(Opaque<bindings::FlatView>);
+
+unsafe impl Send for FlatView {}
+unsafe impl Sync for FlatView {}
+
+impl Deref for FlatView {
+    type Target = bindings::FlatView;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: Opaque<> wraps a pointer from C side. The validity
+        // of the pointer is confirmed at the creation of Opaque<>.
+        unsafe { &*self.0.as_ptr() }
+    }
+}
+
+impl FlatView {
+    /// Translate guest address to the offset within a MemoryRegionSection.
+    ///
+    /// Ideally, this helper should be integrated into
+    /// GuestMemory::to_region_addr(), but we haven't reached there yet.
+    fn translate(
+        &self,
+        addr: GuestAddress,
+        len: GuestUsize,
+        is_write: bool,
+    ) -> Option<(&MemoryRegionSection, MemoryRegionAddress, GuestUsize)> {
+        let mut remain = len as hwaddr;
+        let mut raw_addr: hwaddr = 0;
+
+        // SAFETY: the pointers and reference are convertible and the
+        // offset conversion is considerred.
+        let ptr = unsafe {
+            flatview_translate_section(
+                self.as_mut_ptr(),
+                addr.raw_value(),
+                &mut raw_addr,
+                &mut remain,
+                is_write,
+                MEMTXATTRS_UNSPECIFIED,
+            )
+        };
+
+        if ptr.is_null() {
+            return None;
+        }
+
+        // SAFETY: the pointer is valid and not NULL.
+        let s = unsafe { <FlatView as GuestMemory>::R::from_raw(ptr) };
+        Some((
+            s,
+            MemoryRegionAddress(raw_addr)
+                .checked_sub(s.deref().offset_within_region)
+                .unwrap(),
+            remain as GuestUsize,
+        ))
+    }
+}
+
+impl Bytes<GuestAddress> for FlatView {
+    type E = GuestMemoryError;
+
+    /// The memory wirte interface based on `FlatView`.
+    ///
+    /// This function is similar to `flatview_write` in C side, but it
+    /// only supports MEMTXATTRS_UNSPECIFIED for now.
+    ///
+    /// Note: This function should be called within RCU critical section.
+    /// Furthermore, it is only for internal use and should not be called
+    /// directly.
+    fn write(&self, buf: &[u8], addr: GuestAddress) -> GuestMemoryResult<usize> {
+        self.try_access(
+            buf.len(),
+            addr,
+            true,
+            |offset, count, caddr, region| -> GuestMemoryResult<usize> {
+                // vm-memory provides an elegent way to advance (See
+                // ReadVolatile::read_volatile), but at this moment,
+                // this simple way is enough.
+                let sub_buf = &buf[offset..offset + count];
+                region.write(sub_buf, caddr)
+            },
+        )
+    }
+
+    /// The memory wirte interface based on `FlatView`.
+    ///
+    /// This function is similar to `flatview_read` in C side, but it
+    /// only supports MEMTXATTRS_UNSPECIFIED for now.
+    ///
+    /// Note: This function should be called within RCU critical section.
+    /// Furthermore, it is only for internal use and should not be called
+    /// directly.
+    fn read(&self, buf: &mut [u8], addr: GuestAddress) -> GuestMemoryResult<usize> {
+        if buf.len() == 0 {
+            return Ok(0);
+        }
+
+        self.try_access(
+            buf.len(),
+            addr,
+            false,
+            |offset, count, caddr, region| -> GuestMemoryResult<usize> {
+                // vm-memory provides an elegent way to advance (See
+                // ReadVolatile::write_volatile), but at this moment,
+                // this simple way is enough.
+                let sub_buf = &mut buf[offset..offset + count];
+                region
+                    .fuzz_dma_read(addr, sub_buf.len() as GuestUsize)
+                    .read(sub_buf, caddr)
+            },
+        )
+    }
+
+    /// The memory store interface based on `FlatView`.
+    ///
+    /// This function supports MEMTXATTRS_UNSPECIFIED, and only supports
+    /// native endian, which means before calling this function, make sure
+    /// the endian of value follows target's endian.
+    ///
+    /// Note: This function should be called within RCU critical section.
+    /// Furthermore, it is only for internal use and should not be called
+    /// directly.
+    fn store<T: AtomicAccess>(
+        &self,
+        val: T,
+        addr: GuestAddress,
+        order: Ordering,
+    ) -> GuestMemoryResult<()> {
+        self.translate(addr, size_of::<T>() as GuestUsize, true)
+            .ok_or(GuestMemoryError::InvalidGuestAddress(addr))
+            .and_then(|(region, region_addr, remain)| {
+                // Though C side handles this cross region case via MMIO
+                // by default, it still looks very suspicious for store/
+                // load. It happens Bytes::store() doesn't support more
+                // argument to identify this case, so report an error
+                // directly!
+                if remain < size_of::<T>() as GuestUsize {
+                    return Err(GuestMemoryError::InvalidBackendAddress);
+                }
+
+                region.store(val, region_addr, order)
+            })
+    }
+
+    /// The memory load interface based on `FlatView`.
+    ///
+    /// This function supports MEMTXATTRS_UNSPECIFIED, and only supports
+    /// native endian, which means the value returned by this function
+    /// follows target's endian.
+    ///
+    /// Note: This function should be called within RCU critical section.
+    /// Furthermore, it is only for internal use and should not be called
+    /// directly.
+    fn load<T: AtomicAccess>(&self, addr: GuestAddress, order: Ordering) -> GuestMemoryResult<T> {
+        self.translate(addr, size_of::<T>() as GuestUsize, false)
+            .ok_or(GuestMemoryError::InvalidGuestAddress(addr))
+            .and_then(|(region, region_addr, remain)| {
+                // Though C side handles this cross region case via MMIO
+                // by default, it still looks very suspicious for store/
+                // load. It happens Bytes::load() doesn't support more
+                // arguments to identify this case, so report an error
+                // directly!
+                if remain < size_of::<T>() as GuestUsize {
+                    return Err(GuestMemoryError::InvalidBackendAddress);
+                }
+
+                region
+                    .fuzz_dma_read(addr, size_of::<T> as GuestUsize)
+                    .load(region_addr, order)
+            })
+    }
+
+    fn write_slice(&self, _buf: &[u8], _addr: GuestAddress) -> GuestMemoryResult<()> {
+        unimplemented!()
+    }
+
+    fn read_slice(&self, _buf: &mut [u8], _addr: GuestAddress) -> GuestMemoryResult<()> {
+        unimplemented!()
+    }
+
+    fn read_volatile_from<F>(
+        &self,
+        _addr: GuestAddress,
+        _src: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<usize>
+    where
+        F: ReadVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn read_exact_volatile_from<F>(
+        &self,
+        _addr: GuestAddress,
+        _src: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<()>
+    where
+        F: ReadVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn write_volatile_to<F>(
+        &self,
+        _addr: GuestAddress,
+        _dst: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<usize>
+    where
+        F: WriteVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn write_all_volatile_to<F>(
+        &self,
+        _addr: GuestAddress,
+        _dst: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<()>
+    where
+        F: WriteVolatile,
+    {
+        unimplemented!()
+    }
+}
+
+impl GuestMemory for FlatView {
+    type R = MemoryRegionSection;
+
+    /// Get the number of `MemoryRegionSection`s managed by this `FlatView`.
+    fn num_regions(&self) -> usize {
+        self.deref().nr.try_into().unwrap()
+    }
+
+    /// Find the `MemoryRegionSection` which covers @addr
+    fn find_region(&self, addr: GuestAddress) -> Option<&Self::R> {
+        // set resolve_subpage as true by default
+        //
+        // SAFETY: bindings::FlatView has `dispatch` field and the pointer is
+        // valid, although accessing the field of C structure is ugly.
+        let raw =
+            unsafe { address_space_lookup_section(self.deref().dispatch, addr.raw_value(), true) };
+
+        if !raw.is_null() {
+            let s = unsafe { Self::R::from_raw(raw) };
+            Some(s)
+        } else {
+            None
+        }
+    }
+
+    /// Return an empty iterator.
+    ///
+    /// This function always triggers panic under debug mode.
+    fn iter(&self) -> impl Iterator<Item = &Self::R> {
+        assert!(false); // Do not use this iter()!
+
+        // QEMU has a linear iteration in C side named `flatview_for_each_range`,
+        // but it iterates `FlatRange` instead of `MemoryRegionSection`.
+        //
+        // It is still possible to have a `Iterator` based on `MemoryRegionSection`,
+        // by iterating `FlatView::dispatch::map::sections`.
+        //
+        // However, it is not worth it. QEMU has implemented the two-level "page"
+        // walk in `phys_page_find`, which is more efficient than linear
+        // iteration. Therefore, there is no need to reinvent the wheel on the
+        // Rust side, at least for now.
+        //
+        // Just return an empty iterator to satisfy the trait's contract.
+        // This makes the code compile, but the iterator won't yield
+        // any items.
+        std::iter::empty()
+    }
+
+    fn to_region_addr(&self, _addr: GuestAddress) -> Option<(&Self::R, MemoryRegionAddress)> {
+        // Note: This method should implement FlatView::translate(), but
+        // its function signature is unfriendly to QEMU's translation. QEMU
+        // needs to distinguish write access or not, and care about the
+        // remianing bytes of the region.
+        //
+        // FIXME: Once GuestMemory::to_region_addr() could meet QEMU's
+        // requirements, move FlatView::translate() here.
+        unimplemented!()
+    }
+
+    /// Try to access a contiguous block of guest memory, executing a callback
+    /// for each memory region that backs the requested address range.
+    ///
+    /// This method is the core of memory access.  It iterates through each
+    /// `MemoryRegionSection` that corresponds to the guest address
+    /// range [`addr`, `addr` + `count`) and invokes the provided closure `f`
+    /// for each section.
+    fn try_access<F>(
+        &self,
+        count: usize,
+        addr: GuestAddress,
+        is_write: bool,
+        mut f: F,
+    ) -> GuestMemoryResult<usize>
+    where
+        F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> GuestMemoryResult<usize>,
+    {
+        // FIXME: it's tricky to add more argument in try_access(), e.g.,
+        // attrs. Or maybe it's possible to move try_access() to Bytes trait,
+        // then it can accept a generic type which contains the address and
+        // other arguments.
+
+        if count == 0 {
+            return Ok(count);
+        }
+
+        let mut total = 0;
+        let mut curr = addr;
+
+        while total < count {
+            let len = (count - total) as GuestUsize;
+            let (region, start, remain) = self.translate(curr, len, is_write).unwrap();
+
+            if !region.is_access_allowed(start, remain) {
+                // FIXME: could we return something like MEMTX_ACCESS_ERROR?
+                return Err(GuestMemoryError::InvalidGuestAddress(addr));
+            }
+
+            match f(total as usize, remain as usize, start, region) {
+                // no more data
+                Ok(0) => return Ok(total),
+                // made some progress
+                Ok(res) => {
+                    if res as GuestUsize > remain {
+                        return Err(GuestMemoryError::CallbackOutOfRange);
+                    }
+
+                    total = match total.checked_add(res) {
+                        Some(x) if x < count => x,
+                        Some(x) if x == count => return Ok(x),
+                        _ => return Err(GuestMemoryError::CallbackOutOfRange),
+                    };
+
+                    curr = match curr.overflowing_add(res as GuestUsize) {
+                        (x @ GuestAddress(0), _) | (x, false) => x,
+                        (_, true) => return Err(GuestMemoryError::GuestAddressOverflow),
+                    };
+                }
+                // error happened
+                e => return e,
+            }
+        }
+
+        if total == 0 {
+            Err(GuestMemoryError::InvalidGuestAddress(addr))
+        } else {
+            Ok(total)
+        }
+    }
+}
+
+/// A RAII guard that provides temporary access to a `FlatView`.
+///
+/// Upon creation, this guard increments the reference count of the
+/// underlying `FlatView`.  When the guard goes out of of scope, it
+/// automatically decrements the count.
+///
+/// As long as the guard lives, the access to `FlatView` is valid.
+#[derive(Debug)]
+pub struct FlatViewRefGuard(NonNull<FlatView>);
+
+impl Drop for FlatViewRefGuard {
+    fn drop(&mut self) {
+        // SAFETY: the pointer is convertible.
+        unsafe { flatview_unref(self.0.as_ref().as_mut_ptr()) };
+    }
+}
+
+impl FlatViewRefGuard {
+    /// Attempt to create a new RAII guard for the given `FlatView`.
+    ///
+    /// This may fail if the `FlatView`'s reference count is already zero.
+    pub fn new(flat: &FlatView) -> Option<Self> {
+        // SAFETY: the pointer is convertible.
+        if unsafe { flatview_ref(flat.as_mut_ptr()) } {
+            Some(FlatViewRefGuard(NonNull::from(flat)))
+        } else {
+            None
+        }
+    }
+}
+
+impl Deref for FlatViewRefGuard {
+    type Target = FlatView;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: the pointer and reference are convertible.
+        unsafe { &*self.0.as_ptr() }
+    }
+}
+
+impl Clone for FlatViewRefGuard {
+    /// Clone the guard, which involves incrementing the reference
+    /// count again.
+    ///
+    /// This method will **panic** if the reference count of the underlying
+    /// `FlatView` cannot be incremented (e.g., if it is zero, meaning the
+    /// object is being destroyed).  This can happen in concurrent scenarios.
+    fn clone(&self) -> Self {
+        FlatViewRefGuard::new(self.deref()).expect(
+            "Failed to clone FlatViewRefGuard: the FlatView may have been destroyed concurrently.",
+        )
+    }
+}
-- 
2.34.1