Debugging On Ancient Game Platforms - Revision history

MSaarna at 14:04, 19 November 2022

2022-11-19T14:04:08Z

MSaarna: /* When Problems Manifest Only On One Particular Console, Or Only With One Tester */

2022-11-19T14:00:20Z

‎When Problems Manifest Only On One Particular Console, Or Only With One Tester

MSaarna: /* Use Modern Debugging */

2022-11-19T13:52:29Z

‎Use Modern Debugging

MSaarna at 06:24, 20 March 2021

2021-03-20T06:24:40Z

MSaarna: /* Don't Panic */

2021-03-20T06:24:23Z

‎Don't Panic

MSaarna at 16:05, 5 March 2020

2020-03-05T16:05:48Z

MSaarna at 15:42, 5 March 2020

2020-03-05T15:42:34Z

MSaarna at 15:41, 5 March 2020

2020-03-05T15:41:39Z

MSaarna at 15:26, 5 March 2020

2020-03-05T15:26:18Z

MSaarna at 15:25, 5 March 2020

2020-03-05T15:25:47Z

@@ Line 1: / Line 1: @@
 When you run into obscure programming bugs on ancient game platforms, it's often a challenge to get useful diagnostic information out of them, especially compared to modern development environments. This article provides some helpful general advice for debugging, as well as suggesting some ways you can narrow that gap between old and new development tools.
@@ Line 62: / Line 61: @@
 For the Atari 7800 platform, knowing your way around the A7800/Mame debugger is an essential skill. (see [[Introduction to the MAME debugger]]) On the Atari 2600, the same can be said for the Stella debugger.
 == Common Causes of Catastrophic Problems ==
@@ Line 85: / Line 85: @@
 You should also keep in mind that some bugs tend to be triggered by certain play-styles more than others. As a programmer, you know the correct and ideal way to play the game, so you unintentionally avoid triggering the bug. After all, if you had triggered it before, you would have fixed it. When you get an unusual report from a tester, always make a point of getting all of the circumstances under which it occurred, so you can learn to reproduce it yourself.
 == When Nothing Else Works To Squash The Bug, Trust Nothing ==

@@ Line 80: / Line 80: @@
 On 6502 based platforms, a common assembly language typo is to use something like "lda 0" when you meant to use "lda #0". The former loads the accumulator with the value at memory location 0, while the latter means to load the literal value 0 into the accumulator.
-On many of those same platforms, location 0 is either a register that often happens to be 0, and/or there are floating bits at that location. In most cases, the value returned from 0 will be 0, as it was the last value on the bus, due to being the second byte of the opcode. On some rarer consoles, the last value on the floating bus prior to being read, which makes the "lda 0" mistake strikingly obvious.
+On many platforms, location 0 is either a register or memory location that often happens to be 0, and/or there are undriven/floating bits at that location. With undriven bits, the value typically returned from location 0 will be 0 - it was the last value on the bus, due to being the second byte of the opcode. On some atypical consoles, the value is something else entirely, making the "lda 0" mistake obvious.
-If possible on your emulated platform, you should test your program with undriven bits being randomized. (e.g. Stella, the 2600 emulator supports this)
+If it's possible with your emulator, you should test your program with undriven bits being randomized. (e.g. Stella, the 2600 emulator supports this)
 You should also keep in mind that some bugs tend to be triggered by certain play-styles more than others. As a programmer, you know the correct and ideal way to play the game, so you unintentionally avoid triggering the bug. After all, if you had triggered it before, you would have fixed it. When you get an unusual report from a tester, always make a point of getting all of the circumstances under which it occurred, so you can learn to reproduce it yourself.
 == When Nothing Else Works To Squash The Bug, Trust Nothing ==

@@ Line 55: / Line 55: @@
 Many emulators for old systems provide modern debuggers, which among other things allow you to:
-* set watch points: When a particular variable is read to or written to, code execution will pause, the assembly code involved will be highlighted, and you'll have the opportunity to manually step through it, observing how register values and memory locations change.
+* set watch points: When a particular memory location is read to or written to, code execution will pause, the assembly code involved will be highlighted, and you'll have the opportunity to manually step through it, observing how register values and memory locations change.
 * set break points: When a particular part of the program is reached, code execution will pause, the assembly code involved will be highlighted, and again you can manually step through it.
 * dump memory: At any point in your program execution, you can write the contents of some memory to a file on your PC, for analysis. Some even let you change and reload this memory block.
@@ Line 62: / Line 62: @@
 For the Atari 7800 platform, knowing your way around the A7800/Mame debugger is an essential skill. (see [[Introduction to the MAME debugger]]) On the Atari 2600, the same can be said for the Stella debugger.
 == Common Causes of Catastrophic Problems ==

← Older revision		Revision as of 06:24, 20 March 2021
Line 7:		Line 7:

	When your game is doing things that it shouldn't be doing, and you can't figure out why, it's natural to feel some gloom and despair. This only gets worse the more you throw yourself at the problem, without any results. Try not to give into despair. You've managed to build up your code to it's current state - you're smart enough to squash the bug. If you take a structured approach and dig deep for a bit of persistence, you'll eventually understand the reason why the bug is happening, and how to squash it.		When your game is doing things that it shouldn't be doing, and you can't figure out why, it's natural to feel some gloom and despair. This only gets worse the more you throw yourself at the problem, without any results. Try not to give into despair. You've managed to build up your code to it's current state - you're smart enough to squash the bug. If you take a structured approach and dig deep for a bit of persistence, you'll eventually understand the reason why the bug is happening, and how to squash it.
		+

	== What Changed? ==		== What Changed? ==

@@ Line 6: / Line 6: @@
 == Don't Panic ==
-When your game is doing things that it shouldn't be doing, and you can't figure out why, it's natural to feel some gloom and despair. This only gets worse the more you throw yourself at the problem, without any results. Try not to give into despair. You've managed to build up your code to it's current state - you're smart enough to squash it. If you take a structured approach and dig deep for a bit of persistence, you'll eventually understand the reason it's happening, and squash it.
+When your game is doing things that it shouldn't be doing, and you can't figure out why, it's natural to feel some gloom and despair. This only gets worse the more you throw yourself at the problem, without any results. Try not to give into despair. You've managed to build up your code to it's current state - you're smart enough to squash the bug. If you take a structured approach and dig deep for a bit of persistence, you'll eventually understand the reason why the bug is happening, and how to squash it.
 == What Changed? ==

@@ Line 72: / Line 72: @@
 * Interrupts not correctly starting or exiting: When a 6502 interrupt starts up, you should save all of the register values immediately, as well as clearing decimal mode if you do any addition or subtraction in the interrupt. Before you exit the interrupt, the same register values should be restored.
 * Interrupts reusing general purpose variables: Interrupts shouldn't be using temp variables that your main code uses, because your main code might just find those values have magically changed mid-routine, due to a triggered interrupt. Similarly, you need to be careful with other variable changes, and always consider that the interrupt code may become active anywhere in the body of your main code.
-* Runaway code execution: if you're not using otherwise using interrupts, setting the IRQ vector to an exception handler can provide helpful diagnostic information. <ref name="irqhandler">irq handler tip contributed by TailChao.</ref> In addition to providing feedback on unintentional interrupts, it could advise you to runaway code execution on 6502-based platforms, since the interrupt generating BRK opcode is represented by a byte value of $00, and $00 is often found in sections of data or empty ROM. If you are already using interrupts in your game, you can get a similar effect to the previous suggestion by filling your empty program space with NOP instructions, and ending banks/program sections with a jump to the exception handler.<ref name="nonirqrunaway">non-irq runaway code handler tip contributed by TailChao.</ref>
+* Runaway code execution: if you're not using otherwise using interrupts, setting the IRQ vector to an exception handler can provide helpful diagnostic information. <ref name="irqrunaway">irq runaway code handler tip contributed by TailChao.</ref> In addition to providing feedback on unintentional interrupts, it could advise you to runaway code execution on 6502-based platforms, since the interrupt generating BRK opcode is represented by a byte value of $00, and $00 is often found in sections of data or empty ROM. If you are already using interrupts in your game, you can get a similar effect to the previous suggestion by filling your empty program space with NOP instructions, and ending banks/program sections with a jump to the exception handler.<ref name="nonirqrunaway">non-irq runaway code handler tip contributed by TailChao.</ref>
 * Memory map overlap: It's common to reuse memory locations for two different purposes, on old platforms, because often there's not enough memory to go around. You need to be careful to ensure both memory uses don't accidentally overlap. Sometimes your code will start out without overlap, and then you later expand one of those uses with the faulty assumption the memory is dedicated.
 * Off-by-one errors: It's a common programming error to have a loop run for one more iteration than intended. This can be disastrous if the code in question sets up jump tables, causes a write to unintended RAM, or causes a bank-switch hotspot to be hit.

@@ Line 68: / Line 68: @@
 Here are some common things that can cause spectacular and difficult-to-trace failure in game code. Take these as a check-list, and consider if any of them might be the culprit with your bug.
-* Stack abuse: If your program has unmatched gosub/return or jsr/rts statements, you'll wind up with the stack overwriting memory it shouldn't, and unexpected crashing. Same thing if you have unmatched stack pushes and pops. One method of checking for stack abuse is to use a [https://en.wikipedia.org/wiki/Stack_buffer_overflow#Stack_canaries Stack Canary] in tandem with a debugger watch point, to ensure the canary isn't written to. <ref name="stackcanary">stack canary tip contributed by Karl Garrison</ref>. Another method to detect too many rts/return would be to push the return address for an exception handler to the base of the stack, which will eventually be executed if such a condition repeatedly happens. <ref name="exceptionstackbase">exception routine at the base of the stack tip contributed by TailChao.</ref> Lastly, if your stack issue is caused by an too many gosug/jsr, the address of the problem gosub/jsr will almost certainly be duplicated again and again in stack memory; check for it in a debugger, and look up what program code is at that location, in your assembly list file.
+* Stack abuse: If your program has unmatched gosub/return or jsr/rts statements, you'll wind up with the stack overwriting memory it shouldn't, and unexpected crashing. Same thing if you have unmatched stack pushes and pops. One method of checking for stack abuse is to use a [https://en.wikipedia.org/wiki/Stack_buffer_overflow#Stack_canaries Stack Canary] in tandem with a debugger watch point, to ensure the canary isn't written to. <ref name="stackcanary">stack canary tip contributed by Karl Garrison</ref>. Another method to detect too many rts/return would be to push the return address for an exception handler to the base of the stack, which will eventually be executed if such a condition repeatedly happens. <ref name="exceptionstackbase">exception routine at the base of the stack tip contributed by TailChao.</ref> Lastly, if your stack issue is caused by an too many gosub/jsr, the address of the problem gosub/jsr will almost certainly be duplicated again and again in stack memory; check for it in a debugger, and look up what program code is at that location, in your assembly list file.
 * Stack exhaustion: If you're using a portion of the stack memory as regular variables, as is often the case with 6502 based platforms, using too many nested subroutines may lead to those variables being unintentionally overwritten.
 * Interrupts not correctly starting or exiting: When a 6502 interrupt starts up, you should save all of the register values immediately, as well as clearing decimal mode if you do any addition or subtraction in the interrupt. Before you exit the interrupt, the same register values should be restored.