ASSERT

Syntax

#include <revolution/os.h>

void ASSERT(int expression);

Arguments

expression	Conditional expression to check when the `_DEBUG` macro is defined.

Return Values

None.

Description

When the _DEBUG macro is defined, ASSERT displays an assert failure message if expression is FALSE. A message that includes the text in expression is output to the output port, and the program is halted.

If the _DEBUG macro is not defined, ASSERT will do 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, you should output to the TV screen rather than the serial port. When an assertion failure occurs, the following OSPanic function in os[D].a is called.

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

  Description:  Outputs a formatted message into the output port with the
                file name and 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();
}

It is difficult to implement a generic print function for the TV screen due to various graphics configurations. Therefore, you are free to implement a game-specific version of the OSPanic function and replace the one implemented in os[D].a. Since the OSPanic function is defined to be weak in os[D].a, the game-specific OSPanic function takes precedence over the default version in os[D].a.

The following code is an example implementation of the OSPanic function that shows the assertion failure message on 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

2006/03/01 Initial version.