High-resolution clock for high-precision measurements.
More...
#include <stk_arch.h>
|
| | HiResClock () |
| | Construct a clock instance.
|
| Cycles | GetCycles () |
| | Get number of clock cycles elapsed since the time origin (see the class description).
|
| uint32_t | GetFrequency () const |
| | Get clock frequency.
|
| Ticks | GetTimeUs () |
| | Get elapsed time in microseconds since the time origin (see the class description).
|
High-resolution clock for high-precision measurements.
- Note
- Instance-based: every caller (task, ISR, ...) owns its own instance, so there is no shared driver state and no need for a critical section.
-
Time origin is architecture-specific. Only the ARM Cortex-M3+ implementation measures from the moment of construction of the instance. The other back-ends are stateless and count from a global origin, so the absolute value must not be relied upon, only the difference of two GetCycles()/GetTimeUs() readings is portable:
- ARM Cortex-M3+: the moment of construction (DWT cycle counter, 64-bit accumulator).
- ARM Cortex-M0/M0+: the kernel start (kernel tick count + SysTick), requires an initialized kernel.
- RISC-V: the origin of the hardware counter, i.e.
mtime (reference clock) or, if STK_SUBMICORSECOND_PRECISION_TIMER is enabled, mcycle (CPU clock).
- x86-Win32: the first use of the clock (shared QueryPerformanceCounter origin, also used by the system timer).
-
The unit of the
Cycles value is the unit of the underlying counter: CPU cycles on ARM, CPU cycles or mtime reference ticks on RISC-V (see above), QueryPerformanceCounter ticks on x86-Win32. Always convert with GetFrequency() or use GetTimeUs().
-
A single instance is not re-entrant: do not share one instance between tasks or between a task and an ISR, create one per context instead.
-
On ARM Cortex-M3+ (32-bit DWT counter) an instance must be polled at least once per 2^32 CPU cycles, otherwise a counter wrap is missed. The constructor enables the DWT cycle counter if it is not already running (a running counter is not reset). Without a DWT peripheral (
DWT is not defined by the device header) the counter reads as 0.
- Warning
- Using hw::HiResClock directly requires a Privileged/Secure context. On TrustZone targets, Non-Secure/unprivileged callers must go through the NSC (Non-Secure Callable) gateway functions (
NSC_stk_hw_HiResClock_Init, NSC_stk_hw_HiResClock_GetFrequency, NSC_stk_hw_HiResClock_GetCycles) provided by the ARM Cortex-M back-end instead of calling this class directly. NSC_stk_hw_HiResClock_Init and NSC_stk_hw_HiResClock_GetCycles operate on an instance located in Non-Secure memory (the pointer is validated against the caller's access rights); NSC_stk_hw_HiResClock_GetFrequency takes no instance, the frequency does not depend on instance state.
Definition at line 721 of file stk_arch.h.
◆ HiResClock()
| stk::hw::HiResClock::HiResClock |
( |
| ) |
|
|
explicit |
Construct a clock instance.
- Note
- On ARM Cortex-M3+ the time origin is the moment of construction, on other back-ends it is a global origin, see the class description.
◆ GetCycles()
| Cycles stk::hw::HiResClock::GetCycles |
( |
| ) |
|
Get number of clock cycles elapsed since the time origin (see the class description).
- Note
- ISR-safe (for an instance not used by any other context).
-
Use the difference of two readings for an interval; the absolute value is portable only on ARM Cortex-M3+.
- Returns
- Counter cycles, convert to time using GetFrequency().
Referenced by GetTimeUs(), and stk_hires_cycles().
◆ GetFrequency()
| uint32_t stk::hw::HiResClock::GetFrequency |
( |
| ) |
const |
Get clock frequency.
- Note
- ISR-safe.
- Returns
- Frequency in Hz of the counter behind GetCycles() (CPU clock on ARM;
mtime reference clock or CPU clock on RISC-V; QueryPerformanceCounter frequency on x86-Win32).
Referenced by GetTimeUs(), and stk_hires_frequency().
◆ GetTimeUs()
| Ticks stk::hw::HiResClock::GetTimeUs |
( |
| ) |
|
|
inline |
Get elapsed time in microseconds since the time origin (see the class description).
- Note
- ISR-safe (for an instance not used by any other context).
-
Use the difference of two readings for an interval; the absolute value is portable only on ARM Cortex-M3+.
- Returns
- Microseconds.
Definition at line 751 of file stk_arch.h.
752 {
755
756 if (freq != 0U)
757 {
759 const Cycles ticksu = (cycles * 1000000ULL) /
static_cast<Cycles>(freq);
760
761 ticks =
static_cast<Ticks>(ticksu);
762 }
763
764 return ticks;
765 }
int64_t Ticks
Ticks value.
uint64_t Cycles
Cycles value.
uint32_t GetFrequency() const
Get clock frequency.
Cycles GetCycles()
Get number of clock cycles elapsed since the time origin (see the class description).
References __stk_forceinline, GetCycles(), and GetFrequency().
Referenced by stk_hires_time_us().
The documentation for this class was generated from the following file: