2.1 run_conformance.py - 自动化测试执行
run_conformance.py 是 OpenCL-CTS 的主要自动化测试脚本，用于批量执行测试套件并生成详细的测试报告。
2.1.1 脚本功能概述
该脚本提供以下核心功能：
- 从 CSV 配置文件批量加载测试用例
- 支持选择特定设备类型进行测试
- 提供测试名称过滤功能
- 自动生成带时间戳的日志文件
- 实时监控测试执行状态
- 捕获测试输出并进行结果统计
2.1.2 基本用法
命令行语法
python run_conformance.py <test_list> [device_types] [test_filters] [log=path]
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
test_list | CSV 格式的测试列表文件（必需） | opencl_conformance_tests_quick.csv |
device_types | 要测试的设备类型（可选） | CL_DEVICE_TYPE_GPU |
test_filters | 测试名称过滤器（可选） | basic api math |
log=path | 日志文件路径（可选） | log=./results/test.log |
使用示例
# 1. 运行快速测试套件（所有设备）
python run_conformance.py opencl_conformance_tests_quick.csv
# 2. 仅在 GPU 上运行测试
python run_conformance.py opencl_conformance_tests_full.csv CL_DEVICE_TYPE_GPU
# 3. 运行特定测试（名称包含 "basic" 或 "api"）
python run_conformance.py opencl_conformance_tests_quick.csv basic api
# 4. 指定日志文件路径
python run_conformance.py opencl_conformance_tests_quick.csv \
log=/home/user/test_results/run.log
# 5. CPU 和 GPU 组合测试，过滤数学测试
python run_conformance.py opencl_conformance_tests_full.csv \
CL_DEVICE_TYPE_CPU CL_DEVICE_TYPE_GPU math
2.1.3 核心函数解析
get_tests() - 加载测试列表
def get_tests(filename, devices_to_test):
"""
从 CSV 文件加载测试用例
参数:
filename: CSV 文件路径
devices_to_test: 要测试的设备类型列表
返回:
[(test_name, test_command), ...] 测试元组列表
"""
tests = []
file = open(filename, 'r')
for line in file.readlines():
# 跳过注释行
if line.startswith('#'):
continue
# 解析设备特定测试: device_type,test_name,test_command
device_specific_match = re.search(r"^\s*(.+?)\s*,\s*(.+?)\s*,\s*(.+?)\s*$", line)
if device_specific_match:
device_type = device_specific_match.group(1)
if device_type in devices_to_test:
test_name = device_specific_match.group(2)
test_path = device_specific_match.group(3)
tests.append((test_name, test_path))
continue
# 解析通用测试: test_name,test_command
match = re.search(r"^\s*(.+?)\s*,\s*(.+?)\s*$", line)
if match:
test_name = match.group(1)
test_path = match.group(2)
tests.append((test_name, test_path))
return tests
run_test_checking_output() - 执行单个测试
def run_test_checking_output(current_directory, test_dir, log_file):
"""
执行测试并监控输出
工作流程:
1. 创建临时文件捕获测试输出
2. 启动测试进程
3. 定期检查进程状态和输出
4. 记录测试结果到日志
"""
# 创建临时文件
(output_fd, output_name) = tempfile.mkstemp()
# 构建测试命令
program_to_run = test_dir.split(None, 1)[0]
if os.sep == '\\':
program_to_run += ".exe"
# 执行测试
p = subprocess.Popen(
current_directory + os.sep + test_dir,
stderr=output_fd,
stdout=output_fd,
shell=True
)
# 等待测试完成
p.wait()
# 读取测试输出
os.lseek(output_fd, 0, os.SEEK_SET)
output = os.read(output_fd, 1024 * 1024) # 最多读取 1MB
# 清理
os.close(output_fd)
os.remove(output_name)
return parse_test_result(output)
2.1.4 日志文件格式
脚本自动生成的日志文件名格式：
opencl_conformance_results_YYYY-MM-DD_HH-MM.log
日志内容示例：
========================================
OpenCL Conformance Test Run
Start Time: 16-Dec 14:30:25
========================================
Device Type: CL_DEVICE_TYPE_GPU
Test List: opencl_conformance_tests_quick.csv
----------------------------------------
Running Test: Compute Info
Command: computeinfo/test_computeinfo
Start: 16-Dec 14:30:26
----------------------------------------
PASSED 1 of 1 tests.
End: 16-Dec 14:30:27 (Duration: 1s)
----------------------------------------
Running Test: Basic
Command: basic/test_basic
Start: 16-Dec 14:30:27
----------------------------------------
PASSED 85 of 87 tests.
FAILED 2 of 87 tests.
Failed tests:
- test_fpmath_float: ULP error 4.5 > 4.0
- test_barrier: Timeout after 300s
End: 16-Dec 14:32:15 (Duration: 108s)
========================================
Test Run Summary
========================================
Total Tests: 12
Passed: 10
Failed: 2
Skipped: 0
Total Duration: 348s
End Time: 16-Dec 14:36:13
========================================
2.1.5 返回值说明
脚本根据测试结果返回不同的退出码：
| 退出码 | 含义 | 说明 |
|---|---|---|
| 0 | 全部通过 | 所有测试均通过 |
| -1 | 参数错误 | 命令行参数不正确 |
| 正整数 | 失败数量 | 等于失败的测试数量 |
2.2 generate_spirv_offline.py - SPIR-V 离线生成
该脚本用于预先将 OpenCL C 源代码编译为 SPIR-V 二进制格式，以便在测试中使用。
2.2.1 SPIR-V 离线编译概述
为什么需要离线编译？
- 性能优化：避免测试时重复编译相同的内核代码
- 二进制测试：验证 SPIR-V 二进制加载和执行功能
- 缓存管理：建立编译缓存目录结构
- 平台独立性：生成可在多设备间共享的中间表示
SPIR-V 介绍：
- SPIR-V（Standard Portable Intermediate Representation - V）
- Khronos 定义的跨 API 中间语言
- 支持 OpenCL、Vulkan 等多种图形和计算 API
- 提供更好的编译性能和工具链支持
2.2.2 基本用法
命令行语法
python generate_spirv_offline.py <compilation_cache_dir> <cl_device_info_file>
参数说明：
| 参数 | 说明 | 示例 |
|---|---|---|
compilation_cache_dir | 编译缓存目录 | ./spirv_cache |
cl_device_info_file | 设备信息文件 | device_info.txt |
使用示例
# 1. 基本用法
python generate_spirv_offline.py ./cache device_info.txt
# 2. 为特定设备生成
python generate_spirv_offline.py \
/tmp/spirv_compilation_cache \
/opt/rocm/share/device_info.json
# 3. 与测试流程集成
# 第一步：生成设备信息
clinfo --raw > device_info.txt
# 第二步：离线编译
python generate_spirv_offline.py ./spirv_cache device_info.txt
# 第三步：运行测试（使用预编译的 SPIR-V）
./test_spirv_new --use-cached-spirv ./spirv_cache
2.2.3 工作流程详解
流程图
┌─────────────────────┐
│ 扫描缓存目录 │
│ 查找 .cl 源文件 │
└──────────┬──────────┘
↓
┌─────────────────────┐
│ 读取编译选项 │
│ (.options 文件) │
└──────────┬──────────┘
↓
┌─────────────────────┐
│ 调用离线编译器 │
│ cl_offline_compiler│
└──────────┬──────────┘
↓
┌─────────────────────┐
│ 生成 .spv 文件 │
│ (SPIR-V 二进制) │
└─────────────────────┘
核心函数
def generate_spirv():
"""
遍历缓存目录，编译所有 .cl 文件为 .spv
"""
print("Generating SPIR-V files")
# 遍历缓存目录
for root, dirs, files in os.walk(compilation_cache_dir):
for file in files:
if file.endswith('.cl'):
# 查找对应的编译选项文件
options_file_name = file[:-2] + "options"
build_options = ''
if os.path.exists(os.path.join(root, options_file_name)):
with open(os.path.join(root, options_file_name), 'r') as f:
build_options = f.readline().strip()
# 构建输入输出路径
source_filename = os.path.join(root, file)
output_filename = os.path.join(root, file[:-2]) + "spv"
# 调用离线编译器
command_line = (
"cl_offline_compiler"
" --source=" + source_filename +
" --output=" + output_filename +
" --cl-device-info=" + cl_device_info_filename +
" --mode=spir-v -- " +
'"' + build_options + '"'
)
print(command_line)
os.system(command_line)
return 0
2.2.4 缓存目录结构
典型的编译缓存目录结构：
spirv_cache/
├── basic/
│ ├── kernel_add.cl # OpenCL C 源代码
│ ├── kernel_add.options # 编译选项
│ ├── kernel_add.spv # 生成的 SPIR-V 二进制
│ ├── kernel_sub.cl
│ ├── kernel_sub.options
│ └── kernel_sub.spv
├── math/
│ ├── test_sin.cl
│ ├── test_sin.options
│ ├── test_sin.spv
│ └── ...
└── images/
├── image_kernel.cl
├── image_kernel.options
└── image_kernel.spv
.options 文件格式
编译选项文件示例：
-cl-std=CL2.0 -cl-kernel-arg-info -cl-fast-relaxed-math
常用编译选项：
| 选项 | 说明 |
|---|---|
-cl-std=CL2.0 | 指定 OpenCL C 标准版本 |
-cl-kernel-arg-info | 保留内核参数信息 |
-cl-fast-relaxed-math | 启用快速数学优化 |
-cl-finite-math-only | 假设数学运算不产生 NaN/Inf |
-cl-unsafe-math-optimizations | 允许不安全的数学优化 |
2.2.5 设备信息文件
设备信息文件包含编译器所需的设备能力信息：
{
"device_name": "AMD Radeon RX 7900 XTX",
"device_version": "OpenCL 2.0",
"driver_version": "3.0.0",
"opencl_c_version": "OpenCL C 2.0",
"extensions": [
"cl_khr_fp64",
"cl_khr_int64_base_atomics",
"cl_khr_image2d_from_buffer"
],
"capabilities": {
"max_work_group_size": 1024,
"max_work_item_dimensions": 3,
"preferred_vector_width_float": 4
}
}
2.3 测试配置文件详解
OpenCL-CTS 提供多个预定义的测试配置文件，用于不同测试场景。
2.3.1 opencl_conformance_tests_quick.csv
用途：快速验证基本功能，适合持续集成（CI）环境
特点：
- 跳过长时间运行的图像测试
- 使用较短的数学测试
- 不运行类型转换测试
- 总运行时间约 10-30 分钟
测试内容：
# 基本信息查询
Compute Info,computeinfo/test_computeinfo
# 核心功能测试
Basic,basic/test_basic
API,api/test_api
Compiler,compiler/test_compiler
# 数学函数（简化版）
Common Functions,commonfns/test_commonfns
Geometric Functions,geometrics/test_geometrics
Relationals,relationals/test_relationals
# 线程维度测试（快速模式）
Thread Dimensions,thread_dimensions/test_thread_dimensions quick*
# 缓冲区和内存
Buffers,buffers/test_buffers
Allocations,allocations/test_allocations
# 原子操作
Atomics,atomics/test_atomics
# 性能分析
Profiling,profiling/test_profiling
# 事件处理
Events,events/test_events
2.3.2 opencl_conformance_tests_full.csv
用途：完整的一致性测试，用于官方认证
特点：
- 包含所有测试用例
- 完整的数学精度测试
- 全面的图像格式测试
- 总运行时间可能数小时
额外测试内容（相比 quick 版本）：
# 完整数学测试
Math Brute Force,math_brute_force/test_bruteforce
# 完整类型转换测试
Conversions,conversions/test_conversions
# 完整图像测试
Images (Full),images/test_images_full
# SVM 测试
SVM,SVM/test_SVM
# 子组测试
Subgroups,subgroups/test_subgroups
# 设备分区
Device Partition,device_partition/test_device_partition
# 设备端入队
Device Execution,device_execution/test_device_execution
# 管道
Pipes,pipes/test_pipes
# 扩展测试
Extensions,extensions/test_extensions
2.3.3 opencl_conformance_tests_math.csv
用途：专门测试数学函数精度
特点：
- 仅包含数学相关测试
- 详细的 ULP 精度验证
- 支持单精度、双精度测试
- 可指定测试线程数
测试内容：
# 暴力数学测试（单精度）
Math Brute Force Float,math_brute_force/test_bruteforce --float
# 暴力数学测试（双精度）
Math Brute Force Double,math_brute_force/test_bruteforce --double
# 通用数学函数
Common Functions,commonfns/test_commonfns
# 几何函数
Geometric Functions,geometrics/test_geometrics
# 半精度浮点
Half,half/test_half
2.3.4 opencl_conformance_tests_conversions.csv
用途：类型转换测试
特点：
- 测试所有数值类型转换
- 验证舍入模式
- 检查饱和转换
- 运行时间较长
测试内容：
# 完整转换测试
Conversions,conversions/test_conversions
# 向量类型转换
Vector Conversions,conversions/test_conversions --vector
# 标量类型转换
Scalar Conversions,conversions/test_conversions --scalar
2.3.5 opencl_conformance_tests_full_spirv.csv
用途：SPIR-V 相关测试
特点：
- 测试 SPIR-V 加载和执行
- 验证 SPIR-V 扩展
- 测试特殊化常量
测试内容：
# SPIR-V 基础测试
SPIRV New,spirv_new/test_spirv_new
# SPIR-V 扩展
SPIRV Extensions,spirv_new/test_spirv_new --extensions
# 特殊化常量
SPIRV Specialization,spirv_new/test_spirv_new --specialization
2.3.6 设备特定配置
某些测试可以指定设备类型：
# 语法：device_type,test_name,test_command
# 仅在 GPU 上运行
CL_DEVICE_TYPE_GPU,GPU Specific Test,gpu_tests/test_gpu_only
# 仅在 CPU 上运行
CL_DEVICE_TYPE_CPU,CPU Specific Test,cpu_tests/test_cpu_only
# CPU 和 GPU 都运行（不同命令）
CL_DEVICE_TYPE_CPU,Integer Math,integer_ops/test_integer --cpu-mode
CL_DEVICE_TYPE_GPU,Integer Math,integer_ops/test_integer --gpu-mode
2.3.7 自定义测试配置
创建自定义测试配置文件：
# my_custom_tests.csv
# 注释行以 # 开头
# 基本功能
Basic Tests,basic/test_basic hostptr fpmath_float
# 仅测试原子操作
Atomic Add,atomics/test_atomics add
Atomic Exchange,atomics/test_atomics exchange
# 指定测试参数
Math Sin,math_brute_force/test_bruteforce sin --ulp 4.0
Math Cos,math_brute_force/test_bruteforce cos --ulp 4.0
# GPU 特定测试
CL_DEVICE_TYPE_GPU,Images,images/test_images --format=all
运行自定义配置：
python run_conformance.py my_custom_tests.csv
2.3.8 配置文件最佳实践
1. 分层配置策略
quick.csv → 基础功能 (10-30分钟)
↓
standard.csv → 常规测试 (1-2小时)
↓
full.csv → 完整测试 (数小时)
↓
certification.csv → 官方认证 (包含所有可选测试)
2. 持续集成配置
# ci_smoke_test.csv - 快速冒烟测试 (5分钟)
Compute Info,computeinfo/test_computeinfo
Basic Quick,basic/test_basic hostptr fpmath_float
API Quick,api/test_api min_max_*
3. 回归测试配置
# regression_tests.csv - 针对已知问题的回归测试
Issue #1234,basic/test_basic barrier
Issue #1235,atomics/test_atomics cmpxchg
Issue #1236,images/test_images read_write_2d
本章小结
第2章详细介绍了 OpenCL-CTS 的测试工具与脚本：
-
run_conformance.py：自动化测试执行的核心工具
- 支持批量测试、设备过滤、结果统计
- 生成详细的带时间戳日志
-
generate_spirv_offline.py：SPIR-V 离线编译工具
- 预编译内核代码提升测试性能
- 支持缓存管理和设备信息配置
-
测试配置文件：灵活的测试组合
- quick: 快速验证（CI 友好）
- full: 完整测试（官方认证）
- math/conversions: 专项测试
- 支持自定义配置
掌握这些工具是高效使用 OpenCL-CTS 的关键。下一章将深入 Basic 测试套件的具体用例。
扫一扫
728
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
