This page contains proposed changes for a future release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Runtime Compilation

Runtime Compilation#

HIP Runtime API Reference: Runtime Compilation
Runtime Compilation
Collaboration diagram for Runtime Compilation:

Functions

const char * hiprtcGetErrorString (hiprtcResult result)
 Returns text string message to explain the error which occurred. More...
 
hiprtcResult hiprtcVersion (int *major, int *minor)
 Sets the parameters as major and minor version. More...
 
hiprtcResult hiprtcAddNameExpression (hiprtcProgram prog, const char *name_expression)
 Adds the given name exprssion to the runtime compilation program. More...
 
hiprtcResult hiprtcCompileProgram (hiprtcProgram prog, int numOptions, const char **options)
 Compiles the given runtime compilation program. More...
 
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. More...
 
hiprtcResult hiprtcDestroyProgram (hiprtcProgram *prog)
 Destroys an instance of given hiprtcProgram. More...
 
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. More...
 
hiprtcResult hiprtcGetProgramLog (hiprtcProgram prog, char *log)
 Gets the log generated by the runtime compilation program instance. More...
 
hiprtcResult hiprtcGetCode (hiprtcProgram prog, char *code)
 Gets the pointer of compilation binary by the runtime compilation program instance. More...
 
hiprtcResult hiprtcGetCodeSize (hiprtcProgram prog, size_t *codeSizeRet)
 Gets the size of compilation binary by the runtime compilation program instance. More...
 
hiprtcResult hiprtcGetBitcodeSize (hiprtcProgram prog, size_t *bitcode_size)
 Gets the size of compiled bitcode by the runtime compilation program instance. More...
 
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. More...
 
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. More...
 
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. More...
 
hiprtcResult hiprtcLinkComplete (hiprtcLinkState hip_link_state, void **bin_out, size_t *size_out)
 Completes the linking of the given program. More...
 
hiprtcResult hiprtcLinkDestroy (hiprtcLinkState hip_link_state)
 Deletes the link instance via hiprtc APIs. More...
 

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]progruntime compilation program instance.
[in]name_expressionconst 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]progruntime compilation program instance.
[in]numOptionsnumber of compiler options.
[in]optionscompiler 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]progruntime compilation program instance.
[in]srcconst char pointer to the program source.
[in]nameconst char pointer to the program name.
[in]numHeadersnumber of headers.
[in]headersarray of strings pointing to headers.
[in]includeNamesarray 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]progruntime 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]progruntime compilation program instance.
[out]bitcode_sizethe 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]progruntime compilation program instance.
[out]codechar 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]progruntime compilation program instance.
[out]codeSizeRetthe 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]resultcode 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]progruntime compilation program instance.
[in]name_expressionconst char pointer to the name expression.
[in,out]lowered_nameconst 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]progruntime compilation program instance.
[out]logmemory 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_statehiprtc link state
[in]input_typeType of the input data or bitcode
[in]imageInput data which is null terminated
[in]image_sizeSize of the input data
[in]nameOptional name for this input
[in]num_optionsSize of the options
[in]options_ptrArray of options applied to this input
[in]option_valuesArray 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_statehiprtc link state
[in]input_typeType of the input data or bitcode
[in]file_pathPath to the input file where bitcode is present
[in]num_optionsSize of the options
[in]options_ptrArray of options applied to this input
[in]option_valuesArray 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_statehiprtc link state
[out]bin_outUpon success, points to the output binary
[out]size_outSize 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_optionsNumber of options
[in]option_ptrArray of options
[in]option_vals_pptrArray of option values cast to void*
[out]hip_link_state_ptrhiprtc 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_statelink 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]majorHIP Runtime Compilation major version.
[out]minorHIP Runtime Compilation minor version.
Returns
HIPRTC_ERROR_INVALID_INPUT, HIPRTC_SUCCESS