Struct volatile::Volatile

#[repr(transparent)]
pub struct Volatile<R, A = ReadWrite> { /* private fields */ }

Wraps a reference to make accesses to the referenced value volatile.

Allows volatile reads and writes on the referenced value. The referenced value needs to be Copy for reading and writing, as volatile reads and writes take and return copies of the value.

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

impl<R> Volatile<R>

Constructor functions for creating new values

These functions allow to construct a new Volatile instance from a reference type. While the new function creates a Volatile instance with unrestricted access, there are also functions for creating read-only or write-only instances.

pub const fn new(reference: R) -> Volatile<R>

Constructs a new volatile instance wrapping the given reference.

While it is possible to construct Volatile instances from arbitrary values (including non-reference values), most of the methods are only available when the wrapped type is a reference. The only reason that we don’t forbid non-reference types in the constructor functions is that the Rust compiler does not support trait bounds on generic const functions yet. When this becomes possible, we will release a new version of this library with removed support for non-references. For these reasons it is recommended to use the Volatile type only with references.

Example

use volatile::Volatile;

let mut value = 0u32;

let mut volatile = Volatile::new(&mut value);
volatile.write(1);
assert_eq!(volatile.read(), 1);

pub const fn new_read_only(reference: R) -> Volatile<R, ReadOnly>

Constructs a new read-only volatile instance wrapping the given reference.

This is equivalent to the new function with the difference that the returned Volatile instance does not permit write operations. This is for example useful with memory-mapped hardware registers that are defined as read-only by the hardware.

Example

Reading is allowed:

use volatile::Volatile;

let value = 0u32;

let volatile = Volatile::new_read_only(&value);
assert_eq!(volatile.read(), 0);

But writing is not:

use volatile::Volatile;

let mut value = 0u32;

let mut volatile = Volatile::new_read_only(&mut value);
volatile.write(1);
//ERROR: ^^^^^ the trait `volatile::access::Writable` is not implemented
//             for `volatile::access::ReadOnly`

pub const fn new_write_only(reference: R) -> Volatile<R, WriteOnly>

Constructs a new write-only volatile instance wrapping the given reference.

This is equivalent to the new function with the difference that the returned Volatile instance does not permit read operations. This is for example useful with memory-mapped hardware registers that are defined as write-only by the hardware.

Example

Writing is allowed:

use volatile::Volatile;

let mut value = 0u32;

let mut volatile = Volatile::new_write_only(&mut value);
volatile.write(1);

But reading is not:

use volatile::Volatile;

let value = 0u32;

let volatile = Volatile::new_write_only(&value);
volatile.read();
//ERROR: ^^^^ the trait `volatile::access::Readable` is not implemented
//            for `volatile::access::WriteOnly`

impl<R, T, A> Volatile<R, A>where R: Deref<Target = T>, T: Copy,

Methods for references to Copy types

pub fn read(&self) -> Twhere A: Readable,

Performs a volatile read of the contained value.

Returns a copy of the read value. Volatile reads are guaranteed not to be optimized away by the compiler, but by themselves do not have atomic ordering guarantees. To also get atomicity, consider looking at the Atomic wrapper types of the standard/core library.

Examples

use volatile::Volatile;

let value = 42;
let shared_reference = Volatile::new(&value);
assert_eq!(shared_reference.read(), 42);

let mut value = 50;
let mut_reference = Volatile::new(&mut value);
assert_eq!(mut_reference.read(), 50);

pub fn write(&mut self, value: T)where A: Writable, R: DerefMut,

Performs a volatile write, setting the contained value to the given value.

Volatile writes are guaranteed to not be optimized away by the compiler, but by themselves do not have atomic ordering guarantees. To also get atomicity, consider looking at the Atomic wrapper types of the standard/core library.

Example

use volatile::Volatile;

let mut value = 42;
let mut volatile = Volatile::new(&mut value);
volatile.write(50);

assert_eq!(volatile.read(), 50);

pub fn update<F>(&mut self, f: F)where A: Readable + Writable, R: DerefMut, F: FnOnce(&mut T),

Updates the contained value using the given closure and volatile instructions.

Performs a volatile read of the contained value, passes a mutable reference to it to the function f, and then performs a volatile write of the (potentially updated) value back to the contained value.

use volatile::Volatile;

let mut value = 42;
let mut volatile = Volatile::new(&mut value);
volatile.update(|val| *val += 1);

assert_eq!(volatile.read(), 43);

impl<R, A> Volatile<R, A>

Method for extracting the wrapped value.

pub fn extract_inner(self) -> R

Extracts the inner value stored in the wrapper type.

This method gives direct access to the wrapped reference and thus allows non-volatile access again. This is seldom what you want since there is usually a reason that a reference is wrapped in Volatile. However, in some cases it might be required or useful to use the read_volatile/write_volatile pointer methods of the standard library directly, which this method makes possible.

Since no memory safety violation can occur when accessing the referenced value using non-volatile operations, this method is safe. However, it can lead to bugs at the application level, so this method should be used with care.

Example

use volatile::Volatile;

let mut value = 42;
let mut volatile = Volatile::new(&mut value);
volatile.write(50);
let unwrapped: &mut i32 = volatile.extract_inner();

assert_eq!(*unwrapped, 50); // non volatile access, be careful!

impl<R, T, A> Volatile<R, A>where R: Deref<Target = T>, T: ?Sized,

Transformation methods for accessing struct fields

pub fn map<'a, F, U>(&'a self, f: F) -> Volatile<&'a U, A>where F: FnOnce(&'a T) -> &'a U, U: ?Sized, T: 'a,

Constructs a new Volatile reference by mapping the wrapped value.

This method is useful for accessing individual fields of volatile structs.

Note that this method gives temporary access to the wrapped reference, which allows accessing the value in a non-volatile way. This is normally not what you want, so this method should only be used for reference-to-reference transformations.

Examples

Accessing a struct field:

use volatile::Volatile;

struct Example { field_1: u32, field_2: u8, }
let mut value = Example { field_1: 15, field_2: 255 };
let mut volatile = Volatile::new(&mut value);

// construct a volatile reference to a field
let field_2 = volatile.map(|example| &example.field_2);
assert_eq!(field_2.read(), 255);

Don’t misuse this method to do a non-volatile read of the referenced value:

use volatile::Volatile;

let mut value = 5;
let mut volatile = Volatile::new(&mut value);

// DON'T DO THIS:
let mut readout = 0;
volatile.map(|value| {
   readout = *value; // non-volatile read, might lead to bugs
   value
});

pub fn map_mut<'a, F, U>(&'a mut self, f: F) -> Volatile<&'a mut U, A>where F: FnOnce(&mut T) -> &mut U, R: DerefMut, U: ?Sized, T: 'a,

Constructs a new mutable Volatile reference by mapping the wrapped value.

This method is useful for accessing individual fields of volatile structs.

Note that this method gives temporary access to the wrapped reference, which allows accessing the value in a non-volatile way. This is normally not what you want, so this method should only be used for reference-to-reference transformations.

Examples

Accessing a struct field:

use volatile::Volatile;

struct Example { field_1: u32, field_2: u8, }
let mut value = Example { field_1: 15, field_2: 255 };
let mut volatile = Volatile::new(&mut value);

// construct a volatile reference to a field
let mut field_2 = volatile.map_mut(|example| &mut example.field_2);
field_2.write(128);
assert_eq!(field_2.read(), 128);

Don’t misuse this method to do a non-volatile read or write of the referenced value:

use volatile::Volatile;

let mut value = 5;
let mut volatile = Volatile::new(&mut value);

// DON'T DO THIS:
volatile.map_mut(|value| {
   *value = 10; // non-volatile write, might lead to bugs
   value
});

impl<T, R, A> Volatile<R, A>where R: Deref<Target = [T]>,

Methods for volatile slices

pub fn index<'a, I>(&'a self, index: I) -> Volatile<&'a I::Output, A>where I: SliceIndex<[T]>, T: 'a,

Applies the index operation on the wrapped slice.

Returns a shared Volatile reference to the resulting subslice.

This is a convenience method for the map(|slice| slice.index(index)) operation, so it has the same behavior as the indexing operation on slice (e.g. panic if index is out-of-bounds).

Examples

Accessing a single slice element:

use volatile::Volatile;

let array = [1, 2, 3];
let slice = &array[..];
let volatile = Volatile::new(slice);
assert_eq!(volatile.index(1).read(), 2);

Accessing a subslice:

use volatile::Volatile;

let array = [1, 2, 3];
let slice = &array[..];
let volatile = Volatile::new(slice);
let subslice = volatile.index(1..);
assert_eq!(subslice.index(0).read(), 2);

pub fn index_mut<'a, I>(&'a mut self, index: I) -> Volatile<&mut I::Output, A>where I: SliceIndex<[T]>, R: DerefMut, T: 'a,

Applies the mutable index operation on the wrapped slice.

Returns a mutable Volatile reference to the resulting subslice.

This is a convenience method for the map_mut(|slice| slice.index_mut(index)) operation, so it has the same behavior as the indexing operation on slice (e.g. panic if index is out-of-bounds).

Examples

Accessing a single slice element:

use volatile::Volatile;

let mut array = [1, 2, 3];
let slice = &mut array[..];
let mut volatile = Volatile::new(slice);
volatile.index_mut(1).write(6);
assert_eq!(volatile.index(1).read(), 6);

Accessing a subslice:

use volatile::Volatile;

let mut array = [1, 2, 3];
let slice = &mut array[..];
let mut volatile = Volatile::new(slice);
let mut subslice = volatile.index_mut(1..);
subslice.index_mut(0).write(6);
assert_eq!(subslice.index(0).read(), 6);

pub fn copy_into_slice(&self, dst: &mut [T])where T: Copy,

Copies all elements from self into dst, using a volatile memcpy.

The length of dst must be the same as self.

The method is only available with the unstable feature enabled (requires a nightly Rust compiler).

Panics

This function will panic if the two slices have different lengths.

Examples

Copying two elements from a volatile slice:

use volatile::Volatile;

let src = [1, 2];
// the `Volatile` type does not work with arrays, so convert `src` to a slice
let slice = &src[..];
let volatile = Volatile::new(slice);
let mut dst = [5, 0, 0];

// Because the slices have to be the same length,
// we slice the destination slice from three elements
// to two. It will panic if we don't do this.
volatile.copy_into_slice(&mut dst[1..]);

assert_eq!(src, [1, 2]);
assert_eq!(dst, [5, 1, 2]);

pub fn copy_from_slice(&mut self, src: &[T])where T: Copy, R: DerefMut,

Copies all elements from src into self, using a volatile memcpy.

The length of src must be the same as self.

This method is similar to the slice::copy_from_slice method of the standard library. The difference is that this method performs a volatile copy.

The method is only available with the unstable feature enabled (requires a nightly Rust compiler).

Panics

This function will panic if the two slices have different lengths.

Examples

Copying two elements from a slice into a volatile slice:

use volatile::Volatile;

let src = [1, 2, 3, 4];
let mut dst = [0, 0];
// the `Volatile` type does not work with arrays, so convert `dst` to a slice
let slice = &mut dst[..];
let mut volatile = Volatile::new(slice);

// Because the slices have to be the same length,
// we slice the source slice from four elements
// to two. It will panic if we don't do this.
volatile.copy_from_slice(&src[2..]);

assert_eq!(src, [1, 2, 3, 4]);
assert_eq!(dst, [3, 4]);

pub fn copy_within(&mut self, src: impl RangeBounds<usize>, dest: usize)where T: Copy, R: DerefMut,

Copies elements from one part of the slice to another part of itself, using a volatile memmove.

src is the range within self to copy from. dest is the starting index of the range within self to copy to, which will have the same length as src. The two ranges may overlap. The ends of the two ranges must be less than or equal to self.len().

This method is similar to the slice::copy_within method of the standard library. The difference is that this method performs a volatile copy.

This method is only available with the unstable feature enabled (requires a nightly Rust compiler).

Panics

This function will panic if either range exceeds the end of the slice, or if the end of src is before the start.

Examples

Copying four bytes within a slice:

use volatile::Volatile;

let mut byte_array = *b"Hello, World!";
let mut slice: &mut [u8] = &mut byte_array[..];
let mut volatile = Volatile::new(slice);

volatile.copy_within(1..5, 8);

assert_eq!(&byte_array, b"Hello, Wello!");

impl<R, A> Volatile<R, A>where R: Deref<Target = [u8]>,

Methods for volatile byte slices

pub fn fill(&mut self, value: u8)where R: DerefMut,

Sets all elements of the byte slice to the given value using a volatile memset.

This method is similar to the slice::fill method of the standard library, with the difference that this method performs a volatile write operation. Another difference is that this method is only available for byte slices (not general &mut [T] slices) because there currently isn’t a instrinsic function that allows non-u8 values.

This method is only available with the unstable feature enabled (requires a nightly Rust compiler).

Example

use volatile::Volatile;

let mut buf = Volatile::new(vec![0; 10]);
buf.fill(1);
assert_eq!(buf.extract_inner(), vec![1; 10]);

impl<R, A, T, const N: usize> Volatile<R, A>where R: Deref<Target = [T; N]>,

Methods for converting arrays to slices

pub fn as_slice(&self) -> Volatile<&[T], A>

Converts an array reference to a shared slice.

This makes it possible to use the methods defined on slices.

Example

Reading a subslice from a volatile array reference using index:

use volatile::Volatile;

let src = [1, 2, 3, 4];
let volatile = Volatile::new(&src);

// convert the `Volatile<&[i32; 4]>` array reference to a `Volatile<&[i32]>` slice
let volatile_slice = volatile.as_slice();
// we can now use the slice methods
let subslice = volatile_slice.index(2..);

assert_eq!(subslice.index(0).read(), 3);
assert_eq!(subslice.index(1).read(), 4);

pub fn as_mut_slice(&mut self) -> Volatile<&mut [T], A>where R: DerefMut,

Converts a mutable array reference to a mutable slice.

This makes it possible to use the methods defined on slices.

Example

Writing to an index of a mutable array reference:

use volatile::Volatile;

let mut dst = [0, 0];
let mut volatile = Volatile::new(&mut dst);

// convert the `Volatile<&mut [i32; 2]>` array reference to a `Volatile<&mut [i32]>` slice
let mut volatile_slice = volatile.as_mut_slice();
// we can now use the slice methods
volatile_slice.index_mut(1).write(1);

assert_eq!(dst, [0, 1]);

impl<R> Volatile<R>

Methods for restricting access.

pub fn read_only(self) -> Volatile<R, ReadOnly>

Restricts access permissions to read-only.

Example

use volatile::Volatile;

let mut value: i16 = -4;
let mut volatile = Volatile::new(&mut value);

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

pub fn write_only(self) -> Volatile<R, WriteOnly>

Restricts access permissions to write-only.

Example

Creating a write-only reference to a struct field:

use volatile::Volatile;

struct Example { field_1: u32, field_2: u8, }
let mut value = Example { field_1: 15, field_2: 255 };
let mut volatile = Volatile::new(&mut value);

// construct a volatile write-only reference to `field_2`
let mut field_2 = volatile.map_mut(|example| &mut example.field_2).write_only();
field_2.write(14);
// field_2.read(); // compile-time error

Trait Implementations

impl<R: Clone, A: Clone> Clone for Volatile<R, A>

fn clone(&self) -> Volatile<R, A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R, T, A> Debug for Volatile<R, A>where R: Deref<Target = T>, T: Copy + Debug, A: Readable,

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

Formats the value using the given formatter.

impl<R> Debug for Volatile<R, WriteOnly>where R: Deref,

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

Formats the value using the given formatter.