Runtime Compilation

Runtime Compilation#

HIP Runtime API Reference: Runtime Compilation

Collaboration diagram for Runtime Compilation:

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	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	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.

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

◆ 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]	bitcode_size	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]	codeSizeRet	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

◆ 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]	hip_link_state	hiprtc link state
[in]	input_type	Type of the input data or bitcode
[in]	image	Input data which is null terminated
[in]	image_size	Size of the input data
[in]	name	Optional name for this input
[in]	num_options	Size of the options
[in]	options_ptr	Array of options applied to this input
[in]	option_values	Array of option values cast to void*

Returns: HIPRTC_SUCCESS, HIPRTC_ERROR_INVALID_INPUT

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]	hip_link_state	hiprtc link state
[in]	input_type	Type of the input data or bitcode
[in]	file_path	Path to the input file where bitcode is present
[in]	num_options	Size of the options
[in]	options_ptr	Array of options applied to this input
[in]	option_values	Array of option values cast to void*

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]	hip_link_state	hiprtc link state
[out]	bin_out	Upon success, points to the output binary
[out]	size_out	Size of the binary is stored (optional)

Returns: HIPRTC_SUCCESS

If adding the data fails, it will

Returns: HIPRTC_ERROR_LINKING

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]	num_options	Number of options
[in]	option_ptr	Array of options
[in]	option_vals_pptr	Array of option values cast to void*
[out]	hip_link_state_ptr	hiprtc link state created upon success

Returns: HIPRTC_SUCCESS, HIPRTC_ERROR_INVALID_INPUT, HIPRTC_ERROR_INVALID_OPTION

See also: hiprtcResult

◆ hiprtcLinkDestroy()

hiprtcResult hiprtcLinkDestroy ( hiprtcLinkState hip_link_state )

Deletes the link instance via hiprtc APIs.

Parameters

[in] hip_link_state link state instance

Returns: HIPRTC_SUCCESS

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#

Functions

Detailed Description

Function Documentation

◆ hiprtcAddNameExpression()

◆ hiprtcCompileProgram()

◆ hiprtcCreateProgram()

◆ hiprtcDestroyProgram()

◆ hiprtcGetBitcodeSize()

◆ hiprtcGetCode()

◆ hiprtcGetCodeSize()

◆ hiprtcGetErrorString()

◆ hiprtcGetLoweredName()

◆ hiprtcGetProgramLog()

◆ hiprtcLinkAddData()

◆ hiprtcLinkAddFile()

◆ hiprtcLinkComplete()

◆ hiprtcLinkCreate()

◆ hiprtcLinkDestroy()

◆ hiprtcVersion()