Merge #466

466: Allow restoring currently running rtc (lost time on initialization) r=burrbull a=Rutherther

Hi, I came across a problem when using the Rtc.
The problem is that if the microcontroller is reset, some time will be lost due to the reinitialization of the oscillator.

In order to solve this, I added methods restore_or_new, restore_or_new_lsi, restore_or_new_hse.
These methods check whether the rtc is enabled and the source is correct. If this is the case, the initialization is skipped.
After testing this, (for now, only with lse) it worked as intended, no time was lost anymore and the rtc was still counting.

What do you think about this? Are there any other things needed to be done, or should I change the behavior somehow?

Co-authored-by: František Boháček <fandabohacek@gmail.com>

Author: bors[bot]

examples/rtc.rs

@@ -9,6 +9,8 @@ use panic_semihosting as _;
 use cortex_m_semihosting::hprintln;
 
 use cortex_m_rt::entry;
+use fugit::RateExtU32;
+use stm32f1xx_hal::rtc::RestoredOrNewRtc::{New, Restored};
 use stm32f1xx_hal::{pac, prelude::*, rtc::Rtc};
 
 #[entry]
@@ -19,7 +21,24 @@ fn main() -> ! {
     let rcc = p.RCC.constrain();
     let mut backup_domain = rcc.bkp.constrain(p.BKP, &mut pwr);
 
-    let rtc = Rtc::new(p.RTC, &mut backup_domain);
+    // Initializes rtc every startup, use only if you don't have a battery.
+    // let rtc = Rtc::new(p.RTC, &mut backup_domain);
+
+    // Restores Rtc: that happens in case it was already running, a battery is connected,
+    // and it was already initialized before.
+    // If you are going to use ::new with battery, the time will lack behind
+    // due to unnecessary reinitialization of the crystal,
+    // as well as reset of the selected frequency.
+    // Else, the rtc is initialized.
+    let rtc = match Rtc::restore_or_new(p.RTC, &mut backup_domain) {
+        Restored(rtc) => rtc, // The rtc is restored from previous configuration. You may verify the frequency you want if needed.
+        New(mut rtc) => {
+            // The rtc was just initialized, the clock source selected, frequency is 1.Hz()
+            // Initialize rtc with desired parameters
+            rtc.select_frequency(2u32.Hz()); // Set the frequency to 2 Hz. This will stay same after reset
+            rtc
+        }
+    };
 
     loop {
         hprintln!("time: {}", rtc.current_time());

src/rtc.rs

@@ -20,6 +20,11 @@ pub struct RtcClkLse;
 /// RTC clock source LSI oscillator clock (type state)
 pub struct RtcClkLsi;
 
+pub enum RestoredOrNewRtc<CS> {
+    Restored(Rtc<CS>),
+    New(Rtc<CS>),
+}
+
 /**
   Real time clock
 
@@ -44,14 +49,19 @@ pub struct Rtc<CS = RtcClkLse> {
 
 impl Rtc<RtcClkLse> {
     /**
-      Initialises the RTC. The `BackupDomain` struct is created by
-      `Rcc.bkp.constrain()`.
+      Initialises the RTC with low-speed external crystal source (lse).
+      The `BackupDomain` struct is created by `Rcc.bkp.constrain()`.
 
       The frequency is set to 1 Hz.
 
       Since the RTC is part of the backup domain, The RTC counter is not reset by normal resets or
       power cycles where (VBAT) still has power. Use [set_time](#method.set_time) if you want to
       reset the counter.
+
+      In case application is running of a battery on VBAT,
+      this method will reset the RTC every time, leading to lost time,
+      you may want to use
+      [`restore_or_new`](Rtc::<RtcClkLse>::restore_or_new) instead.
     */
     pub fn new(regs: RTC, bkp: &mut BackupDomain) -> Self {
         let mut result = Rtc {
@@ -72,6 +82,37 @@ impl Rtc<RtcClkLse> {
         result
     }
 
+    /// Tries to obtain currently running RTC to prevent a reset in case it was running from VBAT.
+    /// If the RTC is not running, or is not LSE, it will be reinitialized.
+    ///
+    /// # Examples
+    /// ```
+    /// let rtc = match Rtc::restore_or_new(p.RTC, &mut backup_domain) {
+    ///    Restored(rtc) => rtc, // The rtc is restored from previous configuration. You may verify the frequency you want if needed.
+    ///    New(rtc) => { // The rtc was just initialized, the clock source selected, frequency is 1.Hz()
+    ///        // Initialize rtc with desired parameters
+    ///        rtc.select_frequency(2u16.Hz()); // Set the frequency to 2 Hz. This will stay same after reset
+    ///        rtc
+    ///    }
+    /// };
+    /// ```
+    pub fn restore_or_new(regs: RTC, bkp: &mut BackupDomain) -> RestoredOrNewRtc<RtcClkLse> {
+        if !Self::is_enabled() {
+            RestoredOrNewRtc::New(Rtc::new(regs, bkp))
+        } else {
+            RestoredOrNewRtc::Restored(Rtc {
+                regs,
+                _clock_source: PhantomData,
+            })
+        }
+    }
+
+    /// Returns whether the RTC is currently enabled and LSE is selected.
+    fn is_enabled() -> bool {
+        let rcc = unsafe { &*RCC::ptr() };
+        rcc.bdcr.read().rtcen().bit() && rcc.bdcr.read().rtcsel().is_lse()
+    }
+
     /// Enables the RTC device with the lse as the clock
     fn enable_rtc(_bkp: &mut BackupDomain) {
         // NOTE: Safe RCC access because we are only accessing bdcr
@@ -93,6 +134,21 @@ impl Rtc<RtcClkLse> {
 }
 
 impl Rtc<RtcClkLsi> {
+    /**
+      Initialises the RTC with low-speed internal oscillator source (lsi).
+      The `BackupDomain` struct is created by `Rcc.bkp.constrain()`.
+
+      The frequency is set to 1 Hz.
+
+      Since the RTC is part of the backup domain, The RTC counter is not reset by normal resets or
+      power cycles where (VBAT) still has power. Use [set_time](#method.set_time) if you want to
+      reset the counter.
+
+      In case application is running of a battery on VBAT,
+      this method will reset the RTC every time, leading to lost time,
+      you may want to use
+      [`restore_or_new_lsi`](Rtc::<RtcClkLsi>::restore_or_new_lsi) instead.
+    */
     pub fn new_lsi(regs: RTC, bkp: &mut BackupDomain) -> Self {
         let mut result = Rtc {
             regs,
@@ -112,6 +168,25 @@ impl Rtc<RtcClkLsi> {
         result
     }
 
+    /// Tries to obtain currently running RTC to prevent reset in case it was running from VBAT.
+    /// If the RTC is not running, or is not LSI, it will be reinitialized.
+    pub fn restore_or_new_lsi(regs: RTC, bkp: &mut BackupDomain) -> RestoredOrNewRtc<RtcClkLsi> {
+        if !Rtc::<RtcClkLsi>::is_enabled() {
+            RestoredOrNewRtc::New(Rtc::new_lsi(regs, bkp))
+        } else {
+            RestoredOrNewRtc::Restored(Rtc {
+                regs,
+                _clock_source: PhantomData,
+            })
+        }
+    }
+
+    /// Returns whether the RTC is currently enabled and LSI is selected.
+    fn is_enabled() -> bool {
+        let rcc = unsafe { &*RCC::ptr() };
+        rcc.bdcr.read().rtcen().bit() && rcc.bdcr.read().rtcsel().is_lsi()
+    }
+
     /// Enables the RTC device with the lsi as the clock
     fn enable_rtc(_bkp: &mut BackupDomain) {
         // NOTE: Safe RCC access because we are only accessing bdcr
@@ -136,6 +211,22 @@ impl Rtc<RtcClkLsi> {
 }
 
 impl Rtc<RtcClkHseDiv128> {
+    /**
+      Initialises the RTC with high-speed external oscillator source (hse)
+      divided by 128.
+      The `BackupDomain` struct is created by `Rcc.bkp.constrain()`.
+
+      The frequency is set to 1 Hz.
+
+      Since the RTC is part of the backup domain, The RTC counter is not reset by normal resets or
+      power cycles where (VBAT) still has power. Use [set_time](#method.set_time) if you want to
+      reset the counter.
+
+      In case application is running of a battery on VBAT,
+      this method will reset the RTC every time, leading to lost time,
+      you may want to use
+      [`restore_or_new_hse`](Rtc::<RtcClkHseDiv128>::restore_or_new_hse) instead.
+    */
     pub fn new_hse(regs: RTC, bkp: &mut BackupDomain, hse: Hertz) -> Self {
         let mut result = Rtc {
             regs,
@@ -155,6 +246,28 @@ impl Rtc<RtcClkHseDiv128> {
         result
     }
 
+    /// Tries to obtain currently running RTC to prevent reset in case it was running from VBAT.
+    /// If the RTC is not running, or is not HSE, it will be reinitialized.
+    pub fn restore_or_new_hse(
+        regs: RTC,
+        bkp: &mut BackupDomain,
+        hse: Hertz,
+    ) -> RestoredOrNewRtc<RtcClkHseDiv128> {
+        if !Self::is_enabled() {
+            RestoredOrNewRtc::New(Rtc::new_hse(regs, bkp, hse))
+        } else {
+            RestoredOrNewRtc::Restored(Rtc {
+                regs,
+                _clock_source: PhantomData,
+            })
+        }
+    }
+
+    fn is_enabled() -> bool {
+        let rcc = unsafe { &*RCC::ptr() };
+        rcc.bdcr.read().rtcen().bit() && rcc.bdcr.read().rtcsel().is_hse()
+    }
+
     /// Enables the RTC device with the lsi as the clock
     fn enable_rtc(_bkp: &mut BackupDomain) {
         // NOTE: Safe RCC access because we are only accessing bdcr