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## Follow us 18 19Wechat/微信：香山开源处理器 20 21<div align=left><img width="340" height="117" src="images/wechat.png"/></div> 22 23Zhihu/知乎：[香山开源处理器](https://www.zhihu.com/people/openxiangshan) 24 25Weibo/微博：[香山开源处理器](https://weibo.com/u/7706264932) 26 27You 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]/). 28 29## Architecture 30 31The 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. 32 33The second stable micro-architecture of XiangShan is called Nanhu (南湖) [on the nanhu branch](https://github.com/OpenXiangShan/XiangShan/tree/nanhu). 34 35The current version of XiangShan, also known as Kunminghu (昆明湖), is still under development on the master branch. 36 37The micro-architecture overview of Nanhu (南湖) is shown below. 38 39 40 41 42 43## Sub-directories Overview 44 45Some of the key directories are shown below. 46 47``` 48. 49├── src 50│ └── main/scala # design files 51│ ├── device # virtual device for simulation 52│ ├── system # SoC wrapper 53│ ├── top # top module 54│ ├── utils # utilization code 55│ ├── xiangshan # main design code 56│ └── xstransforms # some useful firrtl transforms 57├── scripts # scripts for agile development 58├── fudian # floating unit submodule of XiangShan 59├── huancun # L2/L3 cache submodule of XiangShan 60├── difftest # difftest co-simulation framework 61└── ready-to-run # pre-built simulation images 62``` 63 64## IDE Support 65 66### bsp 67``` 68make bsp 69``` 70 71### IDEA 72``` 73make idea 74``` 75 76 77## Generate Verilog 78 79* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`. 80* Refer to `Makefile` for more information. 81 82 83 84## Run Programs by Simulation 85 86### Prepare environment 87 88* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU). 89* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project. 90* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am). 91* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation). 92* Clone this project and run `make init` to initialize submodules. 93 94### Run with simulator 95 96* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator. 97* Run `make emu` to build the C++ simulator `./build/emu` with Verilator. 98* Refer to `./build/emu --help` for run-time arguments of the simulator. 99* Refer to `Makefile` and `verilator.mk` for more information. 100 101Example: 102 103```bash 104make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10 105./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so 106``` 107 108## Troubleshooting Guide 109 110[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide) 111 112## Acknowledgement 113 114In the development of XiangShan, some sub-modules from the open-source community are employed. All relevant usage is listed below. 115 116| Sub-module | Source | Detail | 117| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 118| 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`. | 119| 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. | 120 121We 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). 122 123## Publications 124 125### MICRO 2022: Towards Developing High Performance RISC-V Processors Using Agile Methodology 126 127Our paper introduces XiangShan and the practice of agile development methodology on high performance RISC-V processors. 128It covers some representative tools we have developed and used to accelerate the chip development process, including design, functional verification, debugging, performance validation, etc. 129This paper is awarded all three available badges for artifacts evaluation. 130 131[Paper PDF](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan.pdf) | IEEE Xplore (TBD) | ACM DL (TBD) | BibTeX (TBD) 132
