From e5b0694483401cbf506d171d98423110407f2865 Mon Sep 17 00:00:00 2001
From: Ralf Jung <post@ralfj.de>
Date: Sat, 10 Aug 2024 18:55:04 +0200
Subject: [PATCH] clarify situation of non-synchronized differently-sized
 accesses

---
 library/core/src/sync/atomic.rs                        | 3 ++-
 src/tools/miri/src/concurrency/data_race.rs            | 7 +++----
 src/tools/miri/tests/fail/data_race/mixed_size_read.rs | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs
index bd187a1474692..06ded29432274 100644
--- a/library/core/src/sync/atomic.rs
+++ b/library/core/src/sync/atomic.rs
@@ -43,7 +43,8 @@
 //!
 //! That said, Rust *does* inherit the C++ limitation that non-synchronized atomic accesses may not
 //! partially overlap: they must be either disjoint or access the exact same memory. This in
-//! particular rules out non-synchronized differently-sized accesses to the same data.
+//! particular rules out non-synchronized differently-sized atomic accesses to the same data.
+//! (Non-synchronized differently-sized non-atomic read accesses are permitted.)
 //!
 //! [cpp]: https://en.cppreference.com/w/cpp/atomic
 //! [cpp-intro.races]: https://timsong-cpp.github.io/cppwp/n4868/intro.multithread#intro.races
diff --git a/src/tools/miri/src/concurrency/data_race.rs b/src/tools/miri/src/concurrency/data_race.rs
index 69ba396a58b69..5897c59ab70df 100644
--- a/src/tools/miri/src/concurrency/data_race.rs
+++ b/src/tools/miri/src/concurrency/data_race.rs
@@ -304,8 +304,7 @@ impl AccessType {
     }
 }
 
-/// Memory Cell vector clock metadata
-/// for data-race detection.
+/// Per-byte vector clock metadata for data-race detection.
 #[derive(Clone, PartialEq, Eq, Debug)]
 struct MemoryCellClocks {
     /// The vector-clock timestamp and the thread that did the last non-atomic write. We don't need
@@ -324,8 +323,8 @@ struct MemoryCellClocks {
     read: VClock,
 
     /// Atomic access, acquire, release sequence tracking clocks.
-    /// For non-atomic memory in the common case this
-    /// value is set to None.
+    /// For non-atomic memory this value is set to None.
+    /// For atomic memory, each byte carries this information.
     atomic_ops: Option<Box<AtomicMemoryCellClocks>>,
 }
 
diff --git a/src/tools/miri/tests/fail/data_race/mixed_size_read.rs b/src/tools/miri/tests/fail/data_race/mixed_size_read.rs
index 61af972b3dca8..fa4ea8053ef1a 100644
--- a/src/tools/miri/tests/fail/data_race/mixed_size_read.rs
+++ b/src/tools/miri/tests/fail/data_race/mixed_size_read.rs
@@ -10,7 +10,7 @@ fn convert(a: &AtomicU16) -> &[AtomicU8; 2] {
 }
 
 // We can't allow mixed-size accesses; they are not possible in C++ and even
-// Intel says you shouldn't do it.
+// Intel says you shouldn't do it. Even read-read races are disallowed that way.
 fn main() {
     let a = AtomicU16::new(0);
     let a16 = &a;