[RFC v2 18/26] rust/system/memory: Implement vm_memory::GuestMemoryRegion for MemoryRegionSection

Although QEMU already has a native memory region abstraction (MemoryRegion),
it supports overlapping regions. Since the vm-memory crate does not support
overlapping memory, MemoryRegionSection is a more appropriate choice to
implement the vm_memory::GuestMemoryRegion trait.

To achieve this, implement vm_memory::GuestMemoryRegion for MemoryRegionSection,
along with its required supertrait, GuestMemoryRegionBytes. Additionally,
implement Bytes<(MemoryRegionAddress, MemTxAttrs)> to properly attach QEMU's
memory transaction attributes to memory operations.

Furthermore, provide low-level memory write/read/store/load bindings based
on MemoryRegionSection, and add the necessary helpers (fuzz_dma_read() and
is_access_allowed()).

Signed-off-by: Zhao Liu <[email protected]>
---
Changes since v1:
 * Implement GuestMemoryRegionBytes for MemoryRegionSection to satisfy
   supertrait requirement.
 * Implement Bytes<(MemoryRegionAddress, MemTxAttrs)> to attach
   MemTxAttrs.
 * For write/read, add an extra loop to ensure write/read are actually
   finished within the same region.
---
 rust/system/src/memory.rs | 449 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 447 insertions(+), 2 deletions(-)

diff --git a/rust/system/src/memory.rs b/rust/system/src/memory.rs
index 4c258201bad7..34c7b7ce04a1 100644
--- a/rust/system/src/memory.rs
+++ b/rust/system/src/memory.rs
@@ -2,19 +2,38 @@
 // Author(s): Paolo Bonzini <[email protected]>
 // SPDX-License-Identifier: GPL-2.0-or-later
 
-//! Bindings for `MemoryRegion`, `MemoryRegionOps` and `MemTxAttrs`
+//! Bindings for `MemoryRegion`, `MemoryRegionOps`, `MemTxAttrs` and
+//! `MemoryRegionSection`.
 
 use std::{
     ffi::{c_uint, c_void, CStr, CString},
+    io::ErrorKind,
     marker::PhantomData,
+    mem::size_of,
+    ops::Deref,
+    sync::atomic::Ordering,
 };
 
 use common::{callbacks::FnCall, uninit::MaybeUninitField, zeroable::Zeroable, Opaque};
 use qom::prelude::*;
+pub use vm_memory::GuestAddress;
+use vm_memory::{
+    bitmap::BS, Address, AtomicAccess, Bytes, GuestMemoryError, GuestMemoryRegion,
+    GuestMemoryRegionBytes, GuestMemoryResult, GuestUsize, MemoryRegionAddress, ReadVolatile,
+    WriteVolatile,
+};
 
-use crate::bindings::{self, device_endian, memory_region_init_io};
+use crate::bindings::{
+    self, device_endian, memory_region_init_io, rust_section_load, rust_section_read_continue_step,
+    rust_section_store, rust_section_write_continue_step, section_access_allowed,
+    section_covers_region_addr, section_fuzz_dma_read, MemTxResult,
+};
+// FIXME: Convert hwaddr to GuestAddress
 pub use crate::bindings::{hwaddr, MemTxAttrs};
 
+/// Corresponds to C `MEMTX_OK` (#define `MEMTX_OK` 0).
+const MEMTX_OK: MemTxResult = 0;
+
 pub struct MemoryRegionOps<T>(
     bindings::MemoryRegionOps,
     // Note: quite often you'll see PhantomData<fn(&T)> mentioned when discussing
@@ -187,3 +206,429 @@ unsafe impl ObjectType for MemoryRegion {
     unspecified: true,
     ..Zeroable::ZERO
 };
+
+/// A safe wrapper around [`bindings::MemoryRegionSection`].
+///
+/// This struct is fundamental for integrating QEMU's memory model with
+/// the `vm-memory` ecosystem.  It directly maps to the concept of
+/// [`GuestMemoryRegion`] and implements that trait.
+///
+/// ### `MemoryRegion` vs. `MemoryRegionSection`
+///
+/// Although QEMU already has native memory region abstraction, this is
+/// [`MemoryRegion`], which supports overlapping.  But `vm-memory` doesn't
+/// support overlapped memory, so `MemoryRegionSection` is more proper
+/// to implement [`GuestMemoryRegion`] trait.
+///
+/// One point should pay attention is, [`MemoryRegionAddress`] represents the
+/// address or offset within the `MemoryRegionSection`.  But traditional C
+/// bindings treats memory region address or offset as the offset within
+/// `MemoryRegion`.
+///
+/// Therefore, it's necessary to do conversion when calling C bindings
+/// with `MemoryRegionAddress` from the context of `MemoryRegionSection`.
+///
+/// ### Usage
+///
+/// Considerring memory access is almost always through `AddressSpace`
+/// in QEMU, `MemoryRegionSection` is intended for **internal use only**
+///  within the `vm-memory` backend implementation.
+///
+/// Device and other external users should **not** use or create
+/// `MemoryRegionSection`s directly.  Instead, they should work with the
+/// higher-level `MemoryRegion` API to create and manage their device's
+/// memory.  This separation of concerns mirrors the C API and avoids
+/// confusion about different memory abstractions.
+#[repr(transparent)]
+#[derive(common::Wrapper, Debug)]
+pub struct MemoryRegionSection(Opaque<bindings::MemoryRegionSection>);
+
+unsafe impl Send for MemoryRegionSection {}
+unsafe impl Sync for MemoryRegionSection {}
+
+impl Deref for MemoryRegionSection {
+    type Target = bindings::MemoryRegionSection;
+
+    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 MemoryRegionSection {
+    /// A fuzz testing hook for DMA read.
+    ///
+    /// When `CONFIG_FUZZ` is not set, this hook will do nothing.
+    #[allow(dead_code)]
+    fn fuzz_dma_read(&self, addr: GuestAddress, len: GuestUsize) -> &Self {
+        // SAFETY: Opaque<> ensures the pointer is valid, and here it
+        // takes into account the offset conversion between MemoryRegionSection
+        // and MemoryRegion.
+        unsafe {
+            section_fuzz_dma_read(
+                self.as_mut_ptr(),
+                addr.checked_add(self.deref().offset_within_region)
+                    .unwrap()
+                    .raw_value(),
+                len,
+            );
+        }
+        self
+    }
+
+    /// A helper to check if the memory access is allowed.
+    ///
+    /// This is needed for memory write/read.
+    #[allow(dead_code)]
+    fn is_access_allowed(
+        &self,
+        addr: MemoryRegionAddress,
+        len: GuestUsize,
+        attrs: MemTxAttrs,
+    ) -> bool {
+        // SAFETY: Opaque<> ensures the pointer is valid, and here it
+        // takes into account the offset conversion between MemoryRegionSection
+        // and MemoryRegion.
+        let allowed = unsafe {
+            section_access_allowed(
+                self.as_mut_ptr(),
+                attrs,
+                addr.checked_add(self.deref().offset_within_region)
+                    .unwrap()
+                    .raw_value(),
+                len,
+            )
+        };
+        allowed
+    }
+}
+
+/// Satisfies the `Bytes<MemoryRegionAddress>` supertrait required by
+/// `GuestMemoryRegion`.
+///
+/// The blanket impl fails with `HostAddressNotAvailable` because
+/// `MemoryRegionSection` methods all go through `as_volatile_slice()` and
+/// `get_slice()`, which by default return an error.
+///
+/// QEMU's real access path is always attrs-aware and reaches this section
+/// through the `Bytes<(MemoryRegionAddress,
+/// MemTxAttrs)>` impl below.
+impl GuestMemoryRegionBytes for MemoryRegionSection {}
+
+/// The attrs-aware `Bytes` implementation that actually does the C-side
+/// memory access for a single `MemoryRegionSection`.
+///
+/// This composite impl is the *only* real access path into a
+/// `MemoryRegionSection`: QEMU always reaches it through `FlatView`
+/// with the real `attrs`.  The blanket `GuestMemoryRegionBytes` impl above
+/// just satisfies the `GuestMemoryRegion` supertrait bound and is never
+/// actually  called.
+impl Bytes<(MemoryRegionAddress, MemTxAttrs)> for MemoryRegionSection {
+    type E = GuestMemoryError;
+
+    /// Write a byte buffer into guest memory at `addr`.
+    ///
+    /// This shouldn't be called to access memory directly; it is the
+    /// per-region worker invoked by `FlatView`'s write path.  The transaction
+    /// `attrs` are forwarded to the C side. And the cross-region is handled by
+    /// `FlatView`'s write.
+    fn write(
+        &self,
+        buf: &[u8],
+        (addr, attrs): (MemoryRegionAddress, MemTxAttrs),
+    ) -> GuestMemoryResult<usize> {
+        let base = addr
+            .checked_add(self.deref().offset_within_region)
+            .unwrap()
+            .raw_value();
+        let total = buf.len() as u64;
+        let mut done: u64 = 0;
+
+        while done < total {
+            // `step` is the attempt size on input and the bytes actually
+            // handled on output.
+            let mut step = total - done;
+
+            // SAFETY: the pointers and reference are convertible and the
+            // offset conversion is considered.
+            let ret = unsafe {
+                rust_section_write_continue_step(
+                    self.as_mut_ptr(),
+                    attrs,
+                    buf[done as usize..].as_ptr(),
+                    total - done,
+                    base + done,
+                    &mut step,
+                )
+            };
+
+            if ret != MEMTX_OK {
+                return Err(GuestMemoryError::InvalidBackendAddress);
+            }
+
+            // A zero-length step can never make progress.
+            if step == 0 {
+                break;
+            }
+
+            done += step;
+        }
+
+        Ok(done as usize)
+    }
+
+    /// Read a byte buffer from guest memory at `addr`.
+    ///
+    /// This shouldn't be called to access memory directly; it is the
+    /// per-region worker invoked by `FlatView`'s read path.  The transaction
+    /// `attrs` are forwarded to the C side. And the cross-region is handled by
+    /// `FlatView`'s read.
+    fn read(
+        &self,
+        buf: &mut [u8],
+        (addr, attrs): (MemoryRegionAddress, MemTxAttrs),
+    ) -> GuestMemoryResult<usize> {
+        let base = addr
+            .checked_add(self.deref().offset_within_region)
+            .unwrap()
+            .raw_value();
+        let total = buf.len() as u64;
+        let mut done: u64 = 0;
+
+        while done < total {
+            // `step` is the attempt size on input and the bytes actually
+            // handled on output.
+            let mut step = total - done;
+
+            // SAFETY: the pointers and reference are convertible and the
+            // offset conversion is considered.
+            let ret = unsafe {
+                rust_section_read_continue_step(
+                    self.as_mut_ptr(),
+                    attrs,
+                    buf[done as usize..].as_mut_ptr(),
+                    total - done,
+                    base + done,
+                    &mut step,
+                )
+            };
+
+            if ret != MEMTX_OK {
+                return Err(GuestMemoryError::InvalidBackendAddress);
+            }
+
+            // A zero-length step can never make progress.
+            if step == 0 {
+                break;
+            }
+
+            done += step;
+        }
+
+        Ok(done as usize)
+    }
+
+    /// Store a value into guest memory at `addr`.
+    ///
+    /// This function - as the low-level store implementation - is
+    /// called by `FlatView`'s `store()`.  And it shouldn't be called to
+    /// access memory directly.
+    ///
+    /// The transaction `attrs` are forwarded to the C side; the `Ordering` is
+    /// ignored because the access is not Rust-atomic.
+    fn store<T: AtomicAccess>(
+        &self,
+        val: T,
+        (addr, attrs): (MemoryRegionAddress, MemTxAttrs),
+        _order: Ordering,
+    ) -> GuestMemoryResult<()> {
+        let len = size_of::<T>();
+
+        if len > size_of::<u64>() {
+            return Err(GuestMemoryError::IOError(std::io::Error::new(
+                ErrorKind::InvalidInput,
+                "failed to store the data more then 8 bytes",
+            )));
+        }
+
+        // Note: rust_section_store() accepts `const uint8_t *buf`.
+        //
+        // This is a "compromise" solution: vm-memory requires AtomicAccess
+        // but QEMU uses uint64_t as the default type. Here we can't convert
+        // AtomicAccess to u64, since the compiler will complain "an `as`
+        // expression can only be used to convert between primitive types or
+        // to coerce to a specific trait object", or other endless errors
+        // about conversion to u64.
+        //
+        // Fortunately, we can use a byte array to bridge the Rust wrapper
+        // and the C binding. This approach is not without a trade-off,
+        // however: the rust_section_store() function requires an additional
+        // conversion from bytes to a uint64_t for the MMIO case. This performance
+        // overhead is considered acceptable.
+        //
+        // SAFETY: the pointers are convertible and the offset conversion is
+        // considered.
+        let res = unsafe {
+            rust_section_store(
+                self.as_mut_ptr(),
+                addr.checked_add(self.deref().offset_within_region)
+                    .unwrap()
+                    .raw_value(),
+                val.as_slice().as_ptr(),
+                attrs,
+                len as u64,
+            )
+        };
+
+        match res {
+            MEMTX_OK => Ok(()),
+            _ => Err(GuestMemoryError::InvalidBackendAddress),
+        }
+    }
+
+    /// Load a value from guest memory at `addr`.
+    ///
+    /// This function - as the low-level load implementation - is
+    /// called by `FlatView`'s `load()`.  And it shouldn't be called to
+    /// access memory directly.
+    ///
+    /// The transaction `attrs` are forwarded to the C side; the `Ordering` is
+    /// ignored because the access is not Rust-atomic.
+    fn load<T: AtomicAccess>(
+        &self,
+        (addr, attrs): (MemoryRegionAddress, MemTxAttrs),
+        _order: Ordering,
+    ) -> GuestMemoryResult<T> {
+        let len = size_of::<T>();
+
+        if len > size_of::<u64>() {
+            return Err(GuestMemoryError::IOError(std::io::Error::new(
+                ErrorKind::InvalidInput,
+                "failed to load the data more then 8 bytes",
+            )));
+        }
+
+        let mut val: T = T::zeroed();
+
+        // Note: rust_section_load() accepts `uint8_t *buf`.
+        //
+        // This is for a similar reason as store(), with the slight difference
+        // that rust_section_load() requires an additional conversion from
+        // uint64_t to bytes.
+        //
+        // SAFETY: the pointers are convertible and the offset conversion is
+        // considered.
+        let res = unsafe {
+            rust_section_load(
+                self.as_mut_ptr(),
+                addr.checked_add(self.deref().offset_within_region)
+                    .unwrap()
+                    .raw_value(),
+                val.as_mut_slice().as_mut_ptr(),
+                attrs,
+                size_of::<T>() as u64,
+            )
+        };
+
+        match res {
+            MEMTX_OK => Ok(val),
+            _ => Err(GuestMemoryError::InvalidBackendAddress),
+        }
+    }
+
+    fn write_slice(
+        &self,
+        _buf: &[u8],
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+    ) -> GuestMemoryResult<()> {
+        unimplemented!()
+    }
+
+    fn read_slice(
+        &self,
+        _buf: &mut [u8],
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+    ) -> GuestMemoryResult<()> {
+        unimplemented!()
+    }
+
+    fn read_volatile_from<F>(
+        &self,
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+        _src: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<usize>
+    where
+        F: ReadVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn read_exact_volatile_from<F>(
+        &self,
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+        _src: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<()>
+    where
+        F: ReadVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn write_volatile_to<F>(
+        &self,
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+        _dst: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<usize>
+    where
+        F: WriteVolatile,
+    {
+        unimplemented!()
+    }
+
+    fn write_all_volatile_to<F>(
+        &self,
+        _addr: (MemoryRegionAddress, MemTxAttrs),
+        _dst: &mut F,
+        _count: usize,
+    ) -> GuestMemoryResult<()>
+    where
+        F: WriteVolatile,
+    {
+        unimplemented!()
+    }
+}
+
+impl GuestMemoryRegion for MemoryRegionSection {
+    type B = ();
+
+    /// Get the memory size covered by this `MemoryRegionSection`.
+    fn len(&self) -> GuestUsize {
+        self.deref().size as GuestUsize
+    }
+
+    /// Return the minimum (inclusive) Guest physical address managed by
+    /// this `MemoryRegionSection`.
+    fn start_addr(&self) -> GuestAddress {
+        GuestAddress(self.deref().offset_within_address_space)
+    }
+
+    fn bitmap(&self) -> BS<'_, Self::B> {}
+
+    /// Check whether the `@addr` is covered by this `MemoryRegionSection`.
+    fn check_address(&self, addr: MemoryRegionAddress) -> Option<MemoryRegionAddress> {
+        let region_addr = addr
+            .checked_add(self.deref().offset_within_region)?
+            .raw_value();
+        // SAFETY: the pointer is convertible and the offset conversion is
+        // considered.
+        if unsafe { section_covers_region_addr(self.as_mut_ptr(), region_addr) } {
+            Some(addr)
+        } else {
+            None
+        }
+    }
+}
-- 
2.34.1