Allow restoring currently running rtc (lost time on initialization)

[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?

[burrbull]

Maybe some example of usage?

[Rutherther]

Maybe some example of usage?

I could add that.

But just in case it's not clear: This should just replace the Rtc::new, and the difference is that the Rtc won't be reset, when it's already running (in case the battery is connected and it was already initialized). The previously selected frequency should remain intact as well.

Maybe I should also let the user know whether the Rtc is restored, or initialized, as that could allow for something like this:

let rtc = match Rtc::restore_or_new(...) {
  Restored(rtc) => rtc, // The rtc is restored from previous configuration
  New(rtc) => { // The rtc was just initialized, the clock source selected, period is one second
    // Initialize the rtc with desired parameters
    rtc.select_frequency(2.Hz());
    rtc
  }
};

or

let (rtc, rtc_restored) = Rtc::restore_or_new(...);
if !rtc_restored { // The rtc was just initialized, the clock source selected, period is one second
  // Initialize the rtc with desired parameters
  rtc.select_frequency(2.Hz());
}

(not sure which one makes more sense)

I imagine that "restoring" should be the dominant usecase, as users probably don't want to have their time lack behind when resetting. And in case battery is not connected, the rtc will be initialized again. I am surprised that something like this was not implemented so far, maybe people weren't using this crate for something that needed persistent clock so far?

[burrbull]

You can add these examples in documentation of rtc module and/or existing example/rtc.rs

[burrbull]

squash commits, please

[Rutherther]

Right, sorry about that.

[burrbull]

bors r+

[bors]

Build failed:

• Rustfmt

[burrbull]

bors r+

[bors]

Build succeeded!

The publicly hosted instance of bors-ng is deprecated and will go away soon.

If you want to self-host your own instance, instructions are here.
For more help, visit the forum.

If you want to switch to GitHub's built-in merge queue, visit their help page.

• ci (stm32f100, stable)
• ci (stm32f101, stable)
• ci (stm32f103, stable)
• ci (stm32f105, stable)
• ci (stm32f107, stable)
• Rustfmt