read_volatile in std::ptr - Rust (original) (raw)

Function read_volatile

1.9.0

pub unsafe fn read_volatile<T>(src: *const T) -> T

Expand description

Performs a volatile read of the value from src without moving it.

Volatile operations are intended to act on I/O memory. As such, they are considered externally observable events (just like syscalls, but less opaque), and are guaranteed to not be elided or reordered by the compiler across other externally observable events. With this in mind, there are two cases of usage that need to be distinguished:

• When a volatile operation is used for memory inside an allocation, it behaves exactly likeread, except for the additional guarantee that it won’t be elided or reordered (see above). This implies that the operation will actually access memory and not e.g. be lowered to reusing data from a previous read. Other than that, all the usual rules for memory accesses apply (including provenance). In particular, just like in C, whether an operation is volatile has no bearing whatsoever on questions involving concurrent accesses from multiple threads. Volatile accesses behave exactly like non-atomic accesses in that regard.
• Volatile operations, however, may also be used to access memory that is outside of any Rust allocation. In this use-case, the pointer does not have to be valid for reads. This is typically used for CPU and peripheral registers that must be accessed via an I/O memory mapping, most commonly at fixed addresses reserved by the hardware. These often have special semantics associated to their manipulation, and cannot be used as general purpose memory. Here, any address value is possible, including 0 and usize::MAX, so long as the semantics of such a read are well-defined by the target hardware. The provenance of the pointer is irrelevant, and it can be created with without_provenance. The access must not trap. It can cause side-effects, but those must not affect Rust-allocated memory in any way. This access is still not considered atomic, and as such it cannot be used for inter-thread synchronization.

Note that volatile memory operations where T is a zero-sized type are noops and may be ignored.

§Safety

Like read, read_volatile creates a bitwise copy of T, regardless of whether T isCopy. If T is not Copy, using both the returned value and the value at *src canviolate memory safety. However, storing non-Copy types in volatile memory is almost certainly incorrect.

Behavior is undefined if any of the following conditions are violated:

• src must be either valid for reads, or it must point to memory outside of all Rust allocations and reading from that memory must:
  • not trap, and
  • not cause any memory inside a Rust allocation to be modified.
• src must be properly aligned.
• Reading from src must produce a properly initialized value of type T.

Note that even if T has size 0, the pointer must be properly aligned.

§Examples

Basic usage:

let x = 12;
let y = &x as *const i32;

unsafe {
    assert_eq!(std::ptr::read_volatile(y), 12);
}