[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <DBBPI9ZJVO64.3A83G118BMVLI@kernel.org>
Date: Mon, 14 Jul 2025 12:30:12 +0200
From: "Benno Lossin" <lossin@...nel.org>
To: "Boqun Feng" <boqun.feng@...il.com>, <linux-kernel@...r.kernel.org>,
<rust-for-linux@...r.kernel.org>, <lkmm@...ts.linux.dev>,
<linux-arch@...r.kernel.org>
Cc: "Miguel Ojeda" <ojeda@...nel.org>, "Alex Gaynor"
<alex.gaynor@...il.com>, "Gary Guo" <gary@...yguo.net>,
Björn Roy Baron <bjorn3_gh@...tonmail.com>, "Andreas
Hindborg" <a.hindborg@...nel.org>, "Alice Ryhl" <aliceryhl@...gle.com>,
"Trevor Gross" <tmgross@...ch.edu>, "Danilo Krummrich" <dakr@...nel.org>,
"Will Deacon" <will@...nel.org>, "Peter Zijlstra" <peterz@...radead.org>,
"Mark Rutland" <mark.rutland@....com>, "Wedson Almeida Filho"
<wedsonaf@...il.com>, "Viresh Kumar" <viresh.kumar@...aro.org>, "Lyude
Paul" <lyude@...hat.com>, "Ingo Molnar" <mingo@...nel.org>, "Mitchell Levy"
<levymitchell0@...il.com>, "Paul E. McKenney" <paulmck@...nel.org>, "Greg
Kroah-Hartman" <gregkh@...uxfoundation.org>, "Linus Torvalds"
<torvalds@...ux-foundation.org>, "Thomas Gleixner" <tglx@...utronix.de>,
"Alan Stern" <stern@...land.harvard.edu>
Subject: Re: [PATCH v7 4/9] rust: sync: atomic: Add generic atomics
On Mon Jul 14, 2025 at 7:36 AM CEST, Boqun Feng wrote:
> To provide using LKMM atomics for Rust code, a generic `Atomic<T>` is
> added, currently `T` needs to be Send + Copy because these are the
> straightforward usages and all basic types support this.
>
> Implement `AllowAtomic` for `i32` and `i64`, and so far only basic
> operations load() and store() are introduced.
>
> Reviewed-by: Alice Ryhl <aliceryhl@...gle.com>
> Signed-off-by: Boqun Feng <boqun.feng@...il.com>
> ---
> rust/kernel/sync/atomic.rs | 14 ++
> rust/kernel/sync/atomic/generic.rs | 285 +++++++++++++++++++++++++++++
> 2 files changed, 299 insertions(+)
> create mode 100644 rust/kernel/sync/atomic/generic.rs
>
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index e80ac049f36b..c5193c1c90fe 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -16,7 +16,21 @@
> //!
> //! [`LKMM`]: srctree/tools/memory-model/
>
> +pub mod generic;
Hmm, maybe just re-export the stuff? I don't think there's an advantage
to having the generic module be public.
> pub mod ops;
> pub mod ordering;
>
> +pub use generic::Atomic;
> pub use ordering::{Acquire, Full, Relaxed, Release};
> +
> +// SAFETY: `i32` has the same size and alignment with itself, and is round-trip transmutable to
> +// itself.
> +unsafe impl generic::AllowAtomic for i32 {
> + type Repr = i32;
> +}
> +
> +// SAFETY: `i64` has the same size and alignment with itself, and is round-trip transmutable to
> +// itself.
> +unsafe impl generic::AllowAtomic for i64 {
> + type Repr = i64;
> +}
> diff --git a/rust/kernel/sync/atomic/generic.rs b/rust/kernel/sync/atomic/generic.rs
> new file mode 100644
> index 000000000000..b3e07328d857
> --- /dev/null
> +++ b/rust/kernel/sync/atomic/generic.rs
> @@ -0,0 +1,285 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Generic atomic primitives.
> +
> +use super::ops::{AtomicHasBasicOps, AtomicImpl};
> +use super::{ordering, ordering::OrderingType};
> +use crate::build_error;
> +use core::cell::UnsafeCell;
> +
> +/// A memory location which can be safely modified from multiple execution contexts.
> +///
> +/// This has the same size, alignment and bit validity as the underlying type `T`.
Let's also mention that this disables any niche optimizations (due to
the unsafe cell).
> +///
> +/// The atomic operations are implemented in a way that is fully compatible with the [Linux Kernel
> +/// Memory (Consistency) Model][LKMM], hence they should be modeled as the corresponding
> +/// [`LKMM`][LKMM] atomic primitives. With the help of [`Atomic::from_ptr()`] and
> +/// [`Atomic::as_ptr()`], this provides a way to interact with [C-side atomic operations]
> +/// (including those without the `atomic` prefix, e.g. `READ_ONCE()`, `WRITE_ONCE()`,
> +/// `smp_load_acquire()` and `smp_store_release()`).
> +///
> +/// [LKMM]: srctree/tools/memory-model/
> +/// [C-side atomic operations]: srctree/Documentation/atomic_t.txt
Did you check that these links looks good in rustdoc?
> +#[repr(transparent)]
> +pub struct Atomic<T: AllowAtomic>(UnsafeCell<T>);
> +
> +// SAFETY: `Atomic<T>` is safe to share among execution contexts because all accesses are atomic.
> +unsafe impl<T: AllowAtomic> Sync for Atomic<T> {}
> +
> +/// Types that support basic atomic operations.
> +///
> +/// # Round-trip transmutability
> +///
> +/// `T` is round-trip transmutable to `U` if and only if both of these properties hold:
> +///
> +/// - Any valid bit pattern for `T` is also a valid bit pattern for `U`.
> +/// - Transmuting (e.g. using [`transmute()`]) a value of type `T` to `U` and then to `T` again
> +/// yields a value that is in all aspects equivalent to the original value.
> +///
> +/// # Safety
> +///
> +/// - [`Self`] must have the same size and alignment as [`Self::Repr`].
> +/// - [`Self`] must be [round-trip transmutable] to [`Self::Repr`].
> +///
> +/// Note that this is more relaxed than requiring the bi-directional transmutability (i.e.
> +/// [`transmute()`] is always sound between `U` to `T`) because of the support for atomic variables
s/ to / and /
> +/// over unit-only enums, see [Examples].
> +///
> +/// # Limitations
> +///
> +/// Because C primitives are used to implement the atomic operations, and a C function requires a
> +/// valid object of a type to operate on (i.e. no `MaybeUninit<_>`), hence at the Rust <-> C
> +/// surface, only types with no uninitialized bits can be passed. As a result, types like `(u8,
s/no uninitialized/initialized/
> +/// u16)` (a tuple with a `MaybeUninit` hole in it) are currently not supported. Note that
s/a tuple with a `MaybeUninit` hole in it/padding bytes are uninitialized/
> +/// technically these types can be supported if some APIs are removed for them and the inner
> +/// implementation is tweaked, but the justification of support such a type is not strong enough at
> +/// the moment. This should be resolved if there is an implementation for `MaybeUninit<i32>` as
> +/// `AtomicImpl`.
> +///
> +/// # Examples
> +///
> +/// A unit-only enum that implements [`AllowAtomic`]:
> +///
> +/// ```
> +/// use kernel::sync::atomic::{generic::AllowAtomic, Atomic, Relaxed};
> +///
> +/// #[derive(Clone, Copy, PartialEq, Eq)]
> +/// #[repr(i32)]
> +/// enum State {
> +/// Uninit = 0,
> +/// Working = 1,
> +/// Done = 2,
> +/// };
> +///
> +/// // SAFETY: `State` and `i32` has the same size and alignment, and it's round-trip
> +/// // transmutable to `i32`.
> +/// unsafe impl AllowAtomic for State {
> +/// type Repr = i32;
> +/// }
> +///
> +/// let s = Atomic::new(State::Uninit);
> +///
> +/// assert_eq!(State::Uninit, s.load(Relaxed));
> +/// ```
> +/// [`transmute()`]: core::mem::transmute
> +/// [round-trip transmutable]: AllowAtomic#round-trip-transmutability
> +/// [Examples]: AllowAtomic#examples
> +pub unsafe trait AllowAtomic: Sized + Send + Copy {
> + /// The backing atomic implementation type.
> + type Repr: AtomicImpl;
> +}
> +
> +#[inline(always)]
> +const fn into_repr<T: AllowAtomic>(v: T) -> T::Repr {
> + // SAFETY: Per the safety requirement of `AllowAtomic`, the transmute operation is sound.
Please explain the concrete parts of the safety requirements that you
are using here (ie round-trip-transmutability).
> + unsafe { core::mem::transmute_copy(&v) }
> +}
> +
> +/// # Safety
> +///
> +/// `r` must be a valid bit pattern of `T`.
> +#[inline(always)]
> +const unsafe fn from_repr<T: AllowAtomic>(r: T::Repr) -> T {
> + // SAFETY: Per the safety requirement of the function, the transmute operation is sound.
> + unsafe { core::mem::transmute_copy(&r) }
> +}
> +
> +impl<T: AllowAtomic> Atomic<T> {
> + /// Creates a new atomic `T`.
> + pub const fn new(v: T) -> Self {
> + Self(UnsafeCell::new(v))
> + }
> +
> + /// Creates a reference to an atomic `T` from a pointer of `T`.
> + ///
> + /// # Safety
> + ///
> + /// - `ptr` is aligned to `align_of::<T>()`.
> + /// - `ptr` is valid for reads and writes for `'a`.
> + /// - For the duration of `'a`, other accesses to `*ptr` must not cause data races (defined
> + /// by [`LKMM`]) against atomic operations on the returned reference. Note that if all other
> + /// accesses are atomic, then this safety requirement is trivially fulfilled.
> + ///
> + /// [`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:
> + ///
> + /// ```
> + /// # 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 valid, and `.a` is in bounds.
> + /// let foo_a_ptr = unsafe { &raw mut (*foo_ptr).a };
> + ///
> + /// // a = READ_ONCE(foo_ptr->a);
> + /// //
> + /// // SAFETY: `foo_a_ptr` is valid for read, and all other 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 valid for writes, and all other 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.
This sentence should be above the `Safety` section.
> + 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 `T`.
> + ///
> + /// Note that use of the return pointer must not cause data races defined by [`LKMM`].
> + ///
> + /// # Guarantees
> + ///
> + /// The returned pointer is properly aligned (i.e. aligned to [`align_of::<T>()`])
You really only need this guarantee? Not validity etc?
> + ///
> + /// [`LKMM`]: srctree/tools/memory-model
> + /// [`align_of::<T>()`]: core::mem::align_of
> + pub const fn as_ptr(&self) -> *mut T {
> + // GUARANTEE: `self.0` has the same alignment of `T`.
> + self.0.get()
> + }
> +
> + /// Returns a mutable reference to the underlying atomic `T`.
> + ///
> + /// This is safe because the mutable reference of the atomic `T` guarantees the exclusive
s/the exclusive/exclusive/
---
Cheers,
Benno
> + /// access.
> + pub fn get_mut(&mut self) -> &mut T {
> + // SAFETY: `self.as_ptr()` is a valid pointer to `T`. `&mut self` guarantees the exclusive
> + // access, so it's safe to reborrow mutably.
> + unsafe { &mut *self.as_ptr() }
> + }
> +}
Powered by blists - more mailing lists