GBDK 2020 Docs API Documentation for GBDK 2020

Macros | Functions
bgb_emu.h File Reference

Go to the source code of this file.

## Macros
#define | BGB_MESSAGE(message_text) BGB_MESSAGE1(BGB_ADD_DOLLARD(__LINE__), message_text)
#define | BGB_MESSAGE_FMT(buf, ...) sprintf(buf, __VA_ARGS__);BGB_MESSAGE2(BGB_ADD_DOLLARD(__LINE__), BGB_MAKE_LABEL(_##buf));
#define | BGB_PROFILE_BEGIN(MSG) BGB_MESSAGE(BGB_CONCAT(MSG,%ZEROCLKS%));
#define | BGB_PROFILE_END(MSG) BGB_MESSAGE(BGB_CONCAT(MSG,%-8+LASTCLKS%));
#define | BGB_TEXT(MSG) BGB_MESSAGE(BGB_STR(MSG))

## Functions
void | BGB_profiler_message ()

## Detailed Description

Debug window logging and profiling support for the BGB emulator.

Also see the `bgb_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

## ◆ BGB_MESSAGE

#define BGB_MESSAGE | ( |  | message_text | ) | BGB_MESSAGE1(BGB_ADD_DOLLARD(__LINE__), message_text)

Macro to display a message in the BGB 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.

BGB_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
  BGB_PROFILE_BEGIN(), BGB_PROFILE_END()

## ◆ BGB_MESSAGE_FMT

#define BGB_MESSAGE_FMT | ( |  | buf,
|  |  | ...
| ) |  | sprintf(buf, __VA_ARGS__);BGB_MESSAGE2(BGB_ADD_DOLLARD(__LINE__), BGB_MAKE_LABEL(_##buf));

Macro to display a sprintf formatted message in the BGB emulator debug message window

Parameters

  buf | Pointer to a globally defined char buffer
  ... | VA Args list of sprintf parameters

To avoid buffer overflows buf must be large enough to store the entire printed message.

Example:

char mybuf[100]; // should be globally defined
BGB_MESSAGE_FMT(mybuf, "An integer:%d, a string: %s", 12345, "hello bgb")

See also
  BGB_MESSAGE()

## ◆ BGB_PROFILE_BEGIN

#define BGB_PROFILE_BEGIN | ( |  | MSG | ) | BGB_MESSAGE(BGB_CONCAT(MSG,%ZEROCLKS%));

Macro to Start a profiling block for the BGB emulator

Parameters

  MSG | Quoted text string to display in the debug message window

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

See also
  BGB_PROFILE_END(), BGB_MESSAGE()

## ◆ BGB_PROFILE_END

#define BGB_PROFILE_END | ( |  | MSG | ) | BGB_MESSAGE(BGB_CONCAT(MSG,%-8+LASTCLKS%));

Macro to End a profiling block and print the results in the BGB 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 BGB_PROFILE_BEGIN()

The results are in BGB 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.

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

See also
  BGB_PROFILE_BEGIN(), BGB_MESSAGE()

## ◆ BGB_TEXT

#define BGB_TEXT | ( |  | MSG | ) | BGB_MESSAGE(BGB_STR(MSG))

## Function Documentation

## ◆ BGB_profiler_message()

void BGB_profiler_message | ( |  | ) |

Display preset debug information in the BGB debug messages window.

This function is equivalent to:

BGB_MESSAGE("PROFILE,%(SP+$0)%,%(SP+$1)%,%A%,%TOTALCLKS%,%ROMBANK%,%WRAMBANK%");
BGB_MESSAGE
#define BGB_MESSAGE(message_text)
Definition: bgb_emu.h:43
BGB_MESSAGE_FMT
#define BGB_MESSAGE_FMT(buf,...)
Definition: bgb_emu.h:77