CUDA C Programming Guide 在线教程学习笔记 Part 3

▶ 表面内存使用

● 创建 cuda 数组时使用标志 cudaArraySurfaceLoadStore 来创建表面内存，可以用表面对象（surface object）或表面引用（surface reference）来对其进行读写。

● 使用 Surface Object API

■ 涉及的结构定义、接口函数。

// vector_types.h
struct __device_builtin__ __align__(4) uchar4
{
    unsigned char x, y, z, w;
};

// surface_types.h
typedef __device_builtin__ unsigned long long cudaSurfaceObject_t;

■ 完整的测试代码，使用表面内存进行简单的读写。

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>
#include <cuda_runtime_api.h>
#include "device_launch_parameters.h"

#define CEIL(x,y) (((x) + (y) - 1) / (y) + 1)

__global__ void myKernel(cudaSurfaceObject_t inputSurfObj, cudaSurfaceObject_t outputSurfObj, int width, int height)
{
    unsigned int idx = blockIdx.x * blockDim.x + threadIdx.x;
    unsigned int idy = blockIdx.y * blockDim.y + threadIdx.y;
    if (idx < width && idy < height)
    {
        uchar4 data;
        // 简单的表面内存读写，使用了字节地址，而不是简单的线程编号
        surf2Dread(&data, inputSurfObj, sizeof(float) * idx, idy);
        surf2Dwrite(data, outputSurfObj, sizeof(float) * idx, idy);
    }
    cudaBindSurfaceToArray();
}

int main()
{
    // 基本数据
    int i;
    float *h_data, *d_data; 
    int width = 32;
    int height = 32;

    int size = sizeof(float)*width*height;
    h_data = (float *)malloc(size);
    cudaMalloc((void **)&d_data, size);

    for (i = 0; i < width*height; i++)
        h_data[i] = (float)i;

    printf("

");
    for (i = 0; i < width*height; i++)
    {
        printf("%6.1f ", h_data[i]);
        if ((i + 1) % width == 0)
            printf("
");
    }
    
    // 申请 cuda 数组
    cudaChannelFormatDesc channelDesc = cudaCreateChannelDesc(8, 8, 8, 8, cudaChannelFormatKindUnsigned);
    cudaArray* cuInputArray;
    cudaMallocArray(&cuInputArray, &channelDesc, width, height, cudaArraySurfaceLoadStore); 
    cudaArray* cuOutputArray;
    cudaMallocArray(&cuOutputArray, &channelDesc, width, height, cudaArraySurfaceLoadStore);
    cudaMemcpyToArray(cuInputArray, 0, 0, h_data, size,cudaMemcpyHostToDevice);

    // 指定表面内存
    struct cudaResourceDesc resDesc;
    memset(&resDesc, 0, sizeof(resDesc));
    resDesc.resType = cudaResourceTypeArray;

    // 创建表面对象
    resDesc.res.array.array = cuInputArray;
    cudaSurfaceObject_t inputSurfObj = 0;
    cudaCreateSurfaceObject(&inputSurfObj, &resDesc);
    resDesc.res.array.array = cuOutputArray;
    cudaSurfaceObject_t outputSurfObj = 0;
    cudaCreateSurfaceObject(&outputSurfObj, &resDesc);

    // 运行核函数
    dim3 dimBlock(16, 16);
    dim3 dimGrid(CEIL(width, dimBlock.x), CEIL(height, dimBlock.y));
    myKernel << <dimGrid, dimBlock >> > (inputSurfObj, outputSurfObj, width, height);

    // 结果回收和检查结果
    memset(h_data,0,size);// 刷掉原来的 h_data，再用 cuOutputArray 的数据写入     
    cudaMemcpyFromArray(h_data, cuOutputArray, 0, 0, size, cudaMemcpyDeviceToHost);

    printf("

");
    for (i = 0; i < width*height; i++)
    {
        printf("%6.1f ", h_data[i]);
        if ((i + 1) % width == 0)
            printf("
");
    }

    // 回收工作
    cudaDestroySurfaceObject(inputSurfObj);
    cudaDestroySurfaceObject(outputSurfObj);
    cudaFreeArray(cuInputArray);
    cudaFreeArray(cuOutputArray);

    getchar();
    return 0;
}

● 使用 Surface Reference API。

■ 表面引用的一些只读属性需要在声明的时候指定，以便编译时提前确定，只能在全局作用域内静态指定，不能作为参数传递给函数。使用 surface 指定纹理引用属性，Datatype 为数据类型，Type 为纹理引用类型，有 7 种，默认 cudaSurfaceType1D。

surface<void, Type> surfRef;

// cuda_texture_types.h
template<class T, int dim = 1>
struct __device_builtin_surface_type__ surface : public surfaceReference
{
#if !defined(__CUDACC_RTC__)
    __host__ surface(void)
    {
        channelDesc = cudaCreateChannelDesc<T>();
    }

    __host__ surface(struct cudaChannelFormatDesc desc)
    {
        channelDesc = desc;
    }
#endif /* !__CUDACC_RTC__ */  
};

//surface_types.h
#define cudaSurfaceType1D              0x01
#define cudaSurfaceType2D              0x02
#define cudaSurfaceType3D              0x03
#define cudaSurfaceTypeCubemap         0x0C
#define cudaSurfaceType1DLayered       0xF1
#define cudaSurfaceType2DLayered       0xF2
#define cudaSurfaceTypeCubemapLayered  0xFC

// 访问边界模式
enum __device_builtin__ cudaSurfaceBoundaryMode
{
    cudaBoundaryModeZero = 0,    // 0 边界模式
    cudaBoundaryModeClamp = 1,   // 挤压模式
    cudaBoundaryModeTrap = 2     // 陷阱模式
};

// ？表面格式模式
enum __device_builtin__  cudaSurfaceFormatMode
{
    cudaFormatModeForced = 0,   // 强制模式
    cudaFormatModeAuto = 1      // 自动模式
};

// 表面引用的通道描述
struct __device_builtin__ surfaceReference
{
    struct cudaChannelFormatDesc channelDesc;
};

// cuda_runtime_api.h
extern __host__ cudaError_t CUDARTAPI cudaBindSurfaceToArray(const struct surfaceReference *surfref, cudaArray_const_t array, const struct cudaChannelFormatDesc *desc);

■ 表面引用使用字节地址来定位访问（而不是像纹理那样使用 fetch 函数），如以上代码中 surf1Dread(surfRef, sizeof(float) * idx) 或是 surf1Dread(surfRef, sizeof(float) * idx) 。

■ 表面引用必须用函数 cudaBindSurfaceToArray() 绑定到 cuda 数组上才能使用，要求表面引用的维度、数据类型与该数组匹配，否则操作时未定义的，使用完后不需要特殊函数来解除绑定。

■ 将表面引用绑定到 cuda 数组上的范例代码。

// 准备工作
surface<void, Type>surfRef;

...

int width, height;
size_t pitch;
float *d_data;
cudaMallocPitch((void **)&d_data, &pitch, sizeof(float)*width, height);

// 第一种方法，低层 API
surfaceReference* surfRefPtr;
cudaGetSurfaceReference(&surfRefPtr, "surfRef");
cudaChannelFormatDesc channelDesc;
cudaGetChannelDesc(&channelDesc, cuArray);
cudaBindSurfaceToArray(surfRef, cuArray, &channelDesc);

// 第二种方法，高层 API
cudaBindSurfaceToArray(surfRef, cuArray);

■ 完整的应用样例代码。与前面表面对象代码的功能相同。

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>
#include <cuda_runtime_api.h>
#include "device_launch_parameters.h"

#define CEIL(x,y) (((x) + (y) - 1) / (y) + 1)

// 声明表面引用
surface<void, 2> inputSurfRef;
surface<void, 2> outputSurfRef;

__global__ void myKernel(int width, int height)
{
    unsigned int idx = blockIdx.x * blockDim.x + threadIdx.x;
    unsigned int idy = blockIdx.y * blockDim.y + threadIdx.y;
    if (idx < width && idy < height)
    {
        uchar4 data;
        // 简单的表面内存读写，使用了字节地址，而不是简单的线程编号
        surf2Dread(&data, inputSurfRef, sizeof(float) * idx, idy);
        surf2Dwrite(data, outputSurfRef, sizeof(float) * idx, idy);
    }
}

int main()
{
    // 基本数据
    int i;
    float *h_data, *d_data; 
    int width = 32;
    int height = 32;

    int size = sizeof(float)*width*height;
    h_data = (float *)malloc(size);
    cudaMalloc((void **)&d_data, size);

    for (i = 0; i < width*height; i++)
        h_data[i] = (float)i;

    printf("

");
    for (i = 0; i < width*height; i++)
    {
        printf("%6.1f ", h_data[i]);
        if ((i + 1) % width == 0)
            printf("
");
    }
    
    // 申请 cuda 数组
    cudaChannelFormatDesc channelDesc = cudaCreateChannelDesc(8, 8, 8, 8, cudaChannelFormatKindUnsigned);
    cudaArray* cuInputArray;
    cudaMallocArray(&cuInputArray, &channelDesc, width, height, cudaArraySurfaceLoadStore); 
    cudaArray* cuOutputArray;
    cudaMallocArray(&cuOutputArray, &channelDesc, width, height, cudaArraySurfaceLoadStore);
    cudaMemcpyToArray(cuInputArray, 0, 0, h_data, size,cudaMemcpyHostToDevice);

    // 绑定表面引用，注意与表面对象的使用不一样
    cudaBindSurfaceToArray(inputSurfRef, cuInputArray);
    cudaBindSurfaceToArray(outputSurfRef, cuOutputArray);

    // 运行核函数
    dim3 dimBlock(16, 16);
    dim3 dimGrid(CEIL(width, dimBlock.x), CEIL(height, dimBlock.y));
    myKernel << <dimGrid, dimBlock >> > (width, height);

    // 结果回收和检查结果
    memset(h_data,0,size);// 刷掉原来的 h_data，再用 cuOutputArray 的数据写入     
    cudaMemcpyFromArray(h_data, cuOutputArray, 0, 0, size, cudaMemcpyDeviceToHost);

    printf("

");
    for (i = 0; i < width*height; i++)
    {
        printf("%6.1f ", h_data[i]);
        if ((i + 1) % width == 0)
            printf("
");
    }

    // 回收工作
    cudaFreeArray(cuInputArray);
    cudaFreeArray(cuOutputArray);

    getchar();
    return 0;
}

▶ 立方体表面 Cubemap Surface 。 （想象成一个正方体的外表面）

● 一种特殊的二维分层表面。函数 surfCubemapread() 和函数 surfCubemapwrite() 来对其进行读写，使用一个整数下标和两个浮点数有序组来定义层号和表面坐标。

▶ 分层立方体表面 Cubemap Layered Surfaces 。（想象成一个多层的正方体的各外表面）

● 一种特殊的二维分层表面。函数 surfCubemapread() 和函数 surfCubemapwrite() 来对齐进行读写。使用一个整数下标和两个浮点数有序组来定义层号和表面坐标。

● 分层立方体贴图纹理只能使用函数 cudaMAlloc3DArray() 加上 cudaArrayLayered 和 cudaArrayCubemap 标志来声明，使用函数 texCubemapLayered() 来进行访问滤波只在同一层内部进行，不会跨层执行。

▶ cuda 数组。

● cuda 优化的数组类型，可以有一维或二维或三维，每个元素可以有 1 个或 2 个或 4 个分量，各分量可以是 1 B 或 2 B 或 4 B 尺寸的有符号或无符号整数，或 2 B 或 4 B 尺寸的浮点数。cuda 数组只能用纹理访问函数来访问，或表面函数来进行读写。

● 纹理内存和表面内存都是可缓存的，且不能保证缓存和内存的一致性。同一个核函数中，用纹理访问或表面访问来读取“已经全局写入或表面写入的内存”是未定义的。

▶ 压缩版的 surface_types.h

#if !defined(__SURFACE_TYPES_H__)
#define __SURFACE_TYPES_H__

#include "driver_types.h"

#define cudaSurfaceType1D              0x01
#define cudaSurfaceType2D              0x02
#define cudaSurfaceType3D              0x03
#define cudaSurfaceTypeCubemap         0x0C
#define cudaSurfaceType1DLayered       0xF1
#define cudaSurfaceType2DLayered       0xF2
#define cudaSurfaceTypeCubemapLayered  0xFC

//CUDA Surface boundary modes
enum __device_builtin__ cudaSurfaceBoundaryMode
{
    cudaBoundaryModeZero = 0,   // Zero boundary mode */
    cudaBoundaryModeClamp = 1,  // Clamp boundary mode */
    cudaBoundaryModeTrap = 2    // Trap boundary mode */
};

//CUDA Surface format modes
enum __device_builtin__  cudaSurfaceFormatMode
{
    cudaFormatModeForced = 0,   // Forced format mode */
    cudaFormatModeAuto = 1      // Auto format mode */
};

//CUDA Surface reference
struct __device_builtin__ surfaceReference
{
    // Channel descriptor for surface reference
    struct cudaChannelFormatDesc channelDesc;
};

//An opaque value that represents a CUDA Surface object
typedef __device_builtin__ unsigned long long cudaSurfaceObject_t;


#endif