Re: [PATCH v2 1/2] rust: sync: atomic: Add AtomicFlag::get_mut

[Boqun Feng <boqun@kernel.org>]

On Tue, Jan 27, 2026 at 04:10:35PM +0000, Gary Guo wrote:
> On Tue Jan 27, 2026 at 3:59 PM GMT, Boqun Feng wrote:
> > On Tue, Jan 27, 2026 at 03:42:42PM +0000, Gary Guo wrote:
> >> On Tue Jan 27, 2026 at 3:35 PM GMT, Boqun Feng wrote:
> >> > [For some unknown reasons, I cannot send my reply via gmail hence reply
> >> >  via kernel.org account, I might switch from gmail later on]
> >> >
> >> > On Tue, Jan 27, 2026 at 09:52:59PM +0900, FUJITA Tomonori wrote:
> >> >> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
> >> >> 
> >> >> AtomicFlag exposes a bool API, but it lacks a get_mut() equivalent to
> >> >> Atomic<T>::get_mut().
> >> >> 
> >> >> Also add kunit tests for AtomicFlag.
> >> >> 
> >> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> >> >> ---
> >> >>  rust/kernel/sync/atomic.rs           | 20 ++++++++++++++++++++
> >> >>  rust/kernel/sync/atomic/predefine.rs | 17 +++++++++++++++++
> >> >>  2 files changed, 37 insertions(+)
> >> >> 
> >> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> >> >> index 6c46335bdb8c..b6c01d9f3a46 100644
> >> >> --- a/rust/kernel/sync/atomic.rs
> >> >> +++ b/rust/kernel/sync/atomic.rs
> >> >> @@ -591,6 +591,26 @@ pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering)
> >> >>          self.0.store(b.into(), o)
> >> >>      }
> >> >>  
> >> >> +    /// Returns a mutable reference to the underlying flag as a `bool`.
> >> >> +    ///
> >> >> +    /// This is safe because the mutable reference of the atomic flag guarantees exclusive access.
> >> >> +    pub fn get_mut(&mut self) -> &mut bool {
> >> >> +        let byte_ptr = {
> >> >> +            let ptr = self.0.as_ptr().cast::<u8>();
> >> >> +            let offset = if cfg!(target_endian = "big") {
> >> >> +                core::mem::size_of::<Flag>() - 1
> >> >> +            } else {
> >> >> +                0
> >> >> +            };
> >> >
> >> > The idea is solid, but I want to avoid endian handling in the function,
> >> > I would prefer a "struct declaration" solution like:
> >> >
> >> >     #[cfg(target_endian = "big")]
> >> >     #[repr(align(4))]
> >> >     pub(super) struct FlagInner {
> >> >         _pad: [i8; 3],
> >> > 	bool_field: bool,
> >> >     }
> >> >
> >> >     #[cfg(target_endian = "little")]
> >> >     #[repr(align(4))]
> >> >     struct FlagInner {
> >> > 	bool_field: bool,
> >> >         _pad: [i8; 3],
> >> >     }
> >> >
> >> > redefine `Flag` as `BoolFlag`
> >> >
> >> >     #[repr(i32)]
> >> >     pub enum BoolFlag {
> >> >         Clear = 0,
> >> > 	Set = 1,
> >> >     }
> >> >
> >> > and `Flag` becomes a union of `BoolFlag` and `FlagInner`:
> >> >
> >> >     /// # Invariants
> >> >     /// `Flag` is either 0 or 1 in a i32 representation which implies
> >> >     /// that `inner` is always valid as long as `_pad` stays 0.
> >> >     pub union Flag {
> >> >         pub(super) inner: FlagInner,
> >> >         pub flag: BoolFlag,
> >> >     }
> >> >
> >> >     // can static_assert that `Flag` and `BoolFlag` has the same
> >> >     // alignement and size.
> >> >
> >> > then
> >> >
> >> >     impl AtomicFlag {
> >> >         pub fn get_mut(&mut self) -> &mut bool {
> >> > 	    let flag = self.0.get_mut(); // <- &mut Flag
> >> >
> >> >             // INVARIANTS: flag.inner._pad cannot be modified via the
> >> > 	    // returned reference.
> >> > 	    // SAFETY: Per type invariants, `flag.inner.bool_field` is
> >> > 	    // always a valid bool.
> >> > 	    unsafe { &mut flag.inner.bool_field }
> >> > 	}
> >> >     }
> >> >
> >> > Thoughts?
> >> >
> >> > Regards,
> >> > Boqun
> >> 
> >> I think we really need special handling for endianness for this one single
> >> function, so doing all the extra stuff feels really unnecessary.
> >> 
> >
> > First, this one single function changes the design actually, previously
> > you can even implement a Flag as:
> >
> >    enum Flag {
> >        Clear = 6,
> >        Set = 7,
> >    }
> >
> > and it'll work, that is as long as `Flag` behaves like a bool, it's
> > fine. But now this function implies there is actually a bool in `Flag`,
> > which is kinda totally different.
> >
> > Besides, by using the current implement, we set an example about "how to
> > do a byte offset in an i32 for different endians", and then if anyone
> > wanted to do something similar, very likely they would copy-paste and
> > modify what we have here. The potential tech debts are significant. So I
> > would like to do it in a right way ("right" is probably subjective, but
> > it comes from someone who needs to live with the code as a maintainer
> > ;-) and I'm happy to switch to a better way if necessary).
> 
> I think what Fujita has is more "proper". Your approach still have the issue of
> requiring a specific ordering of the fields. If this is messed up, then the
> entire thing is broken. I.e. the safety proof of `get_mut` depends on the fields
> being ordered correctly in `FlagInner`.
> 
> If you want to go down this route then I would just scrap `enum Flag` all
> together and always define it as struct, with an internal `bool` + 3 bytes of
> zero padding. This way we don't even need unsafe for `get_mut`.
> 

Hmm.. so like:

    const PAD_SIZE: usize = <3 or 0 depending on ARCHs>

    /// # Invariants
    /// `pad` has to be all zero.
    struct Flag {
        bool_field: bool,
	pad: [i8; PAD_SIZE],
    }

    impl Flag {
        pub const fn set() -> Flag {
	    Self { true, pad: [0; PAD_SIZE] }
	}

        pub const fn clear() -> Flag {
	    Self { false, pad: [0; PAD_SIZE] }
	}
    }

?

Yes, I think it's better ;-)

Also, now given that `AtomicFlag` behaves exactly like a `Atomic<bool>`,
should we do:

    /// `AtomicFlag` documentation here.
    #[cfg(<Arch supports byte-wise atomic>)]
    type AtomicFlag = Atomic<bool>;
    #[cfg(<Arch doesn't supprot byte-wise atomic>)]
    struct AtomicFlag(Atomic<BooleanFlag>);

    // `Flag` doesn't even need to be public.
    #[cfg(<Arch doesn't supprot byte-wise atomic>)]
    struct BooleanFlag { ... }

(I renamed `Flag` -> `BooleanFlag`)

Thoughts? I don't think there is any extra benefit of exposing
`Atomic<BooleanFlag>`.

Regards,
Boqun

> Best,
> Gary
> >
> > Hope this can explain why I want to do this right now.
> >
> > Regards,
> > Boqun
> >
> >> I prefer Fujita's current version.
> >> 
> >> Best,
> >> Gary
> >> 
> >> >
> >> >> +
> >> >> +            // SAFETY: `ptr` is valid for `size_of::<Flag>()` bytes; `offset` selects the LSB.
> >> >> +            unsafe { ptr.add(offset) }
> >> >> +        };
> >> >> +
> >> >> +        // SAFETY: The LSB holds `0`/`1` for `Flag::Clear/Set`, and `bool` is `i8`-sized/aligned.
> >> >> +        unsafe { &mut *byte_ptr.cast::<bool>() }
> >> >> +    }
> >> >> +
> >> >>      /// 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 {
> >> >> diff --git a/rust/kernel/sync/atomic/predefine.rs b/rust/kernel/sync/atomic/predefine.rs
> >> >> index 11bc67ab70a3..e413b9e9fe21 100644
> >> >> --- a/rust/kernel/sync/atomic/predefine.rs
> >> >> +++ b/rust/kernel/sync/atomic/predefine.rs
> >> >> @@ -351,6 +351,23 @@ fn atomic_bool_tests() {
> >> >>          assert_eq!(Ok(false), x.cmpxchg(false, true, Full));
> >> >>      }
> >> >>  
> >> >> +    #[test]
> >> >> +    fn atomic_flag_tests() {
> >> >> +        let mut flag = AtomicFlag::new(false);
> >> >> +
> >> >> +        assert_eq!(false, flag.load(Relaxed));
> >> >> +
> >> >> +        *flag.get_mut() = true;
> >> >> +        assert_eq!(true, flag.load(Relaxed));
> >> >> +
> >> >> +        assert_eq!(true, flag.xchg(false, Relaxed));
> >> >> +        assert_eq!(false, flag.load(Relaxed));
> >> >> +
> >> >> +        *flag.get_mut() = true;
> >> >> +        assert_eq!(Ok(true), flag.cmpxchg(true, false, Full));
> >> >> +        assert_eq!(false, flag.load(Relaxed));
> >> >> +    }
> >> >> +
> >> >>      #[test]
> >> >>      fn atomic_ptr_tests() {
> >> >>          let mut v = 42;
> >> >> -- 
> >> >> 2.43.0
> >> >> 
> >> 
>