GBDK 2020 Docs  4.1.1
API Documentation for GBDK 2020
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_textQuoted 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%");
#define EMU_MESSAGE(message_text)
Definition: emu_debug.h:43

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
MSGQuoted 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
MSGQuoted 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
formatThe 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.