Re: [PATCH 03/14] rust: sync: atomic: Add ordering annotation types

Elle Rhumsaa
2025-09-06T04:22:54Z

On Thu, Sep 04, 2025 at 09:41:30PM -0700, Boqun Feng wrote:
> Preparation for atomic primitives. Instead of a suffix like _acquire, a
> method parameter along with the corresponding generic parameter will be
> used to specify the ordering of an atomic operations. For example,
> atomic load() can be defined as:
>
> impl<T: ...> Atomic<T> {
> pub fn load<O: AcquireOrRelaxed>(&self, _o: O) -> T { ... }
> }
>
> and acquire users would do:
>
> let r = x.load(Acquire);
>
> relaxed users:
>
> let r = x.load(Relaxed);
>
> doing the following:
>
> let r = x.load(Release);
>
> will cause a compiler error.
>
> Compared to suffixes, it's easier to tell what ordering variants an
> operation has, and it also make it easier to unify the implementation of
> all ordering variants in one method via generic. The `TYPE` associate
> const is for generic function to pick up the particular implementation
> specified by an ordering annotation.
>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> Reviewed-by: Benno Lossin <lossin@kernel.org>
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> Link: https://lore.kernel.org/all/20250719030827.61357-4-boqun.feng@gmail.com/
> ---
> rust/kernel/sync/atomic.rs | 2 +
> rust/kernel/sync/atomic/ordering.rs | 104 ++++++++++++++++++++++++++++
> 2 files changed, 106 insertions(+)
> create mode 100644 rust/kernel/sync/atomic/ordering.rs
>
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index b9f2f4780073..2302e6d51fe2 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -18,5 +18,7 @@
>
> #[allow(dead_code, unreachable_pub)]
> mod internal;
> +pub mod ordering;
>
> pub use internal::AtomicImpl;
> +pub use ordering::{Acquire, Full, Relaxed, Release};
> diff --git a/rust/kernel/sync/atomic/ordering.rs b/rust/kernel/sync/atomic/ordering.rs
> new file mode 100644
> index 000000000000..3f103aa8db99
> --- /dev/null
> +++ b/rust/kernel/sync/atomic/ordering.rs
> @@ -0,0 +1,104 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Memory orderings.
> +//!
> +//! The semantics of these orderings follows the [`LKMM`] definitions and rules.
> +//!
> +//! - [`Acquire`] provides ordering between the load part of the annotated operation and all the
> +//! following memory accesses, and if there is a store part, the store part has the [`Relaxed`]
> +//! ordering.
> +//! - [`Release`] provides ordering between all the preceding memory accesses and the store part of
> +//! the annotated operation, and if there is a load part, the load part has the [`Relaxed`]
> +//! ordering.
> +//! - [`Full`] means "fully-ordered", that is:
> +//! - It provides ordering between all the preceding memory accesses and the annotated operation.
> +//! - It provides ordering between the annotated operation and all the following memory accesses.
> +//! - It provides ordering between all the preceding memory accesses and all the following memory
> +//! accesses.
> +//! - All the orderings are the same strength as a full memory barrier (i.e. `smp_mb()`).
> +//! - [`Relaxed`] provides no ordering except the dependency orderings. Dependency orderings are
> +//! described in "DEPENDENCY RELATIONS" in [`LKMM`]'s [`explanation`].
> +//!
> +//! [`LKMM`]: srctree/tools/memory-model/
> +//! [`explanation`]: srctree/tools/memory-model/Documentation/explanation.txt
> +
> +/// The annotation type for relaxed memory ordering, for the description of relaxed memory
> +/// ordering, see [module-level documentation].
> +///
> +/// [module-level documentation]: crate::sync::atomic::ordering
> +pub struct Relaxed;
> +
> +/// The annotation type for acquire memory ordering, for the description of acquire memory
> +/// ordering, see [module-level documentation].
> +///
> +/// [module-level documentation]: crate::sync::atomic::ordering
> +pub struct Acquire;
> +
> +/// The annotation type for release memory ordering, for the description of release memory
> +/// ordering, see [module-level documentation].
> +///
> +/// [module-level documentation]: crate::sync::atomic::ordering
> +pub struct Release;
> +
> +/// The annotation type for fully-ordered memory ordering, for the description fully-ordered memory
> +/// ordering, see [module-level documentation].
> +///
> +/// [module-level documentation]: crate::sync::atomic::ordering
> +pub struct Full;
> +
> +/// Describes the exact memory ordering.
> +#[doc(hidden)]
> +pub enum OrderingType {
> + /// Relaxed ordering.
> + Relaxed,
> + /// Acquire ordering.
> + Acquire,
> + /// Release ordering.
> + Release,
> + /// Fully-ordered.
> + Full,
> +}
> +
> +mod internal {
> + /// Sealed trait, can be only implemented inside atomic mod.
> + pub trait Sealed {}
> +
> + impl Sealed for super::Relaxed {}
> + impl Sealed for super::Acquire {}
> + impl Sealed for super::Release {}
> + impl Sealed for super::Full {}
> +}
> +
> +/// The trait bound for annotating operations that support any ordering.
> +pub trait Ordering: internal::Sealed {
> + /// Describes the exact memory ordering.
> + const TYPE: OrderingType;
> +}
> +
> +impl Ordering for Relaxed {
> + const TYPE: OrderingType = OrderingType::Relaxed;
> +}
> +
> +impl Ordering for Acquire {
> + const TYPE: OrderingType = OrderingType::Acquire;
> +}
> +
> +impl Ordering for Release {
> + const TYPE: OrderingType = OrderingType::Release;
> +}
> +
> +impl Ordering for Full {
> + const TYPE: OrderingType = OrderingType::Full;
> +}
> +
> +/// The trait bound for operations that only support acquire or relaxed ordering.
> +pub trait AcquireOrRelaxed: Ordering {}
> +
> +impl AcquireOrRelaxed for Acquire {}
> +impl AcquireOrRelaxed for Relaxed {}
> +
> +/// The trait bound for operations that only support release or relaxed ordering.
> +pub trait ReleaseOrRelaxed: Ordering {}
> +
> +impl ReleaseOrRelaxed for Release {}
> +impl ReleaseOrRelaxed for Relaxed {}
> --
> 2.51.0
>
>

Reviewed-by: Elle Rhumsaa <elle@weathered-steel.dev>