Description

Functions providing support for manipulation of system execution state.

It is possible to create new threads, wait for other threads to finish or finish currently running thread.

Threads are defined by their entry function, which treated similarly to main() function of a C program. If thread entry function returns, then it's return value is used as thread return status. This is not interpreted by kernel in any way, but it is available for others.

__SYSCALL int	get_tid ()
	Return current thread ID.

__SYSCALL int	thread_create (int(entrypoint)(void ), void *data, uint8_t priority)
	Create new thread.

__SYSCALL int	thread_join (int thread)
	Wait for other thread to finish.

__SYSCALL int	thread_exit (int status)
	Terminate currently running thread.

__SYSCALL int	setpriority (uint8_t priority)
	Change thread priority.

__SYSCALL int	sched_yield ()
	Give up processor.

void	os_thread_dispose (int arg0)
	Internal function, which disposes of thread which called it.

Function Documentation

◆ get_tid()

__SYSCALL int get_tid ( )

Return current thread ID.

Returns: thread ID of currently running thread.

◆ os_thread_dispose()

void os_thread_dispose ( int arg0 )

Internal function, which disposes of thread which called it.

This function is injected into stack (value of LR of thread entrypoint) of each thread, so if thread entry function returns, the thread is disposed automatically. It causes thread to exit with value returned by thread entrypoint to be recorded as thread return value.

Parameters

arg0	value returned by thread entrypoint

◆ sched_yield()

__SYSCALL int sched_yield ( )

Give up processor.

Call to this method cause thread switch. If thread switch occurs, or not, depends on how thread priorities are configured. If there is no other thread ready at equal or higher priority than currently running thread, then switch won't occurr.

Returns: 0. Mostly.

◆ setpriority()

__SYSCALL int setpriority ( uint8_t priority )

Change thread priority.

Allows to change thread priority. Currently it is only possible to change priority of currently running thread. Thread priorities go from highest (numeric value of 0) to idle thread priority (numeric value of 255). It is not recommended to assign priority of 255 to any thread as this priority is used by kernel's idle thread.

Parameters

priority new priority

◆ thread_create()

__SYSCALL int thread_create	(	int()(void )	entrypoint,
		void *	data,
		uint8_t	priority
	)

Create new thread.

Creates new thread and prepares it for scheduling. This routine can be used for on-demand thread creation. New thread will be bound to current process (the one which owns currently running thread). You can set up thread entrypoint, pass it some user data and opt for thread priority.

Parameters

entrypoint	function, which will be called upon thread startup to run the thread
data	user-defined data passed to the entrypoint as first argument @priority priority of newly created thread. Lower numbers mean higher priorities. Thread with priority 0 has realtime priority, thread with priority 255 is an idle thread. Note that there already is one idle thread and if you create another, then outcome most probably won't be as expected. Use priority 254 for custom idle threads.

Returns: non-negative numbers carrying thread ID of newly created thread or negative numbers to signal error.

◆ thread_exit()

__SYSCALL int thread_exit ( int status )

Terminate currently running thread.

This function will explicitly terminate currently running thread. Another way to implicitly terminate running thread is to return from thread entry function. Thread will be terminated automatically using return value as thread exit status in a way similar to how return from main() is used as process exit status.

Parameters

status thread exit status

Returns: You don't want this function to return.

◆ thread_join()

__SYSCALL int thread_join ( int thread )

Wait for other thread to finish.

This function will block calling thread until other thread quits.

Parameters

thread	thread ID of other threads, which this thread wants to fair for
status	place for return value from other thread to be written

Returns: 0 on success (other thread quit and status value is written), error code otherwise.