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