📚 课程目录第4章运行时API概览

运行时API概览：初始化、设备管理、上下文、模块加载

CUDA 运行时 API（Runtime API）是英伟达 GPU 编程中最常用的用户态接口层。与驱动 API（Driver API）相比，运行时 API 封装了更多底层细节，提供更简洁的编程模型。理解运行时 API 的四大核心域——初始化、设备管理、上下文与模块加载——是掌握 GPU 内核调度与资源管理的基础。本节将逐一剖析这些 API 的底层行为与调用逻辑。

核心原理：运行时 API 的分层与惰性初始化

运行时 API 并非独立于驱动 API 的平行体系，而是构建在驱动 API 之上的封装层。每个运行时 API 调用最终都会映射到 libcuda.so（Linux）或 nvcuda.dll（Windows）中的驱动函数。关键设计在于惰性初始化机制：首次调用任何运行时 API 时，运行时环境才会完成以下初始化序列：

加载驱动库并建立函数指针表。
创建 CUDA 驱动上下文（若不存在）。
初始化主上下文（Primary Context）并绑定到当前线程。
建立设备与主机之间的内存映射基础设施。

这一机制意味着 cudaSetDevice() 并非真正“切换设备”，而是触发或切换线程绑定的主上下文。理解这一点对排查多线程与多 GPU 场景下的资源竞争至关重要。

关键认知：运行时 API 的上下文管理是“隐式”的，每个线程在首次调用时自动绑定主上下文。若需要细粒度控制（如多上下文隔离），必须使用驱动 API 的 cuCtxCreate() 显式管理。

初始化与设备管理：从查询到绑定

设备管理是运行时 API 中最常用的功能集合。核心调用链如下：

// 1. 查询设备数量与能力
int deviceCount;
cudaGetDeviceCount(&deviceCount);

cudaDeviceProp prop;
cudaGetDeviceProperties(&prop, 0);  // 查询设备0属性

// 2. 选择计算设备
cudaSetDevice(0);   // 绑定设备0到当前线程

// 3. 获取当前设备
int currentDevice;
cudaGetDevice(&currentDevice);

// 4. 重置设备（释放所有资源）
cudaDeviceReset();

设备管理的关键参数与属性如下表所示：

API 函数	作用	底层行为
`cudaGetDeviceCount()`	获取可用 GPU 数量	查询 NVML 或驱动枚举 PCI 设备
`cudaSetDevice()`	选择当前线程的计算设备	切换线程绑定的主上下文
`cudaGetDeviceProperties()`	获取设备算力、显存、SM 数量等	填充 `cudaDeviceProp` 结构体
`cudaDeviceReset()`	销毁当前设备上的所有资源	隐式同步并释放主上下文、显存、事件等
`cudaDeviceSynchronize()`	阻塞主机直到设备完成所有任务	向驱动发送同步屏障指令

常见陷阱：cudaDeviceReset() 会销毁当前线程主上下文中的所有资源，包括已分配的显存、加载的模块和创建的流。若其他线程仍在使用该设备上的资源，将导致未定义行为。多线程场景下务必谨慎调用。

上下文管理：隐式主上下文与线程绑定

运行时 API 的上下文管理遵循“每线程主上下文”模型。每个 CPU 线程在首次调用运行时 API 时，会创建一个与该线程绑定的主上下文（Primary Context）。该上下文由运行时自动管理，无需显式创建或销毁。

上下文的核心作用包括：

资源隔离：不同线程的上下文拥有独立的显存分配、模块句柄和事件对象。
调度绑定：内核启动命令通过上下文提交到 GPU 前端队列。
错误传播：异步错误（如非法内存访问）与上下文关联，通过 cudaGetLastError() 查询。

运行时 API 提供 cudaCtxCreate() 和 cudaCtxDestroy() 的封装版本，但更常用的是隐式管理。当需要多上下文隔离时（例如在同一线程中运行两个独立 CUDA 应用），必须使用驱动 API 的 cuCtxCreate() 显式压入/弹出上下文栈。

模块加载：从 cubin 到内核句柄

模块（Module）是 CUDA 中承载内核代码与全局符号的容器。运行时 API 的模块加载通常通过 cudaLaunchKernel() 隐式完成，但理解底层加载流程对调试和性能优化至关重要。

典型加载流程如下：

// 方式一：运行时隐式加载（推荐）
myKernel<<<grid, block>>>(args);  // 编译时嵌入 cubin

// 方式二：显式加载 PTX/cubin 文件
CUmodule module;
cuModuleLoad(&module, "kernel.cubin");  // 驱动 API

CUfunction kernel;
cuModuleGetFunction(&kernel, module, "myKernel");

// 方式三：运行时 API 加载（需配合驱动）
cudaModuleLoad(&module, "kernel.ptx");  // 运行时封装

模块加载的内部步骤包括：

解析二进制：驱动读取 cubin/PTX 文件头，验证架构兼容性（如 sm_80 vs sm_86）。
JIT 编译（若需要）：当 PTX 需要适配不同架构时，驱动调用 NVIDIA 编译器库（NVRTC）生成 SASS。
符号解析：将内核函数名映射到 GPU 代码段地址，建立全局符号表。
常量与全局变量绑定：将 __constant__ 和 __device__ 变量映射到显存地址。

  性能提示：模块加载是重量级操作（可能耗时数十毫秒）。在延迟敏感的应用中，应避免频繁加载/卸载模块。推荐将多个内核打包到同一 cubin 文件中，并在初始化阶段一次性加载。

案例：多 GPU 初始化与模块加载的完整流程

以下代码展示了一个典型的多 GPU 初始化与内核加载场景：

// 初始化阶段
int deviceCount;
cudaGetDeviceCount(&deviceCount);
if (deviceCount < 2) { /* 错误处理 */ }

// 为每个设备创建独立流
cudaStream_t streams[2];
for (int i = 0; i < 2; i++) {
    cudaSetDevice(i);
    cudaStreamCreate(&streams[i]);
}

// 加载模块（假设已编译 kernel.cubin）
CUmodule module;
cuModuleLoad(&module, "kernel.cubin");
CUfunction kernel;
cuModuleGetFunction(&kernel, module, "vectorAdd");

// 在设备0上启动内核
cudaSetDevice(0);
void* args[] = { &d_A0, &d_B0, &d_C0, &n };
cuLaunchKernel(kernel, grid, block, args, 0, streams[0]);

// 在设备1上启动内核
cudaSetDevice(1);
void* args1[] = { &d_A1, &d_B1, &d_C1, &n };
cuLaunchKernel(kernel, grid, block, args1, 0, streams[1]);

// 同步并清理
cudaDeviceSynchronize();
cuModuleUnload(module);

该案例展示了运行时 API 与驱动 API 的混合使用：设备管理与流操作使用运行时 API，而模块加载与内核启动使用驱动 API。这种混合模式在需要精细控制模块生命周期时非常常见。

误区与复盘：运行时 API 的常见错误

误区一：忽略错误返回值。大多数运行时 API 返回 cudaError_t，但开发者常忽略检查。例如 cudaSetDevice() 失败时，后续所有调用都会在错误设备上执行，导致难以排查的隐性错误。正确做法是使用 cudaGetLastError() 或封装宏统一检查。

误区二：混淆设备重置与上下文销毁。cudaDeviceReset() 会销毁当前线程的主上下文，但不会影响其他线程的上下文。若在多线程程序中调用，可能导致其他线程的上下文失效。应使用 cudaSetDevice() 切换设备，而非频繁重置。

误区三：模块加载后立即卸载。若内核仍在 GPU 上执行，卸载模块会导致未定义行为。必须确保所有依赖该模块的内核已完成（通过 cudaDeviceSynchronize() 或流同步），才能安全卸载。

复盘上述问题，核心教训是：运行时 API 的隐式管理虽然便捷，但要求开发者理解其底层状态机。初始化、设备绑定、上下文切换与模块生命周期之间存在严格的时序依赖，任何一步的疏忽都可能导致资源泄漏或程序崩溃。建议在工程实践中建立统一的错误处理宏与资源管理 RAII 类，确保每个 API 调用的返回值都被检查，每个资源都有明确的释放路径。

上图总结了运行时 API 四大核心域之间的调用顺序与资源绑定关系。初始化阶段触发惰性初始化，设备管理确定线程绑定的主上下文，上下文管理提供资源隔离，模块加载将内核代码映射到 GPU 地址空间。底部列出了开发中最常见的四类错误路径，这些错误均源于对隐式状态转换的忽视。

在实际工程中，建议将初始化、设备选择与模块加载封装为独立的初始化类，并在程序入口处统一完成。同时，利用 cudaGetLastError() 与 cudaPeekAtLastError() 区分同步与异步错误，确保每个 API 调用的返回值都被检查。只有深入理解运行时 API 的底层状态机，才能编写出健壮、可扩展的 CUDA 应用程序。