Lines Matching +full:reference +full:- +full:sync
1 // SPDX-License-Identifier: GPL-2.0
13 //! - A normal write from C side is treated as an atomic write if
15 //! - Mixed-size atomic accesses don't cause data races.
17 //! [`LKMM`]: srctree/tools/memory-model/
40 /// [`Atomic::as_ptr()`], this provides a way to interact with [C-side atomic operations]
49 /// [LKMM]: srctree/tools/memory-model/
50 /// [C-side atomic operations]: srctree/Documentation/atomic_t.txt
59 unsafe impl<T: AtomicType> Sync for Atomic<T> {}
63 /// # Round-trip transmutability
65 /// `T` is round-trip transmutable to `U` if and only if both of these properties hold:
67 /// - Any valid bit pattern for `T` is also a valid bit pattern for `U`.
68 /// - Transmuting (e.g. using [`transmute()`]) a value of type `T` to `U` and then to `T` again
73 /// - [`Self`] must have the same size and alignment as [`Self::Repr`].
74 /// - [`Self`] must be [round-trip transmutable] to [`Self::Repr`].
75 /// - [`Self`] must be safe to transfer between execution contexts, if it's [`Send`], this is
81 /// Note that this is more relaxed than requiring the bi-directional transmutability (i.e.
83 /// variables over unit-only enums, see [Examples].
88 /// valid object of a type to operate on (i.e. no `MaybeUninit<_>`), hence at the Rust <-> C
94 /// A unit-only enum that implements [`AtomicType`]:
97 /// use kernel::sync::atomic::{AtomicType, Atomic, Relaxed};
107 /// // SAFETY: `State` and `i32` has the same size and alignment, and it's round-trip
118 /// [round-trip transmutable]: AtomicType#round-trip-transmutability
136 fn rhs_into_delta(rhs: Rhs) -> <Self::Repr as AtomicImpl>::Delta;
140 const fn into_repr<T: AtomicType>(v: T) -> T::Repr {
141 // SAFETY: Per the safety requirement of `AtomicType`, `T` is round-trip transmutable to
150 const unsafe fn from_repr<T: AtomicType>(r: T::Repr) -> T {
157 pub const fn new(v: T) -> Self {
162 /// Creates a reference to an atomic `T` from a pointer of `T`.
169 /// - `ptr` is aligned to `align_of::<T>()`.
170 /// - `ptr` is valid for reads and writes for `'a`.
171 /// - For the duration of `'a`, other accesses to `*ptr` must not cause data races (defined
172 /// by [`LKMM`]) against atomic operations on the returned reference. Note that if all other
175 /// [`LKMM`]: srctree/tools/memory-model
185 /// use kernel::sync::atomic::{Atomic, Relaxed, Release};
204 /// // a = READ_ONCE(foo_ptr->a);
211 /// // smp_store_release(&foo_ptr->a, 2);
217 pub unsafe fn from_ptr<'a>(ptr: *mut T) -> &'a Self {
233 /// [`LKMM`]: srctree/tools/memory-model
235 pub const fn as_ptr(&self) -> *mut T {
242 /// Returns a mutable reference to the underlying atomic `T`.
244 /// This is safe because the mutable reference of the atomic `T` guarantees exclusive access.
249 /// use kernel::sync::atomic::{Atomic, Relaxed};
256 pub fn get_mut(&mut self) -> &mut T {
260 // SAFETY: The pointer is valid per the CAST comment above, and the mutable reference
275 /// use kernel::sync::atomic::{Atomic, Relaxed};
287 pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, _: Ordering) -> T {
305 /// use kernel::sync::atomic::{Atomic, Relaxed};
333 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
349 /// use kernel::sync::atomic::{Atomic, Acquire, Relaxed};
358 pub fn xchg<Ordering: ordering::Ordering>(&self, v: T, _: Ordering) -> T {
393 /// use kernel::sync::atomic::{Atomic, Full, Relaxed};
405 /// // Uses the old value if failed, probably re-try cmpxchg.
434 ) -> Result<T, T> {
476 fn try_cmpxchg<Ordering: ordering::Ordering>(&self, old: &mut T, new: T, _: Ordering) -> bool {
515 /// use kernel::sync::atomic::{Atomic, Relaxed};
545 /// use kernel::sync::atomic::{Atomic, Acquire, Full, Relaxed};
558 pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering) -> T
587 /// use kernel::sync::atomic::{Atomic, Acquire, Full, Relaxed};
600 pub fn fetch_sub<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering) -> T
646 const fn new(b: bool) -> Self {
656 // SAFETY: `Flag` and `Repr` have the same size and alignment, and `Flag` is round-trip
665 /// An atomic flag type intended to be backed by performance-optimal integer type.
670 /// [`AtomicFlag`] is generally preferable to [`Atomic<bool>`] when you need read-modify-write
672 /// not save memory due to padding. On some architectures that do not support byte-sized atomic
680 /// use kernel::sync::atomic::{AtomicFlag, Relaxed};
692 pub const fn new(b: bool) -> Self {
696 /// Returns a mutable reference to the underlying flag as a [`bool`].
698 /// This is safe because the mutable reference of the atomic flag guarantees exclusive access.
703 /// use kernel::sync::atomic::{AtomicFlag, Relaxed};
711 pub fn get_mut(&mut self) -> &mut bool {
717 pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
729 pub fn xchg<Ordering: ordering::Ordering>(&self, new: bool, o: Ordering) -> bool {
740 ) -> Result<bool, bool> {
750 /// This function provides a short-cut of `Atomic::from_ptr().load(..)`, and can be used to work
753 /// - `atomic_load(.., Relaxed)` maps to `READ_ONCE()` when used for inter-thread communication.
754 /// - `atomic_load(.., Acquire)` maps to `smp_load_acquire()`.
758 /// - `ptr` is a valid pointer to `T` and aligned to `align_of::<T>()`.
759 /// - If there is a concurrent store from kernel (C or Rust), it has to be atomic.
765 ) -> T
777 /// This function provides a short-cut of `Atomic::from_ptr().load(..)`, and can be used to work
780 /// - `atomic_store(.., Relaxed)` maps to `WRITE_ONCE()` when used for inter-thread communication.
781 /// - `atomic_load(.., Release)` maps to `smp_store_release()`.
785 /// - `ptr` is a valid pointer to `T` and aligned to `align_of::<T>()`.
786 /// - If there is a concurrent access from kernel (C or Rust), it has to be atomic.
804 /// This function provides a short-cut of `Atomic::from_ptr().xchg(..)`, and can be used to work
809 /// - `ptr` is a valid pointer to `T` and aligned to `align_of::<T>()`.
810 /// - If there is a concurrent access from kernel (C or Rust), it has to be atomic.
816 ) -> T
828 /// This function provides a short-cut of `Atomic::from_ptr().cmpxchg(..)`, and can be used to work
833 /// - `ptr` is a valid pointer to `T` and aligned to `align_of::<T>()`.
834 /// - If there is a concurrent access from kernel (C or Rust), it has to be atomic.
842 ) -> Result<T, T>