Add possibility to restore running rtc

So far the Rtc had to be reset on every
startup, leading to time lacking behind.

This has been addressed by adding method
`Rtc::restore_or_new` that allows to restore
the previous rtc, without resetting it.
In case the rtc was not running, it is initialized.

Documentation has been added and it was included
in `Rtc::new` that `Rtc::restore_or_new` should be
used for persistent time accuracy.

Example `examples/rtc.rs` has been updated to use
the new method.

Author: Rutherther

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