ScratchV-topic06-deliverable

ScratchV-topic06-deliverable/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ScratchV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ScratchV-topic06-deliverable/docs/topic06_bench_suite_usage.md

@@ -0,0 +1,166 @@
+# 课题 6：ScratchV 课程版性能测试套件使用说明
+
+本文档只说明当前作业交付使用的课程版测试套件：`run_tests.py` 和 `tests_main/`。
+
+## 1. 目录结构
+
+```text
+run_tests.py             # 自动化测试脚本
+
+tests_main/
+  activation/            # relu 等激活函数用例
+  branch/                # if/else 分支用例
+  elementwise/           # add 和链式 add 用例
+  loop/                  # for/endfor 循环用例
+  reduction/             # dot/reduction 用例
+  tensor/                # matmul/tensor 用例
+
+build/                   # 编译后生成的 RISC-V 汇编
+
+reports/
+  report.md              # Markdown 测试报告
+  report.html            # HTML 测试报告
+  course_report_instructions.png
+  benchmark_baseline.json
+
+.github/workflows/
+  benchmark.yml          # CI 示例，运行课程版测试套件
+```
+
+当前 `tests_main/` 下有 23 个 DSL 用例，覆盖算术、神经网络算子、循环、if/else 分支、矩阵计算和组合场景。
+
+## 2. 运行测试
+
+在项目根目录运行：
+
+```powershell
+python run_tests.py
+```
+
+运行后会自动：
+
+- 遍历 `tests_main/` 下的 `.dsl` 文件。
+- 调用 ScratchV 编译器生成汇编。
+- 调用 TinyFive 适配器模拟执行。
+- 使用参考执行器计算实际返回值。
+- 对比实际返回值和 `.meta.json` 中的预期返回值。
+- 统计 PASS/FAIL 和指令数。
+- 生成报告。
+
+## 3. Benchmark 模式
+
+重复运行 3 次并取平均：
+
+```powershell
+python run_tests.py --benchmark 3
+```
+
+报告会记录：
+
+- 平均指令数
+- 最小指令数
+- 最大指令数
+- 95% 置信区间
+- 基线指令数
+- 性能变化率
+- 是否性能退化
+
+## 4. 性能基线和退化判断
+
+第一次生成基线：
+
+```powershell
+python run_tests.py --benchmark 3 --update-baseline
+```
+
+之后正常运行：
+
+```powershell
+python run_tests.py --benchmark 3
+```
+
+判断规则：
+
+- 当前平均指令数比基线高出 5% 以上，判定为性能退化。
+- 低于或等于 5% 的波动不算退化。
+- 基线文件保存在 `reports/benchmark_baseline.json`。
+
+## 5. 报告文件
+
+运行后生成：
+
+```text
+reports/report.md
+reports/report.html
+reports/course_report_instructions.png
+```
+
+`report.md` 适合提交作业或放进文档。`report.html` 适合演示，包含表格和 `matplotlib` 生成的性能图表。
+
+## 6. 添加新测试用例
+
+每个课程版用例由两个文件组成：
+
+```text
+tests_main/{category}/{name}.dsl
+tests_main/{category}/{name}.meta.json
+```
+
+`.dsl` 示例：
+
+```text
+# Simple add
+result = add(a, b)
+return result
+```
+
+`.meta.json` 示例：
+
+```json
+{
+  "description": "Simple scalar add.",
+  "expected_output_type": "return_value",
+  "inputs": {
+    "a": 2,
+    "b": 3
+  },
+  "expected_return": 5
+}
+```
+
+添加后运行：
+
+```powershell
+python run_tests.py --benchmark 3
+```
+
+如果失败，优先检查 DSL 语法、输入变量名、预期输出和当前编译器是否支持该算子。
+
+## 7. if/else 分支语法
+
+当前支持简单分支：
+
+```text
+if flag
+result = add(a, b)
+return result
+else
+result = sub(a, b)
+return result
+endif
+```
+
+规则：
+
+- `flag` 非 0 时走 `if` 分支。
+- `flag` 为 0 时走 `else` 分支。
+- 当前不支持复杂比较表达式，比如 `if a > b`。
+
+## 8. CI
+
+`.github/workflows/benchmark.yml` 会在 push 和 pull request 时运行：
+
+- `python -m pytest -q`
+- `python run_tests.py --benchmark 3`
+
+CI 会上传课程版报告文件，方便查看每次修改后的正确性和性能变化。

ScratchV-topic06-deliverable/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scratchv"
+version = "0.1.0"
+description = "A compiler from ONNX models to RISC-V assembly"
+requires-python = ">=3.10"
+dependencies = [
+    "onnx>=1.14",
+    "numpy>=1.24",
+    "protobuf>=4.21",
+    "jinja2>=3.1",
+    "matplotlib>=3.7",
+]
+
+[project.scripts]
+scratchv = "scratchv.main:main"
+
+[tool.setuptools.packages.find]
+include = ["scratchv*"]

ScratchV-topic06-deliverable/reports/benchmark_baseline.json

@@ -0,0 +1,117 @@
+{
+  "add_relu_relu": {
+    "category": "activation",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "relu_add": {
+    "category": "activation",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "relu_only": {
+    "category": "activation",
+    "avg_instr_count": 7.0,
+    "runs": 3
+  },
+  "relu_twice": {
+    "category": "activation",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "if_else": {
+    "category": "branch",
+    "avg_instr_count": 26.0,
+    "runs": 3
+  },
+  "if_relu": {
+    "category": "branch",
+    "avg_instr_count": 22.0,
+    "runs": 3
+  },
+  "if_then": {
+    "category": "branch",
+    "avg_instr_count": 26.0,
+    "runs": 3
+  },
+  "add_chain": {
+    "category": "elementwise",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "add_chain_3": {
+    "category": "elementwise",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "add_fan_in_4": {
+    "category": "elementwise",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "add_reuse": {
+    "category": "elementwise",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "vector_add": {
+    "category": "elementwise",
+    "avg_instr_count": 7.0,
+    "runs": 3
+  },
+  "loop_add_4": {
+    "category": "loop",
+    "avg_instr_count": 27.0,
+    "runs": 3
+  },
+  "loop_add_chain_4": {
+    "category": "loop",
+    "avg_instr_count": 31.0,
+    "runs": 3
+  },
+  "loop_relu_add_4": {
+    "category": "loop",
+    "avg_instr_count": 30.0,
+    "runs": 3
+  },
+  "dot_4": {
+    "category": "reduction",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "dot_8": {
+    "category": "reduction",
+    "avg_instr_count": 8.0,
+    "runs": 3
+  },
+  "dot_relu_4": {
+    "category": "reduction",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "dot_relu_8": {
+    "category": "reduction",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "matmul_2x2": {
+    "category": "tensor",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "matmul_4x4": {
+    "category": "tensor",
+    "avg_instr_count": 9.0,
+    "runs": 3
+  },
+  "matmul_add_2x2": {
+    "category": "tensor",
+    "avg_instr_count": 10.0,
+    "runs": 3
+  },
+  "matmul_relu_2x2": {
+    "category": "tensor",
+    "avg_instr_count": 10.0,
+    "runs": 3
+  }
+}