Document, remove time::now

esp-hal-embassy/src/timer_queue.rs

@@ -60,7 +60,9 @@ impl TimerQueue {
     }
 
     pub fn dispatch(&self) {
-        let now = esp_hal::time::now().duration_since_epoch().as_micros();
+        let now = esp_hal::time::Instant::now()
+            .duration_since_epoch()
+            .as_micros();
         self.arm_alarm(now);
     }
 

esp-hal/CHANGELOG.md

@@ -8,9 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+
 - SPI: Added support for 3-wire SPI (#2919)
 - UART: Add separate config for Rx and Tx (#2965)
 - Added accessor methods to config structs (#3011)
+- `esp_hal::time::{Rate, Duration, Instant}` (#3083)
 - Async support for ADC oneshot reads for ESP32C2, ESP32C3, ESP32C6 and ESP32H2 (#2925, #3082)
 
 ### Changed
@@ -33,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `flip-link` feature is now a config option (`ESP_HAL_CONFIG_FLIP_LINK`) (#3001)
 - Migrate AES driver to DMA move API (#3084)
 - Removed features `psram-quad` and `psram-octal` - replaced by `psram` and the `ESP_HAL_CONFIG_PSRAM_MODE` (`quad`/`octal`) (#3001)
+- The `esp_hal::time` module no longer reexports `fugit` types (#3083)
 
 - I2C: Async functions are postfixed with `_async`, non-async functions are available in async-mode (#3056)
 
@@ -48,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OutputOpenDrain has been removed (#3029)
 - The fields of config structs are no longer public (#3011)
 - Removed the dysfunctional `DmaChannel::set_priority` function (#3088)
+- `esp_hal::time::now()`, which has been replaced by `esp_hal::time::Instant::now()` (#3083)
 
 ## [0.23.1] - 2025-01-15
 

esp-hal/MIGRATING-0.23.md

@@ -266,6 +266,7 @@ All async functions now include the `_async` postfix. Additionally the non-async
 ```diff
 - let result = i2c.write_read(0x77, &[0xaa], &mut data).await;
 + let result = i2c.write_read_async(0x77, &[0xaa], &mut data).await;
+```
 
 ## ADC Changes
 
@@ -277,3 +278,17 @@ NOTE: Async support is only supported in ESP32C3 and ESP32C6 for now
 - Adc<'d, ADC>
 + Adc<'d, ADC, Blocking>
 ```
+
+## time API changes
+
+ESP-HAL no longer publicly exposes `fugit` and no longer exposes the concept of a `tick`.
+This comes with a number of changes:
+
+- The `RateExtU32` and similar traits are no longer used, which means `.kHz()` and similar suffix
+  conversions are no longer available. A number of matching constructors are available. For example,
+  instead of `1.MHz()` you need to write `Rate::from_mhz(1)`.
+- Methods on `esp_hal::time` types are named differently.
+  - Getters are prefixed with `as_`, e.g. `Duration::as_secs`.
+  - Constructors are prefixed with `from`, e.g. `Rate::from_mhz`.
+  - A number of functions that convert from a number into a time type (e.g. `Duration::from_ticks`)
+    are not available. Use conversions from physical units of time, like `Duration::from_millis`.

esp-hal/src/delay.rs

@@ -3,7 +3,7 @@
 //! ## Overview
 //!
 //! The Delay driver provides blocking delay functionalities using the
-//! [now] function.
+//! [`Instant`] struct.
 //!
 //! ## Configuration
 //!
@@ -30,7 +30,6 @@
 //! 
 //! [DelayNs]: https://docs.rs/embedded-hal/1.0.0/embedded_hal/delay/trait.DelayNs.html
 //! [embedded-hal]: https://docs.rs/embedded-hal/1.0.0/embedded_hal/delay/index.html
-//! [now]: crate::time::now
 
 use crate::time::{Duration, Instant};
 

esp-hal/src/time.rs

@@ -144,7 +144,17 @@ impl defmt::Format for Instant {
 }
 
 impl Instant {
+    /// Represents the moment the system booted.
+    pub const EPOCH: Instant = Instant(InnerInstant::from_ticks(0));
+
     /// Returns the current instant.
+    ///
+    /// The counter won’t measure time in sleep-mode.
+    ///
+    /// The timer has a 1 microsecond resolution and will wrap after
+    #[cfg_attr(esp32, doc = "36_558 years")]
+    #[cfg_attr(esp32s2, doc = "7_311 years")]
+    #[cfg_attr(not(any(esp32, esp32s2)), doc = "more than 7 years")]
     pub fn now() -> Self {
         now()
     }
@@ -154,8 +164,8 @@ impl Instant {
     }
 
     /// Returns the elapsed time since boot.
-    pub const fn duration_since_epoch(&self) -> Duration {
-        Duration::from_micros(self.0.ticks())
+    pub fn duration_since_epoch(&self) -> Duration {
+        Self::EPOCH.elapsed()
     }
 
     /// Returns the elapsed `Duration` since this instant was created.
@@ -375,15 +385,7 @@ impl core::ops::Div<Duration> for Duration {
     }
 }
 
-/// Provides time since system start in microseconds precision.
-///
-/// The counter won’t measure time in sleep-mode.
-///
-/// The timer will wrap after
-#[cfg_attr(esp32, doc = "36_558 years")]
-#[cfg_attr(esp32s2, doc = "7_311 years")]
-#[cfg_attr(not(any(esp32, esp32s2)), doc = "more than 7 years")]
-pub fn now() -> Instant {
+fn now() -> Instant {
     #[cfg(esp32)]
     let (ticks, div) = {
         // on ESP32 use LACT

esp-hal/src/timer/systimer.rs

@@ -93,7 +93,7 @@ impl SystemTimer {
 
     /// Create a new instance.
     pub fn new(_systimer: SYSTIMER) -> Self {
-        // Don't reset Systimer as it will break `time::now`, only enable it
+        // Don't reset Systimer as it will break `time::Instant::now`, only enable it
         PeripheralClockControl::enable(PeripheralEnable::Systimer);
 
         #[cfg(soc_etm)]
@@ -124,7 +124,7 @@ impl SystemTimer {
     ///
     /// - Disabling a `Unit` whilst [`Alarm`]s are using it will affect the
     ///   [`Alarm`]s operation.
-    /// - Disabling Unit0 will affect [`now`](crate::time::now).
+    /// - Disabling Unit0 will affect [`Instant::now`].
     pub unsafe fn configure_unit(unit: Unit, config: UnitConfig) {
         unit.configure(config)
     }
@@ -139,8 +139,7 @@ impl SystemTimer {
     ///
     /// - Modifying a unit's count whilst [`Alarm`]s are using it may cause
     ///   unexpected behaviour
-    /// - Any modification of the unit0 count will affect
-    ///   [`now`](crate::time::now).
+    /// - Any modification of the unit0 count will affect [`Instant::now`]
     pub unsafe fn set_unit_value(unit: Unit, value: u64) {
         unit.set_count(value)
     }

esp-hal/src/timer/timg.rs

@@ -151,7 +151,7 @@ impl TimerGroupInstance for TIMG0 {
 
     fn reset_peripheral() {
         // FIXME: for TIMG0 do nothing for now because the reset breaks
-        // `time::now`
+        // `time::Instant::now`
     }
 
     fn configure_wdt_src_clk() {

esp-wifi/src/ble/npl.rs

@@ -661,7 +661,9 @@ unsafe extern "C" fn ble_npl_time_ms_to_ticks(
 
 unsafe extern "C" fn ble_npl_time_get() -> u32 {
     trace!("ble_npl_time_get");
-    esp_hal::time::now().duration_since_epoch().as_millis() as u32
+    esp_hal::time::Instant::now()
+        .duration_since_epoch()
+        .as_millis() as u32
 }
 
 unsafe extern "C" fn ble_npl_callout_set_arg(

esp-wifi/src/timer/riscv.rs

@@ -92,7 +92,9 @@ pub(crate) fn yield_task() {
 /// Current systimer count value
 /// A tick is 1 / 1_000_000 seconds
 pub(crate) fn systimer_count() -> u64 {
-    esp_hal::time::now().duration_since_epoch().as_micros()
+    esp_hal::time::Instant::now()
+        .duration_since_epoch()
+        .as_micros()
 }
 
 // TODO: use an Instance type instead...

esp-wifi/src/timer/xtensa.rs

@@ -17,7 +17,9 @@ pub const TICKS_PER_SECOND: u64 = 1_000_000;
 /// This function must not be called in a critical section. Doing so may return
 /// an incorrect value.
 pub(crate) fn systimer_count() -> u64 {
-    esp_hal::time::now().duration_since_epoch().as_micros()
+    esp_hal::time::Instant::now()
+        .duration_since_epoch()
+        .as_micros()
 }
 
 pub(crate) fn setup_timer(mut timer1: TimeBase) {

esp-wifi/src/wifi/os_adapter.rs

@@ -1500,7 +1500,9 @@ pub unsafe extern "C" fn log_writev(
 ///
 /// *************************************************************************
 pub unsafe extern "C" fn log_timestamp() -> u32 {
-    esp_hal::time::now().duration_since_epoch().as_millis() as u32
+    esp_hal::time::Instant::now()
+        .duration_since_epoch()
+        .as_millis() as u32
 }
 
 /// **************************************************************************

esp-wifi/src/wifi/utils.rs

@@ -8,11 +8,13 @@ use smoltcp::{
 use super::{WifiApDevice, WifiController, WifiDevice, WifiDeviceMode, WifiError, WifiStaDevice};
 use crate::EspWifiController;
 
-// [esp_hal::time::now()] as a smoltcp [`Instant`]
+/// [esp_hal::time::Instant] as a smoltcp [`Instant`]
 #[cfg(feature = "smoltcp")]
 fn timestamp() -> smoltcp::time::Instant {
     smoltcp::time::Instant::from_micros(
-        esp_hal::time::now().duration_since_epoch().as_micros() as i64
+        esp_hal::time::Instant::now()
+            .duration_since_epoch()
+            .as_micros() as i64,
     )
 }
 

examples/src/bin/hmac.rs

@@ -94,19 +94,19 @@ fn main() -> ! {
         let mut remaining = nsrc;
         hw_hmac.init();
         block!(hw_hmac.configure(HmacPurpose::ToUser, KeyId::Key0)).expect("Key purpose mismatch");
-        let pre_hw_hmac = esp_hal::time::now();
+        let pre_hw_hmac = esp_hal::time::Instant::now();
         while remaining.len() > 0 {
             remaining = block!(hw_hmac.update(remaining)).unwrap();
         }
         block!(hw_hmac.finalize(output.as_mut_slice())).unwrap();
-        let post_hw_hmac = esp_hal::time::now();
-        let hw_time = post_hw_hmac - pre_hw_hmac;
+        let hw_time = pre_hw_hmac.elapsed();
+
         let mut sw_hmac = HmacSha256::new_from_slice(key).expect("HMAC can take key of any size");
-        let pre_sw_hash = esp_hal::time::now();
+        let pre_sw_hash = esp_hal::time::Instant::now();
         sw_hmac.update(nsrc);
         let soft_result = sw_hmac.finalize().into_bytes();
-        let post_sw_hash = esp_hal::time::now();
-        let soft_time = post_sw_hash - pre_sw_hash;
+
+        let soft_time = pre_sw_hash.elapsed();
         for (a, b) in output.iter().zip(soft_result) {
             assert_eq!(*a, b);
         }

examples/src/bin/wifi_access_point.rs

@@ -73,7 +73,7 @@ fn main() -> ! {
     let mut wifi = peripherals.WIFI;
     let (iface, device, mut controller) =
         create_network_interface(&init, &mut wifi, WifiApDevice).unwrap();
-    let now = || time::now().duration_since_epoch().as_millis();
+    let now = || time::Instant::now().duration_since_epoch().as_millis();
 
     let mut socket_set_entries: [SocketStorage; 3] = Default::default();
     let socket_set = SocketSet::new(&mut socket_set_entries[..]);
@@ -129,7 +129,7 @@ fn main() -> ! {
             println!("Connected");
 
             let mut time_out = false;
-            let deadline = time::now() + Duration::from_secs(20);
+            let deadline = time::Instant::now() + Duration::from_secs(20);
             let mut buffer = [0u8; 1024];
             let mut pos = 0;
             while let Ok(len) = socket.read(&mut buffer[pos..]) {
@@ -143,7 +143,7 @@ fn main() -> ! {
 
                 pos += len;
 
-                if time::now() > deadline {
+                if time::Instant::now() > deadline {
                     println!("Timeout");
                     time_out = true;
                     break;
@@ -172,7 +172,7 @@ fn main() -> ! {
             println!();
         }
 
-        let start = time::now();
+        let start = time::Instant::now();
         while start.elapsed() < Duration::from_secs(5) {
             socket.work();
         }

examples/src/bin/wifi_access_point_with_sta.rs

@@ -70,7 +70,7 @@ fn main() -> ! {
         mut controller,
     } = create_ap_sta_network_interface(&init, wifi).unwrap();
 
-    let now = || time::now().duration_since_epoch().as_millis();
+    let now = || time::Instant::now().duration_since_epoch().as_millis();
     let mut ap_socket_set_entries: [SocketStorage; 3] = Default::default();
     let ap_socket_set = SocketSet::new(&mut ap_socket_set_entries[..]);
     let mut ap_stack = Stack::new(ap_interface, ap_device, ap_socket_set, now, rng.random());
@@ -154,7 +154,7 @@ fn main() -> ! {
             println!("Connected");
 
             let mut time_out = false;
-            let deadline = time::now() + Duration::from_secs(20);
+            let deadline = time::Instant::now() + Duration::from_secs(20);
             let mut buffer = [0u8; 1024];
             let mut pos = 0;
             loop {
@@ -173,7 +173,7 @@ fn main() -> ! {
                     break;
                 }
 
-                if time::now() > deadline {
+                if time::Instant::now() > deadline {
                     println!("Timeout");
                     time_out = true;
                     break;
@@ -193,7 +193,7 @@ fn main() -> ! {
                     .unwrap();
                 sta_socket.flush().unwrap();
 
-                let deadline = time::now() + Duration::from_secs(20);
+                let deadline = time::Instant::now() + Duration::from_secs(20);
                 loop {
                     let mut buffer = [0u8; 512];
                     if let Ok(len) = sta_socket.read(&mut buffer) {
@@ -203,7 +203,7 @@ fn main() -> ! {
                         break;
                     }
 
-                    if time::now() > deadline {
+                    if time::Instant::now() > deadline {
                         println!("Timeout");
                         break;
                     }
@@ -219,7 +219,7 @@ fn main() -> ! {
             println!();
         }
 
-        let start = time::now();
+        let start = time::Instant::now();
         while start.elapsed() < Duration::from_secs(5) {
             ap_socket.work();
         }