Native threading API. More...

#include "common.h"
#include "errno.h"

Data Structures
struct	bxc_waitable_t
	Common data structure for waitables. More...
struct	bxc_queue_nonatomic_t
	Nonatomic backend storage for message queues. More...
struct	bxc_thread_s
	Thread descriptor structure. More...
struct	bxc_semaphore_s
	Semaphore descriptor structure. More...
struct	bxc_event_s
	Event descriptor structure. More...
struct	bxc_cs_s
	Critical section descriptor structure. More...
struct	bxc_queue_s
	Message queue descriptor structure. More...
union	bxc_waitable_desc_u
	Generic waitable descriptor. More...

Typedefs
typedef enum bxc_wait_result_e	bxc_wait_result_t
	Result of waitables.
typedef int(*)	bxc_thread_func_t(void *user_data)
	Thread function type.
typedef unsigned char	bxc_queue_message_t[16]
	Message type for message queues.
typedef struct bxc_thread_s	bxc_thread_t
	Thread descriptor type.
typedef struct bxc_semaphore_s	bxc_semaphore_t
	Semaphore descriptor type.
typedef struct bxc_event_s	bxc_event_t
	Event descriptor type.
typedef struct bxc_cs_s	bxc_cs_t
	Critical section descriptor type.
typedef struct bxc_queue_s	bxc_queue_t
	Message queue descriptor type.
typedef union bxc_waitable_desc_u	bxc_waitable_desc_t
	Waitable object union used by bxc_thread_t.

Enumerations
enum	bxc_wait_reason_e { BXC_WAIT_ON_NONE = 0x0 , BXC_WAIT_ON_SEMAPHORE = 0x1 , BXC_WAIT_ON_EVENT = 0x2 , BXC_WAIT_ON_QUEUE = 0x4 , BXC_WAIT_ON_SUSPEND = 0x8 , BXC_WAIT_ON_CRITICAL_SECTION = 0x10 , BXC_WAIT_ON_SLEEP = 0x20 , BXC_WAIT_ON_YIELD = 0x20 }
	Thread wait reason enum. More...
enum	bxc_threading_kind_e { BXC_THREADING_KIND_THREAD = 0x100 , BXC_THREADING_KIND_SEMAPHORE = 0x200 , BXC_THREADING_KIND_EVENT = 0x201 , BXC_THREADING_KIND_CS_QUEUE = 0x202 }
	Runtime threading descriptor kind code. More...
enum	bxc_wait_result_e { BXC_WAIT_RESULT_TIMEOUT = 0x82 , BXC_WAIT_RESULT_RESOLVED , BXC_WAIT_RESULT_ERROR }
	Result of waitables. More...

Functions
bxc_thread_t *	OSCreateThread (bxc_thread_func_t func, void *user_data, size_t stack_size, bool defer_start)
	Create a new thread.
int	OSTerminateThread (bxc_thread_t *thr, int exit_code)
	Terminate a thread.
bool	OSSetThreadPriority (bxc_thread_t *thr, short new_slot)
	Set the thread priority (slot number).
short	OSGetThreadPriority (bxc_thread_t *thr)
	Get the thread priority (slot number).
bool	OSSuspendThread (bxc_thread_t *thr)
	Suspend a thread from outside of that thread.
bool	OSResumeThread (bxc_thread_t *thr)
	Start/restart a previously suspended thread.
bool	OSWakeUpThread (bxc_thread_t *thr)
	Force wake up a sleeping thread.
int	OSExitThread (int exit_code)
	Terminate current thread.
void	OSSleep (short time_units)
	Sleep for number of scheduler `time_units` .
bxc_semaphore_t *	OSCreateSemaphore (short init_ctr)
	Create an semaphore descriptor.
bxc_wait_result_t	OSWaitForSemaphore (bxc_semaphore_t *semaphore, short timeout)
	Wait and acquire a semaphore.
bool	OSReleaseSemaphore (bxc_semaphore_t *semaphore)
	Release a semaphore.
bool	OSCloseSemaphore (bxc_semaphore_t *semaphore)
	Destroy a semaphore.
bxc_event_t *	OSCreateEvent (short latch_on, int flag)
	Create an event descriptor.
bxc_wait_result_t	OSWaitForEvent (bxc_event_t *event, short timeout)
	Wait for an event.
bool	OSSetEvent (bxc_event_t *event)
	Set the event flag.
bool	OSResetEvent (bxc_event_t *event)
	Reset the event flag.
bool	OSCloseEvent (bxc_event_t *event)
	Destroy the event descriptor.
void	OSInitCriticalSection (bxc_cs_t *cs)
	Initialize a critical section descriptor.
void	OSEnterCriticalSection (bxc_cs_t *cs)
	Enter/aquire a critical section.
void	OSLeaveCriticalSection (bxc_cs_t *cs)
	Leave/release a critical section.
void	OSDeleteCriticalSection (bxc_cs_t *cs)
	Destroy a critical section descriptor.
bxc_queue_t *	OSCreateMsgQue (unsigned short size)
	Create a message queue descriptor.
bool	OSPostMsgQue (bxc_queue_t queue, const bxc_queue_message_t message)
	Push a message into the queue.
bool	OSSendMsgQue (bxc_queue_t queue, const bxc_queue_message_t message)
	Push a message into the queue and reschedule immediately.
bool	OSPeekMsgQue (bxc_queue_t queue, bxc_queue_message_t message)
	Pop a message from the queue asynchronously.
bool	OSGetMsgQue (bxc_queue_t queue, bxc_queue_message_t message)
	Pop a message from the queue.
bool	OSCloseMsgQue (bxc_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

◆ bxc_queue_message_t

typedef unsigned char bxc_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

◆ bxc_threading_kind_e

enum bxc_threading_kind_e

Runtime threading descriptor kind code.

Enumerator
BXC_THREADING_KIND_THREAD	Thread.
BXC_THREADING_KIND_SEMAPHORE	Semaphore.
BXC_THREADING_KIND_EVENT	Event.
BXC_THREADING_KIND_CS_QUEUE	Critical section or queue.

◆ bxc_wait_reason_e

enum bxc_wait_reason_e

Thread wait reason enum.

Enumerator
BXC_WAIT_ON_NONE	Nothing.
BXC_WAIT_ON_SEMAPHORE	Waiting on a semaphore.
BXC_WAIT_ON_EVENT	Waiting on an event.
BXC_WAIT_ON_QUEUE	Waiting for a message queue push.
BXC_WAIT_ON_SUSPEND	Waiting to be unsuspended by OSResumeThread().
BXC_WAIT_ON_CRITICAL_SECTION	Waiting for a critical section to be released.
BXC_WAIT_ON_SLEEP	Deprecated name of ::BXC_WAIT_ON_TIMEOUT. Deprecated
BXC_WAIT_ON_YIELD	Waiting to take back control after a yield/timeout. This can either mean the thread has yielded voluntarily by calling OSSleep(0) from itself, or that the thread execution is temporarily on hold because it has timed out.

◆ bxc_wait_result_e

enum bxc_wait_result_e

Result of waitables.

Enumerator
BXC_WAIT_RESULT_TIMEOUT	Timeout before the event is set.
BXC_WAIT_RESULT_RESOLVED	The event is set.
BXC_WAIT_RESULT_ERROR	An error occurred.

Function Documentation

◆ OSCloseEvent()

bool OSCloseEvent ( bxc_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 ( bxc_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 ( bxc_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()

bxc_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()

bxc_queue_t * OSCreateMsgQue ( unsigned short size )

extern

Create a message queue descriptor.

Effective queue size will be size - 1 due to how the internal ring buffer implementation tracks usage.

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

bxc_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()

bxc_thread_t * OSCreateThread	(	bxc_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 ( bxc_cs_t * cs )

extern

Destroy a critical section descriptor.

This does not ensure that the critical section's users are properly notified. Therefore one must ensure that no thread is waiting on the critical section before attempting to call this function on it.

Syscall Number: 0x10015

Parameters

[in,out] cs The critical section descriptor.

Returns: None.

◆ OSEnterCriticalSection()

void OSEnterCriticalSection ( bxc_cs_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	(	bxc_queue_t *	queue,
		bxc_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 ( bxc_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 ( bxc_cs_t * cs )

extern

Initialize a critical section descriptor.

Syscall Number: 0x10012

Parameters

[out] cs The critical section descriptor.

Returns: None.

◆ OSLeaveCriticalSection()

void OSLeaveCriticalSection ( bxc_cs_t * cs )

extern

Leave/release a critical section.

Syscall Number: 0x10014

Parameters

[in,out] cs The critical section descriptor.

Returns: None.

◆ OSPeekMsgQue()

bool OSPeekMsgQue	(	bxc_queue_t *	queue,
		bxc_queue_message_t *	message )

extern

Pop a message from the queue asynchronously.

Warning: This is a destructive operation despite the name may suggest that it is not.

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	(	bxc_queue_t *	queue,
		const bxc_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 ( bxc_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 ( bxc_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 ( bxc_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	(	bxc_queue_t *	queue,
		const bxc_queue_message_t *	message )

extern

Push a message into the queue and reschedule immediately.

This results in the thread receiving a message

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 ( bxc_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	(	bxc_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 time_units )

extern

Sleep for number of scheduler time_units .

A time unit is typically around 1ms on Besta RTOS, but this could fluctuate in practice.

When time_units is set to 0, the current thread will yield (voluntarily put itself into the "timed out" state) by clearing the bxc_thread_t::timeout value, and will resume execution after the scheduler goes to idle.

Syscall Number: 0x10008

Parameters

time_units Time to sleep in scheduler time units.

Returns: None.

◆ OSSuspendThread()

bool OSSuspendThread ( bxc_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	(	bxc_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()

bxc_wait_result_t OSWaitForEvent	(	bxc_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.

◆ OSWaitForSemaphore()

bxc_wait_result_t OSWaitForSemaphore	(	bxc_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.

◆ OSWakeUpThread()

bool OSWakeUpThread ( bxc_thread_t * thr )

extern

Force wake up a sleeping thread.

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

Syscall Number: 0x10006

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

◆ bxc_queue_message_t

Enumeration Type Documentation

◆ bxc_threading_kind_e

◆ bxc_wait_reason_e

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