openxiangshan/xiangshan

★ 7,014ScalaAudience · researcherComplexity · 5/5Setup · hard

Mindmap

mindmap
  root((XiangShan))
    What it is
      RISC-V processor design
      Multiple generations
      Academic research origin
    Tech
      Scala and Chisel
      Generates Verilog
      Verilator simulation
    Tools
      xspdb debugger
      difftest co-simulation
      Python debugging
    Components
      fudian float unit
      huancun cache subsystem
      Simulation images

mindmap root((XiangShan)) What it is RISC-V processor design Multiple generations Academic research origin Tech Scala and Chisel Generates Verilog Verilator simulation Tools xspdb debugger difftest co-simulation Python debugging Components fudian float unit huancun cache subsystem Simulation images

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Study a complete production-grade RISC-V processor implementation to learn modern chip microarchitecture.

USE CASE 2

Run XiangShan in Verilator simulation to test programs on the processor design without physical hardware.

USE CASE 3

Use the difftest co-simulation framework to catch processor bugs by running two implementations side by side.

USE CASE 4

Build a modified XiangShan processor with pipeline changes and verify correctness with cycle-by-cycle debugging.

Tech stack

ScalaChiselVerilogPythonVerilator

Getting it running

Difficulty · hard Time to first run · 1day+

Requires building a Verilator simulation environment from generated Verilog and setting up Python tooling, no quick-start path exists.

License details are not described in the explanation.

In plain English

XiangShan is an open-source project to build a high-performance processor chip based on the RISC-V instruction set. RISC-V is an open standard that defines how a CPU understands and executes code, and XiangShan is a full implementation of a physical chip design built on top of that standard. The project comes out of the Institute of Computing Technology at the Chinese Academy of Sciences, and it has been published in academic research as a case study in how to build serious chip hardware using modern, agile development methods. The code is written in Scala using a hardware description framework called Chisel, which lets engineers describe the logic of a chip in a high-level programming language rather than hand-writing low-level circuit code. From that Scala source, the project generates Verilog files, which are the industry-standard format used to actually fabricate or simulate chips. So if you are browsing the repository, you are looking at a full processor design, not application software. XiangShan has gone through multiple generations. The first was called Yanqihu, the second Nanhu, and the current one in active development is called Kunminghu. Each generation represents a new microarchitecture, meaning a new set of decisions about how the processor pipeline is organized internally to run code faster. The repository keeps older stable generations on named branches so they remain accessible alongside the ongoing work on master. Running the project requires setting up a simulation environment. Engineers build a simulator from the Verilog output using a tool called Verilator, then run test programs against it to verify the processor behaves correctly. There is also a Python-based debugging tool called xspdb that allows stepping through program execution cycle by cycle and setting watchpoints on specific memory addresses. A separate co-simulation framework called difftest helps catch bugs by running two implementations side by side and flagging any differences. The project includes a submodule for floating-point arithmetic (fudian), a cache subsystem (huancun), and pre-built simulation images for quick testing. Documentation covering the full chip design, user guide, and architecture details is hosted separately at docs.xiangshan.cc.

Copy-paste prompts

Prompt 1

I want to run the XiangShan RISC-V processor in Verilator simulation. Walk me through the exact steps to build the simulator and run a test program from a blank Ubuntu machine.

Prompt 2

Using the XiangShan difftest framework, show me how to add a new co-simulation reference model and detect a specific instruction bug.

Prompt 3

I am learning chip design using the XiangShan codebase. Explain the Nanhu branch pipeline stages in plain English and point me to the relevant Chisel source files.

Prompt 4

Help me use xspdb to set a watchpoint on a memory address and step through XiangShan execution cycle by cycle to debug a load instruction issue.

Open on GitHub → Explain another repo

← openxiangshan on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.