RTOS helper libraries. More...

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

struct	Semaphore
	Semaphore object with handle and buffer. 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

#define	INVALID_EVENT 32

#define	QUEUE_DELAY_BLOCKING portMAX_DELAY

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

#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 uint8_t	Event

typedef struct Semaphore	Semaphore
	Semaphore object with handle and buffer.

typedef Semaphore	Mutex

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	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	mutex_init (Mutex *mutex)
	Initializes a mutex using provided static entity. More...

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

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

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

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

StatusCode	sem_post (Semaphore *sem)
	Releases a semaphore and increments the counting semaphore. 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

◆ mutex_init()

StatusCode 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

◆ mutex_lock()

StatusCode 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

◆ mutex_unlock()

StatusCode 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

◆ 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

◆ sem_init()

StatusCode 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

◆ sem_post()

StatusCode 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

◆ sem_wait()

StatusCode 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

◆ 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

◆ 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()

◆ mutex_init()

◆ mutex_lock()

◆ mutex_unlock()

◆ 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()

◆ sem_init()

◆ sem_post()

◆ sem_wait()

◆ send_task_end()

◆ tasks_init()

◆ tasks_init_task()

◆ tasks_start()

◆ wait_tasks()