# hygon-ckves

**Repository Path**: anolis/hygon-ckves

## Basic Information

- **Project Name**: hygon-ckves
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hygon CKVES

[English](README.en.md) | 简体中文

Hygon CKVES（CPU and Kernel Validation Exerciser Suite）是面向海光服务器平台的 Linux CPU 与内核验证测试套件。项目代码目前已加入 OpenAnolis 的正式代码仓库 `anolis/hygon-ckves`，为裸机和虚拟化环境提供可复现、可审查、可扩展的验证用例。

> **社区状态：** 本项目代码已加入 OpenAnolis 的正式代码仓库 [anolis/hygon-ckves](https://gitee.com/anolis/hygon-ckves)。

当前仓库使用 Avocado 运行测试，`tests/cpu/` 已有九项只读的启动与 CPU 检查；其他领域的用例待加入。

## 设计目标

- 覆盖 CPU 基础特性、RAS、IOMMU/PCI、虚拟化、安全、稳定性与压力测试。
- 同一用例可在开发机、实验室裸机和 CI 调度环境中使用一致的入口执行。
- 缺少硬件、内核配置或外部工具时明确记为 `CANCEL`，不制造假失败或假通过。
- 默认串行、默认非破坏性；会改变系统状态的用例必须显式标注并由用户授权。
- 用例、参数说明和辅助代码同仓维护，结果由 Avocado 按 job 归档。

## 设计方案

CKVES 首版采用轻量、同仓维护的测试架构：

- 测试用例先与 CKVES 同仓，代码评审时可以同时检查实现、参数和文档。
- 直接使用上游 Avocado 113.0 原生发现、标签和结果模型，不维护自定义套件解析器。
- 公共能力放在小型 `CKVESTest` 基类中，运行入口只做发现与参数转发。
- KVM 基础验证可以使用普通 Avocado 用例；需要复杂 VM 矩阵时再将 `avocado-vt` 作为可选层引入，不让它成为裸机用例的前置依赖。

详细设计见 [docs/architecture.md](docs/architecture.md)，新增用例的完整约束见 [tests/README.md](tests/README.md)。

## 仓库结构

```text
.
├── bin/ckves                 # 环境检查、用例发现和运行入口
├── ckves/                    # 公共 Python 包和 CKVESTest 基类
├── docs/                     # 架构和公开发布检查清单
├── selftests/                # 框架自身的单元测试，不是硬件用例
├── tests/
│   ├── _template/            # 不会被 Avocado 发现的用例模板
│   ├── cpu/
│   ├── iommu/
│   ├── ras/
│   ├── security/
│   ├── stability/
│   └── virtualization/
├── tools/                    # 用例规范和敏感信息检查工具
├── CONTRIBUTING.md           # 贡献流程和评审要求
├── LICENSE                   # Apache License 2.0
├── Makefile                  # 本地和 CI 的稳定入口
└── pyproject.toml            # Python 包与 Avocado 版本声明
```

## 快速开始

### 1. 准备环境

要求 Linux、Python 3.9 或更高版本，以及 Python `venv`。首次执行会在仓库内创建 `.venv`，不会修改系统 Python 环境。

```bash
make setup
make doctor
```

`doctor` 会检查 Avocado、CPU 架构、CPU vendor、当前权限和目录结构。开发框架不要求必须运行在海光机器上；具体用例应在 `setUp()` 中声明自己的平台前置条件。

默认从 Python 配置的软件源安装依赖。网络较慢时可用标准 pip 环境变量指定组织内或区域镜像，例如 `PIP_INDEX_URL=<mirror>/simple make setup`。Avocado 113 仍依赖 `pkg_resources`，因此项目同时约束 `setuptools<81`；升级 Avocado 时应重新评估并移除该兼容约束。

### 2. 查看和运行用例

`list` 列出已加入的 CPU 用例，`run` 在目标机器上执行；用例检查内容及前置条件见 [CPU 用例说明](tests/cpu/README.md)。

```bash
make list
make run
```

可以按文件、目录或标签执行：

```bash
# 运行全部用例，默认最多一个任务并行
bin/ckves run

# 运行 CPU 域
bin/ckves run tests/cpu

# 逗号表示标签同时满足
bin/ckves run --tags 'tier:smoke,risk:safe'

# 多次 --tags 表示满足任意一组
bin/ckves run --tags 'domain:cpu,tier:smoke' --tags 'domain:ras,tier:smoke'

# 实时显示 Avocado 作业日志（单条用例的详细日志另见 debug.log）
bin/ckves run tests/cpu --show-job-log
```

结果默认写入 `results/`。高级 Avocado 参数可直接通过 `.venv/bin/avocado` 使用。

## 新增一个 case

1. 从 `tests/_template/test_feature.py.example` 复制模板到对应领域，并命名为 `test_<feature>.py`。
2. 测试类继承 `ckves.CKVESTest`，类名使用大驼峰格式，测试方法以 `test_` 开头。
3. 在类 docstring 中声明且只声明一组领域、环境、风险和层级标签。
4. 在 `setUp()` 中检查 root、CPU vendor、内核接口、命令或设备等前置条件；条件不满足时调用 `self.cancel()`。
5. 固定数据放入同名的 `<case>.py.data/` 目录。不要提交镜像、大型二进制、私钥、机器地址或内部下载链接。
6. 执行 `make check`，再在目标海光平台运行相关标签集合。

必需标签如下：

| 维度 | 允许值 |
| --- | --- |
| 领域 | `domain:cpu`、`domain:ras`、`domain:iommu`、`domain:virtualization`、`domain:security`、`domain:stability` |
| 环境 | `env:baremetal`、`env:guest`、`env:either` |
| 风险 | `risk:safe`、`risk:disruptive`、`risk:destructive` |
| 层级 | `tier:smoke`、`tier:functional`、`tier:stress` |

风险规则：

- `risk:safe`：只读或产生可自动清理的临时文件，可作为常规 CI 候选。
- `risk:disruptive`：可能改变 governor、模块、网络、设备绑定等运行状态，必须恢复现场并串行执行。
- `risk:destructive`：可能重启、触发故障注入或破坏数据，必须调用 `require_destructive_opt_in()`；只有设置 `CKVES_ALLOW_DESTRUCTIVE=1` 才能继续。

更完整的代码、参数、清理、结果和评审规则见 [tests/README.md](tests/README.md)。

## 开发与 CI 检查

```bash
# 检查用例规范和敏感信息，并运行框架单元测试
make check

# 只检查用例布局和元数据
make validate
```

建议 CI 分两层：普通 runner 执行 `make check`；受控海光裸机 runner 再执行 `bin/ckves run --tags 'tier:smoke,risk:safe'`。破坏性测试不得由普通提交流水线自动触发。


## 贡献与安全

提交补丁前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并执行：

```bash
make check
```

提交前必须确认代码、测试数据和日志可以公开，删除机器标识、账号、内部地址、固件包及受限文档内容。首次公开或迁仓前还应逐项完成 [公开发布检查清单](docs/publication-checklist.md)。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要在公开 Issue 中披露漏洞细节或有效凭据。

本项目采用 [Apache License 2.0](LICENSE) 许可。提交贡献表示你有权按该许可证提供相关内容；第三方代码、测试数据和文档必须保留来源与许可证信息。