Steady Clock

Hardware Interface

Defined in namespace hal

#include <libhal/steady_clock.hpp>

class steady_clock

Hardware abstraction interface for a steady clock mechanism.

Implementations of this interface must follow the same requirements as a std::chrono::steady_clock, in that the clock is monotonic & steady. An additional requirement is added to ensure that the clock is reliable. Meaning calls to the interface functions do not return errors because this clock should be infallible. To ensure this, this clock should be driven by the platform’s peripheral drivers or some other mechanism that is unlikely to go offline while the platform is in a normal operating state.

This clock is steady meaning that subsequent calls to get the uptime of this clock cannot decrease as physical time moves forward and the time between ticks of this clock are constant and defined by the clock’s frequency.

This can be used to get the time since the boot up, or to be more accurate, the time when the steady clock object is created. This clock is most suitable for measuring time intervals.

After creation of this clock, the operating frequency shall not change.

Subclassed by hal::cortex_m::dwt_counter, hal::inert_steady_clock, hal::mock::steady_clock, hal::soft::inert_steady_clock

Public Functions

inline hertz frequency()

Get the operating frequency of the steady clock.

Returns:

hertz - operating frequency of the steady clock. Guaranteed to be a positive value by the implementing driver.

inline std::uint64_t uptime()

Get the current value of the steady clock.

Returns:

std::uint64_t - Number of counts that the steady clock has counted since it started.

Utilities

Defined in namespace hal

#include <libhal-util/steady_clock.hpp>

group SteadyClock

Functions

std::uint64_t future_deadline(hal::steady_clock &p_steady_clock, hal::time_duration p_duration)

Function to compute a future timestamp in ticks.

This function calculates a future timestamp based on the current uptime of a steady clock and a specified duration.

Parameters:

• p_steady_clock – - the steady_clock used to calculate the future duration. Note that this future deadline will only work with this steady clock.

• p_duration – The duration for which we need to compute a future timestamp.

Returns:

A 64-bit unsigned integer representing the future timestamp in steady clock ticks. The future timestamp is calculated as the sum of the current number of ticks of the clock and the number of ticks equivalent to the specified duration. If the duration corresponds to a ticks_required value less than or equal to 1, it will be set to 1 to ensure at least one tick is waited.

steady_clock_timeout(hal::steady_clock &p_steady_clock, hal::time_duration p_duration)

Construct a new counter timeout object.

Parameters:

• p_steady_clock – - steady clock implementation

• p_duration – - number of cycles until timeout

steady_clock_timeout(steady_clock_timeout const &p_timeout) = default

Construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

steady_clock_timeout &operator=(steady_clock_timeout const &p_timeout) = default

Assign construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

Returns:

steady_clock_timeout&

steady_clock_timeout(steady_clock_timeout &&p_timeout) = default

Construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

steady_clock_timeout &operator=(steady_clock_timeout &&p_timeout) = default

Move assign construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

Returns:

steady_clock_timeout&

void operator()()

Call this object to check if it has timed out.

Throws:

std::errc::timed_out – - if the timeout time has been exceeded.

steady_clock_timeout create_timeout(hal::steady_clock &p_steady_clock, hal::time_duration p_duration)

Create a timeout object based on hal::steady_clock.

NOTE: Multiple timeout objects can be made from a single steady_clock without influencing other timeout objects.

Parameters:

• p_steady_clock – - hal::steady_clock implementation

• p_duration – - amount of time until timeout

Returns:

hal::steady_clock_timeout - timeout object

void delay(hal::steady_clock &p_steady_clock, hal::time_duration p_duration)

Delay execution for a duration of time using a hardware steady_clock.

Parameters:

• p_steady_clock – - steady_clock driver

• p_duration – - the amount of time to delay for. Zero or negative time duration will delay for one tick of the p_steady_clock.

inline auto timeout_generator(hal::steady_clock &p_steady_clock)

Generates a function that, when passed a duration, returns a timeout.

Parameters:

p_steady_clock – - steady_clock driver that must out live the lifetime of the returned lambda.

Returns:

auto - a callable that returns a new timeout object each time a time duration is passed to it.

class steady_clock_timeout

#include <steady_clock.hpp>

Timeout object based on hal::steady_clock.

Do not use this class directly. Use hal::create_timeout(hal::steady_clock&) instead of instantiating this class directly.

Public Functions

steady_clock_timeout(hal::steady_clock &p_steady_clock, hal::time_duration p_duration)

Construct a new counter timeout object.

Parameters:

• p_steady_clock – - steady clock implementation

• p_duration – - number of cycles until timeout

steady_clock_timeout(steady_clock_timeout const &p_timeout) = default

Construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

steady_clock_timeout &operator=(steady_clock_timeout const &p_timeout) = default

Assign construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

Returns:

steady_clock_timeout&

steady_clock_timeout(steady_clock_timeout &&p_timeout) = default

Construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

steady_clock_timeout &operator=(steady_clock_timeout &&p_timeout) = default

Move assign construct a new counter timeout object.

Parameters:

p_timeout – - other steady_clock_timeout

Returns:

steady_clock_timeout&

void operator()()

Call this object to check if it has timed out.

Throws:

std::errc::timed_out – - if the timeout time has been exceeded.