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 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder( 83 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB); 84 85 /** 86 * Set an ObjectLinkingLayer creator function for this LLJIT instance. 87 */ 88 void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator( 89 LLVMOrcLLJITBuilderRef Builder, 90 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx); 91 92 /** 93 * Create an LLJIT instance from an LLJITBuilder. 94 * 95 * This operation takes ownership of the Builder argument: clients should not 96 * dispose of the builder after calling this function (even if the function 97 * returns an error). If a null Builder argument is provided then a 98 * default-constructed LLJITBuilder will be used. 99 * 100 * On success the resulting LLJIT instance is uniquely owned by the client and 101 * automatically manages the memory of all JIT'd code and all modules that are 102 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the 103 * LLJIT instance will free all memory managed by the JIT, including JIT'd code 104 * and not-yet compiled modules. 105 */ 106 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result, 107 LLVMOrcLLJITBuilderRef Builder); 108 109 /** 110 * Dispose of an LLJIT instance. 111 */ 112 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J); 113 114 /** 115 * Get a reference to the ExecutionSession for this LLJIT instance. 116 * 117 * The ExecutionSession is owned by the LLJIT instance. The client is not 118 * responsible for managing its memory. 119 */ 120 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J); 121 122 /** 123 * Return a reference to the Main JITDylib. 124 * 125 * The JITDylib is owned by the LLJIT instance. The client is not responsible 126 * for managing its memory. 127 */ 128 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J); 129 130 /** 131 * Return the target triple for this LLJIT instance. This string is owned by 132 * the LLJIT instance and should not be freed by the client. 133 */ 134 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J); 135 136 /** 137 * Returns the global prefix character according to the LLJIT's DataLayout. 138 */ 139 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J); 140 141 /** 142 * Mangles the given string according to the LLJIT instance's DataLayout, then 143 * interns the result in the SymbolStringPool and returns a reference to the 144 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to 145 * decrement the ref-count on the pool entry once they are finished with this 146 * value. 147 */ 148 LLVMOrcSymbolStringPoolEntryRef 149 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName); 150 151 /** 152 * Add a buffer representing an object file to the given JITDylib in the given 153 * LLJIT instance. This operation transfers ownership of the buffer to the 154 * LLJIT instance. The buffer should not be disposed of or referenced once this 155 * function returns. 156 * 157 * Resources associated with the given object will be tracked by the given 158 * JITDylib's default resource tracker. 159 */ 160 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, 161 LLVMMemoryBufferRef ObjBuffer); 162 163 /** 164 * Add a buffer representing an object file to the given ResourceTracker's 165 * JITDylib in the given LLJIT instance. This operation transfers ownership of 166 * the buffer to the LLJIT instance. The buffer should not be disposed of or 167 * referenced once this function returns. 168 * 169 * Resources associated with the given object will be tracked by ResourceTracker 170 * RT. 171 */ 172 LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, 173 LLVMOrcResourceTrackerRef RT, 174 LLVMMemoryBufferRef ObjBuffer); 175 176 /** 177 * Add an IR module to the given JITDylib in the given LLJIT instance. This 178 * operation transfers ownership of the TSM argument to the LLJIT instance. 179 * The TSM argument should not be disposed of or referenced once this 180 * function returns. 181 * 182 * Resources associated with the given Module will be tracked by the given 183 * JITDylib's default resource tracker. 184 */ 185 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J, 186 LLVMOrcJITDylibRef JD, 187 LLVMOrcThreadSafeModuleRef TSM); 188 189 /** 190 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT 191 * instance. This operation transfers ownership of the TSM argument to the LLJIT 192 * instance. The TSM argument should not be disposed of or referenced once this 193 * function returns. 194 * 195 * Resources associated with the given Module will be tracked by ResourceTracker 196 * RT. 197 */ 198 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J, 199 LLVMOrcResourceTrackerRef JD, 200 LLVMOrcThreadSafeModuleRef TSM); 201 202 /** 203 * Look up the given symbol in the main JITDylib of the given LLJIT instance. 204 * 205 * This operation does not take ownership of the Name argument. 206 */ 207 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J, 208 LLVMOrcJITTargetAddress *Result, 209 const char *Name); 210 211 LLVM_C_EXTERN_C_END 212 213 #endif /* LLVM_C_LLJIT_H */ 214