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.
-
void *bsp_timer¶