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>OSSetErrorHandler</TITLE> 9</HEAD> 10<BODY> 11<H1>OSSetErrorHandler</H1> 12<H2>C Specification</H2> 13<DL> 14 <dd><pre><code>#include <revolution/os.h> 15#include <revolution/base/PPCArch.h> 16 17extern u32 __OSFpscrEnableBits; // for OS_ERROR_FPE. OR-ed FPSCR_*E bits 18 19typedef void (*OSErrorHandler)(OSError error, OSContext* context, ...);</code></pre> 20 </dd> 21 <dd><pre><CODE>OSErrorHandler OSSetErrorHandler(OSError error, OSErrorHandler handler);</CODE></pre> 22 </dd> 23</DL> 24<H2>Arguments</H2> 25<TABLE border="1" cellpadding="3" cellspacing="0.1"> 26 <TBODY> 27 <TR> 28<TD width="120" bgcolor="#ffffe8"><CODE><EM><STRONG><CODE><EM><CODE>error</CODE></EM></CODE></STRONG></EM></CODE></TD> 29<TD width="520">Error numbers given in the table below.</TD> 30 </TR> 31 <TR> 32<TD width="120" bgcolor="#ffffe8"><CODE><EM><STRONG><STRONG><EM><CODE>handler</CODE></EM></STRONG></STRONG></EM></CODE></TD> 33<TD width="520">Pointer to the handler to set.</TD> 34 </TR> 35 </TBODY> 36</TABLE> 37<H2>Return Values</H2> 38<P>The handler before the error.</P> 39<H2>Description</H2> 40<p>Implements an error handler of the specified error type. The following error types are defined in <code><os.h></code>.</p> 41<table border="1" style="border-collapse: collapse" bordercolor="#808080" cellpadding="0" cellspacing="0"> 42 <tr> 43<td bgcolor="#C0C0C0">No.<code></td> 44<td bgcolor="#C0C0C0"><code>OSError</code></td> 45<td bgcolor="#C0C0C0">Description</td> 46<td bgcolor="#C0C0C0">Comments</td> 47 </tr> 48 <tr> 49 <td><code>0</code></td> 50<td><code>OS_ERROR_SYSTEM_RESET</code></td> 51<td>System reset exception</td> 52 <td> </td> 53 </tr> 54 <tr> 55 <td><code>1</code></td> 56<td><code>OS_ERROR_MACHINE_CHECK</code></td> 57<td>Machine check exception</td> 58 <td> </td> 59 </tr> 60 <tr> 61 <td><code>2</code></td> 62<td><code>OS_ERROR_DSI</code></td> 63<td>DSI exception</td> 64 <td> </td> 65 </tr> 66 <tr> 67 <td><code>3</code></td> 68<td><code>OS_ERROR_ISI</code></td> 69<td>ISI exception</td> 70 <td> </td> 71 </tr> 72 <tr> 73 <td><code>4</code></td> 74<td><code>OS_ERROR_EXTERNAL_INTERRUPT</code></td> 75<td>External interrupt exception</td> 76<td>(a)</td> 77 </tr> 78 <tr> 79 <td><code>5</code></td> 80<td><code>OS_ERROR_ALIGNMENT</code></td> 81<td>Alignment exception</td> 82 <td> </td> 83 </tr> 84 <tr> 85 <td><code>6</code></td> 86<td><code>OS_ERROR_PROGRAM</code></td> 87<td>Program exception</td> 88<td>(b)</td> 89 </tr> 90 <tr> 91 <td><code>7</code></td> 92<td><code>OS_ERROR_FLOATING_POINT</code></td> 93<td>Floating-point unavailable exception</td> 94<td>(a)</td> 95 </tr> 96 <tr> 97 <td><code>8</code></td> 98<td><code>OS_ERROR_DECREMENTER</code></td> 99<td>Decrementer exception</td> 100<td>(a)</td> 101 </tr> 102 <tr> 103 <td><code>9</code></td> 104<td><code>OS_ERROR_SYSTEM_CALL</code></td> 105<td>System call exception</td> 106<td>(a)</td> 107 </tr> 108 <tr> 109 <td><code>10</code></td> 110<td><code>OS_ERROR_TRACE</code></td> 111<td>Trace exception</td> 112<td>(b)</td> 113 </tr> 114 <tr> 115 <td><code>11</code></td> 116<td><code>OS_ERROR_PERFORMACE_MONITOR</code></td> 117<td>Performance monitor exception</td> 118 <td> </td> 119 </tr> 120 <tr> 121 <td><code>12</code></td> 122<td><code>OS_ERROR_BREAKPOINT</code></td> 123<td>Instruction address break point exception</td> 124<td>(b)</td> 125 </tr> 126 <tr> 127 <td><code>13</code></td> 128<td><code>OS_ERROR_SYSTEM_INTERRUPT</code></td> 129<td>System management interrupt exception</td> 130 <td> </td> 131 </tr> 132 <tr> 133 <td><code>14</code></td> 134<td><code>OS_ERROR_THERMAL_INTERRUPT</code></td> 135<td>Thermal interrupt exception</td> 136 <td> </td> 137 </tr> 138 <tr> 139 <td><code>15</code></td> 140<td><code>OS_ERROR_PROTECTION</code></td> 141<td>Memory protection error</td> 142 <td> </td> 143 </tr> 144 <tr> 145 <td><code>16</code></td> 146<td><code>OS_ERROR_FPE</code></td> 147<td>Floating-point exception</td> 148 <td> </td> 149 </tr> 150</table> 151 152<h3><code>OS_ERROR_SYSTEM_RESET</code> --<code>OS_ERROR_SYSTEM_INTERRUPT</code></h3> 153 154<p>Errors from <code>OS_ERROR_SYSTEM_RESET</code> to <code>OS_ERROR_SYSTEM_INTERRUPT</code> are generated by exceptions that the Broadway processor generates. <code>OSInit</code> sets default error handlers for every error type that writes error messages to the serial output. A game program can overwrite and register the default error handlers if necessary (<em>except those marked with (a) or (b) in the above table</em>; <em>see below</em>).</p> 155 156<p>The <code>OSErrorHandler</code> for these errors takes the third and fourth arguments <em><strong>dsisr</strong></em> and <em><strong>dar</strong></em> as shown below:</p> 157<table border="1" width="100%" cellspacing="1"> 158 159 <tr> 160 <td width="100%"> 161 <pre><code>void (*OSErrorHandler)( OSError <em><strong>error</strong></em>, OSContext* <em><strong>context</strong></em>, 162 u32 <em><strong>dsisr</strong></em>, u32 <em><strong>dar</strong></em> );</code></pre> 163 </td> 164 </tr> 165 166</table> 167<p><code><em><strong>error</strong></em></code> displays the generated error number. <code><em><strong>context</strong></em></code> will have the Broadway register value from the time the error occurred excluding the FPU register context. Because the operating system manages the FPU registers to save context switch overhead, the error handler must not manipulate those registers. <code><em><strong>dsisr</strong></em></code></blink> and <strong><em>dar</em></strong> will have the corresponding Broadway register values from the time the error occurred.</p> 168 169<p><strong><em>(a)</em></strong> Do not set error handlers for <code>OS_ERROR_EXTERNAL_INTERRUPT</code>, <code>OS_ERROR_FLOATING_POINT</code>, <code>OS_ERROR_SYSTEM_CALL</code>, and <code>OS_ERROR_DECREMENTER</code>. These error codes are used by the operating system.</p> 170 171<p><strong><em>(b)</em></strong> Do not set error handlers for <code>OS_ERROR_PROGRAM</code>, <code>OS_ERROR_TRACE</code>, <code>OS_ERROR_BREAKPOINT</code> when using debug. These error codes are used by the debug kernel.</p> 172 173<h3><code>OS_ERROR_PROTECTION</code></h3> 174 175<p><code>OS_ERROR_PROTECTION</code> is generated when Broadway manipulated the memory range from the end of the main memory addresses to 64 megabytes, or when Hollywood detected a memory access violation with the setting specified by <a href="OSProtectRange.html"><code>OSProtectRange</code></a>.</p> 176 177<p>The <code>OSErrorHandler</code> for these errors takes the third and fourth arguments <em><strong>dsisr</strong></em> and <em><strong>dar</strong></em> as shown below:</p> 178<table border="1" width="100%" cellspacing="1"> 179 180 <tr> 181 <td width="100%"> 182<pre></code>// dsisr bits for memory protection error handler, which tells 183// from which region the error was reported 184#define OS_PROTECT0_BIT 0x00000001 // by OS_PROTECT_CHAN0 range 185#define OS_PROTECT1_BIT 0x00000002 // by OS_PROTECT_CHAN1 range 186#define OS_PROTECT2_BIT 0x00000004 // by OS_PROTECT_CHAN2 range 187#define OS_PROTECT3_BIT 0x00000008 // by OS_PROTECT_CHAN3 range 188#define OS_PROTECT_ADDRERR_BIT 0x00000010 // by [24M or 48M, 64M) 189 190void (*OSErrorHandler)( OSError <em><strong>error</strong></em>, OSContext* <em><strong>context</strong></em>, 191 u32 <em><strong>dsisr</strong></em>, u32 <em><strong>dar</strong></em> );</code></pre> 192 </td> 193 </tr> 194 195</table> 196<p><code><em><strong>error</strong></em></code> displays the generated error number (<code>OS_ERROR_PROTECTION</code>). <code><em><strong>context</strong></em></code> will have the Broadway register value from the time the protection error was notified from Hollywood <em>excluding the FPU register context</em>. Because <code>OS_ERROR_PROTECTION</code> is notified asynchronously from Hollywood to Broadway, <code><em><strong>context</strong></em></code> does not contain the register context from the time that the memory protection violation occurred. Because the operating system manages the FPU registers to save context switch overhead, the error handler must not manipulate those registers. <code><em><strong>dar</strong></em></code> contains the physical memory address that violates the memory protection. <code><em><strong>dsisr</strong></em></code> will be <code>OS_PROTECT_ADDRERR_BIT</code> or <code>OS_PROTECT_</code><em>n</em>. 197</p> 198 199<h3><code>OS_ERROR_FPE</code></h3> 200 201<p><code>OS_ERROR_FPE</code> occurs only when error handler is set to <code>OSSetErrorHandler</code>. By setting an <code>OS_ERROR_FPE</code> error handler, floating-point exceptions such as the floating-point zero division can be caught during execution.</p> 202 203<p>The <code>OSErrorHandler</code> for the <code>OS_ERROR_FPE</code> error takes the third and fourth arguments <STRONG><EM><CODE>dsisr</CODE></EM></STRONG> and <STRONG><EM><CODE>dar</CODE></EM></STRONG> as shown below:</p> 204 205<table border="1" width="100%" cellspacing="1"> 206 <tr> 207 <td width="100%"> 208 <pre><code>void (*OSErrorHandler)( OSError <em><strong>error</strong></em>, OSContext* <em><strong>context</strong></em>, 209 u32 <em><strong>dsisr</strong></em>, u32 <em><strong>dar</strong></em> );</code></pre> 210 </td> 211 </tr> 212</table> 213 214<p><code><em><strong>error</strong></em></code> displays the generated error number (<code>OS_ERROR_FPE</code>). <code><em><strong>context</strong></em></code> will have the Broadway register value from the time the floating-point exception occurred including the FPU register context. The error handler can manipulate the FPU register. When the error handler completes processing, this register is reflected to the thread in which the exception occurred. <code><em><strong>dsisr</strong></em></code></blink> and <strong><em>dar</em></strong> will have the corresponding Broadway register values from the time the error occurred. The <code><em><strong>context->fpscr</strong></em></code> bit indicates the floating-point exception types as summarized below:</p> 215 216<table border="1" style="border-collapse: collapse" bordercolor="#808080" cellpadding="0" cellspacing="0"> 217 <tr> 218<td bgcolor="#C0C0C0"><code>fpscr</code> bit </td> 219<td bgcolor="#C0C0C0">Description</td> 220 </tr> 221 <tr> 222<td><code>FPSCR_VX</code></td> 223<td>Invalid operation exception</td> 224 </tr> 225 <tr> 226<td><code>FPSCR_OX</code></td> 227<td>Overflow exception</td> 228 </tr> 229 <tr> 230<td><code>FPSCR_UX</code></td> 231<td>Underflow exception</td> 232 </tr> 233 <tr> 234<td><code>FPSCR_ZX</code></td> 235<td>Zero divide exception</td> 236 </tr> 237 <tr> 238<td><code>FPSCR_XX</code></td> 239<td>Inexact exception</td> 240 </tr> 241</table> 242 243<p>When the error handler is set, the <code>OSSetErrorHandler</code> function sets the MSR[FE0] and MSR[FE1] bits of all threads including threads that will be created afterwards to enable the Broadway precise floating-point exception. The FPSCR bits of each thread are also initialized and bitwise ORed with the <code>__OSFpscrEnableBits</code> global variable. By default, <code>__OSFpscrEnableBits</code> has VE, OE, UE, ZE, and XE bits set (i.e., all bits are enabled). The types of floating-point exceptions that cause <code>OS_ERROR_FPE</code> errors can be controlled by setting a bitwise ORed set of the following enable bits in <code>__OSFpscrEnableBits</code>.</p> 244 245<table border="1" style="border-collapse: collapse" bordercolor="#808080" cellpadding="0" cellspacing="0" height="118"> 246 <tr> 247<td bgcolor="#C0C0C0" height="19"><code>__OSFpscrEnableBits</code> bit </td> 248<td bgcolor="#C0C0C0" height="19">Description</td> 249 </tr> 250 <tr> 251<td height="19"><code>FPSCR_VE</code></td> 252<td height="19">Invalid operation exception enable</td> 253 </tr> 254 <tr> 255<td height="19"><code>FPSCR_OE</code></td> 256<td height="19">Overflow exception enable</td> 257 </tr> 258 <tr> 259<td height="18"><code>FPSCR_UE</code></td> 260<td height="18">Underflow exception enable</td> 261 </tr> 262 <tr> 263<td height="19"><code>FPSCR_ZE</code></td> 264<td height="19">Zero divide exception enable</td> 265 </tr> 266 <tr> 267<td height="19"><code>FPSCR_XE</code></td> 268<td height="19">Inexact exception enable</td> 269 </tr> 270</table> 271 272<p>Once the <code>OS_ERROR_FPE</code> error handler is set, the value of <code>__OSFpscrEnableBits</code> should not be changed until the <code>OS_ERROR_FPE</code> handler is deleted.</p> 273 274 275<p>The example program that shows the use of the <code>OS_ERROR_FPE</code> error handler is under the following path:</p> 276 277<pre><code> $REVOLUTION_SDK_ROOT/build/demos/osdemo/src/fpe.c</code></pre> 278 279<H2>See Also</H2> 280<P><a href="../toc.html#Error" target="contents">Error Functions</a>, <a href="OSProtectRange.html"><code>OSProtectRange</code></a>, <br> IBM Broadway RISC Microprocessor User's Manual<br></P> 281<H2>Revision History</H2> 282<P>2006/03/01 Initial version.</P> 283<hr> 284<P>CONFIDENTIAL</p> 285</BODY> 286</HTML>