xref: /XiangShan/README.md (revision 2a03c3bdc39c27c53d68f71caf088fe1fc0a4b6a) 
1# XiangShan
2
3XiangShan (香山) is an open-source high-performance RISC-V processor project.
4
5中文说明[在此](readme.zh-cn.md)。
6
7## Documentation
8
9XiangShan's documentation is available at [docs.xiangshan.cc](https://docs.xiangshan.cc).
10
11The microarchitecture documentation on [docs.xiangshan.cc](https://docs.xiangshan.cc) is currently outdated for the latest version (Kunminghu). An updated version is in progress.
12
13XiangShan User Guide has been published separately. You can find it at [XiangShan-User-Guide/releases](https://github.com/OpenXiangShan/XiangShan-User-Guide/releases).
14
15## Publications
16
17### MICRO 2022: Towards Developing High Performance RISC-V Processors Using Agile Methodology
18
19Our paper introduces XiangShan and the practice of agile development methodology on high performance RISC-V processors.
20It covers some representative tools we have developed and used to accelerate the chip development process, including design, functional verification, debugging, performance validation, etc.
21This paper is awarded all three available badges for artifact evaluation (Available, Functional, and Reproduced).
22
23![Artifacts Available](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_available_dl.jpg)
24![Artifacts Evaluated — Functional](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_evaluated_functional_dl.jpg)
25![Results Reproduced](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/results_reproduced_dl.jpg)
26
27[Paper PDF](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan.pdf) | [IEEE Xplore](https://ieeexplore.ieee.org/abstract/document/9923860) | [BibTeX](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan.bib) | [Presentation Slides](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan-slides.pdf) | [Presentation Video](https://www.bilibili.com/video/BV1FB4y1j7Jy)
28
29## Follow us
30
31Wechat/微信：香山开源处理器
32
33<div align=left><img width="340" height="117" src="images/wechat.png"/></div>
34
35Zhihu/知乎：[香山开源处理器](https://www.zhihu.com/people/openxiangshan)
36
37Weibo/微博：[香山开源处理器](https://weibo.com/u/7706264932)
38
39You can contact us through [our mailing list](mailto:[email protected]). All mails from this list will be archived [here](https://www.mail-archive.com/[email protected]/).
40
41## Architecture
42
43The first stable micro-architecture of XiangShan is called Yanqihu (雁栖湖) and is [on the yanqihu branch](https://github.com/OpenXiangShan/XiangShan/tree/yanqihu), which has been developed since June 2020.
44
45The second stable micro-architecture of XiangShan is called Nanhu (南湖) and is [on the nanhu branch](https://github.com/OpenXiangShan/XiangShan/tree/nanhu).
46
47The current version of XiangShan, also known as Kunminghu (昆明湖), is still under development on the master branch.
48
49The micro-architecture overview of Kunminghu (昆明湖) is shown below.
50
51![xs-arch-kunminghu](images/xs-arch-kunminghu.svg)
52
53
54
55## Sub-directories Overview
56
57Some of the key directories are shown below.
58
59```
60.
61├── src
62│   └── main/scala         # design files
63│       ├── device         # virtual device for simulation
64│       ├── system         # SoC wrapper
65│       ├── top            # top module
66│       ├── utils          # utilization code
67│       └── xiangshan      # main design code
68│           └── transforms # some useful firrtl transforms
69├── scripts                # scripts for agile development
70├── fudian                 # floating unit submodule of XiangShan
71├── huancun                # L2/L3 cache submodule of XiangShan
72├── difftest               # difftest co-simulation framework
73└── ready-to-run           # pre-built simulation images
74```
75
76## IDE Support
77
78### bsp
79```
80make bsp
81```
82
83### IDEA
84```
85make idea
86```
87
88
89## Generate Verilog
90
91* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`.
92* Refer to `Makefile` for more information.
93
94
95
96## Run Programs by Simulation
97
98### Prepare environment
99
100* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU).
101* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project.
102* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am).
103* Install `mill`. Refer to [the Manual section in this guide](https://mill-build.org/mill/0.11.11/Scala_Installation_IDE_Support.html#_bootstrap_scripts).
104* Clone this project and run `make init` to initialize submodules.
105
106### Run with simulator
107
108* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator.
109* Run `make emu` to build the C++ simulator `./build/emu` with Verilator.
110* Refer to `./build/emu --help` for run-time arguments of the simulator.
111* Refer to `Makefile` and `verilator.mk` for more information.
112
113Example:
114
115```bash
116make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10
117./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so
118```
119
120## Troubleshooting Guide
121
122[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide)
123
124## Acknowledgement
125
126The implementation of XiangShan is inspired by several key papers. We list these papers in XiangShan document, see: [Acknowledgements](https://docs.xiangshan.cc/zh-cn/latest/acknowledgments/). We very much encourage and expect that more academic innovations can be realised based on XiangShan in the future.
127
128## LICENSE
129
130Copyright © 2020-2025 Institute of Computing Technology, Chinese Academy of Sciences.
131
132Copyright © 2021-2025 Beijing Institute of Open Source Chip
133
134Copyright © 2020-2022 by Peng Cheng Laboratory.
135
136XiangShan is licensed under [Mulan PSL v2](LICENSE).
137