On this page

Time Functions

(warning)

Microvisor Public Beta

Microvisor is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until Microvisor's General Availability (GA) release.

Microvisor system calls include the following functions for application timekeeping operations:

Return values and errors

All of the functions described below return a 32-bit integer that is one of the values from the standard Microvisor enumeration MvStatus. All possible error values for a given system call are provided with each function's description.

Success is always signaled by a return value of zero (MV_STATUS_OKAY).

mvGetMicroseconds()

Gets the current value of Microvisor's free-running microsecond clock

Declaration

extern enum MvStatus mvGetMicroseconds(uint64_t *usec);

Parameters

Parameter	Description
`usec`	A pointer to non-secure memory into which the microsecond counter value will be written by Microvisor

Possible errors

Error Value	Description
`MV_STATUS_PARAMETERFAULT`	`usec` does not reference memory accessible to the application

Description

Microvisor's microsecond clock starts from zero when Microvisor is run, and counts up from then on. It has no relation to — and may drift with respect to — wall time.

Example

1// Tick counters
2uint64_t last_tick = 0;
3uint64_t tick = 0;
4
5while (true) {
6  enum MvStatus status = mvGetMicroseconds(&tick);
7    if (status == MV_STATUS_OKAY && tick - last_tick > LED_FLASH_PERIOD_US) {
8    // Toggle the USER LED's GPIO pin every LED_FLASH_PERIOD_US microseconds
9    HAL_GPIO_TogglePin(LED_GPIO_BANK, LED_GPIO_PIN);
10    last_tick = tick;
11  }
12}

mvGetWallTime()

Gets the current time in non-leap microseconds since the Unix epoch

Declaration

extern enum MvStatus mvGetWallTime(uint64_t *usec);

Parameters

Parameter	Description
`usec`	A pointer to non-secure memory into which the microsecond wall time will be written by Microvisor

Possible errors

Error Value	Description
`MV_STATUS_PARAMETERFAULT`	`usec` does not reference memory accessible to the application
`MV_STATUS_TIMENOTSET`	The device's RTC has not yet been set from the server

Description

This will return MV_STATUS_TIMENOTSET on restart until the real-time clock (RTC) is synchronized with the server. Clock synchronization takes place periodically during application lifecycle: for example, it is updated regularly while the device is connected, and again when the device connects or re-connects. The value written into usec may therefore jump forward or backward in response to an updated time from the server.

Example

This example, which modifies a section of the FreeRTOS demo code logging.c file's _write() function, shows how to use the 64-bit wall clock time to feed the standard gmtime() and strftime() functions (defined in <time.h>) to create a timestamp string to prefix any output sent to printf(). The code uses the same source to include the millisecond time:

12022-05-10 13:40:57.489 [DEBUG] Temperature: 25.31
22022-05-10 13:40:57.490 [DEBUG] Network handle: 321452355
32022-05-10 13:40:57.491 [DEBUG] HTTP channel handle: 1702803732
42022-05-10 13:40:57.492 [DEBUG] Sending HTTP request
52022-05-10 13:40:58.023 [ERROR] HTTP status code: 429
62022-05-10 13:40:58.024 [DEBUG] HTTP channel closed

Here is the code:

1// Prepare and add a timestamp to log output if we can.
2// If we can't, we show no time
3char timestamp[64] = {0};
4uint64_t usec = 0;
5enum MvStatus status = mvGetWallTime(&usec);
6if (status == MV_STATUS_OKAY) {
7  // Get the second and millisecond times
8  time_t sec = (time_t)usec / 1000000;
9  time_t msec = (time_t)usec / 1000;
10
11  // Write time string as "2022-05-10 13:30:58.XXX "
12  strftime(timestamp, 64, "%F %T.XXX ", gmtime(&sec));
13
14  // Insert the millisecond time over the XXX
15  sprintf(&timestamp[20], "%03u ", (unsigned)(msec % 1000));
16}
17
18// Write out the time string. Confirm that Microvisor
19// has accepted the request to write data to the channel.
20uint32_t time_chars = 0;
21size_t len = strlen(timestamp);
22if (len > 0) {
23  status = mvWriteChannelStream(log_handles.channel, (const uint8_t*)timestamp, len, &time_chars);
24  if (status != MV_STATUS_OKAY) {
25    errno = EIO;
26    return -1;
27  }
28}
29
30// Write out the message string. Confirm that Microvisor
31// has accepted the request to write data to the channel.
32uint32_t msg_chars = 0;
33status = mvWriteChannelStream(log_handles.channel, (const uint8_t*)ptr, length, &msg_chars);
34if (status == MV_STATUS_OKAY) {
35  // Return the number of characters written to the channel
36  return time_chars + msg_chars;
37} else {
38  errno = EIO;
39  return -1;
40}