1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>OSCreateThread</TITLE> 9</HEAD> 10<BODY> 11<H1>OSCreateThread</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15 <PRE><CODE>#include <revolution/os.h></CODE></PRE> 16 <DD> 17 <PRE><CODE>BOOL OSCreateThread( 18 OSThread* thread, 19 void* (*func)(void*), 20 void* param, 21 void* stackBase, 22 u32 stackSize, 23 OSPriority priority, 24 u16 attribute);</CODE></PRE> 25</DL> 26<H2>Arguments</H2> 27<TABLE border="1" cellpadding="3" cellspacing="0.1"> 28 <TBODY> 29 <TR> 30<TD width="120" bgcolor="#ffffe8"><I><B><CODE>thread</CODE></B></I></TD> 31<TD width="520">Pointer to thread control block to initialize.</TD> 32 </TR> 33 <TR> 34<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>func</CODE></EM></STRONG></CODE></B></I></TD> 35<TD width="520">Pointer to function from which to start execution.</TD> 36 </TR> 37 <TR> 38<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>param</CODE></EM></STRONG></CODE></B></I></TD> 39<TD width="520">Arguments to pass to the start function.</TD> 40 </TR> 41 <TR> 42<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>stackBase</CODE></EM></STRONG></CODE></B></I></TD> 43<TD width="520">Address of initial stack pointer. Note that stacks grow downward so this address should be the highest address in the stack.</TD> 44 </TR> 45 <TR> 46<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>stackSize</CODE></EM></STRONG></CODE></B></I></TD> 47<TD width="520">Size of the stack in bytes. Used to check if the stack is in the correct state.</TD> 48 </TR> 49 <TR> 50<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>priority</CODE></EM></STRONG></CODE></B></I></TD> 51<TD width="520">Base scheduling priority of thread. 0 is the highest priority, and 31 is the lowest.<br>The default thread calling the <code>main()</code> function (created by <a href="../Init/OSInit.html"><code>OSInit()</code></a>) has a priority of 16.</TD> 52 </TR> 53 <TR> 54<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>attribute</CODE></EM></STRONG></CODE></B></I></TD> 55<TD width="520">OR'ed value of attributes. Current valid values: 56 <TABLE border="1" width="500" cellspacing="0.1"> 57 <TBODY> 58 <TR> 59<TD align="left" width="150"><CODE><B>OS_THREAD_ATTR_DETACH</B></CODE></TD> 60<TD width="350">The new thread is invalidated when execution completes.</TD> 61 </TR> 62 <TR> 63 <TD align="left" width="150"><CODE><B>0</B></CODE></TD> 64<TD width="350">The thread control block remains used until another thread is joined to this thread by the <CODE>OSJoinThread</CODE> function.</TD> 65 </TR> 66 </TBODY> 67 </TABLE> 68 </TD> 69 </TR> 70 </TBODY> 71</TABLE> 72<H2>Return Values</H2> 73<P><CODE>TRUE</CODE> if the function succeeds; otherwise, <CODE>FALSE</CODE> (for example, wrong <FONT face="Courier New"><EM><STRONG>priority</STRONG></EM></FONT> value).</P> 74<H2>Description</H2> 75<P>Creates a new thread. At first the created thread is placed in paused mode and must be put in executable mode by calling the <CODE><A href="OSResumeThread.html">OSResumeThread</A></CODE> function.</P> 76<P>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 function <A href="OSCheckActiveThreads.html"><CODE>OSCheckActiveThreads</CODE></A> 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 <CODE>OS_THREAD_STACK_MAGIC</CODE>.</P> 77<P>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.</P> 78<P><STRONG>Note:</STRONG> Be sure to select <CODE>OS_THREAD_ATTR_DETACH</CODE> as the value for <FONT face="Courier New"><EM><STRONG>attribute</STRONG></EM></FONT> 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 <FONT face="Courier New"><EM><STRONG>attribute</STRONG></EM></FONT> is 0), the thread control block will remain used by the operating system until other threads joined to this one (by the <CODE><A href="OSJoinThread.html">OSJoinThread</A></CODE> 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 <CODE><A href="OSDetachThread.html">OSDetachThread</A></CODE> function.</P> 79 80<H2>See Also</H2> 81<P><a href="../toc.html#Thread" target="contents">Thread Synchronization</a>, <a href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</a>, <a href="OSCancelThread.html"><code>OSCancelThread()</code></a>, <a href="OSDetachThread.html"><code>OSDetachThread()</code></a>, <a href="OSExitThread.html"><CODE>OSExitThread()</CODE></a>, <a href="OSResumeThread.html"><CODE>OSResumeThread()</CODE></a>, <a href="OSJoinThread.html"><CODE>OSJoinThread()</CODE></a>, <a href="OSCheckActiveThreads.html"><CODE>OSCheckActiveThreads()</CODE></a></P> 82<H2>Revision History</H2> 83<P> 842007/09/26 Added a note on stack usage by interrupt handlers.<BR>2006/03/01 Initial version.<BR> 85</P> 86<hr><p>CONFIDENTIAL</p></body> 87</HTML>