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 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. 32 33The micro-architecture overview of Nanhu (南湖) is shown below. 34 35 36 37 38 39## Sub-directories Overview 40 41Some of the key directories are shown below. 42 43``` 44. 45├── src 46│ └── main/scala # design files 47│ ├── device # virtual device for simulation 48│ ├── system # SoC wrapper 49│ ├── top # top module 50│ ├── utils # utilization code 51│ ├── xiangshan # main design code 52│ └── xstransforms # some useful firrtl transforms 53├── scripts # scripts for agile development 54├── fudian # floating unit submodule of XiangShan 55├── huancun # L2/L3 cache submodule of XiangShan 56├── difftest # difftest co-simulation framework 57└── ready-to-run # pre-built simulation images 58``` 59 60## IDE Support 61 62### bsp 63``` 64make bsp 65``` 66 67### IDEA 68``` 69make idea 70``` 71 72 73## Generate Verilog 74 75* Run `make verilog` to generate verilog code. The output file is `build/XSTop.v`. 76* Refer to `Makefile` for more information. 77 78 79 80## Run Programs by Simulation 81 82### Prepare environment 83 84* Set environment variable `NEMU_HOME` to the **absolute path** of the [NEMU project](https://github.com/OpenXiangShan/NEMU). 85* Set environment variable `NOOP_HOME` to the **absolute path** of the XiangShan project. 86* Set environment variable `AM_HOME` to the **absolute path** of the [AM project](https://github.com/OpenXiangShan/nexus-am). 87* Install `mill`. Refer to [the Manual section in this guide](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation). 88* Clone this project and run `make init` to initialize submodules. 89 90### Run with simulator 91 92* Install [Verilator](https://verilator.org/guide/latest/), the open-source Verilog simulator. 93* Run `make emu` to build the C++ simulator `./build/emu` with Verilator. 94* Refer to `./build/emu --help` for run-time arguments of the simulator. 95* Refer to `Makefile` and `verilator.mk` for more information. 96 97Example: 98 99```bash 100make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10 101./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so 102``` 103 104## Troubleshooting Guide 105 106[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide) 107 108## Acknowledgement 109 110In the development of XiangShan, some sub-modules from the open-source community are employed. All relevant usage is listed below. 111 112| Sub-module | Source | Detail | 113| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 114| 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`. | 115| 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. | 116 117We 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). 118 119
