第33章 Extensions - 扩展功能测试

33.1 概述

OpenCL扩展机制允许供应商和Khronos工作组引入新功能,而无需修改核心规范。扩展可以是供应商特定的,也可以是跨供应商的标准扩展(KHR扩展)。本章基于OpenCL-CTS test_conformance/extensions/ 测试源码,介绍主要扩展的功能和测试方法。

---

33.2 扩展查询

33.2.1 查询设备扩展

// 获取设备支持的扩展列表
char extensions[4096];
clGetDeviceInfo(device, CL_DEVICE_EXTENSIONS,
                sizeof(extensions), extensions, NULL);

printf("Device extensions:\n%s\n", extensions);

// 检查特定扩展
bool has_fp64 = strstr(extensions, "cl_khr_fp64") != NULL;
bool has_int64_atomics = strstr(extensions, "cl_khr_int64_base_atomics") != NULL;

33.2.2 OpenCL 3.0扩展查询

// 使用新的版本化查询API
cl_name_version device_extensions[100];
size_t num_extensions;

clGetDeviceInfo(device, CL_DEVICE_EXTENSIONS_WITH_VERSION,
                sizeof(device_extensions), device_extensions, &num_extensions);

num_extensions /= sizeof(cl_name_version);
for (size_t i = 0; i < num_extensions; i++) {
    printf("Extension: %s version %d.%d.%d\n",
           device_extensions[i].name,
           CL_VERSION_MAJOR(device_extensions[i].version),
           CL_VERSION_MINOR(device_extensions[i].version),
           CL_VERSION_PATCH(device_extensions[i].version));
}

---

33.3 重要KHR扩展

33.3.1 cl_khr_fp64 - 双精度浮点

功能: 启用64位双精度浮点支持。

查询支持:

if (strstr(extensions, "cl_khr_fp64") != NULL) {
    // 设备支持双精度
    cl_device_fp_config fp64_config;
    clGetDeviceInfo(device, CL_DEVICE_DOUBLE_FP_CONFIG,
                    sizeof(fp64_config), &fp64_config, NULL);
    
    if (fp64_config & CL_FP_FMA) {
        printf("Supports double-precision FMA\n");
    }
}

内核使用:

#pragma OPENCL EXTENSION cl_khr_fp64 : enable

__kernel void test_fp64(__global double* a,
                        __global double* b,
                        __global double* c)
{
    int gid = get_global_id(0);
    c[gid] = a[gid] * b[gid] + a[gid];  // 双精度计算
}

测试用例:

int test_fp64_extension(cl_device_id device, cl_context context)
{
    if (!is_extension_available(device, "cl_khr_fp64")) {
        log_info("cl_khr_fp64 not supported, skipping\n");
        return 0;
    }
    
    const char* source = 
        "#pragma OPENCL EXTENSION cl_khr_fp64 : enable\n"
        "__kernel void test(__global double* out) {\n"
        "    out[0] = 1.234567890123456789;\n"
        "}\n";
    
    cl_program program = clCreateProgramWithSource(context, 1, &source, NULL, NULL);
    cl_int err = clBuildProgram(program, 1, &device, NULL, NULL, NULL);
    
    if (err != CL_SUCCESS) {
        log_error("Failed to build fp64 kernel\n");
        return -1;
    }
    
    // 执行并验证精度
    // ...
    
    return 0;
}

33.3.2 cl_khr_command_buffer - 命令缓冲区

功能: 允许预先录制命令序列,提高命令提交效率。

创建命令缓冲区:

#include <CL/cl_ext.h>

// 创建可变命令缓冲区
cl_command_buffer_properties_khr props[] = {
    CL_COMMAND_BUFFER_FLAGS_KHR, CL_COMMAND_BUFFER_MUTABLE_KHR,
    0
};

cl_int err;
cl_command_buffer_khr cmd_buffer = 
    clCreateCommandBufferKHR(1, &queue, props, &err);

// 录制命令
clCommandNDRangeKernelKHR(cmd_buffer, NULL, NULL,
                          kernel, 1, NULL, &global_size, &local_size,
                          0, NULL, NULL, NULL);

clCommandCopyBufferKHR(cmd_buffer, NULL, queue,
                       src_buffer, dst_buffer, 0, 0, size,
                       0, NULL, NULL, NULL);

// 完成录制
clFinalizeCommandBufferKHR(cmd_buffer);

// 多次执行
for (int i = 0; i < 100; i++) {
    clEnqueueCommandBufferKHR(1, &queue, cmd_buffer, 0, NULL, NULL);
}

clReleaseCommandBufferKHR(cmd_buffer);

测试用例:

int test_command_buffer(cl_device_id device, cl_context context,
                       cl_command_queue queue)
{
    if (!is_extension_available(device, "cl_khr_command_buffer")) {
        return 0;
    }
    
    // 创建命令缓冲区
    cl_int err;
    cl_command_buffer_khr cmd_buf = clCreateCommandBufferKHR(1, &queue, NULL, &err);
    
    // 录制内核执行命令
    size_t global = 1024;
    clCommandNDRangeKernelKHR(cmd_buf, NULL, NULL, kernel, 1,
                             NULL, &global, NULL, 0, NULL, NULL, NULL);
    
    // 完成录制
    clFinalizeCommandBufferKHR(cmd_buf);
    
    // 执行多次
    for (int i = 0; i < 10; i++) {
        clEnqueueCommandBufferKHR(1, &queue, cmd_buf, 0, NULL, NULL);
    }
    clFinish(queue);
    
    // 验证结果
    // ...
    
    clReleaseCommandBufferKHR(cmd_buf);
    return 0;
}

33.3.3 cl_khr_semaphore - 信号量同步

功能: 提供跨设备和跨API的同步机制。

创建信号量:

// 创建OpenCL信号量
cl_semaphore_properties_khr props[] = {
    CL_SEMAPHORE_TYPE_KHR, CL_SEMAPHORE_TYPE_BINARY_KHR,
    0
};

cl_int err;
cl_semaphore_khr semaphore = clCreateSemaphoreWithPropertiesKHR(
    context, props, &err);

// 信号操作
clEnqueueSignalSemaphoresKHR(queue, 1, &semaphore,
                             NULL, 0, NULL, NULL);

// 等待操作
clEnqueueWaitSemaphoresKHR(queue, 1, &semaphore,
                           NULL, 0, NULL, NULL);

clReleaseSemaphoreKHR(semaphore);

跨设备同步:

// 设备1: 执行计算并发送信号
clEnqueueNDRangeKernel(queue1, kernel1, 1, NULL, &global, NULL,
                      0, NULL, NULL);
clEnqueueSignalSemaphoresKHR(queue1, 1, &semaphore, NULL, 0, NULL, NULL);

// 设备2: 等待信号后执行
clEnqueueWaitSemaphoresKHR(queue2, 1, &semaphore, NULL, 0, NULL, NULL);
clEnqueueNDRangeKernel(queue2, kernel2, 1, NULL, &global, NULL,
                      0, NULL, NULL);

33.3.4 cl_khr_external_semaphore - 外部信号量

功能: 与Vulkan、CUDA等外部API共享信号量。

导入外部信号量(Vulkan):

#ifdef _WIN32
    cl_semaphore_properties_khr props[] = {
        CL_SEMAPHORE_TYPE_KHR, CL_SEMAPHORE_TYPE_BINARY_KHR,
        CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR, (cl_semaphore_properties_khr)vk_semaphore_handle,
        0
    };
#else
    cl_semaphore_properties_khr props[] = {
        CL_SEMAPHORE_TYPE_KHR, CL_SEMAPHORE_TYPE_BINARY_KHR,
        CL_SEMAPHORE_HANDLE_OPAQUE_FD_KHR, (cl_semaphore_properties_khr)vk_semaphore_fd,
        0
    };
#endif

cl_semaphore_khr cl_sem = clCreateSemaphoreWithPropertiesKHR(context, props, &err);

// 在OpenCL中使用来自Vulkan的信号量
clEnqueueWaitSemaphoresKHR(queue, 1, &cl_sem, NULL, 0, NULL, NULL);
// 执行OpenCL工作
clEnqueueSignalSemaphoresKHR(queue, 1, &cl_sem, NULL, 0, NULL, NULL);

33.3.5 cl_ext_cxx_for_opencl - C++ for OpenCL

功能: 支持使用C++语法编写OpenCL内核。

C++ for OpenCL内核示例:

// 使用C++特性的内核
class Vector {
    float x, y, z;
public:
    Vector(float x, float y, float z) : x(x), y(y), z(z) {}
    
    float length() const {
        return sqrt(x*x + y*y + z*z);
    }
    
    Vector operator+(const Vector& other) const {
        return Vector(x + other.x, y + other.y, z + other.z);
    }
};

kernel void test_cpp_kernel(global float* output) {
    Vector v1(1.0f, 2.0f, 3.0f);
    Vector v2(4.0f, 5.0f, 6.0f);
    
    Vector v3 = v1 + v2;
    output[get_global_id(0)] = v3.length();
}

编译C++ for OpenCL:

const char* cpp_source = /* 上面的C++内核代码 */;

cl_program program = clCreateProgramWithSource(context, 1, &cpp_source, NULL, &err);

// 使用C++ for OpenCL编译选项
err = clBuildProgram(program, 1, &device, "-cl-std=clc++", NULL, NULL);

---

33.4 CTS测试目录

33.4.1 测试组织

test_conformance/extensions/
├── cl_ext_cxx_for_opencl/        # C++ for OpenCL测试
│   ├── main.cpp
│   ├── address_spaces.hpp
│   └── ...
├── cl_khr_command_buffer/        # 命令缓冲区测试
│   ├── main.cpp
│   ├── basic_command_buffer.cpp
│   ├── mutable_command_buffer.cpp
│   └── ...
├── cl_khr_semaphore/             # 信号量测试
│   ├── main.cpp
│   ├── test_semaphores.cpp
│   └── ...
├── cl_khr_external_semaphore/    # 外部信号量测试
└── cl_khr_dx9_media_sharing/     # DX9媒体共享测试

33.4.2 命令缓冲区测试

// test_conformance/extensions/cl_khr_command_buffer/basic_command_buffer.cpp

int test_basic_command_buffer(cl_device_id device, cl_context context,
                              cl_command_queue queue, int num_elements)
{
    // 检查扩展
    if (!is_extension_available(device, "cl_khr_command_buffer")) {
        log_info("cl_khr_command_buffer not supported\n");
        return TEST_SKIPPED_ITSELF;
    }
    
    // 创建命令缓冲区
    cl_int err;
    cl_command_buffer_khr cmd_buf = clCreateCommandBufferKHR(1, &queue, NULL, &err);
    test_error(err, "clCreateCommandBufferKHR failed");
    
    // 录制命令
    cl_mem buffer = clCreateBuffer(context, CL_MEM_READ_WRITE,
                                   num_elements * sizeof(cl_int), NULL, &err);
    
    cl_int pattern = 42;
    err = clCommandFillBufferKHR(cmd_buf, NULL, queue, buffer,
                                &pattern, sizeof(pattern), 0,
                                num_elements * sizeof(cl_int),
                                0, NULL, NULL, NULL);
    test_error(err, "clCommandFillBufferKHR failed");
    
    // 完成录制
    err = clFinalizeCommandBufferKHR(cmd_buf);
    test_error(err, "clFinalizeCommandBufferKHR failed");
    
    // 执行
    err = clEnqueueCommandBufferKHR(1, &queue, cmd_buf, 0, NULL, NULL);
    test_error(err, "clEnqueueCommandBufferKHR failed");
    
    clFinish(queue);
    
    // 验证结果
    cl_int* results = (cl_int*)malloc(num_elements * sizeof(cl_int));
    clEnqueueReadBuffer(queue, buffer, CL_TRUE, 0,
                       num_elements * sizeof(cl_int), results, 0, NULL, NULL);
    
    for (int i = 0; i < num_elements; i++) {
        if (results[i] != pattern) {
            log_error("Mismatch at %d: expected %d, got %d\n", i, pattern, results[i]);
            return TEST_FAIL;
        }
    }
    
    free(results);
    clReleaseMemObject(buffer);
    clReleaseCommandBufferKHR(cmd_buf);
    
    return TEST_PASS;
}

---

33.5 供应商扩展

33.5.1 NVIDIA扩展

cl_nv_device_attribute_query:

// 查询NVIDIA特定的设备属性
cl_uint warp_size;
clGetDeviceInfo(device, CL_DEVICE_WARP_SIZE_NV,
                sizeof(warp_size), &warp_size, NULL);
printf("NVIDIA warp size: %u\n", warp_size);

33.5.2 AMD扩展

cl_amd_device_attribute_query:

// 查询AMD特定属性
cl_uint wavefront_width;
clGetDeviceInfo(device, CL_DEVICE_WAVEFRONT_WIDTH_AMD,
                sizeof(wavefront_width), &wavefront_width, NULL);
printf("AMD wavefront width: %u\n", wavefront_width);

33.5.3 Intel扩展

cl_intel_advanced_motion_estimation:

// Intel的高级运动估计
#pragma OPENCL EXTENSION cl_intel_advanced_motion_estimation : enable

__kernel void motion_estimation(
    read_only image2d_t src_img,
    read_only image2d_t ref_img,
    sampler_t sampler,
    __global short2* motion_vectors)
{
    // 使用硬件加速的运动估计
    // ...
}

---

33.6 扩展开发指南

33.6.1 使用扩展的最佳实践

// 1. 检查扩展可用性
bool check_required_extensions(cl_device_id device) {
    char extensions[4096];
    clGetDeviceInfo(device, CL_DEVICE_EXTENSIONS,
                    sizeof(extensions), extensions, NULL);
    
    const char* required[] = {
        "cl_khr_fp64",
        "cl_khr_global_int32_base_atomics",
        NULL
    };
    
    for (int i = 0; required[i] != NULL; i++) {
        if (strstr(extensions, required[i]) == NULL) {
            log_error("Required extension not available: %s\n", required[i]);
            return false;
        }
    }
    return true;
}

// 2. 编译时启用扩展
const char* build_options = 
    "-cl-std=CL2.0 "
    "-D USE_FP64 ";

// 3. 内核中使用pragma
const char* kernel_source =
    "#ifdef USE_FP64\n"
    "#pragma OPENCL EXTENSION cl_khr_fp64 : enable\n"
    "#endif\n"
    "\n"
    "__kernel void my_kernel(...) {\n"
    "    // ...\n"
    "}\n";

33.6.2 跨平台兼容性

// 优雅降级策略
cl_program create_program_with_fallback(cl_context context, cl_device_id device) {
    // 尝试使用SPIR-V
    if (is_extension_available(device, "cl_khr_il_program")) {
        cl_program prog = clCreateProgramWithIL(context, spirv_binary, spirv_size, NULL);
        if (prog != NULL) {
            log_info("Using SPIR-V program\n");
            return prog;
        }
    }
    
    // 回退到OpenCL C
    log_info("Falling back to OpenCL C source\n");
    return clCreateProgramWithSource(context, 1, &source, NULL, NULL);
}

---

33.7 扩展测试方法

33.7.1 功能测试

int test_extension_functionality(const char* ext_name,
                                test_func_t test_func,
                                cl_device_id device,
                                cl_context context)
{
    // 检查扩展
    if (!is_extension_available(device, ext_name)) {
        log_info("Extension %s not available, skipping test\n", ext_name);
        return TEST_SKIPPED_ITSELF;
    }
    
    log_info("Testing extension: %s\n", ext_name);
    
    // 执行测试
    int result = test_func(device, context);
    
    if (result == TEST_PASS) {
        log_info("Extension %s test PASSED\n", ext_name);
    } else {
        log_error("Extension %s test FAILED\n", ext_name);
    }
    
    return result;
}

33.7.2 性能测试

// 测试扩展带来的性能提升
double benchmark_with_extension(cl_kernel kernel, cl_command_queue queue) {
    cl_event event;
    size_t global = 1000000;
    
    clEnqueueNDRangeKernel(queue, kernel, 1, NULL, &global, NULL,
                          0, NULL, &event);
    clWaitForEvents(1, &event);
    
    cl_ulong start, end;
    clGetEventProfilingInfo(event, CL_PROFILING_COMMAND_START,
                           sizeof(start), &start, NULL);
    clGetEventProfilingInfo(event, CL_PROFILING_COMMAND_END,
                           sizeof(end), &end, NULL);
    
    return (end - start) / 1000000.0;  // ms
}

void compare_performance() {
    double time_with_ext = benchmark_with_extension(kernel_ext, queue);
    double time_without_ext = benchmark_with_extension(kernel_base, queue);
    
    double speedup = time_without_ext / time_with_ext;
    printf("Speedup with extension: %.2fx\n", speedup);
}

---

33.8 总结

OpenCL扩展机制提供了强大的功能扩展能力:

1. 标准扩展(KHR): 跨供应商标准化功能
2. 供应商扩展: 硬件特定的优化功能
3. 实验性扩展(EXT): 候选标准功能

重要扩展:

• cl_khr_fp64: 双精度浮点
• cl_khr_command_buffer: 命令录制与重放
• cl_khr_semaphore: 同步原语
• cl_khr_external_semaphore: 跨API同步
• cl_ext_cxx_for_opencl: C++内核语法

最佳实践:

• 始终检查扩展可用性
• 提供回退方案确保兼容性
• 使用pragma启用内核扩展
• 测试覆盖功能和性能

CTS测试覆盖:

• 扩展功能正确性
• API行为验证
• 跨设备兼容性
• 性能特征测试

扩展机制使OpenCL能够快速演进,适应新硬件特性和应用需求,同时保持向后兼容性。