105f23f57SWilliam Wang# XiangShan 264fc9c9dSZihao Yu 3*40adeb5aSwangkaifanXiangShan (香山) is an open-source high-performance RISC-V processor project. 464fc9c9dSZihao Yu 5*40adeb5aSwangkaifanDetailed documents will be released in the near future. 664fc9c9dSZihao Yu 7a2ba9cdcSYinan XuCopyright 2020-2021 by Institute of Computing Technology, Chinese Academy of Sciences. 864fc9c9dSZihao Yu 9*40adeb5aSwangkaifan 10*40adeb5aSwangkaifan 11*40adeb5aSwangkaifan## === Tutorial is Comming! === 12*40adeb5aSwangkaifan 13*40adeb5aSwangkaifanA 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*40adeb5aSwangkaifan 15*40adeb5aSwangkaifanFor more information, please refer to [this link](https://openxiangshan.github.io). 16*40adeb5aSwangkaifan 17*40adeb5aSwangkaifan 18*40adeb5aSwangkaifan 19*40adeb5aSwangkaifan## Architecture 20*40adeb5aSwangkaifan 21*40adeb5aSwangkaifanThe 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*40adeb5aSwangkaifan 23*40adeb5aSwangkaifanThe micro-architecture overview is shown below. 24*40adeb5aSwangkaifan 25*40adeb5aSwangkaifan 26*40adeb5aSwangkaifan 27*40adeb5aSwangkaifan 28*40adeb5aSwangkaifan 29*40adeb5aSwangkaifan## Sub-directories Overview 30*40adeb5aSwangkaifan 31*40adeb5aSwangkaifanSome of the key directories are shown below. 32*40adeb5aSwangkaifan 33*40adeb5aSwangkaifan``` 34*40adeb5aSwangkaifan. 35*40adeb5aSwangkaifan├── fpga # supported FPGA boards and files to build a Vivado project 36*40adeb5aSwangkaifan├── read-to-run # pre-built simulation images 37*40adeb5aSwangkaifan├── scripts # scripts for agile development 38*40adeb5aSwangkaifan└── src 39*40adeb5aSwangkaifan ├── test # test files (including diff-test, module-test, etc.) 40*40adeb5aSwangkaifan └── main/scala # design files 41*40adeb5aSwangkaifan ├── bus/tilelink # tilelink utils 42*40adeb5aSwangkaifan ├── device # virtual device for simulation 43*40adeb5aSwangkaifan ├── difftest # diff-test chisel interface 44*40adeb5aSwangkaifan ├── system # SoC wrapper 45*40adeb5aSwangkaifan ├── top # top module 46*40adeb5aSwangkaifan ├── utils # utilization code 47*40adeb5aSwangkaifan ├── xiangshan # main design code 48*40adeb5aSwangkaifan └── xstransforms # some useful firrtl transforms 49*40adeb5aSwangkaifan``` 50*40adeb5aSwangkaifan 51*40adeb5aSwangkaifan 52*40adeb5aSwangkaifan 53*40adeb5aSwangkaifan## Generate Verilog 54*40adeb5aSwangkaifan 55*40adeb5aSwangkaifan* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`. 56*40adeb5aSwangkaifan* Refer to `Makefile` for more information. 57*40adeb5aSwangkaifan 58*40adeb5aSwangkaifan 59*40adeb5aSwangkaifan 60*40adeb5aSwangkaifan## Run Programs by Simulation 61*40adeb5aSwangkaifan 62*40adeb5aSwangkaifan### Prepare environment 6364fc9c9dSZihao Yu 64a2ba9cdcSYinan Xu* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU). 65a2ba9cdcSYinan Xu* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project. 66a2ba9cdcSYinan Xu* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am). 67a2ba9cdcSYinan Xu* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation). 68*40adeb5aSwangkaifan* Clone this project and run `make init` to initialize submodules. 6964fc9c9dSZihao Yu 70*40adeb5aSwangkaifan### Run with simulator 7105f23f57SWilliam Wang 72a2ba9cdcSYinan Xu* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator. 73a2ba9cdcSYinan Xu* Run `make emu` to build the C++ simulator `./build/emu` with Verilator. 74a2ba9cdcSYinan Xu* Refer to `./build/emu --help` for run-time arguments of the simulator. 75a2ba9cdcSYinan Xu* Refer to `Makefile` and `verilator.mk` for more information. 7605f23f57SWilliam Wang 7705f23f57SWilliam WangExample: 78a2ba9cdcSYinan Xu```bash 79a2ba9cdcSYinan Xumake emu CONFIG=MinimalConfig SIM_ARGS=--disable-log EMU_THREADS=2 -j10 80a2ba9cdcSYinan Xu./build/emu -b 0 -e 0 -i $AM_HOME/apps/coremark/build/coremark-riscv64-noop.bin 815c647eb5SZihao Yu``` 825c647eb5SZihao Yu 83
