rom_debug_agent.h

Go to the documentation of this file.

#ifndef YAZE_CLI_SERVICE_AGENT_ROM_DEBUG_AGENT_H_
#define YAZE_CLI_SERVICE_AGENT_ROM_DEBUG_AGENT_H_
 
#include <cstdint>
#include <map>
#include <memory>
#include <string>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/emu/debug/symbol_provider.h"
#include "cli/service/agent/disassembler_65816.h"
#include "cli/service/agent/emulator_service_impl.h"
#include "protos/emulator_service.grpc.pb.h"
 
namespace yaze {
namespace cli {
namespace agent {
 
class RomDebugAgent {
 public:
  struct BreakpointAnalysis {
    uint32_t address;                        // Breakpoint address
    std::string location_description;        // Human-readable location (e.g., "MainGameLoop+$10")
    std::string disassembly;                 // Disassembled instruction
    std::string instruction_explanation;     // AI-friendly explanation of what the instruction does
    std::map<std::string, uint16_t> registers;  // Current register values
    std::vector<std::string> call_stack;     // Call stack leading to this point
    std::vector<std::string> context_lines;  // Surrounding disassembly for context
    std::vector<std::string> suggestions;    // Debugging suggestions
    std::string memory_context;              // Relevant memory state description
  };
 
  struct MemoryAnalysis {
    uint32_t address;                // Memory address
    size_t length;                   // Length of analyzed region
    std::string data_type;           // "sprite", "tile", "palette", "dma", "audio", etc.
    std::string structure_name;      // Specific structure name if known
    std::string description;         // Human-readable description
    std::vector<uint8_t> data;       // Raw data
    std::map<std::string, uint32_t> fields;  // Parsed fields (if structured data)
    std::vector<std::string> anomalies;      // Detected issues or unusual values
  };
 
  struct PatchComparisonResult {
    uint32_t address;                   // Patch location
    size_t length;                      // Patch size
    std::vector<uint8_t> original_code;  // Original ROM code
    std::vector<uint8_t> patched_code;   // Patched code
    std::string original_disassembly;   // Disassembled original
    std::string patched_disassembly;    // Disassembled patch
    std::vector<std::string> differences;  // Key differences explained
    std::vector<std::string> potential_issues;  // Detected problems
    bool is_safe;                       // Whether patch appears safe
  };
 
  enum class IssueType {
    kBadJumpTarget,       // Jump to invalid address
    kStackImbalance,      // Stack pointer corruption
    kWramCorruption,      // Writing to critical WRAM areas
    kDmaConflict,         // DMA during wrong time
    kBankOverflow,        // Code/data exceeds bank boundary
    kInvalidOpcode,       // Executing data as code
    kInfiniteLoop,        // Detected infinite loop
    kNullPointer,         // Dereferencing zero page incorrectly
    kAudioDesync,         // SPC700 communication issue
    kPpuTimingViolation,  // Writing to PPU at wrong time
  };
 
  struct DetectedIssue {
    IssueType type;
    uint32_t address;
    std::string description;
    std::string suggested_fix;
    int severity;  // 1-5, 5 being most severe
  };
 
  // Constructor
  explicit RomDebugAgent(yaze::agent::EmulatorServiceImpl* emulator_service);
 
  // --- Core Analysis Functions ---
 
  absl::StatusOr<BreakpointAnalysis> AnalyzeBreakpoint(
      const yaze::agent::BreakpointHitResponse& hit);
 
  absl::StatusOr<MemoryAnalysis> AnalyzeMemory(
      uint32_t address, size_t length);
 
  absl::StatusOr<std::string> ExplainExecutionTrace(
      const std::vector<ExecutionTraceBuffer::TraceEntry>& trace);
 
  absl::StatusOr<PatchComparisonResult> ComparePatch(
      uint32_t address, size_t length, const std::vector<uint8_t>& original);
 
  // --- Pattern Detection ---
 
  std::vector<DetectedIssue> ScanForIssues(
      uint32_t start_address, uint32_t end_address);
 
  bool IsValidJumpTarget(uint32_t address) const;
 
  bool HasStackImbalance(uint32_t routine_start, uint32_t routine_end);
 
  bool IsMemoryWriteSafe(uint32_t address, size_t length) const;
 
  // --- Helper Functions ---
 
  std::string DescribeMemoryLocation(uint32_t address) const;
 
  std::string IdentifyDataType(uint32_t address) const;
 
  std::string FormatRegisterState(const std::map<std::string, uint16_t>& regs) const;
 
  absl::Status LoadSymbols(const std::string& symbol_file);
 
  void SetOriginalRom(const std::vector<uint8_t>& rom_data);
 
 private:
  // --- ALTTP Memory Layout Constants ---
 
  // WRAM regions ($7E0000-$7FFFFF)
  static constexpr uint32_t WRAM_START = 0x7E0000;
  static constexpr uint32_t WRAM_END = 0x7FFFFF;
 
  // System variables
  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;
 
  // Player/Link state
  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;
 
  // Sprite tables
  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;
 
  // OAM (Object Attribute Memory) buffer
  static constexpr uint32_t OAM_BUFFER = 0x7E0800;
  static constexpr uint32_t OAM_BUFFER_END = 0x7E0A1F;
 
  // DMA registers
  static constexpr uint32_t DMA0_CONTROL = 0x004300;
  static constexpr uint32_t DMA_ENABLE = 0x00420B;
  static constexpr uint32_t HDMA_ENABLE = 0x00420C;
 
  // PPU registers
  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;
 
  // Audio communication
  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;
 
  // Save data
  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;
 
  // --- Helper Methods ---
 
  absl::StatusOr<std::string> AnalyzeInstruction(
      uint32_t address, const uint8_t* code, size_t max_length);
 
  std::vector<std::string> GetDisassemblyContext(
      uint32_t address, int before_lines, int after_lines);
 
  std::vector<std::string> BuildCallStack(uint32_t current_pc);
 
  std::optional<DetectedIssue> DetectIssuePattern(
      uint32_t address, const uint8_t* code, size_t length);
 
  bool IsCriticalMemoryArea(uint32_t address) const;
 
  std::optional<std::string> GetStructureInfo(uint32_t address) const;
 
  // Member variables
  yaze::agent::EmulatorServiceImpl* emulator_service_;  // Non-owning pointer
  std::unique_ptr<Disassembler65816> disassembler_;
  std::unique_ptr<yaze::emu::debug::SymbolProvider> symbol_provider_;
  std::vector<uint8_t> original_rom_;  // Original ROM for comparison
 
  // Cache for performance
  mutable std::map<uint32_t, std::string> address_description_cache_;
  mutable std::map<uint32_t, std::string> data_type_cache_;
};
 
}  // namespace agent
}  // namespace cli
}  // namespace yaze
 
#endif  // YAZE_CLI_SERVICE_AGENT_ROM_DEBUG_AGENT_H_