Native threading API. More...

#include <muteki/common.h>
#include <muteki/errno.h>

Data Structures
struct	threading_waitable_t
	Common data structure for waitables. More...

struct	message_queue_nonatomic_t
	Nonatomic backend storage for message queues. More...

struct	thread_s
	Thread descriptor structure. More...

struct	semaphore_s
	Semaphore descriptor structure. More...

struct	event_s
	Event descriptor structure. More...

struct	critical_section_s
	Critical section descriptor structure. More...

struct	message_queue_s
	Message queue descriptor structure. More...

Typedefs
typedef enum wait_result_e	wait_result_t
	Result of waitables.

typedef int(*	thread_func_t) (void *user_data)
	Thread function type.

typedef char	message_queue_message_t[16]
	Message type for message queues.

typedef struct thread_s	thread_t
	Thread descriptor type.

typedef struct semaphore_s	semaphore_t
	Semaphore descriptor type.

typedef struct event_s	event_t
	Event descriptor type.

typedef struct critical_section_s	critical_section_t
	Critical section descriptor type.

typedef struct message_queue_s	message_queue_t
	Message queue descriptor type.

Enumerations
enum	thread_wait_reason_e { WAIT_ON_NONE = 0x0 , WAIT_ON_SEMAPHORE = 0x1 , WAIT_ON_EVENT = 0x2 , WAIT_ON_QUEUE = 0x4 , WAIT_ON_SUSPEND = 0x8 , WAIT_ON_CRITICAL_SECTION = 0x10 , WAIT_ON_SLEEP = 0x20 }
	Thread wait reason enum. More...

enum	wait_result_e { WAIT_RESULT_TIMEOUT = 0x82 , WAIT_RESULT_RESOLVED , WAIT_RESULT_ERROR }
	Result of waitables. More...

Functions
thread_t *	OSCreateThread (thread_func_t func, void *user_data, size_t stack_size, bool defer_start)
	Create a new thread.

int	OSTerminateThread (thread_t *thr, int exit_code)
	Terminate a thread.

bool	OSSetThreadPriority (thread_t *thr, short new_slot)
	Set the thread priority (slot number).

short	OSGetThreadPriority (thread_t *thr)
	Get the thread priority (slot number).

bool	OSSuspendThread (thread_t *thr)
	Suspend a thread from outside of that thread.

bool	OSResumeThread (thread_t *thr)
	Start/restart a previously suspended thread.

bool	OSWakeUpThread (thread_t *thr)
	Force wake up a sleeping thread.

int	OSExitThread (int exit_code)
	Terminate current thread.

void	OSSleep (short millis)
	Sleep for `millis` milliseconds.

semaphore_t *	OSCreateSemaphore (short init_ctr)
	Create an semaphore descriptor.

wait_result_t	OSWaitForSemaphore (semaphore_t *semaphore, short timeout)
	Wait and acquire a semaphore.

bool	OSReleaseSemaphore (semaphore_t *semaphore)
	Release a semaphore.

bool	OSCloseSemaphore (semaphore_t *semaphore)
	Destroy a semaphore.

event_t *	OSCreateEvent (short latch_on, int flag)
	Create an event descriptor.

wait_result_t	OSWaitForEvent (event_t *event, short timeout)
	Wait for an event.

bool	OSSetEvent (event_t *event)
	Set the event flag.

bool	OSResetEvent (event_t *event)
	Reset the event flag.

bool	OSCloseEvent (event_t *event)
	Destroy the event descriptor.

void	OSInitCriticalSection (critical_section_t *cs)
	Initialize a critical section descriptor.

void	OSEnterCriticalSection (critical_section_t *cs)
	Enter/aquire a critical section.

void	OSLeaveCriticalSection (critical_section_t *cs)
	Leave/release a critical section.

void	OSDeleteCriticalSection (critical_section_t *cs)
	Destroy a critical section descriptor.

message_queue_t *	OSCreateMsgQue (unsigned short size)
	Create a message queue descriptor.

bool	OSPostMsgQue (message_queue_t queue, const message_queue_message_t message)
	Push a message into the queue.

bool	OSSendMsgQue (message_queue_t queue, const message_queue_message_t message)
	Push a message into the queue and reschedule immediately.

bool	OSPeekMsgQue (message_queue_t queue, message_queue_message_t message)
	Peek the bottom of the queue without popping the message.

bool	OSGetMsgQue (message_queue_t queue, message_queue_message_t message)
	Pop a message from the queue.

bool	OSCloseMsgQue (message_queue_t *queue)
	Destroy a message queue descriptor.

short	OSGetCurrentlyRunningTCBPrio (void)
	Get the current running thread's priority (slot number).

Detailed Description

Native threading API.

Typedef Documentation

◆ message_queue_message_t

typedef char message_queue_message_t[16]

Message type for message queues.

This needs to be 4 byte aligned since the inline memcpy in the internal FIFO queue routines use hardcoded ldm/stm.

Enumeration Type Documentation

◆ thread_wait_reason_e

enum thread_wait_reason_e

Thread wait reason enum.

Enumerator
WAIT_ON_NONE	Nothing
WAIT_ON_SEMAPHORE	Waiting on a semaphore.
WAIT_ON_EVENT	Waiting on an event.
WAIT_ON_QUEUE	Waiting for a message queue push.
WAIT_ON_SUSPEND	Waiting to be unsuspended by OSResumeThread().
WAIT_ON_CRITICAL_SECTION	Waiting for a critical section to be released.
WAIT_ON_SLEEP	Waiting for sleep counter to expire.

◆ wait_result_e

enum wait_result_e

Result of waitables.

Enumerator
WAIT_RESULT_TIMEOUT	Timeout before the event is set.
WAIT_RESULT_RESOLVED	The event is set.
WAIT_RESULT_ERROR	An error occurred.

Function Documentation

◆ OSCloseEvent()

bool OSCloseEvent ( event_t * event )

extern

Destroy the event descriptor.

Syscall Number: 0x10011

Parameters

event The event context.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSCloseMsgQue()

bool OSCloseMsgQue ( message_queue_t * queue )

extern

Destroy a message queue descriptor.

Syscall Number: 0x1001d

Parameters

queue The message queue descriptor.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSCloseSemaphore()

bool OSCloseSemaphore ( semaphore_t * semaphore )

extern

Destroy a semaphore.

Syscall Number: 0x1000c

Parameters

semaphore The semaphore context.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSCreateEvent()

event_t * OSCreateEvent	(	short	latch_on,
		int	flag
	)

extern

Create an event descriptor.

Syscall Number: 0x1000d

Parameters

latch_on	Set to non-0 will inhibit the event from getting cleared after a OSWaitForEvent() is resolved.
flag	The initial flag value. Can be either 0 or 1.

Returns: The event descriptor.

◆ OSCreateMsgQue()

message_queue_t * OSCreateMsgQue ( unsigned short size )

extern

Create a message queue descriptor.

Syscall Number: 0x10018

Parameters

size	Size of the queue in number of messages (will use `sizeof(`message_queue_message_t`) * size` bytes of memory).

Returns: The message queue descriptor.

◆ OSCreateSemaphore()

semaphore_t * OSCreateSemaphore ( short init_ctr )

extern

Create an semaphore descriptor.

Syscall Number: 0x10009

Parameters

init_ctr Initial counter value.

Returns: The semaphore descriptor.

◆ OSCreateThread()

thread_t * OSCreateThread	(	thread_func_t	func,
		void *	user_data,
		size_t	stack_size,
		bool	defer_start
	)

extern

Create a new thread.

Syscall Number: 0x10000

Parameters

func	Function to execute in the new thread.
user_data	User data for the thread.
stack_size	The size of the thread stack.
defer_start	Do not immediately schedule this thread and create it as suspended.

Returns: The thread descriptor.

◆ OSDeleteCriticalSection()

void OSDeleteCriticalSection ( critical_section_t * cs )

extern

Destroy a critical section descriptor.

Syscall Number: 0x10015

Parameters

[in,out] cs The critical section descriptor.

Returns: None.

◆ OSEnterCriticalSection()

void OSEnterCriticalSection ( critical_section_t * cs )

extern

Enter/aquire a critical section.

Besta critical sections behave like recursive mutexes. Therefore this will block when multiple threads are trying to enter the same context, but it will let repeated entry attempts initiated by the same thread to pass through. The context is released when all of the entries are reverted by a OSLeaveCriticalSection() call.

Syscall Number: 0x10013

Parameters

[in,out] cs The critical section descriptor.

Returns: None.

◆ OSExitThread()

int OSExitThread ( int exit_code )

extern

Terminate current thread.

Syscall Number: 0x10007

This calls OSTerminateThread() with the descriptor of current thread as thr.

Parameters

exit_code The exit code.

Return values

0	The operation was completed successfully.

◆ OSGetCurrentlyRunningTCBPrio()

short OSGetCurrentlyRunningTCBPrio ( void )

extern

Get the current running thread's priority (slot number).

So far only Pocket Challenge implements this syscall. Calling it on other devices will very likely cause the NOSYS handler to be called, which in turn will crash the system.

On other devices, this can be simulated using mutekix:

#include <muteki/threading.h>
#include <mutekix/threading.h>
 
short OSGetCurrentlyRunningTCBPrio() {
    return OSGetThreadPriority(mutekix_thread_get_current());
}

Requires -lkrnllib when dynamically linking with the shims.

Syscall Number: 0x200a2

Parameters: None.

Returns: The current running thread's priority.

◆ OSGetMsgQue()

bool OSGetMsgQue	(	message_queue_t *	queue,
		message_queue_message_t *	message
	)

extern

Pop a message from the queue.

Syscall Number: 0x1001c

Parameters

queue	The message queue descriptor.
message	The result message.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSGetThreadPriority()

short OSGetThreadPriority ( thread_t * thr )

extern

Get the thread priority (slot number).

Syscall Number: 0x10003

Parameters

thr	The thread descriptor.

Returns: The slot number of the thread.

◆ OSInitCriticalSection()

void OSInitCriticalSection ( critical_section_t * cs )

extern

Initialize a critical section descriptor.

Syscall Number: 0x10012

Parameters

[out] cs The critical section descriptor.

Returns: None.

◆ OSLeaveCriticalSection()

void OSLeaveCriticalSection ( critical_section_t * cs )

extern

Leave/release a critical section.

Syscall Number: 0x10014

Parameters

[in,out] cs The critical section descriptor.

Returns: None.

◆ OSPeekMsgQue()

bool OSPeekMsgQue	(	message_queue_t *	queue,
		message_queue_message_t *	message
	)

extern

Peek the bottom of the queue without popping the message.

Syscall Number: 0x1001b

Parameters

queue	The message queue descriptor.
message	The result message.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSPostMsgQue()

bool OSPostMsgQue	(	message_queue_t *	queue,
		const message_queue_message_t *	message
	)

extern

Push a message into the queue.

Syscall Number: 0x10019

Parameters

queue	The message queue descriptor.
message	The message being pushed.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSReleaseSemaphore()

bool OSReleaseSemaphore ( semaphore_t * semaphore )

extern

Release a semaphore.

Syscall Number: 0x1000b

Parameters

semaphore The semaphore context.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSResetEvent()

bool OSResetEvent ( event_t * event )

extern

Reset the event flag.

This sets the event_t::flag to 0.

Syscall Number: 0x10010

Parameters

event The event context.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSResumeThread()

bool OSResumeThread ( thread_t * thr )

extern

Start/restart a previously suspended thread.

Syscall Number: 0x10005

Parameters

thr	The thread descriptor.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSSendMsgQue()

bool OSSendMsgQue	(	message_queue_t *	queue,
		const message_queue_message_t *	message
	)

extern

Push a message into the queue and reschedule immediately.

Syscall Number: 0x1001a

Parameters

queue	The message queue descriptor.
message	The message being pushed.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSSetEvent()

bool OSSetEvent ( event_t * event )

extern

Set the event flag.

This sets the event_t::flag to 1.

Syscall Number: 0x1000f

Parameters

event The event context.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSSetThreadPriority()

bool OSSetThreadPriority	(	thread_t *	thr,
		short	new_slot
	)

extern

Set the thread priority (slot number).

On Besta RTOS, priority is implied in the natural order of the threads in the global thread table. Some slots in the table seem to be reserved (8 for the top and 18 for the bottom) and are not accessible by just allocating the thread with OSCreateThread(). User can move threads to these reserved slots by calling the OSSetThreadPriority() function.

Syscall Number: 0x10002

Parameters

thr	The thread descriptor.
new_slot	The new slot number.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

See also: OSGetThreadPriority

◆ OSSleep()

void OSSleep ( short millis )

extern

Sleep for millis milliseconds.

Syscall Number: 0x10008

Parameters

millis Time to sleep in milliseconds.

Returns: None.

◆ OSSuspendThread()

bool OSSuspendThread ( thread_t * thr )

extern

Suspend a thread from outside of that thread.

Syscall Number: 0x10004

Parameters

thr	The thread descriptor.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

◆ OSTerminateThread()

int OSTerminateThread	(	thread_t *	thr,
		int	exit_code
	)

extern

Terminate a thread.

Syscall Number: 0x10001

Parameters

thr	Thread to terminate.
exit_code	The exit code.

Return values

0	The operation was completed successfully.

◆ OSWaitForEvent()

wait_result_t OSWaitForEvent	(	event_t *	event,
		short	timeout
	)

extern

Wait for an event.

Syscall Number: 0x1000e

Parameters

event	The event context.
timeout	Timeout in OSSleep() units.

Returns: The result.

See also: wait_result_t

◆ OSWaitForSemaphore()

wait_result_t OSWaitForSemaphore	(	semaphore_t *	semaphore,
		short	timeout
	)

extern

Wait and acquire a semaphore.

Syscall Number: 0x1000a

Parameters

semaphore	The semaphore context.
timeout	Timeout in OSSleep() units.

Returns: The result.

See also: wait_result_t

◆ OSWakeUpThread()

bool OSWakeUpThread ( thread_t * thr )

extern

Force wake up a sleeping thread.

Syscall Number: 0x10006

This expire the sleep counter of a thread immediately and reschedule if the thread is not suspended.

Parameters

thr	The thread descriptor.

Return values

true	The operation was completed successfully.
false	The operation failed with error.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ message_queue_message_t

Enumeration Type Documentation

◆ thread_wait_reason_e

◆ wait_result_e

Function Documentation

◆ OSCloseEvent()

◆ OSCloseMsgQue()

◆ OSCloseSemaphore()

◆ OSCreateEvent()

◆ OSCreateMsgQue()

◆ OSCreateSemaphore()

◆ OSCreateThread()

◆ OSDeleteCriticalSection()

◆ OSEnterCriticalSection()

◆ OSExitThread()

◆ OSGetCurrentlyRunningTCBPrio()

◆ OSGetMsgQue()

◆ OSGetThreadPriority()

◆ OSInitCriticalSection()

◆ OSLeaveCriticalSection()

◆ OSPeekMsgQue()

◆ OSPostMsgQue()

◆ OSReleaseSemaphore()

◆ OSResetEvent()

◆ OSResumeThread()

◆ OSSendMsgQue()

◆ OSSetEvent()

◆ OSSetThreadPriority()

◆ OSSleep()

◆ OSSuspendThread()

◆ OSTerminateThread()

◆ OSWaitForEvent()

◆ OSWaitForSemaphore()

◆ OSWakeUpThread()