diff options
Diffstat (limited to 'docs/specs/testing_and_ci.md')
| -rw-r--r-- | docs/specs/testing_and_ci.md | 83 |
1 files changed, 0 insertions, 83 deletions
diff --git a/docs/specs/testing_and_ci.md b/docs/specs/testing_and_ci.md deleted file mode 100644 index 9d869d8..0000000 --- a/docs/specs/testing_and_ci.md +++ /dev/null @@ -1,83 +0,0 @@ -# 测试与持续集成 (Testing & CI) - -## 1. 目标 (Objective) - -为 LumeOS 项目定义自底向上的自动化测试标准与持续集成(CI)规范。通过建立在系统早期启动阶段驻留执行的 Boot Self-Test(KUnit)框架,严格确保内存管理、调度器、同步原语等底层基础设施无隐患。配合 `make test` Makefile 目标以及退出码(Exit Code)规范,构筑防止代码腐化的防线。 - -## 2. 前置依赖 (Dependencies) - -- **全局类型契约:** `include/lume/types.h`。 -- **输出机制:** 早期格式化输出需求依赖 `early_puts` 和 `early_putc` 等纯串口驱动原语。 -- **宕机机制:** 依赖 `include/lume/panic.h` 定义的 `kernel_panic` 用于对测试失败执行终端处决。 -- **QEMU CI 环境:** 自动化截取退出码依赖硬件特性的 `sifive_test` 接口(通过 OpenSBI 提供 System Reset/Poweroff 的底层能力)。 - -## 3. 核心机制设计 - -为了不侵入或依赖过于复杂的上下文结构,测试系统在操作系统生命周期的“最初始安全阶段”进行: -- **执行点:** 位于 `kernel_main()` 核心初始化逻辑收尾后(所有关键数据结构已分配完毕),但在多核被唤醒(AP 启动)以及用户态进程加载之前。 -- **单核无中断:** 测试套件固定且绝对运行于 BSP (CPU 0) 的单核互斥环境中。在这些断言执行时,硬件中断是被严格关闭的。 - -## 4. KUnit 宏签名与接口规范 (Public APIs) - -在 `include/lume/selftest.h` 中对外暴露以下断言宏。所有测试文件的断言仅允许使用下述原语: - -### 4.1 核心断言宏 - -所有断言宏若验证通过通常无反馈,一旦发现断言失败即发生 `Panic` 导致系统停机。 - -```cpp -// 最基础的条件真实性断言 -#define ST_ASSERT(cond) - -// 验证两个数值、指针或枚举绝对相等的断言 -// 失败时会自动将变量与地址分别序列化输出以协助排查 -#define ST_ASSERT_EQ(a, b) - -// 验证两个量绝对不相等的断言 -#define ST_ASSERT_NE(a, b) -``` - -### 4.2 控制与排版原语 - -```cpp -// 在每个用例的前置输出 `[test] <name> ... ` -void st_begin(const char* name); - -// 在用例顺利通过后输出 `PASS` 并换行 -void st_pass(); - -// C++ 自检主函数,由各个测试子模块(如 test_pmm.cc)自行声明填充。 -// 必须注册到 kernel_main 中调用的 `selftest_run_all()` 总表中。 -void selftest_xxx(); -``` - -## 5. Panic 退出码与 QEMU CI 自动退出 (Exit Codes) - -为了让 GitHub Actions 或者外部自动化测试流水线有效地判决 LumeOS 是否正确运行,我们需要与 QEMU 沟通,而不是靠正则表达式提取输出文字。 - -### 5.1 失败与宕机 (Panic) - -当某个 `ST_ASSERT` 失效时: -1. `kernel_panic("selftest failed", detail);` 触发。 -2. 串口向屏幕喷出宕机回溯(行号与文件名)。 -3. **调用 SBI 接口终止运行:**内核使用 OpenSBI (EID `0x53525354` System Reset Extension),发起 System Failure 指令并传送特定的退出码(例如 Exit Code 127)。 - -### 5.2 成功退出校验 - -当所有的 `selftest` 在 `make test` 命令中走通并通过所有的断言验证时: -1. 输出 `All self-tests PASSED`。 -2. 不会进入系统的死循环(挂机状态)。 -3. 核发送带有 Exit Code 0 的 SBI 成功关机请求,使得宿主机的 `make test` 返回码为成功,绿灯放行 CI 。 - -## 6. `make test` 规范 (Make Target) - -`make test` 须作为一个专职的自动化冒烟测试管道: - -- `make test` 将编译特制的测试版本(例如自动注册带有 CI 自动关机行为的 Flag )。 -- **屏蔽图形学延误:** 测试应当在 Makefile 使用 `-nographic` 的纯无头界面(Headless)运行 QEMU。 -- **无等待结束:** QEMU 只要执行测试程序,系统即可在极短时间内得到退出码反馈结果,不会陷入一直等待。 -- **集成于构建流:** `make fmt && make lint && make test` 是提交到 Main 分支之前在开发者本地应当成为默认习惯的行为指令链。 - -## 7. 错误路径 (Error Paths) - -因为其测试属性:只要未跑通,便进入灾难模式(Panic)。此时不考虑优雅释放任何当前持有的锁,亦不关闭或清理页表,而是立刻抛血书以保护现场,等待开发者进行后续 GDB 对照排查。 |
