ROM Debugging Agent for AI-assisted ROM hacking. More...

#include <rom_debug_agent.h>

Collaboration diagram for yaze::cli::agent::RomDebugAgent:

[legend]

Classes
struct	BreakpointAnalysis
	Analysis result for a breakpoint hit. More...

struct	DetectedIssue
	Detected issue in ROM execution. More...

struct	MemoryAnalysis
	Analysis of a memory region. More...

struct	PatchComparisonResult
	Results from patch comparison. More...

Public Types
enum class	IssueType { kBadJumpTarget , kStackImbalance , kWramCorruption , kDmaConflict , kBankOverflow , kInvalidOpcode , kInfiniteLoop , kNullPointer , kAudioDesync , kPpuTimingViolation }
	Common ROM hacking issue types. More...

Public Member Functions
	RomDebugAgent (yaze::agent::EmulatorServiceImpl *emulator_service)

absl::StatusOr< BreakpointAnalysis >	AnalyzeBreakpoint (const yaze::agent::BreakpointHitResponse &hit)
	Analyze a breakpoint hit with full context.

absl::StatusOr< MemoryAnalysis >	AnalyzeMemory (uint32_t address, size_t length)
	Analyze a memory region and identify its purpose.

absl::StatusOr< std::string >	ExplainExecutionTrace (const std::vector< ExecutionTraceBuffer::TraceEntry > &trace)
	Analyze execution trace and explain program flow.

absl::StatusOr< PatchComparisonResult >	ComparePatch (uint32_t address, size_t length, const std::vector< uint8_t > &original)
	Compare original ROM code with patched code.

std::vector< DetectedIssue >	ScanForIssues (uint32_t start_address, uint32_t end_address)
	Scan for common ROM hacking issues in a code region.

bool	IsValidJumpTarget (uint32_t address) const
	Check if an address is a valid jump target.

bool	HasStackImbalance (uint32_t routine_start, uint32_t routine_end)
	Detect stack imbalance in a subroutine.

bool	IsMemoryWriteSafe (uint32_t address, size_t length) const
	Check if memory write is safe.

std::string	DescribeMemoryLocation (uint32_t address) const
	Get human-readable description of a memory address.

std::string	IdentifyDataType (uint32_t address) const
	Get the data type at a memory address.

std::string	FormatRegisterState (const std::map< std::string, uint16_t > &regs) const
	Format register state for debugging output.

absl::Status	LoadSymbols (const std::string &symbol_file)
	Load symbol table for better disassembly.

void	SetOriginalRom (const std::vector< uint8_t > &rom_data)
	Set the original ROM data for comparison.

Private Member Functions
absl::StatusOr< std::string >	AnalyzeInstruction (uint32_t address, const uint8_t *code, size_t max_length)
	Analyze the instruction at an address.

std::vector< std::string >	GetDisassemblyContext (uint32_t address, int before_lines, int after_lines)
	Get surrounding context for an address.

std::vector< std::string >	BuildCallStack (uint32_t current_pc)
	Build call stack from execution trace.

std::optional< DetectedIssue >	DetectIssuePattern (uint32_t address, const uint8_t *code, size_t length)
	Detect pattern of common issues.

bool	IsCriticalMemoryArea (uint32_t address) const
	Check if address is in a critical system area.

std::optional< std::string >	GetStructureInfo (uint32_t address) const
	Get structure information for a memory address.

Private Attributes
yaze::agent::EmulatorServiceImpl *	emulator_service_

std::unique_ptr< Disassembler65816 >	disassembler_

std::unique_ptr< yaze::emu::debug::SymbolProvider >	symbol_provider_

std::vector< uint8_t >	original_rom_

std::map< uint32_t, std::string >	address_description_cache_

std::map< uint32_t, std::string >	data_type_cache_

Static Private Attributes
static constexpr uint32_t	WRAM_START = 0x7E0000

static constexpr uint32_t	WRAM_END = 0x7FFFFF

static constexpr uint32_t	GAME_MODE = 0x7E0010

static constexpr uint32_t	SUBMODULE = 0x7E0011

static constexpr uint32_t	NMI_FLAG = 0x7E0012

static constexpr uint32_t	FRAME_COUNTER = 0x7E001A

static constexpr uint32_t	LINK_X_POS = 0x7E0022

static constexpr uint32_t	LINK_Y_POS = 0x7E0020

static constexpr uint32_t	LINK_STATE = 0x7E005D

static constexpr uint32_t	LINK_DIRECTION = 0x7E002F

static constexpr uint32_t	SPRITE_TABLE_START = 0x7E0D00

static constexpr uint32_t	SPRITE_TABLE_END = 0x7E0FFF

static constexpr uint32_t	SPRITE_STATE = 0x7E0D10

static constexpr uint32_t	SPRITE_X_LOW = 0x7E0D30

static constexpr uint32_t	SPRITE_X_HIGH = 0x7E0D20

static constexpr uint32_t	SPRITE_Y_LOW = 0x7E0D00

static constexpr uint32_t	SPRITE_Y_HIGH = 0x7E0D20

static constexpr uint32_t	OAM_BUFFER = 0x7E0800

static constexpr uint32_t	OAM_BUFFER_END = 0x7E0A1F

static constexpr uint32_t	DMA0_CONTROL = 0x004300

static constexpr uint32_t	DMA_ENABLE = 0x00420B

static constexpr uint32_t	HDMA_ENABLE = 0x00420C

static constexpr uint32_t	PPU_INIDISP = 0x002100

static constexpr uint32_t	PPU_BGMODE = 0x002105

static constexpr uint32_t	PPU_CGADD = 0x002121

static constexpr uint32_t	PPU_CGDATA = 0x002122

static constexpr uint32_t	APU_PORT0 = 0x002140

static constexpr uint32_t	APU_PORT1 = 0x002141

static constexpr uint32_t	APU_PORT2 = 0x002142

static constexpr uint32_t	APU_PORT3 = 0x002143

static constexpr uint32_t	SRAM_START = 0x7EF000

static constexpr uint32_t	SRAM_END = 0x7EF4FF

static constexpr uint32_t	PLAYER_NAME = 0x7EF000

static constexpr uint32_t	PLAYER_HEALTH = 0x7EF36D

static constexpr uint32_t	PLAYER_MAX_HEALTH = 0x7EF36C

static constexpr uint32_t	INVENTORY_START = 0x7EF340

Detailed Description

ROM Debugging Agent for AI-assisted ROM hacking.

Provides intelligent analysis of ROM execution, breakpoints, memory state, and ASM patches. Designed to help ROM hackers understand crashes, debug patches, and analyze game behavior.

Features:

Breakpoint analysis with disassembly and register state
Memory region analysis (sprites, tiles, game variables)
ASM patch comparison and debugging
Pattern detection for common ROM hacking issues
Execution trace analysis

Definition at line 35 of file rom_debug_agent.h.

Member Enumeration Documentation

◆ IssueType

enum class yaze::cli::agent::RomDebugAgent::IssueType

strong

Common ROM hacking issue types.

Enumerator
kBadJumpTarget
kStackImbalance
kWramCorruption
kDmaConflict
kBankOverflow
kInvalidOpcode
kInfiniteLoop
kNullPointer
kAudioDesync
kPpuTimingViolation

Definition at line 84 of file rom_debug_agent.h.

Constructor & Destructor Documentation

◆ RomDebugAgent()

yaze::cli::agent::RomDebugAgent::RomDebugAgent ( yaze::agent::EmulatorServiceImpl * emulator_service )

explicit

Definition at line 79 of file rom_debug_agent.cc.

References disassembler_.

Member Function Documentation

◆ AnalyzeBreakpoint()

absl::StatusOr< RomDebugAgent::BreakpointAnalysis > yaze::cli::agent::RomDebugAgent::AnalyzeBreakpoint ( const yaze::agent::BreakpointHitResponse & hit )

Analyze a breakpoint hit with full context.

Definition at line 87 of file rom_debug_agent.cc.

◆ AnalyzeMemory()

absl::StatusOr< RomDebugAgent::MemoryAnalysis > yaze::cli::agent::RomDebugAgent::AnalyzeMemory	(	uint32_t	address,
		size_t	length )

Analyze a memory region and identify its purpose.

Definition at line 154 of file rom_debug_agent.cc.

Here is the call graph for this function:

◆ ExplainExecutionTrace()

absl::StatusOr< std::string > yaze::cli::agent::RomDebugAgent::ExplainExecutionTrace ( const std::vector< ExecutionTraceBuffer::TraceEntry > & trace )

Analyze execution trace and explain program flow.

Definition at line 272 of file rom_debug_agent.cc.

References DescribeMemoryLocation(), yaze::zelda3::description, DMA0_CONTROL, and symbol_provider_.

Here is the call graph for this function:

◆ ComparePatch()

absl::StatusOr< RomDebugAgent::PatchComparisonResult > yaze::cli::agent::RomDebugAgent::ComparePatch	(	uint32_t	address,
		size_t	length,
		const std::vector< uint8_t > &	original )

Compare original ROM code with patched code.

Definition at line 415 of file rom_debug_agent.cc.

Here is the call graph for this function:

◆ ScanForIssues()

std::vector< RomDebugAgent::DetectedIssue > yaze::cli::agent::RomDebugAgent::ScanForIssues	(	uint32_t	start_address,
		uint32_t	end_address )

Scan for common ROM hacking issues in a code region.

Definition at line 545 of file rom_debug_agent.cc.

References DetectIssuePattern(), disassembler_, emulator_service_, kInvalidOpcode, and yaze::agent::EmulatorServiceImpl::ReadMemory().

Here is the call graph for this function:

◆ IsValidJumpTarget()

bool yaze::cli::agent::RomDebugAgent::IsValidJumpTarget ( uint32_t address ) const

Check if an address is a valid jump target.

Definition at line 595 of file rom_debug_agent.cc.

References WRAM_END, and WRAM_START.

Referenced by ComparePatch().

◆ HasStackImbalance()

bool yaze::cli::agent::RomDebugAgent::HasStackImbalance	(	uint32_t	routine_start,
		uint32_t	routine_end )

Detect stack imbalance in a subroutine.

Definition at line 618 of file rom_debug_agent.cc.

References disassembler_, emulator_service_, and yaze::agent::EmulatorServiceImpl::ReadMemory().

Here is the call graph for this function:

◆ IsMemoryWriteSafe()

bool yaze::cli::agent::RomDebugAgent::IsMemoryWriteSafe	(	uint32_t	address,
		size_t	length ) const

Check if memory write is safe.

Definition at line 683 of file rom_debug_agent.cc.

References DMA0_CONTROL, and NMI_FLAG.

◆ DescribeMemoryLocation()

std::string yaze::cli::agent::RomDebugAgent::DescribeMemoryLocation ( uint32_t address ) const

Get human-readable description of a memory address.

Definition at line 721 of file rom_debug_agent.cc.

References address_description_cache_, APU_PORT0, APU_PORT3, yaze::zelda3::description, DMA0_CONTROL, DMA_ENABLE, FRAME_COUNTER, GAME_MODE, HDMA_ENABLE, INVENTORY_START, LINK_DIRECTION, LINK_STATE, LINK_X_POS, LINK_Y_POS, NMI_FLAG, OAM_BUFFER, OAM_BUFFER_END, PLAYER_HEALTH, PLAYER_MAX_HEALTH, PLAYER_NAME, PPU_BGMODE, PPU_CGADD, PPU_CGDATA, PPU_INIDISP, SPRITE_TABLE_END, SPRITE_TABLE_START, SRAM_END, SRAM_START, SUBMODULE, WRAM_END, and WRAM_START.

Referenced by AnalyzeMemory(), and ExplainExecutionTrace().

◆ IdentifyDataType()

std::string yaze::cli::agent::RomDebugAgent::IdentifyDataType ( uint32_t address ) const

Get the data type at a memory address.

Definition at line 817 of file rom_debug_agent.cc.

References APU_PORT0, APU_PORT3, data_type_cache_, DMA0_CONTROL, INVENTORY_START, OAM_BUFFER, OAM_BUFFER_END, SPRITE_TABLE_END, SPRITE_TABLE_START, SRAM_END, SRAM_START, WRAM_END, and WRAM_START.

Referenced by AnalyzeMemory().

◆ FormatRegisterState()

std::string yaze::cli::agent::RomDebugAgent::FormatRegisterState ( const std::map< std::string, uint16_t > & regs ) const

Format register state for debugging output.

Definition at line 851 of file rom_debug_agent.cc.

◆ LoadSymbols()

absl::Status yaze::cli::agent::RomDebugAgent::LoadSymbols ( const std::string & symbol_file )

Load symbol table for better disassembly.

Definition at line 866 of file rom_debug_agent.cc.

References symbol_provider_.

◆ SetOriginalRom()

void yaze::cli::agent::RomDebugAgent::SetOriginalRom ( const std::vector< uint8_t > & rom_data )

Set the original ROM data for comparison.

Definition at line 870 of file rom_debug_agent.cc.

References original_rom_.

◆ AnalyzeInstruction()

absl::StatusOr< std::string > yaze::cli::agent::RomDebugAgent::AnalyzeInstruction	(	uint32_t	address,
		const uint8_t *	code,
		size_t	max_length )

private

Analyze the instruction at an address.

Definition at line 876 of file rom_debug_agent.cc.

Referenced by AnalyzeBreakpoint().

◆ GetDisassemblyContext()

std::vector< std::string > yaze::cli::agent::RomDebugAgent::GetDisassemblyContext	(	uint32_t	address,
		int	before_lines,
		int	after_lines )

private

Get surrounding context for an address.

Definition at line 954 of file rom_debug_agent.cc.

References emulator_service_, and yaze::agent::EmulatorServiceImpl::GetDisassembly().

Referenced by AnalyzeBreakpoint().

Here is the call graph for this function:

◆ BuildCallStack()

std::vector< std::string > yaze::cli::agent::RomDebugAgent::BuildCallStack ( uint32_t current_pc )

private

Build call stack from execution trace.

Definition at line 984 of file rom_debug_agent.cc.

References emulator_service_, yaze::agent::EmulatorServiceImpl::GetExecutionTrace(), and symbol_provider_.

Referenced by AnalyzeBreakpoint().

Here is the call graph for this function:

◆ DetectIssuePattern()

std::optional< RomDebugAgent::DetectedIssue > yaze::cli::agent::RomDebugAgent::DetectIssuePattern	(	uint32_t	address,
		const uint8_t *	code,
		size_t	length )

private

Detect pattern of common issues.

Definition at line 1021 of file rom_debug_agent.cc.

References kInfiniteLoop, kInvalidOpcode, kStackImbalance, and kWramCorruption.

Referenced by AnalyzeBreakpoint(), and ScanForIssues().

◆ IsCriticalMemoryArea()

bool yaze::cli::agent::RomDebugAgent::IsCriticalMemoryArea ( uint32_t address ) const

private

Check if address is in a critical system area.

Definition at line 1093 of file rom_debug_agent.cc.

References DMA0_CONTROL, and NMI_FLAG.

Referenced by ComparePatch().

◆ GetStructureInfo()

std::optional< std::string > yaze::cli::agent::RomDebugAgent::GetStructureInfo ( uint32_t address ) const

private

Get structure information for a memory address.

Definition at line 1117 of file rom_debug_agent.cc.

References DMA0_CONTROL, OAM_BUFFER, OAM_BUFFER_END, SPRITE_TABLE_END, and SPRITE_TABLE_START.

Referenced by AnalyzeMemory().

Member Data Documentation

◆ WRAM_START

constexpr uint32_t yaze::cli::agent::RomDebugAgent::WRAM_START = 0x7E0000

staticconstexprprivate

Definition at line 191 of file rom_debug_agent.h.

Referenced by DescribeMemoryLocation(), IdentifyDataType(), and IsValidJumpTarget().

◆ WRAM_END

constexpr uint32_t yaze::cli::agent::RomDebugAgent::WRAM_END = 0x7FFFFF

staticconstexprprivate

Definition at line 192 of file rom_debug_agent.h.

Referenced by DescribeMemoryLocation(), IdentifyDataType(), and IsValidJumpTarget().

◆ GAME_MODE

constexpr uint32_t yaze::cli::agent::RomDebugAgent::GAME_MODE = 0x7E0010

staticconstexprprivate

Definition at line 195 of file rom_debug_agent.h.

	yaze 0.3.2 Link to the Past ROM Editor

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ IssueType

Constructor & Destructor Documentation

◆ RomDebugAgent()

Member Function Documentation

◆ AnalyzeBreakpoint()

◆ AnalyzeMemory()

◆ ExplainExecutionTrace()

◆ ComparePatch()

◆ ScanForIssues()

◆ IsValidJumpTarget()

◆ HasStackImbalance()

◆ IsMemoryWriteSafe()

◆ DescribeMemoryLocation()

◆ IdentifyDataType()

◆ FormatRegisterState()

◆ LoadSymbols()

◆ SetOriginalRom()

◆ AnalyzeInstruction()

◆ GetDisassemblyContext()

◆ BuildCallStack()

◆ DetectIssuePattern()

◆ IsCriticalMemoryArea()

◆ GetStructureInfo()

Member Data Documentation

◆ WRAM_START

◆ WRAM_END

◆ GAME_MODE

◆ SUBMODULE

◆ NMI_FLAG

◆ FRAME_COUNTER

◆ LINK_X_POS

◆ LINK_Y_POS

◆ LINK_STATE

◆ LINK_DIRECTION

◆ SPRITE_TABLE_START

◆ SPRITE_TABLE_END

◆ SPRITE_STATE

◆ SPRITE_X_LOW

◆ SPRITE_X_HIGH

◆ SPRITE_Y_LOW

◆ SPRITE_Y_HIGH

◆ OAM_BUFFER

◆ OAM_BUFFER_END

◆ DMA0_CONTROL

◆ DMA_ENABLE

◆ HDMA_ENABLE

◆ PPU_INIDISP

◆ PPU_BGMODE

◆ PPU_CGADD

◆ PPU_CGDATA

◆ APU_PORT0

◆ APU_PORT1

◆ APU_PORT2

◆ APU_PORT3

◆ SRAM_START

◆ SRAM_END

◆ PLAYER_NAME

◆ PLAYER_HEALTH

◆ PLAYER_MAX_HEALTH

◆ INVENTORY_START

◆ emulator_service_

◆ disassembler_

◆ symbol_provider_

◆ original_rom_

◆ address_description_cache_

◆ data_type_cache_