rust: sync: atomic: clarify AtomicAdd safety comment
Subsystems (3)
PATCH 2/2 rust: sync: atomic: clarify AtomicAdd safety comment
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.
--- rust/kernel/sync/atomic.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
rust/kernel/sync/atomic.rs +3 -4
@@ -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 ;
Signature · 1 line
2.54.0
Gary Guo
maintainerQuoted 6 lines · 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: callingwrapping_addwith a delta fromrhs_into_delta()on a repr obtained viainto_repr()from a valid Self must produce a bit pattern valid for Self.
Where's patch 1/2?
Quoted 11 lines
Signed-off-by Sagar Taunk <[email protected]>--- rust/kernel/sync/atomic.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)rust/kernel/sync/atomic.rs +0
-0
rust/kernel/sync/atomic.rs pub unsafe trait AtomicType: Sized + Copy { · line 130
Quoted 8 lines
rust/kernel/sync/atomic.rs +1
-4@@ -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
Quoted 5 lines
rust/kernel/sync/atomic.rs +2
-0+/// `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 1/1 rust: sync: atomic: clarify AtomicAdd safety comment
In reply to Sagar TaunkThe 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.
--- rust/kernel/sync/atomic.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)
rust/kernel/sync/atomic.rs +8 -4
@@ -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 ;
Signature · 1 line
2.54.0