kapi.h File Reference

#include "api.h"
#include "pros/apix.h"
#include "rtos/FreeRTOS.h"
#include "rtos/stream_buffer.h"

Go to the source code of this file.

Macros
#define	KDBG_FILENO   3
#define	warn_printf(fmt, ...)
#define	warn_wprint(str)
#define	kprintf(fmt, ...)
#define	kprint(str)
#define	kassert(cond)
#define	taskSCHEDULER_SUSPENDED   ((int32_t)0)
#define	taskSCHEDULER_NOT_STARTED   ((int32_t)1)
#define	taskSCHEDULER_RUNNING   ((int32_t)2)

Typedefs
typedef uint32_t	task_stack_t

Functions
void	rtos_suspend_all (void)
int32_t	rtos_resume_all (void)
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)
mutex_t	mutex_create_static (static_sem_s_t *mutex_buffer)
sem_t	sem_create_static (uint32_t max_count, uint32_t init_count, static_sem_s_t *semaphore_buffer)
queue_t	queue_create_static (uint32_t length, uint32_t item_size, uint8_t *storage_buffer, static_queue_s_t *queue_buffer)
void	display_fatal_error (const char *text)
void	kprint_hex (uint8_t *s, size_t len)
int32_t	xTaskGetSchedulerState ()

Detailed Description

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.

Copyright

Copyright (c) 2017-2024, Purdue University ACM SIGBots. All rights reserved.

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/.

Macro Definition Documentation

kassert

#define kassert

(

cond

)

Value:

    do {                                    \
        if (!(cond)) {                        \
            kprint("Assertion failed: " #cond); \
        }                                     \
    } while (0)

kprint

#define kprint

(

str

)

Value:

kprintf("%s", str)

kprintf

#define kprintf	(		fmt,
			... )

Value:

dprintf(KDBG_FILENO, "%s:%d -- " fmt "\n", __FILE__, __LINE__, ##__VA_ARGS__)

warn_printf

#define warn_printf	(		fmt,
			... )

Value:

dprintf(STDERR_FILENO, "%s:%d -- " fmt "\n", __FILE__, __LINE__, ##__VA_ARGS__)

warn_wprint

#define warn_wprint

(

str

)

Value:

wprintf("%s", str)

Function Documentation

display_fatal_error()

void display_fatal_error

(

const char *

text

)

Display a fatal error to the built-in LCD/touch 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.

Parameters

[in]

text

The text string to display to the screen

kprint_hex()

void kprint_hex	(	uint8_t *	s,
		size_t	len )

Prints hex characters to the terminal.

Parameters

[in]	s	The array of hex characters to print
	len	The number of hex characters to print

mutex_create_static()

mutex_t mutex_create_static

(

static_sem_s_t *

mutex_buffer

)

Creates a statically allocated mutex.

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

Parameters

[out]

mutex_buffer

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.

queue_create_static()

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.

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

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.
[out]	storage_buffer	A memory location for data storage
[out]	queue_buffer	A buffer to store the queue in

Returns

A handle to a newly created queue, or NULL if the queue cannot be created.

rtos_resume_all()

int32_t rtos_resume_all

(

void

)

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

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

Returns

True if a context switch is necessary.

rtos_suspend_all()

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.

sem_create_static()

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

Creates a statically allocated semaphore.

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

Parameters

	max_count	The maximum count value that can be reached.
	init_count	The initial count value assigned to the new semaphore.
[out]	semaphore_buffer	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.

task_create_static()

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. 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.

Parameters

function	Pointer to the task entry function
parameters	Pointer to memory that will be used as a parameter for the task being created. This memory should not typically come from stack, but rather from dynamically (i.e., malloc'd) or statically allocated memory.
prio	The priority at which the task should run. TASK_PRIO_DEFAULT plus/minus 1 or 2 is typically used.
stack_depth	The number of words (i.e. 4 * stack_depth) available on the task's stack. TASK_STACK_DEPTH_DEFAULT is typically sufficienct.
name	A descriptive name for the task. This is mainly used to facilitate debugging. The name may be up to 32 characters long.

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.