System task

Low priority background task (KernelBG) running deferred work. More...

Typedefs
typedef void(*	SystemTaskEventCallback) (void *data)
	System task callback.

Functions
void	system_task_init (void)
	Create the KernelBG task.
void	system_task_timer_init (void)
	Set up the timers used by the system task, once timers are available.
void	system_task_watchdog_feed (void)
	Feed the KernelBG watchdog.
bool	system_task_add_callback_from_isr (SystemTaskEventCallback cb, void *data)
	Queue a callback from an ISR.
bool	system_task_add_callback_droppable (SystemTaskEventCallback cb, void *data)
	Queue a callback without waiting, dropping it if the queue is full.
bool	system_task_add_callback_from_isr_droppable (SystemTaskEventCallback cb, void *data)
	ISR flavour of system_task_add_callback_droppable().
bool	system_task_add_callback_from_isr_droppable_raised (SystemTaskEventCallback cb, void *data)
	Queue a droppable callback that raises KernelBG priority until it has run.
bool	system_task_add_callback (SystemTaskEventCallback cb, void *data)
	Queue a callback from task context.
void	system_task_block_callbacks (bool block)
	Block or unblock new callbacks.
uint32_t	system_task_get_available_space (void)
	Get the free space of the queue used by the calling task.
void *	system_task_get_current_callback (void)
	Get the callback being run, for debugging.
void	system_task_enable_raised_priority (bool is_raised)
	Acquire or release a reference raising KernelBG priority.
bool	system_task_is_ready_to_run (void)
	Check whether KernelBG is ready to run.

Detailed Description

Low priority background task (KernelBG) running deferred work.

ISRs and higher priority tasks marshal units of work onto KernelBG by queueing callbacks, which run one at a time in FIFO order. Callbacks are covered by a task watchdog; long ones must call system_task_watchdog_feed() regularly. When KernelBG starves, the app task is briefly throttled.

The enqueue variants differ in what happens when the queue is full:

• system_task_add_callback() waits, then resets the system if still full (apps wait forever on a separate queue),
• system_task_add_callback_from_isr() does not wait and resets the system,
• the _droppable variants do not wait and return false.

static void prv_save_cb(void *data) {
  // Runs on KernelBG.
}
 
system_task_add_callback(prv_save_cb, ctx);

Typedef Documentation

SystemTaskEventCallback

typedef void(* SystemTaskEventCallback) (void *data)

System task callback.

Parameters

data	Context given when queueing the callback.

Function Documentation

system_task_add_callback()

bool system_task_add_callback	(	SystemTaskEventCallback	cb,
		void *	data
	)

Queue a callback from task context.

From the app task, waits for space as long as needed. From other tasks, waits up to 3 seconds, then resets the system.

Parameters

cb	Callback to run on KernelBG.
data	Context passed to cb.

Returns

True if queued, false if callbacks are not accepted (not initialized or blocked).

system_task_add_callback_droppable()

bool system_task_add_callback_droppable	(	SystemTaskEventCallback	cb,
		void *	data
	)

Queue a callback without waiting, dropping it if the queue is full.

Callable from task or ISR context, including with interrupts locked. Never resets on failure. Only use it when losing the callback is tolerable or the caller can retry later.

Parameters

cb	Callback to run on KernelBG.
data	Context passed to cb.

Returns

True if queued, false if the queue is full or callbacks are not accepted.

system_task_add_callback_from_isr()

bool system_task_add_callback_from_isr	(	SystemTaskEventCallback	cb,
		void *	data
	)

Queue a callback from an ISR.

Does not wait. A full queue resets the system.

Parameters

cb	Callback to run on KernelBG.
data	Context passed to cb.

Returns

True if queued, false if callbacks are not accepted (not initialized or blocked).

system_task_add_callback_from_isr_droppable()

bool system_task_add_callback_from_isr_droppable	(	SystemTaskEventCallback	cb,
		void *	data
	)

ISR flavour of system_task_add_callback_droppable().

Parameters

cb	Callback to run on KernelBG.
data	Context passed to cb.

Returns

True if queued, false if the queue is full or callbacks are not accepted.

system_task_add_callback_from_isr_droppable_raised()

bool system_task_add_callback_from_isr_droppable_raised	(	SystemTaskEventCallback	cb,
		void *	data
	)

Queue a droppable callback that raises KernelBG priority until it has run.

The priority is raised while the callback is pending or running, and released after it returns. Nothing is retained if the callback is dropped.

Parameters

cb	Callback to run on KernelBG.
data	Context passed to cb.

Returns

True if queued, false if the queue is full or callbacks are not accepted.

system_task_block_callbacks()

void system_task_block_callbacks

(

bool

block

)

Block or unblock new callbacks.

Parameters

block

True to reject new callbacks, false to accept them.

system_task_enable_raised_priority()

void system_task_enable_raised_priority

(

bool

is_raised

)

Acquire or release a reference raising KernelBG priority.

While at least one reference is held, KernelBG runs at the priority of KernelMain.

Parameters

is_raised

True to acquire a reference, false to release one. Calls must be balanced.

system_task_get_available_space()

uint32_t system_task_get_available_space

(

void

)

Get the free space of the queue used by the calling task.

Returns

Number of callbacks that can be queued before the queue is full.

system_task_get_current_callback()

void * system_task_get_current_callback

(

void

)

Get the callback being run, for debugging.

Returns

Running callback, or NULL when idle.

system_task_init()

void system_task_init

(

void

)

Create the KernelBG task.

system_task_is_ready_to_run()

bool system_task_is_ready_to_run

(

void

)

Check whether KernelBG is ready to run.

Returns

True if ready, false if blocked (e.g. on a mutex or its queue).

system_task_timer_init()

void system_task_timer_init

(

void

)

Set up the timers used by the system task, once timers are available.

system_task_watchdog_feed()

void system_task_watchdog_feed

(

void

)

Feed the KernelBG watchdog.

Call it regularly from callbacks that take a while to run.