1 /*===----------- llvm-c/LLJIT.h - OrcV2 LLJIT C bindings ----------*- C -*-===*\ 2 |* *| 3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| 4 |* Exceptions. *| 5 |* See https://llvm.org/LICENSE.txt for license information. *| 6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| 7 |* *| 8 |*===----------------------------------------------------------------------===*| 9 |* *| 10 |* This header declares the C interface to the LLJIT class in *| 11 |* libLLVMOrcJIT.a, which provides a simple MCJIT-like ORC JIT. *| 12 |* *| 13 |* Many exotic languages can interoperate with C code but have a harder time *| 14 |* with C++ due to name mangling. So in addition to C, this interface enables *| 15 |* tools written in such languages. *| 16 |* *| 17 |* Note: This interface is experimental. It is *NOT* stable, and may be *| 18 |* changed without warning. Only C API usage documentation is *| 19 |* provided. See the C++ documentation for all higher level ORC API *| 20 |* details. *| 21 |* *| 22 \*===----------------------------------------------------------------------===*/ 23 24 #ifndef LLVM_C_LLJIT_H 25 #define LLVM_C_LLJIT_H 26 27 #include "llvm-c/Error.h" 28 #include "llvm-c/Orc.h" 29 #include "llvm-c/TargetMachine.h" 30 #include "llvm-c/Types.h" 31 #include "llvm-c/Visibility.h" 32 33 LLVM_C_EXTERN_C_BEGIN 34 35 /** 36 * @defgroup LLVMCExecutionEngineLLJIT LLJIT 37 * @ingroup LLVMCExecutionEngine 38 * 39 * @{ 40 */ 41 42 /** 43 * A function for constructing an ObjectLinkingLayer instance to be used 44 * by an LLJIT instance. 45 * 46 * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to 47 * set the creator function to use when constructing an LLJIT instance. 48 * This can be used to override the default linking layer implementation 49 * that would otherwise be chosen by LLJITBuilder. 50 * 51 * Object linking layers returned by this function will become owned by the 52 * LLJIT instance. The client is not responsible for managing their lifetimes 53 * after the function returns. 54 */ 55 typedef LLVMOrcObjectLayerRef ( 56 *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)( 57 void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple); 58 59 /** 60 * A reference to an orc::LLJITBuilder instance. 61 */ 62 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef; 63 64 /** 65 * A reference to an orc::LLJIT instance. 66 */ 67 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef; 68 69 /** 70 * Create an LLVMOrcLLJITBuilder. 71 * 72 * The client owns the resulting LLJITBuilder and should dispose of it using 73 * LLVMOrcDisposeLLJITBuilder once they are done with it. 74 */ 75 LLVM_C_ABI LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void); 76 77 /** 78 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership 79 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented 80 * that function from being called). 81 */ 82 LLVM_C_ABI void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder); 83 84 /** 85 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT 86 * instance. Calling this function is optional: if it is not called then the 87 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a 88 * JITTargetMachineBuilder. 89 * 90 * This function takes ownership of the JTMB argument: clients should not 91 * dispose of the JITTargetMachineBuilder after calling this function. 92 */ 93 LLVM_C_ABI void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder( 94 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB); 95 96 /** 97 * Set an ObjectLinkingLayer creator function for this LLJIT instance. 98 */ 99 LLVM_C_ABI void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator( 100 LLVMOrcLLJITBuilderRef Builder, 101 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx); 102 103 /** 104 * Create an LLJIT instance from an LLJITBuilder. 105 * 106 * This operation takes ownership of the Builder argument: clients should not 107 * dispose of the builder after calling this function (even if the function 108 * returns an error). If a null Builder argument is provided then a 109 * default-constructed LLJITBuilder will be used. 110 * 111 * On success the resulting LLJIT instance is uniquely owned by the client and 112 * automatically manages the memory of all JIT'd code and all modules that are 113 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the 114 * LLJIT instance will free all memory managed by the JIT, including JIT'd code 115 * and not-yet compiled modules. 116 */ 117 LLVM_C_ABI LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result, 118 LLVMOrcLLJITBuilderRef Builder); 119 120 /** 121 * Dispose of an LLJIT instance. 122 */ 123 LLVM_C_ABI LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J); 124 125 /** 126 * Get a reference to the ExecutionSession for this LLJIT instance. 127 * 128 * The ExecutionSession is owned by the LLJIT instance. The client is not 129 * responsible for managing its memory. 130 */ 131 LLVM_C_ABI LLVMOrcExecutionSessionRef 132 LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J); 133 134 /** 135 * Return a reference to the Main JITDylib. 136 * 137 * The JITDylib is owned by the LLJIT instance. The client is not responsible 138 * for managing its memory. 139 */ 140 LLVM_C_ABI LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J); 141 142 /** 143 * Return the target triple for this LLJIT instance. This string is owned by 144 * the LLJIT instance and should not be freed by the client. 145 */ 146 LLVM_C_ABI const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J); 147 148 /** 149 * Returns the global prefix character according to the LLJIT's DataLayout. 150 */ 151 LLVM_C_ABI char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J); 152 153 /** 154 * Mangles the given string according to the LLJIT instance's DataLayout, then 155 * interns the result in the SymbolStringPool and returns a reference to the 156 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to 157 * decrement the ref-count on the pool entry once they are finished with this 158 * value. 159 */ 160 LLVM_C_ABI LLVMOrcSymbolStringPoolEntryRef 161 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName); 162 163 /** 164 * Add a buffer representing an object file to the given JITDylib in the given 165 * LLJIT instance. This operation transfers ownership of the buffer to the 166 * LLJIT instance. The buffer should not be disposed of or referenced once this 167 * function returns. 168 * 169 * Resources associated with the given object will be tracked by the given 170 * JITDylib's default resource tracker. 171 */ 172 LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddObjectFile( 173 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMMemoryBufferRef ObjBuffer); 174 175 /** 176 * Add a buffer representing an object file to the given ResourceTracker's 177 * JITDylib in the given LLJIT instance. This operation transfers ownership of 178 * the buffer to the LLJIT instance. The buffer should not be disposed of or 179 * referenced once this function returns. 180 * 181 * Resources associated with the given object will be tracked by ResourceTracker 182 * RT. 183 */ 184 LLVM_C_ABI LLVMErrorRef 185 LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef RT, 186 LLVMMemoryBufferRef ObjBuffer); 187 188 /** 189 * Add an IR module to the given JITDylib in the given LLJIT instance. This 190 * operation transfers ownership of the TSM argument to the LLJIT instance. 191 * The TSM argument should not be disposed of or referenced once this 192 * function returns. 193 * 194 * Resources associated with the given Module will be tracked by the given 195 * JITDylib's default resource tracker. 196 */ 197 LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule( 198 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMOrcThreadSafeModuleRef TSM); 199 200 /** 201 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT 202 * instance. This operation transfers ownership of the TSM argument to the LLJIT 203 * instance. The TSM argument should not be disposed of or referenced once this 204 * function returns. 205 * 206 * Resources associated with the given Module will be tracked by ResourceTracker 207 * RT. 208 */ 209 LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT( 210 LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef JD, 211 LLVMOrcThreadSafeModuleRef TSM); 212 213 /** 214 * Look up the given symbol in the main JITDylib of the given LLJIT instance. 215 * 216 * This operation does not take ownership of the Name argument. 217 */ 218 LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J, 219 LLVMOrcExecutorAddress *Result, 220 const char *Name); 221 222 /** 223 * Returns a non-owning reference to the LLJIT instance's object linking layer. 224 */ 225 LLVM_C_ABI LLVMOrcObjectLayerRef 226 LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J); 227 228 /** 229 * Returns a non-owning reference to the LLJIT instance's object linking layer. 230 */ 231 LLVM_C_ABI LLVMOrcObjectTransformLayerRef 232 LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J); 233 234 /** 235 * Returns a non-owning reference to the LLJIT instance's IR transform layer. 236 */ 237 LLVM_C_ABI LLVMOrcIRTransformLayerRef 238 LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J); 239 240 /** 241 * Get the LLJIT instance's default data layout string. 242 * 243 * This string is owned by the LLJIT instance and does not need to be freed 244 * by the caller. 245 */ 246 LLVM_C_ABI const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J); 247 248 /** 249 * @} 250 */ 251 252 LLVM_C_EXTERN_C_END 253 254 #endif /* LLVM_C_LLJIT_H */ 255