/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hip/checkouts/latest/include/hip/hiprtc.h Source File#

HIP Runtime API Reference: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hip/checkouts/latest/include/hip/hiprtc.h Source File
hiprtc.h
Go to the documentation of this file.
1 /*
2 Copyright (c) 2015 - 2023 Advanced Micro Devices, Inc. All rights reserved.
3 
4 Permission is hereby granted, free of charge, to any person obtaining a copy
5 of this software and associated documentation files (the "Software"), to deal
6 in the Software without restriction, including without limitation the rights
7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 copies of the Software, and to permit persons to whom the Software is
9 furnished to do so, subject to the following conditions:
10 
11 The above copyright notice and this permission notice shall be included in
12 all copies or substantial portions of the Software.
13 
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 THE SOFTWARE.
21 */
22 #pragma once
23 
24 #include <hip/hip_common.h>
25 
26 #if !defined(__HIP_PLATFORM_AMD__) && defined(__HIP_PLATFORM_NVIDIA__)
27 #include <hip/nvidia_detail/nvidia_hiprtc.h>
28 #elif defined(__HIP_PLATFORM_AMD__) && !defined(__HIP_PLATFORM_NVIDIA__)
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif /* __cplusplus */
33 
34 #include <stdlib.h>
35 
36 #if !defined(_WIN32)
37 #pragma GCC visibility push(default)
38 #endif
39 
49 typedef enum hiprtcResult {
50  HIPRTC_SUCCESS = 0,
51  HIPRTC_ERROR_OUT_OF_MEMORY = 1,
52  HIPRTC_ERROR_PROGRAM_CREATION_FAILURE = 2,
53  HIPRTC_ERROR_INVALID_INPUT = 3,
54  HIPRTC_ERROR_INVALID_PROGRAM = 4,
55  HIPRTC_ERROR_INVALID_OPTION = 5,
56  HIPRTC_ERROR_COMPILATION = 6,
57  HIPRTC_ERROR_BUILTIN_OPERATION_FAILURE = 7,
58  HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION = 8,
59  HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION = 9,
60  HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID = 10,
61  HIPRTC_ERROR_INTERNAL_ERROR = 11,
62  HIPRTC_ERROR_LINKING = 100
63 } hiprtcResult;
64 
69 typedef enum hiprtcJIT_option {
70  HIPRTC_JIT_MAX_REGISTERS = 0,
71  HIPRTC_JIT_THREADS_PER_BLOCK,
72  HIPRTC_JIT_WALL_TIME,
73  HIPRTC_JIT_INFO_LOG_BUFFER,
74  HIPRTC_JIT_INFO_LOG_BUFFER_SIZE_BYTES,
75  HIPRTC_JIT_ERROR_LOG_BUFFER,
76  HIPRTC_JIT_ERROR_LOG_BUFFER_SIZE_BYTES,
77  HIPRTC_JIT_OPTIMIZATION_LEVEL,
78  HIPRTC_JIT_TARGET_FROM_HIPCONTEXT,
79  HIPRTC_JIT_TARGET,
80  HIPRTC_JIT_FALLBACK_STRATEGY,
81  HIPRTC_JIT_GENERATE_DEBUG_INFO,
82  HIPRTC_JIT_LOG_VERBOSE,
83  HIPRTC_JIT_GENERATE_LINE_INFO,
84  HIPRTC_JIT_CACHE_MODE,
85  HIPRTC_JIT_NEW_SM3X_OPT,
86  HIPRTC_JIT_FAST_COMPILE,
87  HIPRTC_JIT_GLOBAL_SYMBOL_NAMES,
88  HIPRTC_JIT_GLOBAL_SYMBOL_ADDRESS,
89  HIPRTC_JIT_GLOBAL_SYMBOL_COUNT,
90  HIPRTC_JIT_LTO,
91  HIPRTC_JIT_FTZ,
92  HIPRTC_JIT_PREC_DIV,
94  HIPRTC_JIT_PREC_SQRT,
95  HIPRTC_JIT_FMA,
96  HIPRTC_JIT_NUM_OPTIONS,
97  HIPRTC_JIT_IR_TO_ISA_OPT_EXT = 10000,
99  HIPRTC_JIT_IR_TO_ISA_OPT_COUNT_EXT,
101 } hiprtcJIT_option;
102 
106 typedef enum hiprtcJITInputType {
107  HIPRTC_JIT_INPUT_CUBIN = 0,
108  HIPRTC_JIT_INPUT_PTX,
109  HIPRTC_JIT_INPUT_FATBINARY,
110  HIPRTC_JIT_INPUT_OBJECT,
111  HIPRTC_JIT_INPUT_LIBRARY,
112  HIPRTC_JIT_INPUT_NVVM,
113  HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES,
114  HIPRTC_JIT_INPUT_LLVM_BITCODE = 100,
115  HIPRTC_JIT_INPUT_LLVM_BUNDLED_BITCODE = 101,
116  HIPRTC_JIT_INPUT_LLVM_ARCHIVES_OF_BUNDLED_BITCODE = 102,
117  HIPRTC_JIT_NUM_INPUT_TYPES = (HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES + 3)
118 } hiprtcJITInputType;
127 typedef struct ihiprtcLinkState* hiprtcLinkState;
141 const char* hiprtcGetErrorString(hiprtcResult result);
142 
153 hiprtcResult hiprtcVersion(int* major, int* minor);
154 
159 typedef struct _hiprtcProgram* hiprtcProgram;
160 
173 hiprtcResult hiprtcAddNameExpression(hiprtcProgram prog,
174  const char* name_expression);
175 
190 hiprtcResult hiprtcCompileProgram(hiprtcProgram prog,
191  int numOptions,
192  const char** options);
193 
214 hiprtcResult hiprtcCreateProgram(hiprtcProgram* prog,
215  const char* src,
216  const char* name,
217  int numHeaders,
218  const char** headers,
219  const char** includeNames);
220 
231 hiprtcResult hiprtcDestroyProgram(hiprtcProgram* prog);
232 
250 hiprtcResult hiprtcGetLoweredName(hiprtcProgram prog,
251  const char* name_expression,
252  const char** lowered_name);
253 
263 hiprtcResult hiprtcGetProgramLog(hiprtcProgram prog, char* log);
264 
274 hiprtcResult hiprtcGetProgramLogSize(hiprtcProgram prog,
275  size_t* logSizeRet);
276 
286 hiprtcResult hiprtcGetCode(hiprtcProgram prog, char* code);
287 
297 hiprtcResult hiprtcGetCodeSize(hiprtcProgram prog, size_t* codeSizeRet);
298 
308 hiprtcResult hiprtcGetBitcode(hiprtcProgram prog, char* bitcode);
309 
320 hiprtcResult hiprtcGetBitcodeSize(hiprtcProgram prog, size_t* bitcode_size);
321 
334 hiprtcResult hiprtcLinkCreate(unsigned int num_options, hiprtcJIT_option* option_ptr,
335  void** option_vals_pptr, hiprtcLinkState* hip_link_state_ptr);
336 
355 hiprtcResult hiprtcLinkAddFile(hiprtcLinkState hip_link_state, hiprtcJITInputType input_type,
356  const char* file_path, unsigned int num_options,
357  hiprtcJIT_option* options_ptr, void** option_values);
358 
379 hiprtcResult hiprtcLinkAddData(hiprtcLinkState hip_link_state, hiprtcJITInputType input_type,
380  void* image, size_t image_size, const char* name,
381  unsigned int num_options, hiprtcJIT_option* options_ptr,
382  void** option_values);
383 
398 hiprtcResult hiprtcLinkComplete(hiprtcLinkState hip_link_state, void** bin_out, size_t* size_out);
399 
409 hiprtcResult hiprtcLinkDestroy(hiprtcLinkState hip_link_state);
410 
411 #if !defined(_WIN32)
412 #pragma GCC visibility pop
413 #endif
414 
415 #ifdef __cplusplus
416 }
417 #endif /* __cplusplus */
418 
419 #else
420 #error("Must define exactly one of __HIP_PLATFORM_AMD__ or __HIP_PLATFORM_NVIDIA__");
421 #endif
hiprtcJITInputType
hiprtcJITInputType
Definition: hiprtc.h:106
hiprtcResult
hiprtcResult
Definition: hiprtc.h:49
hiprtcJIT_option
hiprtcJIT_option
Definition: hiprtc.h:69
HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES
@ HIPRTC_JIT_NUM_LEGACY_INPUT_TYPES
Number of legacy input type.
Definition: hiprtc.h:113
HIPRTC_JIT_INPUT_CUBIN
@ HIPRTC_JIT_INPUT_CUBIN
Input cubin.
Definition: hiprtc.h:107
HIPRTC_JIT_INPUT_PTX
@ HIPRTC_JIT_INPUT_PTX
Input PTX.
Definition: hiprtc.h:108
HIPRTC_JIT_INPUT_FATBINARY
@ HIPRTC_JIT_INPUT_FATBINARY
Input fat binary.
Definition: hiprtc.h:109
HIPRTC_JIT_INPUT_LIBRARY
@ HIPRTC_JIT_INPUT_LIBRARY
Input library.
Definition: hiprtc.h:111
HIPRTC_JIT_INPUT_LLVM_BUNDLED_BITCODE
@ HIPRTC_JIT_INPUT_LLVM_BUNDLED_BITCODE
LLVM bundled bitcode.
Definition: hiprtc.h:115
HIPRTC_JIT_INPUT_NVVM
@ HIPRTC_JIT_INPUT_NVVM
Input NVVM.
Definition: hiprtc.h:112
HIPRTC_JIT_INPUT_LLVM_BITCODE
@ HIPRTC_JIT_INPUT_LLVM_BITCODE
LLVM bitcode or IR assembly.
Definition: hiprtc.h:114
HIPRTC_JIT_INPUT_OBJECT
@ HIPRTC_JIT_INPUT_OBJECT
Input object.
Definition: hiprtc.h:110
HIPRTC_JIT_INPUT_LLVM_ARCHIVES_OF_BUNDLED_BITCODE
@ HIPRTC_JIT_INPUT_LLVM_ARCHIVES_OF_BUNDLED_BITCODE
LLVM archives of boundled bitcode.
Definition: hiprtc.h:116
HIPRTC_JIT_NUM_INPUT_TYPES
@ HIPRTC_JIT_NUM_INPUT_TYPES
Definition: hiprtc.h:117
HIPRTC_ERROR_PROGRAM_CREATION_FAILURE
@ HIPRTC_ERROR_PROGRAM_CREATION_FAILURE
Failed to create program.
Definition: hiprtc.h:52
HIPRTC_ERROR_INVALID_PROGRAM
@ HIPRTC_ERROR_INVALID_PROGRAM
Invalid program.
Definition: hiprtc.h:54
HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION
@ HIPRTC_ERROR_NO_NAME_EXPRESSIONS_AFTER_COMPILATION
No name expression after compilation.
Definition: hiprtc.h:58
HIPRTC_ERROR_INVALID_OPTION
@ HIPRTC_ERROR_INVALID_OPTION
Invalid option.
Definition: hiprtc.h:55
HIPRTC_ERROR_INVALID_INPUT
@ HIPRTC_ERROR_INVALID_INPUT
Invalid input.
Definition: hiprtc.h:53
HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID
@ HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID
Invalid name expression.
Definition: hiprtc.h:60
HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION
@ HIPRTC_ERROR_NO_LOWERED_NAMES_BEFORE_COMPILATION
No lowered names before compilation.
Definition: hiprtc.h:59
HIPRTC_SUCCESS
@ HIPRTC_SUCCESS
Success.
Definition: hiprtc.h:50
HIPRTC_ERROR_BUILTIN_OPERATION_FAILURE
@ HIPRTC_ERROR_BUILTIN_OPERATION_FAILURE
Failed in builtin operation.
Definition: hiprtc.h:57
HIPRTC_ERROR_INTERNAL_ERROR
@ HIPRTC_ERROR_INTERNAL_ERROR
Internal error.
Definition: hiprtc.h:61
HIPRTC_ERROR_COMPILATION
@ HIPRTC_ERROR_COMPILATION
Compilation error.
Definition: hiprtc.h:56
HIPRTC_ERROR_OUT_OF_MEMORY
@ HIPRTC_ERROR_OUT_OF_MEMORY
Out of memory.
Definition: hiprtc.h:51
HIPRTC_ERROR_LINKING
@ HIPRTC_ERROR_LINKING
Error in linking.
Definition: hiprtc.h:62
HIPRTC_JIT_FAST_COMPILE
@ HIPRTC_JIT_FAST_COMPILE
CUDA Only Set fast compile.
Definition: hiprtc.h:86
HIPRTC_JIT_INFO_LOG_BUFFER
@ HIPRTC_JIT_INFO_LOG_BUFFER
CUDA Only Pointer to the buffer with logged information.
Definition: hiprtc.h:73
HIPRTC_JIT_WALL_TIME
@ HIPRTC_JIT_WALL_TIME
CUDA Only Value for total wall clock time.
Definition: hiprtc.h:72
HIPRTC_JIT_ERROR_LOG_BUFFER
@ HIPRTC_JIT_ERROR_LOG_BUFFER
CUDA Only Pointer to the buffer with logged error(s)
Definition: hiprtc.h:75
HIPRTC_JIT_GENERATE_LINE_INFO
@ HIPRTC_JIT_GENERATE_LINE_INFO
CUDA Only Generate line number information.
Definition: hiprtc.h:83
HIPRTC_JIT_IR_TO_ISA_OPT_EXT
@ HIPRTC_JIT_IR_TO_ISA_OPT_EXT
Definition: hiprtc.h:97
HIPRTC_JIT_TARGET
@ HIPRTC_JIT_TARGET
CUDA Only JIT target.
Definition: hiprtc.h:79
HIPRTC_JIT_LOG_VERBOSE
@ HIPRTC_JIT_LOG_VERBOSE
CUDA Only Generate log verbose.
Definition: hiprtc.h:82
HIPRTC_JIT_INFO_LOG_BUFFER_SIZE_BYTES
@ HIPRTC_JIT_INFO_LOG_BUFFER_SIZE_BYTES
CUDA Only Size of the buffer in bytes for logged info.
Definition: hiprtc.h:74
HIPRTC_JIT_PREC_DIV
@ HIPRTC_JIT_PREC_DIV
Definition: hiprtc.h:92
HIPRTC_JIT_ERROR_LOG_BUFFER_SIZE_BYTES
@ HIPRTC_JIT_ERROR_LOG_BUFFER_SIZE_BYTES
CUDA Only Size of the buffer in bytes for logged error(s)
Definition: hiprtc.h:76
HIPRTC_JIT_GENERATE_DEBUG_INFO
@ HIPRTC_JIT_GENERATE_DEBUG_INFO
CUDA Only Generate debug information.
Definition: hiprtc.h:81
HIPRTC_JIT_THREADS_PER_BLOCK
@ HIPRTC_JIT_THREADS_PER_BLOCK
CUDA Only Number of thread per block.
Definition: hiprtc.h:71
HIPRTC_JIT_MAX_REGISTERS
@ HIPRTC_JIT_MAX_REGISTERS
CUDA Only Maximum registers may be used in a thread, passed to compiler.
Definition: hiprtc.h:70
HIPRTC_JIT_NUM_OPTIONS
@ HIPRTC_JIT_NUM_OPTIONS
Number of options.
Definition: hiprtc.h:96
HIPRTC_JIT_NEW_SM3X_OPT
@ HIPRTC_JIT_NEW_SM3X_OPT
Definition: hiprtc.h:85
HIPRTC_JIT_TARGET_FROM_HIPCONTEXT
@ HIPRTC_JIT_TARGET_FROM_HIPCONTEXT
CUDA Only The target context, which is the default.
Definition: hiprtc.h:78
HIPRTC_JIT_OPTIMIZATION_LEVEL
@ HIPRTC_JIT_OPTIMIZATION_LEVEL
Value of optimization level for generated codes, acceptable options -O0, -O1, -O2,...
Definition: hiprtc.h:77
HIPRTC_JIT_GLOBAL_SYMBOL_NAMES
@ HIPRTC_JIT_GLOBAL_SYMBOL_NAMES
CUDA Only Array of device symbol names to be relocated to the host.
Definition: hiprtc.h:87
HIPRTC_JIT_FTZ
@ HIPRTC_JIT_FTZ
Definition: hiprtc.h:91
HIPRTC_JIT_IR_TO_ISA_OPT_COUNT_EXT
@ HIPRTC_JIT_IR_TO_ISA_OPT_COUNT_EXT
Definition: hiprtc.h:99
HIPRTC_JIT_GLOBAL_SYMBOL_COUNT
@ HIPRTC_JIT_GLOBAL_SYMBOL_COUNT
CUDA Only Number of symbol count.
Definition: hiprtc.h:89
HIPRTC_JIT_CACHE_MODE
@ HIPRTC_JIT_CACHE_MODE
CUDA Only Set cache mode.
Definition: hiprtc.h:84
HIPRTC_JIT_FALLBACK_STRATEGY
@ HIPRTC_JIT_FALLBACK_STRATEGY
CUDA Only Fallback strategy.
Definition: hiprtc.h:80
HIPRTC_JIT_PREC_SQRT
@ HIPRTC_JIT_PREC_SQRT
Definition: hiprtc.h:94
HIPRTC_JIT_GLOBAL_SYMBOL_ADDRESS
@ HIPRTC_JIT_GLOBAL_SYMBOL_ADDRESS
CUDA Only Array of host addresses to be relocated to the device.
Definition: hiprtc.h:88
HIPRTC_JIT_LTO
@ HIPRTC_JIT_LTO
Definition: hiprtc.h:90
HIPRTC_JIT_FMA
@ HIPRTC_JIT_FMA
Definition: hiprtc.h:95
log
__DEVICE__ double log(double __x)
Returns the natural logarithm of x.
Definition: __clang_hip_math.h:958
hiprtcAddNameExpression
hiprtcResult hiprtcAddNameExpression(hiprtcProgram prog, const char *name_expression)
Adds the given name exprssion to the runtime compilation program.
hiprtcLinkComplete
hiprtcResult hiprtcLinkComplete(hiprtcLinkState hip_link_state, void **bin_out, size_t *size_out)
Completes the linking of the given program.
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.
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,...
hiprtcGetErrorString
const char * hiprtcGetErrorString(hiprtcResult result)
Returns text string message to explain the error which occurred.
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 hiprtcProgr...
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.
hiprtcGetCodeSize
hiprtcResult hiprtcGetCodeSize(hiprtcProgram prog, size_t *codeSizeRet)
Gets the size of compilation binary by the runtime compilation program instance.
hiprtcLinkDestroy
hiprtcResult hiprtcLinkDestroy(hiprtcLinkState hip_link_state)
Deletes the link instance via hiprtc APIs.
hiprtcGetProgramLog
hiprtcResult hiprtcGetProgramLog(hiprtcProgram prog, char *log)
Gets the log generated by the runtime compilation program instance.
hiprtcCompileProgram
hiprtcResult hiprtcCompileProgram(hiprtcProgram prog, int numOptions, const char **options)
Compiles the given runtime compilation program.
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.
hiprtcGetBitcodeSize
hiprtcResult hiprtcGetBitcodeSize(hiprtcProgram prog, size_t *bitcode_size)
Gets the size of compiled bitcode by the runtime compilation program instance.
hiprtcDestroyProgram
hiprtcResult hiprtcDestroyProgram(hiprtcProgram *prog)
Destroys an instance of given hiprtcProgram.
hiprtcGetCode
hiprtcResult hiprtcGetCode(hiprtcProgram prog, char *code)
Gets the pointer of compilation binary by the runtime compilation program instance.
hiprtcVersion
hiprtcResult hiprtcVersion(int *major, int *minor)
Sets the parameters as major and minor version.
hip_common.h
hiprtcGetProgramLogSize
hiprtcResult hiprtcGetProgramLogSize(hiprtcProgram prog, size_t *logSizeRet)
Gets the size of log generated by the runtime compilation program instance.
hiprtcGetBitcode
hiprtcResult hiprtcGetBitcode(hiprtcProgram prog, char *bitcode)
Gets the pointer of compiled bitcode by the runtime compilation program instance.
hiprtcLinkState
struct ihiprtcLinkState * hiprtcLinkState
Definition: hiprtc.h:127
hiprtcProgram
struct _hiprtcProgram * hiprtcProgram
Definition: hiprtc.h:159