Performs a volatile write of a memory location with the given value without reading or dropping the old value.

Volatile operations are intended to act on I/O memory. As such, they are considered externally observable events (just like syscalls), 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 like [write][write()], 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 a register access. 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 access 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 writes. 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 write 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 on zero-sized types (e.g., if a zero-sized type is passed to write_volatile) are noops and may be ignored.

write_volatile does not drop the contents of dst. This is safe, but it could leak allocations or resources, so care should be taken not to overwrite an object that should be dropped when operating on Rust memory. Additionally, it does not drop src. Semantically, src is moved into the location pointed to by dst.

When invoked during const evaluation, this behaves like a regular write. In particular, such reads must always follow the first of the two cases above.

Store splitting

Exactly which hardware stores are performed by this function is, in general, highly target-dependent.

For a simple scalar, such as when T is a thin pointer, this will typically be one store assuming your target supports a store of exactly that size and alignment.

For anything else, it will be split into multiple stores in some unspecified way. This can happen even for scalars: notably, on many targets storing a u128 will still need to be split, despite being "one" scalar. On many targets storing anything larger than a pointer will need to be split. On all current targets a store larger than 64 bytes will need to be split. Any store whose size is not a power of two will also almost certainly need to be split.

There is no stability guarantee on how that splitting happens. It may change at any point.

Safety

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

• dst must be either valid for writes, or T must be a ZST, or dst must point to memory outside of all Rust allocations and writing to that memory must:

  • not trap, and
  • not cause any memory inside a Rust allocation to be modified.

• dst must be properly aligned.

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

Examples

Basic usage:

let mut x = 0;
let y = &mut x as *mut i32;
let z = 12;

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