Trait MmioExt

pub trait MmioExt: Mmio {
    // Provided methods
    fn check_aligned_for<T>(&self, offset: usize) -> Result<(), MmioError> { ... }
    fn check_capacity_for<T>(&self, offset: usize) -> Result<(), MmioError> { ... }
    fn check_suitable_for<T>(&self, offset: usize) -> Result<(), MmioError> { ... }
    fn try_load<T: MmioOperand>(&self, offset: usize) -> Result<T, MmioError> { ... }
    fn load<T: MmioOperand>(&self, offset: usize) -> T { ... }
    fn try_store<T: MmioOperand>(
        &mut self,
        offset: usize,
        value: T,
    ) -> Result<(), MmioError> { ... }
    fn store<T: MmioOperand>(&mut self, offset: usize, value: T) { ... }
    fn try_masked_load<T: MmioOperand>(
        &self,
        offset: usize,
        mask: T,
    ) -> Result<T, MmioError> { ... }
    fn masked_load<T: MmioOperand>(&self, offset: usize, mask: T) -> T { ... }
    fn try_masked_modify<T: MmioOperand>(
        &mut self,
        offset: usize,
        mask: T,
        value: T,
    ) -> Result<(), MmioError> { ... }
    fn masked_modify<T: MmioOperand>(
        &mut self,
        offset: usize,
        mask: T,
        value: T,
    ) { ... }
}

This trait extends Mmio with some useful utilities. There is a blanket implementation for all types implementing Mmio.

Functions may go into this trait instead of Mmio if any of the following is true:

• their behavior shouldn’t differ across Mmio implementations
• they would make Mmio not dyn compatible
• they would introduce an unnecessary burden on Mmio implementers

Provided Methods

fn check_aligned_for<T>(&self, offset: usize) -> Result<(), MmioError>

Check that the given offset into this MMIO region would be suitable aligned for type T. There is no guarantee that this offset is within the bounds of the MMIO region or that there would be sufficient capacity to hold a T at that offset. See MmioExt::check_suitable_for.

Returns MmioError::Unaligned if the offset os not suitably aligned.

fn check_capacity_for<T>(&self, offset: usize) -> Result<(), MmioError>

Checks that the given offset into this MMIO region has sufficient capacity to hold a value of type T. There is no guarantee that the offset is suitably aligned. See MmioExt::check_capacity_for.

fn check_suitable_for<T>(&self, offset: usize) -> Result<(), MmioError>

Checks that the given offset into this MMIO rgion is suitably aligned and has sufficient capacity for a value of type T.

fn try_load<T: MmioOperand>(&self, offset: usize) -> Result<T, MmioError>

Loads an MmioOperand from the MMIO region at the given offset.

Errors

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

fn load<T: MmioOperand>(&self, offset: usize) -> T

Loads an MmioOperand from the MMIO region at the given offset.

Panics

If self.check_suitable_for::<T>(offset) would fail.

See MmioExt::try_load for a non-panicking version.

fn try_store<T: MmioOperand>( &mut self, offset: usize, value: T, ) -> Result<(), MmioError>

Stores an MmioOperand to the MMIO region at the given offset.

Errors

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

fn store<T: MmioOperand>(&mut self, offset: usize, value: T)

Stores an MmioOperand to the MMIO region at the given offset.

Panics

If self.check_suitable_for::<T>(offset) would fail.

See MmioExt::try_store for a non-panicking version.

fn try_masked_load<T: MmioOperand>( &self, offset: usize, mask: T, ) -> Result<T, MmioError>

Loads an MmioOperand value from an MMIO region at the given offset, returning only the bits set in the given mask.

Errors

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

fn masked_load<T: MmioOperand>(&self, offset: usize, mask: T) -> T

Loads an MmioOperand value from an MMIO region at the given offset, returning only the bits set in the given mask.

Panics

If self.check_suitable_for::<T>(offset) would fail.

See MmioExt::try_masked_load for a non-panicking version.

fn try_masked_modify<T: MmioOperand>( &mut self, offset: usize, mask: T, value: T, ) -> Result<(), MmioError>

Updates the value in the MMIO region at the given offset, only modifying the bits set in the given mask.

This operation performs a read-modify-write in order to only modify the bits matching the mask. As this is performed as a load from device memory followed by a store to device memory, the device may change state in between these operations.

Callers must ensure that the this sequence of operations is valid for the device they’re accessing and their use case.

Errors

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

fn masked_modify<T: MmioOperand>(&mut self, offset: usize, mask: T, value: T)

Updates the value in the MMIO region at the given offset, only modifying the bits set in the given mask.

This operation performs a read-modify-write in order to only modify the bits matching the mask. As this is performed as a load from device memory followed by a store to device memory, the device may change state in between these operations.

Callers must ensure that the this sequence of operations is valid for the device they’re accessing and their use case.

Panics

If self.check_suitable_for::<T>(offset) would fail.

See MmioExt::try_masked_modify for a non-panicking version.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<M: Mmio> MmioExt for M