From db4a27389b23afe803b47b8ee4a74f4ff21ab0d5 Mon Sep 17 00:00:00 2001 From: yaozhicheng Date: Thu, 11 Apr 2024 16:15:54 +0800 Subject: [PATCH] split doc --- Readme.md | 188 ++-------------------------------------- Readme_cn.md | 74 ++++++++++++++++ doc/env_cn.md | 136 +++++++++++++++++++++++++++++ doc/join_cn.md | 73 ++++++++++++++++ image/ov-pipline.drawio | 105 ++++++++++++++++++++++ image/ov-pipline.svg | 4 + 6 files changed, 398 insertions(+), 182 deletions(-) create mode 100644 Readme_cn.md create mode 100644 doc/env_cn.md create mode 100644 doc/join_cn.md create mode 100644 image/ov-pipline.drawio create mode 100644 image/ov-pipline.svg diff --git a/Readme.md b/Readme.md index 482e235..5a3c672 100644 --- a/Readme.md +++ b/Readme.md @@ -1,190 +1,14 @@ -# 香山微架构开放验证第一期：昆明湖BPU模块UT验证实战 +# The first phase of Open Verification for the Kunminghu microarchitecture of Xiangshan: Kunminghu's BPU Module UT Verification in Action. -本仓库为“香山微架构开放验证第一期：昆明湖BPU模块UT验证实战”的验证环境。该验证环境需要在linux系统下运行，它包含了如何生成带验证的Python DUT模块、验证示例、验证报告生成等模块。（待验证模块对应的香山仓库为：[github.com/OpenXiangShan/XiangShan](https://github.com/OpenXiangShan/XiangShan)，commit为：XXXX） +[中文文档](Readme_cn.md) -**本验证活动官方为：[www.openverify.cc](https://openverify.cc)** +This project aims to explore open-sourced subdivision verification of the high-performance open-source RISC-V OpenXiangshan processor's microarchitecture. It introduces new tools and methods based on Python, enabling all students interested in chip design and verification to quickly grasp and study the XiangShan microarchitecture. This phase provides a detailed introduction to the principles and implementation of the branch prediction module of the XiangShan Kunminghu architecture, along with the corresponding open-source verification environment. Participants in this phase can earn points and rewards by submitting bugs, writing verification reports, and more. -**gitlink活动地址为：gitlink.com/xxx/xxx** +**The Open-Verify Porject Official Website：[www.openverify.cc](https://openverify.cc)** +**Gitlink Event：[https://www.gitlink.org.cn/glcc/2023/subjects/detail/473](https://www.gitlink.org.cn/glcc/2023/subjects/detail/473)** -## 0x0、安装依赖 - -除去基本的gcc/python3开发环境外，本验仓库还依赖RTL仿真器 Verilator（4.218 ）、Picker工具、MLVP库。具体安装方法请参考以下链接。 - -1. [Verilator](https://www.veripool.org/projects/verilator/wiki/Installing) -2. [Picker](https://github.com/XS-MLVP/picker) -3. [mlvp](https://github.com/XS-MLVP/mlvp) - -通过以下命令安装python依赖： -```bash -pip3 install XXXX XXXX XXXX -``` - -## 0x1、生成待验证模块 - -下载仓库 - -```bash -git clone https://github.com/XS-MLVP/env-xs-ov-00-bpu.git -cd env-xs-ov-00-bpu.git -``` - -### 生成 uFTB - -```bash -make uftb TL=python -``` - -上述命令会在当前目录中生成out目录，其中 picker_out_uFTB 目录下的 UT_FauFTB 即为待验证的Python Module。可以在python环境中直接导入。因为待验证的python DUT与python版本相关，所以无法提供通用版本的python-dut，需要自行编译。 - -```bash -out -`-- picker_out_uFTB - `-- UT_FauFTB - |-- _UT_FauFTB.so - |-- __init__.py - |-- libDPIFauFTB.a - |-- libUTFauFTB.so - |-- libUT_FauFTB.py - |-- uFTB.fst.hier - `-- xspcomm - |-- __init__.py - |-- __pycache__ - | |-- __init__.cpython-38.pyc - | `-- pyxspcomm.cpython-38.pyc - |-- _pyxspcomm.so -> _pyxspcomm.so.0.0.1 - |-- _pyxspcomm.so.0.0.1 - |-- info.py - `-- pyxspcomm.py - -4 directories, 13 files -``` - -当导入模块UT_FauFTB后，可以在Python环境中进行简单测试。 - -```python -from UT_FauFTB import * - -if __name__ == "__main__": - # Create DUT - uftb = DUTFauFTB() - # Init DUT with clock pin name - uftb.init_clock("clock") - - # Your testcases here - # ... - - # Destroy DUT - utb.finalize() -``` - -其他待验证模块，例如 TAGE-SC，FTB也可以通过类似命令生成。 - -### Tage SC - -```bash -make tage_sc TL=python -``` - -### FTB - -```bash -make ftb TL=python -``` - -**支持的模块名称有：uftb、tage_sc、ftb、ras。也可以通过如下命令，一次性生成所有DUT模块。** - -```bash -make all TL=python -``` - -## 0x2、BPU外围环境 - -BPU是CPU中的一个模块，单独无法运行，为了对BPU中的子模块进行验证，本环境提供了其所需的外围环境来驱动BPU中的各个模块。 - -### Fake-FTQ +## Introduction TBD -### 分支Trace - -TBD - - -## 0x3、验证示例 - -本仓库基于uFTB模块提供了验证示例，其中包含了：如何编写测试用例、发送激励、定义功能覆盖率、生成测试报告等。 - -### 编写TestCase - -TBD - -#### 创建测试函数 - -本验证环境基于Pytest进行搭建，因此如何编写test请参考文档：XXXXX。在本示例中，编写了如下test： - -```bash -xxxx/test_xxx.py -``` - -#### 发送激励 - -TDB - -#### 运行测试 - -TBD - -#### 生成测试报告 - -在运行 - -## 0x4、如何参与本活动 - -参与本验证活动，取得名次能够获得丰厚大奖，获得地址为：XXXX。 - -### 流程介绍 - -参与验证的流程如下图所示： - -【图】 - -#### （0）报名 - -TBD - -#### （1）资格认证 - -TBD - -#### （2）fork 本仓库 - -TBD - -#### （3）领取任务 - -TBD - -#### （4）分解测试点 - -TBD - -#### （5）编写测试用例 - -TBD - -#### （6）编写测试代码&测试发现bug - -TBD - -#### （7）通过Issue和PR汇报bug获得积分 - -TBD - -#### （8）编写测试文档 - -TBD - -#### （9）提交测试文档获得最终积分 - -TBD diff --git a/Readme_cn.md b/Readme_cn.md new file mode 100644 index 0000000..2946086 --- /dev/null +++ b/Readme_cn.md @@ -0,0 +1,74 @@ +# 香山微架构开放验证第一期：昆明湖BPU模块UT验证实战 + +**[English Document](Readme.md)** + + +本项目的目标是对高性能开源RISC-V香山处理器的微架构进行开放式分包验证的探索。它提供了基于Python的新工具、新方法，让所有对芯片设计与验证感兴趣的同学能够快速了解香山微架构，学习香山微架构。本期活动对香山昆明湖架构的分支预测模块的原理以及实现进行了详细介绍，并提供了对应的开源验证环境。参本次活动的同学，通过提交Bug、编写验证报告等获取积分与奖励。 + + +**开源开放验证官网：[www.openverify.cc](https://openverify.cc)** +**gitlink活动地址：[https://www.gitlink.org.cn/glcc/2023/subjects/detail/473](https://www.gitlink.org.cn/glcc/2023/subjects/detail/473)** + + +## 简介 + +本项目是基于开源工具对开源芯片进行的开源开放验证。本期验证的对象是香山昆明湖微架构中的BPU模块。 + +### 昆明湖微架构 + +昆明湖架构是香山开源处理器的第三代高性能微架构，架构图请参考：[昆明湖架构图]()。 + +### 芯片验证 + +芯片验证是芯片设计工作中的重点，跳过验证或者验证的不够，会导致流片失败或者芯片产品不达标，带来巨大损失。芯片设计公司把芯片设计当成核心商业机密，而芯片验证通常需要基于芯片设计源代码，因此芯片验证工作只能在公司内部进行。开源香山高性能risc-v芯片不存在“商业机密泄露”等问题，因此可以把芯片验证工作以类似软件分包、众包的方式进行分发，让感兴趣的人远程参与。 + +## 相关文档 + +1. **[基础学习材料](https://open-verify.cc/mlvp/docs/)**，学习什么是芯片验证，如何使用Python进行验证。 +1. **[香山BPU介绍](https://open-verify.cc/xs-bpu/docs/)**，学习什么是分支预测，香山处理器中采用了哪些基础预测器。 +1. **[如何参与本活动](doc/join_cn.md)**，介绍如何参与本活动，有哪些活动规则。 +1. **[构建验证环境](doc/env_cn.md)**，介绍基本验证环境搭建，如何进行验证和提交验证结果。 + + +## 本仓库目录 + +本仓库目录结构和对应说明如下： + +```bash +. +├── LICENSE # 开源协议 +├── Makefile # 注makefile +├── Readme.md # 英文readme +├── Readme_cn.md # 中文readme +├── doc # 仓库文档 +├── image # 文档图片 +├── mk # 子makefile +├── out # dut生成目录 +└── src # dut源代码 +``` + +**注：由于本项目是以PR的方式提交结果，所以请务必按照上述目录要求进行数据组织** + + +## 加入讨论群 + +为了防止群内广告泛滥，请运行以下Python代码获取群号: + +QQ群 +```python +import base64 +base64.b64decode('Your_Base64_Data_Here').decode() +``` + +微信群 +```python +import base64 +from io import BytesIO +from PIL import Image +base64_image_data = \ +"Your_Base64_Image_Data_Here_0"\ +"Your_Base64_Image_Data_Here_1" +image_data = base64.b64decode(base64_image_data) +image = Image.open(BytesIO(image_data)) +image.show() +``` diff --git a/doc/env_cn.md b/doc/env_cn.md new file mode 100644 index 0000000..de1915c --- /dev/null +++ b/doc/env_cn.md @@ -0,0 +1,136 @@ +# BPU验证环境 + +本环境提供BPU验证所需的所有依赖，以及工具包。本验证环境需要在linux系统下运行，它包含了如何生成带验证的Python DUT模块、验证示例、验证报告生成等模块。（待验证模块对应的香山仓库为：[github.com/OpenXiangShan/XiangShan](https://github.com/OpenXiangShan/XiangShan/tree/kunminghu)，commit为：[ea2f767c24941b08d375b2b9529cd11b5850960a](https://github.com/OpenXiangShan/XiangShan/tree/ea2f767c24941b08d375b2b9529cd11b5850960a)） + + +## 安装依赖 + +除去基本的gcc/python3开发环境外，本验仓库还依赖RTL仿真器 Verilator（4.218 ）、Picker工具、MLVP库。具体安装方法请参考以下链接。 + +1. [Verilator](https://www.veripool.org/projects/verilator/wiki/Installing) +2. [Picker](https://github.com/XS-MLVP/picker) +3. [mlvp](https://github.com/XS-MLVP/mlvp) + +通过以下命令安装python依赖： +```bash +pip3 install XXXX XXXX XXXX +``` + +## 生成待验证模块 + +下载仓库 + +```bash +git clone https://github.com/XS-MLVP/env-xs-ov-00-bpu.git +cd env-xs-ov-00-bpu.git +``` + +### 生成 uFTB + +```bash +make uftb TL=python +``` + +上述命令会在当前目录中生成out目录，其中 picker_out_uFTB 目录下的 UT_FauFTB 即为待验证的Python Module。可以在python环境中直接导入。因为待验证的python DUT与python版本相关，所以无法提供通用版本的python-dut，需要自行编译。 + +```bash +out +`-- picker_out_uFTB + `-- UT_FauFTB + |-- _UT_FauFTB.so + |-- __init__.py + |-- libDPIFauFTB.a + |-- libUTFauFTB.so + |-- libUT_FauFTB.py + |-- uFTB.fst.hier + `-- xspcomm + |-- __init__.py + |-- __pycache__ + | |-- __init__.cpython-38.pyc + | `-- pyxspcomm.cpython-38.pyc + |-- _pyxspcomm.so -> _pyxspcomm.so.0.0.1 + |-- _pyxspcomm.so.0.0.1 + |-- info.py + `-- pyxspcomm.py + +4 directories, 13 files +``` + +当导入模块UT_FauFTB后，可以在Python环境中进行简单测试。 + +```python +from UT_FauFTB import * + +if __name__ == "__main__": + # Create DUT + uftb = DUTFauFTB() + # Init DUT with clock pin name + uftb.init_clock("clock") + + # Your testcases here + # ... + + # Destroy DUT + utb.finalize() +``` + +其他待验证模块，例如 TAGE-SC，FTB也可以通过类似命令生成。 + +### Tage SC + +```bash +make tage_sc TL=python +``` + +### FTB + +```bash +make ftb TL=python +``` + +**支持的模块名称有：uftb、tage_sc、ftb、ras。也可以通过如下命令，一次性生成所有DUT模块。** + +```bash +make all TL=python +``` + +## BPU外围环境 + +BPU是CPU中的一个模块，单独无法运行，为了对BPU中的子模块进行验证，本环境提供了其所需的外围环境来驱动BPU中的各个模块。 + +### Fake-FTQ + +TBD + +### 分支Trace + +TBD + + +## 验证示例 + +本仓库基于uFTB模块提供了验证示例，其中包含了：如何编写测试用例、发送激励、定义功能覆盖率、生成测试报告等。 + +### 编写TestCase + +TBD + +#### 创建测试函数 + +本验证环境基于Pytest进行搭建，因此如何编写test请参考文档：XXXXX。在本示例中，编写了如下test： + +```bash +xxxx/test_xxx.py +``` + +#### 发送激励 + +TDB + +#### 运行测试 + +TBD + +#### 生成测试报告 + +TBD diff --git a/doc/join_cn.md b/doc/join_cn.md new file mode 100644 index 0000000..73f6ebc --- /dev/null +++ b/doc/join_cn.md @@ -0,0 +1,73 @@ +## 如何参与本活动 + +参与本验证活动，取得名次能够获得丰厚大奖，报名地址：www.TBDTBD.com + +### 流程介绍 + +参与验证的流程如下图所示： + + + +#### （0）在线报名 + +参加本活动的队伍队员数没有限制，可以是一个也可以是多个。最终奖金按队伍积分发放给队长，且在活动开放期间，队名和队长的名称会被群内公开。 + +#### （1）资格认证 + +为了对参赛队伍进行能力评估，本活动提供了数个具有已知bug的DUT让参加队伍进行验证测试，能发现其中的80%以上的bug并能进行原因分析的队伍才能获得获得参加资格。其中发现的bug数，也会变成对应的队伍积分。 + +#### （2）Fork仓库 + +Fork本仓库，然后在本地进行环境搭建，参与测试任务。 + +#### （3）领取任务 + +任务在本仓库Issue中进行描述，队长以Issue的方式在Issue下方进行报名。管理员会进行统计，然后群内发布公告。 + +#### （4）分解测试点与编写验证方案 + +测试点分解和验证方案是芯片验证过程中的重要步骤，直接影响验证结果。在本阶段，需要通过PR提交对应报告，组织方会对报告进行评审和打分。 + +#### （5）编写测试用例 + +测试用例编写，具体格式可以参考模板XXXX。测试用例需要覆盖到对应的测试点。 + +#### （6）编写测试代码&测试发现bug + +测试过程中，发现bug后，需要对bug进行分析。 + +#### （7）通过Issue和PR汇报bug获得积分 + +可以通过PR随时进行bug提交，但是一天组织方只对一个队伍进行一次bug审查。组织方根据bug类型，等级发放对应积分。 + +#### （8）编写测试文档 + +参考模板XXX进行对应文档编写。 + +#### （9）PPT在线答辩 + +编写PPT在线进行对整个验证任务的答辩。答辩根据给队伍的完成情况集中组织。 + + +## PR提交基本要求 + +覆盖率要求： + +1. 代码行覆盖率需要大于 95% +1. 功能覆盖率必要达到 100% +1. 覆盖率有验证环境运行得到，不可对报告和生成罗辑进行修改 + +文档要求： + +1. 对功能点进行合理的测试点分解。功能点可以自行增加，但不能对原始功能点进行删除。 +1. 设计的测试用例必要覆盖所有测试点和功能点 +1. 请按模板XXX进行编写测试文档 +1. 领取多个验证任务后，其验证报告需要分开写 + +积分获取方式： + +1. 合理的测点分解、合理的验证方案、规范的验证文档 +1. 验出bug并分析出bug原因，按bug确认等级获取积分 +1. 修复本项目中文档，代码中出现的错误，按错误等级获取积分 +1. 提交最终验证报告，按报告质量，覆盖率获得积分 +1. 最终汇报得分 diff --git a/image/ov-pipline.drawio b/image/ov-pipline.drawio new file mode 100644 index 0000000..bce7bc0 --- /dev/null +++ b/image/ov-pipline.drawio @@ -0,0 +1,105 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/image/ov-pipline.svg b/image/ov-pipline.svg new file mode 100644 index 0000000..8b4f9ed --- /dev/null +++ b/image/ov-pipline.svg @@ -0,0 +1,4 @@ + + + +
在线报名
在线报名
资格认证
资格认证
F
o
r
k
仓库
F...
领取任务
领取任务
测试点分解&验证方案
测试点分解&验证方案
编写
&测试测用例
编写 &测试测用例
b
u
g汇报
b...
测试文档撰写
测试文档撰写
P
P
T在线答辩
P...
每个队伍、每个阶段的基本数据（阶段、任务、积分）相互公开
每个队伍、每个阶段的基本数据（阶段、任务、积分）相互公开
队伍
队伍
结束
结算
结束 结算Text is not SVG - cannot display \ No newline at end of file