# XSPdb **Repository Path**: mingyuncode/XSPdb ## Basic Information - **Project Name**: XSPdb - **Description**: https://github.com/OpenXiangShan/XSPdb.git - **Primary Language**: Unknown - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-15 - **Last Updated**: 2026-01-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## XSPdb 介绍 [英文介绍](/README.en.md) XSPdb 是基于Python pdb调试器构建的专用RSIC-V IP调试工具，针对香山difftest接口核进行了定制，提供类GDB的交互式调试能力。该工具集成终端命令行界面、RTL级波形调试开关、自动化脚本回放、系统快照保存/恢复等基础功能模块，同时实现寄存器初始化配置、指令集反汇编解析等核心调试能力，并扩展支持断点条件触发、观察点实时追踪、寄存器/内存可视化监控等高级调试场景，通过硬件信号级调试接口与软件执行状态联动机制，为RISC-V IP的软硬件协同验证提供解决方案。
screenshot
XSPdb 截图
### 安装依赖 下载仓库，安装依赖： ``` git clone https://github.com/OpenXiangShan/XSPdb.git # 下载仓库 pip install -r XSPdb/requirements.txt # 安装依赖 pip install . # 根据需要确定是否需要安装 ``` 如果不需要源码集成，也可通过 pip 直接安装： ```bash pip3 install XSPdb@git+https://github.com/OpenXiangShan/XSPd@master ``` ### 快速开始 下载仓库安装依赖后，在仓库中执行`make test` ```bash cd XSPdb make test ``` 上述命令依次执行以下内容： - 下载XiangShan的二进制Python版本 - 下载测试bin文件 - 运行`example/test.py`进入XSPdb交互模式 示例输出与交互如下： ```bash LD_PRELOAD=XSPython/xspcomm/libxspcomm.so.0.0.1 PYTHONPATH=. python3 example/test.py Using simulated 32768B flash [Info] reset complete > XSPdb/example/test.py(13)test_sim_top() -> while True: (XiangShan) # 进入交互模式，可通过tab查询所有可用命令 (XiangShan)xui # 进入ui模式 (XiangShan)xload ready-to-run/microbench.bin # 加载需要运行的bin文件，命令可通过tab补全 (XiangShan)xistep # 执行到下一次指令提交 (XiangShan)xstep 10000 # 执行10000个cycles ``` 默认情况下，XSPdb会寻找系统中的`spike-dasm`进行反汇编，如果没找到，则采用`capstone`进行反汇编（部分指令`capstone`无法识别）。 ### 手动测试 XSPdb 交互的对象是 XiangShan的Python版本，因此需要提前构建，具体构建方法可参考：[TBD](TBD)。 为了方便测试，也可以在[Release中](https://github.com/OpenXiangShan/XSPdb/releases)下载编译好的版本: ```bash cd XSPdb wget https://github.com/OpenXiangShan/XSPdb/releases/download/v0.1.0-test/XSPython.tar.gz wget https://github.com/OpenXiangShan/XSPdb/releases/download/v0.1.0-test/ready-to-run.tar.gz tar xf XSPython.tar.gz tar xf ready-to-run.tar.gz ``` 然后，通过以下代码进行测试： ```bash LD_PRELOAD=XSPython/xspcomm/libxspcomm.so.0.0.1 PYTHONPATH=. python3 example/test.py ``` 使用LD_PRELOAD提前加载xspcomm的原因是防止本地系统xspcomm库与XSPython中的，有版本冲突. ### 命令行模式（非交互）： 除了提供交互模式外，XSPdb也提供了批处理模式，可以把它当成一个全系统仿真器使用，其入口为 `emu.py`，例如 ```bash ./emu.py -i ready-to-run/microbench.bin ``` `emu.py`在执行过程中，可以通过 ctrl+c 中断进入XSPdb交互模式。具体命令行参数如下： ```bash usage: emu.py [-h] [-v] [-C MAX_CYCLES] [-i IMAGE] [-b WAVE_BEGIN] [-e WAVE_END] [-t INTERACT_AT] [-l] [--log-file LOG_FILE] [-bi BATCH_INTERVAL] [-s SCRIPT] [-r REPLAY] [--debug-level {debug,info,warn,erro}] [--log-level {debug,info,warn,erro}] [-pc PC_COMMITS] [--sim-args SIM_ARGS] [-F FLASH] [--no-interact] [--wave-path WAVE_PATH] [--ram-size RAM_SIZE] [--diff DIFF] [--cmds CMDS] [--cmds-post CMDS_POST] [--mem-base-address MEM_BASE_ADDRESS] [--flash-base-address FLASH_BASE_ADDRESS] [--diff-first-inst_address DIFF_FIRST_INST_ADDRESS] [--trace-pc-symbol-block-change] [--max-run-time MAX_RUN_TIME] XSPdb Emulation Tool options: -h, --help show this help message and exit -v, --version show program's version number and exit -C MAX_CYCLES, --max-cycles MAX_CYCLES maximum simulation cycles to execute -i IMAGE, --image IMAGE image file to load and run -b WAVE_BEGIN, --wave-begin WAVE_BEGIN start waveform dump at the specified cycle -e WAVE_END, --wave-end WAVE_END stop waveform dump at the specified cycle -t INTERACT_AT, --interact-at INTERACT_AT enter interactive mode at the specified cycle -l, --log enable logging output --log-file LOG_FILE log file name (default: ./XSPdb.log) -bi BATCH_INTERVAL, --batch-interval BATCH_INTERVAL interval time (seconds) between batch commands -s SCRIPT, --script SCRIPT script file to execute -r REPLAY, --replay REPLAY replay log file --debug-level {debug,info,warn,erro} set debug level --log-level {debug,info,warn,erro} set log level -pc PC_COMMITS, --pc-commits PC_COMMITS run until the specified number of commits; -1 means no limit --sim-args SIM_ARGS additional simulator arguments (comma-separated) -F FLASH, --flash FLASH flash binary file for simulation --no-interact disable interactive mode (do not handle the ctrl-c signal) --wave-path WAVE_PATH output path for waveform file --ram-size RAM_SIZE simulation RAM size (e.g., 8GB or 128MB) --diff DIFF path to REF shared object for difftest testing --cmds CMDS XSPdb commands to execute before run (\n for newline) --cmds-post CMDS_POST XSPdb commands to execute after script/replay (\n for newline) --mem-base-address MEM_BASE_ADDRESS base address of memory --flash-base-address FLASH_BASE_ADDRESS base address of flash --diff-first-inst_address DIFF_FIRST_INST_ADDRESS first instruction address for difftest --trace-pc-symbol-block-change enable tracing of PC symbol block changes --max-run-time MAX_RUN_TIME maximum run time (eg 10s, 1m, 1h) ``` ### 常用命令： - `xload` Load a binary file into memory （加载指定bin文件到内存） - `xflash` Load a binary file into Flash （加载指定bin文件到Flash） - `xreset_flash` Reset Flash （重置Flash） - `xexport_bin` Export Flash + memory data to a file （导出Flash和内存数据到文件） - `xexport_flash` Export Flash data to a file （导出Flash数据到文件） - `xexport_ram` Export memory data to a file （导出内存数据到文件） - `xload_script` Load an XSPdb script （加载XSPdb脚本） - `xmem_write` Write memory data （写入内存数据） - `xbytes_to_bin` Convert bytes data to a binary file （将字节数据转换为bin文件） - `xnop_insert` Insert NOP instructions in a specified address range （在指定地址范围插入NOP指令） - `xclear_dasm_cache` Clear disassembly cache （清除反汇编缓存） - `xprint` Print the value and width of an internal signal （打印内部信号的值和宽度） - `xset` Set the value of an internal signal （设置内部信号的值） - `xstep` Step through the circuit （逐步执行电路） - `xistep` Step through instructions （逐步执行指令） - `xwatch_commit_pc` Watch commit PC （监视提交的PC） - `xunwatch_commit_pc` Unwatch commit PC （取消监视提交的PC） - `xwatch` Add a watch variable （添加监视变量） - `xunwatch` Remove a watch variable （移除监视变量） - `xpc` Print the current Commit PCs （打印当前提交的PC） - `xexpdiffstate` Set a variable to difftest_stat （将变量设置为difftest_stat） - `xexportself` Set a variable to XSPdb self （将变量设置为XSPdb自身） - `xreset` Reset DUT （重置DUT） - `xlist_xclock_cb` List all xclock callbacks （列出所有xclock回调） - `xui` Enter the Text UI interface （进入文本用户界面） - `xdasm` Disassemble memory data （反汇编内存数据） - `xdasmflash` Disassemble Flash data （反汇编Flash数据） - `xdasmbytes` Disassemble binary data （反汇编二进制数据） - `xdasmnumber` Disassemble a number （反汇编一个数字） - `xbytes2number` Convert bytes to an integer （将字节转换为整数） - `xnumber2bytes` Convert an integer to bytes （将整数转换为字节） - `xparse_instr_file` Parse uint64 strings （解析uint64字符串） - `xload_instr_file` Load uint64 strings into memory （加载uint64字符串到内存） - `xparse_reg_file` Parse a register file （解析寄存器文件） - `xload_reg_file` Load a register file （加载寄存器文件） - `xset_iregs` Set Flash internal registers (Integer) （设置Flash内部寄存器（整数）） - `xset_mpc` Set the jump address (by mpc) after Flash initialization, default is 0x80000000 （设置Flash初始化后的跳转地址（通过mpc），默认值为0x80000000） - `xget_mpc` Get the jump address after Flash initialization, default is 0x80000000 （获取Flash初始化后的跳转地址，默认值为0x80000000） - `xset_fregs` Set Flash floating-point registers (general) （设置Flash浮点寄存器（通用）） - `xset_ireg` Set a single Flash internal register (Integer) （设置单个Flash内部寄存器（整数）） - `xset_freg` Set a Flash floating-point register （设置Flash浮点寄存器） - `xlist_flash_iregs` List Flash internal registers （列出Flash内部寄存器） - `xlist_flash_fregs` List Flash floating-point registers （列出Flash浮点寄存器） - `xlist_freg_map` List floating-point register mappings （列出浮点寄存器映射） 可通过`xcmds`列出所有命令，说明和所在module（通过`xapis`列出所有API，说明和所在module）。