ASSERT

C Specification

#include <revolution/os.h>

void ASSERT(int expression);

Arguments

expression Conditional expression used for checking if the _DEBUG macro is defined.

Return Values

None.

Description

When the _DEBUG macro is defined, the ASSERT function displays a failure message if expression is FALSE. The message that contains the text of expression appears in the output port, and the console is halted.

If the _DEBUG macro is not defined, ASSERT does nothing.

Tips: 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 OSPanic function shown below in os[D].a is called.

/*---------------------------------------------------------------------------*
Name: OSPanic()

Description: Outputs a formatted message into the output port with the
file name and the line number. And then halts.

Arguments: file        should be __FILE__
line        should be __LINE__
msg         pointer to a null-terminated string that contains
the format specifications
...         optional arguments

Returns: None.
 *---------------------------------------------------------------------------*/
__declspec(weak) void OSPanic(const char* file, int line, const char* msg, ...)
{
va_list marker;
u32     i;
u32*    p;

OSDisableInterrupts();
va_start(marker, msg);
vprintf(msg, marker);
va_end(marker);
OSReport(" in \"%s\" on line %d.\n", file, line);

// Stack crawl
OSReport("\nAddress: Back Chain LR Save\n");
for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
p && (u32) p != 0xffffffff && i++ < 16;
p = (u32*) *p)                         // get caller sp
    {
OSReport("0x%08x: 0x%08x 0x%08x\n", p, p[0], p[1]);
    }

PPCHalt();
}

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 OSPanic and to replace the one in os[D].a. Because the OSPanic function is weakly defined in os[D].a, the game-specific OSPanic function takes precedence over the default OSPanic in os[D].a.

The following code is an implementation example of the OSPanic function that shows the assertion failure message on a TV screen using the OSFatal function.

char Message[2048]; // Panic message buffer

void OSPanic(const char* file, int line, const char* msg, ...)
{
va_list marker;
u32     i;
u32*    p;
int     len;
GXColor bg = {   0,   0, 255, 0 };
GXColor fg = { 255, 255, 255, 0 };

va_start(marker, msg);
len = vsprintf(Message, msg, marker);
va_end(marker);
len += sprintf(Message + len, " in \"%s\" on line %d.\n", file, line);

// Stack crawl
len += sprintf(Message + len, "\nAddress: Back Chain LR Save\n");
for (i = 0, p = (u32*) OSGetStackPointer(); // get current sp
p && (u32) p != 0xffffffff && i++ < 16;
p = (u32*) *p)                         // get caller sp
    {
len += sprintf(Message + len, "0x%08x: 0x%08x 0x%08x\n", p, p[0], p[1]);
    }

OSFatal(fg, bg, Message);
// NOT REACHED HERE
}

Revision History