XiangShan ships its least settled branch as the default one
Open-source high-performance RISC-V processor
At a glance
- What is it?
- XiangShan is an open-source high-performance RISC-V processor written in Scala and built with mill, Verilator, and a Makefile full of overridable defaults. This looks at what the branch table says about stability, what a simulation run actually requires, and where the repository stops.
- Who is it for?
- XiangShan suits people who intend to build it: check out kunminghu-v2 instead of the default kunminghu-v3, expect to set three absolute paths and install mill and Verilator, and read docs.xiangshan.cc for whatever the repository files leave out. It is the wrong choice if you want a tagged release to pin, since the repository has no GitHub releases and version status lives in branches.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Scala, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- OpenXiangShan/XiangShan7,401 ★ · +127
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| OpenXiangShan/XiangShan | 7.3k | 7.4k |
127 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The default branch is the one the project asks you to hold off on
The default branch here is kunminghu-v3, and the branch status table marks that branch as maintained and under active development, then immediately warns about it: kunminghu-v3 is still evolving rapidly and its functionality may not yet be stable. For research, verification, or downstream applications, the table says to prioritize kunminghu-v2, which is marked maintained without the active development flag. So the branch you get by default is the one the maintainers describe as unsettled, and the branch they point you at is not the default. That asymmetry is the first thing to settle, because every target in the Makefile runs against whichever branch you checked out. The repository is not archived, and the last push landed on 2026-11-02, so you are choosing a moving target rather than reading a settled snapshot.
Six branches, and a status table frozen on 2026/06/30
The status table names six generation and version rows. Yanqihu sits on the yanqihu branch and has been developed since June 2020, marked maintained at minimum effort. Nanhu-V2 sits on nanhu with the same minimum marking. Nanhu-V3 is not in this repository at all: that row points at Siudya/Nanhu, with neither maintenance nor development filled in. Nanhu-V5 lives under OpenXiangShan-Nanhu/OpenNanhu-V5 and is marked both maintained and under active development. Kunminghu-V2 and Kunminghu-V3 are both maintained here, and only Kunminghu-V3 carries the active development flag. The table calls itself time-sensitive, invites an issue when it has gone stale, and records its own last update as 2026/06/30. Two of the six rows point outside this repository, so anyone chasing a generation can end up reading another group's tree with nothing here about how that tree is maintained.
Three absolute paths stand between a clone and a running simulation
Simulation is the documented way to run programs, and it starts with three environment variables and a submodule pass. NEMU_HOME must be the absolute path of the NEMU project, NOOP_HOME the absolute path of the XiangShan project itself, and AM_HOME the absolute path of the AM project, published as nexus-am. All three must be absolute, so a relative checkout path will not satisfy them. You also install mill, then initialize submodules after cloning:
make initThat step is not cosmetic. The design is assembled from several pieces, and the repository tree carries difftest, XSCache, yunsuan, rocket-chip, ChiselAIA, ChiselIOPMP, and OpenIOMMU next to src/.
make emu builds a C++ simulator, not a processor
Verilator is the simulator named in the guide, and make emu builds a C++ emulator binary at ./build/emu. Runtime arguments are documented through that binary's own help output rather than on a separate page. The guide's example passes a configuration, a thread count, and a job count, then runs a CoreMark binary against a RISC-V NEMU interpreter shared object:
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-interpreter-soWhat this path cannot hand you is hardware. The repository documents generating Verilog into build/rtl/, with files such as build/rtl/XSTop.sv, and the Makefile names an FPGA top module at top.TopMain, and the README documents Verilog generation and simulation.
The Makefile defaults decide which core you are actually building
Nearly every build decision is a variable with a default. CONFIG defaults to DefaultConfig, NUM_CORES to 1, ISSUE to E.b, LLC to OpenLLC, and RTL_SUFFIX to sv. The top module is assembled as $(XSTOP_PREFIX)XSTop, so the file name that lands in build/rtl depends on a prefix variable, and that prefix is not yours by default: when YAML_CONFIG is set and holds an XSTopPrefix key, the Makefile greps the value out of that yaml file and overrides your setting. Change the prefix in the config and the generated top module name changes with it, which quietly breaks any script expecting build/rtl/XSTop.sv. The supported CHI issues are listed in SUPPORT_CHI_ISSUE, starting B C E, the generator jar is placed at build/xsgen.jar, Scala sources are found under src/main/scala and tests under src/test/scala.
A container image stands in for the whole toolchain
The Dockerfile begins at ghcr.io/openxiangshan/xs-env:stable instead of installing a toolchain step by step. It overrides the entry point of the verilator image to /bin/bash, points VERILATOR at /usr/local/bin/verilator-wrap.sh, copies .mill-version aside to record which mill the project expects, and works in /work with out and build declared as volumes so generated files survive the container. It also runs git config --global --add safe.directory '*' to disable the safe directory check, then binds the source read only while sending mill's own output to a tmpfs and downloads dependencies:
make deps MILL_OUTPUT_DIR=/tmp/.mill-outThe price of that convenience is a pinned environment. Anything that only misbehaves on your mill or Verilator version stays hidden until the image itself is rebuilt.
xspdb is the way in without compiling anything
For debugging there are two ways to use xspdb, and the first is a quick start with prebuilt binaries. Its stated advantage is that it is lightweight, requires no compilation, and needs only a standard Python environment, which the guide describes as enough for the full XiangShan experience with low memory usage. What you trade for that speed is the link to your own checkout. The Makefile pulls in scripts/Makefile.pdb to wire pdb support into the build, so a debug session normally starts from a build you compiled.
src/main/scala is the design and the submodules are the edges
Under src/main/scala the design splits into device for the virtual device used in simulation, system as the SoC wrapper, top for the top module, utils for utility code, and xiangshan for the main design code, with a transforms directory holding firrtl transforms. Beside it sit scripts for agile development, yunsuan as its own submodule, XSCache for the cache subsystem, difftest as the co-simulation framework, and ready-to-run holding the binaries the example command loads. The root adds macros/, debug/, tools/, utility, project/, docs/, and images/, plus .scalafmt.conf, scalastyle-config.xml, scalastyle-test-config.xml, and a separate Makefile.test. Scala is the primary language, the code license is MulanPSL-2.0, the documents are CC-BY-4.0, and translations run through Weblate.
Editorial conclusion
XiangShan suits people who intend to build it: check out kunminghu-v2 instead of the default kunminghu-v3, expect to set three absolute paths and install mill and Verilator, and read docs.xiangshan.cc for whatever the repository files leave out. It is the wrong choice if you want a tagged release to pin, since the repository has no GitHub releases and version status lives in branches.
Frequently asked questions
What does the name XiangShan mean?
In this repository XiangShan is written 香山 and stands for an open-source high-performance RISC-V processor project, with Scala as its primary language and MulanPSL-2.0 as its license. Its micro-architecture generations carry separate names: Yanqihu (雁栖湖), Nanhu (南湖), and Kunminghu (昆明湖).
Where do XiangShan developers talk to each other?
The repository names a mailing list, [email protected], with every message archived, and that is the channel it points people to. Alongside it sit a Zhihu account, a Weibo account, and a WeChat account called 香山开源处理器. The Weblate project is where documentation translation happens.
Is XiangShan a city or a software project?
A processor project. The homepage is xiangshan.cc, the default branch is kunminghu-v3, the license is MulanPSL-2.0, and the code is Scala under src/main/scala. The Kunminghu-V3 branch is marked as still evolving rapidly, with functionality that may not yet be stable.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openxiangshan-xiangshan)Star history chart for your README
[](https://hysenlabs.com/projects/openxiangshan-xiangshan)Was this useful?