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 name="GENERATOR" content="Microsoft FrontPage 5.0">
7<META http-equiv="Content-Style-Type" content="text/css">
8<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
9<title>ASSERT</title>
10</head>
11
12<body>
13
14<h1>ASSERT</h1>
15
16<h2>Syntax</h2>
17<dl><dd><pre class="construction">
18#include &lt;revolution/os.h&gt;
19
20void ASSERT(int expression);
21</pre></dd></dl>
22
23<h2>Arguments</h2>
24<TABLE class="arguments" border="1" >
25  <tr>
26<th>expression</th>
27<td>Conditional expression to check when the <CODE>_DEBUG</CODE> macro is defined.</td>
28  </tr>
29</table>
30
31<h2>Return Values</h2>
32<p>None.</p>
33
34<H2>Description</H2>
35<P>When the <CODE>_DEBUG</CODE> macro is defined, <CODE>ASSERT</CODE> displays an assert failure message if <SPAN class="argument">expression</SPAN> is <code>FALSE</code>. A message that includes the text in <SPAN class="argument">expression</SPAN> is output to the output port, and the program is halted.</P>
36<P>If the <CODE>_DEBUG</CODE> macro is not defined, <CODE>ASSERT</CODE> will do nothing.</P>
37<P><strong>Tips:</strong> By default, the output of the assertion failure message goes to the serial port of the development hardware. In the final phase of game development, you should output to the TV screen rather than the serial port. When an assertion failure occurs, the following <code>OSPanic</code> function in <code>os[D].a</code> is called.</P>
38
39<table border="1" width="100%">
40    <tr>
41    <td width="100%">
42      <pre><CODE>/*---------------------------------------------------------------------------*
43  Name:         OSPanic()
44
45  Description:  Outputs a formatted message into the output port with the
46                file name and line number, and then halts.
47
48  Arguments:    file        should be __FILE__
49                line        should be __LINE__
50                msg         pointer to a null-terminated string that contains
51                            the format specifications
52                ...         optional arguments
53
54  Returns:      None.
55 *---------------------------------------------------------------------------*/
56__declspec(weak) void OSPanic(const char* file, int line, const char* msg, ...)
57{
58    va_list marker;
59    u32     i;
60    u32*    p;
61
62    OSDisableInterrupts();
63    va_start(marker, msg);
64    vprintf(msg, marker);
65    va_end(marker);
66    OSReport(&quot; in \&quot;%s\&quot; on line %d.\n&quot;, file, line);
67
68    // Stack crawl
69    OSReport(&quot;\nAddress:      Back Chain    LR Save\n&quot;);
70    for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
71         p &amp;&amp; (u32) p != 0xffffffff &amp;&amp; i++ &lt; 16;
72         p = (u32*) *p)                         // get caller sp
73    {
74        OSReport(&quot;0x%08x:   0x%08x    0x%08x\n&quot;, p, p[0], p[1]);
75    }
76
77    PPCHalt();
78}</CODE></pre>
79    </td>
80  </tr>
81</table>
82
83<P>It is difficult to implement a generic print function for the TV screen due to various graphics configurations. Therefore, you are free to implement a game-specific version of the <CODE>OSPanic</CODE> function and replace the one implemented in <code>os[D].a</code>. Since the <CODE>OSPanic</CODE> function is defined to be <CODE>weak</CODE> in <CODE>os[D].a</CODE>, the game-specific <CODE>OSPanic</CODE> function takes precedence over the default version in <CODE>os[D].a</code>.</P>
84<P>The following code is an example implementation of the <code>OSPanic</code> function that shows the assertion failure message on TV screen using the <A href="OSFatal.html"><code>OSFatal</code></A> function.</P>
85
86<table border="1" width="100%">
87    <tr>
88    <td width="100%">
89      <pre><CODE>char Message[2048]; // Panic message buffer
90
91void OSPanic(const char* file, int line, const char* msg, ...)
92{
93    va_list marker;
94    u32     i;
95    u32*    p;
96    int     len;
97    GXColor bg = {   0,   0, 255, 0 };
98    GXColor fg = { 255, 255, 255, 0 };
99
100    va_start(marker, msg);
101    len = vsprintf(Message, msg, marker);
102    va_end(marker);
103    len += sprintf(Message + len, &quot; in \&quot;%s\&quot; on line %d.\n&quot;, file, line);
104
105    // Stack crawl
106    len += sprintf(Message + len, &quot;\nAddress:    Back Chain LR Save\n&quot;);
107    for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
108         p &amp;&amp; (u32) p != 0xffffffff &amp;&amp; i++ &lt; 16;
109         p = (u32*) *p)                         // get caller sp
110    {
111        len += sprintf(Message + len, &quot;0x%08x: 0x%08x 0x%08x\n&quot;, p, p[0], p[1]);
112    }
113
114    OSFatal(fg, bg, Message);
115    // NOT REACHED HERE
116}</CODE></pre>
117    </td>
118  </tr>
119
120</table>
121
122<h2>See Also</h2>
123<P class="reference">
124<A href="../toc.html#Error" target="contents">Error Functions</A>,
125<a href="ASSERTMSG.html">ASSERTMSG</a>,
126<a href="OSHalt.html">OSHalt</a>,
127<a href="OSReport.html">OSReport</a>
128</p>
129
130<H2>Revision History</H2>
131<P>
1322006/03/01 Initial version.<br>
133</P>
134
135<hr><p>CONFIDENTIAL</p></body>
136</html>