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 32 LLVM_C_EXTERN_C_BEGIN 33 34 /** 35 * @defgroup LLVMCExecutionEngineLLJIT LLJIT 36 * @ingroup LLVMCExecutionEngine 37 * 38 * @{ 39 */ 40 41 /** 42 * A function for constructing an ObjectLinkingLayer instance to be used 43 * by an LLJIT instance. 44 * 45 * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to 46 * set the creator function to use when constructing an LLJIT instance. 47 * This can be used to override the default linking layer implementation 48 * that would otherwise be chosen by LLJITBuilder. 49 * 50 * Object linking layers returned by this function will become owned by the 51 * LLJIT instance. The client is not responsible for managing their lifetimes 52 * after the function returns. 53 */ 54 typedef LLVMOrcObjectLayerRef ( 55 *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)( 56 void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple); 57 58 /** 59 * A reference to an orc::LLJITBuilder instance. 60 */ 61 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef; 62 63 /** 64 * A reference to an orc::LLJIT instance. 65 */ 66 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef; 67 68 /** 69 * Create an LLVMOrcLLJITBuilder. 70 * 71 * The client owns the resulting LLJITBuilder and should dispose of it using 72 * LLVMOrcDisposeLLJITBuilder once they are done with it. 73 */ 74 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void); 75 76 /** 77 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership 78 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented 79 * that function from being called). 80 */ 81 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder); 82 83 /** 84 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT 85 * instance. Calling this function is optional: if it is not called then the 86 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a 87 * JITTargetMachineBuilder. 88 * 89 * This function takes ownership of the JTMB argument: clients should not 90 * dispose of the JITTargetMachineBuilder after calling this function. 91 */ 92 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder( 93 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB); 94 95 /** 96 * Set an ObjectLinkingLayer creator function for this LLJIT instance. 97 */ 98 void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator( 99 LLVMOrcLLJITBuilderRef Builder, 100 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx); 101 102 /** 103 * Create an LLJIT instance from an LLJITBuilder. 104 * 105 * This operation takes ownership of the Builder argument: clients should not 106 * dispose of the builder after calling this function (even if the function 107 * returns an error). If a null Builder argument is provided then a 108 * default-constructed LLJITBuilder will be used. 109 * 110 * On success the resulting LLJIT instance is uniquely owned by the client and 111 * automatically manages the memory of all JIT'd code and all modules that are 112 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the 113 * LLJIT instance will free all memory managed by the JIT, including JIT'd code 114 * and not-yet compiled modules. 115 */ 116 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result, 117 LLVMOrcLLJITBuilderRef Builder); 118 119 /** 120 * Dispose of an LLJIT instance. 121 */ 122 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J); 123 124 /** 125 * Get a reference to the ExecutionSession for this LLJIT instance. 126 * 127 * The ExecutionSession is owned by the LLJIT instance. The client is not 128 * responsible for managing its memory. 129 */ 130 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J); 131 132 /** 133 * Return a reference to the Main JITDylib. 134 * 135 * The JITDylib is owned by the LLJIT instance. The client is not responsible 136 * for managing its memory. 137 */ 138 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J); 139 140 /** 141 * Return the target triple for this LLJIT instance. This string is owned by 142 * the LLJIT instance and should not be freed by the client. 143 */ 144 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J); 145 146 /** 147 * Returns the global prefix character according to the LLJIT's DataLayout. 148 */ 149 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J); 150 151 /** 152 * Mangles the given string according to the LLJIT instance's DataLayout, then 153 * interns the result in the SymbolStringPool and returns a reference to the 154 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to 155 * decrement the ref-count on the pool entry once they are finished with this 156 * value. 157 */ 158 LLVMOrcSymbolStringPoolEntryRef 159 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName); 160 161 /** 162 * Add a buffer representing an object file to the given JITDylib in the given 163 * LLJIT instance. This operation transfers ownership of the buffer to the 164 * LLJIT instance. The buffer should not be disposed of or referenced once this 165 * function returns. 166 * 167 * Resources associated with the given object will be tracked by the given 168 * JITDylib's default resource tracker. 169 */ 170 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, 171 LLVMMemoryBufferRef ObjBuffer); 172 173 /** 174 * Add a buffer representing an object file to the given ResourceTracker's 175 * JITDylib in the given LLJIT instance. This operation transfers ownership of 176 * the buffer to the LLJIT instance. The buffer should not be disposed of or 177 * referenced once this function returns. 178 * 179 * Resources associated with the given object will be tracked by ResourceTracker 180 * RT. 181 */ 182 LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, 183 LLVMOrcResourceTrackerRef RT, 184 LLVMMemoryBufferRef ObjBuffer); 185 186 /** 187 * Add an IR module to the given JITDylib in the given LLJIT instance. This 188 * operation transfers ownership of the TSM argument to the LLJIT instance. 189 * The TSM argument should not be disposed of or referenced once this 190 * function returns. 191 * 192 * Resources associated with the given Module will be tracked by the given 193 * JITDylib's default resource tracker. 194 */ 195 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J, 196 LLVMOrcJITDylibRef JD, 197 LLVMOrcThreadSafeModuleRef TSM); 198 199 /** 200 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT 201 * instance. This operation transfers ownership of the TSM argument to the LLJIT 202 * instance. The TSM argument should not be disposed of or referenced once this 203 * function returns. 204 * 205 * Resources associated with the given Module will be tracked by ResourceTracker 206 * RT. 207 */ 208 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J, 209 LLVMOrcResourceTrackerRef JD, 210 LLVMOrcThreadSafeModuleRef TSM); 211 212 /** 213 * Look up the given symbol in the main JITDylib of the given LLJIT instance. 214 * 215 * This operation does not take ownership of the Name argument. 216 */ 217 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J, 218 LLVMOrcExecutorAddress *Result, 219 const char *Name); 220 221 /** 222 * Returns a non-owning reference to the LLJIT instance's object linking layer. 223 */ 224 LLVMOrcObjectLayerRef LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J); 225 226 /** 227 * Returns a non-owning reference to the LLJIT instance's object linking layer. 228 */ 229 LLVMOrcObjectTransformLayerRef 230 LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J); 231 232 /** 233 * Returns a non-owning reference to the LLJIT instance's IR transform layer. 234 */ 235 LLVMOrcIRTransformLayerRef LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J); 236 237 /** 238 * Get the LLJIT instance's default data layout string. 239 * 240 * This string is owned by the LLJIT instance and does not need to be freed 241 * by the caller. 242 */ 243 const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J); 244 245 /** 246 * @} 247 */ 248 249 LLVM_C_EXTERN_C_END 250 251 #endif /* LLVM_C_LLJIT_H */ 252