linux/rust/kernel/sync/atomic.rs

// SPDX-License-Identifier: GPL-2.0

//! Atomic primitives.
//!
//! These primitives have the same semantics as their C counterparts: and the precise definitions of
//! semantics can be found at [`LKMM`]. Note that Linux Kernel Memory (Consistency) Model is the
//! only model for Rust code in kernel, and Rust's own atomics should be avoided.
//!
//! # Data races
//!
//! [`LKMM`] atomics have different rules regarding data races:
//!
//! - A normal write from C side is treated as an atomic write if
//!   CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC=y.
//! - Mixed-size atomic accesses don't cause data races.
//!
//! [`LKMM`]: srctree/tools/memory-model/

#[allow(dead_code, unreachable_pub)]
mod internal;

pub use internal::AtomicImpl;
rust: sync: Add basic atomic operation mapping framework Preparation for generic atomic implementation. To unify the implementation of a generic method over `i32` and `i64`, the C side atomic methods need to be grouped so that in a generic method, they can be referred as <type>::<method>, otherwise their parameters and return value are different between `i32` and `i64`, which would require using `transmute()` to unify the type into a `T`. Introduce `AtomicImpl` to represent a basic type in Rust that has the direct mapping to an atomic implementation from C. Use a sealed trait to restrict `AtomicImpl` to only support `i32` and `i64` for now. Further, different methods are put into different `*Ops` trait groups, and this is for the future when smaller types like `i8`/`i16` are supported but only with a limited set of API (e.g. only set(), load(), xchg() and cmpxchg(), no add() or sub() etc). While the atomic mod is introduced, documentation is also added for memory models and data races. Also bump my role to the maintainer of ATOMIC INFRASTRUCTURE to reflect my responsibility on the Rust atomic mod. Signed-off-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Benno Lossin <lossin@kernel.org> Reviewed-by: Elle Rhumsaa <elle@weathered-steel.dev> Link: https://lore.kernel.org/all/20250719030827.61357-3-boqun.feng@gmail.com/ 2025-09-04 21:41:29 -07:00			`// SPDX-License-Identifier: GPL-2.0`

			`//! Atomic primitives.`
			`//!`
			`//! These primitives have the same semantics as their C counterparts: and the precise definitions of`
			//! semantics can be found at [`LKMM`]. Note that Linux Kernel Memory (Consistency) Model is the
			`//! only model for Rust code in kernel, and Rust's own atomics should be avoided.`
			`//!`
			`//! # Data races`
			`//!`
			//! [`LKMM`] atomics have different rules regarding data races:
			`//!`
			`//! - A normal write from C side is treated as an atomic write if`
			`//! CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC=y.`
			`//! - Mixed-size atomic accesses don't cause data races.`
			`//!`
			//! [`LKMM`]: srctree/tools/memory-model/

			`#[allow(dead_code, unreachable_pub)]`
			`mod internal;`

			`pub use internal::AtomicImpl;`