Struct Mmio 

pub struct Mmio<const SIZE: usize = 0>(/* private fields */);

IO-mapped memory region.

The creator (usually a subsystem / bus such as PCI) is responsible for creating the mapping, performing an additional region request etc.

Invariant

addr is the start and maxsize the length of valid I/O mapped memory region of size maxsize.

Examples

use kernel::{
    bindings,
    ffi::c_void,
    io::{
        Io,
        IoKnownSize,
        Mmio,
        MmioRaw,
        PhysAddr,
    },
};
use core::ops::Deref;

// See also `pci::Bar` for a real example.
struct IoMem<const SIZE: usize>(MmioRaw<SIZE>);

impl<const SIZE: usize> IoMem<SIZE> {
    /// # Safety
    ///
    /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
    /// virtual address space.
    unsafe fn new(paddr: usize) -> Result<Self>{
        // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
        // valid for `ioremap`.
        let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) };
        if addr.is_null() {
            return Err(ENOMEM);
        }

        Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?))
    }
}

impl<const SIZE: usize> Drop for IoMem<SIZE> {
    fn drop(&mut self) {
        // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
        unsafe { bindings::iounmap(self.0.addr() as *mut c_void); };
    }
}

impl<const SIZE: usize> Deref for IoMem<SIZE> {
   type Target = Mmio<SIZE>;

   fn deref(&self) -> &Self::Target {
        // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
        unsafe { Mmio::from_raw(&self.0) }
   }
}

// SAFETY: Invalid usage for example purposes.
let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
iomem.write32(0x42, 0x0);
assert!(iomem.try_write32(0x42, 0x0).is_ok());
assert!(iomem.try_write32(0x42, 0x4).is_err());

Implementations

impl<const SIZE: usize> Mmio<SIZE>

pub unsafe fn from_raw(raw: &MmioRaw<SIZE>) -> &Self

Converts an MmioRaw into an Mmio instance, providing the accessors to the MMIO mapping.

Safety

Callers must ensure that addr is the start of a valid I/O mapped memory region of size maxsize.

pub fn read8_relaxed(&self, offset: usize) -> u8

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn read16_relaxed(&self, offset: usize) -> u16

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn read32_relaxed(&self, offset: usize) -> u32

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn read64_relaxed(&self, offset: usize) -> u64

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn try_read8_relaxed(&self, offset: usize) -> Result<u8>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_read16_relaxed(&self, offset: usize) -> Result<u16>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_read32_relaxed(&self, offset: usize) -> Result<u32>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_read64_relaxed(&self, offset: usize) -> Result<u64>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn write8_relaxed(&self, value: u8, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn write16_relaxed(&self, value: u16, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn write32_relaxed(&self, value: u32, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn write64_relaxed(&self, value: u64, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

pub fn try_write8_relaxed(&self, value: u8, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_write16_relaxed(&self, value: u16, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_write32_relaxed(&self, value: u32, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

pub fn try_write64_relaxed(&self, value: u64, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

Trait Implementations

impl<const SIZE: usize> Io for Mmio<SIZE>

fn addr(&self) -> usize

Returns the base address of this mapping.

fn maxsize(&self) -> usize

Returns the maximum size of this mapping.

fn try_read8(&self, offset: usize) -> Result<u8>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_read16(&self, offset: usize) -> Result<u16>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_read32(&self, offset: usize) -> Result<u32>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_read64(&self, offset: usize) -> Result<u64>

Read IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_write8(&self, value: u8, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_write16(&self, value: u16, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_write32(&self, value: u32, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn try_write64(&self, value: u64, offset: usize) -> Result

Write IO data from a given offset.

Bound checks are performed on runtime, it fails if the offset (plus the type size) is out of bounds.

fn read8(&self, offset: usize) -> u8

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn read16(&self, offset: usize) -> u16

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn read32(&self, offset: usize) -> u32

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn read64(&self, offset: usize) -> u64

Read IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn write8(&self, value: u8, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn write16(&self, value: u16, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn write32(&self, value: u32, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn write64(&self, value: u64, offset: usize)

Write IO data from a given offset known at compile time.

Bound checks are performed on compile time, hence if the offset is not known at compile time, the build will fail.

fn io_addr<U>(&self, offset: usize) -> Result<usize>

Returns the absolute I/O address for a given offset, performing runtime bound checks.

impl<const SIZE: usize> IoKnownSize for Mmio<SIZE>

const MIN_SIZE: usize = SIZE

Minimum usable size of this region.

fn io_addr_assert<U>(&self, offset: usize) -> usize

Returns the absolute I/O address for a given offset, performing compile-time bound checks.

impl<const SIZE: usize> IoCapable<u16> for Mmio<SIZE>

impl<const SIZE: usize> IoCapable<u32> for Mmio<SIZE>

impl<const SIZE: usize> IoCapable<u64> for Mmio<SIZE>

Available on CONFIG_64BIT only.

impl<const SIZE: usize> IoCapable<u8> for Mmio<SIZE>