Difference between revisions of "Debug messages"

Revision as of 10:59, 22 December 2024

Debug messages is a feature in Gameboy debuggers that allows you to output debug data from the running program into a log window or file. Currently, two standards exist. Both use the ld d,d instruction followed by a relative jump (jr) jumping over the message payload, and a unique identifier, followed by the message payload itself. Similar to how source code breakpoint use the ld b,b instruction, which is normally a no-op, debug messages use ld d,d. Because of this, debug messages will be ignored with minimal overhaad if executed on real hardware or an emulator without support for them.

Classic (no$gmb style) debug messages

This style of debug message dates back to no$gmb, but is supported in BGB, Emulicious and possibly other emulators with debug support as well.

Message specified directly

This style of debug message has the syntax shown in the following example code: (RGBDS syntax)

        ; Macro definition. (Usually defined in an include file.)
MACRO debug_message
        ld      d,d
        jr      :+
        dw      $6464           ; Two ASCII characters: "dd"
        dw      $0000           ; Identifier for this debug message type
        db      \1
:
ENDM

        ; Invoke the macro
        debug_message "Hello!"

Message specified with a pointer

Alternatively, you can point to a message somewhere else using a far pointer, consisting of an address and a bank, both represented as 16 bit numbers.

        ; Macro definition. (Usually defined in an include file.)
macro debug_message_pointer
        ld      d,d
        jr      :+
        dw      $6464           ; Two ASCII characters: "dd"
        dw      $0001           ; Identifier for this debug message type
        dw      \1
        dw      bank(\1)
:
endm
        
        ; Invoke the macro
        debug_message_pointer a_msg

        ; A null-terminated string. (Defined somewhere else so code doesn't fall right into it!)
a_msg:
        db      "Hello!",0

Operands

Several special operands can be used to print information about the internal state of the emulated machine.

%A%  %B%  %C%  %D%  %E%  %H%  %L% 
%AF% %BC% %DE% %HL% %PC% %SP% 
%ALLREGS% 

%ZF% %Z% %ZERO%
%CF% %CARRY%
%IME%