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>

where T: FromBytes + IntoBytes,

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

Performs an MMIO read and returns the value.

If T is exactly 1, 2, 4 or 8 bytes long then this will be a single operation. Otherwise it will be split into several, reading chunks as large as possible.

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 read from.

impl<T> UniqueMmioPointer<'_, T>

where T: Immutable + IntoBytes,

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

Performs an MMIO write of the given value.

If T is exactly 1, 2, 4 or 8 bytes long then this will be a single operation. Otherwise it will be split into several, writing chunks as large as possible.

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<'_, ReadPureWrite<T>>

where T: Immutable + IntoBytes,

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

Performs an MMIO write of the entire T.

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 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(&mut self) -> [UniqueMmioPointer<'_, T>; LEN]

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

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 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 and returns the value.

If T is exactly 1, 2, 4 or 8 bytes long then this will be a single operation. Otherwise it will be split into several, reading chunks as large as possible.

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<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,