CUDA Driver API :: CUDA Toolkit Documentation

6.10. 模块管理

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

枚举

enum CUmoduleLoadingMode

Functions

CUresult cuLinkAddData ( CUlinkState state, CUjitInputType type, void* data, size_t size, const char* name, unsigned int numOptions, CUjit_option* options, void** optionValues ): Add an input to a pending linker invocation.
CUresult cuLinkAddFile ( CUlinkState state, CUjitInputType type, const char* path, unsigned int numOptions, CUjit_option* options, void** optionValues ): Add a file input to a pending linker invocation.
CUresult cuLinkComplete ( CUlinkState state, void** cubinOut, size_t* sizeOut ): Complete a pending linker invocation.
CUresult cuLinkCreate ( unsigned int numOptions, CUjit_option* options, void** optionValues, CUlinkState* stateOut ): Creates a pending JIT linker invocation.
CUresult cuLinkDestroy ( CUlinkState state ): Destroys state for a JIT linker invocation.
CUresult cuModuleEnumerateFunctions ( CUfunction* functions, unsigned int numFunctions, CUmodule mod ): Returns the function handles within a module.
CUresult cuModuleGetFunction ( CUfunction* hfunc, CUmodule hmod, const char* name ): Returns a function handle.
CUresult cuModuleGetFunctionCount ( unsigned int* count, CUmodule mod ): Returns the number of functions within a module.
CUresult cuModuleGetGlobal ( CUdeviceptr* dptr, size_t* bytes, CUmodule hmod, const char* name ): Returns a global pointer from a module.
CUresult cuModuleGetLoadingMode ( CUmoduleLoadingMode* mode ): Query lazy loading mode.
CUresult cuModuleLoad ( CUmodule* module, const char* fname ): Loads a compute module.
CUresult cuModuleLoadData ( CUmodule* module, const void* image ): Load a module's data.
CUresult cuModuleLoadDataEx ( CUmodule* module, const void* image, unsigned int numOptions, CUjit_option* options, void** optionValues ): Load a module's data with options.
CUresult cuModuleLoadFatBinary ( CUmodule* module, const void* fatCubin ): Load a module's data.
CUresult cuModuleUnload ( CUmodule hmod ): Unloads a module.

枚举

enum CUmoduleLoadingMode

CUDA 延迟加载状态

数值

CU_MODULE_EAGER_LOADING = 0x1: Lazy Kernel Loading is not enabled
CU_MODULE_LAZY_LOADING = 0x2: Lazy Kernel Loading is enabled

Functions

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

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

参数

state: A pending linker action.
type: The type of the input data.
data: The input data. PTX must be NULL-terminated.
size: The length of the input data.
name: An optional name for this input in log messages.
numOptions: Size of options.
options: Options to be applied only for this input (overrides options from cuLinkCreate).
optionValues: Array of option values, each cast to 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。

Note:

对于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: A pending linker action
type: The type of the input data
path: Path to the input file
numOptions: Size of options
options: Options to be applied only for this input (overrides options from cuLinkCreate)
optionValues: Array of option values, each cast to 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。

Note:

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

另请参阅：

cuLinkCreate, cuLinkAddData, cuLinkComplete, cuLinkDestroy

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

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

参数

state: A pending linker invocation
cubinOut: On success, this will point to the output image
sizeOut: Optional parameter to receive the size of the generated image

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_OUT_OF_MEMORY

描述

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

另请参阅：

cuLinkCreate, cuLinkAddData, cuLinkAddFile, cuLinkDestroy, cuModuleLoadData

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

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

参数

numOptions: Size of options arrays
options: Array of linker and compiler options
optionValues: Array of option values, each cast to void *
stateOut: On success, this will contain a CUlinkState to specify and complete this action

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时将被视为可重定位代码（相当于nvcc的-rdc=true选项），其效果与离线可重定位设备代码链接类似。

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

Note:

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

Note:

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

另请参阅：

cuLinkAddData, cuLinkAddFile, cuLinkComplete, cuLinkDestroy

CUresult cuLinkDestroy ( CUlinkState state )

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

参数

state: State object for the linker invocation

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE

描述

另请参阅：

cuLinkCreate

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

返回模块内的函数句柄。

参数

functions: - Buffer where the function handles are returned to
numFunctions: - Maximum number of function handles may be returned to the buffer
mod: - Module to query from

CUDA_SUCCESS, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

在functions中返回模块mod内最多numFunctions个函数句柄。当函数加载模式设置为LAZY时，获取的函数可能仅部分加载。可通过cuFunctionIsLoaded查询函数的加载状态。当调用部分加载的函数句柄时，CUDA API可能会自动加载该函数，这可能导致额外延迟。另外，也可使用cuFunctionLoad显式加载函数。当模块卸载时，返回的函数句柄将失效。

另请参阅：

cuModuleGetFunction, cuModuleGetFunctionCount, cuFuncIsLoaded, cuFuncLoad

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

返回一个函数句柄。

参数

hfunc: - Returned function handle
hmod: - Module to retrieve function from
name: - Name of function to retrieve

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND

描述

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

Note:

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

另请参阅：

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

CUresult cuModuleGetFunctionCount ( unsigned int* count, CUmodule mod )

返回模块内的函数数量。

参数

count: - Number of functions found within the module
mod: - Module to query

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_VALUE

描述

返回mod中函数的数量到count参数。

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

从模块返回一个全局指针。

参数

dptr: - Returned global device pointer
bytes: - Returned global size in bytes
hmod: - Module to retrieve global from
name: - Name of global to retrieve

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_FOUND

描述

返回位于模块hmod中名为name的全局变量的基指针和大小到*dptr和*bytes中。如果不存在该名称的变量，cuModuleGetGlobal()将返回CUDA_ERROR_NOT_FOUND。参数dptr或bytes中的一个（不能同时为NULL）可以为NULL，这种情况下该参数将被忽略。

Note:

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

另请参阅：

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

CUresult cuModuleGetLoadingMode ( CUmoduleLoadingMode* mode )

查询懒加载模式。

参数

mode: - Returns the lazy loading mode

CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE,

描述

返回懒加载模式模块加载模式由CUDA_MODULE_LOADING环境变量控制

Note:

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

另请参阅：

cuModuleLoad,

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

加载一个计算模块。

参数

module: - Returned module
fname: - Filename of module to load

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文件。

Note:

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

另请参阅：

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

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