【从嵌入式视角学习香山处理器】一、如何开始？（开发环境搭建）

一、前言

当你看到这篇文章的时候，可能多少已经听说一点关于“香山处理器”项目的描述：它是一个完全开源的CPU设计项目，由中科院的老师和同学们发起并维护；如果说香山项目有“官方组织”，那应该就是中科院的师生们了。
Github仓库在这里：https://github.com/OpenXiangShan。
另外还有个Gitee仓库：https://gitee.com/OpenXiangShan。

这篇文章的内容主要为了记录我在搭建环境过程中踩过的坑，以及怎么解决的。包括：

• github代码克隆不下来
• 相关工具链安装失败
• 工程编译过程中的报错

但是，不包括以下内容：

• 工程子文件夹内容介绍
• 编译脚本解析
• 编译后的功能测试示例
• 编译后的性能测试示例
• chisel编程语言入门
• …

最后附上一切编译正常结束的样子，以供读者对照参考。

---

二、硬件配置要求：环境搭建是否有门槛？

香山作为一个以设计能真实流片的CPU为目的的代码项目，以及期望它“能像开源软件Linux kernel一样长盛不衰30年”（中科院老师说的），所以使用了比较低门槛、且高效率的语言chesel3来代替verilog。
但于此同时，chesel的编译对环境的内存大小要求较高：官方推荐64G（他们自己使用128G）。
硬盘和CPU要求不高。

官方推荐配置：（https://github.com/OpenXiangShan/xs-env#一初始环境准备）

请准备一台性能较强的服务器，以下为服务器的一些配置要求：
操作系统：Ubuntu 20.04 LTS （其他版本未测试，不建议使用） CPU：不限，性能将决定编译与生成的速度
内存：最低 32G，推荐 64G 及以上
磁盘空间：20G 及以上
网络：请自行配置顺畅的网络环境
-（提示：内存过小、SWAP空间不足会导致编译错误。参见：https://github.com/OpenXiangShan/XiangShan/issues/891）

我的配置：

• 虚拟机：VMware Workstation 16 Pro
• 操作系统：Ubuntu 20.04 LTS
• 内存：30G
• 磁盘空间：20G
• 处理器：i7-11700（分配8核）

注意：

• 如果内存不够大，可以尝试修改工程的编译参数（Xmx64G）为对应内存大小的一半看看

---

三、软件配置要求：有什么大坑要注意？

• VMware Workstation Pro：或者VMware Player也行
• 科学上网工具：Linux版本的科学上网工具，主要用于从Github下载代码和相关工具
• vscode（可选）：windows和Linux都要装，用于从本地windows用ssh连接到远程Linux看代码

---

四、软件安装（参考）

1、我的虚拟机：

为了能正常使用ssh进行开发，我的环境做了以下几点

• 虚拟机的“网络连接”设置为“桥接模式”
• 手动配置静态地址为：192.168.3.100（和本地windows在同一网段，具体看家里使用的路由器分配网段是多少）
• 手动安装和启动openssh-server：Ubuntu20.04默认精简了很多工具，需要安装系统后再手动安装（好像？）

2、我的科学上网工具：

（但如果你的环境能正常流畅地访问Github，这一步是不需要的；直接跳到下一节）
注意：科学上网工具不止一款。
配置并开启科学上网工具后还要设置全局变量和系统的代理参数：

• 全局变量：用于给命令行进行代理转发，主要是git clone https://github.com/xxx、curl https://xxx这俩命令要用到
• 系统的代理：用于给浏览器（和其他GUI软件？）进行代理转发，主要是为了能正常访问Github网页

3、我的本地vscode：（windows）

4、我的远程vscode：（Ubuntu20.04）

这小节的标题比较迷惑，但我想不出更好的描述……
实际想说的是：通过本地vscode用ssh远程打开Linux上的目录。

操作步骤：

• 打开本地的vscode
• 选择左侧栏的“Remote SSH”插件，然后输入Ubuntu地址和用户名：ssh <用户名>@<Ubuntu的静态ip>（即想要远程连接上的地址）
• 正常情况下即可连接上，然后本地vscode会自动打开图中的“终端”窗口：用cd <准备下载香山代码的路径>进入指定目录
• 从Github克隆香山的“环境部署”代码：git clone https://github.com/OpenXiangShan/xs-env.git
• 之所以克隆这个xs-env代码而不直接克隆OpenXiangShan，是因为完整的开发环境需要依赖很多其他的工具（python/mill/curl等）和子模块代码（Huancun/NutShell/Varilator等），xs-env的功能就是通过脚本帮我们一次性下载安装好

五、开发环境部署：完整的开发环境是怎样的？

开发环境部署主要按照xs-env的readme说明来（虽然这里遇到挺多坑……）。

git clone https://github.com/OpenXiangShan/xs-env
cd xs-env
sudo -s ./setup-tools.sh
source setup.sh

每一步都不能有报错。
如果遇到报错，可能的原因和值得尝试的方法如下：

现象	原因	解决方法
1.克隆代码失败（异常情况1）	访问Github时网络很不稳定	1.检查科学上网工具是否已经全局开启；2.echo $http_proxy和echo $https_proxy检查这两个变量是否为空；3.只有上面两步正常了才能真正通过科学上网工具代理去克隆代码；
2.mill工具安装超时失败	（同上）	（同上）
3.克隆rocket-chip代码失败（异常情况2）	科学上网工具代理对ssh连接方式无效	修改./xs-env/XiangShan/huancun/.gitmodules文件中的原下载链接git@github.com:OpenXiangShan/rocket-chip.git为https方式url = https://github.com/OpenXiangShan/rocket-chip.git
4.source setup.sh执行失败，提示edu.berkeley.cs:chisel3_2.12:3.5-SNAPSHOT	这个挺坑：是官方某次修改xs-env代码时引入的bug；比如我当时发现的是这个提交(2021.11.10)，从Github的在线编译报告能看到同样的报错	官方已解决，最新的代码不再出现报错；或者可以自己回退到有bug的上一次的提交：git reset --hard HEAD^，再次执行source setup.sh即可

---

六、开发环境验证：部署成功后是什么样子呢？（香山代码初次编译）

部署后的环境验证也继续按照xs-env的readme说明来进行：

cd ./XiangShan
make init
make verilog #可能误报error，但以下一步检查.v文件是否存在为准
ls XiangShan/build/XSTop.v #查看是否正常生成.v文件，否则的确是编译出错；下一步也会出错
make emu CONFIG=MinimalConfig SIM_ARGS=--disable-log EMU_TRACE=1 -j32
ls ./build/emu #查看是否正常生成emu文件，否则表示编译出错

上面的命令是编译最小配置的单核香山。

如果正常，则会有以下输出：

...
clang++    SimJTAG.o axi4.o common.o compress.o device.o flash.o keyboard.o lightsss.o ram.o remote_bitbang.o sdcard.o uart.o vga.o difftest.o goldenmem.o interface.o nemuproxy.o ref.o memdep.o runahead.o spikedasm.o tllogger.o main.o emu.o snapshot.o verilated.o verilated_dpi.o verilated_vcd_c.o VSimTop__ALL.a   -lpthread -lSDL2 -ldl -lz -lsqlite3    -o /home/cwq/1_xiangshan/xs-env/XiangShan/build/emu
rm VSimTop__ALL.verilator_deplist.tmp
make[3]: 离开目录“/home/cwq/1_xiangshan/xs-env/XiangShan/build/emu-compile”
make[2]: 离开目录“/home/cwq/1_xiangshan/xs-env/XiangShan/difftest”
make[1]: 离开目录“/home/cwq/1_xiangshan/xs-env/XiangShan/difftest”

接着可以（可选）用下面的命令尝试编译完整配置的双核香山（我没试过……可能出现别的报错）：

make SIM_ARGS="--dual-core" verilog
ls XiangShan/build/XSTop.v #查看是否正常生成.v文件，否则的确是编译出错；下一步也会出错
make emu -j32
ls ./build/emu #查看是否正常生成emu文件，否则表示编译出错

如果到这一步都正常结束，那么：
恭喜！环境搭建成功！
但如果遇到报错，可能的原因和值得尝试的方法如下：

现象	原因	解决方法
1.make init失败	克隆rocket-chip代码失败，导致命令执行异常	手动删除XiangShan/rocket-chip文件夹，再重新make init
2.make emu xxx失败	内存参数设置过小	修改对应的build.sc文件的两个-Xmx64G为Ubuntu总内存的一半左右，再执行命令（比如我虚拟机有30G，但修改为-Xmx10G后可正常）
3.make emu CONFIG=MinimalConfig xxx失败	之前执行make emu失败时留下不完整的文件夹导致的	删除该不完整的文件夹：make clean，重新执行命令即可

---

接下来准备继续按照readme的步骤，跑下workload。

欢迎邮箱（mapleleaf_chen@qq.com）或微信（HeyYo_Qing）交流~