clippy: fix everything that clippy requires, add safety comments, fix some isolated moments in the code

Author: denisandroid

src/access.rs

@@ -1,11 +1,11 @@
 //! Access control markers for volatile pointers.
 //!
-//! This module defines markers ([`RO`], [`RW`], [`WO`]) used to specify 
-//! the capabilities of a [`VolatilePtr`]. These markers are zero-sized 
+//! This module defines markers ([`RO`], [`RW`], [`WO`]) used to specify
+//! the capabilities of a [`VolatilePtr`]. These markers are zero-sized
 //! and exist only to enforce access rules at compile time.
 
-use core::fmt::Debug;
 use cluFullTransmute::transmute_unchecked;
+use core::fmt::Debug;
 
 /// A trait that defines how a specific access marker relates to raw pointers.
 pub trait VolatilePtrAccess<T>: Debug + Clone + Copy + PartialEq + PartialOrd + Eq + Ord {
@@ -19,8 +19,8 @@ pub trait VolatilePtrAccess<T>: Debug + Clone + Copy + PartialEq + PartialOrd +
 }
 
 /// **Read-Only** access marker.
-/// 
-/// Pointers with this marker only allow `.read()` operations. 
+///
+/// Pointers with this marker only allow `.read()` operations.
 /// Maps to `*const T`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum RO {}
@@ -40,7 +40,7 @@ impl<T> VolatilePtrAccess<T> for RO {
 }
 
 /// **Read-Write** access marker.
-/// 
+///
 /// Pointers with this marker allow both `.read()` and `.write()` operations.
 /// Maps to `*mut T`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
@@ -61,7 +61,7 @@ impl<T> VolatilePtrAccess<T> for RW {
 }
 
 /// **Write-Only** access marker.
-/// 
+///
 /// Pointers with this marker only allow `.write()` operations.
 /// Maps to `*mut T`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
@@ -82,9 +82,9 @@ impl<T> VolatilePtrAccess<T> for WO {
 }
 
 /// Forcefully converts a raw pointer type to its address representation.
-/// 
+///
 /// # Safety
-/// This is used internally to perform address arithmetic. It relies on the fact 
+/// This is used internally to perform address arithmetic. It relies on the fact
 /// that `*const T` and `*mut T` have the same layout as `usize`.
 pub(crate) const unsafe fn into_usize_unchecked<A: VolatilePtrAccess<T>, T>(v: A::TPtr) -> usize {
     unsafe { transmute_unchecked(v) }

src/lib.rs

@@ -22,8 +22,8 @@ pub mod ptr;
 
 /// A helper macro to resolve volatile pointer types and access rights.
 ///
-/// This macro maps shorthand syntax (like `rw`, `ro`, `wo`) and data types 
-/// to the underlying [`VolatilePtr`] implementation. It is the core engine 
+/// This macro maps shorthand syntax (like `rw`, `ro`, `wo`) and data types
+/// to the underlying [`VolatilePtr`] implementation. It is the core engine
 /// behind the type generation in `volatile_table!`.
 ///
 /// # Syntax Patterns:
@@ -80,7 +80,7 @@ macro_rules! volatile_type {
 
 /// A universal constructor macro for creating volatile pointers.
 ///
-/// This macro provides a flexible DSL for instantiating [`VolatilePtr`] from raw pointers 
+/// This macro provides a flexible DSL for instantiating [`VolatilePtr`] from raw pointers
 /// or memory addresses (as `usize`). It handles access rights and type casting automatically.
 ///
 /// # Syntax Variations:
@@ -94,7 +94,7 @@ macro_rules! volatile_type {
 ///
 /// ```rust
 /// use volatile_table::volatile;
-/// 
+///
 /// static mut SOME_VAR: usize = 0;
 ///
 /// // 1. Default (Read-Write, usize, from raw pointer)
@@ -185,7 +185,7 @@ macro_rules! volatile {
 ///     /// System clock control
 ///     pub rw <u32> CLK_CTRL = 0x4000_0000;
 ///     /// Status register (read-only)
-///     ro <u32> STATUS = 0x4000_0004; 
+///     ro <u32> STATUS = 0x4000_0004;
 /// }
 /// ```
 ///
@@ -204,7 +204,7 @@ macro_rules! volatile {
 /// # How it works
 /// - For entries with `<type>`, the macro assumes the initialization value is a memory address (`usize`).
 /// - For entries without `<type>`, it treats the value as a pointer expression unless flagged.
-/// - The `map` block expands into a series of constant definitions where each child register 
+/// - The `map` block expands into a series of constant definitions where each child register
 ///   is calculated as `BASE_ADDR + OFFSET`.
 #[macro_export]
 macro_rules! volatile_table {
@@ -311,10 +311,10 @@ macro_rules! volatile_table {
     [ ] => [];
 }
 
-/// **Internal use only.** 
+/// **Internal use only.**
 ///
 /// This macro handles the expansion of the `map` block within [`volatile_table!`].
-/// It recursively processes register definitions and calculates their absolute 
+/// It recursively processes register definitions and calculates their absolute
 /// addresses based on a base pointer using byte offsets.
 #[doc(hidden)]
 #[macro_export]

src/ptr.rs

@@ -1,6 +1,6 @@
 //! Type-safe volatile pointer implementation.
 //!
-//! [`VolatilePtr`] is a transparent wrapper around a raw pointer that uses 
+//! [`VolatilePtr`] is a transparent wrapper around a raw pointer that uses
 //! type-state patterns to enforce access rights at compile time.
 
 use crate::access::{RO, RW, VolatilePtrAccess, WO};
@@ -35,18 +35,45 @@ impl<T> VolatilePtr<RW, T> {
     }
 
     /// Performs a volatile read.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs a raw pointer dereference.
+    /// The caller must ensure that:
+    /// - The pointer is aligned for type `T`.
+    /// - The pointer is valid for reads and points to initialized memory (or a valid MMIO register).
+    /// - No other thread is performing a non-volatile write to this memory location simultaneously.
     #[inline]
     pub unsafe fn read(&self) -> T {
         unsafe { ptr::read_volatile(self.address) }
     }
 
     /// Performs a volatile write.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs a raw pointer dereference.
+    /// The caller must ensure that:
+    /// - The pointer is aligned for type `T`.
+    /// - The pointer is valid for writes.
+    /// - The memory address is mapped and accessible by the process/core.
     #[inline]
     pub unsafe fn write(&self, value: T) {
         unsafe { ptr::write_volatile(self.address, value) }
     }
 
     /// Modifies the value using a closure (Read-Modify-Write).
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs raw pointer dereferences.
+    /// The caller must ensure the same safety requirements as for [`Self::read`] and [`Self::write`].
+    ///
+    /// # Important: Non-atomicity
+    ///
+    /// This operation is **not atomic**. It performs a separate read and a separate write.
+    /// In a multi-threaded environment or in the presence of interrupts that modify the same
+    /// register, a race condition may occur between the read and the write.
     #[inline]
     pub unsafe fn set(&self, set_fn: impl FnOnce(T) -> T) {
         unsafe {
@@ -63,20 +90,36 @@ impl<T> VolatilePtr<RW, T> {
     }
 
     /// Calculates an offset from the pointer using typed arithmetic.
-    /// 
+    ///
     /// The offset is multiplied by `size_of::<T>()`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().add(count) })
     }
 
     /// Calculates a byte-based offset from the pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn byte_add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().byte_add(count) })
     }
 
     /// Calculates a byte-based offset using wrapping arithmetic.
+    ///
+    /// # Safety
+    ///
+    /// While this method uses wrapping arithmetic, the caller is responsible
+    /// for ensuring that the resulting address points to a valid memory location
+    /// before performing any read or write operations.
     #[inline]
     pub const unsafe fn raw_byte_add(&self, count: usize) -> Self {
         let ptr = self.get_address() as *mut u8;
@@ -85,6 +128,12 @@ impl<T> VolatilePtr<RW, T> {
     }
 
     /// Spins until the register matches the expected value.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the address is valid for volatile reads.
+    /// This is a busy-wait loop; it is the caller's responsibility to ensure
+    /// the condition will eventually be met to avoid a permanent hang.
     #[inline]
     pub unsafe fn wait_until(&self, value: T, mut spin_hint: impl FnMut())
     where
@@ -106,12 +155,26 @@ where
     // RW
 
     /// Sets bits using a bitwise mask (`v | mask`).
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs raw pointer dereferences.
+    /// The caller must ensure the same safety requirements as for [`Self::read`] and [`Self::write`].
+    ///
+    /// Note that this is a non-atomic Read-Modify-Write operation.
     #[inline]
     pub unsafe fn set_bits(&self, mask: T) {
         unsafe { self.set(|v| v | mask) };
     }
 
     /// Clears bits using a bitwise mask (`v & !mask`).
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs raw pointer dereferences.
+    /// The caller must ensure the same safety requirements as for [`Self::read`] and [`Self::write`].
+    ///
+    /// Note that this is a non-atomic Read-Modify-Write operation.
     #[inline]
     pub unsafe fn clear_bits(&self, mask: T) {
         unsafe { self.set(|v| v & !mask) };
@@ -127,6 +190,14 @@ impl<T> VolatilePtr<RO, T> {
     }
 
     /// Performs a volatile read.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs a raw pointer dereference.
+    /// The caller must ensure that:
+    /// - The pointer is aligned for type `T`.
+    /// - The pointer is valid for reads and points to initialized memory (or a valid MMIO register).
+    /// - No other thread is performing a non-volatile write to this memory location simultaneously.
     #[inline]
     pub unsafe fn read(&self) -> T {
         unsafe { ptr::read_volatile(self.address) }
@@ -139,20 +210,36 @@ impl<T> VolatilePtr<RO, T> {
     }
 
     /// Calculates an offset from the pointer using typed arithmetic.
-    /// 
+    ///
     /// The offset is multiplied by `size_of::<T>()`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().add(count) })
     }
 
     /// Calculates a byte-based offset from the pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn byte_add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().byte_add(count) })
     }
 
     /// Calculates a byte-based offset using wrapping arithmetic.
+    ///
+    /// # Safety
+    ///
+    /// While this method uses wrapping arithmetic, the caller is responsible
+    /// for ensuring that the resulting address points to a valid memory location
+    /// before performing any read or write operations.
     #[inline]
     pub const unsafe fn raw_byte_add(&self, count: usize) -> Self {
         let ptr = self.get_address() as *mut u8;
@@ -161,6 +248,12 @@ impl<T> VolatilePtr<RO, T> {
     }
 
     /// Spins until the register matches the expected value.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the address is valid for volatile reads.
+    /// This is a busy-wait loop; it is the caller's responsibility to ensure
+    /// the condition will eventually be met to avoid a permanent hang.
     #[inline]
     pub unsafe fn wait_until(&self, value: T, mut spin_hint: impl FnMut())
     where
@@ -181,6 +274,14 @@ impl<T> VolatilePtr<WO, T> {
     }
 
     /// Performs a volatile write.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it performs a raw pointer dereference.
+    /// The caller must ensure that:
+    /// - The pointer is aligned for type `T`.
+    /// - The pointer is valid for writes.
+    /// - The memory address is mapped and accessible by the process/core.
     #[inline]
     pub unsafe fn write(&self, value: T) {
         unsafe { ptr::write_volatile(self.address, value) }
@@ -193,20 +294,36 @@ impl<T> VolatilePtr<WO, T> {
     }
 
     /// Calculates an offset from the pointer using typed arithmetic.
-    /// 
+    ///
     /// The offset is multiplied by `size_of::<T>()`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().add(count) })
     }
 
     /// Calculates a byte-based offset from the pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the resulting pointer is within the bounds
+    /// of the same allocated object or a valid memory-mapped region.
     #[inline]
     pub const unsafe fn byte_add(&self, count: usize) -> Self {
         Self::from_ptr(unsafe { self.get_address().byte_add(count) })
     }
 
     /// Calculates a byte-based offset using wrapping arithmetic.
+    ///
+    /// # Safety
+    ///
+    /// While this method uses wrapping arithmetic, the caller is responsible
+    /// for ensuring that the resulting address points to a valid memory location
+    /// before performing any read or write operations.
     #[inline]
     pub const unsafe fn raw_byte_add(&self, count: usize) -> Self {
         let ptr = self.get_address() as *mut u8;
@@ -223,7 +340,7 @@ where
     #[inline]
     pub const fn from_ptr(address: A::TPtr) -> Self {
         Self {
-            address: address,
+            address,
             _access_marker: PhantomData,
             _type_marker: PhantomData,
         }

tests/volatile_macro.rs

@@ -1,10 +1,9 @@
-
 #[test]
 fn test_volatile_macro() {
     use volatile_table::volatile;
-    
+
     let mut v = 10usize;
-    let addr = &mut v as *mut _ as *mut usize;
+    let addr = &mut v as *mut _;
 
     unsafe {
         // rw
@@ -33,4 +32,3 @@ fn test_volatile_macro() {
         assert_eq!(volatile_ptr.read(), 3);
     }
 }
-