SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk::hw::HiResClock Class Reference

High-resolution clock for high-precision measurements. More...

#include <stk_arch.h>

Inheritance diagram for stk::hw::HiResClock:
Collaboration diagram for stk::hw::HiResClock:

Public Member Functions

 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).

Detailed 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.

Constructor & Destructor Documentation

◆ 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.

Member Function Documentation

◆ 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().

Here is the caller graph for this function:

◆ 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().

Here is the caller graph for this function:

◆ 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 {
753 Ticks ticks = 0LL;
754 const uint32_t freq = GetFrequency();
755
756 if (freq != 0U)
757 {
758 const Cycles cycles = GetCycles();
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.
Definition stk_common.h:221
uint64_t Cycles
Cycles value.
Definition stk_common.h:231
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().

Here is the call graph for this function:
Here is the caller graph for this function:

The documentation for this class was generated from the following file: