docs: further revision on read_volatile

Author: RalfJung

library/core/src/ptr/mod.rs

@@ -113,6 +113,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 +
@@ -1747,69 +1751,61 @@ pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 
 /// Performs a volatile read of the value from `src` without moving it.
 ///
-/// Rust does not currently have a rigorously and formally defined memory model,
-/// so the precise semantics of what "volatile" means here is subject to change
-/// 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.
+/// Rust does not currently have a rigorously and formally defined memory model, so the precise
+/// semantics of what "volatile" means here is subject to change 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. 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. In this use-case, the pointer validity rules in the [module documentation][mod-docs]
+///   may not apply.
+///
+/// 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
+/// [mod-docs]: crate::ptr
 ///
 /// # Safety
 ///
 /// 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.
+/// * Reading from `src` must produce a properly initialized value of type `T`.
 ///
-/// * 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.
-///
-/// 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
-/// value and the value at `*src` can [violate memory safety][read-ownership].
-/// However, modeling volatile memory with non-[`Copy`] types is almost
-/// certainly incorrect.
+/// 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 value and the value at `*src` can
+/// [violate memory safety][read-ownership]. However, modeling volatile memory with non-[`Copy`]
+/// types is almost certainly incorrect.
 ///
 /// Note that even if `T` has size `0`, the pointer must be properly aligned.
 ///
+/// [valid]: self#safety
 /// [read-ownership]: read#ownership-of-the-returned-value
 ///
 /// # Examples