xref: /XiangShan/readme.zh-cn.md (revision e05e6e4ff34afa1beef54a4dad870791cb76ab77) 
1# 香山
2
3香山（XiangShan）是一款开源的高性能 RISC-V 处理器。
4
5English Readme is [here](README.md).
6
7©2020-2022 中国科学院计算技术研究所版权所有
8
9©2020-2022 鹏城实验室版权所有
10
11## 文档和报告
12
13香山的文档托管在 [docs.xiangshan.cc](https://docs.xiangshan.cc)。
14
15[docs.xiangshan.cc](https://docs.xiangshan.cc) 上的微架构文档尚未根据最新架构（昆明湖）更新，我们正在撰写新的设计文档。
16
17香山用户文档已单独发布，您可在此处查看：[XiangShan-User-Guide/releases](https://github.com/OpenXiangShan/XiangShan-User-Guide/releases)
18
19## 论文发表情况
20
21### MICRO 2022: Towards Developing High Performance RISC-V Processors Using Agile Methodology
22
23我们在 MICRO'22 会议上的论文介绍了香山处理器及敏捷开发实践经验，包括一些面向设计、功能验证、调试、性能评估等方面的敏捷开发工具。论文得到了 Artifact Evaluation 的所有三个徽章。
24
25![Artifacts Available](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_available_dl.jpg)
26![Artifacts Evaluated — Functional](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/artifacts_evaluated_functional_dl.jpg)
27![Results Reproduced](https://github.com/OpenXiangShan/XiangShan-doc/raw/main/publications/images/results_reproduced_dl.jpg)
28
29[Paper PDF](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan.pdf) | [IEEE Xplore](https://ieeexplore.ieee.org/abstract/document/9923860) | [BibTeX](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan.bib) | [Presentation Slides](https://github.com/OpenXiangShan/XiangShan-doc/blob/main/publications/micro2022-xiangshan-slides.pdf) | [Presentation Video](https://www.bilibili.com/video/BV1FB4y1j7Jy)
30
31
32## 关注我们
33
34Wechat/微信：香山开源处理器
35
36<div align=left><img width="340" height="117" src="images/wechat.png"/></div>
37
38Zhihu/知乎：[香山开源处理器](https://www.zhihu.com/people/openxiangshan)
39
40Weibo/微博：[香山开源处理器](https://weibo.com/u/7706264932)
41
42可以通过[我们的邮件列表](mailto:[email protected])联系我们。列表中的所有邮件会存档到[这里](https://www.mail-archive.com/[email protected]/)。
43
44## 处理器架构
45
46自 2020 年 6 月开始开发的[雁栖湖](https://github.com/OpenXiangShan/XiangShan/tree/yanqihu)为香山处理器的首个稳定的微架构。
47
48香山的第二代微架构被命名为[南湖](https://github.com/OpenXiangShan/XiangShan/tree/nanhu)。
49
50香山的第三代微架构（昆明湖）正在 master 分支上不断开发中。
51
52昆明湖微架构概览：
53![xs-arch-kunminghu](images/xs-arch-kunminghu.svg)
54
55## 目录概览
56
57以下是一些关键目录：
58
59```
60.
61├── src
62│   └── main/scala         # 设计文件
63│       ├── device         # 用于仿真的虚拟设备
64│       ├── system         # SoC 封装
65│       ├── top            # 顶层模块
66│       ├── utils          # 复用封装
67│       └── xiangshan      # 主体设计代码
68│           └── transforms # 一些实用的 firrtl 变换代码
69├── scripts                # 用于敏捷开发的脚本文件
70├── fudian                 # 香山浮点子模块
71├── huancun                # 香山 L2/L3 缓存子模块
72├── difftest               # 香山协同仿真框架
73└── read-to-run            # 预建的仿真镜像文件
74```
75
76## IDE 支持
77
78### bsp
79```
80make bsp
81```
82
83### IDEA
84```
85make idea
86```
87
88
89## 生成 Verilog
90
91* 运行 `make verilog` 以生成 verilog 代码。输出文件为 `build/XSTop.v`。
92* 更多信息详见 `Makefile`。
93
94## 仿真运行
95
96### 环境搭建
97
98* 设定环境变量 `NEMU_HOME` 为[香山 NEMU](https://github.com/OpenXiangShan/NEMU) 在您机器上的绝对路径。
99* 设定环境变量 `NOOP_HOME` 为香山工程文件夹的绝对路径。
100* 设定环境变量 `AM_HOME` 为[香山 AM](https://github.com/OpenXiangShan/nexus-am) 的绝对路径。
101* 项目使用 `mill` 进行 scala 编译，因此需要安装 `mill`，详见 [mill 手动安装指南](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html#_installation)（目前仅英文版本）。
102* 克隆本项目，运行 `make init` 以初始化本项目引用的开源子模块。
103
104### 运行仿真
105
106* 安装开源 verilog 仿真器 [Verilator](https://verilator.org/guide/latest/)。
107* 运行 `make emu` 以利用 Verilator 构建 C++ 仿真器 `./build/emu`。
108* 运行 `./build/emu --help` 可以获得仿真器的各种运行时参数。
109* 更多细节详见 `Makefile` 与 `verilator.mk`。
110
111运行示例：
112
113```bash
114make emu CONFIG=MinimalConfig EMU_THREADS=2 -j10
115./build/emu -b 0 -e 0 -i ./ready-to-run/coremark-2-iteration.bin --diff ./ready-to-run/riscv64-nemu-interpreter-so
116```
117
118## 错误排除指南
119
120[Troubleshooting Guide](https://github.com/OpenXiangShan/XiangShan/wiki/Troubleshooting-Guide)
121
122## 致谢
123
124香山处理器是绝佳的微架构学术研究平台，能够充分支持学术界的试验创新想法。香山处理器中已经实现或参考借鉴了如下论文，列举如下：[致谢](https://docs.xiangshan.cc/zh-cn/latest/acknowledgments/)。我们非常鼓励并期待，未来能够基于香山处理器实现更多的学术创新。