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>C Specification</h2>
17
18<dl>
19<dd><pre><code>#include &lt;revolution/os.h&gt;</code></pre>
20  </dd>
21<dd><pre><code>void ASSERT(int <em>expression</em>);</code></pre>
22  </dd>
23</dl>
24
25<h2>Arguments</h2>
26
27<table border="1" cellpadding="3" cellspacing="0.1">
28  <tr>
29<td width="120" bgcolor="#ffffe8"><code><strong><em><STRONG><EM><CODE>expression</CODE></EM></STRONG></em></strong></code></td>
30<td width="520">Conditional expression used for checking if the <CODE>_DEBUG</CODE> macro is defined. </td>
31  </tr>
32</table>
33
34<h2>Return Values</h2>
35
36<p>None.</p>
37<H2>Description</H2>
38<P>When the <code>_DEBUG</code> macro is defined, the <code>ASSERT</code> function displays a failure message if <code><strong><em>expression</em></strong></code> is <CODE>FALSE</CODE>.&nbsp;The message that contains the text of <code><strong><em>expression</em></strong></code> appears in the output port, and the console is halted.</P>
39<P>If the <code>_DEBUG</code> macro is not defined, <code>ASSERT</code> does nothing.</P>
40<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, output to the TV screen rather than the serial port may be more desirable. When an assertion fails, the <code>OSPanic</code> function shown below&nbsp;in <code>os[D].a</code> is called.</P>
41<table border="1" width="100%">
42
43    <tr>
44    <td width="100%">
45      <pre><CODE>/*---------------------------------------------------------------------------*
46Name: OSPanic()
47
48Description: Outputs a formatted message into the output port with the
49file name and the line number. And then halts.
50
51Arguments: file        should be __FILE__
52line        should be __LINE__
53msg         pointer to a null-terminated string that contains
54the format specifications
55...         optional arguments
56
57Returns: None.
58 *---------------------------------------------------------------------------*/
59__declspec(weak) void OSPanic(const char* file, int line, const char* msg, ...)
60{
61va_list marker;
62u32     i;
63u32*    p;
64
65OSDisableInterrupts();
66va_start(marker, msg);
67vprintf(msg, marker);
68va_end(marker);
69OSReport(&quot; in \&quot;%s\&quot; on line %d.\n&quot;, file, line);
70
71// Stack crawl
72OSReport(&quot;\nAddress: Back Chain LR Save\n&quot;);
73for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
74p &amp;&amp; (u32) p != 0xffffffff &amp;&amp; i++ &lt; 16;
75p = (u32*) *p)                         // get caller sp
76    {
77OSReport(&quot;0x%08x: 0x%08x 0x%08x\n&quot;, p, p[0], p[1]);
78    }
79
80PPCHalt();
81}</CODE></pre>
82    </td>
83  </tr>
84
85</table>
86<P>Since it is difficult to implement standard output function for the TV screen due to the various graphics configurations, it is acceptable to implement the game-specific version of <code>OSPanic</code> and to replace the one in <code>os[D].a</code>. Because the <code>OSPanic</code> function is weakly defined in <code>os[D].a</code>, the game-specific <code>OSPanic</code> function takes precedence over the default <code>OSPanic</code> in <code>os[D].a</code>.</P>
87<P>The following code is an implementation example of the <code>OSPanic</code> function that shows the assertion failure message on a TV screen using the <code><a href="OSFatal.html">OSFatal</a></code> function.</P>
88<table border="1" width="100%">
89
90    <tr>
91    <td width="100%">
92<pre>char Message[2048]; // Panic message buffer
93
94void OSPanic(const char* file, int line, const char* msg, ...)
95{
96va_list marker;
97u32     i;
98u32*    p;
99int     len;
100GXColor bg = {   0,   0, 255, 0 };
101GXColor fg = { 255, 255, 255, 0 };
102
103va_start(marker, msg);
104len = vsprintf(Message, msg, marker);
105va_end(marker);
106len += sprintf(Message + len, &quot; in \&quot;%s\&quot; on line %d.\n&quot;, file, line);
107
108// Stack crawl
109len += sprintf(Message + len, &quot;\nAddress: Back Chain LR Save\n&quot;);
110for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
111p &amp;&amp; (u32) p != 0xffffffff &amp;&amp; i++ &lt; 16;
112p = (u32*) *p)                         // get caller sp
113    {
114len += sprintf(Message + len, &quot;0x%08x: 0x%08x 0x%08x\n&quot;, p, p[0], p[1]);
115    }
116
117OSFatal(fg, bg, Message);
118// NOT REACHED HERE
119}</CODE></pre>
120    </td>
121  </tr>
122
123</table>
124
125
126
127<h2>See Also</h2>
128
129<p><a href="../list.html#Error" target="contents">Error Functions</a>, <code><a href="ASSERTMSG.html">ASSERTMSG</a></code>,<code> <a href="OSHalt.html">OSHalt</a></code>,<code><a href="OSReport.html">OSReport</a></code> </p>
130<H2>Revision History</H2>
131<P>03/01/2006 Initial version.</P>
132</body>
133</html>