xref: /XiangShan/README.md (revision e2aeeb1fa0d1a7d9b864b765d56c1c3014623c50) 
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## Docs and slides
12
13[XiangShan-doc](https://github.com/OpenXiangShan/XiangShan-doc) is our official documentation repository. It contains design spec., technical slides, tutorial and more.
14
15* Micro-architecture documentation of XiangShan has been published. Please check out https://xiangshan-doc.readthedocs.io
16
17## Publications
18
19### MICRO 2022: Towards Developing High Performance RISC-V Processors Using Agile Methodology
20
21Our paper introduces XiangShan and the practice of agile development methodology on high performance RISC-V processors.
22It covers some representative tools we have developed and used to accelerate the chip development process, including design, functional verification, debugging, performance validation, etc.
23This paper is awarded all three available badges for artifact evaluation (Available, Functional, and Reproduced).
24
25![Artifacts Available](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_available_dl.jpg)
26![Artifacts Evaluated — Functional](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_evaluated_functional_dl.jpg)
27![Results Reproduced](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/results_reproduced_dl.jpg)
28
29[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)
30
31## Follow us
32
33Wechat/微信：香山开源处理器
34
35<div align=left><img width="340" height="117" src="images/wechat.png"/></div>
36
37Zhihu/知乎：[香山开源处理器](https://www.zhihu.com/people/openxiangshan)
38
39Weibo/微博：[香山开源处理器](https://weibo.com/u/7706264932)
40
41You can contact us through [our mail list](mailto:[email protected]). All mails from this list will be archived to [here](https://www.mail-archive.com/[email protected]/).
42
43## Architecture
44
45The first stable micro-architecture of XiangShan is called Yanqihu (雁栖湖) [on the yanqihu branch](https://github.com/OpenXiangShan/XiangShan/tree/yanqihu), which has been developed since June 2020.
46
47The second stable micro-architecture of XiangShan is called Nanhu (南湖) [on the nanhu branch](https://github.com/OpenXiangShan/XiangShan/tree/nanhu).
48
49The current version of XiangShan, also known as Kunminghu (昆明湖), is still under development on the master branch.
50
51The micro-architecture overview of Nanhu (南湖) is shown below.
52
53![xs-arch-nanhu](images/xs-arch-nanhu.svg)
54
55
56
57## Sub-directories Overview
58
59Some of the key directories are shown below.
60
61```
62.
63├── src
64│   └── main/scala         # design files
65│       ├── device         # virtual device for simulation
66│       ├── system         # SoC wrapper
67│       ├── top            # top module
68│       ├── utils          # utilization code
69│       ├── xiangshan      # main design code
70│       └── xstransforms   # some useful firrtl transforms
71├── scripts                # scripts for agile development
72├── fudian                 # floating unit submodule of XiangShan
73├── huancun                # L2/L3 cache submodule of XiangShan
74├── difftest               # difftest co-simulation framework
75└── ready-to-run           # pre-built simulation images
76```
77
78## IDE Support
79
80### bsp
81```
82make bsp
83```
84
85### IDEA
86```
87make idea
88```
89
90
91## Generate Verilog
92
93* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`.
94* Refer to `Makefile` for more information.
95
96
97
98## Run Programs by Simulation
99
100### Prepare environment
101
102* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU).
103* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project.
104* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am).
105* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation).
106* Clone this project and run `make init` to initialize submodules.
107
108### Run with simulator
109
110* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator.
111* Run `make emu` to build the C++ simulator `./build/emu` with Verilator.
112* Refer to `./build/emu --help` for run-time arguments of the simulator.
113* Refer to `Makefile` and `verilator.mk` for more information.
114
115Example:
116
117```bash
118make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10
119./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so
120```
121
122## Troubleshooting Guide
123
124[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide)
125
126## Acknowledgement
127
128In the development of XiangShan, some sub-modules from the open-source community are employed. All relevant usage is listed below.
129
130| Sub-module         | Source                                                       | Detail                                                       |
131| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
132| L2 Cache/LLC       | [Sifive block-inclusivecache](https://github.com/ucb-bar/block-inclusivecache-sifive) | Our new L2/L3 design are inspired by Sifive's `block-inclusivecache`. |
133| Diplomacy/TileLink | [Rocket-chip](https://github.com/chipsalliance/rocket-chip)  | We reused the Diplomacy framework and TileLink utility that exist in rocket-chip to negotiate bus. |
134
135We are grateful for the support of the open-source community and encourage other open-source projects to reuse our code within the scope of the [license](LICENSE).
136