Debug messages - Revision history

Nitro2k01: /* Emulator and toolchain specific caveats */

2024-12-22T18:17:31Z

‎Emulator and toolchain specific caveats

Nitro2k01 at 18:09, 22 December 2024

2024-12-22T18:09:46Z

Nitro2k01: /* Operands */

2024-12-22T17:20:11Z

‎Operands

Nitro2k01 at 17:13, 22 December 2024

2024-12-22T17:13:05Z

Nitro2k01: /* Operands */

2024-12-22T16:47:15Z

‎Operands

Nitro2k01: /* Operands */

2024-12-22T16:45:55Z

‎Operands

Nitro2k01 at 15:59, 22 December 2024

2024-12-22T15:59:23Z

Nitro2k01: Created page with "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..."

2024-12-22T15:06:51Z

Created page with "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..."

New page

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)
<pre>
; 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!"

</pre>
===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.
<pre>
; 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
</pre>

← Older revision		Revision as of 18:17, 22 December 2024
Line 84:		Line 84:

	Any operands above that are full words must be uppercase when used with Emulicious. In BGB, they are case insensitive, and you could even use something like %RoMbAnK%, mocking Spongebob style.		Any operands above that are full words must be uppercase when used with Emulicious. In BGB, they are case insensitive, and you could even use something like %RoMbAnK%, mocking Spongebob style.
		+
		+	===Zero pad===
		+
		+	BGB and Emulicious will behave slightly differently in how they pad values. For example, BGB pads 16 bit register expressions like %HL% to 4 digits, whereas Emulicious doesn't. However, %ALLREGS% does contain values padded to 4 digits. This can be worth keeping in mind if you're planning to parse the log output using code.

	===Garbled text due to charmaps===		===Garbled text due to charmaps===

@@ Line 71: / Line 71: @@
 |-
 || <pre>%expression%text if true;text if false;</pre> || Ternary expression, similar to condition?if_true:if_false in c family languages.
+|-
+|| <pre>%(BC)% %(DE)% %(HL)%
+%(SP)% %(PC)%</pre> || Read the value at the address specified by the expression. Most commonly used with 16 bit registers, but can be used with any expression.
+|-
 |}

@@ Line 69: / Line 69: @@
 |-
 || <pre>%ZEROCLKS%</pre> || Reset the timer used for %LASTCLKS%.
 |}

← Older revision		Revision as of 17:13, 22 December 2024
Line 71:		Line 71:

	\|}		\|}
		+
		+	==Emulator and toolchain specific caveats==
		+
		+	===Case sensitivity===
		+
		+	Any operands above that are full words must be uppercase when used with Emulicious. In BGB, they are case insensitive, and you could even use something like %RoMbAnK%, mocking Spongebob style.
		+
		+	===Garbled text due to charmaps===
		+
		+	In RGBDS, if you use a custom [https://rgbds.gbdev.io/docs/v0.6.1/rgbasm.5#Character_maps charmap] globally, this will garble the message strings. In this case, make sure to specify a standard ASCII charmap. The example below assumes the "default" charmap is untouched.
		+
		+	<pre>
		+	; 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
		+	pushc
		+	setcharmap default
		+	db \1
		+	popc
		+	:
		+	ENDM
		+
		+	; Invoke the macro
		+	debug_message "Hello!"
		+
		+	</pre>

@@ Line 60: / Line 60: @@
 |-
 || <pre>%ROMBANK% %SRAMBANK% %XRAMBANK%
-%WRAMBANK% %VRAMBANK%</pre> || The selected ROM or RAM bank of various types. (Note: XRAMBANK is only supported in BGB and not in Emulicious. XRAMBANK is an alias for SRAMBANK so you can use SRAMBANK to be compatible with both.)
+%WRAMBANK% %VRAMBANK%</pre> || The selected ROM or RAM bank of various types. (Note: %XRAMBANK% is only supported in BGB and not in Emulicious. %XRAMBANK% is an alias for %SRAMBANK% so you can use %SRAMBANK% to be compatible with both.)
 |-
 || <pre>%TOTALCLKS%</pre> || Number of clock cycles since power on. All these operands output in units of 1 nop in GBC double speed mode. So exeucintg a nop in ''single speed mode'' will increment the clock timers by 2.
@@ Line 68: / Line 68: @@
 || <pre>%LASTCLKS%</pre> || Number of clock cycles since last user of %ZEROCLKS%. (Can be used for benchmarking.)
 |-
-|| <pre>%ZEROCLKS%</pre> || Reset the timer used for LASTCLKS.
+|| <pre>%ZEROCLKS%</pre> || Reset the timer used for %LASTCLKS%.
 |}

@@ Line 53: / Line 53: @@
 || <pre>%A%  %B%  %C%  %D%  %E%  %H%  %L%
 %AF% %BC% %DE% %HL% %PC% %SP%
-%ALLREGS% </pre> || The current value of a 8-bit CPU register, 16-bit CPU register.
+%ALLREGS% </pre> || The current value of a 8-bit CPU register, 16-bit CPU register or a dump of all registers.
 |-
 || <pre>%ZF% %Z% %ZERO%
 %CF% %CARRY%
-%IME%</pre> || The current value of a CPU flag or the interrupt master enable.
+%IME%</pre> || The current value of a CPU flag or the interrupt master enable. (Note: these operands are only supported in BGB and not in Emulicious.)
 |}

← Older revision		Revision as of 15:59, 22 December 2024
Line 43:		Line 43:
	db "Hello!",0		db "Hello!",0
	</pre>		</pre>
		+	===Operands===
		+
		+	Several special operands can be used to print information about the internal state of the emulated machine.
		+
		+	{\| class="wikitable"
		+	\|-
		+	! Operand !! Description
		+	\|-
		+	\|\| <pre>%A% %B% %C% %D% %E% %H% %L%
		+	%AF% %BC% %DE% %HL% %PC% %SP%
		+	%ALLREGS% </pre> \|\| The current value of a 8-bit CPU register, 16-bit CPU register.
		+	\|-
		+	\|\| <pre>%ZF% %Z% %ZERO%
		+	%CF% %CARRY%
		+	%IME%</pre> \|\| The current value of a CPU flag or the interrupt master enable.
		+
		+	\|}