The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoDebug

All debug related functionality. More...

Files

file  SoDebug.c
file  SoDebug.h
file  SoDebugPrintf.c

Defines

#define SO_DEBUG
 Undefine this (comment it) if you are going to do a release build;.

#define SO_ASSERT(a_Assertion, a_Message)
 Define that controls what system the debugprint should use. Assertion macro.

#define SO_DEBUG_PRINT(a_String)
 Prints debug messages;.

#define SO_DEBUG_PRINT_INT_VALUE(a_Var)
 prints integer value

#define SO_DEBUG_PRINT_CHAR_VALUE(a_Var)
 prints character value

#define SO_DEBUG_PRINT_STRING_VALUE(a_Var)
 prints string value

#define SO_COMPILE_TIME_ASSERT(a_Assertion, a_Message)
 generates a breakpoint (BATGBA only) Compile-time assertion.

#define SO_DEPRECATED_FUNCTION(a_FunctionName, a_Message)
 Deprecated function declaration macro.


Functions

char * dstrcpy (u8 *strdst, const u8 *strsrc)
 debug helper: copy string

char * dstrcpynum (u8 *strdst, s32 value, int base)
 debug helper: copy number to string

u16 dstrlen (const u8 *str)
 debug helper: string length

u16 dstrnlen (const u8 *str, u16 count)
 debug helper: string length

char * ditoa (s32 num, char *buf, int len, int base)
 debug helper: convert integer to string

int dsprintf (char *buf, const char *fmt,...)
 sprintf function to support debugging

int dvsprintf (char *buf, const char *fmt, va_list args)
 vsprintf function to support debugging

void SoDebugPrintIntValue (const char *a_Name, s32 a_Value, int base)
 debug helper: print 'watch' for a number

void SoDebugAssert (bool a_Assertion, char *a_Message, char *a_Expression, char *a_File, u32 a_Line)
 Called by the SO_ASSERT macro in debug builds.

void SoDebugPrintf (const char *a_Format,...)
 Print formatted output;.

void SoDebugPrint (const char *a_Message)
 This prints a debug message depending on the running environment;.

void SoDebugPrintCharValue (const char *a_Name, char a_cValue)
 debug helper: print 'watch' for a character

void SoDebugPrintStringValue (const char *a_Name, const char *a_szValue)
 debug helper: print 'watch' for a string

void SoDebugDumpWordBuffer (const char *a_szDescription, u16 *a_pBuffer, u16 a_iCount)
 debug helper: print a 'watch' for a binary block


Variables

char s_DebugBuffer [256]
 Temporary buffer for debug print output.

Detailed Description

All debug related functionality.

Singleton

This module contains all stuff related to debugging, like debug-output, assertions, etc.

Define Documentation

#define SO_ASSERT (  a_Assertion,
a_Message    ) 
 

Define that controls what system the debugprint should use. Assertion macro.

Parameters:
a_Assertion  Expression that results in a boolean value (true, false, 0 or non zero).
a_Message  Message that is displayed when the assertion fails.
This macro can be used for assertions. When you are running a debug build and the given assertion fails, it halts the program and displays the assertion, the message, the line number, and the name of the file in which the assertion is located.

In release builds (when SO_DEBUG is not defined) these assertions are removed by the preprocessor.

#define SO_COMPILE_TIME_ASSERT (  a_Assertion,
a_Message    ) 
 

generates a breakpoint (BATGBA only) Compile-time assertion.

Parameters:
a_Assertion  Expression that results in a boolean value (true, false, 0 or non zero).
a_Message  Message that is displayed when the assertion fails. This must be an identifier not a string, due to the nature of this assertion (compile-time). So if you want to say "Value 64 not allowed", then just use Value_64_not_allowed instead. And if you don't understand this, then you shouldn't be using compile time assertions.
This is to check certain preconditions during the compile phase, like values of constants and their relations. If the assertion fails, you will get an error from the compiler, telling you where the assertion occured. This error might look a bit weird, something like size of array .... is negative. But the array identifier will given an indication of what happened. You can then go to the line of the error for a better explanation.

#define SO_DEBUG
 

Undefine this (comment it) if you are going to do a release build;.

When this is not defined then assertions are optimized away, as well as some other stuff that is done. It's all magic :) hehe...

However, you can always be sure that if something works in debug mode, it WILL work in release mode too.

#define SO_DEBUG_PRINT (  a_String    ) 
 

Prints debug messages;.

Parameters:
a_String  Message you want to display;
This macro routs the given string to a console depending on the SO_DEBUG_RUNNING_ON_* defines.

In release builds (when SO_DEBUG is not defined) these debug prints are removed by the preprocessor.

#define SO_DEPRECATED_FUNCTION (  a_FunctionName,
a_Message    ) 
 

Deprecated function declaration macro.

Parameters:
a_FunctionName  Name of the function that has been deprecated
a_Message  Message to explain what to do instead (if anything)
This macro gives a more friendly notification to a user of the SGADE library if they are attempting to use a function that is no longer supported. It should make it much easier to track down the error than getting a link error, or the old method of providing a stub for the removed function that just asserts.

Function Documentation

char* ditoa (  s32    num,
char *    buf,
int    len,
int    base
) 
 

debug helper: convert integer to string

Parameters:
num  the number to be converted
buf  where the result of the conversion will be stored
len  number of bytes in destination buffer
base  number base for conversion, must be between 2 and 16

int dsprintf (  char *    buf,
const char *    fmt,
...   
) 
 

sprintf function to support debugging

Parameters:
buf  buffer to contain the print output
fmt  format string
Variable argument printf function. See standard-C sprintf documentation for usage. Returns the number of variable arguments that were processed.

char* dstrcpy (  u8 *    strdst,
const u8 *    strsrc
) 
 

debug helper: copy string

Parameters:
strdst  target string
strsrc  source string
Returns :
pointer to end of target string
Multiple calls to dstrcpy and \dstrcpynum can be chained passing the result of one call into the next. The appending effect this produces can be used to create a "poor-man's printf".

char* dstrcpynum (  u8 *    strdst,
s32    value,
int    base
) 
 

debug helper: copy number to string

Parameters:
strdst  target string
value  number to be copied
base  number base for conversion, should be 10 or 16
Returns :
pointer to end of target string

u16 dstrlen (  const u8 *    str ) 
 

debug helper: string length

Parameters:
str  string to check
Returns :
length of str (number of characters before first nul byte)

u16 dstrnlen (  const u8 *    str,
u16    count
) 
 

debug helper: string length

Parameters:
str  string to check
count  max number of characters to check
Returns :
length of str (number of characters before first nul byte)

int dvsprintf (  char *    buf,
const char *    fmt,
va_list    args
) 
 

vsprintf function to support debugging

Parameters:
buf  buffer to contain the print output
fmt  format string
args  format arguments
Variable argument printf function. See standard-C sprintf documentation for usage. Returns the number of variable arguments that were processed.

void SoDebugAssert (  bool    a_Assertion,
char *    a_Message,
char *    a_Expression,
char *    a_File,
u32    a_Line
) 
 

Called by the SO_ASSERT macro in debug builds.

For internal use only.

Parameters:
a_Assertion  The boolean expression that you want to assert.
a_Message  Message describing what happened when the assertion fails.
a_Expression  Stringized version of the a_Assertion parameter. So we can print the assertion.
a_File  Name of the file in which the assertion is located.
a_Line  Line number at which the assertion appears.
SoAssertImplementation is called by the SO_ASSERT macro when the application is running a debug build. If the given assertion fails, it halts the program and displays the assertion, the message, the line number, and the name of the file in which the assertion is located.

void SoDebugDumpWordBuffer (  const char *    a_szDescription,
u16 *    a_pBuffer,
u16    a_iCount
) 
 

debug helper: print a 'watch' for a binary block

Parameters:
a_szDescription  description of the binary block
a_pBuffer  pointer to the binary block
a_iCount  number of words in the block
This routine generates a multi-line printout containing the description followed by the byte count in parenthesis and one or more lines of hex numbers representing the contents of the block. For example, when called with the arguments "("Player Info", { 0, 5, 8, 10, 7 }, 5) would result in the following output: Player Info (5 entries) 0000, 0005, 0008, 000A, 0007

void SoDebugPrint (  const char *    a_Message ) 
 

This prints a debug message depending on the running environment;.

Parameters:
a_Message  Message you want to print;
The actual SO_DEBUG_RUNNING_ON_* define will decide where the message is routed to.

Warning:
In order to be able to print stuff on MBV2 you have to supply the include path to where "mbv2lib.c" is located on your harddrive. You can change this in the SGADE makefile;

void SoDebugPrintCharValue (  const char *    a_Name,
char    a_cValue
) 
 

debug helper: print 'watch' for a character

Parameters:
a_Name  the name of the value to be printed
a_cValue  the value to be printed
This routine generates a printout containing the name of the value, an equal sign and the value itself. For example, calling this routine with the arguments ("Initial", 'M') would result in a printed line containing "Initial = M".

void SoDebugPrintf (  const char *    a_Format,
...   
) 
 

Print formatted output;.

Parameters:
a_Format  Format control (see your stdlib references).

void SoDebugPrintIntValue (  const char *    a_Name,
s32    a_Value,
int    base
) 
 

debug helper: print 'watch' for a number

Parameters:
a_Name  the name of the value to be printed
a_Value  the value to be printed
base  number base for value, should be 10 or 16
This routine generates a printout containing the name of the value, an equal sign and the value itself. For example, calling this routine with the arguments ("FrameCount", 798, 10) would result in a printed line containing "FrameCount = 798".

void SoDebugPrintStringValue (  const char *    a_Name,
const char *    a_szValue
) 
 

debug helper: print 'watch' for a string

Parameters:
a_Name  the name of the value to be printed
a_szValue  the value to be printed
This routine generates a printout containing the name of the value, an equal sign and the value itself. For example, calling this routine with the arguments ("Player", "Henry") would result in a printed line containing "Player = "Henry"".

Variable Documentation

char s_DebugBuffer[ 256 ]
 

Temporary buffer for debug print output.

For internal use only.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.