Implement a high precision gettime based on tsc

services/comps/time/src/clocksource.rs

@@ -0,0 +1,218 @@
+//! This module provides abstractions for hardware-assisted timing mechanisms, encapsulated by the `ClockSource` struct.
+//! A `ClockSource` can be constructed from any counter with a stable frequency, enabling precise time measurements to be taken
+//! by retrieving instances of `Instant`.
+//!
+//! The `ClockSource` module is a fundamental building block for timing in systems that require high precision and accuracy.
+//! It can be integrated into larger systems to provide timing capabilities, or used standalone for time tracking and elapsed time measurements.
+
+use alloc::sync::Arc;
+use core::{cmp::max, ops::Add, time::Duration};
+use jinux_frame::sync::SpinLock;
+use jinux_util::coeff::Coeff;
+
+use crate::NANOS_PER_SECOND;
+
+/// `ClockSource` is an abstraction for hardware-assisted timing mechanisms.
+/// A `ClockSource` can be created based on any counter that operates at a stable frequency.
+/// Users are able to measure time by retrieving `Instant` from this source.
+///
+/// # Implementation
+/// The `ClockSource` relies on obtaining the frequency of the counter and the method for reading the cycles in order to measure time.
+/// The **cycles** here refer the counts of the base time counter.
+/// Additionally, the `ClockSource` also holds a last recorded instant, which acts as a reference point for subsequent time retrieval.
+/// To prevent numerical overflow during the calculation of `Instant`, this last recorded instant **must be periodically refreshed**.
+/// The maximum interval for these updates must be determined at the time of the `ClockSource` initialization.
+///
+/// # Examples
+/// Suppose we have a counter called `counter` which have the frequency `counter.freq`, and the method to read its cycles called `read_counter()`.
+/// We can create a corresponding `ClockSource` and use it as follows:
+///
+/// ```rust
+/// // here we set the max_delay_secs = 10
+/// let max_delay_secs = 10;
+/// // create a clocksource named counter_clock
+/// let counter_clock = ClockSource::new(counter.freq, max_delay_secs, Arc::new(read_counter));
+/// // read an instant.
+/// let instant = counter_clock.read_instant();
+/// ```
+///
+/// If using this `ClockSource`, you must ensure its internal instant will be updated
+/// at least once within a time interval of not more than `max_delay_secs.
+pub struct ClockSource {
+    read_cycles: Arc<dyn Fn() -> u64 + Sync + Send>,
+    base: ClockSourceBase,
+    coeff: Coeff,
+    last_instant: SpinLock<Instant>,
+    last_cycles: SpinLock<u64>,
+}
+
+impl ClockSource {
+    /// Create a new `ClockSource` instance.
+    /// Require basic information of based time counter, including the function for reading cycles, the frequency
+    /// and the maximum delay seconds to update this `ClockSource`.
+    /// The `ClockSource` also calculates a reliable `Coeff` based on the counter's frequency and the maximum delay seconds.
+    /// This `Coeff` is used to convert the number of cycles into the duration of time that has passed for those cycles.
+    pub fn new(
+        freq: u64,
+        max_delay_secs: u64,
+        read_cycles: Arc<dyn Fn() -> u64 + Sync + Send>,
+    ) -> Self {
+        let base = ClockSourceBase::new(freq, max_delay_secs);
+        // Too big `max_delay_secs` will lead to a low resolution Coeff.
+        debug_assert!(max_delay_secs < 600);
+        let coeff = Coeff::new(NANOS_PER_SECOND as u64, freq, max_delay_secs * freq);
+        Self {
+            read_cycles,
+            base,
+            coeff,
+            last_instant: SpinLock::new(Instant::zero()),
+            last_cycles: SpinLock::new(0),
+        }
+    }
+
+    fn cycles_to_nanos(&self, cycles: u64) -> u64 {
+        self.coeff * cycles
+    }
+
+    /// Use the instant cycles to calculate the instant.
+    /// It first calculates the difference between the instant cycles and the last recorded cycles stored in the clocksource.
+    /// Then `ClockSource` will convert the passed cycles into passed time and calculate the current instant.
+    fn calculate_instant(&self, instant_cycles: u64) -> Instant {
+        let delta_nanos = {
+            let delta_cycles = instant_cycles - self.last_cycles();
+            self.cycles_to_nanos(delta_cycles)
+        };
+        let duration = Duration::from_nanos(delta_nanos);
+        self.last_instant() + duration
+    }
+
+    /// Use an input instant to update the internal instant in the `ClockSource`.
+    fn update_last_instant(&self, instant: &Instant) {
+        *self.last_instant.lock() = *instant;
+    }
+
+    /// Use an input cycles to update the internal instant in the `ClockSource`.
+    fn update_last_cycles(&self, cycles: u64) {
+        *self.last_cycles.lock() = cycles;
+    }
+
+    /// read current cycles of the `ClockSource`.
+    pub fn read_cycles(&self) -> u64 {
+        (self.read_cycles)()
+    }
+
+    /// Return the last instant recorded in the `ClockSource`.
+    pub fn last_instant(&self) -> Instant {
+        return *self.last_instant.lock();
+    }
+
+    /// Return the last cycles recorded in the `ClockSource`.
+    pub fn last_cycles(&self) -> u64 {
+        return *self.last_cycles.lock();
+    }
+
+    /// Return the maximum delay seconds for updating of the `ClockSource`.
+    pub fn max_delay_secs(&self) -> u64 {
+        self.base.max_delay_secs()
+    }
+
+    /// Return the reference to the generated cycles coeff of the `ClockSource`.
+    pub fn coeff(&self) -> &Coeff {
+        &self.coeff
+    }
+
+    /// Return the frequency of the counter used in the `ClockSource`.
+    pub fn freq(&self) -> u64 {
+        self.base.freq()
+    }
+
+    /// Calibrate the recorded `Instant` to zero, and record the instant cycles.
+    pub(crate) fn calibrate(&self, instant_cycles: u64) {
+        self.update_last_cycles(instant_cycles);
+        self.update_last_instant(&Instant::zero());
+    }
+
+    /// Get the instant to update the internal instant in the `ClockSource`.
+    pub(crate) fn update(&self) {
+        let instant_cycles = self.read_cycles();
+        let instant = self.calculate_instant(instant_cycles);
+        self.update_last_cycles(instant_cycles);
+        self.update_last_instant(&instant);
+    }
+
+    /// Read the instant corresponding to the current time.
+    /// When trying to read an instant from the clocksource, it will use the reading method to read instant cycles.
+    /// Then leverage it to calculate the instant.
+    pub(crate) fn read_instant(&self) -> Instant {
+        let instant_cycles = self.read_cycles();
+        self.calculate_instant(instant_cycles)
+    }
+}
+
+/// `Instant` captures a specific moment, storing the duration of time
+/// elapsed since a reference point (typically the system boot time).
+/// The `Instant` is expressed in seconds and the fractional part is expressed in nanoseconds.
+#[derive(Debug, Default, Copy, Clone)]
+pub struct Instant {
+    secs: u64,
+    nanos: u32,
+}
+
+impl Instant {
+    pub const fn zero() -> Self {
+        Self { secs: 0, nanos: 0 }
+    }
+
+    pub fn new(secs: u64, nanos: u32) -> Self {
+        Self { secs, nanos }
+    }
+
+    /// Return the seconds recorded in the Instant.
+    pub fn secs(&self) -> u64 {
+        self.secs
+    }
+
+    /// Return the nanoseconds recorded in the Instant.
+    pub fn nanos(&self) -> u32 {
+        self.nanos
+    }
+}
+
+impl Add<Duration> for Instant {
+    type Output = Instant;
+
+    fn add(self, other: Duration) -> Self::Output {
+        let mut secs = self.secs + other.as_secs();
+        let mut nanos = self.nanos + other.subsec_nanos();
+        if nanos >= NANOS_PER_SECOND {
+            secs += 1;
+            nanos -= NANOS_PER_SECOND;
+        }
+        Instant::new(secs, nanos)
+    }
+}
+
+/// The basic properties of `ClockSource`.
+#[derive(Debug, Copy, Clone)]
+struct ClockSourceBase {
+    freq: u64,
+    max_delay_secs: u64,
+}
+
+impl ClockSourceBase {
+    fn new(freq: u64, max_delay_secs: u64) -> Self {
+        let max_delay_secs = max(2, max_delay_secs);
+        ClockSourceBase {
+            freq,
+            max_delay_secs,
+        }
+    }
+
+    fn max_delay_secs(&self) -> u64 {
+        self.max_delay_secs
+    }
+
+    fn freq(&self) -> u64 {
+        self.freq
+    }
+}