参考资料与版本边界

本站口径

• 文档类型：基于源码的非官方、持续演进中文学习手册；
• 目标读者：RISC-V64 Bring-up、性能分析与优化工程师；
• 源码基线：kunminghu-v3，commit c7b373bdbe9a9417b4c22ede4ddd0d970eb48b73；
• 默认配置口径：top.DefaultConfig；
• 语言口径：中文是本站唯一内容源，不维护本站英文镜像。

更新源码后，先比较参数和模块边界，再更新文档。不能只替换页面上的 commit 字符串，因为调度拓扑、事件 ID、队列大小和恢复路径都可能改变。

一手资料

代码

• Daydream0929/XiangShan
• OpenXiangShan/XiangShan
• XSCache 子模块
• Difftest

香山官方文档

• 昆明湖 V3 设计文档
• 香山用户手册
• 香山官方文档主页

同名 V3 页面不保证描述同一代码快照

截至本站建立时，官方 kunminghu-v3 导航已覆盖前端、后端、访存、MMU 与 L2 等模块，但设计文档前言和用户手册正文仍明确以“昆明湖 V2R2”为对象。 本站优先用固定 commit 源码确认实现事实，再用官方文档解释设计意图，不能把 导航版本名直接当成与本仓库当前提交一致的实现版本。

RISC-V 规范

• RISC-V ISA Manual（官方仓库）
• 本站部署的 ISA 手册
• RISC-V International 技术规范

规范回答“软件可以依赖什么”，XiangShan 源码回答“当前实现如何做到”。若两者 看似冲突，先核对扩展版本、特权模式、WARL 条件和当前配置。

如何引用本站结论

推荐同时记录：

1. 本页 URL 与标题；
2. XiangShan commit；
3. 直接支持结论的源码 permalink；
4. 使用的 CONFIG；
5. 若为性能结论，附 workload 和原始 counter。

示例：

XiangShan kunminghu-v3 @ c7b373b
CONFIG=DefaultConfig
结论：写 satp/vsatp/hgatp 会生成流水线刷新条件
源码：src/main/scala/xiangshan/backend/fu/NewCSR/NewCSR.scala#L973-L981

已知缺口

首版重点建立软件到硬件的数据流，以下主题仍适合继续扩展：

• 每个 BPU predictor 的表结构、训练时机和时序；
• 各 Issue Queue 的精确端口/唤醒拓扑；
• RVV 指令拆分、异常与向量访存细节；
• CHI 状态机、snoop 与多核一致性案例；
• Linux perf 事件映射与真实板级测量；
• 用具体 benchmark 演示从 counter 到源码优化的完整案例。

这些缺口会在后续随仓库版本和实际工作问题逐步补齐。