submodule(difftest): refactor DiffTop, PhyReg and Refill #5221
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
klin02
requested review from
Gao-Zeyu,
Tang-Haojin,
cebarobot,
good-circle,
linjuanZ and
ngc7331
as code owners
klin02
force-pushed
the
difftest-kmh-v3
branch
2 times, most recently
from
9e55611 to
df13598
Compare
ngc7331
added
the
module: tool
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
klin02
force-pushed
the
difftest-kmh-v3
branch
2 times, most recently
from
6ca433c to
9331c8d
Compare
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
Maxpicca-Li
approved these changes
Dec 8, 2025
klin02
force-pushed
the
difftest-kmh-v3
branch
3 times, most recently
from
f446ef0 to
98ff9b2
Compare
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
klin02
force-pushed
the
difftest-kmh-v3
branch
from
98ff9b2 to
bbf6aab
Compare
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
klin02
force-pushed
the
difftest-kmh-v3
branch
from
bbf6aab to
40ef692
Compare
klin02
requested review from
NewPaulWalker,
lewislzh,
wissygh,
xiaofeibao-xjtu and
yaozhicheng
as code owners
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
klin02
force-pushed
the
difftest-kmh-v3
branch
from
40ef692 to
1a2ffed
Compare
Latest difftest introduces following notable change: 1. CPU as submodule of Difftest Difftest now allows instantiating the CPU as a submodule and exposing additional IOs. LazyModules must explicitly provide clock and reset signals. (PRs: difftest#713, difftest#757, difftest#758) 2. Replace ArchReg + WriteBack with PhyReg + RenameTable The old embedded-into-CPU Difftest logic is removed. The new PhyReg + RenameTable interface eliminates additional phy-to-arch logic and multi- read-port overhead inside the CPU and removes interface of ArchReg/WriteBack. (PRs: difftest#714, difftest#754) 3. RefillEvent interface modification Refill checking now support masked refill-check to support low-power read. (PRs: difftest#719, difftest#723) 4. PGO_BOLT option for emu compilation A new PGO_BOLT mode is provided to accelerate EMU compilation under profile-guided optimization. (PR: difftest#756, difftest#761)
This change moves XSDiffTop instantiation into the Difftest for fpgaDiff. DiffTop will generated with a SimTop wrapper, where DiffTest outputs, together with XSTop's IO ports, AXI4 buses of memory/peripheral/DMA will be exposed for external connection. Temporarily, we still expose XSNoCDiffTop with appended Difftest IOs, and generate XSTop and XSNoCTop with internal Difftest DPI-C, so as to avoid extra TopIOs and mixed generated files. We will try to refactor them like DiffTop later.(i.e. generate with a seperated Difftest)
This change refactors Difftest interfaces, replacing the previous ArchReg and WriteBack with PhyRegState and ArchRenameTable. By default, Difftest still extracts PhyReg and RenameTable into ArchReg on the hardware side, so that the extra multi-read area is accounted for within Difftest. When acceleration is enabled, this extraction is deferred to the software side, eliminating the extra hardware area overhead. Since 128-bit ArchVecReg are now treated as two 64-bit registers in Difftest, we add corresponding register splitting in XiangShan. The address indexs (InstrCommit.otherwpdest and RenameTable) are also converted from `index` to `2*index` and `2*index + 1` for reg splitting. Note XiangShan separates V0 and Vf register files. When mering the two regfiles and renameTable for Difftest, the indexs of Vf must add offset of V0RegSize to ensure correct indexing.
After #3051, we have supported low-power read (read only 5 out of 8 8B-banks) in ICacheDataArray, and in V3, it was further modified to dynamically compute the mask based on the taken branch location. Though, previous DiffRefillEvent does not support masked comparison, instead it checks entire 512bit, so it will fail if we enable checks on cacheid >=3 (OpenXiangShan/difftest#712). As we're refactoring ICache recently, we need this check to ensure the refactored code is working properly. This commit removes unused idtfr and introduces masked refill-check for Difftest, where each mask bit controls comparison of 8B data. However, as the newly added masked Refill fails CI, we disable it for now, and wait for later fixup. Co-authored-by: ngc7331 <[email protected]>
This change unifies the args handling for PLDM and FPGA_DIFF into a shared DEBUG_ARGS options, with PLDM=1 or FPGA=1 used to distinguish between the two environments. For PLDM, we continue to enable the full Difftest by default as it used to be. For FPGA, we set it default to BASIC_DIFF and remove additional debug printing to reduce overhead. Any extra options can be supplied via DEBUG_ARGS as needed. Example usage: PLDM=1 DEBUG_ARGS="--difftest-config ZESN --perf-level CRITICAL" FPGA=1 DEBUG_ARGS="--difftest-config ESBIFDU --difftest-exclude Vec"
## Description This PR adds comprehensive difftest capabilities to xspdb, enabling developers to perform co-simulation debugging with reference models. ## Features ### Core APIs - `api_load_ref_so()`: Load difftest reference shared object - `api_init_ref()`: Initialize difftest reference - `api_set_difftest_diff()`: Turn on/off difftest checking - `api_difftest_reset()`: Reset difftest state ### Debugging Commands - `xload_difftest_ref_so <path>`: Load reference .so file - `xdifftest_turn_on_with_ref <path>`: Turn on difftest with reference - `xdifftest_reset`: Reset difftest state - `xdifftest_display [instance]`: Display difftest status - `xistep [count]`: Step through instructions and stop at commit - `xistep_break <on|off>`: Control instruction breakpoint - `xpc`: Display current commit PCs and instructions ### PC Watching - `xwatch_commit_pc <address>`: Watch a specific commit PC - `xunwatch_commit_pc <address>`: Remove PC watch ### Configuration - `xdifftest_pmem_base_first_instr_address`: Configure memory base and entry point - `xexpdiffstate <var>`: Export difftest state to variable ## Usage Examples ```bash $ make pdb-run (XiangShan) xload_difftest_ref_so /path/to/riscv64-nemu-interpreter-so (XiangShan) xdifftest_turn_on_with_ref /path/to/riscv64-nemu-interpreter-so (XiangShan) xistep 10 (XiangShan) xwatch_commit_pc 0x80000000 (XiangShan) xpc Co-authored-by: Zhicheng Yao <[email protected]>
## Description This PR adds comprehensive file import/export capabilities to xspdb, enabling developers to dump and load Flash/RAM contents during debugging sessions. ## Features ### Core APIs - `api_export_flash(bin_file, force_size=-1)`: Programmatic Flash export with smart mret detection - `api_export_ram(end_address, bin_file)`: Programmatic RAM export - `api_export_unified_bin(ram_start, ram_end, bin_file)`: Export unified binary with Flash + RAM - `api_convert_reg_file(file_name)`: Parse register file in format ### Debugging Commands - `xexport_flash <file> [force_size]`: Export Flash data to binary file - `xexport_ram <address> <file>`: export RAM data from memory base to specified address - `xexport_bin <end_address> <file> [start_address]`: Combines Flash + RAM into single binary file when `start_address` is specified ## Usage Examples ```bash $ make pdb-run (XiangShan) xexport_flash /tmp/flash.bin (XiangShan) xexport_flash /tmp/flash.bin 512 (XiangShan) xexport_ram 0x80100000 /tmp/ram.bin (XiangShan) xexport_bin 0x80100000 /tmp/dump 0x80040000 (XiangShan) xexport_bin 0x80100000 /tmp/dump (XiangShan) xbytes_to_bin b'\x13\x00\x00\x00' test.bin Co-authored-by: Zhicheng Yao <[email protected]>
## Description This PR adds comprehensive memory read/write operations and call stack backtrace capabilities to xspdb, enabling developers to inspect and modify memory contents during debugging sessions, as well as analyze call stacks. ## Features ### Core APIs - `api_write_bytes_with_rw`: write implementation with custom read/write functions - `api_read_bytes_with_func`: read implementation with custom read function - `api_get_call_stack`: get call stack from specified SP and PC ## Usage Examples ```bash $ make pdb-run (XiangShan) xmem_read 0x80000000 16 data bytes(16): b'\x13\x00\x00\x00...' (XiagShan) xmem_read_range 0x80000000 0x80000010 data bytes(16): b'\x13\x00\x00\x00...'
## Description
This PR add instruction debugging commands for XSPdb. Users can
decode/encode RISC‑V instructions, parse and load instruction files, and
conveniently convert between bytes and integers.
## Features
### Core APIs
- api_dasm_from_bytes(bytes, pc): Disassemble bytes to assembly text
(used internally for display).
- api_write_bytes(addr, data: bytes): Write a bytes buffer into DUT
memory.
- api_complite_localfile(text): Provide file path completion for CLI.
- api_convert_uint64_bytes(file_name): Parse a file containing
space-separated hex u64 strings into a bytes buffer.
### Debugging Commands
- xdecode_instr <instr>: Decode a single instruction (int or bytes).
Automatically detects compressed vs. 32-bit based on data.
- xencode_instr {"instr"}: Encode instruction fields into machine code;
prints asm/hex/bytes.
- xparse_instr_file <file>: Parse a file of uint64 strings to a
printable hex-bytes sequence (little-endian).
- xload_instr_file <address> <file>: Parse a uint64-string file and
write resulting bytes to DUT memory at <address>. Clears cached
disassembly.
- xnop_insert <start> <end>: Fill [start, end) range with RVC NOPs
(0x0001). Performs range and alignment checks.
## Usage Examples
```bash
$ make pdb-run
(XiangShan) xload_difftest_ref_so /path/to/riscv64-nemu-interpreter-so
(XiangShan) xdifftest_turn_on_with_ref /path/to/riscv64-nemu-interpreter-so
(XiangShan) xistep 10
(XiangShan) xwatch_commit_pc 0x80000000
(XiangShan) xdecode_instr 0x00000013
(XiangShan) xdecode_instr b'\x13\x00\x00\x00'
(XiangShan) xload_instr_file 0x80000000 instrs.txt
Co-authored-by: Zhicheng Yao <[email protected]>
## Description
This commit introduces three scripting modules under XSPdb’s xscmd:
- ELF: symbol table loading and address<->symbol translation, plus PC
symbol block change tracing to ease debug navigation.
- Trap: “good trap” detection, trap-break toggling, and trap info
printing. Minor text/robustness polishes are included without changing
public behavior.
## Features
### Core APIs
- api_get_elf_symbol_dict(elf_file, search_dirs=["./ready-to-run"]):
Invoke readelf -sW to build symbol dictionaries: by address, by name,
and sorted lists for bisection.
- api_update_local_elf_symbol_dict(): Rebuild symbol tables for the
current executable (self.exec_bin_file).
- api_turn_on_pc_symbol_block_change(on=True): Toggle PC symbol-block
change tracing and auto-load symbols as needed.
- api_is_hit_good_trap(show_log=False): Query whether a “good trap” is
observed; optional log.
- api_is_hit_good_loop(show_log=False): Heuristic “good loop” check
based on committed instruction 0x6f.
- api_break_on_trap(on: bool): Toggle break-on-trap checker.
- api_get_trap_info(): Return trap info dict {pc, code, hasTrap,
cycleCnt, hasWFI}.
### Debugging Commands
- xtrace_pc_symbol_block_change: Enable/disable symbol block change
tracing. When enabled, block transitions are printed automatically
during stepping.
- Tab-completion for on/off provided.
- xgood_trap_disable [true|false]: Disable/enable the “good trap”
checker.
- xtrap_break_on / xtrap_break_off: Enable/disable “break on trap”
behavior.
- xtrap_info: Print current trap state
(pc/code/hasTrap/cycleCnt/hasWFI).
- cmd_com: Helper module; provides file name/path completion for other
commands.
## Usage Examples
```bash
$ make pdb-run
(XiangShan) xload_difftest_ref_so /path/to/riscv64-nemu-interpreter-so
(XiangShan) xdifftest_turn_on_with_ref /path/to/riscv64-nemu-interpreter-so
(XiangShan) xistep 10
(XiangShan) xtrace_pc_symbol_block_change on
(XiangShan) xtrace_pc_symbol_block_change off
(XiangShan) xgood_trap_disable true
(XiangShan) xtrap_break_on
(XiangShan) xtrap_info
Co-authored-by: Zhicheng Yao <[email protected]>
Co-authored-by: Zhicheng Yao <[email protected]>
Co-authored-by: Zhicheng Yao <[email protected]>
This PR updates the xspdb to adapt to the API changes. --------- Co-authored-by: Zhicheng Yao <[email protected]>
klin02
force-pushed
the
difftest-kmh-v3
branch
from
1a2ffed to
bb37b9f
Compare
|
[Generated by IPC robot]
kunminghu-v3 branch:
|
lewislzh
approved these changes
Dec 16, 2025
good-circle
approved these changes
Dec 16, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Same PR on master: #5188
To fix XSPDB for latest Difftest, we also cherry-pick some PDB-related CI from master.