Kernel primitives for manipulating threads. More...

Macros
#define	STACK_ALIGN

#define	PRIORITY_INVALID 0x1FFU

#define	PRIORITY_MAX 0xFFU

#define	STACK_INVALID 0xFFFFFFFFU

#define	KERNEL_STRUCTS_INITIALIZED_SIGNATURE 0x434D5258

Typedefs
typedef uint8_t	Thread_t

Functions
int	os_thread_alloc (Process_t process, uint8_t priority)
	Allocate thread entry in thread table.

int	__os_thread_create (Process_t process, entrypoint_t entrypoint, void data, uint8_t priority, uint8_t core)
	Full workflow needed to create a thread.

bool	os_get_next_thread (uint8_t current_thread, uint8_t *next_thread)
	Obtain next thread to run.

int	os_sched_yield (void)
	Kernel implementation of sched_yield() syscall.

long	os_sched_timing_callback (long delay_us)
	Kernel callback for timing provider.

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.

uint8_t	os_get_current_process (void)
	Kernel implementation of get_pid.

uint32_t	os_get_micro_time (void)
	Get amount of microseconds elapsed since scheduler start.

int	os_idle_thread (void *data)
	CMRX idle thread.

int	os_stack_create ()
	Find free stack slot and allocate it.

uint32_t *	os_stack_get (int stack_id)
	Get address of stack.

void	os_stack_dispose (uint32_t stack_id)
	Release stack slot.

int	os_thread_exit (int status)
	Kernel implementation of thread_exit() syscall.

int	os_thread_kill (uint8_t thread_id, int status)
	Kernel way to kill an arbitrary thread.

int	os_thread_stop (uint8_t thread_id)
	Kernel implementation of thread_stop() syscall.

struct OS_thread_t *	os_thread_by_id (Thread_t id)

int	os_thread_set_ready (struct OS_thread_t *thread)

int	os_thread_continue (uint8_t thread_id)
	Kernel implementation of thread_continue() syscall.

int	os_setpriority (uint8_t priority)
	Kernel implementation of setpriority() syscall.

static void	cb_thread_join_notify (const void *object, Thread_t thread, int sleeper_id, Event_t event)

int	os_thread_join (uint8_t thread_id)
	Kernel implementation of thread_join() syscall.

int	os_thread_construct (Thread_t tid, entrypoint_t entrypoint, void data, uint8_t core)
	Make thread runnable.

int	os_thread_create (entrypoint_t entrypoint, void data, uint8_t priority)
	Syscall handling thread_create() Creates new thread inside current process using specified entrypoint.

void	_os_start (uint8_t start_core)
	Start up scheduler.

uint32_t	os_shutdown ()
	Kernel implementation of the shutdown() syscall.

struct OS_thread_t *	os_thread_get (Thread_t thread_id)
	Get thread descriptor.

int	os_thread_migrate (uint8_t thread_id, int target_core)
	Migrate thread between CPU cores.

void	os_thread_dispose (void)
	Alias to thread_exit.

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.

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.

struct OS_core_state_t	core [OS_NUM_CORES]
	CPU scheduling thread IDs.

Detailed Description

Kernel primitives for manipulating threads.

Macro Definition Documentation

◆ KERNEL_STRUCTS_INITIALIZED_SIGNATURE

#define KERNEL_STRUCTS_INITIALIZED_SIGNATURE 0x434D5258

◆ 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,
		uint8_t	core
	)

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
core	core on which thread will be created

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

◆ _os_start()

void _os_start ( uint8_t start_core )

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.

Parameters

[in] start_core number of core for which the kernel is started

◆ cb_thread_join_notify()

static void cb_thread_join_notify	(	const void *	object,
		Thread_t	thread,
		int	sleeper_id,
		Event_t	event
	)

static

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

uint32_t os_shutdown ( void )

Kernel implementation of the shutdown() 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()

uint32_t * os_stack_get ( int stack_id )

Get address of stack.

Parameters

stack_id ID of stack

Returns: base address of stack

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

struct OS_thread_t * os_thread_by_id ( Thread_t id )

◆ os_thread_construct()

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

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
core	ID of core the thread should run at

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 )

Kernel implementation of thread_continue() syscall.

◆ os_thread_create()

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

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

Kernel implementation of thread_create() syscall.

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

int os_thread_migrate	(	uint8_t	thread_id,
		int	target_core
	)

Migrate thread between CPU cores.

This function takes existing thread which is bound to some core and moved it over to scheduler queue of another core. In order for this call to be successful, the thread must already be stopped. If thread is woken up by e.g. signal arrived from interrupt service handler via isr_kill() while this call is in progress then the call will fail.

Parameters

thread_id	ID of thread to be migrated
target_core	ID of core where the thread should be migrated.

Returns: E_OK if thread was migrated; E_INVALID if thread is not stopped or call is not made from the core at which the thread is currently running.

◆ os_thread_set_ready()

int os_thread_set_ready ( struct OS_thread_t * thread )

◆ os_thread_stop()

int os_thread_stop ( uint8_t thread )

Kernel implementation of thread_stop() syscall.

Variable Documentation

◆ core [1/2]

struct OS_core_state_t core[OS_NUM_CORES]

CPU scheduling thread IDs.

◆ core [2/2]

struct OS_core_state_t core[OS_NUM_CORES]

extern

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.

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ KERNEL_STRUCTS_INITIALIZED_SIGNATURE

◆ PRIORITY_INVALID

◆ PRIORITY_MAX

◆ STACK_ALIGN

◆ STACK_INVALID

Typedef Documentation

◆ Thread_t

Function Documentation

◆ __os_thread_create()

◆ _os_start()

◆ cb_thread_join_notify()

◆ os_get_current_process()

◆ os_get_current_stack()

◆ os_get_current_thread()

◆ os_get_micro_time()

◆ os_get_next_thread()

◆ os_idle_thread()

◆ os_sched_timing_callback()

◆ os_sched_yield()

◆ os_set_current_thread()

◆ os_setpriority()

◆ os_shutdown()

◆ os_stack_create()

◆ os_stack_dispose()

◆ os_stack_get()

◆ os_thread_alloc()

◆ os_thread_by_id()

◆ os_thread_construct()

◆ os_thread_continue()

◆ os_thread_create()

◆ os_thread_dispose()

◆ os_thread_exit()

◆ os_thread_get()

◆ os_thread_join()

◆ os_thread_kill()

◆ os_thread_migrate()

◆ os_thread_set_ready()

◆ os_thread_stop()

Variable Documentation

◆ core [1/2]

◆ core [2/2]

◆ os_processes

◆ os_stacks

◆ os_threads

◆ sched_microtime

◆ sched_tick_increment