kapi.h file

Contents

Kernel API header

Contains additional declarations for use internally within kernel development. This file includes the FreeRTOS header, which allows for creation of statically allocated FreeRTOS primitives like tasks, semaphores, and queues.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Functions

void rtos_suspend_all(void)
Suspends the scheduler without disabling interrupts.
int32_t rtos_resume_all(void)
Resumes the scheduler.
task_t task_create_static(task_fn_t task_code, void*const param, uint32_t priority, const size_t stack_size, const char*const name, task_stack_t*const stack_buffer, static_task_s_t*const task_buffer)
Creates a task using statically allocated buffers.
mutex_t mutex_create_static(static_sem_s_t* mutex_buffer)
Creates a statically allocated mutex.
sem_t sem_create_static(uint32_t max_count, uint32_t init_count, static_sem_s_t* semaphore_buffer)
Creates a statically allocated semaphore.
queue_t queue_create_static(uint32_t length, uint32_t item_size, uint8_t* storage_buffer, static_queue_s_t* queue_buffer)
Creates a statically allocated queue.
void display_fatal_error(const char* text)
Display a fatal error to the built-in LCD/touch screen.
void kprint_hex(uint8_t* s, size_t len)
Prints hex characters to the terminal.
int32_t xTaskGetSchedulerState()

Typedefs

using task_stack_t = uint32_t

Defines

#define task_t
#define task_fn_t
#define mutex_t
#define sem_t
#define queue_t
#define KDBG_FILENO
#define warn_printf(fmt, ...)
#define warn_wprint(str)
#define kprintf(fmt, ...)
#define kprint(str)
#define kassert(cond)
#define taskSCHEDULER_SUSPENDED
#define taskSCHEDULER_NOT_STARTED
#define taskSCHEDULER_RUNNING

Function documentation

void rtos_suspend_all(void)

Suspends the scheduler without disabling interrupts.

context switches will not occur while the scheduler is suspended. RTOS ticks that occur while the scheduler is suspended will be held pending until the scheduler has been unsuspended with rtos_resume_all()

When used correctly, this function ensures that operations occur atomically w.r.t. multitasking. Functions like task_delay, queue_send, and other functions MUST NOT be called while the scheduler is disabled.

int32_t rtos_resume_all(void)

Resumes the scheduler.

Returns True if a context switch is necessary.

It does not resume unsuspended tasks that were previously suspended by task_suspend.

if(rtos_resume_all()) { task_delay(0); // force context switch }

task_t task_create_static(task_fn_t task_code, void*const param, uint32_t priority, const size_t stack_size, const char*const name, task_stack_t*const stack_buffer, static_task_s_t*const task_buffer)

Creates a task using statically allocated buffers.

Parameters
task_code
param
priority
stack_size
name A descriptive name for the task. This is mainly used to facilitate debugging. The name may be up to 32 characters long.
stack_buffer
task_buffer
Returns A handle by which the newly created task can be referenced. If an error occurred, NULL will be returned and errno can be checked for hints as to why task_create failed.

All tasks used by the PROS system must use statically allocated buffers. This function uses the following values of errno when an error state is reached: ENOMEM - The stack cannot be used as the TCB was not created.

mutex_t mutex_create_static(static_sem_s_t* mutex_buffer)

Creates a statically allocated mutex.

Parameters
mutex_buffer out A buffer to store the mutex in
Returns A handle to a newly created mutex. If an error occurred, NULL will be returned and errno can be checked for hints as to why mutex_create failed.

All FreeRTOS primitives must be created statically if they are required for operation of the kernel.

sem_t sem_create_static(uint32_t max_count, uint32_t init_count, static_sem_s_t* semaphore_buffer)

Creates a statically allocated semaphore.

Parameters
max_count The maximum count value that can be reached.
init_count The initial count value assigned to the new semaphore.
semaphore_buffer out A buffer to store the semaphore in
Returns A newly created semaphore. If an error occurred, NULL will be returned and errno can be checked for hints as to why sem_create failed.

All FreeRTOS primitives must be created statically if they are required for operation of the kernel.

queue_t queue_create_static(uint32_t length, uint32_t item_size, uint8_t* storage_buffer, static_queue_s_t* queue_buffer)

Creates a statically allocated queue.

Parameters
length The maximum number of items that the queue can contain.
item_size The number of bytes each item in the queue will require.
storage_buffer out A memory location for data storage
queue_buffer out A buffer to store the queue in
Returns A handle to a newly created queue, or NULL if the queue cannot be created.

All FreeRTOS primitives must be created statically if they are required for operation of the kernel.

void display_fatal_error(const char* text)

Display a fatal error to the built-in LCD/touch screen.

Parameters
text in The text string to display to the screen

This function is intended to be used when the integrity of the RTOS cannot be trusted. No thread-safety mechanisms are used and this function only relies on the use of the libv5rts.

void kprint_hex(uint8_t* s, size_t len)

Prints hex characters to the terminal.

Parameters
s in The array of hex characters to print
len The number of hex characters to print