xref: /XiangShan/README.md (revision 8c0a01afbe82229c17d6d4d0063f93c3171d8843) 
1# XiangShan
2
3XiangShan (香山) is an open-source high-performance RISC-V processor project.
4
5Detailed documents will be released in the near future.
6中文说明[在此](README-ZH-HANS.md)。
7
8Copyright 2020-2021 by Institute of Computing Technology, Chinese Academy of Sciences.
9
10
11
12## === Tutorial is Coming! ===
13
14A tutorial on XiangShan is held at RISC-V World Conference China 2021 in June.  Multiple technical reports will be included in the conference as well. Stay tuned!
15
16For more information, please refer to [this link](https://openxiangshan.github.io).
17
18
19
20## Architecture
21
22The first stable micro-architecture of XiangShan is called Yanqihu (雁栖湖) on this [branch](https://github.com/OpenXiangShan/XiangShan/tree/yanqihu), which has been developed since June 2020. The current version of XiangShan, also known as Nanhu (南湖), is still under development on the master branch.
23
24The micro-architecture overview is shown below.
25
26![xs-arch-single](xs-arch-simple.svg)
27
28
29
30## Sub-directories Overview
31
32Some of the key directories are shown below.
33
34```
35.
36├── fpga                   # supported FPGA boards and files to build a Vivado project
37├── read-to-run            # pre-built simulation images
38├── scripts                # scripts for agile development
39└── src
40    ├── test               # test files (including diff-test, module-test, etc.)
41    └── main/scala         # design files
42        ├── bus/tilelink   # tilelink utils
43        ├── device         # virtual device for simulation
44        ├── difftest       # diff-test chisel interface
45        ├── system         # SoC wrapper
46        ├── top            # top module
47        ├── utils          # utilization code
48        ├── xiangshan      # main design code
49        └── xstransforms   # some useful firrtl transforms
50```
51
52
53
54## Generate Verilog
55
56* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`.
57* Refer to `Makefile` for more information.
58
59
60
61## Run Programs by Simulation
62
63### Prepare environment
64
65* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU).
66* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project.
67* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am).
68* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation).
69* Clone this project and run `make init` to initialize submodules.
70
71### Run with simulator
72
73* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator.
74* Run `make emu` to build the C++ simulator `./build/emu` with Verilator.
75* Refer to `./build/emu --help` for run-time arguments of the simulator.
76* Refer to `Makefile` and `verilator.mk` for more information.
77
78Example:
79
80```bash
81make emu CONFIG=MinimalConfig SIM_ARGS=--disable-log EMU_THREADS=2 -j10
82./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so
83```
84
85## Acknowledgement
86
87In the development of XiangShan, some sub-modules from the open-source community are employed. All relevant usage is listed below.
88
89| Sub-module         | Source                                                       | Detail                                                       |
90| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
91| L2 Cache/LLC       | [Sifive block-inclusivecache](https://github.com/ucb-bar/block-inclusivecache-sifive) | We enhance the function and the timing of the original module, finally turning it into a Cache generator that can be configured as L2/LLC. |
92| 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. |
93| FPU                | [Berkeley hardfloat](https://github.com/ucb-bar/berkeley-hardfloat) | We use Berkeley-hardfloat as our FPU and implement an SRT-4 div/sqrt unit for it. Additionally, we split the FMA pipeline to optimize the timing. |
94
95We 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).
96
97