Module time

Time types designed for Zephyr, inspired by std::time.

In std, there are two primary time types: Duration, representing a span of time, and Instant, representing a specific point in time. Both have nanosecond precision, which is well-suited to more powerful machines. However, on embedded systems like Zephyr, this precision can lead to performance issues, often requiring divisions whenever timeouts are used.

In the Rust embedded ecosystem, the fugit crate is commonly used for handling time. It provides both Duration and Instant types, but with parameters that allow the representation to match the time slice used, enabling compile-time conversion and storing time directly as tick counts.

Zephyr manages time in terms of system tick intervals, derived from sys_clock_hw_cycles_per_sec(). This model aligns well with fugit, especially when the types are properly parameterized.

It’s important to note that Rust’s std::Instant requires time to be monotonically increasing.

Zephyr’s sys/time_units.h provides a variety of optimized macros for manipulating time values, converting between human-readable units and ticks, and minimizing divisions (especially by non-constant values). Similarly, the fugit crate offers constructors that aim to result in constants when possible, avoiding costly division operations.

Structs

• Forever
  A sleep that waits forever. This is its own type, that is Into<Timeout> and can be used anywhere a timeout is needed.
• NoWait
  A sleep that doesn’t ever wait. This is its own type, that is Info<Timeout> and can be used anywhere a timeout is needed.
• Timeout
  Wrapper around the timeout type, so we can implement From/Info.

Constants

• SYS_FREQUENCY
  The system time base. The system clock has this many ticks per second.

Functions

• sleep
  Put the current thread to sleep, for the given duration. Uses k_sleep for the actual sleep. Returns a duration roughly representing the remaining amount of time if the sleep was woken.

Type Aliases

• Duration
  Duration appropriate for Zephyr calls that expect k_timeout_t. The result will be a time interval from “now” (when the call is made).
• Instant
  An Instant appropriate for Zephyr calls that expect a k_timeout_t. The result will be an absolute time in terms of system ticks.
• Tick
  Zephyr can be configured for either 64-bit or 32-bit time values. Use the appropriate type internally to match. This should end up the same size as k_ticks_t, but unsigned instead of signed.