kernel/sync/atomic/
ordering.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Memory orderings.
4//!
5//! The semantics of these orderings follows the [`LKMM`] definitions and rules.
6//!
7//! - [`Acquire`] provides ordering between the load part of the annotated operation and all the
8//!   following memory accesses, and if there is a store part, the store part has the [`Relaxed`]
9//!   ordering.
10//! - [`Release`] provides ordering between all the preceding memory accesses and the store part of
11//!   the annotated operation, and if there is a load part, the load part has the [`Relaxed`]
12//!   ordering.
13//! - [`Full`] means "fully-ordered", that is:
14//!   - It provides ordering between all the preceding memory accesses and the annotated operation.
15//!   - It provides ordering between the annotated operation and all the following memory accesses.
16//!   - It provides ordering between all the preceding memory accesses and all the following memory
17//!     accesses.
18//!   - All the orderings are the same strength as a full memory barrier (i.e. `smp_mb()`).
19//! - [`Relaxed`] provides no ordering except the dependency orderings. Dependency orderings are
20//!   described in "DEPENDENCY RELATIONS" in [`LKMM`]'s [`explanation`].
21//!
22//! [`LKMM`]: srctree/tools/memory-model/
23//! [`explanation`]: srctree/tools/memory-model/Documentation/explanation.txt
24
25/// The annotation type for relaxed memory ordering, for the description of relaxed memory
26/// ordering, see [module-level documentation].
27///
28/// [module-level documentation]: crate::sync::atomic::ordering
29pub struct Relaxed;
30
31/// The annotation type for acquire memory ordering, for the description of acquire memory
32/// ordering, see [module-level documentation].
33///
34/// [module-level documentation]: crate::sync::atomic::ordering
35pub struct Acquire;
36
37/// The annotation type for release memory ordering, for the description of release memory
38/// ordering, see [module-level documentation].
39///
40/// [module-level documentation]: crate::sync::atomic::ordering
41pub struct Release;
42
43/// The annotation type for fully-ordered memory ordering, for the description fully-ordered memory
44/// ordering, see [module-level documentation].
45///
46/// [module-level documentation]: crate::sync::atomic::ordering
47pub struct Full;
48
49/// Describes the exact memory ordering.
50#[doc(hidden)]
51pub enum OrderingType {
52    /// Relaxed ordering.
53    Relaxed,
54    /// Acquire ordering.
55    Acquire,
56    /// Release ordering.
57    Release,
58    /// Fully-ordered.
59    Full,
60}
61
62mod internal {
63    /// Sealed trait, can be only implemented inside atomic mod.
64    pub trait Sealed {}
65
66    impl Sealed for super::Relaxed {}
67    impl Sealed for super::Acquire {}
68    impl Sealed for super::Release {}
69    impl Sealed for super::Full {}
70}
71
72/// The trait bound for annotating operations that support any ordering.
73pub trait Ordering: internal::Sealed {
74    /// Describes the exact memory ordering.
75    const TYPE: OrderingType;
76}
77
78impl Ordering for Relaxed {
79    const TYPE: OrderingType = OrderingType::Relaxed;
80}
81
82impl Ordering for Acquire {
83    const TYPE: OrderingType = OrderingType::Acquire;
84}
85
86impl Ordering for Release {
87    const TYPE: OrderingType = OrderingType::Release;
88}
89
90impl Ordering for Full {
91    const TYPE: OrderingType = OrderingType::Full;
92}
93
94/// The trait bound for operations that only support acquire or relaxed ordering.
95pub trait AcquireOrRelaxed: Ordering {}
96
97impl AcquireOrRelaxed for Acquire {}
98impl AcquireOrRelaxed for Relaxed {}
99
100/// The trait bound for operations that only support release or relaxed ordering.
101pub trait ReleaseOrRelaxed: Ordering {}
102
103impl ReleaseOrRelaxed for Release {}
104impl ReleaseOrRelaxed for Relaxed {}
kernel/sync/atomic/ordering.rs

kernel/sync/atomic/
ordering.rs
