Module Management

Module Management#

HIP Runtime API Reference: Module Management

Collaboration diagram for Module Management:

Modules
	Cooperative groups kernel launch of Module management.

Functions
hipError_t	hipModuleGetGlobal (hipDeviceptr_t dptr, size_t bytes, hipModule_t hmod, const char *name)
	Returns a global pointer from a module.

hipError_t	hipModuleLoadFatBinary (hipModule_t module, const void fatbin)
	Loads fatbin object.

hipError_t	hipModuleLoad (hipModule_t module, const char fname)
	Loads code object from file into a module the currrent context.

hipError_t	hipModuleUnload (hipModule_t module)
	Frees the module.

hipError_t	hipModuleGetFunction (hipFunction_t function, hipModule_t module, const char kname)
	Function with kname will be extracted if present in module.

hipError_t	hipModuleGetFunctionCount (unsigned int *count, hipModule_t mod)
	Returns the number of functions within a module.

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.

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.

hipError_t	hipLibraryUnload (hipLibrary_t library)
	Unload HIP Library.

hipError_t	hipLibraryGetKernel (hipKernel_t pKernel, hipLibrary_t library, const char name)
	Get Kernel object from library.

hipError_t	hipLibraryGetKernelCount (unsigned int *count, hipLibrary_t library)
	Get Kernel count in library.

hipError_t	hipGetFuncBySymbol (hipFunction_t functionPtr, const void symbolPtr)
	Gets pointer to device entry function that matches entry function symbolPtr.

hipError_t	hipGetDriverEntryPoint (const char symbol, void funcPtr, unsigned long long flags, hipDriverEntryPointQueryResult driverStatus)
	Gets function pointer of a requested HIP API.

hipError_t	hipModuleGetTexRef (textureReference *texRef, hipModule_t hmod, const char name)
	returns the handle of the texture reference with the name from the module.

hipError_t	hipModuleLoadData (hipModule_t module, const void image)
	builds module from code object data which resides in host memory.

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.

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.

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.

hipError_t	hipLinkComplete (hipLinkState_t state, void *hipBinOut, size_t sizeOut)
	Completes the linking of the given program.

hipError_t	hipLinkCreate (unsigned int numOptions, hipJitOption options, void optionValues, hipLinkState_t stateOut)
	Creates a linker instance with options.

hipError_t	hipLinkDestroy (hipLinkState_t state)
	Deletes the linker instance.

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.

Detailed Description

This section describes the module management functions of HIP runtime API.

Function Documentation

◆ hipGetDriverEntryPoint()

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

Gets function pointer of a requested HIP API.

Parameters

[in]	symbol	The API base name
[out]	funcPtr	Pointer to the requested function
[in]	flags	Flags for the search
[out]	driverStatus	Optional returned status of the search

Returns: hipSuccess, hipErrorInvalidValue

◆ hipGetFuncBySymbol()

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

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

Parameters

[out]	functionPtr	Device entry function
[in]	symbolPtr	Pointer to device entry function to search for

Returns: hipSuccess, hipErrorInvalidDeviceFunction

◆ hipLibraryGetKernel()

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

Get Kernel object from library.

Parameters

[out]	pKernel	Output kernel object
[in]	library	Input hip library
[in]	name	kernel name to be searched for

Returns: hipSuccess, hipErrorInvalidValue

◆ hipLibraryGetKernelCount()

hipError_t hipLibraryGetKernelCount	(	unsigned int *	count,
		hipLibrary_t	library
	)

Get Kernel count in library.

Parameters

[out]	count	Count of kernels in library
[in]	library	Input created hip library

Returns: hipSuccess, hipErrorInvalidValue

◆ hipLibraryLoadData()

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

[out]	library	Output Library
[in]	code	In memory object
[in]	jitOptions	JIT options, CUDA only
[in]	jitOptionsValues	JIT options values, CUDA only
[in]	numJitOptions	Number of JIT options
[in]	libraryOptions	Library options
[in]	libraryOptionValues	Library options values
[in]	numLibraryOptions	Number of library options

Returns: hipSuccess, hipErrorInvalidValue,

◆ hipLibraryLoadFromFile()

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

[out]	library	Output Library
[in]	fileName	file which contains code object
[in]	jitOptions	JIT options, CUDA only
[in]	jitOptionsValues	JIT options values, CUDA only
[in]	numJitOptions	Number of JIT options
[in]	libraryOptions	Library options
[in]	libraryOptionValues	Library options values
[in]	numLibraryOptions	Number of library options

Returns: hipSuccess, hipErrorInvalidValue

◆ hipLibraryUnload()

hipError_t hipLibraryUnload ( hipLibrary_t library )

Unload HIP Library.

Parameters

[in] library Input created hip library

Returns: hipSuccess, hipErrorInvalidValue

◆ hipLinkAddData()

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.

Parameters

[in]	state	hip link state
[in]	type	Type of the input data or bitcode
[in]	data	Input data which is null terminated
[in]	size	Size of the input data
[in]	name	Optional name for this input
[in]	numOptions	Size of the options
[in]	options	Array of options applied to this input
[in]	optionValues	Array of option values cast to void*

Returns: hipSuccess, hipErrorInvalidValue, hipErrorInvalidHandle

If adding the file fails, it will

Returns: hipErrorInvalidConfiguration

See also: hipError_t

◆ hipLinkAddFile()

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.

Parameters

[in]	state	hip link state
[in]	type	Type of the input data or bitcode
[in]	path	Path to the input file where bitcode is present
[in]	numOptions	Size of the options
[in]	options	Array of options applied to this input
[in]	optionValues	Array of option values cast to void*

Returns: hipSuccess, hipErrorInvalidValue

If adding the file fails, it will

Returns: hipErrorInvalidConfiguration

See also: hipError_t

◆ hipLinkComplete()

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

Completes the linking of the given program.

Parameters

[in]	state	hip link state
[out]	hipBinOut	Upon success, points to the output binary
[out]	sizeOut	Size of the binary is stored (optional)

Returns: hipSuccess hipErrorInvalidValue

If adding the data fails, it will

Returns: hipErrorInvalidConfiguration

See also: hipError_t

◆ hipLinkCreate()

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

Creates a linker instance with options.

Parameters

[in]	numOptions	Number of options
[in]	options	Array of options
[in]	optionValues	Array of option values cast to void*
[out]	stateOut	hip link state created upon success

Returns: hipSuccess hipErrorInvalidValue hipErrorInvalidConfiguration

See also: hipSuccess

◆ hipLinkDestroy()

hipError_t hipLinkDestroy ( hipLinkState_t state )

Deletes the linker instance.

Parameters

[in] state link state instance

Returns: hipSuccess hipErrorInvalidValue

See also: hipSuccess

◆ hipMemGetHandleForAddressRange()

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

[out]	handle	Ptr to the handle where the fd or other types will be returned.
[in]	dptr	Device ptr for which we get the handle.
[in]	size	Size of the address range.
[in]	handleType	Type of the handle requested for the address range.
[in]	flags	Any flags set regarding the handle requested.

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

◆ hipModuleGetFunction()

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

Function with kname will be extracted if present in module.

Parameters

[in]	module	Module to get function from
[in]	kname	Pointer to the name of function
[out]	function	Pointer to function handle

Returns: hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

◆ hipModuleGetFunctionCount()

hipError_t hipModuleGetFunctionCount	(	unsigned int *	count,
		hipModule_t	mod
	)

Returns the number of functions within a module.

Parameters

[in]	mod	Module to get function count from
[out]	count	function count from module

Returns: hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

◆ hipModuleGetGlobal()

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

[out]	dptr	Returns global device pointer
[out]	bytes	Returns global size in bytes
[in]	hmod	Module to retrieve global from
[in]	name	Name of global to retrieve

Returns: hipSuccess, hipErrorInvalidValue, hipErrorNotFound, hipErrorInvalidContext

◆ hipModuleGetTexRef()

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

[in]	hmod	Module
[in]	name	Pointer of name of texture reference
[out]	texRef	Pointer of texture reference

Returns: hipSuccess, hipErrorNotInitialized, hipErrorNotFound, hipErrorInvalidValue

◆ hipModuleLoad()

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

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

Parameters

[in]	fname	Filename of code object to load
[out]	module	Module

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

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

◆ hipModuleLoadData()

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

[in]	image	The pointer to the location of data
[out]	module	Retuned module

Returns: hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

◆ hipModuleLoadDataEx()

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

[in]	image	The pointer to the location of data
[out]	module	Retuned module
[in]	numOptions	Number of options
[in]	options	Options for JIT
[in]	optionValues	Option values for JIT

Returns: hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

◆ hipModuleLoadFatBinary()

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

Loads fatbin object.

Parameters

[in]	fatbin	fatbin to be loaded as a module
[out]	module	Module

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

◆ hipModuleUnload()

hipError_t hipModuleUnload ( hipModule_t module )

Frees the module.

Parameters

[in] module Module to free

Returns: hipSuccess, hipErrorInvalidResourceHandle

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

Module Management

Module Management#

Modules

Functions

Detailed Description

Function Documentation

◆ hipGetDriverEntryPoint()

◆ hipGetFuncBySymbol()

◆ hipLibraryGetKernel()

◆ hipLibraryGetKernelCount()

◆ hipLibraryLoadData()

◆ hipLibraryLoadFromFile()

◆ hipLibraryUnload()

◆ hipLinkAddData()

◆ hipLinkAddFile()

◆ hipLinkComplete()

◆ hipLinkCreate()

◆ hipLinkDestroy()

◆ hipMemGetHandleForAddressRange()

◆ hipModuleGetFunction()

◆ hipModuleGetFunctionCount()

◆ hipModuleGetGlobal()

◆ hipModuleGetTexRef()

◆ hipModuleLoad()

◆ hipModuleLoadData()

◆ hipModuleLoadDataEx()

◆ hipModuleLoadFatBinary()

◆ hipModuleUnload()