yaozhicheng
5f66112dcc
|
||
|---|---|---|
| .. | ||
| image | ||
| README.md | ||
README.md
万众一芯之香山处理器
中文|English
本项目旨在通过开源众包的方式对香山处理器的昆明湖架构进行单元（Unit Test）验证。该项目选择Python作为主要的验证语言，参与验证你将学习到以下内容：
- 电路的运行特性：从软件的角度观察电路的运行特性，深入了解电路设计的原理。
- 高性能处理器设计：学习Chisel硬件描述语言，研读相关代码和论文，掌握最新的架构设计理念。
- 芯片验证的基本流程：熟悉规范文档（Spec文档），学习如何进行UT验证，并评估验证结果的合理性。
- Python芯片验证：掌握异步编程、回调等高级编程模式，利用Python进行芯片验证。
- Linux开发环境：学习基础的Linux操作命令，搭建验证环境。
本项目欢迎多方面的贡献，并将在一定期限内以特定方式给予奖励（如奖金、证书、实习机会等）。具体贡献类型包括：
- 贡献一：编写验证文档，包括设计对象（Design Under Test，DUT）的规范文档、说明文档、功能描述文档等。
- 贡献二：开发测试用例，包括针对各个功能点的测试代码与注释，以及相关的说明文档。
- 贡献三：发现并报告香山处理器中的bug，并提供原因分析和修复建议。
- 贡献四：其他方面的贡献，例如为本项目提供的工具增加新功能等。
万众一芯项目地址：https://open-verify.cc
期待你的参与！
整体状态
验证进度
当前各个DUT的验证状态，包括功能点个数、代码行覆盖率、Bug数等，请查看 https://open-verify.cc/UnityChipForXiangShan/。
其他内容快捷连接：
注：本项目中的统计信息根据commit等数据自动更新，参与者可以提交issue（写明任务内容，预计完成时间等）同步正在进行的任务。
准备环境
本项目基于Python编程语言进行UT验证，采用的工具和测试框架为picker和mlvp，环境需求如下：
- Linux操作系统。建议WSL2下安装Ubuntu22.04。
- Python。建议Python3.11。
- picker。按照快速开始中的提示安装最新版本。
- mlvp。可通过
pip3 install mlvp@git+https://github.com/XS-MLVP/mlvp安装最新版本。
环境配置完成后，clone仓库：
git clone https://github.com/XS-MLVP/UnityChipForXiangShan.git
下载RTL代码：
默认从仓库https://github.com/XS-MLVP/UnityChipXiangShanRTLs中下载。用户也可以自行按照XiangShan文档编译生成RTL。
cd UnityChipForXiangShan
make rtl # 该命下载最新的rtl代码，并解压至rtl目录，并创建软连接
# 可通过target指定版本
make rtl target=2024092701/openxiangshan-kmh-97e37a2237-24092701.tar.gz
所有RTL下载包请在UnityChipXiangShanRTLs中查看。
编译DUT
该过程的目的是将RTL通过picker工具打包为Python模块。可以通过make命令指定被打包DUT，也可以一次性打包所有DUT。
# 调用scripts目录中的Makefile.build_ut_<name>，创建待验证的Python版DUT
make dut target=<name>
# 例如：
make dut target=backend_ctrlblock_decode
# 调用scripts目录中所有的Makefile.build_ut_*文件，创建所有DUT。
make dut_all
以make dut target=backend_ctrlblock_decode为例，命令执行完成后，会在dut目录下生成对应的Python包：
dut/
├── __init__.py
├── decodestage
├── predecode
└── rvcexpander
完成转换后，在测试用例代码中可以import对应的DUT，例如：
from dut.predecode.UT_PreDecode import DUTPreDecode
dut = DUTPreDecode()
运行测试
本项目基于mlvp验证框架进行验证（mlvp基于Pytest测试框架）。运算测试时，测试框架自动搜索所有以test_*.py文件，并自动执行其中所有以test_开头的测试用例（Test Case）。
# 执行所有ut_*目录中的test case
make test_all
# 执行指定目录下的test case
make test target=<dir>
# 例如：
# 执行ut_backend/ut_decode目录中所有的test case
make test target=ut_backend/ut_decode
运行完成后，在out目录会生成html版本的测试报告，可通过浏览器直接打开查看（VS Code IDE建议安装Open In Default Browser插件）。
添加测试
添加一个全新的DUT测试用例，需要完成以下三部分内容：
- 添加编译脚本： 在
scripts目录下编写对应的rtl到python的编译Makefile文件（例如Makefile.build_ut_backend_ctrlblock_decode，必须以Makefile.build_ut_开头）以及对应的目录（目录中包含必要的输入文件，例如rtl的filelist，需要导出的内部信号等）。 - 添加测试用例： 在对应的
ut_*目录中创建对应的python模块（例如ut_backend/ctrl_block/decode）,在该模块中需要包含以test_*.py的测试用例。用例的目录结构请按照昆明湖层级架构图进行添加，以确保收集测试结果时能与层级图对应。测试用例的编写方法请参考Pytest官方文档。 - 添加依赖模块： 如果有需要的话，可以在
tools、comm等模块中添加该DUT测试需要的基础工具。如果该工具不够通用请添加到对应的ut_模块中，且不能以test_前缀进行命名（例如参考模型可以是ut_backend/ctrl_block/decode/reference.py）
如果是在已有的DUT测试中增加内容，按原有目录结构添加即可。
*目录或文件名称需要合理，能通过其命名知晓其具体含义。
如何通过picker和mlvp库进行Python芯片验证，请参考：https://open-verify.cc/mlvp/docs
添加文档
本项目的DUT文档通过docsy编写，文档内容位于documents/content目录，分en和zh-cn两种语言。具体文档编写语法，所用工具等，请参考docsy文档和hugo文档。
可以通过以下命令查看效果（hugo安装：documents/README.md）：
$cd documents
$hugo server
# 找到类似输出：
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
通过浏览器访问http://127.0.0.1:1313即可查看文档。
目录结构
├── comm # 公共函数模块，例如日志、环境配置等
├── docs # 文档在线部署目录（web + doc），请不要修改
├── documents # DUT docsy 文档
│ ├── content
│ │ ├── en
│ │ │ └── docs # DUT 英文文档
│ │ └── zh-cn
│ │ └── docs # DUT 中文文档 （提交PR时，中英文都需要）
│ └── static # DUT 静态目录，插入的图片按content中的目录结构放该目录
├── dut # DUT的Python模块，自动生成
├── out # 输出
│ └── report # 输出的测试报告
├── rtl # RTL文件目录
├── scripts # DUT转Python的编译脚本
├── tools # 公共工具模块
├── ut_backend # 后端测试集合
├── ut_frontend # 前端测试集合
├── ut_mem_block # 访存测试集合
└── ut_misc # 其他访存测试集合
参与本项目
本项目欢迎任何人以Fork + PR的方式参与。
若测试过程中发现bug，提交流程如下：
- 参与者编写测试用例，自测完成后提交PR
- 如果发现有未pass的测试，分析bug原因，然后在本仓库提交 issue（关联对应PR），并赋予bugc标签
- 香山开放者确认bug，修改标签为bug
- 参与者在香山官方仓库上提交issue（附上本仓库的issue确认连接）
*请在issue中对bug进行详细描述，方便加速确认
万众一芯QQ交流群：
