XiangShanLab：香山处理器学习与实践平台

English | 香山官网 | GitHub Issues

XiangShanLab 是面向香山处理器学习、开发与验证的开放式知识与实践仓库。仓库围绕香山开发环境、Scala/Chisel、Diplomacy、RISC-V 规范、处理器微架构、运行场景分析、调试方法和工程实践组织内容，并提供题库、Bug 案例、研究资料、AI 辅助工具与竞赛项目。

本仓库适合：

• 希望从零开始运行并系统学习香山的学习者；
• 希望掌握 Chisel、Diplomacy、SoC 集成与总线互联的开发者；
• 希望分析香山流水线、访存、预测、异常和调试机制的研究者；
• 希望开展 RISC-V 验证、Bug 定位、波形分析或 AI 加速扩展的工程人员。

仓库内容仍在持续建设中。部分章节、题目和工具可能尚未完善，欢迎通过 Issue 或 Pull Request 参与改进。

快速开始

1. 克隆仓库

仓库包含 wavekit-xslab 子模块，建议递归克隆：

git clone --recursive https://github.com/OpenXiangShan/XiangShanLab.git
cd XiangShanLab

如果已经完成普通克隆，可补充初始化子模块：

git submodule update --init --recursive

2. 选择入口

• 第一次接触香山：阅读学习路径指引，然后从开发环境课程开始。
• 学习 Chisel / Diplomacy：进入香山编程课程并结合编程实践动手练习。
• 分析香山微架构：依次学习超标量基础、设计文档和源码分析。
• 开展场景验证与调试：使用场景分析、调试案例及工具集。
• 准备竞赛项目：查看2026 CIE RISC-V 大赛应用方向及其提交指南。

推荐学习路径

基础阶段

1. 搭建环境并完成 Hello XiangShan；
2. 学习 Scala、Chisel 与基本工程实践；
3. 了解 RISC-V 指令集、特权架构与常用模拟器；
4. 建立流水线、冒险、乱序执行和存储层次的基础认识。

进阶阶段

1. 阅读香山设计文档和模块源码分析；
2. 结合波形理解指令从取指到提交的生命周期；
3. 学习预测、重定向、访存重放、异常与 Difftest 等典型场景；
4. 通过题库、Bug 案例和实践项目巩固分析与实现能力。

方向化实践

• 香山处理器方向：重点学习微架构、场景分析、调试和源码工具。
• DSU / SoC 方向：重点学习 Chisel、Diplomacy、TileLink、AXI 和互联实践。
• 香山 AI 方向：在掌握架构基础后，尝试自定义指令、算子加速和软硬件协同优化。

更完整的分阶段建议、任务认领与交付说明见学习路径指引。

课程体系

课程主体位于 xiangshan-course/：

课程同时提供 docs-en/ 英文资料；目前英文内容主要覆盖前六章，不同章节的翻译进度可能不同。

仓库资源地图

编程实践

xiangshan-programming-practice/ 提供可独立阅读和运行的实验工程，包括：

• ChiselIOPMP/：IOPMP 核心实现及相关数据通路示例；
• IopmpSystem/：DCache—IOPMP—Memory 系统级实验；
• TwoToOneXbarSystem/：2-to-1 AXI4 XBar 互联实验；
• NonBlockingCache/：非阻塞 Cache 设计实践；
• mmu-smmpt/：MMU / SMMPT 相关实现与测试。

各工程的依赖和运行方法不同，请以对应目录中的 README 与构建文件为准。

AI 与分析工具

tools/ 主要面向 Codex/agent 辅助的硬件学习、验证和分析工作流，当前覆盖：

• 香山 Kunminghu 源码结构与机制分析；
• 基于 WaveKit 的流水线和单指令波形追踪；
• 微架构机制到可执行验证场景的转换；
• 测试生成、仿真、波形检查的场景闭环；
• 香山 Issue/PR 数据整理与 Bug 归因；
• RISC-V 安全、隔离、I/O 保护和可信调试规范查询。

多数工具以 SKILL.md 为入口，并通过 references/、scripts/ 和 agents/ 提供配套资料。涉及真实源码、波形或仿真时，请同时提供对应路径、分支或 commit、目标 PC 和运行命令。

参与贡献

欢迎修正文档、补充课程、回答题目、添加实验、整理 Bug 案例或完善工具。

建议流程：

1. Fork 本仓库并从最新主分支创建工作分支；
2. 尽量保持修改聚焦，并核对文档中的相对链接与命令；
3. 在 Pull Request 中说明修改目的、影响范围和验证方式；
4. 如发现问题但暂时无法修复，可先提交 GitHub Issue。

社区任务的认领、同步与交付原则可参考社区去中心化治理策略。Hello XiangShan 任务的特定提交流程见提交指南。

许可与说明

• 本仓库由多个课程、代码、数据和工具模块组成，请以各目录中的许可证和说明为准。
• xiangshan-course 中的代码采用 Apache-2.0，课程文档采用 CC BY-NC 4.0；详情见其课程 README。
• 外部论文、规范、图片、代码和链接的版权归原作者或对应项目所有。
• 本仓库不是香山处理器 RTL 主仓库；香山处理器源码与开发环境请参考下方关联项目。

关联项目

• OpenXiangShan/XiangShan：香山处理器主仓库；
• OpenXiangShan/xs-env：香山开发与仿真环境；
• XiangShanLab/wavekit-xslab：本仓库使用的 WaveKit 子模块；
• openxiangshan.cc：香山官方网站。

---

从学习路径指引开始，完成第一次香山运行，再逐步进入编程、微架构、场景分析与调试实践。