Module management

hipError_t hipModuleGetGlobal(hipDeviceptr_t *dptr, size_t *bytes, hipModule_t hmod, const char *name)

Returns a global pointer from a module.

Returns in *dptr and *bytes the pointer and size of the global of name name located in module hmod. If no variable of that name exists, it returns hipErrorNotFound. Both parameters dptr and bytes are optional. If one of them is NULL, it is ignored and hipSuccess is returned.

Parameters:

• dptr – [out] Returns global device pointer

• bytes – [out] Returns global size in bytes

• hmod – [in] Module to retrieve global from

• name – [in] Name of global to retrieve

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorNotFound, hipErrorInvalidContext

hipError_t hipModuleLoadFatBinary(hipModule_t *module, const void *fatbin)

Loads fatbin object.

Parameters:

• fatbin – [in] fatbin to be loaded as a module

• module – [out] Module

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorFileNotFound, hipErrorOutOfMemory, hipErrorSharedObjectInitFailed, hipErrorNotInitialized

hipError_t hipModuleLoad(hipModule_t *module, const char *fname)

Loads code object from file into a module the currrent context.

Warning

File/memory resources allocated in this function are released only in hipModuleUnload.

Parameters:

• fname – [in] Filename of code object to load

• module – [out] Module

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorFileNotFound, hipErrorOutOfMemory, hipErrorSharedObjectInitFailed, hipErrorNotInitialized

hipError_t hipModuleUnload(hipModule_t module)

Frees the module.

The module is freed, and the code objects associated with it are destroyed.

Parameters:

module – [in] Module to free

Returns:

hipSuccess, hipErrorInvalidResourceHandle

hipError_t hipModuleGetFunction(hipFunction_t *function, hipModule_t module, const char *kname)

Function with kname will be extracted if present in module.

Parameters:

• module – [in] Module to get function from

• kname – [in] Pointer to the name of function

• function – [out] Pointer to function handle

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

hipError_t hipModuleGetFunctionCount(unsigned int *count, hipModule_t mod)

Returns the number of functions within a module.

Parameters:

• mod – [in] Module to get function count from

• count – [out] function count from module

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

hipError_t hipLibraryLoadData(hipLibrary_t *library, const void *code, hipJitOption **jitOptions, void **jitOptionsValues, unsigned int numJitOptions, hipLibraryOption **libraryOptions, void **libraryOptionValues, unsigned int numLibraryOptions)

Load hip Library from inmemory object.

Parameters:

• library – [out] Output Library

• code – [in] In memory object

• jitOptions – [in] JIT options, CUDA only

• jitOptionsValues – [in] JIT options values, CUDA only

• numJitOptions – [in] Number of JIT options

• libraryOptions – [in] Library options

• libraryOptionValues – [in] Library options values

• numLibraryOptions – [in] Number of library options

Returns:

hipSuccess, hipErrorInvalidValue,

hipError_t hipLibraryLoadFromFile(hipLibrary_t *library, const char *fileName, hipJitOption **jitOptions, void **jitOptionsValues, unsigned int numJitOptions, hipLibraryOption **libraryOptions, void **libraryOptionValues, unsigned int numLibraryOptions)

Load hip Library from file.

Parameters:

• library – [out] Output Library

• fileName – [in] file which contains code object

• jitOptions – [in] JIT options, CUDA only

• jitOptionsValues – [in] JIT options values, CUDA only

• numJitOptions – [in] Number of JIT options

• libraryOptions – [in] Library options

• libraryOptionValues – [in] Library options values

• numLibraryOptions – [in] Number of library options

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipLibraryUnload(hipLibrary_t library)

Unload HIP Library.

Parameters:

library – [in] Input created hip library

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipLibraryGetKernel(hipKernel_t *pKernel, hipLibrary_t library, const char *name)

Get Kernel object from library.

Parameters:

• pKernel – [out] Output kernel object

• library – [in] Input hip library

• name – [in] kernel name to be searched for

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipLibraryGetKernelCount(unsigned int *count, hipLibrary_t library)

Get Kernel count in library.

Parameters:

• count – [out] Count of kernels in library

• library – [in] Input created hip library

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipGetFuncBySymbol(hipFunction_t *functionPtr, const void *symbolPtr)

Gets pointer to device entry function that matches entry function symbolPtr.

Parameters:

• functionPtr – [out] Device entry function

• symbolPtr – [in] Pointer to device entry function to search for

Returns:

hipSuccess, hipErrorInvalidDeviceFunction

hipError_t hipGetDriverEntryPoint(const char *symbol, void **funcPtr, unsigned long long flags, hipDriverEntryPointQueryResult *driverStatus)

Gets function pointer of a requested HIP API.

Parameters:

• symbol – [in] The API base name

• funcPtr – [out] Pointer to the requested function

• flags – [in] Flags for the search

• driverStatus – [out] Optional returned status of the search

Returns:

hipSuccess, hipErrorInvalidValue

hipError_t hipModuleGetTexRef(textureReference **texRef, hipModule_t hmod, const char *name)

returns the handle of the texture reference with the name from the module.

Parameters:

• hmod – [in] Module

• name – [in] Pointer of name of texture reference

• texRef – [out] Pointer of texture reference

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorNotFound, hipErrorInvalidValue

hipError_t hipModuleLoadData(hipModule_t *module, const void *image)

builds module from code object data which resides in host memory.

The “image” is a pointer to the location of code object data. This data can be either a single code object or a fat binary (fatbin), which serves as the entry point for loading and launching device-specific kernel executions.

By default, the following command generates a fatbin:

“amdclang++ -O3 -c –offload-device-only –offload-arch=<GPU_ARCH> <input_file> -o <output_file>”

For more details, refer to: Kernel Compilation in the HIP kernel language C++ support, or HIP runtime compilation (HIP RTC).

Parameters:

• image – [in] The pointer to the location of data

• module – [out] Retuned module

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

hipError_t hipModuleLoadDataEx(hipModule_t *module, const void *image, unsigned int numOptions, hipJitOption *options, void **optionValues)

builds module from code object which resides in host memory. Image is pointer to that location. Options are not used. hipModuleLoadData is called.

Parameters:

• image – [in] The pointer to the location of data

• module – [out] Retuned module

• numOptions – [in] Number of options

• options – [in] Options for JIT

• optionValues – [in] Option values for JIT

Returns:

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

hipError_t hipLinkAddData(hipLinkState_t state, hipJitInputType type, void *data, size_t size, const char *name, unsigned int numOptions, hipJitOption *options, void **optionValues)

Adds bitcode data to be linked with options.

If adding the file fails, it will

See also

hipError_t

Parameters:

• state – [in] hip link state

• type – [in] Type of the input data or bitcode

• data – [in] Input data which is null terminated

• size – [in] Size of the input data

• name – [in] Optional name for this input

• numOptions – [in] Size of the options

• options – [in] Array of options applied to this input

• optionValues – [in] Array of option values cast to void*

Returns:

hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

Returns:

hipErrorInvalidConfiguration

hipError_t hipLinkAddFile(hipLinkState_t state, hipJitInputType type, const char *path, unsigned int numOptions, hipJitOption *options, void **optionValues)

Adds a file with bitcode to be linked with options.

If adding the file fails, it will

See also

hipError_t

Parameters:

• state – [in] hip link state

• type – [in] Type of the input data or bitcode

• path – [in] Path to the input file where bitcode is present

• numOptions – [in] Size of the options

• options – [in] Array of options applied to this input

• optionValues – [in] Array of option values cast to void*

Returns:

hipSuccess, hipErrorInvalidValue

Returns:

hipErrorInvalidConfiguration

hipError_t hipLinkComplete(hipLinkState_t state, void **hipBinOut, size_t *sizeOut)

Completes the linking of the given program.

If adding the data fails, it will

See also

hipError_t

Parameters:

• state – [in] hip link state

• hipBinOut – [out] Upon success, points to the output binary

• sizeOut – [out] Size of the binary is stored (optional)

Returns:

hipSuccess hipErrorInvalidValue

Returns:

hipErrorInvalidConfiguration

hipError_t hipLinkCreate(unsigned int numOptions, hipJitOption *options, void **optionValues, hipLinkState_t *stateOut)

Creates a linker instance with options.

See also

hipSuccess

Parameters:

• numOptions – [in] Number of options

• option – [in] Array of options

• optionValues – [in] Array of option values cast to void*

• stateOut – [out] hip link state created upon success

Returns:

hipSuccess hipErrorInvalidValue hipErrorInvalidConfiguration

hipError_t hipLinkDestroy(hipLinkState_t state)

Deletes the linker instance.

See also

hipSuccess

Parameters:

state – [in] link state instance

Returns:

hipSuccess hipErrorInvalidValue

hipError_t hipMemGetHandleForAddressRange(void *handle, hipDeviceptr_t dptr, size_t size, hipMemRangeHandleType handleType, unsigned long long flags)

Returns a handle for the address range requested.

This function returns a handle to a device pointer created using either hipMalloc set of APIs or through hipMemAddressReserve (as long as the ptr is mapped).

Parameters:

• handle – [out] Ptr to the handle where the fd or other types will be returned.

• dptr – [in] Device ptr for which we get the handle.

• size – [in] Size of the address range.

• handleType – [in] Type of the handle requested for the address range.

• flags – [in] Any flags set regarding the handle requested.

Returns:

hipSuccess if the kernel is launched successfully, otherwise an appropriate error code.