OSCreateThread

Syntax

#include <revolution/os.h>

BOOL OSCreateThread(
    OSThread*  thread,
    void*    (*func)(void*),
    void*      param,
    void*      stackBase,
    u32        stackSize,
    OSPriority priority,
    u16        attribute);

Arguments

thread Pointer to thread control block to initialize.

func Pointer to function from which to start execution.

param Arguments to pass to the start function.

stackBase Address of initial stack pointer. Note that stacks grow downward so this address should be the highest address in the stack.

stackSize Size of the stack in bytes. Used to check if 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, which calls the main function (and is created with the OSInit function), has a priority of 16.

attribute

OR'ed value of attributes. Current valid values:

OS_THREAD_ATTR_DETACH	The new thread is invalidated when execution completes.
0	The thread control block remains used until another thread is joined to this thread by the `OSJoinThread` function.

Return Values

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

Description

Creates a new thread. At first the created thread is placed in paused mode and must therefore be put in executable mode by calling the OSResumeThread function.

This function takes the base (highest 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 that the stack does not overflow. If the program is found to be behaving oddly, be sure to check that the value of the word specified by "stackEnd" in the thread structure matches OS_THREAD_STACK_MAGIC.

In Revolution OS, the current thread's stack is used when interrupt handlers run. Therefore, you must configure the stack size with some extra space taken into account.

Note: Be sure to select OS_THREAD_ATTR_DETACH as the value for attribute in order to match the thread mechanism used by the NINTENDO64 (N64). This is done so that the thread control block is actually freed quickly when thread execution ends. If nothing has been selected as an attribute (if the value of attribute is 0), the thread control block will remain used by the operating system until other threads joined to this one (by the OSJoinThread function) have finished executing. Accordingly, threads joined later take the return value of the thread that has terminated. This is also useful for debugging, as the context of the thread can be analyzed in the debugger after it has terminated. The "detached" attribute can also be set for a thread using the OSDetachThread function.

Revision History

2007/09/26 Added a note on stack usage by interrupt handlers.
2006/03/01 Initial version.