Help:Contents/Finding Content/Debugger guide

To do: Add guides to more debuggers

A debugger allows the user to run through the assembly code of a program, ROM image, BIOS, etc. Note for beginner hackers, it is recommended to start with simpler methods such as an emulator's in-built cheat searcher.

This guide will both explain the basics of debuggers and how to use them to find new unused content.

Debuggers

32px	BGB BGB is an emulator for Game Boy and Game Boy Color

Basic Terminology

• A routine (or subroutine for smaller routines contained within larger ones) refers to any function/program in the game to be run by the CPU.
• An index number or identifier is a number used to represent data for a register, memory address/pointer, opcode or operand. It can be in hexadecimal, decimal, and so on.
• Hexadecimal is the base-16 number system (0-F) usually stored in at least one byte (00-FF or 0 through 255 in decimal). Decimal is the base-10 number system (0-9). Binary is the base-2 number system (0 or 1) and the decimal values (+)2^0, 2^1 through to 2^7 are considered as the bits, because there are usually 8 bits in a byte.
• The CPU (Central Processing Unit) can be considered as like the 'brain' of the platform's architecture. Low-level programming refers to code closer to the machine level, and is typically harder to use by humans (such as Z80) than higher level code such as C++.
• An opcode is an instruction used by the CPU or the index number of it. Here is an example list of opcodes for the Game Boy/Game Boy Color's GBZ80 processor.
• An operand is for the value or values used with an opcode/instruction.
• The code refers to bytes run by the CPU (for routines or subroutines), while data is normally not intended to be run by the CPU (for data structures like sprite, audio, map information)
• A breakpoint allows the player to pause the game after specific criteria is met during gameplay, such as accessing a certain position in the program counter, or editing a memory address.
• The program counter is the current instruction (opcode which may include an operand with it) the CPU is running.
• A memory address is an offset or pointer representation of a location in the game or the platform's ROM, RAM, I/O, etc. An offset can be differentiated as the exact location in a hex editor (or the location relative to a position), while a pointer is a representation of the location derived from the offset and used internally by the game. The pointer may also be banked in a ROM that supports the Memory Bank Controller, as consoles like the Game Boy cannot access all of the ROM at once.
• The MBC (Memory Bank Controller) is responsible for operations/storing in banked memory. Sometimes false writes to ROM are used to specify and run a Memory Bank Controller command, such as changing banks. In the case of the Game Boy, typically this only applies to pointers 4000-7FFF for ROM (0000-3FFF are bankless or 'bank 0') and some games have banked SRAM or WRAM.
• The stack controls the flow of code after an old subroutine has ended. ret runs the routine currently located on the stack and then adds 2 to the stack pointer. The stack pointer is a location directing to a list of pointers (two-byte pointers for Game Boy/Color at the bank stored in the MBC) to run in game, and for the stack pointer stored in the hardware registers, ret will move to the first pointer in the list. In addition to directly writing to the stack pointer, one can push or pop to manipulate the stack with a memory pair. Push on the stack takes away 2 from the stack pointer then moves the register pair's representation to be the current stack pointer, while pop adds 2 to the stack pointer instead.
• A jump (jp) directly moves the program counter to the specified address, while a call adds the next instruction to the current stack pointer, so that ret can continue directly after the call.
• A hardware register is used as storage for the specific platform's processor/CPU. Also, while a value can be stored into a RAM memory address, the value is stored into a hardware register first.
• A flag (for the CPU) can be on or off, and is used for conditional checks during runtime. However, there may be an index number with more possibilities than just on/off for a hardware register used to specify data about a specific flag as well.
• Hardware timing can be split into CPU (processor) and GPU (video) cycles.
• V-Blank (Vertical blanking interval) represents the time in between the end of the frame's visible line and the next frame's first visible line. It may also refer to the Vblank function in a video game.
• PPU (Picture Processing Unit) is responsible for generating the video signal on a television.
• OAM (Object Attribute Memory) controls information about sprite tiles in PPU. Also an OAM DMA (Object Attribute Memory Direct Memory Access) routine may be used in the code.
• LCDC Y-Coordinate (register LY in Game Boy) is the vertical line for transferring the present data to the LCD Driver. On Game Boy, it ranges between 0-153. V-Blank must occur during 144 to 153.