HAL Timer API

[will sanfilippo <wi...@runtime.io>]

Hello:

We are working on a HAL API for timer peripherals. This HAL will be used to provide high resolution timers and not an OS based timer; that already exists. This HAL provides the ability to receive a callback when a timer expires and also to do short, blocking delays. Timer expiration can be set relative to “now” (hal_timer_start) or to occur at a specified timer tick value (hal_timer_start_at). 

Questions/comments:

1) I think that one of the major points of contention with this API will be the use of ticks instead of standard units of time (microseconds, milliseconds, etc). There is a helper function to convert ticks to microseconds (and vice versa) but that is about all. We have reasons why we chose ticks which I would be happy to discuss with those interested.

2) How do you think the hal_timer_start_at() API should act if the specified tick has already passed? Should it call the callback at the current context or return an error? I am leaning towards returning an error code to indicate this.

/* HAL timer struct */
typedef void (timer_cb *)(void *arg);

struct hal_timer
{
	timer_cb 	cb_func;
	void 	*cb_arg;

	/* NOTE: these are here to denote some internals that will be kept. These may change or there may be addtions */
	uint32_t 	expiration_tick;
	struct hal_timer *next;
}

/* Initialize the timer at the given frequency */
int hal_timer_init(int timer_num, uint32_t freq_hz);

/*
 * Returns the resolution of the timer. NOTE: the frequency may not be
 * obtainable so the caller can use this to determine the resolution.
 * Returns resolution in nanoseconds.
 */
uint32_t hal_timer_get_resolution(int timer_num);

/* Convert ticks to usecs */
uint32_t hal_timer_ticks_to_usecs(int timer_num, uint32_t ticks);

/* Convert microsseconds to ticks */
uint32_t hal_timer_usecs_to_ticks(int timer_num, uint32_t usecs);

/* Returns the timers current tick value */
uint32_t hal_timer_read(int timer_num);

/* Perform a blocking delay for a number of ticks. */
int hal_timer_delay_ticks(int timer_num, uint32_t ticks);

/* Initialize the HAL timer structure with the callback and the callback argument */
int hal_timer_set_cb(struct hal_timer *, timer_cb cb_func, void *);

/* Start a timer that will expire in ‘ticks’ ticks. Ticks cannot be 0 */
int hal_timer_start(struct hal_timer *, uint32_t ticks);

/* Stop a currently running timer */
int hal_timer_stop(struct hal_timer *);

/*
 * Start a timer that will expire when the timer reaches ‘tick’.
 * If the tick has already passed <see commment above>
 */
int hal_timer_start_at(struct hal_timer *, uint32_t tick);