sdb.h

/*
 * sdb.h - SDB (SPARC Debugger) for UT699/LEON3 Simulator
 *
 * Enhanced debugger for SPARC V8 simulation with features:
 * - Code and data breakpoints
 * - Watchpoints on memory and registers
 * - Call stack display
 * - Pipeline state inspection
 * - Performance counters
 * - Profiling integration
 *
 * Based on DLite from SimpleScalar, extensively modified for SPARC V8.
 */

#ifndef SDB_H
#define SDB_H

#include <stdio.h>

#include "host.h"
#include "misc.h"
#include "machine.h"
#include "regs.h"
#include "memory.h"
#include "eval.h"

/*
 * Supported SDB Commands:
 *
 * help              - print command reference
 * version           - print SDB version information
 * terminate         - terminate the simulation with statistics
 * quit              - exit the simulator
 * cont {<addr>}     - continue program execution (optionally at <addr>)
 * step              - step program one instruction
 * next              - step program one instruction in current procedure
 * stepi <n>         - step <n> instructions
 * print <expr>      - print the value of <expr>
 * regs              - print register contents
 * fregs             - print floating-point register contents
 * sregs             - print special/control registers (PSR, WIM, TBR, Y)
 * windows           - print all register windows
 * mstate            - print machine specific state
 * display/<mods> <addr> - display the value at <addr> using format <modifiers>
 * dump {<addr>} {<cnt>} - dump memory at <addr> (optionally for <cnt> words)
 * dis <addr> {<cnt>}    - disassemble instructions at <addr>
 * break <addr>      - set breakpoint at <addr>
 * dbreak <addr> {r|w|x} - set data breakpoint at <addr>
 * watch <reg>       - set watchpoint on register <reg>
 * breaks            - list active breakpoints and watchpoints
 * delete <id>       - delete breakpoint/watchpoint <id>
 * clear             - clear all breakpoints and watchpoints
 * bt                - print backtrace (call stack)
 * info              - print pipeline and simulation info
 * profile           - show profiling summary
 * reset             - reset CPU to initial state
 * symbols           - list loaded symbols
 * where             - show current location with source context
 *
 * Command modifiers <mods>:
 * b - print a byte
 * h - print a half (short)
 * w - print a word
 * q - print a qword
 * d - print in decimal format
 * u - print in unsigned decimal format
 * o - print in octal format
 * x - print in hex format
 * 1 - print in binary format
 * f - print a float
 * F - print a double
 * c - print a character
 * s - print a string
 */

/* Maximum call stack depth for backtrace */
#define SDB_MAX_CALL_DEPTH    256

/* Maximum number of breakpoints */
#define SDB_MAX_BREAKPOINTS   64

/* Maximum number of watchpoints */
#define SDB_MAX_WATCHPOINTS   32

/* Breakpoint types */
#define SDB_BP_CODE     0x01    /* Code breakpoint */
#define SDB_BP_DATA_R   0x02    /* Data read breakpoint */
#define SDB_BP_DATA_W   0x04    /* Data write breakpoint */
#define SDB_BP_DATA_X   0x08    /* Data execute breakpoint */

/* Watchpoint types */
#define SDB_WP_REG      0x10    /* Register watchpoint */
#define SDB_WP_MEM      0x20    /* Memory watchpoint */

/* Call stack entry */
typedef struct {
    md_addr_t call_pc;      /* PC of CALL instruction */
    md_addr_t func_addr;    /* Address of called function */
    md_addr_t return_addr;  /* Expected return address */
    counter_t entry_cycle;  /* Cycle when function was entered */
    counter_t entry_insn;   /* Instruction count at entry */
    char func_name[64];     /* Function name (if known) */
} sdb_call_entry_t;

/* Call stack structure */
typedef struct {
    sdb_call_entry_t entries[SDB_MAX_CALL_DEPTH];
    int depth;
} sdb_call_stack_t;

/* SDB register access function type */
typedef char *                          /* error str, NULL if none */
(*sdb_reg_obj_t)(struct regs_t *regs,   /* registers to access */
                 int is_write,          /* access type */
                 enum md_reg_type rt,   /* reg bank to access */
                 int reg,               /* register number */
                 struct eval_value_t *val);  /* input, output */

/* SDB memory access function type */
typedef char *                          /* error str, NULL if none */
(*sdb_mem_obj_t)(struct mem_t *mem,     /* memory space to access */
                 int is_write,          /* access type */
                 md_addr_t addr,        /* address to access */
                 char *p,               /* input/output buffer */
                 int nbytes);           /* size of access */

/* SDB machine state display function type */
typedef char *                          /* error str, NULL if none */
(*sdb_mstate_obj_t)(FILE *stream,       /* output stream */
                    char *cmd,          /* optional command string */
                    struct regs_t *regs,/* registers to access */
                    struct mem_t *mem); /* memory space to access */

/* Initialize the SDB debugger */
void sdb_init(sdb_reg_obj_t reg_obj,        /* register state object */
              sdb_mem_obj_t mem_obj,        /* memory state object */
              sdb_mstate_obj_t mstate_obj); /* machine state object */

/* Default memory state accessor */
char *sdb_mem_obj(struct mem_t *mem,    /* memory space to access */
                  int is_write,         /* access type */
                  md_addr_t addr,       /* address to access */
                  char *p,              /* input, output */
                  int nbytes);          /* size of access */

/* Default machine-specific state accessor */
char *sdb_mstate_obj(FILE *stream,          /* output stream */
                     char *cmd,             /* optional command string */
                     struct regs_t *regs,   /* registers to access */
                     struct mem_t *mem);    /* memory space to access */

/* State access masks */
#define ACCESS_READ     0x01    /* read access allowed */
#define ACCESS_WRITE    0x02    /* write access allowed */
#define ACCESS_EXEC     0x04    /* execute access allowed */

/* Non-zero iff one breakpoint is set, for fast break check */
extern md_addr_t sdb_fastbreak;

/* Set non-zero to enter SDB after next instruction */
extern int sdb_active;

/* Non-zero to force a check for a break */
extern int sdb_check;

/* Internal break check interface */
int __sdb_check_break(md_addr_t next_PC,    /* address of next inst */
                      int access,           /* mem access of last inst */
                      md_addr_t addr,       /* mem addr of last inst */
                      counter_t icount,     /* instruction count */
                      counter_t cycle);     /* cycle count */

/* Check for a break condition (macro for speed) */
#define sdb_check_break(NPC, ACCESS, ADDR, ICNT, CYCLE)         \
  ((sdb_check || sdb_active)                                    \
   ? __sdb_check_break((NPC), (ACCESS), (ADDR), (ICNT), (CYCLE))\
   : FALSE)

/* SDB debugger main loop */
void sdb_main(md_addr_t regs_PC,        /* addr of last inst to exec */
              md_addr_t next_PC,        /* addr of next inst to exec */
              counter_t cycle,          /* current processor cycle */
              struct regs_t *regs,      /* registers to access */
              struct mem_t *mem);       /* memory to access */

/*
 * Call Stack Tracking API
 */

/* Initialize call stack tracking */
void sdb_call_stack_init(void);

/* Push a function call onto the call stack */
void sdb_call_push(md_addr_t call_pc, md_addr_t func_addr, 
                   counter_t cycle, counter_t insn);

/* Pop a function return from the call stack */
void sdb_call_pop(md_addr_t return_pc, counter_t cycle, counter_t insn);

/* Get current call stack depth */
int sdb_call_depth(void);

/* Print backtrace */
void sdb_print_backtrace(FILE *stream);

/*
 * Enhanced Features
 */

/* Print all register windows */
void sdb_print_windows(FILE *stream, struct regs_t *regs);

/* Print control registers (PSR, WIM, TBR, Y) */
void sdb_print_control_regs(FILE *stream, struct regs_t *regs);

/* Print floating-point registers */
void sdb_print_fp_regs(FILE *stream, struct regs_t *regs);

/* Print pipeline state (for sim-inorder) */
void sdb_print_pipeline(FILE *stream);

/* Print simulation info and statistics */
void sdb_print_info(FILE *stream);

/* Reset CPU state (for reset command) */
void sdb_reset_cpu(struct regs_t *regs, struct mem_t *mem);

#endif /* SDB_H */