timer header

The documentation of QEMU’s qemu/timer.h header.

QEMU_TIMER_ATTR_EXTERNAL()

Parameters

Description

An individual timer may be given one or multiple attributes when initialized. Each attribute corresponds to one bit. Attributes modify the processing of timers when they fire.

The following attributes are available:

QEMU_TIMER_ATTR_EXTERNAL: drives external subsystem QEMU_TIMER_ATTR_ALL: mask for all existing attributes

Timers with this attribute do not recorded in rr mode, therefore it could be used for the subsystems that operate outside the guest core. Applicable only with virtual clock type.

int64_t qemu_clock_get_ms(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Get the millisecond value of a clock with type type

Return

the clock value in milliseconds

int64_t qemu_clock_get_us(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Get the microsecond value of a clock with type type

Return

the clock value in microseconds

bool qemu_clock_has_timers(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Determines whether a clock’s default timer list has timers attached

Note that this function should not be used when other threads also access the timer list. The return value may be outdated by the time it is acted upon.

Return

true if the clock’s default timer list has timers attached

bool qemu_clock_expired(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Determines whether a clock’s default timer list has an expired timer.

Return

true if the clock’s default timer list has an expired timer

bool qemu_clock_use_for_deadline(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Determine whether a clock should be used for deadline calculations. Some clocks, for instance vm_clock with use_icount set, do not count in nanoseconds. Such clocks are not used for deadline calculations, and are presumed to interrupt any poll using qemu_notify/aio_notify etc.

Return

true if the clock runs in nanoseconds and should be used for a deadline.

int64_t qemu_clock_deadline_ns_all(QEMUClockType type, int attr_mask)

Parameters

QEMUClockType type

the clock type

int attr_mask

mask for the timer attributes that are included in deadline calculation

Description

Calculate the deadline across all timer lists associated with a clock (as opposed to just the default one) in nanoseconds, or -1 if no timer is set to expire.

Return

time until expiry in nanoseconds or -1

QEMUTimerList * qemu_clock_get_main_loop_timerlist(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Return the default timer list associated with a clock.

Return

the default timer list

void qemu_clock_notify(QEMUClockType type)

Parameters

QEMUClockType type

the clock type

Description

Call the notifier callback connected with the default timer list linked to the clock, or qemu_notify() if none.

void qemu_clock_enable(QEMUClockType type, bool enabled)

Parameters

QEMUClockType type

the clock type

bool enabled

true to enable, false to disable

Description

Enable or disable a clock Disabling the clock will wait for related timerlists to stop executing qemu_run_timers. Thus, this functions should not be used from the callback of a timer that is based on clock. Doing so would cause a deadlock.

Caller should hold BQL.

void qemu_start_warp_timer(void)

Parameters

void

no arguments

Description

Starts a timer for virtual clock update

bool qemu_clock_run_timers(QEMUClockType type)

Parameters

QEMUClockType type

clock on which to operate

Description

Run all the timers associated with the default timer list of a clock.

Return

true if any timer ran.

bool qemu_clock_run_all_timers(void)

Parameters

void

no arguments

Description

Run all the timers associated with the default timer list of every clock.

Return

true if any timer ran.

QEMUTimerList * timerlist_new(QEMUClockType type, QEMUTimerListNotifyCB * cb, void * opaque)

Parameters

QEMUClockType type

the clock type to associate with the timerlist

QEMUTimerListNotifyCB * cb

the callback to call on notification

void * opaque

the opaque pointer to pass to the callback

Description

Create a new timerlist associated with the clock of type type.

Return

a pointer to the QEMUTimerList created

void timerlist_free(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to free

Description

Frees a timer_list. It must have no active timers.

bool timerlist_has_timers(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to operate on

Description

Determine whether a timer list has active timers

Note that this function should not be used when other threads also access the timer list. The return value may be outdated by the time it is acted upon.

Return

true if the timer list has timers.

bool timerlist_expired(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to operate on

Description

Determine whether a timer list has any timers which are expired.

Return

true if the timer list has timers which have expired.

int64_t timerlist_deadline_ns(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to operate on

Description

Determine the deadline for a timer_list, i.e. the number of nanoseconds until the first timer expires. Return -1 if there are no timers.

Return

the number of nanoseconds until the earliest timer expires -1 if none

QEMUClockType timerlist_get_clock(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to operate on

Description

Determine the clock type associated with a timer list.

Return

the clock type associated with the timer list.

bool timerlist_run_timers(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to use

Description

Call all expired timers associated with the timer list.

Return

true if any timer expired

void timerlist_notify(QEMUTimerList * timer_list)

Parameters

QEMUTimerList * timer_list

the timer list to use

Description

call the notifier callback associated with the timer list.

void timerlistgroup_init(QEMUTimerListGroup * tlg, QEMUTimerListNotifyCB * cb, void * opaque)

Parameters

QEMUTimerListGroup * tlg

the timer list group

QEMUTimerListNotifyCB * cb

the callback to call when a notify is required

void * opaque

the opaque pointer to be passed to the callback.

Description

Initialise a timer list group. This must already be allocated in memory and zeroed. The notifier callback is called whenever a clock in the timer list group is reenabled or whenever a timer associated with any timer list is modified. If cb is specified as null, qemu_notify() is used instead.

void timerlistgroup_deinit(QEMUTimerListGroup * tlg)

Parameters

QEMUTimerListGroup * tlg

the timer list group

Description

Deinitialise a timer list group. This must already be initialised. Note the memory is not freed.

bool timerlistgroup_run_timers(QEMUTimerListGroup * tlg)

Parameters

QEMUTimerListGroup * tlg

the timer list group

Description

Run the timers associated with a timer list group. This will run timers on multiple clocks.

Return

true if any timer callback ran

int64_t timerlistgroup_deadline_ns(QEMUTimerListGroup * tlg)

Parameters

QEMUTimerListGroup * tlg

the timer list group

Description

Determine the deadline of the soonest timer to expire associated with any timer list linked to the timer list group. Only clocks suitable for deadline calculation are included.

Return

the deadline in nanoseconds or -1 if no timers are to expire.

void timer_init_full(QEMUTimer * ts, QEMUTimerListGroup * timer_list_group, QEMUClockType type, int scale, int attributes, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimer * ts

the timer to be initialised

QEMUTimerListGroup * timer_list_group

(optional) the timer list group to attach the timer to

QEMUClockType type

the clock type to use

int scale

the scale value for the timer

int attributes

0, or one or more OR’ed QEMU_TIMER_ATTR_<id> values

QEMUTimerCB * cb

the callback to be called when the timer expires

void * opaque

the opaque pointer to be passed to the callback

Description

Initialise a timer with the given scale and attributes, and associate it with timer list for given clock type in timer_list_group (or default timer list group, if NULL). The caller is responsible for allocating the memory.

You need not call an explicit deinit call. Simply make sure it is not on a list with timer_del.

void timer_init(QEMUTimer * ts, QEMUClockType type, int scale, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimer * ts

the timer to be initialised

QEMUClockType type

the clock to associate with the timer

int scale

the scale value for the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Initialize a timer with the given scale on the default timer list associated with the clock. See timer_init_full for details.

void timer_init_ns(QEMUTimer * ts, QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimer * ts

the timer to be initialised

QEMUClockType type

the clock to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Initialize a timer with nanosecond scale on the default timer list associated with the clock. See timer_init_full for details.

void timer_init_us(QEMUTimer * ts, QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimer * ts

the timer to be initialised

QEMUClockType type

the clock to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Initialize a timer with microsecond scale on the default timer list associated with the clock. See timer_init_full for details.

void timer_init_ms(QEMUTimer * ts, QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimer * ts

the timer to be initialised

QEMUClockType type

the clock to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Initialize a timer with millisecond scale on the default timer list associated with the clock. See timer_init_full for details.

QEMUTimer * timer_new_full(QEMUTimerListGroup * timer_list_group, QEMUClockType type, int scale, int attributes, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUTimerListGroup * timer_list_group

(optional) the timer list group to attach the timer to

QEMUClockType type

the clock type to use

int scale

the scale value for the timer

int attributes

0, or one or more OR’ed QEMU_TIMER_ATTR_<id> values

QEMUTimerCB * cb

the callback to be called when the timer expires

void * opaque

the opaque pointer to be passed to the callback

Description

Create a new timer with the given scale and attributes, and associate it with timer list for given clock type in timer_list_group (or default timer list group, if NULL). The memory is allocated by the function.

This is not the preferred interface unless you know you are going to call timer_free. Use timer_init or timer_init_full instead.

The default timer list has one special feature: in icount mode, QEMU_CLOCK_VIRTUAL timers are run in the vCPU thread. This is not true of other timer lists, which are typically associated with an AioContext—each of them runs its timer callbacks in its own AioContext thread.

Return

a pointer to the timer

QEMUTimer * timer_new(QEMUClockType type, int scale, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUClockType type

the clock type to use

int scale

the scale value for the timer

QEMUTimerCB * cb

the callback to be called when the timer expires

void * opaque

the opaque pointer to be passed to the callback

Description

Create a new timer with the given scale, and associate it with the default timer list for the clock type type. See timer_new_full for details.

Return

a pointer to the timer

QEMUTimer * timer_new_ns(QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUClockType type

the clock type to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Create a new timer with nanosecond scale on the default timer list associated with the clock. See timer_new_full for details.

Return

a pointer to the newly created timer

QEMUTimer * timer_new_us(QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUClockType type

the clock type to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Create a new timer with microsecond scale on the default timer list associated with the clock. See timer_new_full for details.

Return

a pointer to the newly created timer

QEMUTimer * timer_new_ms(QEMUClockType type, QEMUTimerCB * cb, void * opaque)

Parameters

QEMUClockType type

the clock type to associate with the timer

QEMUTimerCB * cb

the callback to call when the timer expires

void * opaque

the opaque pointer to pass to the callback

Description

Create a new timer with millisecond scale on the default timer list associated with the clock. See timer_new_full for details.

Return

a pointer to the newly created timer

void timer_deinit(QEMUTimer * ts)

Parameters

QEMUTimer * ts

the timer to be de-initialised

Description

Deassociate the timer from any timerlist. You should call timer_del before. After this call, any further timer_del call cannot cause dangling pointer accesses even if the previously used timerlist is freed.

void timer_free(QEMUTimer * ts)

Parameters

QEMUTimer * ts

the timer

Description

Free a timer (it must not be on the active list)

void timer_del(QEMUTimer * ts)

Parameters

QEMUTimer * ts

the timer

Description

Delete a timer from the active list.

This function is thread-safe but the timer and its timer list must not be freed while this function is running.

void timer_mod_ns(QEMUTimer * ts, int64_t expire_time)

Parameters

QEMUTimer * ts

the timer

int64_t expire_time

the expiry time in nanoseconds

Description

Modify a timer to expire at expire_time

This function is thread-safe but the timer and its timer list must not be freed while this function is running.

void timer_mod_anticipate_ns(QEMUTimer * ts, int64_t expire_time)

Parameters

QEMUTimer * ts

the timer

int64_t expire_time

the expiry time in nanoseconds

Description

Modify a timer to expire at expire_time or the current time, whichever comes earlier.

This function is thread-safe but the timer and its timer list must not be freed while this function is running.

void timer_mod(QEMUTimer * ts, int64_t expire_timer)

Parameters

QEMUTimer * ts

the timer

int64_t expire_timer

undescribed

Description

Modify a timer to expiry at expire_time, taking into account the scale associated with the timer.

This function is thread-safe but the timer and its timer list must not be freed while this function is running.

void timer_mod_anticipate(QEMUTimer * ts, int64_t expire_time)

Parameters

QEMUTimer * ts

the timer

int64_t expire_time

the expiry time in nanoseconds

Description

Modify a timer to expire at expire_time or the current time, whichever comes earlier, taking into account the scale associated with the timer.

This function is thread-safe but the timer and its timer list must not be freed while this function is running.

bool timer_pending(QEMUTimer * ts)

Parameters

QEMUTimer * ts

the timer

Description

Determines whether a timer is pending (i.e. is on the active list of timers, whether or not it has not yet expired).

Return

true if the timer is pending

bool timer_expired(QEMUTimer * timer_head, int64_t current_time)

Parameters

QEMUTimer * timer_head

undescribed

int64_t current_time

the current time

Description

Determines whether a timer has expired.

Return

true if the timer has expired

uint64_t timer_expire_time_ns(QEMUTimer * ts)

Parameters

QEMUTimer * ts

the timer

Description

Determine the expiry time of a timer

Return

the expiry time in nanoseconds

void timer_get(QEMUFile * f, QEMUTimer * ts)

Parameters

QEMUFile * f

the file

QEMUTimer * ts

the timer

Description

Read a timer ts from a file f

void timer_put(QEMUFile * f, QEMUTimer * ts)

Parameters

QEMUFile * f

the file

QEMUTimer * ts

the timer

int qemu_timeout_ns_to_ms(int64_t ns)

Parameters

int64_t ns

nanosecond timeout value

Description

Convert a nanosecond timeout value (or -1) to a millisecond value (or -1), always rounding up.

Return

millisecond timeout value

int qemu_poll_ns(GPollFD * fds, guint nfds, int64_t timeout)

Parameters

GPollFD * fds

Array of file descriptors

guint nfds

number of file descriptors

int64_t timeout

timeout in nanoseconds

Description

Perform a poll like g_poll but with a timeout in nanoseconds. See g_poll documentation for further details.

Return

number of fds ready

int64_t qemu_soonest_timeout(int64_t timeout1, int64_t timeout2)

Parameters

int64_t timeout1

first timeout in nanoseconds (or -1 for infinite)

int64_t timeout2

second timeout in nanoseconds (or -1 for infinite)

Description

Calculates the soonest of two timeout values. -1 means infinite, which is later than any other value.

Return

soonest timeout value in nanoseconds (or -1 for infinite)

void init_clocks(QEMUTimerListNotifyCB * notify_cb)

Parameters

QEMUTimerListNotifyCB * notify_cb

undescribed

Description

Initialise the clock & timer infrastructure