Allow setting RTC time

esp-hal/CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Allow configuration of period updating method for MCPWM timers (#1898)
 - Add self-testing mode for TWAI peripheral. (#1929)
 - Added a `PeripheralClockControl::reset` to the driver constructors where missing (#1893)
+- Added `Rtc::set_time_us` and `Rtc::set_time_ms` to allow setting RTC time, and `Rtc::get_rtc_time_us` and `Rtc::get_rtc_time_ms` to allow getting the RTC time without taking into account boot time (#1883)
 
 ### Changed
 
@@ -23,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Allow DMA to/from psram for esp32s3 (#1827)
 - DMA buffers now don't require a static lifetime. Make sure to never `mem::forget` an in-progress DMA transfer (consider using `#[deny(clippy::mem_forget)]`) (#1837)
 - Peripherals (where possible) are now explicitly reset and enabled in their constructors (#1893)
+- Renamed `Rtc::get_time_raw` to `Rtc::get_rtc_time_raw` (#1883)
 
 ### Fixed
 

esp-hal/src/rtc_cntl/mod.rs

@@ -83,7 +83,7 @@ use crate::efuse::Efuse;
 #[cfg(not(any(esp32c6, esp32h2)))]
 use crate::peripherals::{LPWR, TIMG0};
 #[cfg(any(esp32c6, esp32h2))]
-use crate::peripherals::{LP_TIMER, LP_WDT};
+use crate::peripherals::{LP_AON, LP_TIMER, LP_WDT};
 #[cfg(any(esp32, esp32s3, esp32c3, esp32c6))]
 use crate::rtc_cntl::sleep::{RtcSleepConfig, WakeSource, WakeTriggers};
 use crate::{
@@ -217,8 +217,12 @@ impl<'d> Rtc<'d> {
         RtcClock::estimate_xtal_frequency()
     }
 
-    /// Read the current value of the rtc time registers.
-    pub fn get_time_raw(&self) -> u64 {
+    /// Read the current raw value of the rtc time registers.
+    ///
+    /// **This function does not take into account the boot time registers, and
+    /// therefore will not react to using [`set_time_us`][Self::set_time_us]
+    /// and [`set_time_ms`][Self::set_time_ms].**
+    pub fn get_rtc_time_raw(&self) -> u64 {
         #[cfg(not(any(esp32c6, esp32h2)))]
         let rtc_cntl = unsafe { &*LPWR::ptr() };
         #[cfg(any(esp32c6, esp32h2))]
@@ -257,13 +261,113 @@ impl<'d> Rtc<'d> {
     }
 
     /// Read the current value of the rtc time registers in microseconds.
-    pub fn get_time_us(&self) -> u64 {
-        self.get_time_raw() * 1_000_000 / RtcClock::get_slow_freq().frequency().to_Hz() as u64
+    ///
+    /// **This function does not take into account the boot time registers, and
+    /// therefore will not react to using [`set_time_us`][Self::set_time_us]
+    /// and [`set_time_ms`][Self::set_time_ms].**
+    pub fn get_rtc_time_us(&self) -> u64 {
+        self.get_rtc_time_raw() * 1_000_000 / RtcClock::get_slow_freq().frequency().to_Hz() as u64
     }
 
     /// Read the current value of the rtc time registers in milliseconds.
+    ///
+    /// **This function does not take into account the boot time registers, and
+    /// therefore will not react to using [`set_time_us`][Self::set_time_us]
+    /// and [`set_time_ms`][Self::set_time_ms].**
+    pub fn get_rtc_time_ms(&self) -> u64 {
+        self.get_rtc_time_raw() * 1_000 / RtcClock::get_slow_freq().frequency().to_Hz() as u64
+    }
+
+    /// Read the current value of the boot time registers in microseconds.
+    fn get_boot_time_us(&self) -> u64 {
+        // For more info on about how RTC setting works and what it has to do with boot time, see https://github.com/esp-rs/esp-hal/pull/1883
+
+        // In terms of registers, STORE2 and STORE3 are used on all current chips
+        // (esp32, esp32p4, esp32h2, esp32c2, esp32c3, esp32c5, esp32c6, esp32c61,
+        // esp32s2, esp32s3)
+
+        // In terms of peripherals:
+
+        // - LPWR is used on the following chips: esp32, esp32p4, esp32c2, esp32c3,
+        //   esp32s2, esp32s3
+
+        // - LP_AON is used on the following chips: esp32c5, esp32c6, esp32c61, esp32h2
+
+        // For registers and peripherals used in esp-idf, see https://github.com/search?q=repo%3Aespressif%2Fesp-idf+RTC_BOOT_TIME_LOW_REG+RTC_BOOT_TIME_HIGH_REG+path%3A**%2Frtc.h&type=code
+
+        #[cfg(not(any(esp32c6, esp32h2)))]
+        let rtc_cntl = unsafe { &*LPWR::ptr() };
+        #[cfg(any(esp32c6, esp32h2))]
+        let rtc_cntl = unsafe { &*LP_AON::ptr() };
+
+        let (l, h) = (rtc_cntl.store2(), rtc_cntl.store3());
+
+        let l = l.read().bits() as u64;
+        let h = h.read().bits() as u64;
+
+        // https://github.com/espressif/esp-idf/blob/23e4823f17a8349b5e03536ff7653e3e584c9351/components/newlib/port/esp_time_impl.c#L115
+        l + (h << 32)
+    }
+
+    /// Set the current value of the boot time registers in microseconds.
+    fn set_boot_time_us(&self, boot_time_us: u64) {
+        // Please see `get_boot_time_ms` for documentation on registers and peripherals
+        // used for certain SOCs.
+
+        #[cfg(not(any(esp32c6, esp32h2)))]
+        let rtc_cntl = unsafe { &*LPWR::ptr() };
+        #[cfg(any(esp32c6, esp32h2))]
+        let rtc_cntl = unsafe { &*LP_AON::ptr() };
+
+        let (l, h) = (rtc_cntl.store2(), rtc_cntl.store3());
+
+        // https://github.com/espressif/esp-idf/blob/23e4823f17a8349b5e03536ff7653e3e584c9351/components/newlib/port/esp_time_impl.c#L102-L103
+        l.write(|w| unsafe { w.bits((boot_time_us & 0xffffffff) as u32) });
+        h.write(|w| unsafe { w.bits((boot_time_us >> 32) as u32) });
+    }
+
+    /// Read the current value of the time registers in microseconds.
+    pub fn get_time_us(&self) -> u64 {
+        // current time is boot time + time since boot
+        let rtc_time_us = self.get_rtc_time_us();
+        let boot_time_us = self.get_boot_time_us();
+        let wrapped_boot_time_us = u64::MAX - boot_time_us;
+        // We can detect if we wrapped the boot time by checking if rtc time is greater
+        // than the amount of time we would've wrapped.
+        if rtc_time_us > wrapped_boot_time_us {
+            // We also just checked that this won't overflow
+            rtc_time_us - wrapped_boot_time_us
+        } else {
+            boot_time_us + rtc_time_us
+        }
+    }
+
+    /// Read the current value of the time registers in milliseconds.
     pub fn get_time_ms(&self) -> u64 {
-        self.get_time_raw() * 1_000 / RtcClock::get_slow_freq().frequency().to_Hz() as u64
+        self.get_time_us() / 1_000
+    }
+
+    /// Set the current value of the time registers in microseconds.
+    pub fn set_time_us(&self, time_us: u64) {
+        // Current time is boot time + time since boot (rtc time)
+        // So boot time = current time - time since boot (rtc time)
+        let rtc_time_us = self.get_rtc_time_us();
+        if time_us < rtc_time_us {
+            // An overflow would happen if we subtracted rtc_time_us from time_us.
+            // To work around this, we can wrap around u64::MAX by subtracting the
+            // difference between the current time and the time since boot.
+            // Subtracting time since boot and adding current new time is equivalent and
+            // avoids overflow. We just checked that rtc_time_us is less than time_us
+            // so this won't overflow.
+            self.set_boot_time_us(u64::MAX - rtc_time_us + time_us)
+        } else {
+            self.set_boot_time_us(time_us - rtc_time_us)
+        }
+    }
+
+    /// Set the current value of the time registers in milliseconds.
+    pub fn set_time_ms(&self, time_ms: u64) {
+        self.set_time_us(time_ms * 1_000)
     }
 
     /// Enter deep sleep and wake with the provided `wake_sources`.

esp-hal/src/rtc_cntl/sleep/esp32.rs

@@ -54,7 +54,7 @@ impl WakeSource for TimerWakeupSource {
         let clock_hz = clock_freq.frequency().to_Hz() as u64;
         let ticks = self.duration.as_micros() as u64 * clock_hz / 1_000_000u64;
         // "alarm" time in slow rtc ticks
-        let now = rtc.get_time_raw();
+        let now = rtc.get_rtc_time_raw();
         let time_in_ticks = now + ticks;
         unsafe {
             rtc_cntl

esp-hal/src/rtc_cntl/sleep/esp32c3.rs

@@ -99,7 +99,7 @@ impl WakeSource for TimerWakeupSource {
         let clock_hz = clock_freq.frequency().to_Hz() as u64;
         let ticks = self.duration.as_micros() as u64 * clock_hz / 1_000_000u64;
         // "alarm" time in slow rtc ticks
-        let now = rtc.get_time_raw();
+        let now = rtc.get_rtc_time_raw();
         let time_in_ticks = now + ticks;
         unsafe {
             rtc_cntl

esp-hal/src/rtc_cntl/sleep/esp32c6.rs

@@ -46,7 +46,7 @@ impl WakeSource for TimerWakeupSource {
         let clock_hz = clock_freq.frequency().to_Hz() as u64;
         let ticks = self.duration.as_micros() as u64 * clock_hz / 1_000_000u64;
         // "alarm" time in slow rtc ticks
-        let now = rtc.get_time_raw();
+        let now = rtc.get_rtc_time_raw();
         let time_in_ticks = now + ticks;
         unsafe {
             lp_timer.tar0_high().write(|w| {

esp-hal/src/rtc_cntl/sleep/esp32s3.rs

@@ -94,7 +94,7 @@ impl WakeSource for TimerWakeupSource {
         let clock_hz = clock_freq.frequency().to_Hz() as u64;
         let ticks = self.duration.as_micros() as u64 * clock_hz / 1_000_000u64;
         // "alarm" time in slow rtc ticks
-        let now = rtc.get_time_raw();
+        let now = rtc.get_rtc_time_raw();
         let time_in_ticks = now + ticks;
         unsafe {
             rtc_cntl

examples/src/bin/rtc_time.rs

@@ -27,5 +27,10 @@ fn main() -> ! {
     loop {
         esp_println::println!("rtc time in milliseconds is {}", rtc.get_time_ms());
         delay.delay_millis(1000);
+
+        // Set the time to half a second in the past
+        let new_time = rtc.get_time_ms() - 500;
+        esp_println::println!("setting rtc time to {new_time} milliseconds");
+        rtc.set_time_ms(new_time);
     }
 }