feat(rtic-v2-rtc-monotonics): Addresses some issues raised about merg…

…ing the PR (#804) * Deprecates the entire `rtc::rtic::v1` module, which primarily just implements the old RTIC v1 `Monotonic` trait for `Rtc<Count32Mode>`. * Adds #[hal_macro_helper] to functions as required and removes them from other, non-function items. * Adds documentation to `rtc::rtic::set_monotonic_prio` about the dependence on the RTIC static variable `RTIC_ASYNC_MAX_LOGICAL_PRIO`.
atsamd-rs · Jan 2, 2025 · 71b308c · 71b308c
1 parent d05b300
commit 71b308c
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 16 deletions.
diff --git a/hal/src/rtc/mod.rs b/hal/src/rtc/mod.rs
@@ -100,7 +100,6 @@ pub struct Rtc<Mode: RtcMode> {
     _mode: PhantomData<Mode>,
 }
 
-#[hal_macro_helper]
 impl<Mode: RtcMode> Rtc<Mode> {
     // --- Helper Functions for M0 vs M4 targets
     #[inline]
@@ -114,6 +113,7 @@ impl<Mode: RtcMode> Rtc<Mode> {
     }
 
     #[inline]
+    #[hal_macro_helper]
     fn mode0_ctrla(&self) -> &Mode0CtrlA {
         #[hal_cfg("rtc-d5x")]
         return self.mode0().ctrla();
@@ -122,6 +122,7 @@ impl<Mode: RtcMode> Rtc<Mode> {
     }
 
     #[inline]
+    #[hal_macro_helper]
     fn mode2_ctrla(&self) -> &Mode2CtrlA {
         #[hal_cfg("rtc-d5x")]
         return self.mode2().ctrla();
@@ -130,6 +131,7 @@ impl<Mode: RtcMode> Rtc<Mode> {
     }
 
     #[inline]
+    #[hal_macro_helper]
     fn sync(&self) {
         #[hal_cfg("rtc-d5x")]
         while self.mode2().syncbusy().read().bits() != 0 {}
@@ -166,6 +168,7 @@ impl<Mode: RtcMode> Rtc<Mode> {
     }
 
     /// Reonfigures the peripheral for 32bit counter mode.
+    #[hal_macro_helper]
     pub fn into_count32_mode(mut self) -> Rtc<Count32Mode> {
         self.enable(false);
         self.sync();
@@ -192,6 +195,7 @@ impl<Mode: RtcMode> Rtc<Mode> {
 
     /// Reconfigures the peripheral for clock/calendar mode. Requires the source
     /// clock to be running at 1024 Hz.
+    #[hal_macro_helper]
     pub fn into_clock_mode(mut self) -> Rtc<ClockMode> {
         // The max divisor is 1024, so to get 1 Hz, we need a 1024 Hz source.
         assert_eq!(

diff --git a/hal/src/rtc/modes.rs b/hal/src/rtc/modes.rs
@@ -29,7 +29,7 @@
 // access was checked in the datasheet and accounted for.
 
 use crate::pac;
-use atsamd_hal_macros::hal_macro_helper;
+use atsamd_hal_macros::{hal_cfg, hal_macro_helper};
 use pac::Rtc;
 
 /// Type-level enum for RTC interrupts.
@@ -73,7 +73,6 @@ macro_rules! create_rtc_interrupt {
 /// An abstraction of an RTC in a particular mode that provides low-level
 /// access and handles all register syncing issues using only associated
 /// functions.
-#[hal_macro_helper]
 pub trait RtcMode {
     /// The type of the COUNT register.
     type Count: Copy + PartialEq + Eq;
@@ -91,6 +90,7 @@ pub trait RtcMode {
 
     /// Resets the RTC, leaving it disabled in MODE0.
     #[inline]
+    #[hal_macro_helper]
     fn reset(rtc: &Rtc) {
         // Reset RTC back to initial settings, which disables it and enters mode 0.
         // NOTE: This register and field are the same in all modes.
@@ -111,6 +111,7 @@ pub trait RtcMode {
 
     /// Starts the RTC and does any required initialization for this mode.
     #[inline]
+    #[hal_macro_helper]
     fn start_and_initialize(rtc: &Rtc) {
         Self::enable(rtc);
 
@@ -157,6 +158,7 @@ pub trait RtcMode {
 
     /// Disables the RTC.
     #[inline]
+    #[hal_macro_helper]
     fn disable(rtc: &Rtc) {
         // SYNC: Write
         Self::sync(rtc);
@@ -169,6 +171,7 @@ pub trait RtcMode {
 
     /// Enables the RTC.
     #[inline]
+    #[hal_macro_helper]
     fn enable(rtc: &Rtc) {
         // SYNC: Write
         Self::sync(rtc);
@@ -199,7 +202,6 @@ pub trait RtcMode {
     }
 }
 
-#[hal_macro_helper]
 pub mod mode0 {
     use super::*;
 
@@ -216,6 +218,7 @@ pub mod mode0 {
         type Count = u32;
 
         #[inline]
+        #[hal_macro_helper]
         unsafe fn set_mode(rtc: &Rtc) {
             // SYNC: Write
             Self::sync(rtc);
@@ -240,6 +243,7 @@ pub mod mode0 {
         }
 
         #[inline]
+        #[hal_macro_helper]
         fn count(rtc: &Rtc) -> Self::Count {
             #[hal_cfg(any("rtc-d11", "rtc-d21"))]
             {
@@ -254,6 +258,7 @@ pub mod mode0 {
         }
 
         #[inline]
+        #[hal_macro_helper]
         fn sync_busy(rtc: &Rtc) -> bool {
             // SYNC: None
             #[hal_cfg(any("rtc-d11", "rtc-d21"))]
@@ -266,7 +271,6 @@ pub mod mode0 {
     }
 }
 
-#[hal_macro_helper]
 pub mod mode1 {
     use super::*;
 
@@ -281,6 +285,7 @@ pub mod mode1 {
         type Count = u16;
 
         #[inline]
+        #[hal_macro_helper]
         unsafe fn set_mode(rtc: &Rtc) {
             // SYNC: Write
             Self::sync(rtc);
@@ -310,6 +315,7 @@ pub mod mode1 {
         }
 
         #[inline]
+        #[hal_macro_helper]
         fn count(rtc: &Rtc) -> Self::Count {
             #[hal_cfg(any("rtc-d11", "rtc-d21"))]
             {
@@ -324,6 +330,7 @@ pub mod mode1 {
         }
 
         #[inline]
+        #[hal_macro_helper]
         fn sync_busy(rtc: &Rtc) -> bool {
             // SYNC: None
             #[hal_cfg(any("rtc-d11", "rtc-d21"))]

diff --git a/hal/src/rtc/rtic/backends.rs b/hal/src/rtc/rtic/backends.rs
@@ -96,7 +96,7 @@ macro_rules! __internal_backend_methods {
 #[macro_export]
 macro_rules! __internal_basic_backend {
     ($name:ident, $mode:ty, $mode_num:literal, $rtic_int:ty) => {
-        use atsamd_hal_macros::hal_macro_helper;
+        use atsamd_hal_macros::hal_cfg;
         use rtic_time::timer_queue::{TimerQueue, TimerQueueBackend};
         use $crate::pac;
         use $crate::rtc::modes::RtcMode;
@@ -106,7 +106,6 @@ macro_rules! __internal_basic_backend {
 
         static RTC_TQ: TimerQueue<$name> = TimerQueue::new();
 
-        #[hal_macro_helper]
         impl $name {
             $crate::__internal_backend_methods! {
                 mode = $mode;
@@ -181,7 +180,7 @@ macro_rules! __internal_basic_backend {
 #[macro_export]
 macro_rules! __internal_half_period_counting_backend {
     ($name:ident, $mode:ty, $mode_num:literal, $rtic_int:ty, $half_period_int:ty, $overflow_int:ty) => {
-        use atsamd_hal_macros::hal_macro_helper;
+        use atsamd_hal_macros::hal_cfg;
         use core::sync::atomic::Ordering;
         use portable_atomic::AtomicU64;
         use rtic_time::{
@@ -206,7 +205,6 @@ macro_rules! __internal_half_period_counting_backend {
         static RTC_PERIOD_COUNT: AtomicU64 = AtomicU64::new(0);
         static RTC_TQ: TimerQueue<$name> = TimerQueue::new();
 
-        #[hal_macro_helper]
         impl $name {
             $crate::__internal_backend_methods! {
                 mode = $mode;

diff --git a/hal/src/rtc/rtic/mod.rs b/hal/src/rtc/rtic/mod.rs
@@ -4,8 +4,8 @@
 //! Enabling the `rtic` feature is required to use this module.
 //!
 //! For RTIC v1, the old [`rtic_monotonic::Monotonic`] trait is implemented for
-//! [`Rtc`](crate::rtc::Rtc) in [`Count32Mode`](crate::rtc::Count32Mode). A
-//! monotonic for RTIC v2 is provided here.
+//! [`Rtc`](crate::rtc::Rtc) in [`Count32Mode`](crate::rtc::Count32Mode) in the
+//! [`v1`] module. A monotonic for RTIC v2 is provided here.
 //!
 //! # RTC clock selection
 //!
@@ -117,8 +117,11 @@
 
 /// Items for RTIC v1.
 ///
-/// TODO: This probably needs to be modernized (e.g. it does not implement
-/// half-period counting) or deprecated/removed.
+/// This mainly implements [`rtic_monotonic::Monotonic`] for
+/// [`Rtc<Count32Mode>`](crate::rtc::Rtc).
+///
+/// This will be removed in a future release, users should migrate to RTIC v2.
+#[deprecated]
 pub mod v1 {
     use crate::rtc::{Count32Mode, Rtc};
     use rtic_monotonic::Monotonic;
@@ -165,7 +168,7 @@ pub mod v1 {
 mod backends;
 
 use super::modes::{mode0::RtcMode0, mode1::RtcMode1, RtcMode};
-use atsamd_hal_macros::hal_macro_helper;
+use atsamd_hal_macros::hal_cfg;
 
 pub mod prelude {
     pub use super::rtc_clock;
@@ -226,7 +229,6 @@ impl RtcModeMonotonic for RtcMode1 {
     const MIN_COMPARE_TICKS: Self::Count = 8;
 }
 
-#[hal_macro_helper]
 mod backend {
     use super::*;
 
@@ -317,7 +319,16 @@ const fn cortex_logical2hw(logical: u8, nvic_prio_bits: u8) -> u8 {
     ((1 << nvic_prio_bits) - logical) << (8 - nvic_prio_bits)
 }
 
-/// This function was copied from the private function in `rtic-monotonics`.
+/// This function was modified from the private function in `rtic-monotonics`.
+///
+/// Note that this depends on the static variable `RTIC_ASYNC_MAX_LOGICAL_PRIO`
+/// defined as part of RTIC. Should this ever be used without linking with RTIC,
+/// the user would need to define this as follows:
+///
+/// ```
+/// #[no_mangle]
+/// pub static RTIC_ASYNC_MAX_LOGICAL_PRIO: u8 = (something);
+/// ```
 unsafe fn set_monotonic_prio(prio_bits: u8, interrupt: impl cortex_m::interrupt::InterruptNumber) {
     extern "C" {
         static RTIC_ASYNC_MAX_LOGICAL_PRIO: u8;