Add `Atomic::fetch_sub` with implementation and documentation in line with
existing `Atomic::fetch_add` implementation.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 rust/kernel/sync/atomic.rs          | 45 +++++++++++++++++++++++++++++++++++++
 rust/kernel/sync/atomic/internal.rs |  5 +++++
 2 files changed, 50 insertions(+)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 4aebeacb961a2..aa0b672cef848 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -559,4 +559,49 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
         // SAFETY: `ret` comes from reading `self.0`, which is a valid `T` per type invariants.
         unsafe { from_repr(ret) }
     }
+
+    /// Atomic fetch and subtract.
+    ///
+    /// Atomically updates `*self` to `(*self).wrapping_sub(v)`, and returns the value of `*self`
+    /// before the update.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::sync::atomic::{Atomic, Acquire, Full, Relaxed};
+    ///
+    /// let x = Atomic::new(42);
+    ///
+    /// assert_eq!(42, x.load(Relaxed));
+    ///
+    /// assert_eq!(30, { x.fetch_sub(12, Acquire); x.load(Relaxed) });
+    ///
+    /// let x = Atomic::new(42);
+    ///
+    /// assert_eq!(42, x.load(Relaxed));
+    ///
+    /// assert_eq!(30, { x.fetch_sub(12, Full); x.load(Relaxed) });
+    /// ```
+    #[inline(always)]
+    pub fn fetch_sub<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering) -> T
+    where
+        // Types that support addition also support subtraction.
+        T: AtomicAdd<Rhs>,
+    {
+        let v = T::rhs_into_delta(v);
+
+        // INVARIANT: `self.0` is a valid `T` after `atomic_fetch_sub*()` due to safety requirement
+        // of `AtomicAdd`.
+        let ret = {
+            match Ordering::TYPE {
+                OrderingType::Full => T::Repr::atomic_fetch_sub(&self.0, v),
+                OrderingType::Acquire => T::Repr::atomic_fetch_sub_acquire(&self.0, v),
+                OrderingType::Release => T::Repr::atomic_fetch_sub_release(&self.0, v),
+                OrderingType::Relaxed => T::Repr::atomic_fetch_sub_relaxed(&self.0, v),
+            }
+        };
+
+        // SAFETY: `ret` comes from reading `self.0`, which is a valid `T` per type invariants.
+        unsafe { from_repr(ret) }
+    }
 }
diff --git a/rust/kernel/sync/atomic/internal.rs b/rust/kernel/sync/atomic/internal.rs
index 6fdd8e59f45be..7eed8c66efff8 100644
--- a/rust/kernel/sync/atomic/internal.rs
+++ b/rust/kernel/sync/atomic/internal.rs
@@ -261,5 +261,10 @@ fn fetch_add[acquire, release, relaxed](a: &AtomicRepr<Self>, v: Self::Delta) ->
             // SAFETY: `a.as_ptr()` is valid and properly aligned.
             unsafe { bindings::#call(v, a.as_ptr().cast()) }
         }
+
+        fn fetch_sub[acquire, release, relaxed](a: &AtomicRepr<Self>, v: Self::Delta) -> Self {
+            // SAFETY: `a.as_ptr()` is valid and properly aligned.
+            unsafe { bindings::#call(v, a.as_ptr().cast()) }
+        }
     }
 );

---
base-commit: 63804fed149a6750ffd28610c5c1c98cce6bd377
change-id: 20260128-atomic-sub-2ff15962df12

Best regards,
-- 
Andreas Hindborg <a.hindborg@kernel.org>

On Wed, Jan 28, 2026 at 01:47:11PM +0100, Andreas Hindborg wrote:
> Add `Atomic::fetch_sub` with implementation and documentation in line with
> existing `Atomic::fetch_add` implementation.
> 
> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>

> +    /// let x = Atomic::new(42);
> +    ///
> +    /// assert_eq!(42, x.load(Relaxed));
> +    ///
> +    /// assert_eq!(30, { x.fetch_sub(12, Acquire); x.load(Relaxed) });

These asserts are a bit confusing to read. After all, the fetch_sub call
also returns a value, so how about this?

let x = Atomic::new(42);
assert_eq!(42, x.load(Relaxed));
assert_eq!(42, x.fetch_sub(12, Acquire));
assert_eq!(30, x.load(Relaxed));

Otherwise LGTM.
Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Alice

"Alice Ryhl" <aliceryhl@google.com> writes:

> On Wed, Jan 28, 2026 at 01:47:11PM +0100, Andreas Hindborg wrote:
>> Add `Atomic::fetch_sub` with implementation and documentation in line with
>> existing `Atomic::fetch_add` implementation.
>>
>> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
>
>> +    /// let x = Atomic::new(42);
>> +    ///
>> +    /// assert_eq!(42, x.load(Relaxed));
>> +    ///
>> +    /// assert_eq!(30, { x.fetch_sub(12, Acquire); x.load(Relaxed) });
>
> These asserts are a bit confusing to read. After all, the fetch_sub call
> also returns a value, so how about this?
>
> let x = Atomic::new(42);
> assert_eq!(42, x.load(Relaxed));
> assert_eq!(42, x.fetch_sub(12, Acquire));
> assert_eq!(30, x.load(Relaxed));

We can do that. I basically copied the docs from add. Should I change
those as well?


Best regards,
Andreas Hindborg

On Wed Jan 28, 2026 at 2:16 PM GMT, Andreas Hindborg wrote:
> "Alice Ryhl" <aliceryhl@google.com> writes:
>
>> On Wed, Jan 28, 2026 at 01:47:11PM +0100, Andreas Hindborg wrote:
>>> Add `Atomic::fetch_sub` with implementation and documentation in line with
>>> existing `Atomic::fetch_add` implementation.
>>>
>>> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
>>
>>> +    /// let x = Atomic::new(42);
>>> +    ///
>>> +    /// assert_eq!(42, x.load(Relaxed));
>>> +    ///
>>> +    /// assert_eq!(30, { x.fetch_sub(12, Acquire); x.load(Relaxed) });
>>
>> These asserts are a bit confusing to read. After all, the fetch_sub call
>> also returns a value, so how about this?
>>
>> let x = Atomic::new(42);
>> assert_eq!(42, x.load(Relaxed));
>> assert_eq!(42, x.fetch_sub(12, Acquire));
>> assert_eq!(30, x.load(Relaxed));
>
> We can do that. I basically copied the docs from add. Should I change
> those as well?

Please do. I also find that the existing example has too many line breaks :)
Something compact as what Alice suggested would be nice.

Best,
Gary

>
> Best regards,
> Andreas Hindborg