1.5. time — System time

This module implements wall clock time, date and low overhead microsecond timing functions.

The time_micros*() and time_busy_wait_us() functions are intended for bit banging drivers, requiring precise microsecond timing with very low overhead. The internal microsecond counter wraps around quite frequently, and it’s recommended to only measure very short time periods. The maximum time that can be measured is port specific, and can be read at runtime with time_micros_maximum().

Source code: src/kernel/time.h, src/kernel/time.c

Test code: tst/kernel/time/main.c

Test coverage: src/kernel/time.c

Enums

enum time_compare_t

A comparsion result.

Values:

time_compare_less_than_t = 0
time_compare_equal_t = 1
time_compare_greater_than_t = 2

Functions

int time_get(struct time_t *now_p)

Get current time in seconds and nanoseconds. The resolution of the time is implementation specific and may vary a lot between different architectures.

Return
zero(0) or negative error code.
Parameters
  • now_p: Read current time.

int time_set(struct time_t *new_p)

Set current time in seconds and nanoseconds.

Return
zero(0) or negative error code.
Parameters
  • new_p: New current time.

int time_add(struct time_t *res_p, struct time_t *left_p, struct time_t *right_p)

Add given times.

Return
zero(0) or negative error code.
Parameters
  • res_p: The result of the adding left_p to right_p.
  • left_p: First operand.
  • right_p: Second operand.

int time_subtract(struct time_t *res_p, struct time_t *left_p, struct time_t *right_p)

Subtract given times.

Return
zero(0) or negative error code.
Parameters
  • res_p: The result of the subtrancting left_p from right_p.
  • left_p: The operand to subtract from.
  • right_p: The operand to subtract.

enum time_compare_t time_compare(struct time_t *left_p, struct time_t *right_p)

Compare given times and return their relationship as less than, equal, or greater than.

Return
The result of the comparsion.
Parameters
  • left_p: First time to compare.
  • right_p: Second time to compare.

int time_unix_time_to_date(struct date_t *date_p, struct time_t *time_p)

Convert given unix time to a date.

Return
zero(0) or negative error code or negative error code.
Parameters
  • date_p: Converted time.
  • time_p: Unix time to convert.

void time_busy_wait_us(int microseconds)

Busy wait for given number of microseconds.

This function may be called from interrupt context and with the system lock taken.

NOTE: The maximum allowed time to sleep is target specific.

Return
void
Parameters
  • useconds: Microseconds to busy wait.

int time_micros(void)

Get current time in microseconds. Use time_micros_resolution() and time_micros_maximum() to get its properties, and time_micros_elapsed() to calculate the elapsed time between two times.

This function may be called from interrupt context and with the system lock taken.

Return
Current time in microseconds.

int time_micros_elapsed(int start, int stop)

Calculate the elapsed time from start to stop. The caller must ensure that the micro timer has not wrapped more than once for this calculation to work.

This function may be called from interrupt context and with the system lock taken.

Return
The elapsed time from start to stop.

int time_micros_resolution(void)

Get micros resolution in microseconds, rounded up.

This function may be called from interrupt context and with the system lock taken.

Return
Resolution in microseconds or negative error code.

int time_micros_maximum(void)

Get micros maximum value plus one, often the system tick period.

This function may be called from interrupt context and with the system lock taken.

Return
Maximum value plus one in microseconds or negative error code. Returns -ENOSYS if the the micro functionality is unimplemented on this board.

struct time_t
#include <time.h>

A time in seconds and nanoseconds. seconds and nanoseconds shall be added to get the time.

Public Members

int32_t seconds

Number of seconds.

int32_t nanoseconds

Number of nanoseconds.

struct date_t
#include <time.h>

A date in year, month, date, day, hour, minute and seconds.

Public Members

int second

Second [0..59].

int minute

Minute [0..59].

int hour

Hour [0..23].

int day

Weekday [1..7], where 1 is Monday and 7 is Sunday.

int date

Day in month [1..31]

int month

Month [1..12] where 1 is January and 12 is December.

int year

Year [1970..].