emu_debug.h File Reference

#include <types.h>

Go to the source code of this file.

Macros
#define	EMU_MESSAGE(message_text)   EMU_MESSAGE1(EMU_MACRONAME(__LINE__), message_text)
#define	BGB_MESSAGE(message_text)   EMU_MESSAGE(message_text)
#define	EMU_PROFILE_BEGIN(MSG)   EMU_MESSAGE_SUFFIX(MSG, "%ZEROCLKS%");
#define	BGB_PROFILE_BEGIN(MSG)   EMU_PROFILE_BEGIN(MSG)
#define	EMU_TEXT(MSG)   EMU_MESSAGE(MSG)
#define	BGB_TEXT(MSG)   EMU_TEXT(MSG)
#define	BGB_printf(...)   EMU_printf(__VA_ARGS__)
#define	EMU_BREAKPOINT   __asm__("ld b, b");
#define	BGB_BREAKPOINT   EMU_BREAKPOINT

Functions
void	EMU_printf (const char *format,...) OLDCALL

Detailed Description

Debug window logging and profiling support for emulators (BGB, Emulicious, etc).

Also see the emu_debug example project included with gbdk.

See the BGB Manual for more information ("expressions, breakpoint conditions, and debug messages") http://bgb.bircd.org/manual.html#expressions

Macro Definition Documentation

EMU_MESSAGE

#define EMU_MESSAGE

(

message_text

)

EMU_MESSAGE1(EMU_MACRONAME(__LINE__), message_text)

Macro to display a message in the emulator debug message window

Parameters

message_text

Quoted text string to display in the debug message window

The following special parameters can be used when bracketed with "%" characters.

• CPU registers: AF, BC, DE, HL, SP, PC, B, C, D, E, H, L, A, ZERO, ZF, Z, CARRY, CY, IME, ALLREGS
• Other state values: ROMBANK, XRAMBANK, SRAMBANK, WRAMBANK, VRAMBANK, TOTALCLKS, LASTCLKS, CLKS2VBLANK

Example: print a message along with the currently active ROM bank.

EMU_MESSAGE("Current ROM Bank is: %ROMBANK%");

See the BGB Manual for more information ("expressions, breakpoint conditions, and debug messages") http://bgb.bircd.org/manual.html#expressions

See also

EMU_PROFILE_BEGIN(), EMU_PROFILE_END()

BGB_MESSAGE

#define BGB_MESSAGE

(

message_text

)

EMU_MESSAGE(message_text)

EMU_PROFILE_BEGIN

#define EMU_PROFILE_BEGIN

(

MSG

)

EMU_MESSAGE_SUFFIX(MSG, "%ZEROCLKS%");

Macro to Start a profiling block for the emulator (BGB, Emulicious, etc)

Parameters

MSG	Quoted text string to display in the debug message window along with the result

To complete the profiling block and print the result call EMU_PROFILE_END.

See also

EMU_PROFILE_END(), EMU_MESSAGE()

BGB_PROFILE_BEGIN

#define BGB_PROFILE_BEGIN

(

MSG

)

EMU_PROFILE_BEGIN(MSG)

EMU_TEXT

#define EMU_TEXT

(

MSG

)

EMU_MESSAGE(MSG)

Macro to End a profiling block and print the results in the emulator debug message window

Parameters

MSG	Quoted text string to display in the debug message window along with the result

This should only be called after a previous call to EMU_PROFILE_BEGIN()

The results are in Emulator clock units, which are "1 nop in [CGB] doublespeed mode".

So when running in Normal Speed mode (i.e. non-CGB doublespeed) the printed result should be divided by 2 to get the actual ellapsed cycle count.

If running in CB Double Speed mode use the below call instead, it correctly compensates for the speed difference. In this scenario, the result does not need to be divided by 2 to get the ellapsed cycle count.

EMU_MESSAGE("NOP TIME: %-4+LASTCLKS%");

See also

EMU_PROFILE_BEGIN(), EMU_MESSAGE()

BGB_TEXT

#define BGB_TEXT

(

MSG

)

EMU_TEXT(MSG)

BGB_printf

#define BGB_printf

(

...

)

EMU_printf(__VA_ARGS__)

EMU_BREAKPOINT

#define EMU_BREAKPOINT   __asm__("ld b, b");

The Emulator will break into debugger when encounters this line

BGB_BREAKPOINT

#define BGB_BREAKPOINT   EMU_BREAKPOINT

Function Documentation

EMU_printf()

void EMU_printf	(	const char *	format,
			...
	)

Display preset debug information in the Emulator debug messages window.

This function is equivalent to:

EMU_MESSAGE("PROFILE,%(SP+$0)%,%(SP+$1)%,%A%,%TOTALCLKS%,%ROMBANK%,%WRAMBANK%");

Print the string and arguments given by format to the emulator debug message window

Parameters

format

The format string as per printf

Does not return the number of characters printed. Result string MUST BE LESS OR EQUAL THAN 128 BYTES LONG, INCLUDING THE TRAILIG ZERO BYTE!

Currently supported:

• %hx (char as hex)
• %hu (unsigned char)
• %hd (signed char)
• %c (character)
• %u (unsigned int)
• %d (signed int)
• %x (unsigned int as hex)
• %s (string)

Warning: to correctly pass chars for printing as chars, they must be explicitly re-cast as such when calling the function. See docs_chars_varargs for more details.