Runtime Compilation#

HIP Runtime API Reference: Runtime Compilation
Runtime Compilation

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

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_BUILTIN_OPERATION_FAILURE = 7,
  HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION = 8,
  HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION = 9,
  HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID = 10,
  HIPRTC_ERROR_INTERNAL_ERROR = 11,
  HIPRTC_ERROR_LINKING = 100
}
 
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. 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 hiprtcGetProgramLogSize (hiprtcProgram prog, size_t *logSizeRet)
 Gets the size of 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 hiprtcGetBitcode (hiprtcProgram prog, char *bitcode)
 Gets the pointer of compiled bitcode 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.



Typedef Documentation

◆ hiprtcLinkState

typedef struct ihiprtcLinkState* hiprtcLinkState

◆ hiprtcProgram

typedef struct _hiprtcProgram* hiprtcProgram

Enumeration Type Documentation

◆ 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

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

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_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 
HIPRTC_ERROR_LINKING 

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

◆ hiprtcGetBitcode()

hiprtcResult hiprtcGetBitcode ( hiprtcProgram  prog,
char *  bitcode 
)

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

Parameters
[in]progruntime compilation program instance.
[out]codechar 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]progruntime compilation program instance.
[out]codethe 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]codethe 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

◆ hiprtcGetProgramLogSize()

hiprtcResult hiprtcGetProgramLogSize ( hiprtcProgram  prog,
size_t *  logSizeRet 
)

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

Parameters
[in]progruntime compilation program instance.
[out]logSizeRetsize 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]hiprtclink 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]hiprtclink 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]hiprtclink 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]hiprtclink state instance
Returns
HIPRTC_SUCCESS
See also
hiprtcResult

◆ hiprtcLinkDestroy()

hiprtcResult hiprtcLinkDestroy ( hiprtcLinkState  hip_link_state)

Deletes the link instance via hiprtc APIs.

Parameters
[in]hiprtclink state instance
[out]codethe 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]majorHIP Runtime Compilation major version.
[out]minorHIP Runtime Compilation minor version.