editing

Author: RalfJung

library/core/src/ptr/mod.rs

@@ -116,6 +116,10 @@
 //! fully contiguous (i.e., has no "holes"), there is no guarantee that this
 //! will not change in the future.
 //!
+//! Allocated objects must behave like "normal" memory: in particular, reads must not have
+//! side-effects, and writes must become visible to other threads using the usual synchronization
+//! primitives.
+//!
 //! For any allocated object with `base` address, `size`, and a set of
 //! `addresses`, the following are guaranteed:
 //! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base +
@@ -1755,38 +1759,30 @@ pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 /// over time. That being said, the semantics will almost always end up pretty
 /// similar to [C11's definition of volatile][c11].
 ///
-/// Volatile operations are intended to act on I/O memory, and are guaranteed
-/// to not be elided or reordered by the compiler across other volatile
-/// operations. 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], all
-///   the typical restrictions of Rust-allocated memory apply, meaning things
-///   like data races and mutable aliasing remain as undefined behavior. In
-///   addition, the volatile rule that the operation won't be elided or
-///   reordered applies, such that the operation will access memory and not e.g.
-///   be lowered to a register access or stack pop. The memory in `src` should
-///   remain unchanged. 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. All this is because this kind of target-memory may be used from
-///   safe code at any time, and its validity assumptions must not be violated.
-///
-/// - Volatile operations, however, provide a conditionally valid way to access
-///   memory that is _outside_ of any allocation. The main use-case is 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, from 0 to
-///   [`usize::MAX`], so long as its semantics are well-defined by the target
-///   hardware. The access is restricted to not trap/interrupt. It can (and
-///   usually will) cause side-effects, but note they shouldn't affect
-///   Rust-allocated memory in any way.
-///
-/// The compiler shouldn't change the relative order or number of volatile
-/// memory operations. However, volatile memory operations on zero-sized types
-/// (e.g., if a zero-sized type is passed to `read_volatile`) are noops
-/// and may be ignored.
+/// 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
+///   [`read`], 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 or stack pop. Other than that, all the usual rules for memory accesses
+///   apply. 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 access memory that is _outside_ of any Rust
+///   allocation. The main use-case is 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 access must not trap. It
+///   can (and usually will) cause side-effects, but those must not affect Rust-allocated memory in
+///   any way.
+///
+/// Note that volatile memory operations on zero-sized types (e.g., if a zero-sized type is passed
+/// to `read_volatile`) are noops and may be ignored.
 ///
 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
 /// [allocation]: crate::ptr#allocated-object
@@ -1795,15 +1791,14 @@ pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `src` must be readable without trapping.
+/// * `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.
 ///
-/// * No Rust memory may be modified.
-///
-/// * If operating on an allocation, `src` must point to a properly initialized
-///   value of type `T`, and the safe usage assumptions of the data must be
-///   satisfied.
+/// * Reading from `src` must produce a properly initialized value of type `T`.
 ///
 /// Like [`read`], `read_volatile` creates a bitwise copy of `T`, regardless of
 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned