From: Alice Ryhl <aliceryhl@google.com>
To: Boqun Feng <boqun.feng@gmail.com>
Cc: rust-for-linux@vger.kernel.org, rcu@vger.kernel.org,
linux-kernel@vger.kernel.org, linux-arch@vger.kernel.org,
llvm@lists.linux.dev, lkmm@lists.linux.dev,
"Miguel Ojeda" <ojeda@kernel.org>,
"Alex Gaynor" <alex.gaynor@gmail.com>,
"Wedson Almeida Filho" <wedsonaf@gmail.com>,
"Gary Guo" <gary@garyguo.net>,
"Björn Roy Baron" <bjorn3_gh@protonmail.com>,
"Benno Lossin" <benno.lossin@proton.me>,
"Andreas Hindborg" <a.hindborg@samsung.com>,
"Alan Stern" <stern@rowland.harvard.edu>,
"Andrea Parri" <parri.andrea@gmail.com>,
"Will Deacon" <will@kernel.org>,
"Peter Zijlstra" <peterz@infradead.org>,
"Nicholas Piggin" <npiggin@gmail.com>,
"David Howells" <dhowells@redhat.com>,
"Jade Alglave" <j.alglave@ucl.ac.uk>,
"Luc Maranget" <luc.maranget@inria.fr>,
"Paul E. McKenney" <paulmck@kernel.org>,
"Akira Yokosawa" <akiyks@gmail.com>,
"Daniel Lustig" <dlustig@nvidia.com>,
"Joel Fernandes" <joel@joelfernandes.org>,
"Nathan Chancellor" <nathan@kernel.org>,
"Nick Desaulniers" <ndesaulniers@google.com>,
kent.overstreet@gmail.com,
"Greg Kroah-Hartman" <gregkh@linuxfoundation.org>,
elver@google.com, "Mark Rutland" <mark.rutland@arm.com>,
"Thomas Gleixner" <tglx@linutronix.de>,
"Ingo Molnar" <mingo@redhat.com>,
"Borislav Petkov" <bp@alien8.de>,
"Dave Hansen" <dave.hansen@linux.intel.com>,
x86@kernel.org, "H. Peter Anvin" <hpa@zytor.com>,
"Catalin Marinas" <catalin.marinas@arm.com>,
torvalds@linux-foundation.org,
linux-arm-kernel@lists.infradead.org,
linux-fsdevel@vger.kernel.org, "Trevor Gross" <tmgross@umich.edu>,
dakr@redhat.com, "Frederic Weisbecker" <frederic@kernel.org>,
"Neeraj Upadhyay" <neeraj.upadhyay@kernel.org>,
"Josh Triplett" <josh@joshtriplett.org>,
"Uladzislau Rezki" <urezki@gmail.com>,
"Steven Rostedt" <rostedt@goodmis.org>,
"Mathieu Desnoyers" <mathieu.desnoyers@efficios.com>,
"Lai Jiangshan" <jiangshanlai@gmail.com>,
Zqiang <qiang.zhang1211@gmail.com>,
"Paul Walmsley" <paul.walmsley@sifive.com>,
"Palmer Dabbelt" <palmer@dabbelt.com>,
"Albert Ou" <aou@eecs.berkeley.edu>,
linux-riscv@lists.infradead.org
Subject: Re: [RFC v2 04/13] rust: sync: atomic: Add generic atomics
Date: Thu, 12 Dec 2024 11:57:07 +0100 [thread overview]
Message-ID: <CAH5fLgjhQouU=kqVx7LET2yeWt6sKt-VO5PR5SnQ8doaG4ihuQ@mail.gmail.com> (raw)
In-Reply-To: <20241101060237.1185533-5-boqun.feng@gmail.com>
On Fri, Nov 1, 2024 at 7:03 AM Boqun Feng <boqun.feng@gmail.com> 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. The trait
> `AllowAtomic` should be only ipmlemented inside atomic mod until the
> generic atomic framework is mature enough (unless the ipmlementer is a
> `#[repr(transparent)]` new type).
>
> `AtomicIpml` types are automatically `AllowAtomic`, and so far only
> basic operations load() and store() are introduced.
The ipml typo continues in this patch.
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> ---
> rust/kernel/sync/atomic.rs | 2 +
> rust/kernel/sync/atomic/generic.rs | 253 +++++++++++++++++++++++++++++
> 2 files changed, 255 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 be2e8583595f..b791abc59b61 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -16,7 +16,9 @@
> //!
> //! [`LKMM`]: srctree/tools/memory-mode/
>
> +pub mod generic;
> pub mod ops;
> pub mod ordering;
>
> +pub use generic::Atomic;
> pub use ordering::{Acquire, Full, Relaxed, Release};
> diff --git a/rust/kernel/sync/atomic/generic.rs b/rust/kernel/sync/atomic/generic.rs
> new file mode 100644
> index 000000000000..204da38e2691
> --- /dev/null
> +++ b/rust/kernel/sync/atomic/generic.rs
> @@ -0,0 +1,253 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Generic atomic primitives.
> +
> +use super::ops::*;
> +use super::ordering::*;
> +use crate::types::Opaque;
> +
> +/// A generic atomic variable.
> +///
> +/// `T` must impl [`AllowAtomic`], that is, an [`AtomicImpl`] has to be chosen.
> +///
> +/// # Invariants
> +///
> +/// Doing an atomic operation while holding a reference of [`Self`] won't cause a data race, this
> +/// is guaranteed by the safety requirement of [`Self::from_ptr`] and the extra safety requirement
> +/// of the usage on pointers returned by [`Self::as_ptr`].
> +#[repr(transparent)]
> +pub struct Atomic<T: AllowAtomic>(Opaque<T>);
> +
> +// SAFETY: `Atomic<T>` is safe to share among execution contexts because all accesses are atomic.
> +unsafe impl<T: AllowAtomic> Sync for Atomic<T> {}
Surely it should also be Send?
> +/// Atomics that support basic atomic operations.
> +///
> +/// TODO: Unless the `impl` is a `#[repr(transparet)]` new type of an existing [`AllowAtomic`], the
> +/// impl block should be only done in atomic mod. And currently only basic integer types can
> +/// implement this trait in atomic mod.
What's up with this TODO? Can't you just write an appropriate safety
requirement?
> +/// # Safety
> +///
> +/// [`Self`] must have the same size and alignment as [`Self::Repr`].
> +pub unsafe trait AllowAtomic: Sized + Send + Copy {
> + /// The backing atomic implementation type.
> + type Repr: AtomicImpl;
> +
> + /// Converts into a [`Self::Repr`].
> + fn into_repr(self) -> Self::Repr;
> +
> + /// Converts from a [`Self::Repr`].
> + fn from_repr(repr: Self::Repr) -> Self;
What do you need these methods for?
> +}
> +
> +// SAFETY: `T::Repr` is `Self` (i.e. `T`), so they have the same size and alignment.
> +unsafe impl<T: AtomicImpl> AllowAtomic for T {
> + type Repr = Self;
> +
> + fn into_repr(self) -> Self::Repr {
> + self
> + }
> +
> + fn from_repr(repr: Self::Repr) -> Self {
> + repr
> + }
> +}
> +
> +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.
> + ///
> + /// [`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.
> + /// let foo_a_ptr = unsafe { core::ptr::addr_of_mut!((*foo_ptr).a) };
> + ///
> + /// // 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);
> + /// ```
> + #[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`,
> + // 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));
> + /// ```
> + ///
> + #[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`,
> + // 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.
> + unsafe {
> + if Ordering::IS_RELAXED {
> + T::Repr::atomic_set(a, v)
> + } else {
> + T::Repr::atomic_set_release(a, v)
> + }
> + };
> + }
> +}
> --
> 2.45.2
>
next prev parent reply other threads:[~2024-12-12 10:57 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-11-01 6:02 [RFC v2 00/13] LKMM *generic* atomics in Rust Boqun Feng
2024-11-01 6:02 ` [RFC v2 01/13] rust: Introduce atomic API helpers Boqun Feng
2024-11-01 6:02 ` [RFC v2 02/13] rust: sync: Add basic atomic operation mapping framework Boqun Feng
2024-12-12 10:51 ` Alice Ryhl
2024-12-12 17:07 ` Boqun Feng
2024-12-13 14:37 ` Alice Ryhl
2024-12-13 20:28 ` Boqun Feng
2024-11-01 6:02 ` [RFC v2 03/13] rust: sync: atomic: Add ordering annotation types Boqun Feng
2024-11-01 6:02 ` [RFC v2 04/13] rust: sync: atomic: Add generic atomics Boqun Feng
2024-12-12 10:57 ` Alice Ryhl [this message]
2024-12-12 17:34 ` Boqun Feng
2024-12-13 14:32 ` Alice Ryhl
2024-12-13 20:13 ` Boqun Feng
2024-11-01 6:02 ` [RFC v2 05/13] rust: sync: atomic: Add atomic {cmp,}xchg operations Boqun Feng
2024-11-01 6:02 ` [RFC v2 06/13] rust: sync: atomic: Add the framework of arithmetic operations Boqun Feng
2024-11-01 6:02 ` [RFC v2 07/13] rust: sync: atomic: Add Atomic<u{32,64}> Boqun Feng
2024-11-01 6:02 ` [RFC v2 08/13] rust: sync: atomic: Add Atomic<{usize,isize}> Boqun Feng
2024-11-01 6:02 ` [RFC v2 09/13] rust: sync: atomic: Add Atomic<*mut T> Boqun Feng
2024-11-01 6:02 ` [RFC v2 10/13] rust: sync: atomic: Add arithmetic ops for " Boqun Feng
2024-11-01 6:02 ` [RFC v2 11/13] rust: sync: Add memory barriers Boqun Feng
2024-11-01 6:55 ` David Gow
2024-11-01 7:04 ` Boqun Feng
2024-11-01 7:01 ` [RFC v2.1 " Boqun Feng
2024-11-01 6:02 ` [RFC v2 12/13] rust: add rcu abstraction Boqun Feng
2024-11-01 6:02 ` [RFC v2 13/13] rust: sync: rcu: Add RCU protected pointer Boqun Feng
2024-11-01 14:30 ` [RFC v2 00/13] LKMM *generic* atomics in Rust Miguel Ojeda
2024-11-02 7:35 ` David Gow
2025-04-21 16:27 ` Boqun Feng
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAH5fLgjhQouU=kqVx7LET2yeWt6sKt-VO5PR5SnQ8doaG4ihuQ@mail.gmail.com' \
--to=aliceryhl@google.com \
--cc=a.hindborg@samsung.com \
--cc=akiyks@gmail.com \
--cc=alex.gaynor@gmail.com \
--cc=aou@eecs.berkeley.edu \
--cc=benno.lossin@proton.me \
--cc=bjorn3_gh@protonmail.com \
--cc=boqun.feng@gmail.com \
--cc=bp@alien8.de \
--cc=catalin.marinas@arm.com \
--cc=dakr@redhat.com \
--cc=dave.hansen@linux.intel.com \
--cc=dhowells@redhat.com \
--cc=dlustig@nvidia.com \
--cc=elver@google.com \
--cc=frederic@kernel.org \
--cc=gary@garyguo.net \
--cc=gregkh@linuxfoundation.org \
--cc=hpa@zytor.com \
--cc=j.alglave@ucl.ac.uk \
--cc=jiangshanlai@gmail.com \
--cc=joel@joelfernandes.org \
--cc=josh@joshtriplett.org \
--cc=kent.overstreet@gmail.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-riscv@lists.infradead.org \
--cc=lkmm@lists.linux.dev \
--cc=llvm@lists.linux.dev \
--cc=luc.maranget@inria.fr \
--cc=mark.rutland@arm.com \
--cc=mathieu.desnoyers@efficios.com \
--cc=mingo@redhat.com \
--cc=nathan@kernel.org \
--cc=ndesaulniers@google.com \
--cc=neeraj.upadhyay@kernel.org \
--cc=npiggin@gmail.com \
--cc=ojeda@kernel.org \
--cc=palmer@dabbelt.com \
--cc=parri.andrea@gmail.com \
--cc=paul.walmsley@sifive.com \
--cc=paulmck@kernel.org \
--cc=peterz@infradead.org \
--cc=qiang.zhang1211@gmail.com \
--cc=rcu@vger.kernel.org \
--cc=rostedt@goodmis.org \
--cc=rust-for-linux@vger.kernel.org \
--cc=stern@rowland.harvard.edu \
--cc=tglx@linutronix.de \
--cc=tmgross@umich.edu \
--cc=torvalds@linux-foundation.org \
--cc=urezki@gmail.com \
--cc=wedsonaf@gmail.com \
--cc=will@kernel.org \
--cc=x86@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).