OSSetErrorHandler

Syntax

#include <revolution/os.h>
#include <revolution/base/PPCArch.h>

extern u32 __OSFpscrEnableBits;  // for OS_ERROR_FPE. OR-ed FPSCR_*E bits

typedef void (*OSErrorHandler)(OSError error, OSContext* context, ...);

OSErrorHandler OSSetErrorHandler(OSError error, OSErrorHandler handler);

Arguments

Return Values

The handler before the error.

Description

Implements an error handler for the specified error type. The following error types are defined in <os.h>.

OS_ERROR_SYSTEM_RESET ~ OS_ERROR_SYSTEM_INTERRUPT

Errors from OS_ERROR_SYSTEM_RESET to OS_ERROR_SYSTEM_INTERRUPT are issued by exceptions generated by the Broadway processor. The OSInit 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.)

The OSErrorHandler for these errors takes the following dsisr and dar as third and fourth arguments.

void (*OSErrorHandler)( OSError error, OSContext* context, 
                        u32 dsisr, u32 dar );

error indicates the generated error number. context contains the Broadway register value at the time the error was incurred, excluding the FPU register context. Because the operating system manages the FPU registers to reduce context switch overhead, the error handler must not manipulate those registers. dsisr and dar contain the Broadway register values corresponding to the time the error occurred.

(a) Do not set error handlers for OS_ERROR_EXTERNAL_INTERRUPT, OS_ERROR_FLOATING_POINT, OS_ERROR_SYSTEM_CALL, and OS_ERROR_DECREMENTER. These error codes are used by the operating system.

(b) Do not set error handlers for OS_ERROR_PROGRAM, OS_ERROR_TRACE, OS_ERROR_BREAKPOINT when using the debugger. These error codes are used by the debug kernel.

OS_ERROR_PROTECTION

OS_ERROR_PROTECTION 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 OSProtectRange.

The OSErrorHandler for these errors takes the following dsisr and dar as third and fourth arguments.

// dsisr bits for memory protection error handler, which tells
// from which region the error was reported
#define OS_PROTECT0_BIT             0x00000001  // by OS_PROTECT_CHAN0 range
#define OS_PROTECT1_BIT             0x00000002  // by OS_PROTECT_CHAN1 range
#define OS_PROTECT2_BIT             0x00000004  // by OS_PROTECT_CHAN2 range
#define OS_PROTECT3_BIT             0x00000008  // by OS_PROTECT_CHAN3 range
#define OS_PROTECT_ADDRERR_BIT      0x00000010  // by [24M or 48M, 64M)

void (*OSErrorHandler)( OSError error, OSContext* context, 
                        u32 dsisr, u32 dar );

error indicates the generated error number (OS_ERROR_PROTECTION). context contains all the Broadway register values at the time the protection error notification was received from Hollywood, excluding the FPU register context. Since OS_ERROR_PROTECTION is an asynchronous notification sent from Hollywood to Broadway, context does not 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. dar contains the physical memory address that violated memory protection. dsisr is either OS_PROTECT_ADDRERR_BIT or OS_PROTECT_n.

OS_ERROR_FPE

OS_ERROR_FPE occurs only when an error handler was set with the OSSetErrorHandler function. By setting an OS_ERROR_FPE error handler, floating-point exceptions, such as floating-point zero division, can be captured at run-time.

The OSErrorHandler for the OS_ERROR_FPE error takes the following dsisr and dar as third and fourth arguments.

void (*OSErrorHandler)( OSError error, OSContext* context, 
                        u32 dsisr, u32 dar );

error indicates the generated error number (OS_ERROR_FPE). context contains the Broadway register values when notification of the floating-point exception error was sent, including the FPU register context. 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. dsisr and dar contain the Broadway register values corresponding to the time the error occurred. The context->fpscr bit indicates the floating-point exception type; these types are summarized below.

When an error handler is set, OSSetErrorHandler 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 __OSFpscrEnableBits global variable. By default, __OSFpscrEnableBits has the VE, OE, UE, ZE and XE bits set (that is, all bits are enabled). The types of floating-point exceptions that cause OS_ERROR_FPE errors can be controlled by setting the bitwise OR of the following enable bits in __OSFpscrEnableBits.

After the OS_ERROR_FPE error handler is set, the value of __OSFpscrEnableBits should not be changed until the OS_ERROR_FPE handler is deleted.

A sample program illustrating the use of the OS_ERROR_FPE error handler is found at the following location:

$REVOLUTION_SDK_ROOT/build/demos/osdemo/src/fpe.c

Note: If you are debugging with CodeWarrior, the CodeWarrior error dialog is displayed. The error handler registered by the OSSetErrorHandler function is not displayed.

Note: Floating-point exceptions in the KPAD library
KPADInit, KPADRead and other KPAD library functions perform internal operations in which floating-point numbers are divided by each other, and this can result in floating-point exceptions (inexact floating-point operations). This does not adversely affect the behavior of applications, but the exceptions that are generated by these functions are detected along with other floating-point exceptions. This is a necessary process required to preserve the precision of Wii Remote data, so you cannot prevent the exceptions from occurring.

If the exceptions are detected by OSSetErrorHandler, you can remove floating-point exceptions as a detection target if the need arises.

See Also

Error Functions
OSProtectRange
IBM Broadway RISC Microprocessor User's Manual

Revision History

2010/06/23 Added a note about the generation of floating-point exceptions in the KPAD library.
2009/11/18 Explained operations for CodeWarrior Debug/Run.
2006/03/01 Initial version.

CONFIDENTIAL