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