Main Page | Modules | Related Pages

Debug Functions/Information

Pages:

Assertion Checking

The HEL_ASSERT mechanism evaluates an expression and, when the result is FALSE, displays an errorscreen and aborts the program execution until you press a specific button. The error-screen displays several informations where in the source the assertion failed. This includes:
Assertion Screen
assert_01.png
Macro:
HEL_ASSERT(expression, message ...)

Parameter:

expression    : Expression that evaluates to TRUE or FALSE
message       : Message to display when expression is FALSE

The HEL_ASSERT macro is typically used to identify logic errors during program development by implementing the expression argument to evaluate to FALSE only when the program is operating incorrectly.

After debugging is complete, assertion checking can be turned off by undefine HAM_DEBUGGER in 'ham/include/mygba.h':

#define HAM_DEBUGGER

Example:

In this program the SetHeroState function uses HEL_ASSERT to test if the passed pointer pHero is NULL and State is lesser than HERO_STATE_ITEMS.

typedef struct _THero
{
    int State;
}THero;

enum
{
    HERO_STATE_JUMP=0,
    HERO_STATE_WALK,
    HERO_STATE_STAY,
    
    HERO_STATE_ITEMS
}HERO_STATE;

THero gHero;
void SetHeroState(THero *pHero, u32 State);

void main(int argc, char *argv[])
{
    // Initialization and whatever ...
    
    // Does not raise an error!
    SetHeroState(&gHero, HERO_STATE_STAY);
    
    // Displays an error, because we
    // pass NULL as first parameter!!
    SetHeroState(NULL, HERO_STATE_STAY);
}

void SetHeroState(THero *pHero, u32 State)
{
    HEL_ASSERT(pHero != NULL, "pHero must not be NULL");
    HEL_ASSERT(State < HERO_STATE_ITEMS, "State must not be greater than HERO_STATE_ITEMS");
    
    pHero->State = State;
}

See also:
On Assertion

Program execution breakpoints

HEL provides an easy to use mechanism to set program execution breakpoints, which are automatically turned off when you switch to releasemode. Please note that these breakpoints are currently only supported by NO$GBA emulator and must be explicit turned on!

Using such a breakpoint is easy, all you need is HEL_DEBUG_BRK

Example:

The following example shows how to stop the program execution using HEL_DEBUG_BRK macro:

int main()
{
  ham_Init();
  
  // stop program execution!
  HEL_DEBUG_BRK;
  
  while(GameIsRunning)
  {
    // some fancy stuff ...
  }
  
  return 0;
}

The program execution is stopped after ham_Init and before the while-loop. NO$GBA halts at this point and displays the assembler sourcecode in its debugger-window where you then can step through:

debug_brk0.png

Note:
If you use HEL's breakpoint implementation with another emulator than NO$GBA, it will just leave the corresponsing opcode away, assuming you specified what emulator you use (see Debug Message Output) and therfore will not halt at the position where the breakpoint is set.
Requirements:

NO$GBA shareware or professional version. "Source Code BReakpoints" must be turned on in no$gba Xcept setup.

Debug and Release Library mystery

This document is intented to outline the differences between the debug and release library of HEL.

HEL Library comes in two forms. One for debug purposes, using Assertion Checking and one for the final release, which does not include ASSERT and is faster and smaller.

The debug library consumes more memory (ROM/IWRAM/EWRAM) than the release library and is also slower and bigger in its filesize. The more memory consumtion is archieved because it includes a few variables for reference-counting which are located in EWRAM (< 500byte) and some self-modifing-code which must be in IWRAM (< 400byte).

While working on a project, it's recommended to use the debug library. This is just because the debug library includes ASSERT checking and so it will display an errormessage when you pass an invalid parameter to one of HEL's functions. ASSERT calls seem to be a bit overhead for the little GBA, but they help a lot in the development process and therefore they are implemented in the debug version of HEL.

All ASSERT calls, Reference-Counter variables as well as Debugging Functions are removed in the release library. Even a lot of functions get replaced with macros when you switch to release mode to gain maximum speed. As of version HEL 1.5, this includes the Object/Window/DMA/System/SpecialFX/etc... modules!

Switch between Debug and Release Library:

Since sooner or later you want to switch between the debug and release library, here is an explanation how this can be done.

Copy libhel.a as described in the Installation guide into the correct directory. Now, depending on what version you copied (debug or release) you have to either enable or disable HAM_DEBUGGER which is located in mygba.h. The file mygba.h is the header file of HAM and located into the 'ham/include' directory in your HAM installation. Make a stringsearch in this file for HAM_DEBUGGER. You should come across this text:

#define HAM_DEBUGGER 1

That is the default setting! If you want to turn off debugging just comment out this line as demonstrated below:

//#define HAM_DEBUGGER 1

HEL is now also forced to use macros for a lot of functions, please see notes in this context.

When to use the Release Library:

A disadvantage of the debug library is that you don't have the full performance as mentioned earlier. At some point of time you want to see how your game really runs on the GBA. This is a good moment to rebuild the project in release mode and then watch it in all its glory and full speed on hardware. Basically, whenever I think my game is bugfree and I want to test it on hardware, I rebuild the entire project with the release library and switch back to the debug version when I continue developing by using an emulator.

Notes:

Due to the fact that several modules in HEL are almost entirely replaced with macros in release mode, you can encounter an error that it cannot find a symbol (function) in the library. This error occurs when you use the release library but you did not remove the HAM_DEBUGGER define. In this case HEL still thinks it should use the functions which are located in the library instead of using the macros.

See also:
Installation

Debug Message Output

HEL provides an easy to use mechanism to output formatted debug messages, which are automatically turned off when you switch to releasemode.

The Debug-Message-System currently supports NO$GBA and VisualBoy Advance. Activating one or the other is easiely done:

HEL_DEBUG_MSG_TYPE_NOCHASH is the default setting when you just installed HEL.

Example:

The following example shows how to switch to VisualBoy Advance support. Once you have hel.h infront of you and scrolled a few lines down, you see:

//#define HEL_DEBUG_MSG_TYPE_VBA
#define HEL_DEBUG_MSG_TYPE_NOCHASH

As you can see, at this time NO$GBA support is activated. To activate VBA, change it to:

#define HEL_DEBUG_MSG_TYPE_VBA
//#define HEL_DEBUG_MSG_TYPE_NOCHASH

Usage:

To make use of Debug-Messages in your project, all you need is HEL_DEBUG_MSG. It does not matter what Debug-System you activated (NO$GBA or VBA), just use HEL_DEBUG_MSG. Everything else is done for you automatically!

Macro:

HEL_DEBUG_MSG(txt, args...)

Parameter:

txt    : Format-control string
args   : Optional arguments

Example:

HEL_DEBUG_MSG("Hello World\n");
HEL_DEBUG_MSG("I am %d years old.\n", 28);

Output:

Hello World
I am 28 years old.

Remarks:

HEL's Debug-Message-System only works, as the name already says, in Debug-Mode. To switch between Debug and Release-Mode, please see Debug and Release Library mystery. Another important part is to know that VisualBoy Advance Debug-Messages do not work on hardware! They freeze the GBA! Having Debug-Messages enabled when using it outside an emulator makes no sense anyway.

Requirements:

NO$GBA shareware or professional version, freeware version does not support debugmessages! VisualBoy Advance SDL (commandline tool).

See also:
Assertion Checking

On Assertion

You can specify a function that gets called before an assertion takes place. This can be helpful if you want to output your engine stats or whatever, when something went wrong. Use the hel_DebugSetOnAssert function for this.

Function:

hel_DebugSetOnAssert(PDebugAssertFunc pFunc)

Parameter:

pFunc : A pointer to the function that should be called before an assertion takes place

Example:

void main(int argc, char *argv[])
{
    // Initialization and whatever ...

    // set function that gets executed before
    // the assertion takes place
    hel_DebugSetOnAssert(OnAssert);

    // raise an assertion
    ASSERT(0==1, "0 cannot be 1");
}

void OnAssert(TDebugAssertInfo *pInfo)
{
    // just write some text to the console
    HEL_DEBUG_MSG("OnAssert called");
}

See also:
Assertion Checking

Generated on Sun Oct 9 20:21:00 2005 by DoxyGen 1.4.4