rust: io_mem: Add Mem abstraction

To be refactored into io once that's upstream.

Author: hoshinolina

rust/kernel/io_mem.rs

@@ -6,7 +6,9 @@
 
 #![allow(dead_code)]
 
+use crate::types::declare_flags_type;
 use crate::{addr::*, bindings, error::code::*, error::Result};
+
 use core::convert::TryInto;
 use core::ptr::NonNull;
 
@@ -54,7 +56,7 @@ impl Resource {
     }
 }
 
-/// Represents a memory block of at least `SIZE` bytes.
+/// Represents an MMIO memory block of at least `SIZE` bytes.
 ///
 /// # Invariants
 ///
@@ -327,3 +329,104 @@ impl<const SIZE: usize> Drop for IoMem<SIZE> {
         unsafe { bindings::iounmap(self.ptr as _) };
     }
 }
+
+declare_flags_type! {
+    /// Flags to be used when remapping memory.
+    ///
+    /// They can be combined with the operators `|`, `&`, and `!`.
+    pub struct MemFlags(core::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<core::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 `ioremap`, 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()) };
+    }
+}