OSCreateThread

Syntax

#include <cafe/os.h>

typedef int (*OSThread_Proc)(int intArg, void *ptrArg);

BOOL OSCreateThread(OSThread*  thread ,
                    OSThread_Proc entryPoint,
                    int        intArg,
                    void*      ptrArg,
                    void*      stack,
                    u32        stackSize,
                    OSPriority priority,
                    u16        attr);

Parameters

thread Pointer to thread control block to initialize. The alignment of the thread control block is a minimum of 8 bytes.
entryPoint Pointer to function from which to start execution.
intArg Number of arguments to pass to the start function.
ptrArg Arguments to pass to the start function.
stack Address of initial stack pointer.
NOTE:
Stacks grow downward, so this address should be the highest address in the stack.
stackSize Size of the stack in bytes. Used to check whether the stack is in the correct state.
priority Base scheduling priority of thread. 0 is the highest priority, 31 is the lowest. The default thread calling the main function (created by the OSInit function) has a priority of 16 (OS_PRIORITY_APP_DEFAULT).
attr The attributes of a thread are determined from the OR of the bit values listed in the attributes table below. 0 is a special value that indicates that the thread control block remains in use until another thread is joined to this thread using the OSJoinThread function.

Attributes

OS_THREAD_ATTR_DETACH The new thread is deleted when execution completes.
OS_THREAD_ATTR_AFFINITY_CORE0 Specify Core 0 to run the thread.
OS_THREAD_ATTR_AFFINITY_CORE1 Specify Core 1 to run the thread.
OS_THREAD_ATTR_AFFINITY_CORE2 Specify Core 2 to run the thread.
OS_THREAD_ATTR_CHECK_STACK_USE Check for stack usage.
OS_THREAD_ATTR_AFFINITY_NONE Affinity to run on every core.
WARNING:
Do not set thread affinity to OS_THREAD_ATTR_AFFINITY_NONE for any thread that may make a call to any OSDynLoad* function. Loading an RPL can fail if the calling thread has affinity OS_THREAD_ATTR_AFFINITY_NONE.

Return Values

TRUE if the function succeeds. Otherwise, FALSE (for example, an incorrect priority value).

Description

Creates a new thread. The created thread is initially paused and must be put into the executable state by calling the OSResumeThread function.

This function takes the base (upper address) and size of the stack so that a magic word can be written into the last word of the stack. The OSCheckActiveThreads function checks for stack overflows. If unusual behavior is found in the game program, check to see whether the value of the position of the word specified in the thread structure's stackEnd.

NOTE:
Select OS_THREAD_ATTR_DETACH as the value for attr to conform to the Nintendo 64 thread mechanism. This value is set to free the thread control block without failure when thread execution ends. If nothing has been selected as an attribute (if the value of attr equals zero), the operating system continues to use the thread control block until other threads that are joined to this thread using the OSJoinThread function execute at the end. Accordingly, joined threads receive the return value of the thread that has ended. This return value is also useful for debugging because the thread context can be analyzed in the debugger after the thread has stopped. The detached attribute can also be set for a thread using the OSDetachThread function.
CAUTION:
Do not allocate or use an OSThread through an address that was mapped by the OSMapMemory function. For more information, see OSMapMemory.

Do Not Call From

Multiple threads This function is not thread-safe.

See Also

OSDetachThread
OSExitThread
OSResumeThread
OSJoinThread
OSCreateThreadType
OSCheckActiveThreads

Revision History

2014/04/04 Created attribute table.
2014/01/24 Added Caution to Description block.
2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup pass.
2012/05/25 Matched actual header.
2010/08/30 Initial version.


CONFIDENTIAL