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.

impl<const SIZE: usize> Mmio<SIZE>

pub fn relaxed(&self) -> &RelaxedMmio<SIZE>

Returns a RelaxedMmio reference that performs relaxed I/O operations.

Relaxed accessors do not provide ordering guarantees with respect to DMA or memory accesses and can be used when such ordering is not required.

Examples

use kernel::io::{
    Io,
    Mmio,
    RelaxedMmio,
};

fn do_io(io: &Mmio<0x100>) {
    // The access is performed using `readl_relaxed` instead of `readl`.
    let v = io.relaxed().read32(0x10);
}

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 io_addr<U>(&self, offset: usize) -> Result<usize>

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

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

where Self: IoCapable<u8>,

Fallible 8-bit read with runtime bounds check.

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

where Self: IoCapable<u16>,

Fallible 16-bit read with runtime bounds check.

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

where Self: IoCapable<u32>,

Fallible 32-bit read with runtime bounds check.

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

where Self: IoCapable<u64>,

Fallible 64-bit read with runtime bounds check.

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

where Self: IoCapable<u8>,

Fallible 8-bit write with runtime bounds check.

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

where Self: IoCapable<u16>,

Fallible 16-bit write with runtime bounds check.

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

where Self: IoCapable<u32>,

Fallible 32-bit write with runtime bounds check.

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

where Self: IoCapable<u64>,

Fallible 64-bit write with runtime bounds check.

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

where Self: IoKnownSize + IoCapable<u8>,

Infallible 8-bit read with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u16>,

Infallible 16-bit read with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u32>,

Infallible 32-bit read with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u64>,

Infallible 64-bit read with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u8>,

Infallible 8-bit write with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u16>,

Infallible 16-bit write with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u32>,

Infallible 32-bit write with compile-time bounds check.

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

where Self: IoKnownSize + IoCapable<u64>,

Infallible 64-bit write with compile-time bounds check.

fn try_read<T, L>(&self, location: L) -> Result<T>

where L: IoLoc<T>, Self: IoCapable<L::IoType>,

Generic fallible read with runtime bounds check.

fn try_write<T, L>(&self, location: L, value: T) -> Result

where L: IoLoc<T>, Self: IoCapable<L::IoType>,

Generic fallible write with runtime bounds check.

fn try_write_reg<T, L, V>(&self, value: V) -> Result

where L: IoLoc<T>, V: LocatedRegister<Location = L, Value = T>, Self: IoCapable<L::IoType>,

Generic fallible write of a fully-located register value.

fn try_update<T, L, F>(&self, location: L, f: F) -> Result

where L: IoLoc<T>, Self: IoCapable<L::IoType>, F: FnOnce(T) -> T,

Generic fallible update with runtime bounds check.

fn read<T, L>(&self, location: L) -> T

where L: IoLoc<T>, Self: IoKnownSize + IoCapable<L::IoType>,

Generic infallible read with compile-time bounds check.

fn write<T, L>(&self, location: L, value: T)

where L: IoLoc<T>, Self: IoKnownSize + IoCapable<L::IoType>,

Generic infallible write with compile-time bounds check.

fn write_reg<T, L, V>(&self, value: V)

where L: IoLoc<T>, V: LocatedRegister<Location = L, Value = T>, Self: IoKnownSize + IoCapable<L::IoType>,

Generic infallible write of a fully-located register value.

fn update<T, L, F>(&self, location: L, f: F)

where L: IoLoc<T>, Self: IoKnownSize + IoCapable<L::IoType> + Sized, F: FnOnce(T) -> T,

Generic infallible update with compile-time bounds check.

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

unsafe fn io_read(&self, address: usize) -> u16

Performs an I/O read of type T at address and returns the result.

unsafe fn io_write(&self, value: u16, address: usize)

Performs an I/O write of value at address.

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

unsafe fn io_read(&self, address: usize) -> u32

Performs an I/O read of type T at address and returns the result.

unsafe fn io_write(&self, value: u32, address: usize)

Performs an I/O write of value at address.

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

Available on CONFIG_64BIT only.

unsafe fn io_read(&self, address: usize) -> u64

Performs an I/O read of type T at address and returns the result.

unsafe fn io_write(&self, value: u64, address: usize)

Performs an I/O write of value at address.

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

unsafe fn io_read(&self, address: usize) -> u8

Performs an I/O read of type T at address and returns the result.

unsafe fn io_write(&self, value: u8, address: usize)

Performs an I/O write of value at address.

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.