Timer

The hardware independent timer structure and API to configure, initialize, and run timers.

Description

The HAL timer structure is shown below. The user can declare as many of these structures as required. They are enqueued on a particular HW timer queue when the user calls the hal_timer_start or hal_timer_start_at API. The user must have called hal_timer_set_cb before starting a timer.

NOTE: the user should not have to modify/examine the contents of this structure; the hal timer API should be used.

struct hal_timer
{
    void                *bsp_timer; /* Internal platform specific pointer */
    hal_timer_cb        cb_func;    /* Callback function */
    void                *cb_arg;    /* Callback argument */
    uint32_t            expiry;     /* Tick at which timer should expire */
    TAILQ_ENTRY(hal_timer) link;    /* Queue linked list structure */
};

API

typedef void (*hal_timer_cb)(void *arg)
int hal_timer_init(int timer_num, void *cfg)

Initialize a HW timer.

Parameters

  • timer_num: The number of the HW timer to initialize

  • cfg: Hardware specific timer configuration. This is passed from BSP directly to the MCU specific driver.

int hal_timer_deinit(int timer_num)

Un-initialize a HW timer.

Parameters

  • timer_num: The number of the HW timer to un-initialize

int hal_timer_config(int timer_num, uint32_t freq_hz)

Config a HW timer at the given frequency and start it.

If the exact frequency is not obtainable the closest obtainable frequency is set.

Return

0 on success, non-zero error code on failure

Parameters

  • timer_num: The number of the HW timer to configure

  • freq_hz: The frequency in Hz to configure the timer at

uint32_t hal_timer_get_resolution(int timer_num)

Returns the resolution of the HW timer.

NOTE: the frequency may not be obtainable so the caller can use this to determine the resolution. Returns resolution in nanoseconds. A return value of 0 indicates an invalid timer was used.

Return

The resolution of the timer

Parameters

  • timer_num: The number of the HW timer to get resolution for

uint32_t hal_timer_read(int timer_num)

Returns the HW timer current tick value.

Return

The current tick value

Parameters

  • timer_num: The HW timer to read the tick value from

int hal_timer_delay(int timer_num, uint32_t ticks)

Perform a blocking delay for a number of ticks.

Return

0 on success, non-zero error code on failure

Parameters

  • timer_num: The timer number to use for the blocking delay

  • ticks: The number of ticks to delay for

int hal_timer_set_cb(int timer_num, struct hal_timer *tmr, hal_timer_cb cb_func, void *arg)

Set the timer structure prior to use.

Should not be called if the timer is running. Must be called at least once prior to using timer.

Return

0 on success, non-zero error code on failure.

Parameters

  • timer_num: The number of the HW timer to configure the callback on

  • tmr: The timer structure to use for this timer

  • cb_func: The timer callback to call when the timer fires

  • arg: An opaque argument to provide the timer callback

int hal_timer_start(struct hal_timer *tmr, uint32_t ticks)

Start a timer that will expire in ‘ticks’ ticks.

Ticks cannot be 0

Return

0 on success, non-zero error code on failure.

Parameters

  • tmr: The timer to start

  • ticks: The number of ticks to expire the timer in

int hal_timer_start_at(struct hal_timer *tmr, uint32_t tick)

Start a timer that will expire when the timer reaches ‘tick’.

If tick has already passed the timer callback will be called “immediately” (at interrupt context).

Return

0 on success, non-zero error code on failure.

Parameters

  • tmr: The timer to start

  • tick: The absolute tick value to fire the timer at

int hal_timer_stop(struct hal_timer *tmr)

Stop a currently running timer; associated callback will NOT be called.

Parameters

  • tmr: The timer to stop

struct hal_timer
#include <hal_timer.h>

The HAL timer structure.

The user can declare as many of these structures as desired. They are enqueued on a particular HW timer queue when the user calls the :c:func:hal_timer_start() or :c:func:hal_timer_start_at() API. The user must have called :c:func:hal_timer_set_cb() before starting a timer.

NOTE: the user should not have to modify/examine the contents of this structure; the hal timer API should be used.

Public Members

void *bsp_timer

Internal platform specific pointer.

hal_timer_cb cb_func

Callback function.

void *cb_arg

Callback argument.

uint32_t expiry

Tick at which timer should expire.