Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v3.2 or v3.0.

Timer

Because ACRN is a flexible, lightweight reference hypervisor, we provide limited timer management services:

  • Only the LAPIC tsc-deadline timer is supported as the clock source.

  • A timer can only be added on the logical CPU for a process or thread. Timer scheduling or timer migrating is not supported.

How It Works

When the system boots, we check that the hardware supports the LAPIC tsc-deadline timer by checking CPUID.01H:ECX.TSC_Deadline[bit 24]. If support is missing, we output an error message and panic the hypervisor. If supported, we register the timer interrupt callback that raises a timer softirq on each logical CPU and sets the LAPIC timer mode to tsc-deadline timer mode by writing the local APIC LVT register.

Data Structures and APIs

Interfaces Design

void initialize_timer(struct hv_timer *timer, timer_handle_t func, void *priv_data, uint64_t timeout, uint64_t period_in_cycle)

Initialize a timer structure.

Remark

Don’t initialize a timer twice if it has been added to the timer list after calling add_timer. If you want to, delete the timer from the list first.

Parameters
  • timer[in] Pointer to timer.

  • func[in] irq callback if time reached.

  • priv_data[in] func private data.

  • timeout[in] tsc deadline to interrupt.

  • period_in_cycle[in] period of the periodic timer in unit of TSC cycles.

bool timer_expired(const struct hv_timer *timer, uint64_t now, uint64_t *delta)

Check a timer whether expired.

Parameters
  • timer[in] Pointer to timer.

  • now[in] to compare.

  • delta[in] Pointer to return the delta (timeout - now) if timer is not expired.

Return values

true – if the timer is expired, false otherwise.

bool timer_is_started(const struct hv_timer *timer)

Check if a timer is active (in the timer list) or not.

Parameters
  • timer[in] Pointer to timer.

Return values

true – if the timer is in timer list, false otherwise.

int32_t add_timer(struct hv_timer *timer)

Add a timer.

Remark

Don’t call it in the timer callback function or interrupt content.

Parameters
  • timer[in] Pointer to timer.

Return values
  • 0 – on success

  • -EINVAL – timer has an invalid value

void del_timer(struct hv_timer *timer)

Delete a timer.

Remark

Don’t call it in the timer callback function or interrupt content.

Parameters
  • timer[in] Pointer to timer.

void timer_init(void)

Initialize timer.

void calibrate_tsc(void)

Calibrate Time Stamp Counter (TSC) frequency.

Remark

Generic time related routines, e.g., cpu_tickrate(), us_to_ticks(), udelay(), etc., relies on this function being called earlier during system initialization.

uint64_t cpu_ticks(void)

Read current CPU tick count.

Remark

On x86, this is the Time Stamp Counter (TSC) value of the current logical CPU.

Returns

CPU ticks

uint32_t cpu_tickrate(void)

Get CPU tick frequency in KHz.

Remark

On x86, this is the Time Stamp Counter (TSC) frequency of the current logical CPU.

Returns

CPU frequency (KHz)

uint64_t us_to_ticks(uint32_t us)

Convert micro seconds to CPU ticks.

Parameters
  • us[in] micro seconds to convert

Returns

CPU ticks

uint64_t ticks_to_us(uint64_t ticks)

Convert CPU cycles to micro seconds.

Parameters
  • ticks[in] CPU ticks to convert

Returns

microsecond

uint64_t ticks_to_ms(uint64_t ticks)

Convert CPU cycles to milli seconds.

Parameters
  • ticks[in] CPU ticks to convert

Returns

millisecond

void udelay(uint32_t us)

Busy wait a few micro seconds.

Parameters
  • us[in] micro seconds to delay.