1# XiangShan 2 3XiangShan (香山) is an open-source high-performance RISC-V processor project. 4 5中文说明[在此](readme.zh-cn.md)。 6 7Copyright 2020-2021 by Institute of Computing Technology, Chinese Academy of Sciences. 8 9Copyright 2020-2021 by Peng Cheng Laboratory. 10 11## Docs and slides 12We gave 20+ presentations on RISC-V World Conference China 2021. XiangShan tutorial was held at the same place. Our slides for RVWC2021 have been updated on [our doc repo](https://github.com/OpenXiangShan/XiangShan-doc) (in Chinese). 13 14我们在2021年RISC-V中国峰会的报告已经更新到[这里](https://github.com/OpenXiangShan/XiangShan-doc)。文档和相关信息也将持续更新到相同的仓库。 15 16## Follow us 17 18Wechat/微信：香山开源处理器 19 20<div align=left><img width="340" height="117" src="images/wechat.png"/></div> 21 22Zhihu/知乎：[香山开源处理器](https://www.zhihu.com/people/openxiangshan) 23 24Weibo/微博：[香山开源处理器](https://weibo.com/u/7706264932) 25 26You 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]/). 27 28## Architecture 29 30The 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. 31 32The micro-architecture overview is shown below. 33 34 35 36 37 38## Sub-directories Overview 39 40Some of the key directories are shown below. 41 42``` 43. 44├── ready-to-run # pre-built simulation images 45├── scripts # scripts for agile development 46└── src 47 ├── test # test files (including diff-test, module-test, etc.) 48 └── main/scala # design files 49 ├── device # virtual device for simulation 50 ├── difftest # diff-test chisel interface 51 ├── system # SoC wrapper 52 ├── top # top module 53 ├── utils # utilization code 54 ├── xiangshan # main design code 55 └── xstransforms # some useful firrtl transforms 56``` 57 58 59 60## Generate Verilog 61 62* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`. 63* Refer to `Makefile` for more information. 64 65 66 67## Run Programs by Simulation 68 69### Prepare environment 70 71* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU). 72* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project. 73* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am). 74* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation). 75* Clone this project and run `make init` to initialize submodules. 76 77### Run with simulator 78 79* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator. 80* Run `make emu` to build the C++ simulator `./build/emu` with Verilator. 81* Refer to `./build/emu --help` for run-time arguments of the simulator. 82* Refer to `Makefile` and `verilator.mk` for more information. 83 84Example: 85 86```bash 87make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10 88./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so 89``` 90 91## Troubleshooting Guide 92 93[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide) 94 95## Acknowledgement 96 97In the development of XiangShan, some sub-modules from the open-source community are employed. All relevant usage is listed below. 98 99| Sub-module | Source | Detail | 100| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 101| 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`. | 102| 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. | 103 104We 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). 105 106
