Re: [PATCH v5 04/10] rust: sync: atomic: Add generic atomics

Andreas Hindborg
2025-06-26T12:15:47Z

"Boqun Feng" <boqun.feng@gmail.com> writes:

[...]

> +
> +impl<T: AllowAtomic> Atomic<T> {
> + /// Creates a new atomic.
> + pub const fn new(v: T) -> Self {
> + Self(Opaque::new(v))
> + }
> +
> + /// Creates a reference to [`Self`] from a pointer.
> + ///
> + /// # Safety
> + ///
> + /// - `ptr` has to be a valid pointer.
> + /// - `ptr` has to be valid for both reads and writes for the whole lifetime `'a`.
> + /// - For the whole lifetime of '`a`, other accesses to the object cannot cause data races
> + /// (defined by [`LKMM`]) against atomic operations on the returned reference.

I feel the wording is a bit tangled here. How about something along the
lines of

For the duration of `'a`, all accesses to the object must be atomic.

> + ///
> + /// [`LKMM`]: srctree/tools/memory-model
> + ///
> + /// # Examples
> + ///
> + /// Using [`Atomic::from_ptr()`] combined with [`Atomic::load()`] or [`Atomic::store()`] can
> + /// achieve the same functionality as `READ_ONCE()`/`smp_load_acquire()` or
> + /// `WRITE_ONCE()`/`smp_store_release()` in C side:
> + ///
> + /// ```rust
> + /// # use kernel::types::Opaque;
> + /// use kernel::sync::atomic::{Atomic, Relaxed, Release};
> + ///
> + /// // Assume there is a C struct `Foo`.
> + /// mod cbindings {
> + /// #[repr(C)]
> + /// pub(crate) struct foo { pub(crate) a: i32, pub(crate) b: i32 }
> + /// }
> + ///
> + /// let tmp = Opaque::new(cbindings::foo { a: 1, b: 2});
> + ///
> + /// // struct foo *foo_ptr = ..;
> + /// let foo_ptr = tmp.get();
> + ///
> + /// // SAFETY: `foo_ptr` is a valid pointer, and `.a` is inbound.

Did you mean to say "in bounds"? Or what is "inbound"?

> + /// let foo_a_ptr = unsafe { core::ptr::addr_of_mut!((*foo_ptr).a) };

This should be `&raw mut` by now, right?

> + ///
> + /// // a = READ_ONCE(foo_ptr->a);
> + /// //
> + /// // SAFETY: `foo_a_ptr` is a valid pointer for read, and all accesses on it is atomic, so no
> + /// // data race.
> + /// let a = unsafe { Atomic::from_ptr(foo_a_ptr) }.load(Relaxed);
> + /// # assert_eq!(a, 1);
> + ///
> + /// // smp_store_release(&foo_ptr->a, 2);
> + /// //
> + /// // SAFETY: `foo_a_ptr` is a valid pointer for write, and all accesses on it is atomic, so no
> + /// // data race.
> + /// unsafe { Atomic::from_ptr(foo_a_ptr) }.store(2, Release);
> + /// ```
> + ///
> + /// However, this should be only used when communicating with C side or manipulating a C struct.
> + pub unsafe fn from_ptr<'a>(ptr: *mut T) -> &'a Self
> + where
> + T: Sync,
> + {
> + // CAST: `T` is transparent to `Atomic<T>`.
> + // SAFETY: Per function safety requirement, `ptr` is a valid pointer and the object will
> + // live long enough. It's safe to return a `&Atomic<T>` because function safety requirement
> + // guarantees other accesses won't cause data races.
> + unsafe { &*ptr.cast::<Self>() }
> + }
> +
> + /// Returns a pointer to the underlying atomic variable.
> + ///
> + /// Extra safety requirement on using the return pointer: the operations done via the pointer
> + /// cannot cause data races defined by [`LKMM`].
> + ///
> + /// [`LKMM`]: srctree/tools/memory-model
> + pub const fn as_ptr(&self) -> *mut T {
> + self.0.get()
> + }
> +
> + /// Returns a mutable reference to the underlying atomic variable.
> + ///
> + /// This is safe because the mutable reference of the atomic variable guarantees the exclusive
> + /// access.
> + pub fn get_mut(&mut self) -> &mut T {
> + // SAFETY: `self.as_ptr()` is a valid pointer to `T`, and the object has already been
> + // initialized. `&mut self` guarantees the exclusive access, so it's safe to reborrow
> + // mutably.
> + unsafe { &mut *self.as_ptr() }
> + }
> +}
> +
> +impl<T: AllowAtomic> Atomic<T>
> +where
> + T::Repr: AtomicHasBasicOps,
> +{
> + /// Loads the value from the atomic variable.
> + ///
> + /// # Examples
> + ///
> + /// Simple usages:
> + ///
> + /// ```rust
> + /// use kernel::sync::atomic::{Atomic, Relaxed};
> + ///
> + /// let x = Atomic::new(42i32);
> + ///
> + /// assert_eq!(42, x.load(Relaxed));
> + ///
> + /// let x = Atomic::new(42i64);
> + ///
> + /// assert_eq!(42, x.load(Relaxed));
> + /// ```
> + ///
> + /// Customized new types in [`Atomic`]:
> + ///
> + /// ```rust
> + /// use kernel::sync::atomic::{generic::AllowAtomic, Atomic, Relaxed};
> + ///
> + /// #[derive(Clone, Copy)]
> + /// #[repr(transparent)]
> + /// struct NewType(u32);
> + ///
> + /// // SAFETY: `NewType` is transparent to `u32`, which has the same size and alignment as
> + /// // `i32`.
> + /// unsafe impl AllowAtomic for NewType {
> + /// type Repr = i32;
> + ///
> + /// fn into_repr(self) -> Self::Repr {
> + /// self.0 as i32
> + /// }
> + ///
> + /// fn from_repr(repr: Self::Repr) -> Self {
> + /// NewType(repr as u32)
> + /// }
> + /// }
> + ///
> + /// let n = Atomic::new(NewType(0));
> + ///
> + /// assert_eq!(0, n.load(Relaxed).0);
> + /// ```
> + #[doc(alias("atomic_read", "atomic64_read"))]
> + #[inline(always)]
> + pub fn load<Ordering: AcquireOrRelaxed>(&self, _: Ordering) -> T {
> + let a = self.as_ptr().cast::<T::Repr>();
> +
> + // SAFETY:
> + // - For calling the atomic_read*() function:
> + // - `self.as_ptr()` is a valid pointer, and per the safety requirement of `AllocAtomic`,

Typo `AllocAtomic`.

> + // a `*mut T` is a valid `*mut T::Repr`. Therefore `a` is a valid pointer,
> + // - per the type invariants, the following atomic operation won't cause data races.
> + // - For extra safety requirement of usage on pointers returned by `self.as_ptr():
> + // - atomic operations are used here.
> + let v = unsafe {
> + if Ordering::IS_RELAXED {
> + T::Repr::atomic_read(a)
> + } else {
> + T::Repr::atomic_read_acquire(a)
> + }
> + };
> +
> + T::from_repr(v)
> + }
> +
> + /// Stores a value to the atomic variable.
> + ///
> + /// # Examples
> + ///
> + /// ```rust
> + /// use kernel::sync::atomic::{Atomic, Relaxed};
> + ///
> + /// let x = Atomic::new(42i32);
> + ///
> + /// assert_eq!(42, x.load(Relaxed));
> + ///
> + /// x.store(43, Relaxed);
> + ///
> + /// assert_eq!(43, x.load(Relaxed));
> + /// ```
> + ///
> + #[doc(alias("atomic_set", "atomic64_set"))]
> + #[inline(always)]
> + pub fn store<Ordering: ReleaseOrRelaxed>(&self, v: T, _: Ordering) {
> + let v = T::into_repr(v);
> + let a = self.as_ptr().cast::<T::Repr>();
> +
> + // SAFETY:
> + // - For calling the atomic_set*() function:
> + // - `self.as_ptr()` is a valid pointer, and per the safety requirement of `AllocAtomic`,

Typo `AllocAtomic`.

Best regards,
Andreas Hindborg