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 7Copyright 2020-2021 by Institute of Computing Technology, Chinese Academy of Sciences. 8 9 10 11## === Tutorial is Coming! === 12 13A 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! 14 15For more information, please refer to [this link](https://openxiangshan.github.io). 16 17 18 19## Architecture 20 21The 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 master branch. 22 23The micro-architecture overview is shown below. 24 25 26 27 28 29## Sub-directories Overview 30 31Some of the key directories are shown below. 32 33``` 34. 35├── fpga # supported FPGA boards and files to build a Vivado project 36├── read-to-run # pre-built simulation images 37├── scripts # scripts for agile development 38└── src 39 ├── test # test files (including diff-test, module-test, etc.) 40 └── main/scala # design files 41 ├── bus/tilelink # tilelink utils 42 ├── device # virtual device for simulation 43 ├── difftest # diff-test chisel interface 44 ├── system # SoC wrapper 45 ├── top # top module 46 ├── utils # utilization code 47 ├── xiangshan # main design code 48 └── xstransforms # some useful firrtl transforms 49``` 50 51 52 53## Generate Verilog 54 55* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`. 56* Refer to `Makefile` for more information. 57 58 59 60## Run Programs by Simulation 61 62### Prepare environment 63 64* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU). 65* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project. 66* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am). 67* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation). 68* Clone this project and run `make init` to initialize submodules. 69 70### Run with simulator 71 72* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator. 73* Run `make emu` to build the C++ simulator `./build/emu` with Verilator. 74* Refer to `./build/emu --help` for run-time arguments of the simulator. 75* Refer to `Makefile` and `verilator.mk` for more information. 76 77Example: 78```bash 79make emu CONFIG=MinimalConfig SIM_ARGS=--disable-log EMU_THREADS=2 -j10 80./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so 81``` 82 83 84 85## Acknowledgement 86 87In the development of XiangShan, some sub-modules from 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 a 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
