Data Structures
struct	OSMutexQueue

struct	OSFastMutexQueue

Macros
#define	OS_THREAD_TAG 0x74487244u

Typedefs
typedef struct OSFastMutex	OSFastMutex

typedef struct OSFastMutexQueue	OSFastMutexQueue

typedef struct OSMutex	OSMutex

typedef struct OSMutexQueue	OSMutexQueue

typedef struct OSThread	OSThread

typedef uint8_t	OSThreadState
	A value from enum OS_THREAD_STATE. More...

typedef uint32_t	OSThreadRequest
	A value from enum OS_THREAD_REQUEST. More...

typedef uint8_t	OSThreadAttributes
	A bitfield of enum OS_THREAD_ATTRIB. More...

typedef int(*	OSThreadEntryPointFn) (int argc, const char **argv)

typedef void(*	OSThreadCleanupCallbackFn) (OSThread thread, void stack)

typedef void(*	OSThreadDeallocatorFn) (OSThread thread, void stack)

Enumerations
enum	OS_THREAD_STATE { OS_THREAD_STATE_NONE = 0, OS_THREAD_STATE_READY = 1 << 0, OS_THREAD_STATE_RUNNING = 1 << 1, OS_THREAD_STATE_WAITING = 1 << 2, OS_THREAD_STATE_MORIBUND = 1 << 3 }

enum	OS_THREAD_REQUEST { OS_THREAD_REQUEST_NONE = 0, OS_THREAD_REQUEST_SUSPEND = 1, OS_THREAD_REQUEST_CANCEL = 2 }

enum	OS_THREAD_ATTRIB { OS_THREAD_ATTRIB_AFFINITY_CPU0 = 1 << 0, OS_THREAD_ATTRIB_AFFINITY_CPU1 = 1 << 1, OS_THREAD_ATTRIB_AFFINITY_CPU2 = 1 << 2, OS_THREAD_ATTRIB_AFFINITY_ANY = ((1 << 0) \| (1 << 1) \| (1 << 2)), OS_THREAD_ATTRIB_DETACHED = 1 << 3, OS_THREAD_ATTRIB_STACK_USAGE = 1 << 5 }

Functions
struct	WUT_ALIGNAS (8) OSThread

void	OSCancelThread (OSThread *thread)
	Cancels a thread. More...

int32_t	OSCheckActiveThreads ()
	Returns the count of active threads. More...

int32_t	OSCheckThreadStackUsage (OSThread *thread)
	Get the maximum amount of stack the thread has used. More...

void	OSClearThreadStackUsage (OSThread *thread)
	Disable tracking of thread stack usage. More...

void	OSContinueThread (OSThread *thread)
	Clears a thread's suspend counter and resumes it. More...

BOOL	OSCreateThread (OSThread thread, OSThreadEntryPointFn entry, int32_t argc, char argv, void *stack, uint32_t stackSize, int32_t priority, OSThreadAttributes attributes)
	Create a new thread. More...

void	OSDetachThread (OSThread *thread)
	Detach thread. More...

void	OSExitThread (int32_t result)
	Exit the current thread with a exit code. More...

void	OSGetActiveThreadLink (OSThread thread, OSThreadLink link)
	Get the next and previous thread in the thread's active queue. More...

OSThread *	OSGetCurrentThread ()
	Return pointer to OSThread object for the current thread. More...

OSThread *	OSGetDefaultThread (uint32_t coreID)
	Returns the default thread for a specific core. More...

uint32_t	OSGetStackPointer ()
	Return current stack pointer, value of r1 register. More...

uint32_t	OSGetThreadAffinity (OSThread *thread)
	Get a thread's affinity. More...

const char *	OSGetThreadName (OSThread *thread)
	Get a thread's name. More...

int32_t	OSGetThreadPriority (OSThread *thread)
	Get a thread's base priority. More...

void *	OSGetThreadSpecific (uint32_t id)
	Get a thread's specific value set by OSSetThreadSpecific. More...

BOOL	OSIsThreadSuspended (OSThread *thread)
	Returns TRUE if a thread is suspended. More...

BOOL	OSIsThreadTerminated (OSThread *thread)
	Returns TRUE if a thread is terminated. More...

BOOL	OSJoinThread (OSThread thread, int threadResult)
	Wait until thread is terminated. More...

int32_t	OSResumeThread (OSThread *thread)
	Resumes a thread. More...

BOOL	OSRunThread (OSThread thread, OSThreadEntryPointFn entry, int argc, const char *argv)
	Run a function on an already created thread. More...

BOOL	OSSetThreadAffinity (OSThread *thread, uint32_t affinity)
	Set a thread's affinity. More...

BOOL	OSSetThreadCancelState (BOOL state)
	Set a thread's cancellation state. More...

OSThreadCleanupCallbackFn	OSSetThreadCleanupCallback (OSThread *thread, OSThreadCleanupCallbackFn callback)
	Set the callback to be called just before a thread is terminated. More...

OSThreadDeallocatorFn	OSSetThreadDeallocator (OSThread *thread, OSThreadDeallocatorFn deallocator)
	Set the callback to be called just after a thread is terminated. More...

void	OSSetThreadName (OSThread thread, const char name)
	Set a thread's name. More...

BOOL	OSSetThreadPriority (OSThread *thread, int32_t priority)
	Set a thread's priority. More...

BOOL	OSSetThreadRunQuantum (OSThread *thread, uint32_t quantum)
	Set a thread's run quantum. More...

void	OSSetThreadSpecific (uint32_t id, void *value)
	Set a thread specific value. More...

BOOL	OSSetThreadStackUsage (OSThread *thread)
	Set thread stack usage tracking. More...

void	OSSleepThread (OSThreadQueue *queue)
	Sleep the current thread and add it to a thread queue. More...

void	OSSleepTicks (OSTime ticks)
	Sleep the current thread for a period of time. More...

uint32_t	OSSuspendThread (OSThread *thread)
	Suspend a thread. More...

void	OSTestThreadCancel ()
	Check to see if the current thread should be cancelled or suspended. More...

void	OSWakeupThread (OSThreadQueue *queue)
	Wake up all threads in queue. More...

void	OSYieldThread ()
	Yield execution to waiting threads with same priority. More...

Detailed Description

Manage and run threads on each of the system's cores.

The thread scheduler in the Wii U uses co-operative scheduling, this is different to the usual pre-emptive scheduling that most operating systems use (such as Windows, Linux, etc). In co-operative scheduling threads must voluntarily yield execution to other threads. In pre-emptive threads are switched by the operating system after an amount of time.

With the Wii U's scheduling model the thread with the highest priority which is in a non-waiting state will always be running (where 0 is the highest priority and 31 is the lowest). Execution will only switch to other threads once this thread has been forced to wait, such as when waiting to acquire a mutex, or when the thread voluntarily yields execution to other threads which have the same priority using OSYieldThread. OSYieldThread will never yield to a thread with lower priority than the current thread.

Data Structure Documentation

◆ OSMutexQueue

struct OSMutexQueue

Definition at line 97 of file thread.h.

Data Fields
OSMutex *	head
OSMutex *	tail
void *	parent

◆ OSFastMutexQueue

struct OSFastMutexQueue

Definition at line 109 of file thread.h.

Data Fields
OSFastMutex *	head
OSFastMutex *	tail

Macro Definition Documentation

◆ OS_THREAD_TAG

#define OS_THREAD_TAG 0x74487244u

Definition at line 118 of file thread.h.

Typedef Documentation

◆ OSFastMutex

typedef struct OSFastMutex OSFastMutex

Definition at line 33 of file thread.h.

◆ OSFastMutexQueue

typedef struct OSFastMutexQueue OSFastMutexQueue

Definition at line 34 of file thread.h.

◆ OSMutex

typedef struct OSMutex OSMutex

Definition at line 35 of file thread.h.

◆ OSMutexQueue

typedef struct OSMutexQueue OSMutexQueue

Definition at line 36 of file thread.h.

◆ OSThread

typedef struct OSThread OSThread

Definition at line 37 of file thread.h.

◆ OSThreadState

typedef uint8_t OSThreadState

A value from enum OS_THREAD_STATE.

Definition at line 40 of file thread.h.

◆ OSThreadRequest

typedef uint32_t OSThreadRequest

A value from enum OS_THREAD_REQUEST.

Definition at line 43 of file thread.h.

◆ OSThreadAttributes

typedef uint8_t OSThreadAttributes

A bitfield of enum OS_THREAD_ATTRIB.

Definition at line 46 of file thread.h.

◆ OSThreadEntryPointFn

typedef int(* OSThreadEntryPointFn) (int argc, const char **argv)

Definition at line 48 of file thread.h.

◆ OSThreadCleanupCallbackFn

typedef void(* OSThreadCleanupCallbackFn) (OSThread *thread, void *stack)

Definition at line 49 of file thread.h.

◆ OSThreadDeallocatorFn

typedef void(* OSThreadDeallocatorFn) (OSThread *thread, void *stack)

Definition at line 50 of file thread.h.

Enumeration Type Documentation

◆ OS_THREAD_STATE

enum OS_THREAD_STATE

Enumerator
OS_THREAD_STATE_NONE
OS_THREAD_STATE_READY	Thread is ready to run.
OS_THREAD_STATE_RUNNING	Thread is running.
OS_THREAD_STATE_WAITING	Thread is waiting, i.e. on a mutex.
OS_THREAD_STATE_MORIBUND	Thread is about to terminate.

Definition at line 52 of file thread.h.

◆ OS_THREAD_REQUEST

enum OS_THREAD_REQUEST

Enumerator
OS_THREAD_REQUEST_NONE
OS_THREAD_REQUEST_SUSPEND
OS_THREAD_REQUEST_CANCEL

Definition at line 69 of file thread.h.

◆ OS_THREAD_ATTRIB

enum OS_THREAD_ATTRIB

Enumerator
OS_THREAD_ATTRIB_AFFINITY_CPU0	Allow the thread to run on CPU0.
OS_THREAD_ATTRIB_AFFINITY_CPU1	Allow the thread to run on CPU1.
OS_THREAD_ATTRIB_AFFINITY_CPU2	Allow the thread to run on CPU2.
OS_THREAD_ATTRIB_AFFINITY_ANY	Allow the thread to run any CPU.
OS_THREAD_ATTRIB_DETACHED	Start the thread detached.
OS_THREAD_ATTRIB_STACK_USAGE	Enables tracking of stack usage.

Definition at line 76 of file thread.h.

Function Documentation

◆ WUT_ALIGNAS()

struct WUT_ALIGNAS ( 8 )

Should always be set to the value OS_THREAD_TAG.

Bitfield of OS_THREAD_STATE

Bitfield of OS_THREAD_ATTRIB

Unique thread ID

Suspend count (increased by OSSuspendThread).

Actual priority of thread.

Base priority of thread, 0 is highest priority, 31 is lowest priority.

Exit value

Queue the thread is currently waiting on

Link used for thread queue

Queue of threads waiting to join this thread

Mutex this thread is waiting to lock

Queue of mutexes this thread owns

Link for global active thread queue

Stack start (top, highest address)

Stack end (bottom, lowest address)

Thread entry point

Thread specific values, accessed with OSSetThreadSpecific and OSGetThreadSpecific.

Thread name, accessed with OSSetThreadName and OSGetThreadName.

The stack pointer passed in OSCreateThread.

Called just before thread is terminated, set with OSSetThreadCleanupCallback

Called just after a thread is terminated, set with OSSetThreadDeallocator

If TRUE then a thread can be cancelled or suspended, set with OSSetThreadCancelState

Current thread request, used for cancelleing and suspending the thread.

Pending suspend request count

Result of thread suspend

Queue of threads waiting for a thread to be suspended.

Definition at line 120 of file thread.h.

◆ OSCancelThread()

void OSCancelThread ( OSThread * thread )

Cancels a thread.

This sets the threads requestFlag to OS_THREAD_REQUEST_CANCEL, the thread will be terminated next time OSTestThreadCancel is called.

◆ OSCheckActiveThreads()

int32_t OSCheckActiveThreads ( )

Returns the count of active threads.

◆ OSCheckThreadStackUsage()

int32_t OSCheckThreadStackUsage ( OSThread * thread )

Get the maximum amount of stack the thread has used.

◆ OSClearThreadStackUsage()

void OSClearThreadStackUsage ( OSThread * thread )

Disable tracking of thread stack usage.

◆ OSContinueThread()

void OSContinueThread ( OSThread * thread )

Clears a thread's suspend counter and resumes it.

◆ OSCreateThread()

BOOL OSCreateThread	(	OSThread *	thread,
		OSThreadEntryPointFn	entry,
		int32_t	argc,
		char *	argv,
		void *	stack,
		uint32_t	stackSize,
		int32_t	priority,
		OSThreadAttributes	attributes
	)

Create a new thread.

Parameters

thread	Thread to initialise.
entry	Thread entry point.
argc	argc argument passed to entry point.
argv	argv argument passed to entry point.
stack	Top of stack (highest address).
stackSize	Size of stack.
priority	Thread priority, 0 is highest priorty, 31 is lowest.
attributes	Thread attributes, see OSThreadAttributes.

◆ OSDetachThread()

void OSDetachThread ( OSThread * thread )

Detach thread.

◆ OSExitThread()

void OSExitThread ( int32_t result )

Exit the current thread with a exit code.

This function is implicitly called when the thread entry point returns.

◆ OSGetActiveThreadLink()

void OSGetActiveThreadLink	(	OSThread *	thread,
		OSThreadLink *	link
	)

Get the next and previous thread in the thread's active queue.

◆ OSGetCurrentThread()

OSThread* OSGetCurrentThread ( )

Return pointer to OSThread object for the current thread.

◆ OSGetDefaultThread()

OSThread* OSGetDefaultThread ( uint32_t coreID )

Returns the default thread for a specific core.

Each core has 1 default thread created before the game boots. The default thread for core 1 calls the RPX entry point, the default threads for core 0 and 2 are suspended and can be used with OSRunThread.

◆ OSGetStackPointer()

uint32_t OSGetStackPointer ( )

Return current stack pointer, value of r1 register.

◆ OSGetThreadAffinity()

uint32_t OSGetThreadAffinity ( OSThread * thread )

Get a thread's affinity.

◆ OSGetThreadName()

const char* OSGetThreadName ( OSThread * thread )

Get a thread's name.

◆ OSGetThreadPriority()

int32_t OSGetThreadPriority ( OSThread * thread )

Get a thread's base priority.

◆ OSGetThreadSpecific()

void* OSGetThreadSpecific ( uint32_t id )

Get a thread's specific value set by OSSetThreadSpecific.

◆ OSIsThreadSuspended()

BOOL OSIsThreadSuspended ( OSThread * thread )

Returns TRUE if a thread is suspended.

◆ OSIsThreadTerminated()

BOOL OSIsThreadTerminated ( OSThread * thread )

Returns TRUE if a thread is terminated.

◆ OSJoinThread()

BOOL OSJoinThread	(	OSThread *	thread,
		int *	threadResult
	)

Wait until thread is terminated.

If the target thread is detached, returns FALSE.

Parameters

thread	Thread to wait for
threadResult	Pointer to store thread exit value in.

Returns: Returns TRUE if thread has terminated, FALSE if thread is detached.

◆ OSResumeThread()

int32_t OSResumeThread ( OSThread * thread )

Resumes a thread.

Decrements the thread's suspend counter, if the counter reaches 0 the thread is resumed.

Returns: Returns the previous value of the suspend counter.

◆ OSRunThread()

BOOL OSRunThread	(	OSThread *	thread,
		OSThreadEntryPointFn	entry,
		int	argc,
		const char **	argv
	)

Run a function on an already created thread.

Can only be used on idle threads.

◆ OSSetThreadAffinity()

BOOL OSSetThreadAffinity	(	OSThread *	thread,
		uint32_t	affinity
	)

Set a thread's affinity.

◆ OSSetThreadCancelState()

BOOL OSSetThreadCancelState ( BOOL state )

Set a thread's cancellation state.

If the state is TRUE then the thread can be suspended or cancelled when OSTestThreadCancel is called.

◆ OSSetThreadCleanupCallback()

OSThreadCleanupCallbackFn OSSetThreadCleanupCallback	(	OSThread *	thread,
		OSThreadCleanupCallbackFn	callback
	)

Set the callback to be called just before a thread is terminated.

◆ OSSetThreadDeallocator()

OSThreadDeallocatorFn OSSetThreadDeallocator	(	OSThread *	thread,
		OSThreadDeallocatorFn	deallocator
	)

Set the callback to be called just after a thread is terminated.

◆ OSSetThreadName()

void OSSetThreadName	(	OSThread *	thread,
		const char *	name
	)

Set a thread's name.

◆ OSSetThreadPriority()

BOOL OSSetThreadPriority	(	OSThread *	thread,
		int32_t	priority
	)

Set a thread's priority.

◆ OSSetThreadRunQuantum()

BOOL OSSetThreadRunQuantum	(	OSThread *	thread,
		uint32_t	quantum
	)

Set a thread's run quantum.

This is the maximum amount of time the thread can run for before being forced to yield.

◆ OSSetThreadSpecific()

void OSSetThreadSpecific	(	uint32_t	id,
		void *	value
	)

Set a thread specific value.

Can be read with OSGetThreadSpecific.

◆ OSSetThreadStackUsage()

BOOL OSSetThreadStackUsage ( OSThread * thread )

Set thread stack usage tracking.

◆ OSSleepThread()

void OSSleepThread ( OSThreadQueue * queue )

Sleep the current thread and add it to a thread queue.

Will sleep until the thread queue is woken with OSWakeupThread.

◆ OSSleepTicks()

void OSSleepTicks ( OSTime ticks )

Sleep the current thread for a period of time.

◆ OSSuspendThread()

uint32_t OSSuspendThread ( OSThread * thread )

Suspend a thread.

Increases a thread's suspend counter, if the counter is >0 then the thread is suspended.

Returns: Returns the thread's previous suspend counter value

◆ OSTestThreadCancel()

void OSTestThreadCancel ( )

Check to see if the current thread should be cancelled or suspended.

This is implicitly called in:

OSLockMutex
OSTryLockMutex
OSUnlockMutex
OSAcquireSpinLock
OSTryAcquireSpinLock
OSTryAcquireSpinLockWithTimeout
OSReleaseSpinLock
OSCancelThread

◆ OSWakeupThread()

void OSWakeupThread ( OSThreadQueue * queue )

Wake up all threads in queue.

Clears the thread queue.

◆ OSYieldThread()

void OSYieldThread ( )

Yield execution to waiting threads with same priority.

This will never switch to a thread with a lower priority than the current thread.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ OSMutexQueue

◆ OSFastMutexQueue

Macro Definition Documentation

◆ OS_THREAD_TAG

Typedef Documentation

◆ OSFastMutex

◆ OSFastMutexQueue

◆ OSMutex

◆ OSMutexQueue

◆ OSThread

◆ OSThreadState

◆ OSThreadRequest

◆ OSThreadAttributes

◆ OSThreadEntryPointFn

◆ OSThreadCleanupCallbackFn

◆ OSThreadDeallocatorFn

Enumeration Type Documentation

◆ OS_THREAD_STATE

◆ OS_THREAD_REQUEST

◆ OS_THREAD_ATTRIB

Function Documentation

◆ WUT_ALIGNAS()

◆ OSCancelThread()

◆ OSCheckActiveThreads()

◆ OSCheckThreadStackUsage()

◆ OSClearThreadStackUsage()

◆ OSContinueThread()

◆ OSCreateThread()

◆ OSDetachThread()

◆ OSExitThread()

◆ OSGetActiveThreadLink()

◆ OSGetCurrentThread()

◆ OSGetDefaultThread()

◆ OSGetStackPointer()

◆ OSGetThreadAffinity()

◆ OSGetThreadName()

◆ OSGetThreadPriority()

◆ OSGetThreadSpecific()

◆ OSIsThreadSuspended()

◆ OSIsThreadTerminated()

◆ OSJoinThread()

◆ OSResumeThread()

◆ OSRunThread()

◆ OSSetThreadAffinity()

◆ OSSetThreadCancelState()

◆ OSSetThreadCleanupCallback()

◆ OSSetThreadDeallocator()

◆ OSSetThreadName()

◆ OSSetThreadPriority()

◆ OSSetThreadRunQuantum()

◆ OSSetThreadSpecific()

◆ OSSetThreadStackUsage()

◆ OSSleepThread()

◆ OSSleepTicks()

◆ OSSuspendThread()

◆ OSTestThreadCancel()

◆ OSWakeupThread()

◆ OSYieldThread()