CUDA 驱动程序 API :: CUDA 工具包文档

6.10. 模块管理

本节介绍底层 CUDA 驱动程序应用程序编程接口的模块管理功能。

枚举

enum CUmoduleLoadingMode

函数

CUresult cuLinkAddData ( CUlinkState state, CUjitInputType type, void* data, size_t size, const char* name, unsigned int numOptions, CUjit_option* options, void** optionValues ): 向待处理的链接器调用添加输入。
CUresult cuLinkAddFile ( CUlinkState state, CUjitInputType type, const char* path, unsigned int numOptions, CUjit_option* options, void** optionValues ): 向待处理的链接器调用添加文件输入。
CUresult cuLinkComplete ( CUlinkState state, void** cubinOut, size_t* sizeOut ): 完成待处理的链接器调用。
CUresult cuLinkCreate ( unsigned int numOptions, CUjit_option* options, void** optionValues, CUlinkState* stateOut ): 创建待处理的 JIT 链接器调用。
CUresult cuLinkDestroy ( CUlinkState state ): 销毁 JIT 链接器调用的状态。
CUresult cuModuleEnumerateFunctions ( CUfunction* functions, unsigned int numFunctions, CUmodule mod ): 返回模块内的函数句柄。
CUresult cuModuleGetFunction ( CUfunction* hfunc, CUmodule hmod, const char* name ): 返回函数句柄。
CUresult cuModuleGetFunctionCount ( unsigned int* count, CUmodule mod ): 返回模块内的函数数量。
CUresult cuModuleGetGlobal ( CUdeviceptr* dptr, size_t* bytes, CUmodule hmod, const char* name ): 从模块返回全局指针。
CUresult cuModuleGetLoadingMode ( CUmoduleLoadingMode* mode ): 查询延迟加载模式。
CUresult cuModuleLoad ( CUmodule* module, const char* fname ): 加载计算模块。
CUresult cuModuleLoadData ( CUmodule* module, const void* image ): 加载模块的数据。
CUresult cuModuleLoadDataEx ( CUmodule* module, const void* image, unsigned int numOptions, CUjit_option* options, void** optionValues ): 使用选项加载模块的数据。
CUresult cuModuleLoadFatBinary ( CUmodule* module, const void* fatCubin ): 加载模块的数据。
CUresult cuModuleUnload ( CUmodule hmod ): 卸载模块。

枚举

enum CUmoduleLoadingMode

CUDA 延迟加载状态

值

CU_MODULE_EAGER_LOADING = 0x1: 未启用延迟内核加载
CU_MODULE_LAZY_LOADING = 0x2: 已启用延迟内核加载

函数

CUresult cuLinkAddData ( CUlinkState state, CUjitInputType type, void* data, size_t size, const char* name, unsigned int numOptions, CUjit_option* options, void** optionValues )

向待处理的链接器调用添加输入。

参数

state: 待处理的链接器操作。
type: 输入数据的类型。
data: 输入数据。PTX 必须以 NULL 结尾。
size: 输入数据的长度。
name: 日志消息中此输入的可选名称。
numOptions: 选项的大小。
options: 仅应用于此输入的选项（覆盖来自 cuLinkCreate 的选项）。
optionValues: 选项值数组，每个都强制转换为 void *。

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_IMAGE, CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_NO_BINARY_FOR_GPU

描述

的所有权data由调用者保留。在此调用返回后，不保留对任何输入的引用。

此方法仅接受编译器选项，这些选项在必须从 PTX 编译数据时使用，并且不接受 CU_JIT_WALL_TIME, CU_JIT_INFO_LOG_BUFFER, CU_JIT_ERROR_LOG_BUFFER, CU_JIT_TARGET_FROM_CUCONTEXT 或 CU_JIT_TARGET 中的任何一个。

注意

对于 LTO-IR 输入，仅接受使用 CUDA 12.0 之前的工具包编译的 LTO-IR

另请参阅

cuLinkCreate, cuLinkAddFile, cuLinkComplete, cuLinkDestroy

CUresult cuLinkAddFile ( CUlinkState state, CUjitInputType type, const char* path, unsigned int numOptions, CUjit_option* options, void** optionValues )

向待处理的链接器调用添加文件输入。

参数

state: 待处理的链接器操作
type: 输入数据的类型
path: 输入文件的路径
numOptions: 选项的大小
options: 仅应用于此输入的选项（覆盖来自 cuLinkCreate 的选项）
optionValues: 选项值数组，每个都强制转换为 void *

CUDA_SUCCESS, CUDA_ERROR_FILE_NOT_FOUND CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_IMAGE, CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_NO_BINARY_FOR_GPU

描述

在此调用返回后，不保留对任何输入的引用。

此方法仅接受编译器选项，这些选项在输入必须从 PTX 编译时使用，并且不接受 CU_JIT_WALL_TIME, CU_JIT_INFO_LOG_BUFFER, CU_JIT_ERROR_LOG_BUFFER, CU_JIT_TARGET_FROM_CUCONTEXT 或 CU_JIT_TARGET 中的任何一个。

此方法等效于对文件内容调用 cuLinkAddData。

注意

对于 LTO-IR 输入，仅接受使用 CUDA 12.0 之前的工具包编译的 LTO-IR

另请参阅

cuLinkCreate, cuLinkAddData, cuLinkComplete, cuLinkDestroy

CUresult cuLinkComplete ( CUlinkState state, void** cubinOut, size_t* sizeOut )

完成待处理的链接器调用。

参数

state: 待处理的链接器调用
cubinOut: 成功后，这将指向输出图像
sizeOut: 可选参数，用于接收生成的图像大小

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY

描述

完成待处理的链接器操作，并返回链接设备代码的 cubin 图像，该图像可与 cuModuleLoadData 一起使用。cubin 归state所有，因此应在state通过 cuLinkDestroy 销毁之前加载。此调用不会销毁state.

另请参阅

cuLinkCreate, cuLinkAddData, cuLinkAddFile, cuLinkDestroy, cuModuleLoadData

CUresult cuLinkCreate ( unsigned int numOptions, CUjit_option* options, void** optionValues, CUlinkState* stateOut )

创建待处理的 JIT 链接器调用。

参数

numOptions: 选项数组的大小
options: 链接器和编译器选项数组
optionValues: 选项值数组，每个都强制转换为 void *
stateOut: 成功后，这将包含一个 CUlinkState 以指定和完成此操作

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_JIT_COMPILER_NOT_FOUND

描述

如果调用成功，则调用者拥有返回的 CUlinkState，最终应使用 cuLinkDestroy 销毁。设备代码机器大小（32 位或 64 位）将与调用应用程序匹配。

可以指定链接器和编译器选项。编译器选项将应用于必须从 PTX 编译的此链接器操作的输入。选项 CU_JIT_WALL_TIME, CU_JIT_INFO_LOG_BUFFER_SIZE_BYTES 和 CU_JIT_ERROR_LOG_BUFFER_SIZE_BYTES 将累积数据，直到 CUlinkState 被销毁。

通过 cuLinkAddData 和 cuLinkAddFile 传入的数据在 cuLinkComplete 期间链接最终 cubin 时将被视为可重定位的（-rdc=true 到 nvcc），并且将具有与离线可重定位设备代码链接类似的后果。

optionValues如果使用输出选项，则必须在 CUlinkState 的生命周期内保持有效。在此调用返回后，不维护对输入的其他引用。

注意

对于 LTO-IR 输入，仅接受使用 CUDA 12.0 之前的工具包编译的 LTO-IR

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cuLinkAddData, cuLinkAddFile, cuLinkComplete, cuLinkDestroy

CUresult cuLinkDestroy ( CUlinkState state )

销毁 JIT 链接器调用的状态。

参数

state: 链接器调用的状态对象

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE

描述

另请参阅

cuLinkCreate

CUresult cuModuleEnumerateFunctions ( CUfunction* functions, unsigned int numFunctions, CUmodule mod )

返回模块内的函数句柄。

参数

functions: - 函数句柄返回到的缓冲区
numFunctions: - 可以返回到缓冲区的最大函数句柄数
mod: - 要从中查询的模块

CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

在functions中返回最多numFunctions个函数句柄，这些句柄位于mod内。当函数加载模式设置为 LAZY 时，检索到的函数可能部分加载。可以使用 cuFunctionIsLoaded 查询函数的加载状态。当使用部分加载的函数句柄调用时，CUDA API 可能会自动加载函数，这可能会导致额外的延迟。或者，可以使用 cuFunctionLoad 显式加载函数。当模块卸载时，返回的函数句柄将变为无效。

另请参阅

cuModuleGetFunction, cuModuleGetFunctionCount, cuFuncIsLoaded, cuFuncLoad

CUresult cuModuleGetFunction ( CUfunction* hfunc, CUmodule hmod, const char* name )

返回函数句柄。

参数

hfunc: - 返回的函数句柄
hmod: - 要从中检索函数的模块
name: - 要检索的函数的名称

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND

描述

在*hfunc名称为name的函数的句柄，该函数位于模块hmod中。如果不存在该名称的函数，则 cuModuleGetFunction() 返回 CUDA_ERROR_NOT_FOUND。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoad, cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload

CUresult cuModuleGetFunctionCount ( unsigned int* count, CUmodule mod )

返回模块内的函数数量。

参数

count: - 在模块中找到的函数数量
mod: - 要查询的模块

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

在count模块mod.

CUresult cuModuleGetGlobal ( CUdeviceptr* dptr, size_t* bytes, CUmodule hmod, const char* name )

返回模块中的全局指针。

参数

dptr: - 返回的全局设备指针
bytes: - 返回的全局大小（字节）
hmod: - 从中检索全局变量的模块
name: - 要检索的全局变量的名称

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND

描述

在*dptr和*bytes名为 global 的全局变量的基指针和大小name的函数的句柄，该函数位于模块hmod。如果不存在该名称的变量，cuModuleGetGlobal() 返回 CUDA_ERROR_NOT_FOUND。参数之一dptr或bytes（不是两者）可以为 NULL，在这种情况下将被忽略。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cuModuleGetFunction, cuModuleGetTexRef, cuModuleLoad, cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload, cudaGetSymbolAddress, cudaGetSymbolSize

CUresult cuModuleGetLoadingMode ( CUmoduleLoadingMode* mode )

查询延迟加载模式。

参数

mode: - 返回延迟加载模式

CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,

描述

返回延迟加载模式。模块加载模式由 CUDA_MODULE_LOADING 环境变量控制。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cuModuleLoad,

CUresult cuModuleLoad ( CUmodule* module, const char* fname )

加载计算模块。

参数

module: - 返回的模块
fname: - 要加载的模块的文件名

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_PTX, CUDA_ERROR_UNSUPPORTED_PTX_VERSION, CUDA_ERROR_NOT_FOUND, CUDA_ERROR_OUT_OF_MEMORY, CUDA_ERROR_FILE_NOT_FOUND, CUDA_ERROR_NO_BINARY_FOR_GPU, CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, CUDA_ERROR_SHARED_OBJECT_INIT_FAILED, CUDA_ERROR_JIT_COMPILER_NOT_FOUND

描述

接受文件名fname并将相应的模块加载module到当前上下文中。CUDA 驱动程序 API 不会尝试延迟分配模块所需的资源；如果无法分配模块所需的功能和数据（常量和全局）的内存，则 cuModuleLoad() 将失败。该文件应为 nvcc 输出的 cubin 文件，或 nvcc 输出或手写的 PTX 文件，或从工具链 4.0 或更高版本开始的 nvcc 输出的 fatbin 文件。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cuModuleGetFunction, cuModuleGetGlobal, cuModuleGetTexRef, cuModuleLoadData, cuModuleLoadDataEx, cuModuleLoadFatBinary, cuModuleUnload

CUresult cuModuleLoadData ( CUmodule* module, const void* image )