| name | cuda-c-api |
| description | CUDA C 编程接口完整参考手册 |
| category | fundamental |
| version | 1.0.0 |
| metadata | {"backend":"cuda","dsl":"cuda_c"} |
CUDA C API 参考手册
本文档提供 CUDA C 核心编程接口的详细参考,包括函数签名、参数说明和使用示例。
1. 函数修饰符
global
__global__ void kernel_function(参数列表);
- 功能: 标记为可在 GPU 上执行的内核函数
- 调用: 只能从主机代码调用,使用
<<<>>> 语法启动
- 返回值: 必须为
void
device
__device__ float device_function(参数列表);
- 功能: 标记为在 GPU 上执行的设备函数
- 调用: 只能从其他
__device__ 或 __global__ 函数调用
- 用途: 内核内部的辅助函数
host
__host__ void host_function(参数列表);
- 功能: 标记为在 CPU 上执行的函数(默认)
- 调用: 只能从主机代码调用
host device
__host__ __device__ float utility_function(float x);
- 功能: 同时在 CPU 和 GPU 上可用
- 用途: 通用工具函数
2. 内存类型修饰符
shared
__shared__ float shared_memory[256];
- 功能: 声明线程块内共享的内存
- 生命周期: 与线程块相同
- 访问: 块内所有线程可读写
- 容量: 通常 48-164 KB/SM
constant
__constant__ float constant_data[64];
- 功能: 声明只读的常量内存
- 特点: 缓存优化,适合广播读取
- 设置: 通过
cudaMemcpyToSymbol 从主机端设置
extern shared
extern __shared__ float dynamic_shared[];
- 功能: 动态分配的共享内存
- 大小: 在内核启动时通过第三个参数指定
- 启动:
kernel<<<grid, block, shared_mem_bytes>>>(args)
3. 内核启动语法
基本语法
kernel_name<<<grid_size, block_size>>>(参数列表);
kernel_name<<<grid_size, block_size, shared_mem_bytes>>>(参数列表);
kernel_name<<<grid_size, block_size, shared_mem_bytes, stream>>>(参数列表);
- grid_size: 网格大小(
int 或 dim3)
- block_size: 线程块大小(
int 或 dim3)
- shared_mem_bytes: 动态共享内存大小(可选,默认 0)
- stream: CUDA 流(可选,默认 0)
dim3 类型
dim3 grid_size(blocks_x, blocks_y, blocks_z);
dim3 block_size(threads_x, threads_y, threads_z);
- 用途: 多维网格和线程块配置
- 默认: 未指定的维度默认为 1
4. 线程和块索引系统
块索引变量
int bx = blockIdx.x; // X 方向块索引
int by = blockIdx.y; // Y 方向块索引
int bz = blockIdx.z; // Z 方向块索引
- 类型:
uint3
- 用途: 确定当前线程块在网格中的位置
线程索引变量
int tx = threadIdx.x; // X 方向线程索引
int ty = threadIdx.y; // Y 方向线程索引
int tz = threadIdx.z; // Z 方向线程索引
- 类型:
uint3
- 用途: 确定当前线程在线程块中的位置
块维度信息
int bdx = blockDim.x; // X 方向线程数
int bdy = blockDim.y; // Y 方向线程数
int bdz = blockDim.z; // Z 方向线程数
网格维度信息
int gdx = gridDim.x; // X 方向块数
int gdy = gridDim.y; // Y 方向块数
int gdz = gridDim.z; // Z 方向块数
5. 内存管理 API
cudaMalloc(devPtr, size)
float* d_data;
cudaMalloc(&d_data, n * sizeof(float));
- 参数: 设备指针的地址, 分配字节数
- 返回:
cudaError_t 错误状态码
- 功能: 在 GPU 上分配全局内存
cudaFree(devPtr)
cudaFree(d_data);
- 参数: 设备内存指针
- 返回:
cudaError_t 错误状态码
- 功能: 释放 GPU 全局内存
cudaMemcpy(dst, src, count, kind)
// 主机 → 设备
cudaMemcpy(d_data, h_data, size, cudaMemcpyHostToDevice);
// 设备 → 主机
cudaMemcpy(h_data, d_data, size, cudaMemcpyDeviceToHost);
// 设备 → 设备
cudaMemcpy(d_dst, d_src, size, cudaMemcpyDeviceToDevice);
- 参数: 目标指针, 源指针, 字节数, 传输方向
- 返回:
cudaError_t 错误状态码
- 传输方向:
cudaMemcpyHostToDevice: H2D
cudaMemcpyDeviceToHost: D2H
cudaMemcpyDeviceToDevice: D2D
cudaMemset(devPtr, value, count)
cudaMemset(d_data, 0, n * sizeof(float));
- 参数: 设备指针, 填充值(按字节), 字节数
- 功能: 将设备内存设为指定值
6. 线程同步机制
__syncthreads()
__syncthreads();
- 功能: 等待块内所有线程到达同步点
- 用途: 确保共享内存数据一致性
- ⚠️ 注意: 块内所有线程都必须执行到此同步点,否则导致死锁
__threadfence()
__threadfence();
- 功能: 确保当前线程的内存写入对所有线程全局可见
- 用途: 跨线程块的数据可见性保证
__threadfence_block()
__threadfence_block();
- 功能: 确保当前线程的内存写入对同块线程可见
- 用途: 块内的内存可见性保证
7. 原子操作 API
atomicAdd(address, val)
atomicAdd(&output[0], local_sum);
- 功能: 线程安全的加法操作
- 支持类型:
int, unsigned int, float, double(Compute Capability 6.0+)
atomicMax / atomicMin
atomicMax(&max_val, local_max);
atomicMin(&min_val, local_min);
- 功能: 线程安全的最大值/最小值更新
- 支持类型:
int, unsigned int
atomicCAS(address, compare, val)
int old = atomicCAS(&target, expected, desired);
- 功能: 比较并交换(Compare-And-Swap)
- 返回: 原始值
atomicExch(address, val)
float old = atomicExch(&target, new_value);
8. 数学运算函数
标准数学函数
float max_val = fmaxf(a, b); // 最大值
float min_val = fminf(a, b); // 最小值
float abs_val = fabsf(x); // 绝对值
float sqrt_val = sqrtf(x); // 平方根
float rsqrt_val = rsqrtf(x); // 平方根倒数
float exp_val = expf(x); // 指数
float log_val = logf(x); // 自然对数
float pow_val = powf(base, exp); // 幂运算
float ceil_val = ceilf(x); // 向上取整
float floor_val = floorf(x); // 向下取整
快速数学函数(精度略低但速度更快)
float fast_exp = __expf(x); // 快速指数
float fast_log = __logf(x); // 快速对数
float fast_sin = __sinf(x); // 快速正弦
float fast_cos = __cosf(x); // 快速余弦
float fast_pow = __powf(b, e); // 快速幂运算
类型转换
float f = __int2float_rn(i); // int → float(最近舍入)
int i = __float2int_rn(f); // float → int(最近舍入)
9. Warp 级操作(Compute Capability 3.0+)
__shfl_sync / __shfl_down_sync
// Warp 内数据交换
float val = __shfl_sync(0xFFFFFFFF, src_val, src_lane);
// Warp 内归约
float val = __shfl_down_sync(0xFFFFFFFF, src_val, offset);
- 功能: Warp 内线程间直接数据交换
- 参数: mask(参与线程掩码), 源值, 源 lane / 偏移量
10. PyTorch 集成 API
torch::Tensor 操作
// 在 CUDA 源代码中使用 PyTorch 接口
torch::Tensor my_op(torch::Tensor input) {
auto size = input.numel();
auto output = torch::zeros_like(input);
int block_size = 256;
int num_blocks = (size + block_size - 1) / block_size;
my_kernel<<<num_blocks, block_size>>>(
input.data_ptr<float>(),
output.data_ptr<float>(),
size
);
return output;
}
常用 torch::Tensor 方法
input.numel() // 元素总数
input.size(dim) // 指定维度大小
input.data_ptr<float>() // 获取数据指针
torch::zeros_like(input) // 创建同形状零张量
torch::empty_like(input) // 创建同形状未初始化张量
使用建议
- 边界检查: 所有数组访问前必须检查边界
- 原子操作: 仅在必要时使用,有性能开销
- 快速数学函数: 精度要求不高时使用
__expf 等加速
- 共享内存: 使用前后必须
__syncthreads() 同步
- 错误检查: 每个 CUDA API 调用后检查返回值
- 内存对齐: 确保数据按合适边界对齐(128 字节)