deprecate ptr() function for the v0.7.x series

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Deprecated
+- the `ptr()` function on all peripherals register blocks in favor of
+  the associated constant `PTR` (#386).
+
 ## [v0.7.4] - 2021-12-31
 
 ### Added

panic-itm/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- changed `ITM::ptr()` to `ITM::PTR` as the `ptr()` functions are
+  deprecated (#386).
+
 ## [v0.4.2] - 2020-11-14
 
 - Support cortex-m v0.7.0

panic-itm/src/lib.rs

@@ -46,7 +46,7 @@ use cortex_m::peripheral::ITM;
 fn panic(info: &PanicInfo) -> ! {
     interrupt::disable();
 
-    let itm = unsafe { &mut *ITM::ptr() };
+    let itm = unsafe { &mut *ITM::PTR };
     let stim = &mut itm.stim[0];
 
     iprintln!(stim, "{}", info);

src/itm.rs

@@ -128,7 +128,7 @@ pub fn write_all(port: &mut Stim, buffer: &[u8]) {
 ///
 /// ```no_run
 /// # use cortex_m::{itm::{self, Aligned}, peripheral::ITM};
-/// # let port = unsafe { &mut (*ITM::ptr()).stim[0] };
+/// # let port = unsafe { &mut (*ITM::PTR).stim[0] };
 /// let mut buffer = Aligned([0; 14]);
 ///
 /// buffer.0.copy_from_slice(b"Hello, world!\n");

src/peripheral/cpuid.rs

@@ -122,7 +122,7 @@ impl CPUID {
     pub fn cache_dminline() -> u32 {
         const CTR_DMINLINE_POS: u32 = 16;
         const CTR_DMINLINE_MASK: u32 = 0xF << CTR_DMINLINE_POS;
-        let ctr = unsafe { (*Self::ptr()).ctr.read() };
+        let ctr = unsafe { (*Self::PTR).ctr.read() };
         (ctr & CTR_DMINLINE_MASK) >> CTR_DMINLINE_POS
     }
 
@@ -134,7 +134,7 @@ impl CPUID {
     pub fn cache_iminline() -> u32 {
         const CTR_IMINLINE_POS: u32 = 0;
         const CTR_IMINLINE_MASK: u32 = 0xF << CTR_IMINLINE_POS;
-        let ctr = unsafe { (*Self::ptr()).ctr.read() };
+        let ctr = unsafe { (*Self::PTR).ctr.read() };
         (ctr & CTR_IMINLINE_MASK) >> CTR_IMINLINE_POS
     }
 }

src/peripheral/dcb.rs

@@ -53,7 +53,7 @@ impl DCB {
     pub fn is_debugger_attached() -> bool {
         unsafe {
             // do an 8-bit read of the 32-bit DHCSR register, and get the LSB
-            let value = ptr::read_volatile(Self::ptr() as *const u8);
+            let value = ptr::read_volatile(Self::PTR as *const u8);
             value & 0x1 == 1
         }
     }

src/peripheral/dwt.rs

@@ -77,39 +77,39 @@ impl DWT {
     #[inline]
     pub fn num_comp() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { ((*Self::ptr()).ctrl.read() >> NUMCOMP_OFFSET) as u8 }
+        unsafe { ((*Self::PTR).ctrl.read() >> NUMCOMP_OFFSET) as u8 }
     }
 
     /// Returns `true` if the the implementation supports sampling and exception tracing
     #[cfg(not(armv6m))]
     #[inline]
     pub fn has_exception_trace() -> bool {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).ctrl.read() & NOTRCPKT == 0 }
+        unsafe { (*Self::PTR).ctrl.read() & NOTRCPKT == 0 }
     }
 
     /// Returns `true` if the implementation includes external match signals
     #[cfg(not(armv6m))]
     #[inline]
     pub fn has_external_match() -> bool {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).ctrl.read() & NOEXTTRIG == 0 }
+        unsafe { (*Self::PTR).ctrl.read() & NOEXTTRIG == 0 }
     }
 
     /// Returns `true` if the implementation supports a cycle counter
     #[cfg(not(armv6m))]
     #[inline]
     pub fn has_cycle_counter() -> bool {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).ctrl.read() & NOCYCCNT == 0 }
+        unsafe { (*Self::PTR).ctrl.read() & NOCYCCNT == 0 }
     }
 
     /// Returns `true` if the implementation the profiling counters
     #[cfg(not(armv6m))]
     #[inline]
     pub fn has_profiling_counter() -> bool {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).ctrl.read() & NOPRFCNT == 0 }
+        unsafe { (*Self::PTR).ctrl.read() & NOPRFCNT == 0 }
     }
 
     /// Enables the cycle counter
@@ -138,7 +138,7 @@ impl DWT {
     #[inline]
     pub fn cycle_counter_enabled() -> bool {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).ctrl.read() & CYCCNTENA != 0 }
+        unsafe { (*Self::PTR).ctrl.read() & CYCCNTENA != 0 }
     }
 
     /// Returns the current clock cycle count
@@ -157,7 +157,7 @@ impl DWT {
     #[inline]
     pub fn cycle_count() -> u32 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).cyccnt.read() }
+        unsafe { (*Self::PTR).cyccnt.read() }
     }
 
     /// Set the cycle count
@@ -174,7 +174,7 @@ impl DWT {
     #[inline]
     pub fn unlock() {
         // NOTE(unsafe) atomic write to a stateless, write-only register
-        unsafe { (*Self::ptr()).lar.write(0xC5AC_CE55) }
+        unsafe { (*Self::PTR).lar.write(0xC5AC_CE55) }
     }
 
     /// Get the CPI count
@@ -188,7 +188,7 @@ impl DWT {
     #[inline]
     pub fn cpi_count() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).cpicnt.read() as u8 }
+        unsafe { (*Self::PTR).cpicnt.read() as u8 }
     }
 
     /// Set the CPI count
@@ -203,7 +203,7 @@ impl DWT {
     #[inline]
     pub fn exception_count() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).exccnt.read() as u8 }
+        unsafe { (*Self::PTR).exccnt.read() as u8 }
     }
 
     /// Set the exception count
@@ -224,7 +224,7 @@ impl DWT {
     #[inline]
     pub fn sleep_count() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).sleepcnt.read() as u8 }
+        unsafe { (*Self::PTR).sleepcnt.read() as u8 }
     }
 
     /// Set the sleep count
@@ -239,7 +239,7 @@ impl DWT {
     #[inline]
     pub fn lsu_count() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).lsucnt.read() as u8 }
+        unsafe { (*Self::PTR).lsucnt.read() as u8 }
     }
 
     /// Set the lsu count
@@ -256,7 +256,7 @@ impl DWT {
     #[inline]
     pub fn fold_count() -> u8 {
         // NOTE(unsafe) atomic read with no side effects
-        unsafe { (*Self::ptr()).foldcnt.read() as u8 }
+        unsafe { (*Self::PTR).foldcnt.read() as u8 }
     }
 
     /// Set the folded instruction count

src/peripheral/mod.rs

@@ -50,7 +50,7 @@
 //! } // all the peripheral singletons are destroyed here
 //!
 //! // actually safe because this is an atomic read with no side effects
-//! let cyccnt = unsafe { (*DWT::ptr()).cyccnt.read() };
+//! let cyccnt = unsafe { (*DWT::PTR).cyccnt.read() };
 //! ```
 //!
 //! # References
@@ -245,8 +245,9 @@ impl AC {
     /// Pointer to the register block
     pub const PTR: *const self::ac::RegisterBlock = 0xE000_EF90 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const self::ac::RegisterBlock {
         Self::PTR
     }
@@ -271,8 +272,9 @@ impl CBP {
     /// Pointer to the register block
     pub const PTR: *const self::cbp::RegisterBlock = 0xE000_EF50 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const self::cbp::RegisterBlock {
         Self::PTR
     }
@@ -299,8 +301,9 @@ impl CPUID {
     /// Pointer to the register block
     pub const PTR: *const self::cpuid::RegisterBlock = 0xE000_ED00 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const self::cpuid::RegisterBlock {
         Self::PTR
     }
@@ -326,8 +329,9 @@ impl DCB {
     /// Pointer to the register block
     pub const PTR: *const dcb::RegisterBlock = 0xE000_EDF0 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const dcb::RegisterBlock {
         Self::PTR
     }
@@ -353,8 +357,9 @@ impl DWT {
     /// Pointer to the register block
     pub const PTR: *const dwt::RegisterBlock = 0xE000_1000 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const dwt::RegisterBlock {
         Self::PTR
     }
@@ -381,8 +386,9 @@ impl FPB {
     /// Pointer to the register block
     pub const PTR: *const fpb::RegisterBlock = 0xE000_2000 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const fpb::RegisterBlock {
         Self::PTR
     }
@@ -410,8 +416,9 @@ impl FPU {
     /// Pointer to the register block
     pub const PTR: *const fpu::RegisterBlock = 0xE000_EF30 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const fpu::RegisterBlock {
         Self::PTR
     }
@@ -443,8 +450,9 @@ impl ICB {
     /// Pointer to the register block
     pub const PTR: *mut icb::RegisterBlock = 0xE000_E004 as *mut _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *mut icb::RegisterBlock {
         Self::PTR
     }
@@ -478,8 +486,9 @@ impl ITM {
     /// Pointer to the register block
     pub const PTR: *mut itm::RegisterBlock = 0xE000_0000 as *mut _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *mut itm::RegisterBlock {
         Self::PTR
     }
@@ -514,8 +523,9 @@ impl MPU {
     /// Pointer to the register block
     pub const PTR: *const mpu::RegisterBlock = 0xE000_ED90 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const mpu::RegisterBlock {
         Self::PTR
     }
@@ -541,8 +551,9 @@ impl NVIC {
     /// Pointer to the register block
     pub const PTR: *const nvic::RegisterBlock = 0xE000_E100 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const nvic::RegisterBlock {
         Self::PTR
     }
@@ -569,8 +580,9 @@ impl SAU {
     /// Pointer to the register block
     pub const PTR: *const sau::RegisterBlock = 0xE000_EDD0 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const sau::RegisterBlock {
         Self::PTR
     }
@@ -597,8 +609,9 @@ impl SCB {
     /// Pointer to the register block
     pub const PTR: *const scb::RegisterBlock = 0xE000_ED04 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const scb::RegisterBlock {
         Self::PTR
     }
@@ -624,8 +637,9 @@ impl SYST {
     /// Pointer to the register block
     pub const PTR: *const syst::RegisterBlock = 0xE000_E010 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const syst::RegisterBlock {
         Self::PTR
     }
@@ -652,8 +666,9 @@ impl TPIU {
     /// Pointer to the register block
     pub const PTR: *const tpiu::RegisterBlock = 0xE004_0000 as *const _;
 
-    /// Returns a pointer to the register block (to be deprecated in 0.7)
+    /// Returns a pointer to the register block
     #[inline(always)]
+    #[deprecated(since = "0.7.5", note = "Use the associated constant `PTR` instead")]
     pub const fn ptr() -> *const tpiu::RegisterBlock {
         Self::PTR
     }