New timer

Timers and deferred work run on the high priority NewTimer task. More...

Macros
#define	TIMER_INVALID_ID   0
	Invalid timer id, never returned by new_timer_create().
#define	TIMER_START_FLAG_REPEATING   0x01
	Re-arm the timer with the same timeout after each expiry.
#define	TIMER_START_FLAG_FAIL_IF_EXECUTING   0x02
	Fail if the callback is executing.
#define	TIMER_START_FLAG_FAIL_IF_SCHEDULED   0x04
	Fail if the timer is already scheduled, instead of rescheduling it.

Typedefs
typedef void(*	NewTimerCallback) (void *data)
	Timer callback, run on the NewTimer task.
typedef uint32_t	TimerID
	Timer handle; ids are used instead of pointers to avoid use-after-free.
typedef void(*	NewTimerWorkCallback) (void *data)
	Work callback, run on the NewTimer task.

Functions
TimerID	new_timer_create (void)
	Create a timer, initially stopped.
bool	new_timer_start (TimerID timer, uint32_t timeout_ms, NewTimerCallback cb, void *cb_data, uint32_t flags)
	Schedule a timer.
bool	new_timer_stop (TimerID timer)
	Stop a timer.
bool	new_timer_scheduled (TimerID timer, uint32_t *expire_ms_p)
	Check whether a timer is scheduled.
void	new_timer_delete (TimerID timer)
	Delete a timer, stopping it first.
void *	new_timer_debug_get_current_callback (void)
	Get the callback being executed, for the watchdog.
void	new_timer_add_work_callback_from_isr (NewTimerWorkCallback cb, void *data)
	Queue work on the NewTimer task from an ISR.
bool	new_timer_add_work_callback (NewTimerWorkCallback cb, void *data)
	Queue work on the NewTimer task.
void	new_timer_service_init (void)
	Create the NewTimer task; called once at boot.

Detailed Description

Timers and deferred work run on the high priority NewTimer task.

NewTimer runs at the highest task priority and executes timer callbacks and work deferred from interrupts by drivers. Callbacks must be short: anything long should be handed to another task, e.g. with an evented timer or a system task callback. Timers are a wrapper around the kernel task timers.

static TimerID s_timer;
 
static void timeout_cb(void *data) {
  // Runs on NewTimer.
}
 
s_timer = new_timer_create();
new_timer_start(s_timer, 500, timeout_cb, NULL, TIMER_START_FLAG_REPEATING);
// ...
new_timer_stop(s_timer);
new_timer_delete(s_timer);

Macro Definition Documentation

TIMER_INVALID_ID

#define TIMER_INVALID_ID   0

Invalid timer id, never returned by new_timer_create().

TIMER_START_FLAG_FAIL_IF_EXECUTING

#define TIMER_START_FLAG_FAIL_IF_EXECUTING   0x02

Fail if the callback is executing.

Neither schedule the timer nor wait; new_timer_start() returns false. Useful when the callback may be blocked on a semaphore owned by the task issuing the start.

TIMER_START_FLAG_FAIL_IF_SCHEDULED

#define TIMER_START_FLAG_FAIL_IF_SCHEDULED   0x04

Fail if the timer is already scheduled, instead of rescheduling it.

TIMER_START_FLAG_REPEATING

#define TIMER_START_FLAG_REPEATING   0x01

Re-arm the timer with the same timeout after each expiry.

Typedef Documentation

NewTimerCallback

typedef void(* NewTimerCallback) (void *data)

Timer callback, run on the NewTimer task.

Parameters

data	Data passed to new_timer_start().

NewTimerWorkCallback

typedef void(* NewTimerWorkCallback) (void *data)

Work callback, run on the NewTimer task.

Parameters

data	Data passed when queuing the work.

TimerID

typedef uint32_t TimerID

Timer handle; ids are used instead of pointers to avoid use-after-free.

Function Documentation

new_timer_add_work_callback()

bool new_timer_add_work_callback	(	NewTimerWorkCallback	cb,
		void *	data
	)

Queue work on the NewTimer task.

Waits up to 50 ticks for space in the queue.

Parameters

cb	Work callback.
data	Data passed to cb.

Returns

true if queued, false if the queue stayed full.

new_timer_add_work_callback_from_isr()

void new_timer_add_work_callback_from_isr	(	NewTimerWorkCallback	cb,
		void *	data
	)

Queue work on the NewTimer task from an ISR.

Used to handle time sensitive hardware events. The work is dropped if the queue is full.

Parameters

cb	Work callback.
data	Data passed to cb.

new_timer_create()

TimerID new_timer_create

(

void

)

Create a timer, initially stopped.

Timers come from a fixed pool; running out of timers asserts.

Returns

Non-zero timer id.

new_timer_debug_get_current_callback()

void * new_timer_debug_get_current_callback

(

void

)

Get the callback being executed, for the watchdog.

Returns

Running timer or work callback, or NULL.

new_timer_delete()

void new_timer_delete

(

TimerID

timer

)

Delete a timer, stopping it first.

If the callback is executing, the timer is freed after it returns.

Parameters

timer

Timer id.

new_timer_scheduled()

bool new_timer_scheduled	(	TimerID	timer,
		uint32_t *	expire_ms_p
	)

Check whether a timer is scheduled.

Parameters

	timer	Timer id.
[out]	expire_ms_p	If not NULL, milliseconds until the timer fires; only valid when scheduled.

Returns

true if the timer is scheduled.

new_timer_service_init()

void new_timer_service_init

(

void

)

Create the NewTimer task; called once at boot.

new_timer_start()

bool new_timer_start	(	TimerID	timer,
		uint32_t	timeout_ms,
		NewTimerCallback	cb,
		void *	cb_data,
		uint32_t	flags
	)

Schedule a timer.

A timer that is already scheduled is rescheduled for the new time, unless TIMER_START_FLAG_FAIL_IF_SCHEDULED is given.

Parameters

timer	Timer id.
timeout_ms	Timeout in milliseconds.
cb	Callback.
cb_data	Data passed to cb.
flags	Zero or more TIMER_START_FLAG_ values.

Returns

true on success; false is only returned when one of the FAIL_IF flags applies.

new_timer_stop()

bool new_timer_stop

(

TimerID

timer

)

Stop a timer.

Safe to call on a timer that is not scheduled. A repeating timer does not run again even if its callback is executing.

Parameters

timer

Timer id.

Returns

false if the callback is executing, true otherwise.