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.

Parameters:

  • timer_num – The number of the HW timer to configure

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

Returns:

0 on success, non-zero error code on failure

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.

Parameters:

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

Returns:

The resolution of the timer

uint32_t hal_timer_read(int timer_num)

Returns the HW timer current tick value.

Parameters:

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

Returns:

The current tick value

int hal_timer_delay(int timer_num, uint32_t ticks)

Perform a blocking delay for a number of ticks.

Parameters:

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

  • ticks – The number of ticks to delay for

Returns:

0 on success, non-zero error code on failure

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.

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

Returns:

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

int hal_timer_start(struct hal_timer *tmr, uint32_t ticks)

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

Ticks cannot be 0

Parameters:

  • tmr – The timer to start

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

Returns:

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

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).

Parameters:

  • tmr – The timer to start

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

Returns:

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

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.