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