Threads

Description

Macros
#define	STACK_ALIGN
#define	PRIORITY_INVALID   0x1FFU
#define	PRIORITY_MAX   0xFFU
#define	STACK_INVALID   0xFFFFFFFFU

Typedefs
typedef uint8_t	Thread_t

Functions
long	os_sched_timing_callback (long delay_us)
	Kernel callback for timing provider.
uint8_t	os_get_current_process (void)
	Kernel implementation of get_pid.
uint8_t	os_get_current_thread (void)
	Kernel implementation of get_tid() syscall.
void	os_set_current_thread (Thread_t new_thread)
	Kernel internal function to override current thread.
uint8_t	os_get_current_stack (void)
	Get ID of stack used by current thread.
uint32_t	os_get_micro_time (void)
	Get amount of microseconds elapsed since scheduler start.
int	os_sched_yield (void)
	Kernel implementation of sched_yield() syscall.
void	os_start ()
	Start up scheduler.
void	systick_setup (int xms)
	Configures systick timer.
int	os_thread_create (entrypoint_t *entrypoint, void *data, uint8_t priority)
	Kernel implementation of thread_create() syscall.
int	os_thread_join (uint8_t thread_id)
	Kernel implementation of thread_join() syscall.
int	os_thread_exit (int status)
	Kernel implementation of thread_exit() syscall.
int	os_thread_stop (uint8_t thread_id)
	Kernel implementation of thread_stop() syscall.
int	os_thread_continue (uint8_t thread_id)
	Kernel implementation of thread_continue() syscall.
int	os_thread_kill (uint8_t thread_id, int status)
	Kernel way to kill an arbitrary thread.
int	os_setpriority (uint8_t priority)
	Kernel implementation of setpriority() syscall.
unsigned long *	os_stack_get (int stack_id)
	Get address of stack.
struct OS_thread_t *	os_thread_get (Thread_t thread_id)
	Get thread descriptor.
int	os_thread_construct (Thread_t tid, entrypoint_t *entrypoint, void *data)
	Make thread runnable.
void	os_thread_dispose (void)
	Alias to thread_exit.
int	os_thread_alloc (Process_t process, uint8_t priority)
	Allocate thread entry in thread table.
bool	os_get_next_thread (uint8_t current_thread, uint8_t *next_thread)
	Obtain next thread to run.
int	os_idle_thread (void *data)
	CMRX idle thread.
int	os_stack_create ()
	Find free stack slot and allocate it.
void	os_stack_dispose (uint32_t stack_id)
	Release stack slot.
int	__os_thread_create (Process_t process, entrypoint_t *entrypoint, void *data, uint8_t priority)
	Full workflow needed to create a thread.

Variables
struct OS_thread_t	os_threads [OS_THREADS]
	List of active threads.
struct OS_process_t	os_processes [OS_PROCESSES]
	List of active processes.
static struct OS_core_state_t	core [OS_NUM_CORES]
	CPU scheduling thread IDs.
struct OS_stack_t	os_stacks
	Thread stacks.
uint32_t	sched_tick_increment
	Amount of real time advance per one scheduler tick.
static uint32_t	sched_microtime = 0
	Current scheduler real time.

Macro Definition Documentation

PRIORITY_INVALID

#define PRIORITY_INVALID   0x1FFU

PRIORITY_MAX

#define PRIORITY_MAX   0xFFU

STACK_ALIGN

#define STACK_ALIGN

STACK_INVALID

#define STACK_INVALID   0xFFFFFFFFU

Typedef Documentation

Thread_t

typedef uint8_t Thread_t

Function Documentation

__os_thread_create()

int __os_thread_create	(	Process_t	process,
		entrypoint_t *	entrypoint,
		void *	data,
		uint8_t	priority
	)

Full workflow needed to create a thread.

This function is callable both from syscall and internally from kernel (during e.g. system startup) and performs complete thread creation workflow.

Parameters

process	ID of process owning the thread. Process must already be existing.
entrypoint	address of function which shall be executed as entrypoint into the thread
data	address of data block which should be passed to entrypoint function as an argument
priority	thread priority. Numerically lower values mean higher priorities

Returns

Non-negative values denote ID of thread just created, negative values mean errors.

os_get_current_process()

uint8_t os_get_current_process

(

void

)

Kernel implementation of get_pid.

Returns

Current process ID. This is actually an offset in process table.

os_get_current_stack()

uint8_t os_get_current_stack

(

void

)

Get ID of stack used by current thread.

Returns

Current active stack ID. This is actually an offset in stack table.

os_get_current_thread()

uint8_t os_get_current_thread

(

void

)

Kernel implementation of get_tid() syscall.

Returns

Current thread ID. This is actually an offset in thread table.

os_get_micro_time()

uint32_t os_get_micro_time

(

void

)

Get amount of microseconds elapsed since scheduler start.

Returns

internal kernel soft timer. This gets updated upon each systick handler call. It may jitter a bit. Wraps after about 4 million seconds.

os_get_next_thread()

bool os_get_next_thread	(	uint8_t	current_thread,
		uint8_t *	next_thread
	)

Obtain next thread to run.

This function performs thread list lookup. It searches for thread, which is in ready state and has highest (numerically lowest) priority.

Parameters

current_thread	thread which is currently running
next_thread	pointer to variable where next thread ID will be stored

Returns

true if any runnable thread (different than current) was found, false otherwise.

os_idle_thread()

int os_idle_thread

(

void *

data

)

CMRX idle thread.

This thread runs whenever no other CMRX thread is ready to be run. It does nothing useful.

os_sched_timing_callback()

long os_sched_timing_callback

(

long

delay_us

)

Kernel callback for timing provider.

Kernel entrypoint for timed events. Kernel tells the timing provider, what is the delay before the next call, whenever this function is called. Timing provider shall then wait for given amount of time and then call this callback again. If the delay is 0, then timing provider can shutdown itself as there is no expected timed wakeup.

Parameters

[in]

delay_us

the actual amount of microseconds which happened since the last wakeup

Returns

amount of microseconds, which shall pass before next wakeup will happen. If this value is zero, then no next wakeup shall happen.

os_sched_yield()

int os_sched_yield

(

void

)

Kernel implementation of sched_yield() syscall.

Causes scheduler to consider another task to be ran.

os_set_current_thread()

void os_set_current_thread

(

Thread_t

new_thread

)

Kernel internal function to override current thread.

DANGEROUS!!!

os_setpriority()

int os_setpriority

(

uint8_t

priority

)

Kernel implementation of setpriority() syscall.

os_stack_create()

int os_stack_create

(

)

Find free stack slot and allocate it.

Returns

If there is at least one free stack slot, then return it's ID. If no free stack is available, return STACK_INVALID constant.

os_stack_dispose()

void os_stack_dispose

(

uint32_t

stack_id

)

Release stack slot.

Parameters

stack_id

Stack slot which should be released.

os_stack_get()

unsigned long * os_stack_get

(

int

stack_id

)

Get address of stack.

Parameters

stack_id

ID of stack

Returns

base address of stack

os_start()

void os_start

(

)

Start up scheduler.

This function populates thread table based on thread autostart macro use. It also creates idle thread with priority 255 and starts scheduler. It never returns until you have very bad day.

os_thread_alloc()

int os_thread_alloc	(	Process_t	process,
		uint8_t	priority
	)

Allocate thread entry in thread table.

Will allocate entry in thread table. Thread won't be runnable after allocation, but thread ID will be reserved for it.

Parameters

process	ID of process owning the thread. Process must be existing already.
priority	tread priority

Returns

Positive values denote thread ID reserved for new thread usable in further calls. Negative value means that there was no free slot in thread table to allocate new thread.

os_thread_construct()

int os_thread_construct	(	Thread_t	tid,
		entrypoint_t *	entrypoint,
		void *	data
	)

Make thread runnable.

This function will take previously allocated thread and will construct it's internal state, so that it is runnable. This includes stack allocation and filling in values, so that thread can be scheduled and run.

Parameters

tid	Thread ID of thread to be constructed
entrypoint	pointer to thread entrypoint function
data	pointer to thread data. pass NULL pointer if no thread data is used

Returns

E_OK if thread was constructed, E_OUT_OF_STACKS if there is no free stack available and E_TASK_RUNNING if thread is not in state suitable for construction (either slot is free, or already constructed).

os_thread_continue()

int os_thread_continue

(

uint8_t

thread_id

)

Kernel implementation of thread_continue() syscall.

os_thread_create()

int os_thread_create	(	entrypoint_t *	entrypoint,
		void *	data,
		uint8_t	priority
	)

Kernel implementation of thread_create() syscall.

Syscall handling thread_create() Creates new thread inside current process using specified entrypoint.

os_thread_dispose()

void os_thread_dispose

(

void

)

Alias to thread_exit.

This is in fact the same function as thread_exit. The only difference is that if for whatever reason syscall to os_thread_exit() will fail, this asserts.

os_thread_exit()

int os_thread_exit

(

int

status

)

Kernel implementation of thread_exit() syscall.

os_thread_get()

struct OS_thread_t * os_thread_get

(

Thread_t

thread_id

)

Get thread descriptor.

Parameters

thread_id

ID of thread

Returns

address of thread description strcture or NULL pointer if thread_id out of range.

os_thread_join()

int os_thread_join

(

uint8_t

thread_id

)

Kernel implementation of thread_join() syscall.

os_thread_kill()

int os_thread_kill	(	uint8_t	thread_id,
		int	status
	)

Kernel way to kill an arbitrary thread.

This call terminates any thread currently existing. There is no syscall for this right now.

Parameters

thread_id	ID of thread to be terminated. May even be thread currently running.
status	thread exit status

Returns

0 if operation succeeded, error number otherwise

os_thread_stop()

int os_thread_stop

(

uint8_t

thread_id

)

Kernel implementation of thread_stop() syscall.

systick_setup()

void systick_setup

(

int

xms

)

Configures systick timer.

Configures systick timer to cause sys_tick_handler to be called periodically.

Parameters

xms	amount of milliseconds between calls.

Variable Documentation

core

struct OS_core_state_t core[OS_NUM_CORES]

static

CPU scheduling thread IDs.

os_processes

struct OS_process_t os_processes[OS_PROCESSES]

List of active processes.

Scheduler notion on existing processes.

os_stacks

struct OS_stack_t os_stacks

Thread stacks.

Scheduler notion on existing stacks.

os_threads

struct OS_thread_t os_threads[OS_THREADS]

List of active threads.

Scheduler notion on existing threads.

sched_microtime

uint32_t sched_microtime = 0

static

Current scheduler real time.

sched_tick_increment

uint32_t sched_tick_increment

extern

Amount of real time advance per one scheduler tick.