English | 香山官网 | GitHub Issues
XiangShanLab 是面向香山处理器学习、开发、验证和研究的开放仓库。仓库以课程文档为主，同时收录编程实践、问题题库、Bug 案例、分析工具、研究论文、合作机构资料、外部贡献项目以及竞赛项目。
仓库包含 tools/wavekit-xslab Git 子模块，建议递归克隆：
git clone --recursive https://github.com/OpenXiangShan/XiangShanLab.git
cd XiangShanLab如果已经完成普通克隆：
git submodule update --init --recursive- 第一次学习香山：阅读学习路径指引，再从香山开发环境课程开始。
- 学习 Scala、Chisel 和 Diplomacy：阅读香山编程课程，并完成编程实践中的工程。
- 学习 RISC-V 规范：进入RISC-V 规范资料。
- 分析香山微架构：从超标量基础开始，再阅读设计文档和源码分析。
- 研究运行场景和调试问题：使用场景分析、调试案例和问题题库。
- 使用 AI 辅助工具分析源码、波形或 Bug：查看工具目录及各工具的
SKILL.md。 - 登记或了解社区外部贡献项目：查看外部贡献项目目录，了解项目与 RISC-V、香山及其支撑方向的关系。
- 参加 2026 CIE RISC-V 大赛：查看应用方向赛题和提交指南。
- 参与 RISC-V 国际社区：阅读RISC-V International 参与指南，了解如何注册会员、加入群组、订阅邮件列表和加入委员会。
课程主体位于 xiangshan-course/，中文资料位于 docs/，英文资料位于 docs-en/。中文课程当前包含 14 个章节目录；英文课程当前包含 8 个章节目录，另有一个独立的微架构资料目录。
| 章节 | 内容 | 入口 |
|---|---|---|
| 1 | 香山开发环境、模拟器、仿真流程与 Difftest | 开始学习 |
| 2 | Scala、Chisel、Diplomacy、TileLink 与 AXI | 开始学习 |
| 3 | RISC-V 指令集与规范资料 | 开始学习 |
| 4 | 超标量、乱序执行、前端、后端和存储子系统 | 开始学习 |
| 5 | 指令生命周期、预测、预取、访存、重放和冲突 | 开始学习 |
| 6 | Bug 分析、异常、CSR、PMA/PMP、X-state 和调试案例 | 开始学习 |
| 7 | NoC、Cache 一致性、CHI、XSCache、DDR 和死锁 | 进入目录 |
| 8 | 香山 AI 相关资料 | 进入目录 |
| 9 | AIA 规范、设计、集成和隔离 | 进入目录 |
| 10 | 安全方向资料 | 进入目录 |
| 11 | DDR 相关资料 | 进入目录 |
| 12 | 工作负载和虚拟机运行场景 | 进入目录 |
| 13 | 验证方向资料 | 进入目录 |
| 14 | 香山敏捷工具资料 | 进入目录 |
课程仓库的详细说明、许可证和中英文资料入口见 xiangshan-course/README.md。
| 目录 | 内容 | 推荐入口 |
|---|---|---|
xiangshan-course/ |
香山系统化学习课程，包含中文和英文文档 | 课程 README |
xiangshan-programming-practice/ |
IOPMP、AXI XBar、非阻塞 Cache、MMU/SMMPT 等实践工程 | 实践目录 |
xiangshan-question-bank/ |
香山开发、Chisel、Diplomacy、ISA、微架构、验证和系统软件题库 | Hello XiangShan 题目 |
xiangshan-bugs-library/ |
异常类和微架构类 Bug 摘要，以及 Bug 数据处理脚本 | 微架构 Bug 摘要 |
tools/ |
源码分析、波形分析、场景提取、验证驱动、Bug 分析和规范查询工具 | 工具 README |
XiangShanLab-user-guide/ |
学习路径、任务提交、文档反馈和社区协作说明 | 学习路径指引 |
xiangshan-research/ |
香山相关论文、研究方向和文献索引 | 论文索引 |
xiangshan-collaborators/ |
香山合作高校和科研机构资料 | 合作机构 |
external-contribution-project/ |
香山社区、合作机构和个人贡献的外部项目登记资料 | 项目说明 |
2026-CIE-RISC-V-Contest-Application-Track/ |
2026 CIE RISC-V 大赛应用方向赛题与提交文件 | 赛题说明 |
RISC-V-International-Participation-Guide/ |
RISC-V International 参与指南：会员注册、群组/邮件列表与委员会加入 | 参与指南 |
xiangshan-programming-practice/中的项目相互独立，依赖和运行命令以各项目 README、Makefile 或 build.sbt 为准：
ChiselIOPMP/：DMA 到 IOPMP 再到 Memory 的 Chisel 实验；IopmpSystem/：DCache、IOPMP 和 Memory 组成的系统级实验；TwoToOneXbarSystem/：两个 AXI4 Master 共享一个 Memory Slave 的 2-to-1 XBar 实验；NonBlockingCache/：非阻塞 Cache 设计与测试；mmu-smmpt/：MMU / SMMPT 相关实现、模块和测试；miniXiangShan/：以香山微架构为原型的教学级乱序处理器 Chisel 工程（RV32IM + Sv32 分页），详见项目 README。
external-contribution-project/用于登记香山社区、合作实验室、高校、企业和个人贡献的外部项目，包括实验、工具、验证框架、扩展模块和研究成果。项目可以使用香山、扩展香山、验证香山，或为香山提供运行、集成和研究基础设施。
新增项目时，请基于贡献模板在对应项目目录中说明项目简介、公开仓库、依赖的 RISC-V 扩展和香山版本、构建或验证命令、维护组织及贡献者信息。详细登记规范、开发环境要求和当前项目列表见外部贡献项目 README。
tools/中的工具主要服务于 Codex/agent 辅助的硬件学习和验证工作，当前包括：
xiangshan-code-analyzer/：香山 Kunminghu 源码分析；analyze-xiangshan-wavekit/、xiangshan-wave-analysis/：波形和流水线行为分析；scenarios-extractor/、verification-driver/：验证场景提取与验证规则；xiangshan-debug/：调试和 Difftest 追踪；xiangshan-bugs-analyzer/：香山 Issue/PR 数据整理和 Bug 分析；riscv-skill-pack/、specification-analyzer/：RISC-V 技术和安全规范查询；wavekit-xslab/：作为 Git 子模块接入的 WaveKit 工具。
多数工具以 SKILL.md 为入口。涉及源码、波形或仿真时，应同时提供对应路径、分支或 commit、目标 PC 和运行命令。
欢迎补充课程、修正文档、回答题目、添加实践工程、整理 Bug 案例、完善工具，以及登记和维护外部贡献项目。
建议：
- 从最新主分支创建聚焦的工作分支；
- 修改后检查 Markdown 相对链接、命令和目录名称；
- 在 Pull Request 中说明修改内容、影响范围和验证方式；
- 如果暂时无法修复问题，可通过 GitHub Issues 报告。
外部贡献项目请登记在 external-contribution-project/ 中。当前目录包含 HACO、内存安全和香山外部验证项目等资料；项目可使用、扩展或验证香山，也可提供 DDR、验证、AI、NoC 或安全等支撑能力。
新增项目时，请复制贡献模板到对应项目目录，并填写项目简介、公开仓库、与 RISC-V 和香山的关系、依赖的 RISC-V 扩展和香山版本或 commit、构建或验证命令、维护组织及贡献者信息。具体项目清单和登记要求见外部贡献项目 README。
任务认领、同步和交付规则见社区去中心化治理策略，Hello XiangShan 的提交流程见提交指南。
仓库已关闭空白 Issue。请根据问题类型选择合适的模板，并在提交前搜索已有 Issue，补充可复现的上下文、相关链接和验证结果。
| 模板 | 适用场景 |
|---|---|
| 任务发布 | 发布可被认领、需要质押并按 DDL 交付的课程或工程任务；请把交付物写成可验收清单。 |
| hello xiangshan 作业提交 | 提交已完成的 hello xiangshan 基础任务；请上传完整运行截图，并阅读提交指南。 |
| 报告文档问题 | 报告课程文档中的错误、过时内容、失效链接或表述不清。 |
| Technical Q&A | 咨询课程材料、文档、源码或调试相关的具体技术问题；请提供准确链接、命令和错误信息。 |
| Project Collaboration Proposal | 提议新的协作项目；请说明背景、范围、里程碑、交付物和参与方式。 |
| Contribution Certificate Application | 为已完成的香山项目或贡献申请贡献证明；请提供可核验的项目链接和证书信息。 |
| RISC-V International Proposal (XiangShan) | 向 RISC-V International 提交与 XiangShan 开源高性能 RISC-V 处理器相关的提案；请说明目标领域（AI、SoC、Server Platform、Security 等）、目标 SIG/TG/HC、动机与解决方案、使用场景、实现与验证、时间线里程碑及成员资格状态。 |
任务发布、认领、同步和交付规则见社区去中心化治理策略。如果模板无法覆盖你的问题，请先在对应模板中补充说明；config.yml 已禁用空白 Issue。
- 本仓库包含课程、代码、数据和工具模块，各目录的许可证和说明可能不同，请以对应目录为准。
xiangshan-course的代码采用 Apache-2.0，课程文档采用 CC BY-NC 4.0，详情见课程 README。- 本仓库不是香山处理器 RTL 主仓库。处理器源码、开发环境和官网见：