[PATCH 2/2] rust: sync: atomic: clarify AtomicAdd safety comment

[PATCH 2/2] rust: sync: atomic: clarify AtomicAdd safety comment

[Sagar Taunk]

The previous safety comment for AtomicAdd was marked with a TODO
and contained a grammatically broken sentence that was difficult to
parse. Rewrite the safety requirement to clearly state the actual
contract: calling wrapping_add with a delta from rhs_into_delta()
on a repr obtained via into_repr() from a valid Self must produce
a bit pattern valid for Self.

Signed-off-by: Sagar Taunk <sagartaunk2@gmail.com>
---
 rust/kernel/sync/atomic.rs | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 9cd009d57e35..b38d9a17f9e8 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -127,10 +127,9 @@ pub unsafe trait AtomicType: Sized + Copy {
 ///
 /// # Safety
 ///
-// TODO: Properly defines `wrapping_add` in the following comment.
-/// `wrapping_add` any value of type `Self::Repr::Delta` obtained by [`Self::rhs_into_delta()`] to
-/// any value of type `Self::Repr` obtained through transmuting a value of type `Self` to must
-/// yield a value with a bit pattern also valid for `Self`.
+/// Calling `wrapping_add` with any value of type `Self::Repr::Delta` produced by
+/// `Self::rhs_into_delta()`, on any `Self::Repr` value obtained via `into_repr()` from a valid
+/// `Self`, must produce a bit pattern also valid for `Self`.
 pub unsafe trait AtomicAdd<Rhs = Self>: AtomicType {
     /// Converts `Rhs` into the `Delta` type of the atomic implementation.
     fn rhs_into_delta(rhs: Rhs) -> <Self::Repr as AtomicImpl>::Delta;
-- 
2.54.0

Re: [PATCH 2/2] rust: sync: atomic: clarify AtomicAdd safety comment

[Gary Guo]

On Mon Apr 27, 2026 at 9:32 PM BST, Sagar Taunk wrote:
> The previous safety comment for AtomicAdd was marked with a TODO
> and contained a grammatically broken sentence that was difficult to
> parse. Rewrite the safety requirement to clearly state the actual
> contract: calling wrapping_add with a delta from rhs_into_delta()
> on a repr obtained via into_repr() from a valid Self must produce
> a bit pattern valid for Self.

Where's patch 1/2?

>
> Signed-off-by: Sagar Taunk <sagartaunk2@gmail.com>
> ---
>  rust/kernel/sync/atomic.rs | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index 9cd009d57e35..b38d9a17f9e8 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -127,10 +127,9 @@ pub unsafe trait AtomicType: Sized + Copy {
>  ///
>  /// # Safety
>  ///
> -// TODO: Properly defines `wrapping_add` in the following comment.
> -/// `wrapping_add` any value of type `Self::Repr::Delta` obtained by [`Self::rhs_into_delta()`] to
> -/// any value of type `Self::Repr` obtained through transmuting a value of type `Self` to must
> -/// yield a value with a bit pattern also valid for `Self`.
> +/// Calling `wrapping_add` with any value of type `Self::Repr::Delta` produced by

It does not read to me there's any clarification being done here.

Best,
Gary

> +/// `Self::rhs_into_delta()`, on any `Self::Repr` value obtained via `into_repr()` from a valid
> +/// `Self`, must produce a bit pattern also valid for `Self`.
>  pub unsafe trait AtomicAdd<Rhs = Self>: AtomicType {
>      /// Converts `Rhs` into the `Delta` type of the atomic implementation.
>      fn rhs_into_delta(rhs: Rhs) -> <Self::Repr as AtomicImpl>::Delta;

[PATCH v2] rust: sync: atomic: clarify AtomicAdd safety comment

[Sagar Taunk]

The previous safety comment for AtomicAdd was marked with a TODO
and contained a grammatically broken sentence that was difficult to
parse. Rewrite the comment to fix the grammar and clearly define the
safety contract, including what `wrapping_add` means in the context
and why `Self::Repr::Delta` may differ from `Self::Repr`.

Signed-off-by: Sagar Taunk <sagartaunk2@gmail.com>
---
 rust/kernel/sync/atomic.rs | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 9cd009d57e35..4000fff16e69 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -127,10 +127,14 @@ pub unsafe trait AtomicType: Sized + Copy {
 ///
 /// # Safety
 ///
-// TODO: Properly defines `wrapping_add` in the following comment.
-/// `wrapping_add` any value of type `Self::Repr::Delta` obtained by [`Self::rhs_into_delta()`] to
-/// any value of type `Self::Repr` obtained through transmuting a value of type `Self` to must
-/// yield a value with a bit pattern also valid for `Self`.
+/// `Self::Repr::Delta` is the type of value being added in the underlying
+/// C atomic operation, and may differ from `Self::Repr` (e.g., `i32` for 32-bit
+/// integer atomics or `isize` rather than the pointer value `*const c_void` for pointer atomics,
+/// where the C function expects a byte offset rather than the pointer itself).
+/// Thus, for any `Self::Repr` obtained by transmuting a valid `Self`,
+/// adding any `Self::Repr::Delta` value produced by `Self::rhs_into_delta()` using
+/// `wrapping_add`, where `wrapping_add` denotes addition that wraps on overflow
+/// rather than causing undefined behavior, must yield a bit pattern that is valid for `Self`.
 pub unsafe trait AtomicAdd<Rhs = Self>: AtomicType {
     /// Converts `Rhs` into the `Delta` type of the atomic implementation.
     fn rhs_into_delta(rhs: Rhs) -> <Self::Repr as AtomicImpl>::Delta;
-- 
2.54.0