Expand description
Timekeeping using the SysTick Timer.
Note: this entire module is only available if the systick feature is
present; it is on by default.
The OS uses the Cortex-M SysTick Timer to maintain a monotonic counter
recording the number of milliseconds (“ticks”) since boot. This module
provides ways to read that timer, and also to arrange for tasks to be woken
at specific times (such as sleep_until and sleep_for).
To use this facility in an application, you need to call
initialize_sys_tick to inform the OS of the system clock speed.
Otherwise, no operations in this module will work properly.
You can get the value of tick counter using TickTime::now.
§Types for describing time
This module uses three main types for describing time, in slightly different roles.
TickTime represents a specific point in time, measured as a number of
ticks since boot (or, really, since the executor was started). It’s a
64-bit count of milliseconds, which means it overflows every 584 million
years. This lets us ignore overflows in timestamps, making everything
simpler. TickTime is analogous to std::time::Instant from the Rust
standard library.
Millis represents a relative time interval in milliseconds. This uses the
same representation as TickTime, so adding them together is cheap.
core::time::Duration is similar to Millis but with a lot more bells and
whistles. It’s the type used to measure time intervals in the Rust standard
library. It can be used with most time-related API in the OS, but you might
not want to do so on a smaller CPU: Duration uses a mixed-number-base
format internally that means almost all operations require a 64-bit multiply
or divide. On machines lacking such instructions, this can become quite
costly (in terms of both program size and time required).
Cases where the OS won’t accept Duration are mostly around things like
sleeps, where the operation will always be performed in units of whole
ticks, so being able to pass (say) nanoseconds is misleading.
§Imposing a timeout on an operation
If you want to stop a concurrent process if it’s not done by a certain time,
see the with_deadline function (and its relative friend,
with_timeout). These let you impose a deadline on any future, such that
if it hasn’t resolved by a certain time, it will be dropped (cancelled).
§Fixing “lost ticks”
If the longest sequence in your application between any two await points
takes less than a millisecond, the standard timer configuration will work
fine and keep reliable time.
However, if you sometimes need to do more work than that – or if you’re
concerned you might do so by accident due to a bug – the systick IRQ can be
configured to preempt task code. The OS is designed to handle this safely.
For more information, see
run_tasks_with_preemption.
§Getting higher precision
For many applications, milliseconds are a fine unit of time, but sometimes
you need something more precise. Currently, the easiest way to do this is to
enlist a different hardware timer. The time module has no special
privileges that you can’t make use of, and adding your own alternate
timekeeping module is explictly supported in the design (this is why the
"systick" feature exists).
This can also be useful on processors like the Nordic nRF52 series, where the best sleep mode to use when idling the CPU also stops the systick timer. On platforms like that, the systick isn’t useful as a monotonic clock, and you’ll want to use some other vendor-specific timer.
Currently there’s no example of how to do this in the repo. If you need this, please file an issue.
Structs§
- A period of time measured in milliseconds.
- Helper for doing something periodically, accurately.
- Represents a moment in time by the value of the system tick counter. System-specific analog of
std::time::Instant.
Functions§
- Sets up the tick counter for 1kHz operation, assuming a CPU core clock of
clock_hz. - Sleeps until the system time has increased by
d. - Sleeps until the system time is equal to or greater than
deadline. - Alters a future to impose a deadline on its completion.
- Alters a future to impose a timeout on its completion.