rust: io: mem: Add Mem abstraction

Signed-off-by: Janne Grunau <j@jannau.net>

Author: hoshinolina

rust/kernel/io/mem.rs

@@ -3,6 +3,7 @@
 //! Generic memory-mapped IO.
 
 use core::ops::Deref;
+use core::ptr::NonNull;
 
 use crate::{
     c_str,
@@ -21,6 +22,7 @@ use crate::{
         IoRaw, //
     },
     prelude::*,
+    types::declare_flags_type, //
 };
 
 /// An IO request for a specific device and resource.
@@ -285,3 +287,104 @@ impl<const SIZE: usize> Deref for IoMem<SIZE> {
         unsafe { Io::from_raw(&self.io) }
     }
 }
+
+declare_flags_type! {
+    /// Flags to be used when remapping memory.
+    ///
+    /// They can be combined with the operators `|`, `&`, and `!`.
+    pub struct MemFlags(crate::ffi::c_ulong) = 0;
+}
+
+impl MemFlags {
+    /// Matches the default mapping for System RAM on the architecture.
+    ///
+    /// This is usually a read-allocate write-back cache. Moreover, if this flag is specified and
+    /// the requested remap region is RAM, memremap() will bypass establishing a new mapping and
+    /// instead return a pointer into the direct map.
+    pub const WB: MemFlags = MemFlags(bindings::MEMREMAP_WB as _);
+
+    /// Establish a mapping whereby writes either bypass the cache or are written through to memory
+    /// and never exist in a cache-dirty state with respect to program visibility.
+    ///
+    /// Attempts to map System RAM with this mapping type will fail.
+    pub const WT: MemFlags = MemFlags(bindings::MEMREMAP_WT as _);
+    /// Establish a writecombine mapping, whereby writes may be coalesced together  (e.g. in the
+    /// CPU's write buffers), but is otherwise uncached.
+    ///
+    /// Attempts to map System RAM with this mapping type will fail.
+    pub const WC: MemFlags = MemFlags(bindings::MEMREMAP_WC as _);
+
+    // Note: Skipping MEMREMAP_ENC/DEC since they are under-documented and have zero
+    // users outside of arch/x86.
+}
+
+/// Represents a non-MMIO memory block. This is like [`IoMem`], but for cases where it is known
+/// that the resource being mapped does not have I/O side effects.
+// Invariants:
+// `ptr` is a non-null and valid address of at least `usize` bytes and returned by a `memremap`
+// call.
+// ```
+pub struct Mem {
+    ptr: NonNull<crate::ffi::c_void>,
+    size: usize,
+}
+
+impl Mem {
+    /// Tries to create a new instance of a memory block from a Resource.
+    ///
+    /// The resource described by `res` is mapped into the CPU's address space so that it can be
+    /// accessed directly. It is also consumed by this function so that it can't be mapped again
+    /// to a different address.
+    ///
+    /// If multiple caching flags are specified, the different mapping types will be attempted in
+    /// the order [`MemFlags::WB`], [`MemFlags::WT`], [`MemFlags::WC`].
+    ///
+    /// # Flags
+    ///
+    /// * [`MemFlags::WB`]: Matches the default mapping for System RAM on the architecture.
+    ///   This is usually a read-allocate write-back cache. Moreover, if this flag is specified and
+    ///   the requested remap region is RAM, memremap() will bypass establishing a new mapping and
+    ///   instead return a pointer into the direct map.
+    ///
+    /// * [`MemFlags::WT`]: Establish a mapping whereby writes either bypass the cache or are written
+    ///   through to memory and never exist in a cache-dirty state with respect to program visibility.
+    ///   Attempts to map System RAM with this mapping type will fail.
+    /// * [`MemFlags::WC`]: Establish a writecombine mapping, whereby writes may be coalesced together
+    ///   (e.g. in the CPU's write buffers), but is otherwise uncached. Attempts to map System RAM with
+    ///   this mapping type will fail.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that either (a) the resulting interface cannot be used to initiate DMA
+    /// operations, or (b) that DMA operations initiated via the returned interface use DMA handles
+    /// allocated through the `dma` module.
+    pub unsafe fn try_new(res: Resource, flags: MemFlags) -> Result<Self> {
+        let size: usize = res.size().try_into()?;
+
+        let addr = unsafe { bindings::memremap(res.start(), size, flags.as_raw()) };
+        let ptr = NonNull::new(addr).ok_or(ENOMEM)?;
+        // INVARIANT: `ptr` is non-null and was returned by `memremap`, so it is valid.
+        Ok(Self { ptr, size })
+    }
+
+    /// Returns the base address of the memory mapping as a raw pointer.
+    ///
+    /// It is up to the caller to use this pointer safely, depending on the requirements of the
+    /// hardware backing this memory block.
+    pub fn ptr(&self) -> *mut u8 {
+        self.ptr.cast().as_ptr()
+    }
+
+    /// Returns the size of this mapped memory block.
+    pub fn size(&self) -> usize {
+        self.size
+    }
+}
+
+impl Drop for Mem {
+    fn drop(&mut self) {
+        // SAFETY: By the type invariant, `self.ptr` is a value returned by a previous successful
+        // call to `memremap`.
+        unsafe { bindings::memunmap(self.ptr.as_ptr()) };
+    }
+}