1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<title>Reset and Shutdown APIs</title> 9</head> 10 11<body> 12 13<h1>Reset Functions and Shutdown Functions</h1> 14 15<h2>Introduction</h2> 16 17<P>The Revolution SDK provides several functions for executing operations related to system state transitions such as reset/shutdown. An application needs to call these functions as appropriate when it detects that the Reset Button or Power Button has been pressed or when it wants to terminate the execution. </P> 18 19<h2>Functions</h2> 20<dl> 21 <dd> 22 <pre><code> 23void OSRebootSystem(void); 24void OSShutdownSystem(void); 25void OSRestart(u32 resetCode); 26void OSReturnToMenu(void); 27 </code></pre> 28 </dd> 29</dl> 30 31<h2>Description</h2> 32<P>The four functions listed above are provided as APIs for implementing reset/shutdown processing. <A HREF="OSRebootSystem.html"><CODE>OSRebootSystem</CODE></A> restarts the system; <A HREF="OSShutdownSystem.html"><CODE>OSShutdownSystem</CODE></A> shuts down the system; <A HREF="OSRestart.html"><CODE>OSRestart</CODE></A> restarts the current application; and <A HREF="OSReturnToMenu.html"><CODE>OSReturnToMenu</CODE></A> executes processes necessary to return to the system menu. For details on these functions, see the separate function description available for each.</P> 33 34<P>When called, these reset/shutdown functions internally execute processes that terminate each sub-system.</P> 35 36<h2>Caution</h2> 37 38<P>Note the following before calling a reset/shutdown function.</P> 39<BLOCKQUOTE>[Required] Something that can result in a fatal error such as a system hang-up.</BLOCKQUOTE> 40<BLOCKQUOTE> 41<BLOCKQUOTE><em><strong></strong></em><STRONG>Callbacks: </strong></em>An error may occur when a reset/shutdown fuction is called if a user callback/handler that might call any of the following APIs is present.</BLOCKQUOTE> 42</BLOCKQUOTE> 43 44<BLOCKQUOTE><BLOCKQUOTE><BLOCKQUOTE> 45<UL> 46<li>Initialization APIs for audio related libraries (<code>AXInit(), AIInit(), ARInit()</code>, etc.)</li> 47<li>GX API</li> 48</UL> 49</BLOCKQUOTE></BLOCKQUOTE></BLOCKQUOTE> 50<BLOCKQUOTE> 51<BLOCKQUOTE>These Reset/Shutdown functions shut down all subsystems before all interrupts are disabled and all user alarms are canceled. This means that if there's a unfinished asynchronous API or a valid alarm when this function is called, the associated callback/handler can be called after these subsystems are shut down from inside this function. If the callback/handler attempts to use any subsystem after shutdown, it fails and may cause a critical problem (for example, hangup) that depends on the particular subsystem. The above is the list of APIs that can cause a problem. If the system hangs after calling Reset/Shutdown functions, be sure to check if any of the callbacks or handlers are using one of the above APIs. </BLOCKQUOTE> 52</BLOCKQUOTE> 53<BLOCKQUOTE>[Recommended] A recommended item is one that is recommended, but not fatal as reset may be delayed if not implemented. </BLOCKQUOTE> 54<BLOCKQUOTE> 55<BLOCKQUOTE><STRONG>Audio: </strong></em>We <b>strongly recommend</b> that all audio subsystems be terminated before calling a reset/shutdown function. This caution is taken for two reasons. First, it may take time to shut down the audio subsystem from within the API if they are not terminated before the Reset/Shutdown function is called. Second, there is no guarantee that the reset/shutdown function will stop the audio without generating noise. </BLOCKQUOTE> 56</BLOCKQUOTE> 57<BLOCKQUOTE> 58<BLOCKQUOTE><STRONG>NAND Flash, SD Memory Card, GC Memory Card </strong></em>We <b>strongly recommend</b> that reset/shutdown functions not be called until all NAND flash and Memory Card operations are complete. Otherwise, it may take a relatively long time for a hot reset to be issued. This is because the reset/shutdown functions unmount any currently mounted Memory Cards.</BLOCKQUOTE> 59</BLOCKQUOTE> 60<BLOCKQUOTE> 61<BLOCKQUOTE><STRONG>VI: </strong></em> Since it's not guaranteed that frame buffers are kept unchanged during reset/shutdown procedures, it's <b>recommended</b> that the application call <A href="../../vi/VISetBlack.html"><code>VISetBlack(TRUE)</code></a>(and call <A href="../../vi/VIFlush.html"><code>VIFlush()</code></a>, <A href="../../vi/VIWaitForRetrace.html"><code>VIWaitForRetrace()</code></a> to wait until the screen turns into black) . Note that reset/shutdown functions do not call <A href="../../vi/VISetBlack.html"><code>VISetBlack(TRUE)</code></a> inside the API. 62</BLOCKQUOTE> 63</BLOCKQUOTE> 64<BLOCKQUOTE> 65<BLOCKQUOTE><STRONG>Optical Disc Drive: </STRONG>We recommend that any DVD functions not be called before calling a reset/shutdown function. There is no need to call <code>DVDCancel(Async)</code>, <code>DVDCancelAll(Async)</code>, or <code>DVDClose</code> for reset/shutdown. Reset/shutdown functions cancel all optical disc drive requests inside the API. For this reason, it may take a long time to issue a reset/shutdown to cancel them if there are incomplete optical disc drive processes. </BLOCKQUOTE> 66</BLOCKQUOTE> 67<BLOCKQUOTE>[Other Notes]</BLOCKQUOTE> 68<BLOCKQUOTE> 69<BLOCKQUOTE>Reset/shutdown functions suspend the thread scheduler inside the function. Once this API is called, user threads will never be executed.</BLOCKQUOTE> 70</BLOCKQUOTE> 71<BLOCKQUOTE> 72<BLOCKQUOTE>The Revolution SDK does not use the Broadway's segmented address translation mechanism by MMU or access any related registers including SDR1 and SR<i>n</i>. If the application manually activates the segmented address translation mechanism, the register must be reverted to the original state before the restart via <code>OS_RESET_RESTART</code>. Otherwise, unexpected program behavior could occur.</BLOCKQUOTE> 73<BLOCKQUOTE>The contents of all data in memory are not guaranteed if the system is rebooted. </BLOCKQUOTE> 74</BLOCKQUOTE> 75 76<P><strong>CAUTION: </strong>These APIs must not be called from inside a callback. Its behavior in a callback is not guaranteed.</P> 77 78<h2>See Also</h2> 79<P><a target="contents" href="../toc.html#Reset">Reset/Shutdown Functions</a></P> 80 81<H2>Revision History</H2> 82<P>08/10/2006 Initial version.</P> 83 84<hr> 85<P>CONFIDENTIAL</p> 86</BODY> 87</HTML>