Struct voladdress::VolRegion

#[repr(C)]
pub struct VolRegion<T, R, W> { /* private fields */ }

A dynamically sized span of volatile memory.

If you think of VolBlock as being similar to an array, this type is more similar to a slice.

The primary utility of this type is just that it bundles a pointer and length together, which allows you to have safe dynamic bounds checking. Just like with VolBlock, It does not have a lifetime or participate in borrow checking, and it does not enforce exclusive access.

A VolRegion assumes that elements of the region are directly one after the other (again, like how VolBlock works). If you need dynamic bounds checking on a spaced out series of values that would be some other type, which doesn’t currently exist in the library. (Open a PR maybe?)

Generic Parameters

• T / R / W: These parameters are applied to the VolAddress type returned when accessing the region in any way (indexing, iteration, etc).

Safety

• This type stores a base VolAddress internally, and so you must follow all of those safety rules. Notably, the base address must never be zero.
• The region must legally contain len contiguous values of the T type, starting from the base address.
• The region must not wrap around past the end of the address space.

Implementations

impl<T, R, W> VolRegion<T, R, W>

pub const unsafe fn from_raw_parts(addr: VolAddress<T, R, W>, len: usize) -> Self

Constructs a region from raw parts.

Safety

• As per the type docs.

pub const fn len(self) -> usize

Gets the length (in elements) of the region.

pub const fn as_usize(self) -> usize

Converts the VolBlock the usize for the start of the block.

pub const fn as_ptr(self) -> *const T

Converts the VolBlock into an individual const pointer.

This should usually only be used when you need to call a foreign function that expects a pointer.

pub const fn as_mut_ptr(self) -> *mut T

Converts the VolBlock into an individual mut pointer.

This should usually only be used when you need to call a foreign function that expects a pointer.

pub fn as_slice_ptr(self) -> *const [T]

Converts the VolBlock into a const slice pointer.

pub fn as_slice_mut_ptr(self) -> *mut [T]

Converts the VolBlock into an mut slice pointer.

pub const fn index(self, i: usize) -> VolAddress<T, R, W>

Index into the region.

Panics

• If the index requested is out of bounds this will panic.

pub const fn get(self, i: usize) -> Option<VolAddress<T, R, W>>

Gets Some(addr) if in bounds, or None if out of bounds.

pub fn sub_slice<RB: RangeBounds<usize>>(self, r: RB) -> Self

Gets a sub-slice of this region as a new region.

Panics

• If either specified end of the range is out of bounds this will panic.

pub const fn iter(self) -> VolBlockIter<T, R, W>

Gives an iterator over this region.

pub fn iter_range<RB: RangeBounds<usize>>(self, r: RB) -> VolBlockIter<T, R, W>

Same as region.sub_slice(range).iter()

impl<T, W> VolRegion<T, Safe, W>where T: Copy,

pub fn read_to_slice(self, buffer: &mut [T])

Volatile reads each element into the provided buffer.

Panics

• If the buffer’s length is not exactly this region’s length.

impl<T, W> VolRegion<T, Unsafe, W>where T: Copy,

pub unsafe fn read_to_slice(self, buffer: &mut [T])

Volatile reads each element into the provided buffer.

Panics

• If the buffer’s length is not exactly this region’s length.

Safety

• The safety rules of reading this address depend on the device. Consult your hardware manual.

impl<T, R> VolRegion<T, R, Safe>where T: Copy,

pub fn write_from_slice(self, buffer: &[T])

Volatile all slice elements into this region.

Panics

• If the buffer’s length is not exactly this region’s length.

impl<T, R> VolRegion<T, R, Unsafe>where T: Copy,

pub unsafe fn write_from_slice(self, buffer: &[T])

Volatile all slice elements into this region.

Panics

• If the buffer’s length is not exactly this region’s length.

Safety

• The safety rules of writing this address depend on the device. Consult your hardware manual.

Trait Implementations

impl<T, R, W> Clone for VolRegion<T, R, W>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, R, W> Debug for VolRegion<T, R, W>

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

Formats the value using the given formatter.

impl<T, R, W, const C: usize> From<VolBlock<T, R, W, C>> for VolRegion<T, R, W>

fn from(block: VolBlock<T, R, W, C>) -> Self

Converts to this type from the input type.

impl<T: Hash, R: Hash, W: Hash> Hash for VolRegion<T, R, W>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord, R: Ord, W: Ord> Ord for VolRegion<T, R, W>

fn cmp(&self, other: &VolRegion<T, R, W>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<T: PartialEq, R: PartialEq, W: PartialEq> PartialEq<VolRegion<T, R, W>> for VolRegion<T, R, W>

fn eq(&self, other: &VolRegion<T, R, W>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialOrd, R: PartialOrd, W: PartialOrd> PartialOrd<VolRegion<T, R, W>> for VolRegion<T, R, W>

fn partial_cmp(&self, other: &VolRegion<T, R, W>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, R, W> Copy for VolRegion<T, R, W>

impl<T: Eq, R: Eq, W: Eq> Eq for VolRegion<T, R, W>

impl<T, R, W> StructuralEq for VolRegion<T, R, W>

impl<T, R, W> StructuralPartialEq for VolRegion<T, R, W>