DOCSEARCHbyAlgolia
Submit Docs

XiangShan RISC-V Processor Documentation

repository·kunminghu-v3·Indexed 27 days ago

https://github.com/openxiangshan/xiangshan

An open-source, high-performance RISC-V processor project featuring micro-architectures such as Yanqihu, Nanhu, and Kunminghu. The documentation covers environment setup, Verilog code generation, Verilator simulation, and the XSPdb Python-based debugging tool for hardware/software co-verification. It also includes guides for Top-down analysis using top_down.py and draw.py, as well as contribution guidelines for reporting bugs and submitting pull requests.

Tokens
13K
Snippets
26
Records
94
Agent score
92%

What's inside XiangShan

  1. Overview of XSPdb

    kunminghu-v3
    XSPdb is a Python pdb-based debugging tool designed for RISC-V IPs, specifically customized for the XiangShan difftest interface. It provides a GDB-like interactive CLI, waveform control, flexible breakpoints/triggers, and scripts for reproducible debugging. It enables signal-level debugging integrated with software execution state for hardware/software co-verification.

  2. Manage CPU registers in XSPdb

    kunminghu-v3

    XSPdb provides utilities to manipulate various register types for reproducible testing and debugging. You can manage:

    • Integer Registers (x0-x31)
    • Floating-Point Registers (f0-f31)
    • Control Registers (including MPC/Program Counter)
    • Flash Registers (used for boot-time initialization during simulation startup)

    Register files support both decimal and hexadecimal formats. Floating-point registers accept values in IEEE 754 format.

  4. Submit a Pull Request

    kunminghu-v3

    Follow these steps and conventions when submitting code:

    1. Discussion: Discuss your proposed changes via an issue before starting work to avoid duplication.
    2. Formatting: Run make reformat to automatically format your code before committing.
    3. Scope: Keep changes within a single theme. Avoid mixing unrelated features in one PR.
    4. Commit Format: Use Conventional Commits following the type(scope): description format.
    5. Draft PRs: Start with a Draft Pull Request. Only convert to Ready for review after rebasing to the latest main line, passing self-tests, and passing CI.

    Common Commit Types:

    • feat: New feature
    • fix: Bug or performance fix
    • perf: Performance tuning
    • area / timing / power: PPA optimizations
    • build / ci / chore: Build, CI, or maintenance
    • docs: Documentation updates
    • style: Formatting (no functional change)
    • refactor: Code refactoring
    • test: Testing changes
    • submodule: Submodule updates
    make reformat

  5. Disassemble memory, flash, or raw bytes in XSPdb

    kunminghu-v3

    XSPdb provides several commands to translate memory content, flash data, or raw bytes into human-readable assembly instructions. The system uses spike-dasm as the primary engine for accurate RISC-V disassembly with symbol information, falling back to capstone if spike-dasm is unavailable.

    Available disassembly commands:

    • xdasm: Disassemble the Main Memory (RAM region starting from PMEM_BASE, default 0x80000000).
    • xdasmflash: Disassemble Flash Memory (starting from FLASH_BASE, default 0x10000000).
    • xdasmbytes: Disassemble arbitrary Raw Bytes.
    • xdasmnumber: Disassemble a single instruction Number (instruction word).

  6. Report a Bug in XiangShan RTL

    kunminghu-v3

    If you find defects in the XiangShan RTL (e.g., difftest failures), use the Bug report template on GitHub. To provide a complete report, include the branch, commit, phenomenon, environment, and test cases.

    You can use the ./scripts/bug-report.sh script to generate a bug-report.tar.gz file containing system information (OS, memory, toolchain versions, etc.). Important: Review the contents of the archive to ensure no sensitive information is included before uploading.

    ./scripts/bug-report.sh

  7. Step the DUT clock using xstep and xistep

    kunminghu-v3

    In the design environment, you can advance the Device Under Test (DUT) clock using two primary commands. These commands support integrating breakpoints, xbreak triggers, and fork-backup tick logic.

    • Use xstep to advance the clock by a specific number of cycles (N cycles), performing periodic break checks during the process.
    • Use xistep to step exactly one instruction (ISA step) when the hardware/environment supports it.

    Breakpoints and xbreak triggers are evaluated at the step boundaries.

  8. Select the appropriate XiangShan branch

    kunminghu-v3

    XiangShan is organized into different micro-architecture branches. Choose based on your stability requirements:

    • Yanqihu (雁栖湖): The first stable micro-architecture. Use the yanqihu branch.
    • Nanhu (南湖): The second stable micro-architecture. Use the nanhu branch.
    • Kunminghu (昆明湖): The third-generation micro-architecture under active development. Use kunminghu-v2 for research, verification, or downstream applications as it is more stable. Use kunminghu-v3 for the latest evolving functionality (not yet stable).

  10. Load data into simulation memory or flash

    kunminghu-v3

    XSPdb provides several methods to populate simulation memory for testing and boot scenarios:

    • Binary Loading: Use xload to load binary files into memory or xflash to load them into flash regions.
    • Instruction Lists: Use xload_instr_file to parse and load instruction sequences from text files. This supports comments and empty lines.
    • Direct Writes: Use xmem_write to write arbitrary values to specific memory addresses.
    • Flash Reset: Use xreset_flash to reset the flash contents to their initial state.

  11. Set up the XiangShan simulation environment

    kunminghu-v3

    To run XiangShan simulations, you must configure several environment variables and install necessary dependencies:

    1. Environment Variables:
      • NEMU_HOME: Absolute path to the XiangShan NEMU repository.
      • NOOP_HOME: Absolute path to the XiangShan project folder.
      • AM_HOME: Absolute path to the XiangShan AM repository.
    2. Dependencies:
      • Install mill for Scala compilation.
      • Install Verilator for Verilog simulation.
      • Install picker if you intend to use xspdb.
    3. Initialization:
      • Clone the repository and run make init to initialize all open-source submodules.
    make init

  12. Configure register initialization via files

    kunminghu-v3

    For reproducible test setups, use file-based configuration. XSPdb supports:

    • Register Files: Text files containing register values in a standardized format (supporting comments and empty lines).
    • Instruction Lists: Lists of instructions used to initialize registers.

    Files can be parsed and validated using xparse_reg_file and loaded using xload_reg_file. This approach allows for version control of specific test environments.