[PATCH v3 0/2] rust: sync: atomic flag helpers

[PATCH v3 0/2] rust: sync: atomic flag helpers

[FUJITA Tomonori]

This series improves the Rust atomic-boolean support.

The first patch adds a Flag enum (Clear/Set) and implements AtomicType
for it, so Atomic<Flag> can be used when RMW operations (xchg/cmpxchg)
are needed and byte-sized RMWs may be inefficient.

The second patch adds AtomicFlag as a thin wrapper around Atomic<Flag>
to provide a simple bool-based load/store/xchg API.

v3:
- Add AtomicFlag struct provding a simple bool API
v2: https://lore.kernel.org/rust-for-linux/20260108125005.2945800-1-fujita.tomonori@gmail.com/
- Update the description
- Add bidirectional From conversions between Flag and bool
- Use intra-doc links
- Fix level header for Examples
- Fix a typo
- Add a newline after the `use`s block in examples
v1: https://lore.kernel.org/rust-for-linux/20260101102718.2073674-1-fujita.tomonori@gmail.com/

FUJITA Tomonori (2):
  rust: sync: atomic: Add i32-backed Flag for atomic booleans
  rust: sync: atomic: Add AtomicFlag bool wrapper for easier use

 rust/kernel/sync/atomic.rs | 102 +++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)


base-commit: 7bd94324bf04ca1161d94fc193adf782b0cfc0a9
-- 
2.43.0

[PATCH v3 1/2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
users can use Atomic<Flag> for boolean flags.

The backing integer type is an implementation detail; it is currently
i32 but may change in the future.

Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
particular, when RMW operations such as xchg()/cmpxchg() may be used
and minimizing memory usage is not the top priority. On some
architectures without byte-sized RMW instructions, Atomic<bool> can be
slower for RMW operations.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
 rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index ca9cab77abf0..473d3c07e234 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
         unsafe { from_repr(ret) }
     }
 }
+
+/// An atomic flag type intended to be backed by a performance-optimal integer type.
+///
+/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
+/// in the future.
+///
+/// [`Atomic<Flag>`] is generally preferable to [`Atomic<bool>`] when you need read-modify-write
+/// (RMW) operations (e.g. [`Atomic::xchg()`]/[`Atomic::cmpxchg()`]) or when [`Atomic<bool>`] does
+/// not save memory due to padding. On some architectures that do not support byte-sized atomic
+/// RMW operations, RMW operations on [`Atomic<bool>`] are slower.
+///
+/// If you only use [`Atomic::load()`]/[`Atomic::store()`], either [`Atomic<bool>`] or
+/// [`Atomic<Flag>`] is fine.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::sync::atomic::{Atomic, Flag, Relaxed};
+///
+/// let flag = Atomic::new(Flag::Clear);
+/// assert_eq!(Flag::Clear, flag.load(Relaxed));
+/// flag.store(Flag::Set, Relaxed);
+/// assert_eq!(Flag::Set, flag.load(Relaxed));
+/// ```
+#[derive(Clone, Copy, PartialEq, Eq)]
+#[repr(i32)]
+pub enum Flag {
+    /// The flag is clear.
+    Clear = 0,
+    /// The flag is set.
+    Set = 1,
+}
+
+// SAFETY: `Flag` and `i32` have the same size and alignment, and it is round-trip
+// transmutable to `i32`.
+unsafe impl AtomicType for Flag {
+    type Repr = i32;
+}
+
+impl From<Flag> for bool {
+    #[inline(always)]
+    fn from(f: Flag) -> Self {
+        f == Flag::Set
+    }
+}
+
+impl From<bool> for Flag {
+    #[inline(always)]
+    fn from(b: bool) -> Self {
+        if b {
+            Flag::Set
+        } else {
+            Flag::Clear
+        }
+    }
+}
-- 
2.43.0

[PATCH v3 2/2] rust: sync: atomic: Add AtomicFlag bool wrapper for easier use

[FUJITA Tomonori]

Provide AtomicFlag as a thin wrapper around Atomic<Flag> so users can
work with a simple bool API for load/store/xchg while keeping ordering
controls.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
 rust/kernel/sync/atomic.rs | 46 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 473d3c07e234..c3039289b989 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -622,3 +622,49 @@ fn from(b: bool) -> Self {
         }
     }
 }
+
+/// A convenience wrapper around [`Atomic<Flag>`] that exposes a [`bool`] API.
+pub struct AtomicFlag(Atomic<Flag>);
+
+impl AtomicFlag {
+    /// Creates a new atomic flag.
+    pub const fn new(b: bool) -> Self {
+        if b {
+            AtomicFlag(Atomic::new(Flag::Set))
+        } else {
+            AtomicFlag(Atomic::new(Flag::Clear))
+        }
+    }
+
+    /// Loads the value from the atomic flag.
+    #[inline(always)]
+    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
+        self.0.load(o).into()
+    }
+
+    /// Stores a value to the atomic flag.
+    #[inline(always)]
+    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
+        self.0.store(b.into(), o)
+    }
+
+    /// Stores a value to the atomic flag and returns the previous value.
+    #[inline(always)]
+    pub fn xchg<Ordering: ordering::Ordering>(&self, b: bool, o: Ordering) -> bool {
+        self.0.xchg(b.into(), o).into()
+    }
+
+    /// Store a value to the atomic flag if the current value is equal to `old`.
+    #[inline(always)]
+    pub fn cmpxchg<Ordering: ordering::Ordering>(
+        &self,
+        old: bool,
+        new: bool,
+        o: Ordering,
+    ) -> Result<bool, bool> {
+        match self.0.cmpxchg(old.into(), new.into(), o) {
+            Ok(v) => Ok(v.into()),
+            Err(v) => Err(v.into()),
+        }
+    }
+}
-- 
2.43.0

Re: [PATCH v3 1/2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[Alice Ryhl]

On Sun, Jan 11, 2026 at 02:05:57PM +0900, FUJITA Tomonori wrote:
> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
> users can use Atomic<Flag> for boolean flags.
> 
> The backing integer type is an implementation detail; it is currently
> i32 but may change in the future.
> 
> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
> particular, when RMW operations such as xchg()/cmpxchg() may be used
> and minimizing memory usage is not the top priority. On some
> architectures without byte-sized RMW instructions, Atomic<bool> can be
> slower for RMW operations.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> ---
>  rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 56 insertions(+)
> 
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index ca9cab77abf0..473d3c07e234 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>          unsafe { from_repr(ret) }
>      }
>  }
> +
> +/// An atomic flag type intended to be backed by a performance-optimal integer type.
> +///
> +/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
> +/// in the future.

How is it, could we make it u8 on some architectures without penalty,
and have it be i32 on others? Or is i32 better always.

Alice

Re: [PATCH v3 2/2] rust: sync: atomic: Add AtomicFlag bool wrapper for easier use

[Gary Guo]

On Sun Jan 11, 2026 at 5:05 AM GMT, FUJITA Tomonori wrote:
> Provide AtomicFlag as a thin wrapper around Atomic<Flag> so users can
> work with a simple bool API for load/store/xchg while keeping ordering
> controls.
>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> ---
>  rust/kernel/sync/atomic.rs | 46 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
>
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index 473d3c07e234..c3039289b989 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -622,3 +622,49 @@ fn from(b: bool) -> Self {
>          }
>      }
>  }
> +
> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a [`bool`] API.
> +pub struct AtomicFlag(Atomic<Flag>);
> +
> +impl AtomicFlag {
> +    /// Creates a new atomic flag.

Need an `#[inline]` here.

> +    pub const fn new(b: bool) -> Self {
> +        if b {
> +            AtomicFlag(Atomic::new(Flag::Set))
> +        } else {
> +            AtomicFlag(Atomic::new(Flag::Clear))
> +        }
> +    }

Would it make sense to have an inherent method on `Flag`?

    impl Flag {
        #[inline]
        pub const fn new(b: bool) -> Self { .. }
    }

Best,
Gary

> +
> +    /// Loads the value from the atomic flag.
> +    #[inline(always)]
> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
> +        self.0.load(o).into()
> +    }
> +
> +    /// Stores a value to the atomic flag.
> +    #[inline(always)]
> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
> +        self.0.store(b.into(), o)
> +    }
> +
> +    /// Stores a value to the atomic flag and returns the previous value.
> +    #[inline(always)]
> +    pub fn xchg<Ordering: ordering::Ordering>(&self, b: bool, o: Ordering) -> bool {
> +        self.0.xchg(b.into(), o).into()
> +    }
> +
> +    /// Store a value to the atomic flag if the current value is equal to `old`.
> +    #[inline(always)]
> +    pub fn cmpxchg<Ordering: ordering::Ordering>(
> +        &self,
> +        old: bool,
> +        new: bool,
> +        o: Ordering,
> +    ) -> Result<bool, bool> {
> +        match self.0.cmpxchg(old.into(), new.into(), o) {
> +            Ok(v) => Ok(v.into()),
> +            Err(v) => Err(v.into()),
> +        }
> +    }
> +}

Re: [PATCH v3 1/2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Mon, 12 Jan 2026 09:18:32 +0000
Alice Ryhl <aliceryhl@google.com> wrote:

> On Sun, Jan 11, 2026 at 02:05:57PM +0900, FUJITA Tomonori wrote:
>> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>> users can use Atomic<Flag> for boolean flags.
>> 
>> The backing integer type is an implementation detail; it is currently
>> i32 but may change in the future.
>> 
>> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>> particular, when RMW operations such as xchg()/cmpxchg() may be used
>> and minimizing memory usage is not the top priority. On some
>> architectures without byte-sized RMW instructions, Atomic<bool> can be
>> slower for RMW operations.
>> 
>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>> ---
>>  rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 56 insertions(+)
>> 
>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> index ca9cab77abf0..473d3c07e234 100644
>> --- a/rust/kernel/sync/atomic.rs
>> +++ b/rust/kernel/sync/atomic.rs
>> @@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>>          unsafe { from_repr(ret) }
>>      }
>>  }
>> +
>> +/// An atomic flag type intended to be backed by a performance-optimal integer type.
>> +///
>> +/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
>> +/// in the future.
> 
> How is it, could we make it u8 on some architectures without penalty,
> and have it be i32 on others? Or is i32 better always.

Does the following look reasonable?

#[derive(Clone, Copy, PartialEq, Eq)]
#[cfg_attr(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64), repr(i8))]
#[cfg_attr(
    not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)),
    repr(i32)
)]
pub enum Flag {
    /// The flag is clear.
    Clear = 0,
    /// The flag is set.
    Set = 1,
}

#[cfg(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64))]
type FlagRepr = i8;
#[cfg(not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)))]
type FlagRepr = i32;

unsafe impl AtomicType for Flag {
    type Repr = FlagRepr;
}

Re: [PATCH v3 2/2] rust: sync: atomic: Add AtomicFlag bool wrapper for easier use

[FUJITA Tomonori]

On Mon, 12 Jan 2026 12:51:53 +0000
"Gary Guo" <gary@garyguo.net> wrote:

> On Sun Jan 11, 2026 at 5:05 AM GMT, FUJITA Tomonori wrote:
>> Provide AtomicFlag as a thin wrapper around Atomic<Flag> so users can
>> work with a simple bool API for load/store/xchg while keeping ordering
>> controls.
>>
>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>> ---
>>  rust/kernel/sync/atomic.rs | 46 ++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 46 insertions(+)
>>
>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> index 473d3c07e234..c3039289b989 100644
>> --- a/rust/kernel/sync/atomic.rs
>> +++ b/rust/kernel/sync/atomic.rs
>> @@ -622,3 +622,49 @@ fn from(b: bool) -> Self {
>>          }
>>      }
>>  }
>> +
>> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a [`bool`] API.
>> +pub struct AtomicFlag(Atomic<Flag>);
>> +
>> +impl AtomicFlag {
>> +    /// Creates a new atomic flag.
> 
> Need an `#[inline]` here.

Thanks, good catch. I'll add in v4.

>> +    pub const fn new(b: bool) -> Self {
>> +        if b {
>> +            AtomicFlag(Atomic::new(Flag::Set))
>> +        } else {
>> +            AtomicFlag(Atomic::new(Flag::Clear))
>> +        }
>> +    }
> 
> Would it make sense to have an inherent method on `Flag`?
> 
>     impl Flag {
>         #[inline]
>         pub const fn new(b: bool) -> Self { .. }
>     }

Yes, that makes sense. I'll change it.

Re: [PATCH v3 1/2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[Gary Guo]

On Mon Jan 12, 2026 at 10:30 PM GMT, FUJITA Tomonori wrote:
> On Mon, 12 Jan 2026 09:18:32 +0000
> Alice Ryhl <aliceryhl@google.com> wrote:
>
>> On Sun, Jan 11, 2026 at 02:05:57PM +0900, FUJITA Tomonori wrote:
>>> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>>> users can use Atomic<Flag> for boolean flags.
>>> 
>>> The backing integer type is an implementation detail; it is currently
>>> i32 but may change in the future.
>>> 
>>> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>>> particular, when RMW operations such as xchg()/cmpxchg() may be used
>>> and minimizing memory usage is not the top priority. On some
>>> architectures without byte-sized RMW instructions, Atomic<bool> can be
>>> slower for RMW operations.
>>> 
>>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>>> ---
>>>  rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
>>>  1 file changed, 56 insertions(+)
>>> 
>>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>>> index ca9cab77abf0..473d3c07e234 100644
>>> --- a/rust/kernel/sync/atomic.rs
>>> +++ b/rust/kernel/sync/atomic.rs
>>> @@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>>>          unsafe { from_repr(ret) }
>>>      }
>>>  }
>>> +
>>> +/// An atomic flag type intended to be backed by a performance-optimal integer type.
>>> +///
>>> +/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
>>> +/// in the future.
>> 
>> How is it, could we make it u8 on some architectures without penalty,
>> and have it be i32 on others? Or is i32 better always.
>
> Does the following look reasonable?
>
> #[derive(Clone, Copy, PartialEq, Eq)]
> #[cfg_attr(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64), repr(i8))]
> #[cfg_attr(
>     not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)),
>     repr(i32)
> )]

The arch list looks correct to me.

> pub enum Flag {
>     /// The flag is clear.
>     Clear = 0,
>     /// The flag is set.
>     Set = 1,
> }
>
> #[cfg(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64))]
> type FlagRepr = i8;
> #[cfg(not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)))]
> type FlagRepr = i32;

This doesn't need an extra typedef. You can just put `#[cfg]` on the associate
item below.

Best,
Gary

>
> unsafe impl AtomicType for Flag {
>     type Repr = FlagRepr;
> }

Re: [PATCH v3 1/2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Tue, 13 Jan 2026 01:12:29 +0000
"Gary Guo" <gary@garyguo.net> wrote:

> On Mon Jan 12, 2026 at 10:30 PM GMT, FUJITA Tomonori wrote:
>> On Mon, 12 Jan 2026 09:18:32 +0000
>> Alice Ryhl <aliceryhl@google.com> wrote:
>>
>>> On Sun, Jan 11, 2026 at 02:05:57PM +0900, FUJITA Tomonori wrote:
>>>> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>>>> users can use Atomic<Flag> for boolean flags.
>>>> 
>>>> The backing integer type is an implementation detail; it is currently
>>>> i32 but may change in the future.
>>>> 
>>>> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>>>> particular, when RMW operations such as xchg()/cmpxchg() may be used
>>>> and minimizing memory usage is not the top priority. On some
>>>> architectures without byte-sized RMW instructions, Atomic<bool> can be
>>>> slower for RMW operations.
>>>> 
>>>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>>>> ---
>>>>  rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
>>>>  1 file changed, 56 insertions(+)
>>>> 
>>>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>>>> index ca9cab77abf0..473d3c07e234 100644
>>>> --- a/rust/kernel/sync/atomic.rs
>>>> +++ b/rust/kernel/sync/atomic.rs
>>>> @@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>>>>          unsafe { from_repr(ret) }
>>>>      }
>>>>  }
>>>> +
>>>> +/// An atomic flag type intended to be backed by a performance-optimal integer type.
>>>> +///
>>>> +/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
>>>> +/// in the future.
>>> 
>>> How is it, could we make it u8 on some architectures without penalty,
>>> and have it be i32 on others? Or is i32 better always.
>>
>> Does the following look reasonable?
>>
>> #[derive(Clone, Copy, PartialEq, Eq)]
>> #[cfg_attr(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64), repr(i8))]
>> #[cfg_attr(
>>     not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)),
>>     repr(i32)
>> )]
> 
> The arch list looks correct to me.

Thanks for confirming.

>> pub enum Flag {
>>     /// The flag is clear.
>>     Clear = 0,
>>     /// The flag is set.
>>     Set = 1,
>> }
>>
>> #[cfg(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64))]
>> type FlagRepr = i8;
>> #[cfg(not(any(CONFIG_X86_64, CONFIG_UML, CONFIG_ARM, CONFIG_ARM64)))]
>> type FlagRepr = i32;
> 
> This doesn't need an extra typedef. You can just put `#[cfg]` on the associate
> item below.

Got it. I thought the type alias was cleaner, but I'll drop it and put
the #[cfg] on the associated type.