Runtime Compilation

Runtime Compilation#

HIP Runtime API Reference: Runtime Compilation

Collaboration diagram for Runtime Compilation:

Typedefs
typedef struct ihiprtcLinkState *	hiprtcLinkState

typedef struct _hiprtcProgram *	hiprtcProgram

Enumerations
enum	hiprtcResult { HIPRTC_SUCCESS = 0 , HIPRTC_ERROR_OUT_OF_MEMORY = 1 , HIPRTC_ERROR_PROGRAM_CREATION_FAILURE = 2 , HIPRTC_ERROR_INVALID_INPUT = 3 , HIPRTC_ERROR_INVALID_PROGRAM = 4 , HIPRTC_ERROR_INVALID_OPTION = 5 , HIPRTC_ERROR_COMPILATION = 6 , HIPRTC_ERROR_LINKING = 7 , HIPRTC_ERROR_BUILTIN_OPERATION_FAILURE = 8 , HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION = 9 , HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION = 10 , HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID = 11 , HIPRTC_ERROR_INTERNAL_ERROR = 12 }

enum	hiprtcJIT_option { HIPRTC_JIT_MAX_REGISTERS = 0 , HIPRTC_JIT_THREADS_PER_BLOCK , HIPRTC_JIT_WALL_TIME , HIPRTC_JIT_INFO_LOG_BUFFER , HIPRTC_JIT_INFO_LOG_BUFFER_SIZE_BYTES , HIPRTC_JIT_ERROR_LOG_BUFFER , HIPRTC_JIT_ERROR_LOG_BUFFER_SIZE_BYTES , HIPRTC_JIT_OPTIMIZATION_LEVEL , HIPRTC_JIT_TARGET_FROM_HIPCONTEXT , HIPRTC_JIT_TARGET , HIPRTC_JIT_FALLBACK_STRATEGY , HIPRTC_JIT_GENERATE_DEBUG_INFO , HIPRTC_JIT_LOG_VERBOSE , HIPRTC_JIT_GENERATE_LINE_INFO , HIPRTC_JIT_CACHE_MODE , HIPRTC_JIT_NEW_SM3X_OPT , HIPRTC_JIT_FAST_COMPILE , HIPRTC_JIT_GLOBAL_SYMBOL_NAMES , HIPRTC_JIT_GLOBAL_SYMBOL_ADDRESS , HIPRTC_JIT_GLOBAL_SYMBOL_COUNT , HIPRTC_JIT_LTO , HIPRTC_JIT_FTZ , HIPRTC_JIT_PREC_DIV , HIPRTC_JIT_PREC_SQRT , HIPRTC_JIT_FMA , HIPRTC_JIT_NUM_OPTIONS }

enum	hiprtcJITInputType { HIPRTC_JIT_INPUT_CUBIN = 0 , HIPRTC_JIT_INPUT_PTX , HIPRTC_JIT_INPUT_FATBINARY , HIPRTC_JIT_INPUT_OBJECT , HIPRTC_JIT_INPUT_LIBRARY , HIPRTC_JIT_INPUT_NVVM , HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES , HIPRTC_JIT_INPUT_LLVM_BITCODE = 100 , HIPRTC_JIT_INPUT_LLVM_BUNDLED_BITCODE = 101 , HIPRTC_JIT_INPUT_LLVM_ARCHIVES_OF_BUNDLED_BITCODE = 102 , HIPRTC_JIT_NUM_INPUT_TYPES = (HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES + 3) }

Functions
const char *	hiprtcGetErrorString (hiprtcResult result)
	Returns text string message to explain the error which occurred.

hiprtcResult	hiprtcVersion (int major, int minor)
	Sets the parameters as major and minor version.

hiprtcResult	hiprtcAddNameExpression (hiprtcProgram prog, const char *name_expression)
	Adds the given name exprssion to the runtime compilation program.

hiprtcResult	hiprtcCompileProgram (hiprtcProgram prog, int numOptions, const char **options)
	Compiles the given runtime compilation program.

hiprtcResult	hiprtcCreateProgram (hiprtcProgram prog, const char src, const char name, int numHeaders, const char headers, const char *includeNames)
	Creates an instance of hiprtcProgram with the given input parameters, and sets the output hiprtcProgram prog with it.

hiprtcResult	hiprtcDestroyProgram (hiprtcProgram *prog)
	Destroys an instance of given hiprtcProgram.

hiprtcResult	hiprtcGetLoweredName (hiprtcProgram prog, const char name_expression, const char *lowered_name)
	Gets the lowered (mangled) name from an instance of hiprtcProgram with the given input parameters, and sets the output lowered_name with it.

hiprtcResult	hiprtcGetProgramLog (hiprtcProgram prog, char *log)
	Gets the log generated by the runtime compilation program instance.

hiprtcResult	hiprtcGetProgramLogSize (hiprtcProgram prog, size_t *logSizeRet)
	Gets the size of log generated by the runtime compilation program instance.

hiprtcResult	hiprtcGetCode (hiprtcProgram prog, char *code)
	Gets the pointer of compilation binary by the runtime compilation program instance.

hiprtcResult	hiprtcGetCodeSize (hiprtcProgram prog, size_t *codeSizeRet)
	Gets the size of compilation binary by the runtime compilation program instance.

hiprtcResult	hiprtcGetBitcode (hiprtcProgram prog, char *bitcode)
	Gets the pointer of compiled bitcode by the runtime compilation program instance.

hiprtcResult	hiprtcGetBitcodeSize (hiprtcProgram prog, size_t *bitcode_size)
	Gets the size of compiled bitcode by the runtime compilation program instance.

hiprtcResult	hiprtcLinkCreate (unsigned int num_options, hiprtcJIT_option option_ptr, void option_vals_pptr, hiprtcLinkState hip_link_state_ptr)
	Creates the link instance via hiprtc APIs.

hiprtcResult	hiprtcLinkAddFile (hiprtcLinkState hip_link_state, hiprtcJITInputType input_type, const char file_path, unsigned int num_options, hiprtcJIT_option options_ptr, void **option_values)
	Adds a file with bit code to be linked with options.

hiprtcResult	hiprtcLinkAddData (hiprtcLinkState hip_link_state, hiprtcJITInputType input_type, void image, size_t image_size, const char name, unsigned int num_options, hiprtcJIT_option options_ptr, void *option_values)
	Completes the linking of the given program.

hiprtcResult	hiprtcLinkComplete (hiprtcLinkState hip_link_state, void *bin_out, size_t size_out)
	Completes the linking of the given program.

hiprtcResult	hiprtcLinkDestroy (hiprtcLinkState hip_link_state)
	Deletes the link instance via hiprtc APIs.

Detailed Description

This section describes the runtime compilation functions of HIP runtime API.

Typedef Documentation

◆ hiprtcLinkState

typedef struct ihiprtcLinkState* hiprtcLinkState

◆ hiprtcProgram

typedef struct _hiprtcProgram* hiprtcProgram

Enumeration Type Documentation

◆ hiprtcJIT_option

enum hiprtcJIT_option

Enumerator
HIPRTC_JIT_MAX_REGISTERS
HIPRTC_JIT_THREADS_PER_BLOCK
HIPRTC_JIT_WALL_TIME
HIPRTC_JIT_INFO_LOG_BUFFER
HIPRTC_JIT_INFO_LOG_BUFFER_SIZE_BYTES
HIPRTC_JIT_ERROR_LOG_BUFFER
HIPRTC_JIT_ERROR_LOG_BUFFER_SIZE_BYTES
HIPRTC_JIT_OPTIMIZATION_LEVEL
HIPRTC_JIT_TARGET_FROM_HIPCONTEXT
HIPRTC_JIT_TARGET
HIPRTC_JIT_FALLBACK_STRATEGY
HIPRTC_JIT_GENERATE_DEBUG_INFO
HIPRTC_JIT_LOG_VERBOSE
HIPRTC_JIT_GENERATE_LINE_INFO
HIPRTC_JIT_CACHE_MODE
HIPRTC_JIT_NEW_SM3X_OPT
HIPRTC_JIT_FAST_COMPILE
HIPRTC_JIT_GLOBAL_SYMBOL_NAMES
HIPRTC_JIT_GLOBAL_SYMBOL_ADDRESS
HIPRTC_JIT_GLOBAL_SYMBOL_COUNT
HIPRTC_JIT_LTO
HIPRTC_JIT_FTZ
HIPRTC_JIT_PREC_DIV
HIPRTC_JIT_PREC_SQRT
HIPRTC_JIT_FMA
HIPRTC_JIT_NUM_OPTIONS

◆ hiprtcJITInputType

enum hiprtcJITInputType

Enumerator
HIPRTC_JIT_INPUT_CUBIN
HIPRTC_JIT_INPUT_PTX
HIPRTC_JIT_INPUT_FATBINARY
HIPRTC_JIT_INPUT_OBJECT
HIPRTC_JIT_INPUT_LIBRARY
HIPRTC_JIT_INPUT_NVVM
HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES
HIPRTC_JIT_INPUT_LLVM_BITCODE
HIPRTC_JIT_INPUT_LLVM_BUNDLED_BITCODE
HIPRTC_JIT_INPUT_LLVM_ARCHIVES_OF_BUNDLED_BITCODE
HIPRTC_JIT_NUM_INPUT_TYPES

◆ hiprtcResult

enum hiprtcResult

Enumerator
HIPRTC_SUCCESS
HIPRTC_ERROR_OUT_OF_MEMORY
HIPRTC_ERROR_PROGRAM_CREATION_FAILURE
HIPRTC_ERROR_INVALID_INPUT
HIPRTC_ERROR_INVALID_PROGRAM
HIPRTC_ERROR_INVALID_OPTION
HIPRTC_ERROR_COMPILATION
HIPRTC_ERROR_LINKING
HIPRTC_ERROR_BUILTIN_OPERATION_FAILURE
HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION
HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION
HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID
HIPRTC_ERROR_INTERNAL_ERROR

Function Documentation

◆ hiprtcAddNameExpression()

hiprtcResult hiprtcAddNameExpression	(	hiprtcProgram	prog,
		const char *	name_expression
	)

Adds the given name exprssion to the runtime compilation program.

Parameters

[in]	prog	runtime compilation program instance.
[in]	name_expression	const char pointer to the name expression.

Returns: HIPRTC_SUCCESS

If const char pointer is NULL, it will return HIPRTC_ERROR_INVALID_INPUT.

See also: hiprtcResult

◆ hiprtcCompileProgram()

hiprtcResult hiprtcCompileProgram	(	hiprtcProgram	prog,
		int	numOptions,
		const char **	options
	)

Compiles the given runtime compilation program.

Parameters

[in]	prog	runtime compilation program instance.
[in]	numOptions	number of compiler options.
[in]	options	compiler options as const array of strins.

Returns: HIPRTC_SUCCESS

If the compiler failed to build the runtime compilation program, it will return HIPRTC_ERROR_COMPILATION.

See also: hiprtcResult

◆ hiprtcCreateProgram()

hiprtcResult hiprtcCreateProgram	(	hiprtcProgram *	prog,
		const char *	src,
		const char *	name,
		int	numHeaders,
		const char **	headers,
		const char **	includeNames
	)

Creates an instance of hiprtcProgram with the given input parameters, and sets the output hiprtcProgram prog with it.

Parameters

[in,out]	prog	runtime compilation program instance.
[in]	src	const char pointer to the program source.
[in]	name	const char pointer to the program name.
[in]	numHeaders	number of headers.
[in]	headers	array of strings pointing to headers.
[in]	includeNames	array of strings pointing to names included in program source.

Returns: HIPRTC_SUCCESS

Any invalide input parameter, it will return HIPRTC_ERROR_INVALID_INPUT or HIPRTC_ERROR_INVALID_PROGRAM.

If failed to create the program, it will return HIPRTC_ERROR_PROGRAM_CREATION_FAILURE.

See also: hiprtcResult

◆ hiprtcDestroyProgram()

hiprtcResult hiprtcDestroyProgram ( hiprtcProgram * prog )

Destroys an instance of given hiprtcProgram.

Parameters

[in] prog runtime compilation program instance.

Returns: HIPRTC_SUCCESS

If prog is NULL, it will return HIPRTC_ERROR_INVALID_INPUT.

See also: hiprtcResult

◆ hiprtcGetBitcode()

hiprtcResult hiprtcGetBitcode	(	hiprtcProgram	prog,
		char *	bitcode
	)

Gets the pointer of compiled bitcode by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	code	char pointer to bitcode.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcGetBitcodeSize()

hiprtcResult hiprtcGetBitcodeSize	(	hiprtcProgram	prog,
		size_t *	bitcode_size
	)

Gets the size of compiled bitcode by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	code	the size of bitcode.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcGetCode()

hiprtcResult hiprtcGetCode	(	hiprtcProgram	prog,
		char *	code
	)

Gets the pointer of compilation binary by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	code	char pointer to binary.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcGetCodeSize()

hiprtcResult hiprtcGetCodeSize	(	hiprtcProgram	prog,
		size_t *	codeSizeRet
	)

Gets the size of compilation binary by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	code	the size of binary.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcGetErrorString()

const char * hiprtcGetErrorString ( hiprtcResult result )

Returns text string message to explain the error which occurred.

Parameters

[in] result code to convert to string.

Returns: const char pointer to the NULL-terminated error string

Warning: In HIP, this function returns the name of the error, if the hiprtc result is defined, it will return "Invalid HIPRTC error code"

See also: hiprtcResult

◆ hiprtcGetLoweredName()

hiprtcResult hiprtcGetLoweredName	(	hiprtcProgram	prog,
		const char *	name_expression,
		const char **	lowered_name
	)

Gets the lowered (mangled) name from an instance of hiprtcProgram with the given input parameters, and sets the output lowered_name with it.

Parameters

[in]	prog	runtime compilation program instance.
[in]	name_expression	const char pointer to the name expression.
[in,out]	lowered_name	const char array to the lowered (mangled) name.

Returns: HIPRTC_SUCCESS

If any invalide nullptr input parameters, it will return HIPRTC_ERROR_INVALID_INPUT

If name_expression is not found, it will return HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID

If failed to get lowered_name from the program, it will return HIPRTC_ERROR_COMPILATION.

See also: hiprtcResult

◆ hiprtcGetProgramLog()

hiprtcResult hiprtcGetProgramLog	(	hiprtcProgram	prog,
		char *	log
	)

Gets the log generated by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	log	memory pointer to the generated log.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcGetProgramLogSize()

hiprtcResult hiprtcGetProgramLogSize	(	hiprtcProgram	prog,
		size_t *	logSizeRet
	)

Gets the size of log generated by the runtime compilation program instance.

Parameters

[in]	prog	runtime compilation program instance.
[out]	logSizeRet	size of generated log.

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcLinkAddData()

hiprtcResult hiprtcLinkAddData	(	hiprtcLinkState	hip_link_state,
		hiprtcJITInputType	input_type,
		void *	image,
		size_t	image_size,
		const char *	name,
		unsigned int	num_options,
		hiprtcJIT_option *	options_ptr,
		void **	option_values
	)

Completes the linking of the given program.

Parameters

[in]	hiprtc	link state, jit input type, image_ptr , option reated parameters.
[out]	None.

Returns: HIPRTC_SUCCESS

If adding the file fails, it will

Returns: HIPRTC_ERROR_PROGRAM_CREATION_FAILURE

See also: hiprtcResult

◆ hiprtcLinkAddFile()

hiprtcResult hiprtcLinkAddFile	(	hiprtcLinkState	hip_link_state,
		hiprtcJITInputType	input_type,
		const char *	file_path,
		unsigned int	num_options,
		hiprtcJIT_option *	options_ptr,
		void **	option_values
	)

Adds a file with bit code to be linked with options.

Parameters

[in]	hiprtc	link state, jit input type, file path, option reated parameters.
[out]	None.

Returns: HIPRTC_SUCCESS

If input values are invalid, it will

Returns: HIPRTC_ERROR_INVALID_INPUT

See also: hiprtcResult

◆ hiprtcLinkComplete()

hiprtcResult hiprtcLinkComplete	(	hiprtcLinkState	hip_link_state,
		void **	bin_out,
		size_t *	size_out
	)

Completes the linking of the given program.

Parameters

[in]	hiprtc	link state instance
[out]	linked_binary,linked_binary_size.

Returns: HIPRTC_SUCCESS

If adding the data fails, it will

Returns: HIPRTC_ERROR_PROGRAM_CREATION_FAILURE

See also: hiprtcResult

◆ hiprtcLinkCreate()

hiprtcResult hiprtcLinkCreate	(	unsigned int	num_options,
		hiprtcJIT_option *	option_ptr,
		void **	option_vals_pptr,
		hiprtcLinkState *	hip_link_state_ptr
	)

Creates the link instance via hiprtc APIs.

Parameters

[in]	hip_jit_options
[out]	hiprtc	link state instance

Returns: HIPRTC_SUCCESS

See also: hiprtcResult

◆ hiprtcLinkDestroy()

hiprtcResult hiprtcLinkDestroy ( hiprtcLinkState hip_link_state )

Deletes the link instance via hiprtc APIs.

Parameters

[in]	hiprtc	link state instance
[out]	code	the size of binary.

Returns: HIPRTC_SUCCESS

If linking fails, it will

Returns: HIPRTC_ERROR_LINKING

See also: hiprtcResult

◆ hiprtcVersion()

hiprtcResult hiprtcVersion	(	int *	major,
		int *	minor
	)

Sets the parameters as major and minor version.

Parameters

[out]	major	HIP Runtime Compilation major version.
[out]	minor	HIP Runtime Compilation minor version.

Runtime Compilation

Runtime Compilation#

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ hiprtcLinkState

◆ hiprtcProgram

Enumeration Type Documentation

◆ hiprtcJIT_option

◆ hiprtcJITInputType

◆ hiprtcResult

Function Documentation

◆ hiprtcAddNameExpression()

◆ hiprtcCompileProgram()

◆ hiprtcCreateProgram()

◆ hiprtcDestroyProgram()

◆ hiprtcGetBitcode()

◆ hiprtcGetBitcodeSize()

◆ hiprtcGetCode()

◆ hiprtcGetCodeSize()

◆ hiprtcGetErrorString()

◆ hiprtcGetLoweredName()

◆ hiprtcGetProgramLog()

◆ hiprtcGetProgramLogSize()

◆ hiprtcLinkAddData()

◆ hiprtcLinkAddFile()

◆ hiprtcLinkComplete()

◆ hiprtcLinkCreate()

◆ hiprtcLinkDestroy()

◆ hiprtcVersion()