XiangShan: Evaluating the Open-Source RISC-V Processor for Kunminghu V3

What XiangShan Is and Who Should Care

XiangShan (香山) is an open-source high-performance RISC-V processor project. The primary language is Scala, the design is built with Chisel, and the repository is licensed under MulanPSL-2.0. The problem it addresses is the gap between a specification and a working out-of-order RISC-V core: instead of starting from a blank Chisel project, you get a full microarchitecture with a cache subsystem, a SoC wrapper, and a co-simulation framework already wired together.

The audience is narrow. This is not a board support package you flash onto an FPGA and forget. The README's branch table shows three generations (Yanqihu, Nanhu, Kunminghu), and the project publishes a MICRO 2022 paper on agile development methodology for high-performance RISC-V processors. That framing tells you who it is for: teams that want to modify the microarchitecture, run difftest against a reference model, or evaluate design trade-offs in academic work. If you want a RISC-V core to embed in a product with a vendor support contract, this is the wrong shape of project.

The Chisel-to-Verilog Pipeline and Difftest

XiangShan is written in Chisel and compiled to SystemVerilog. The repository layout makes the data flow legible: src/main/scala holds the design files, split into device (virtual devices for simulation), system (the SoC wrapper), top (the top module), utils, and xiangshan (the main design code, with a transforms subdirectory for FIRRTL transforms). XSCache is the cache subsystem, yunsuan is a submodule, and difftest is the co-simulation framework.

Generation is a Make target. The README states that running make verilog produces multiple .sv files in build/rtl/, for example build/rtl/XSTop.sv. The Makefile confirms the naming: TOP is $(XSTOP_PREFIX)XSTop, SIM_TOP is SimTop, and the RTL suffix defaults to sv. Configuration is parameterized through CONFIG, NUM_CORES, ISSUE, and LLC variables, with DefaultConfig as the default. Difftest is the verification mechanism: the emulator runs alongside a reference implementation and compares state, which is why the example command passes --diff ./ready-to-run/riscv64-nemu-interpret. That side-by-side comparison is the part that makes a core this large tractable to debug, and it is the mechanism the MICRO 2022 paper describes as part of the agile methodology.

Installing XiangShan and Running a First Simulation

The README lists the environment prerequisites before any build. NEMU_HOME, NOOP_HOME, and AM_HOME must be set to absolute paths of the NEMU project, the XiangShan project, and the AM project respectively. You also need mill installed, following the bootstrap script instructions in the mill manual. Then clone the repository and initialize submodules.

make init

For simulation you need Verilator, the open-source Verilog simulator. The README gives this example, which builds the C++ simulator with two emulation threads and ten parallel jobs, then runs a prebuilt CoreMark binary with difftest against the NEMU interpreter:

make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10
./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpret

After the build you should have ./build/emu. The README points to ./build/emu --help for the run-time arguments, and to Makefile and verilator.mk for build details. If you would rather not assemble the toolchain, the repository ships a Dockerfile that starts from ghcr.io/openxiangshan/xs-env:stable, copies .mill-version, runs make deps, and declares /work/out and /work/build as volumes. Note that the Dockerfile overrides the verilator image ENTRYPOINT with /bin/bash and sets VERILATOR=/usr/local/bin/verilator-wrap.sh. IDE support is two targets: make bsp for BSP and make idea for IDEA.

Kunminghu V3 Is Not the Branch You Should Default To

The most consequential thing in the README is the warning attached to the default branch. The repository's default branch is kunminghu-v3, and the README states plainly that kunminghu-v3 is still evolving rapidly and its functionality may not yet be stable. It then recommends prioritizing kunminghu-v2 for research, verification, or downstream applications. The branch table marks kunminghu-v3 as both maintained and under active development, and kunminghu-v2 as maintained but not under active development.

That is a real trade-off, not a formality. Checking out the default branch puts you on the moving target. Checking out kunminghu-v2 puts you on a branch that is no longer receiving active development. You have to pick which kind of instability you can absorb. The README also notes that the branch maintenance section is time-sensitive and carries its own last-updated date, which means the table can go stale between releases. There is no release list in the repository metadata, so there is no versioned tarball to pin against; your pin is a branch name and a commit.

The documentation situation has the same shape. The README points to docs.xiangshan.cc, with a separate Kunminghu V2R2 design document at docs.xiangshan.cc/projects/design and a user guide at docs.xiangshan.cc/projects/user-guide. The README itself does not document rollback, migration between generations, or a supported-version policy. If you need a documented compatibility guarantee across upgrades, the repository does not currently provide one.

How XiangShan Compares to Rocket Chip and BOOM

The repository carries a rocket-chip directory, and the Chisel lineage makes the comparison concrete. Rocket Chip is the in-order, single-issue baseline from the Berkeley ecosystem: smaller, more thoroughly documented, and the usual starting point for a first RISC-V core in Chisel. BOOM is the out-of-order sibling in the same ecosystem, sharing Rocket's diplomacy and tile infrastructure.

XiangShan's difference is scope and ambition. It is a multi-generation, high-performance out-of-order design with its own cache subsystem (XSCache), its own arithmetic submodule (yunsuan), and a difftest co-simulation framework built around NEMU rather than around the Rocket ecosystem's test harness. The README's MICRO 2022 paper is explicitly about agile development methodology for high-performance processors, including design, functional verification, debugging, and performance validation. So the pitch is not just the core; it is the toolchain around the core.

The cost of that ambition is that you are outside the Rocket Chip ecosystem's conventions. If your team already knows Rocket's diplomacy parameters and its test infrastructure, XiangShan is a second learning curve, not an extension of the first. If you need a small in-order core to prototype a peripheral or an accelerator, Rocket Chip is the smaller commitment. XiangShan makes sense when the out-of-order microarchitecture itself is the subject of your work.

Licence and Maintenance Costs

XiangShan is licensed under MulanPSL-2.0. The Dockerfile header and the Makefile header both carry the standard Mulan PSL v2 notice, including the disclaimer that the software is provided on an AS IS basis without warranties of any kind, and the instruction to obtain a copy of the licence at http://license.coscl.org.cn/MulanPSL2. MulanPSL-2.0 is a permissive licence with an explicit patent grant, but whether its patent and notice terms fit your distribution model is a question for your own counsel; this article does not give legal advice.

The licence does not cover everything in the tree. The README states that all XiangShan documents are licensed under CC-BY-4.0, which is a separate licence from the code. If you redistribute the design documents, that is the licence that applies to them.

Maintenance cost tracks the branch table. kunminghu-v2 is maintained but not under active development, so fixes there are limited. kunminghu-v3 is under active development, so it moves. The repository's last push was on 2026-09-21, which is recent, but recency of the default branch does not tell you anything about the stability of the branch you actually checked out. Budget for reading the design document rather than the source alone: the README directs you to the Kunminghu V2R2 design document for microarchitecture detail, and the README itself does not describe the pipeline.

What the Repository Does Not Tell You

Several things a prospective adopter would want are absent. There is no release list in the repository metadata, so there are no tagged versions to compare. The README does not document rollback, does not state a support window for older generations, and does not describe what changed between Kunminghu V2 and V3 beyond the stability warning. The Yanqihu branch has been developed since June 2020 and is marked as minimally maintained, which is a signal about how long a generation stays viable.

The Dockerfile is a partial answer to reproducibility, since it pins ghcr.io/openxiangshan/xs-env:stable and reads .mill-version, but the tag stable is a moving tag. If you need a byte-identical build environment six months from now, pinning to that tag is not enough; you would need the digest, which the repository does not record. That is a real gap for a project whose stated goal includes research reproducibility, and the MICRO 2022 artifact badges speak to reproducibility of the paper's results rather than of arbitrary downstream builds.

Editorial conclusion

Adopt XiangShan if you are doing processor microarchitecture research, verification, or downstream integration on kunminghu-v2, and you are prepared to work from the design documents at docs.xiangshan.cc. Do not adopt it if you need a stable drop-in core for production silicon, because the README states that kunminghu-v3 is still evolving rapidly and its functionality may not yet be stable. Before committing, verify the branch maintenance table, confirm the NEMU, AM, and NOOP_HOME paths resolve on your machine, and check whether the Kunminghu V2R2 design document covers the subsystem you intend to modify.

Frequently asked questions

Official sources

1. Issues
2. License: MulanPSL-2.0
3. OpenXiangShan/XiangShan on GitHub
4. Project website
5. README