Struct volatile::VolatileRef

source ·

pub struct VolatileRef<'a, T, A = ReadWrite, O = VolatileOps>where
    T: ?Sized,
{ /* private fields */ }

Expand description

Volatile pointer type that respects Rust’s aliasing rules.

This pointer type behaves similar to Rust’s reference types:

it requires exclusive &mut self access for mutability
only read-only types implement [Clone] and [Copy]
[Send] and [Sync] are implemented if T: Sync

To perform volatile operations on VolatileRef types, use the as_ptr or as_mut_ptr methods to create a temporary VolatilePtr instance.

Since not all volatile resources (e.g. memory mapped device registers) are both readable and writable, this type supports limiting the allowed access types through an optional second generic parameter A that can be one of ReadWrite, ReadOnly, or WriteOnly. It defaults to ReadWrite, which allows all operations.

The size of this struct is the same as the size of the contained reference.

Implementations§

source §

impl<'a, T> VolatileRef<'a, T>
where T: ?Sized,

Constructor functions.

These functions construct new VolatileRef values. While the new function creates a VolatileRef instance with unrestricted access, there are also functions for creating read-only or write-only instances.

source

pub unsafe fn new(pointer: NonNull<T>) -> Self

Turns the given pointer into a VolatileRef.

§Safety

The pointer must be properly aligned.
It must be “dereferenceable” in the sense defined in the [core::ptr] documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime ’a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this VolatileRef exists, the memory the pointer points to must not get accessed (read or written) through any other pointer.

source

pub const unsafe fn new_read_only( pointer: NonNull<T>, ) -> VolatileRef<'a, T, ReadOnly>

Turns the given pointer into a read-only VolatileRef.

§Safety

The pointer must be properly aligned.
It must be “dereferenceable” in the sense defined in the [core::ptr] documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime ’a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this VolatileRef exists, the memory the pointer points to must not get mutated.

source

pub const unsafe fn new_restricted<A>( access: A, pointer: NonNull<T>, ) -> VolatileRef<'a, T, A>
where A: Access,

Turns the given pointer into a VolatileRef instance with the given access.

§Safety

The pointer must be properly aligned.
It must be “dereferenceable” in the sense defined in the [core::ptr] documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime ’a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this VolatileRef exists, the memory the pointer points to must not get mutated. If the given access parameter allows write access, the pointer must not get read either while this VolatileRef exists.

source

pub const unsafe fn new_restricted_with_ops<A, O>( access: A, ops: O, pointer: NonNull<T>, ) -> VolatileRef<'a, T, A, O>
where A: Access, O: Ops,

source

pub fn from_ref(reference: &'a T) -> VolatileRef<'a, T, ReadOnly>
where T: 'a,

Creates a VolatileRef from the given shared reference.

Note: This function is only intended for testing, not for accessing real volatile data. The reason is that the &mut T argument is considered dereferenceable by Rust, so the compiler is allowed to insert non-volatile reads. This might lead to undesired (or even undefined?) behavior when accessing volatile data. So to be safe, only create raw pointers to volatile data and use the Self::new constructor instead.

source

pub fn from_mut_ref(reference: &'a mut T) -> Self
where T: 'a,

Creates a VolatileRef from the given mutable reference.

Note: This function is only intended for testing, not for accessing real volatile data. The reason is that the &mut T argument is considered dereferenceable by Rust, so the compiler is allowed to insert non-volatile reads. This might lead to undesired (or even undefined?) behavior when accessing volatile data. So to be safe, only create raw pointers to volatile data and use the Self::new constructor instead.

source §

impl<'a, T, A, O> VolatileRef<'a, T, A, O>
where T: ?Sized,

source

pub fn as_ptr(&self) -> VolatilePtr<'_, T, A::RestrictShared, O>
where A: Access,

Borrows this VolatileRef as a read-only VolatilePtr.

Use this method to do (partial) volatile reads of the referenced data.

source

pub fn as_mut_ptr(&mut self) -> VolatilePtr<'_, T, A, O>
where A: Access,

Borrows this VolatileRef as a mutable VolatilePtr.

Use this method to do (partial) volatile reads or writes of the referenced data.

source

pub fn into_ptr(self) -> VolatilePtr<'a, T, A>
where A: Access,

Converts this VolatileRef into a VolatilePtr with full access without shortening the lifetime.

Use this method when you need a VolatilePtr instance that lives for the full lifetime 'a.

This method consumes the VolatileRef.

source §

impl<'a, T> VolatileRef<'a, T, ReadWrite>
where T: ?Sized,

Methods for restricting access.

source

pub fn read_only(self) -> VolatileRef<'a, T, ReadOnly>

Restricts access permissions to read-only.

§Example

use volatile::VolatileRef;
use core::ptr::NonNull;

let mut value: i16 = -4;
let mut volatile = VolatileRef::from_mut_ref(&mut value);

let read_only = volatile.read_only();
assert_eq!(read_only.as_ptr().read(), -4);
// read_only.as_ptr().write(10); // compile-time error

source

pub fn write_only(self) -> VolatileRef<'a, T, WriteOnly>

Restricts access permissions to write-only.

§Example

Creating a write-only reference to a struct field:

use volatile::{VolatileRef};
use core::ptr::NonNull;

#[derive(Clone, Copy)]
struct Example { field_1: u32, field_2: u8, }
let mut value = Example { field_1: 15, field_2: 255 };
let mut volatile = VolatileRef::from_mut_ref(&mut value);

let write_only = volatile.write_only();
// write_only.as_ptr().read(); // compile-time error