RTOS helper libraries. More...

Classes
struct	Semaphore
	Semaphore object with handle and buffer. More...

struct	Queue
	Queue storage and access struct. More...

struct	SoftTimer
	Soft timer storage. More...

struct	SoftwareWatchdog
	Software Watchdog Timer structure Uses a SoftTimer internally to track timeouts. More...

struct	Task

Macros
#define	delay_s(time) delay_ms((time) * 1000)
	Blocking delay for some amount of time in seconds. More...

#define	BLOCK_INDEFINITELY UINT16_MAX
	Maximum time permitted to wait for a semaphore or mutex.

#define	BLOCK_INDEFINITELY UINT16_MAX

#define	INVALID_EVENT 32

#define	QUEUE_DELAY_BLOCKING 0xFFFFFFFFU
	Maximum delay time to block current thread.

#define	TASK(task_name, task_stack_size)
	Define a task function. This should go in a source file (.c). More...

#define	MAX_NUM_TASKS 15
	Maximum amount of RTOS tasks supported at a time.

#define	TASK_PRIORITY(prio) ((TaskPriority)prio)
	Convienience priority to make code more readable.

#define	WAIT_TASK_TIMEOUT_MS 1000
	Define wait timeout as 1 second, tasks cycle executino should not take longer than a second.

#define	TASK_MIN_STACK_SIZE configMINIMAL_STACK_SIZE
	Minimum stack size a task can have. If you pass in something smaller than the min size, a warning will be issued.

#define	TASK_STACK_256 ((size_t)256)
	Common stack sizes. If your task is failing for strange reasons, bump the stack size one size up.

#define	TASK_STACK_512 ((size_t)512)

#define	TASK_STACK_1024 ((size_t)1024)

#define	TASK_STACK_2048 ((size_t)2048)

#define	TASK_STACK_4096 ((size_t)4096)

Typedefs
typedef struct Semaphore	Semaphore
	Semaphore object with handle and buffer.

typedef Semaphore	Mutex

typedef uint8_t	Event

typedef TimerHandle_t	SoftTimerId
	Redefine FreeRTOS TimerHandle_t to SoftTimerId.

typedef void(*	SoftTimerCallback) (SoftTimerId id)
	Software timer callback function.

typedef UBaseType_t	TaskPriority

typedef struct Task	Task

Functions
void	delay_ms (uint32_t time_ms)
	Blocking delay for some amount of time in milliseconds. More...

void	non_blocking_delay_ms (uint32_t time_ms)
	Non-blocking delay for some amount of time in milliseconds. More...

StatusCode	ms_mutex_init (Mutex *mutex)
	Initializes a mutex using provided static entity. More...

StatusCode	ms_mutex_lock (Mutex *mutex, uint16_t ms_to_wait)
	Locks a Mutex. More...

StatusCode	ms_mutex_unlock (Mutex *mutex)
	Unlocks a Mutex. More...

StatusCode	ms_sem_init (Semaphore *sem, uint32_t max_count, uint32_t initial_count)
	Initializes counting semaphore with max and initial count. More...

StatusCode	ms_sem_wait (Semaphore *sem, uint32_t timeout_ms)
	Obtains previously initiated semaphore and decrements the counting semaphore. More...

StatusCode	ms_sem_post (Semaphore *sem)
	Releases a semaphore and increments the counting semaphore. More...

StatusCode	event_from_notification (uint32_t notification, Event event)
	Get the highest priority event available and clears it. More...

bool	notify_check_event (uint32_t *notification, Event event)
	Checks if the notification is available in the event. More...

StatusCode	notify_get (uint32_t *notification)
	Get the current notification value for the calilng task without a timeout. More...

StatusCode	notify_wait (uint32_t *notification, uint32_t ms_to_wait)
	Get the current notification value for the calilng task with a maximum timeout. More...

StatusCode	notify (Task *task, Event event)
	Notify a specific task with an event. More...

void	notify_from_isr (Task *task, Event event)
	Sends an event notification from an ISR to a task. More...

StatusCode	queue_init (Queue *queue)
	Create a queue with the parameters specified in settings. More...

StatusCode	queue_send (Queue queue, const void item, uint32_t delay_ms)
	Place an item into the queue, delaying for delay_ms before timing out. More...

StatusCode	queue_send_from_isr (Queue queue, const void item, BaseType_t *higher_prio_woken)
	Place an item into the queue from an ISR. More...

StatusCode	queue_receive (Queue queue, void buf, uint32_t delay_ms)
	Retrieve an item from the queue, delaying for delay_ms before timing out. More...

StatusCode	queue_receive_from_isr (Queue queue, void buf, BaseType_t *higher_prio_woken)
	Retrieve an item from the queue, delaying for delay_ms before timing out. More...

StatusCode	queue_peek (Queue queue, void buf, uint32_t delay_ms)
	Receive an item from the queue without removing it. More...

void	queue_reset (Queue *queue)
	Reset all data in the queue. More...

uint32_t	queue_get_num_items (Queue *queue)
	Retrieve the total number of spaces in the queue. More...

uint32_t	queue_get_spaces_available (Queue *queue)
	Retrieve the space left in the queue. More...

StatusCode	software_timer_init (uint32_t duration_ms, SoftTimerCallback callback, SoftTimer *timer)
	Creates a new software timer without starting it. More...

StatusCode	software_timer_start (SoftTimer *timer)
	Starts an initialized software timer. More...

StatusCode	software_timer_init_and_start (uint32_t duration_ms, SoftTimerCallback callback, SoftTimer *timer)
	Initializes and starts a software timer. More...

StatusCode	software_timer_cancel (SoftTimer *timer)
	Cancels a running software timer. More...

StatusCode	software_timer_reset (SoftTimer *timer)
	Restarts a software timer. More...

bool	software_timer_inuse (SoftTimer *timer)
	Checks if a software timer is currently active. More...

uint32_t	software_timer_remaining_time (SoftTimer *timer)
	Gets the remaining time on a software timer. More...

StatusCode	software_watchdog_init (SoftwareWatchdog *watchdog, uint32_t period_ms, SoftTimerCallback fault_callback)
	Initializes the software watchdog timer. More...

StatusCode	software_watchdog_kick (SoftwareWatchdog *watchdog)
	"Kicks" (resets) the watchdog timer to prevent timeout More...

StatusCode	software_watchdog_stop (SoftwareWatchdog *watchdog)
	Stops and disables the watchdog timer. More...

StatusCode	tasks_init_task (Task task, TaskPriority priority, void context)
	Initialize a task that was previously declared with TASK(). More...

void	tasks_start (void)
	Start the FreeRTOS scheduler to run the tasks that were previously initialized. More...

StatusCode	tasks_init (void)
	Initialize the task module. More...

StatusCode	wait_tasks (uint16_t num_tasks)
	Waits for num_tasks of RTOS tasks to finish. More...

StatusCode	send_task_end (void)
	A wrapper to give to the semaphore, to be called by tasks when they complete. More...

Detailed Description

RTOS helper libraries.

Macro Definition Documentation

◆ delay_s

#define delay_s ( time ) delay_ms((time) * 1000)

Blocking delay for some amount of time in seconds.

Parameters

time_ms Amount of time to delay for

◆ TASK

#define TASK	(	task_name,
		task_stack_size
	)

Value:

  /* forward declaration so we can reference it in the Task */                                                                                                                              \
  static void _s_task_impl_##task_name(void *);                                                                                                                                             \
  static StackType_t _s_stack_##task_name[task_stack_size];                                                                                                                                 \
  /* use a compound literal so users can use it as a pointer */                                                                                                                             \
  Task *task_name = &((Task){                                                                                                                                                               \
      .task_func = _s_task_impl_##task_name, .name = #task_name, .stack = _s_stack_##task_name, .stack_size = task_stack_size, .handle = NULL, /* will be initialized by tasks_init_task */ \
  });                                                                                                                                                                                       \
  static void _s_task_impl_##task_name(void *context)

Define a task function. This should go in a source file (.c).

The generated function has the following signature: void _s_your_task_function(void *context) where context is the context pointer passed to tasks_init_task.

Parameters

task_name	is the name of your task, which should match any previous DECLARE_TASK declarations.
task_stack_size	is the depth of your task's stack - use your judgement to choose.

Function Documentation

◆ delay_ms()

void delay_ms ( uint32_t time_ms )

Blocking delay for some amount of time in milliseconds.

Parameters

time_ms Amount of time to delay for

◆ event_from_notification()

StatusCode event_from_notification	(	uint32_t *	notification,
		Event *	event
	)

Get the highest priority event available and clears it.

Call this function in a while loop to clear all events

Parameters

notification	Notification value that is cleared and returned
event	Event value that is updated to the highest priority

Returns: STATUS_CODE_OK if all events are processed (notification = 0) STATUS_CODE_INCOPMLETE if some events are not cleared

◆ ms_mutex_init()

StatusCode ms_mutex_init ( Mutex * mutex )

Initializes a mutex using provided static entity.

Parameters

mutex Mutex handle

Returns: STATUS_CODE_OK on success STATUS_CODE_UNINITIALIZED on failure

◆ ms_mutex_lock()

StatusCode ms_mutex_lock	(	Mutex *	mutex,
		uint16_t	ms_to_wait
	)

Locks a Mutex.

The locking task is responsible for unlocking the mutex Waits ms_to_wait milliseconds if mutex is already locked, then times out Using BLOCK_INDEFINITELY will cause this method to wait forever on mutex becoming available

Parameters

mutex	Mutex handle
ms_to_wait	Amount of time to wait for mutex

Returns: STATUS_CODE_OK on success STATUS_CODE_TIMEOUT on timeout

◆ ms_mutex_unlock()

StatusCode ms_mutex_unlock ( Mutex * mutex )

Unlocks a Mutex.

The task which locks the mutex MUST also be the one to unlock it Caller specifies whether the method is being called from a task or interrupt handler higher_priority_task_woken informs the caller whether a higher priority task has become unblocked

Parameters

mutex Mutex handle

Returns: STATUS_CODE_OK on success STATUS_CODE_INTERNAL_ERROR on failure

◆ ms_sem_init()

StatusCode ms_sem_init	(	Semaphore *	sem,
		uint32_t	max_count,
		uint32_t	initial_count
	)

Initializes counting semaphore with max and initial count.

Parameters

sem	Semaphore handle
max_count	Maximum count for counting semaphore
initial_count	Initial count value to set the counting semaphore

Returns: STATUS_CODE_OK on success STATUS_CODE_UNINITIALIZED on pxSemaphoreBuffer is NULL

◆ ms_sem_post()

StatusCode ms_sem_post ( Semaphore * sem )

Releases a semaphore and increments the counting semaphore.

Note that this must not be used from ISR An error can occur if there is no space on the queue

Parameters

sem	Semaphore handle

Returns: STATUS_CODE_OK if semaphore is released STATUS_CODE_INTERNAL_ERROR on error

◆ ms_sem_wait()

StatusCode ms_sem_wait	(	Semaphore *	sem,
		uint32_t	timeout_ms
	)

Obtains previously initiated semaphore and decrements the counting semaphore.

Waits timeout_ms milliseconds for the semaphore to become available

Parameters

sem	Semaphore handle
timeout_ms	Amount of time to wait for the semaphore

Returns: STATUS_CODE_OK on success STATUS_CODE_TIMEOUT if xTicksToWait expires

◆ non_blocking_delay_ms()

void non_blocking_delay_ms ( uint32_t time_ms )

Non-blocking delay for some amount of time in milliseconds.

Parameters

time_ms Amount of time to delay for

◆ notify()

StatusCode notify	(	Task *	task,
		Event	event
	)

Notify a specific task with an event.

Parameters

task	Pointer to the task to notify
event	Numeric value used to signal task

Returns: STATUS_CODE_OK

◆ notify_check_event()

bool notify_check_event	(	uint32_t *	notification,
		Event	event
	)

Checks if the notification is available in the event.

Parameters

notification Pointer to the notification to

Returns: True if the notification exists. False if it does not

◆ notify_from_isr()

void notify_from_isr	(	Task *	task,
		Event	event
	)

Sends an event notification from an ISR to a task.

Parameters

task	Pointer to the task to notify
event	Numeric value used to signal task

◆ notify_get()

StatusCode notify_get ( uint32_t * notification )

Get the current notification value for the calilng task without a timeout.

Parameters

notification Pointer to a notification value that is updated upon success

Returns: STATUS_CODE_OK if the value is retrieved successfully STATUS_CODE_TIMEOUT if the value cannot be retrieved

◆ notify_wait()

StatusCode notify_wait	(	uint32_t *	notification,
		uint32_t	ms_to_wait
	)

Get the current notification value for the calilng task with a maximum timeout.

Parameters

notification	Pointer to a notification value that is polled
ms_to_wait	Time in milliseconds to wait for a notification before timing out

Returns: STATUS_CODE_OK if notification is received successfully STATUS_CODE_TIMEOUT if a timeout has occurred

◆ queue_get_num_items()

uint32_t queue_get_num_items ( Queue * queue )

Retrieve the total number of spaces in the queue.

Parameters

queue Pointer to queue handle

Returns: Total number of spaces available

◆ queue_get_spaces_available()

uint32_t queue_get_spaces_available ( Queue * queue )

Retrieve the space left in the queue.

Parameters

queue Pointer to queue handle

Returns: Remaining number of spaces available

◆ queue_init()

StatusCode queue_init ( Queue * queue )

Create a queue with the parameters specified in settings.

Parameters

queue Pointer to queue handle

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect

◆ queue_peek()

StatusCode queue_peek	(	Queue *	queue,
		void *	buf,
		uint32_t	delay_ms
	)

Receive an item from the queue without removing it.

Parameters

queue	Pointer to queue handle
item	Pointer to the buffer to fill from the queue
delay_ms	Time in milliseconds to wait for data in the queue before timing out

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect STATUS_CODE_RESOURCE_EXHAUSTED if the queue is empty

◆ queue_receive()

StatusCode queue_receive	(	Queue *	queue,
		void *	buf,
		uint32_t	delay_ms
	)

Retrieve an item from the queue, delaying for delay_ms before timing out.

Parameters

queue	Pointer to queue handle
item	Pointer to the buffer to fill from the queue
delay_ms	Time in milliseconds to wait for data in the queue before timing out

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect STATUS_CODE_RESOURCE_EXHAUSTED if the queue is empty

◆ queue_receive_from_isr()

StatusCode queue_receive_from_isr	(	Queue *	queue,
		void *	buf,
		BaseType_t *	higher_prio_woken
	)

Retrieve an item from the queue, delaying for delay_ms before timing out.

Parameters

queue	Pointer to queue handle
item	Pointer to the buffer to fill from the queue
higher_prio_woken	Boolean to indicate a context switch after exiting the ISR

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect STATUS_CODE_RESOURCE_EXHAUSTED if the queue is empty

◆ queue_reset()

void queue_reset ( Queue * queue )

Reset all data in the queue.

Parameters

queue Pointer to queue handle

◆ queue_send()

StatusCode queue_send	(	Queue *	queue,
		const void *	item,
		uint32_t	delay_ms
	)

Place an item into the queue, delaying for delay_ms before timing out.

Parameters

queue	Pointer to queue handle
item	Pointer to the item sent to the queue
delay_ms	Time in milliseconds to wait for space in the queue before timing out

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect STATUS_CODE_RESOURCE_EXHAUSTED if the queue is full

◆ queue_send_from_isr()

StatusCode queue_send_from_isr	(	Queue *	queue,
		const void *	item,
		BaseType_t *	higher_prio_woken
	)

Place an item into the queue from an ISR.

Parameters

queue	Pointer to queue handle
item	Pointer to the item sent to the queue
higher_prio_woken	Boolean to indicate a context switch after exiting the ISR

Returns: STATUS_CODE_OK if initialization succeeded STATUS_CODE_INVALID_ARGS if one of the parameters are incorrect STATUS_CODE_RESOURCE_EXHAUSTED if the queue is full

◆ send_task_end()

StatusCode send_task_end ( void )

A wrapper to give to the semaphore, to be called by tasks when they complete.

Returns: STATUS_CODE_OK if successfully release sempahore

◆ software_timer_cancel()

StatusCode software_timer_cancel ( SoftTimer * timer )

Cancels a running software timer.

Parameters

timer Pointer to the timer instance

Returns: STATUS_CODE_OK if the timer was successfully cancelled

◆ software_timer_init()

StatusCode software_timer_init	(	uint32_t	duration_ms,
		SoftTimerCallback	callback,
		SoftTimer *	timer
	)

Creates a new software timer without starting it.

Parameters

duration_ms	Duration of the timer in milliseconds
callback	Callback function to execute when the timer expires
timer	Pointer to the timer instance

Returns: STATUS_CODE_OK if the timer was successfully initialized

◆ software_timer_init_and_start()

StatusCode software_timer_init_and_start	(	uint32_t	duration_ms,
		SoftTimerCallback	callback,
		SoftTimer *	timer
	)

Initializes and starts a software timer.

Parameters

duration_ms	Duration of the timer in milliseconds
callback	Callback function to execute when the timer expires
timer	Pointer to the timer instance

Returns: STATUS_CODE_OK if the timer was successfully initialized and started

◆ software_timer_inuse()

bool software_timer_inuse ( SoftTimer * timer )

Checks if a software timer is currently active.

Parameters

timer Pointer to the timer instance

Returns: true if the timer is running, false otherwise

◆ software_timer_remaining_time()

uint32_t software_timer_remaining_time ( SoftTimer * timer )

Gets the remaining time on a software timer.

Parameters

timer Pointer to the timer instance

Returns: Remaining time in ticks, or 0 if the timer has expired

◆ software_timer_reset()

StatusCode software_timer_reset ( SoftTimer * timer )

Restarts a software timer.

Parameters

timer Pointer to the timer instance

Returns: STATUS_CODE_OK if the timer was successfully restarted

◆ software_timer_start()

StatusCode software_timer_start ( SoftTimer * timer )

Starts an initialized software timer.

Parameters

timer Pointer to the timer instance

Returns: STATUS_CODE_OK if the timer was successfully started

◆ software_watchdog_init()

StatusCode software_watchdog_init	(	SoftwareWatchdog *	watchdog,
		uint32_t	period_ms,
		SoftTimerCallback	fault_callback
	)

Initializes the software watchdog timer.

Parameters

watchdog	Pointer to the watchdog instance
period_ms	Timeout period in milliseconds
fault_callback	Function to call if watchdog is not kicked before timeout

Returns: STATUS_CODE_OK if successfully initialized

◆ software_watchdog_kick()

StatusCode software_watchdog_kick ( SoftwareWatchdog * watchdog )

"Kicks" (resets) the watchdog timer to prevent timeout

Parameters

watchdog Pointer to the watchdog instance

Returns: STATUS_CODE_OK if successfully kicked

◆ software_watchdog_stop()

StatusCode software_watchdog_stop ( SoftwareWatchdog * watchdog )

Stops and disables the watchdog timer.

Parameters

watchdog Pointer to the watchdog instance

Returns: STATUS_CODE_OK if successfully stopped

◆ tasks_init()

StatusCode tasks_init ( void )

Initialize the task module.

Must be called before tasks are initialized or the scheduler is started.

Returns: STATUS_CODE_OK if successfully initialize the module.

◆ tasks_init_task()

StatusCode tasks_init_task	(	Task *	task,
		TaskPriority	priority,
		void *	context
	)

Initialize a task that was previously declared with TASK().

Parameters

task	Task handle
priority	The task priority: higher number is higher priority, and the maximum
context	Pointer to arguments that are passed to the task is configNUM_TASK_PRIORITIES - 1.

Returns: STATUS_CODE_OK if successfully initialize task.

◆ tasks_start()

void tasks_start ( void )

Start the FreeRTOS scheduler to run the tasks that were previously initialized.

This function should not return!

◆ wait_tasks()

StatusCode wait_tasks ( uint16_t num_tasks )

Waits for num_tasks of RTOS tasks to finish.

Parameters

num_tasks Number of task completions to wait for

Takes num_tasks from end task semaphore, tracking the number of tasks completed

Returns: STATUS_CODE_OK if num_tasks items taken successfully STATUS_CODE_TIMEOUT if timeout occurs

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ delay_s

◆ TASK

Function Documentation

◆ delay_ms()

◆ event_from_notification()

◆ ms_mutex_init()

◆ ms_mutex_lock()

◆ ms_mutex_unlock()

◆ ms_sem_init()

◆ ms_sem_post()

◆ ms_sem_wait()

◆ non_blocking_delay_ms()

◆ notify()

◆ notify_check_event()

◆ notify_from_isr()

◆ notify_get()

◆ notify_wait()

◆ queue_get_num_items()

◆ queue_get_spaces_available()

◆ queue_init()

◆ queue_peek()

◆ queue_receive()

◆ queue_receive_from_isr()

◆ queue_reset()

◆ queue_send()

◆ queue_send_from_isr()

◆ send_task_end()

◆ software_timer_cancel()

◆ software_timer_init()

◆ software_timer_init_and_start()

◆ software_timer_inuse()

◆ software_timer_remaining_time()

◆ software_timer_reset()

◆ software_timer_start()

◆ software_watchdog_init()

◆ software_watchdog_kick()

◆ software_watchdog_stop()

◆ tasks_init()

◆ tasks_init_task()

◆ tasks_start()

◆ wait_tasks()