Trait Mmio

pub trait Mmio {
    // Required methods
    fn len(&self) -> usize;
    fn align_offset(&self, align: usize) -> usize;
    fn try_load8(&self, offset: usize) -> Result<u8, MmioError>;
    fn try_load16(&self, offset: usize) -> Result<u16, MmioError>;
    fn try_load32(&self, offset: usize) -> Result<u32, MmioError>;
    fn try_load64(&self, offset: usize) -> Result<u64, MmioError>;
    fn try_store8(&mut self, offset: usize, value: u8) -> Result<(), MmioError>;
    fn try_store16(
        &mut self,
        offset: usize,
        value: u16,
    ) -> Result<(), MmioError>;
    fn try_store32(
        &mut self,
        offset: usize,
        value: u32,
    ) -> Result<(), MmioError>;
    fn try_store64(
        &mut self,
        offset: usize,
        value: u64,
    ) -> Result<(), MmioError>;

    // Provided methods
    fn load8(&self, offset: usize) -> u8 { ... }
    fn load16(&self, offset: usize) -> u16 { ... }
    fn load32(&self, offset: usize) -> u32 { ... }
    fn load64(&self, offset: usize) -> u64 { ... }
    fn store8(&mut self, offset: usize, value: u8) { ... }
    fn store16(&mut self, offset: usize, value: u16) { ... }
    fn store32(&mut self, offset: usize, value: u32) { ... }
    fn store64(&mut self, offset: usize, value: u64) { ... }
}

An Mmio implementation provides access to an MMIO region.

Device memory

For implementations that provide access to device memory, all memory must be accessed with volatile semantics. I/O instructions should not be coalesced or cached and should occur in program order.

Implementations are not required to provide any ordering guarantees between device memory access and other instructions. Furthermore there is no guarantee that any side-effects are visible to subsequent operations.

Callers who need guarantees around instruction ordering and side-effect visibility should insert the appropriate compiler fences and/or memory barriers.

Safety

Implementations of Mmio are required to be safe in a Rust sense, however loads may have side-effects and device memory may change outside of the control of the host.

Offsets, Alignment and Capacity

Mmio implementations provide access to device memory via offsets, not addresses. There are no requirements on the alignment of offset 0.

When using the load and store operations, callers are required to provide offsets representing locations that are suitably aligned and fully within bounds of the location. Failure to do so does not cause any safety issues, but may result in errors for the checked loads and stores, or panics for the non-checked variants.

If these guarantees can’t be provided statically for a given use case, the following functions can be used to ensure these requirements:

• MmioExt::check_aligned_for: returns an MmioError::Unaligned error if the given offset is not suitably aligned.
• MmioExt::check_capacity_for: returns an MmioError::OutOfRange error if there is not sufficient capacity at the given offset.
• MmioExt::check_suitable_for: returns an MmioError if there is not sufficient capacity at the given offset or it is not suitably aligned.

Dyn Compatibility

This trait is dyn compatible. See the MmioExt trait for useful utilities that extend this trait.

Required Methods

fn len(&self) -> usize

Returns the size in bytes of this MMIO region.

fn align_offset(&self, align: usize) -> usize

Computes the first offset within this region that is aligned to align.

See the trait-level documentation for more information on offsets and alignment.

Panics

If align is not a power of 2.

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

Loads one byte from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the load would exceed the bounds of this MMIO region.

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

Loads two bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the load would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

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

Loads four bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the load would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

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

Loads eight bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the load would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

fn try_store8(&mut self, offset: usize, value: u8) -> Result<(), MmioError>

Stores one byte to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the store would exceed the bounds of this MMIO region.

fn try_store16(&mut self, offset: usize, value: u16) -> Result<(), MmioError>

Stores two bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the store would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

fn try_store32(&mut self, offset: usize, value: u32) -> Result<(), MmioError>

Stores four bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the store would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

fn try_store64(&mut self, offset: usize, value: u64) -> Result<(), MmioError>

Stores eight bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Errors

• MmioError::OutOfRange: if the store would exceed the bounds of this MMIO region.
• MmioError::Unaligned: if the offset is not suitably aligned.

Provided Methods

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

Loads one byte from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the load would exceed the bounds of this MMIO region.

See Mmio::try_load8 for a non-panicking version.

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

Loads two bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the load would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_load16 for a non-panicking version.

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

Loads four bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the load would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_load32 for a non-panicking version.

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

Loads eight bytes from this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the load would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_load64 for a non-panicking version.

fn store8(&mut self, offset: usize, value: u8)

Stores one byte to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the store would exceed the bounds of this MMIO region.

See Mmio::try_store8 for a non-panicking version.

fn store16(&mut self, offset: usize, value: u16)

Stores two bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the store would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_store16 for a non-panicking version.

fn store32(&mut self, offset: usize, value: u32)

Stores four bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the store would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_store32 for a non-panicking version.

fn store64(&mut self, offset: usize, value: u64)

Stores eight bytes to this MMIO region at the given offset.

See the trait-level documentation for information about offset requirements.

Panics

• If the store would exceed the bounds of this MMIO region.
• If the offset is not suitably aligned.

See Mmio::try_store64 for a non-panicking version.

Implementors

impl<Impl: UnsafeMmio, Owner: Borrow<Impl>> Mmio for MmioRegion<Impl, Owner>