构建、仿真与调试入口

本页只覆盖进入微架构学习所需的最短路径。香山完整 RTL 构建和仿真依赖较多， 运行前应核对仓库 README、内存和磁盘条件。

本机仓库状态

仓库已使用递归方式克隆，并执行了官方初始化目标：

git clone --recurse-submodules \
  https://github.com/Daydream0929/XiangShan.git
cd XiangShan
make init

make init 会初始化必要的一级和嵌套 submodule。当前 checkout 的递归 submodule 状态均与 superproject 固定提交一致。

为什么仍然使用 make init

即使 clone 时带了 --recurse-submodules，make init 仍是上游定义的 初始化入口。以后 submodule 列表或额外初始化步骤改变时，这个目标更可靠。 目标定义见 Makefile。

生成 Verilog

默认配置生成：

make verilog

常用的参数化入口：

make verilog CONFIG=DefaultConfig
make verilog CONFIG=BackendV2Config

在比较结构参数前，必须记录 CONFIG。例如当前 DefaultConfig 与 BackendV2Config 的译码宽度、ROB/RAB 和物理寄存器配置不同。

资源预算

根 Makefile 的 JVM 默认最大堆配置达到数十 GB。不要在共享机器上盲目并行 启动多个 elaboration；先检查可用内存、构建目录和其他用户负载。

构建仿真器

上游推荐入口：

make emu

difftest submodule 提供仿真、参考模型和差分测试基础设施。理解一次失败时， 先把问题分成三类：

1. 架构状态不一致：提交点 PC、GPR/FPR/VR、CSR 或内存状态不同；
2. 实现时序问题：replay、redirect、flush 或握手在错误周期发生；
3. 环境/模型差异：设备、MMIO、未定义行为或 reference model 配置不同。

调试数据库

仓库提供 XSPdb 入口：

make pdb

相关文档与脚本位于：

• docs/XSPdb
• scripts/xspdb
• difftest

只构建本站文档

文档构建与 RTL 构建完全隔离：

python3 -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install -r requirements-docs.txt
mkdocs serve

严格检查：

mkdocs build --strict

本地地址通常为 http://127.0.0.1:8000/XiangShan/。GitHub Pages 部署由 仓库 workflow 自动完成。