Struct UniqueMmioPointer 

pub struct UniqueMmioPointer<'a, T>(/* private fields */)
where
    T: ?Sized;

A unique owned pointer to the registers of some MMIO device.

It is guaranteed to be valid and unique; no other access to the MMIO space of the device may happen for the lifetime 'a.

A UniqueMmioPointer may be created from a mutable reference, but this should only be used for testing purposes, as references should never be constructed for real MMIO address space.

Implementations

impl<T> UniqueMmioPointer<'_, T>

pub unsafe fn read_unsafe(&mut self) -> T

Performs an MMIO read of the entire T.

Safety

This field must be safe to perform an MMIO read from.

pub unsafe fn write_unsafe(&mut self, value: T)

Performs an MMIO write of the entire T.

Note that this takes &mut self rather than &self because an MMIO read may cause side-effects that change the state of the device.

Safety

This field must be safe to perform an MMIO write to.

impl<T> UniqueMmioPointer<'_, T>

where T: ?Sized,

pub const unsafe fn new(regs: NonNull<T>) -> UniqueMmioPointer<'_, T>

Creates a new UniqueMmioPointer from a non-null raw pointer.

Safety

regs must be a properly aligned and valid pointer to some MMIO address space of type T, which is mapped as device memory and valid to read and write from any thread with volatile operations. There must not be any other aliases which are used to access the same MMIO region while this UniqueMmioPointer exists.

If T contains any fields wrapped in ReadOnly, WriteOnly or ReadWrite then they must indeed be safe to perform MMIO reads or writes on.

pub const unsafe fn child<U>( &mut self, regs: NonNull<U>, ) -> UniqueMmioPointer<'_, U>

where U: ?Sized,

Creates a new UniqueMmioPointer with the same lifetime as this one.

This is used internally by the field! macro and shouldn’t be called directly.

Safety

regs must be a properly aligned and valid pointer to some MMIO address space of type T, within the allocation that self points to.

pub const fn ptr_mut(&mut self) -> *mut T

Returns a raw mut pointer to the MMIO registers.

pub const fn ptr_nonnull(&mut self) -> NonNull<T>

Returns a NonNull<T> pointer to the MMIO registers.

pub const fn reborrow(&mut self) -> UniqueMmioPointer<'_, T>

Returns a new UniqueMmioPointer with a lifetime no greater than this one.

impl<'a, T> UniqueMmioPointer<'a, T>

where T: ?Sized,

pub const unsafe fn split_child<U>( &mut self, regs: NonNull<U>, ) -> UniqueMmioPointer<'a, U>

where U: ?Sized,

Creates a new UniqueMmioPointer with the same lifetime as this one, but not tied to the lifetime this one is borrowed for.

This is used internally by the split_fields! macro and shouldn’t be called directly.

Safety

regs must be a properly aligned and valid pointer to some MMIO address space of type T, within the allocation that self points to. split_child must not be called for the same child field more than once, and the original UniqueMmioPointer must not be used after split_child has been called for one or more of its fields.

impl<T> UniqueMmioPointer<'_, ReadWrite<T>>

where T: FromBytes + IntoBytes,

pub fn read(&mut self) -> T

Performs an MMIO read of the entire T.

impl<T> UniqueMmioPointer<'_, ReadWrite<T>>

where T: Immutable + IntoBytes,

pub fn write(&mut self, value: T)

Performs an MMIO write of the entire T.

impl<T> UniqueMmioPointer<'_, ReadWrite<T>>

where T: FromBytes + Immutable + IntoBytes,

pub fn modify(&mut self, f: impl FnOnce(T) -> T)

Performs an MMIO read of the entire T, applies the given function to it, and then performs an MMIO write of the resulting value.

This is equivalent to calling read then write.

pub fn modify_mut(&mut self, f: impl FnOnce(&mut T))

Performs an MMIO read of the entire T, calls the given function to modify it, and then performs an MMIO write of the resulting value.

This is equivalent to calling read then write.

impl<T> UniqueMmioPointer<'_, ReadPureWrite<T>>

where T: Immutable + IntoBytes,

pub fn write(&mut self, value: T)

Performs an MMIO write of the entire T.

impl<T> UniqueMmioPointer<'_, ReadPureWrite<T>>

where T: FromBytes + Immutable + IntoBytes,

pub fn modify(&mut self, f: impl FnOnce(T) -> T)

Performs an MMIO read of the entire T, applies the given function to it, and then performs an MMIO write of the resulting value.

This is equivalent to calling read then write.

pub fn modify_mut(&mut self, f: impl FnOnce(&mut T))

Performs an MMIO read of the entire T, calls the given function to modify it, and then performs an MMIO write of the resulting value.

This is equivalent to calling read then write.

impl<T> UniqueMmioPointer<'_, ReadOnly<T>>

where T: FromBytes + IntoBytes,

pub fn read(&mut self) -> T

Performs an MMIO read of the entire T.

impl<T> UniqueMmioPointer<'_, WriteOnly<T>>

where T: Immutable + IntoBytes,

pub fn write(&mut self, value: T)

Performs an MMIO write of the entire T.

impl<'a, T> UniqueMmioPointer<'a, [T]>

pub const fn get(&mut self, index: usize) -> Option<UniqueMmioPointer<'_, T>>

Returns a UniqueMmioPointer to an element of this slice, or None if the index is out of bounds.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut slice: UniqueMmioPointer<[ReadWrite<u32>]>;
let mut element = slice.get(1).unwrap();
element.write(42);

pub fn get_range( &mut self, range: Range<usize>, ) -> Option<UniqueMmioPointer<'_, [T]>>

Returns a UniqueMmioPointer to a range of elements of this slice, or None if the range is out of bounds.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut slice: UniqueMmioPointer<[ReadWrite<u32>]>;
let mut range = slice.get_range(1..3).unwrap();
range.get(0).unwrap().write(100);
range.get(1).unwrap().write(200);
assert_eq!(None, range.get(2));
assert_eq!(100, slice.get(1).unwrap().read());
assert_eq!(200, slice.get(2).unwrap().read());

pub fn iter(&mut self) -> UniqueMmioPointerIterator<'_, T>

Returns a new iterator of the items of the slice.

pub const fn take(self, index: usize) -> Option<UniqueMmioPointer<'a, T>>

Returns a UniqueMmioPointer to an element of this slice, or None if the index is out of bounds.

Unlike UniqueMmioPointer::get this takes ownership of the original pointer. This is useful when you want to store the resulting pointer without keeping the original pointer around.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut slice: UniqueMmioPointer<[ReadWrite<u32>]>;
let mut element = slice.take(1).unwrap();
element.write(42);
// `slice` can no longer be used at this point.

impl<'a, T, const LEN: usize> UniqueMmioPointer<'a, [T; LEN]>

pub fn split(self) -> [UniqueMmioPointer<'a, T>; LEN]

Splits a UniqueMmioPointer to an array into an array of UniqueMmioPointers.

pub fn split_some<const N: usize>( self, chosen: [usize; N], ) -> [UniqueMmioPointer<'a, T>; N]

Splits a UniqueMmioPointer to an array into an array of UniqueMmioPointers, taking only the chosen indices.

Panics if chosen contains the same index more than once, or any index out of bounds.

pub const fn as_mut_slice(&mut self) -> UniqueMmioPointer<'_, [T]>

Converts this array pointer to an equivalent slice pointer.

pub const fn get(&mut self, index: usize) -> Option<UniqueMmioPointer<'_, T>>

Returns a UniqueMmioPointer to an element of this array, or None if the index is out of bounds.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut slice: UniqueMmioPointer<[ReadWrite<u32>; 3]>;
let mut element = slice.get(1).unwrap();
element.write(42);
slice.get(2).unwrap().write(100);

pub fn get_range( &mut self, range: Range<usize>, ) -> Option<UniqueMmioPointer<'_, [T]>>

Returns a UniqueMmioPointer to a range of elements of this array, or None if the range is out of bounds.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut slice: UniqueMmioPointer<[ReadWrite<u32>; 3]>;
let mut range = slice.get_range(1..3).unwrap();
range.get(0).unwrap().write(100);
range.get(1).unwrap().write(200);
assert_eq!(None, range.get(2));
assert_eq!(100, slice.get(1).unwrap().read());
assert_eq!(200, slice.get(2).unwrap().read());

pub fn iter(&mut self) -> UniqueMmioPointerIterator<'_, T>

Returns a new iterator to the items of the array.

pub const fn take(self, index: usize) -> Option<UniqueMmioPointer<'a, T>>

Returns a UniqueMmioPointer to an element of this array, or None if the index is out of bounds.

Unlike UniqueMmioPointer::get this takes ownership of the original pointer. This is useful when you want to store the resulting pointer without keeping the original pointer around.

Example

use safe_mmio::{UniqueMmioPointer, fields::ReadWrite};

let mut array: UniqueMmioPointer<[ReadWrite<u32>; 3]>;
let mut element = array.take(1).unwrap();
element.write(42);
// `array` can no longer be used at this point.

Methods from Deref<Target = SharedMmioPointer<'a, T>>

pub unsafe fn read_unsafe(&self) -> T

Performs an MMIO read of the entire T.

Safety

This field must be safe to perform an MMIO read from, and doing so must not cause any side-effects.

pub unsafe fn child<U>(&self, regs: NonNull<U>) -> SharedMmioPointer<'a, U>

where U: ?Sized,

Creates a new SharedMmioPointer with the same lifetime as this one.

This is used internally by the field_shared! macro and shouldn’t be called directly.

Safety

regs must be a properly aligned and valid pointer to some MMIO address space of type T, within the allocation that self points to.

pub fn ptr(&self) -> *const T

Returns a raw const pointer to the MMIO registers.

Trait Implementations

impl<T> Debug for UniqueMmioPointer<'_, T>

where T: ?Sized,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, T> Deref for UniqueMmioPointer<'a, T>

where T: ?Sized,

type Target = SharedMmioPointer<'a, T>

The resulting type after dereferencing.

fn deref(&self) -> &<UniqueMmioPointer<'a, T> as Deref>::Target

Dereferences the value.

impl<'a, T> From<&'a mut T> for UniqueMmioPointer<'a, T>

where T: ?Sized,

fn from(r: &'a mut T) -> UniqueMmioPointer<'a, T>

Converts to this type from the input type.

impl<'a, T, const LEN: usize> From<UniqueMmioPointer<'a, [T; LEN]>> for UniqueMmioPointer<'a, [T]>

fn from(value: UniqueMmioPointer<'a, [T; LEN]>) -> UniqueMmioPointer<'a, [T]>

Converts to this type from the input type.

impl<'a, T> From<UniqueMmioPointer<'a, T>> for SharedMmioPointer<'a, T>

where T: ?Sized,

fn from(unique: UniqueMmioPointer<'a, T>) -> SharedMmioPointer<'a, T>

Converts to this type from the input type.

impl<'a, T> From<UniqueMmioPointer<'a, T>> for UniqueMmioPointer<'a, [T]>

fn from(value: UniqueMmioPointer<'a, T>) -> UniqueMmioPointer<'a, [T]>

Converts to this type from the input type.

impl<'a, T> From<UniqueMmioPointer<'a, T>> for UniqueMmioPointer<'a, [T; 1]>

fn from(value: UniqueMmioPointer<'a, T>) -> UniqueMmioPointer<'a, [T; 1]>

Converts to this type from the input type.

impl<'a, T> IntoIterator for UniqueMmioPointer<'a, [T]>

type Item = UniqueMmioPointer<'a, T>

The type of the elements being iterated over.

type IntoIter = UniqueMmioPointerIterator<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <UniqueMmioPointer<'a, [T]> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<'a, T, const LEN: usize> IntoIterator for UniqueMmioPointer<'a, [T; LEN]>

type Item = UniqueMmioPointer<'a, T>

The type of the elements being iterated over.

type IntoIter = UniqueMmioPointerIterator<'a, T>

Which kind of iterator are we turning this into?

fn into_iter( self, ) -> <UniqueMmioPointer<'a, [T; LEN]> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T> PartialEq for UniqueMmioPointer<'_, T>

where T: ?Sized,

fn eq(&self, other: &UniqueMmioPointer<'_, T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Eq for UniqueMmioPointer<'_, T>

where T: ?Sized,