1 /*===---------------- llvm-c/Orc.h - OrcV2 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 libLLVMOrcJIT.a, which implements *| 11 |* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *| 12 |* (especially memory ownership rules) is provided. Core Orc concepts are *| 13 |* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++ *| 14 |* headers *| 15 |* *| 16 |* Many exotic languages can interoperate with C code but have a harder time *| 17 |* with C++ due to name mangling. So in addition to C, this interface enables *| 18 |* tools written in such languages. *| 19 |* *| 20 |* Note: This interface is experimental. It is *NOT* stable, and may be *| 21 |* changed without warning. Only C API usage documentation is *| 22 |* provided. See the C++ documentation for all higher level ORC API *| 23 |* details. *| 24 |* *| 25 \*===----------------------------------------------------------------------===*/ 26 27 #ifndef LLVM_C_ORC_H 28 #define LLVM_C_ORC_H 29 30 #include "llvm-c/Error.h" 31 #include "llvm-c/TargetMachine.h" 32 #include "llvm-c/Types.h" 33 34 LLVM_C_EXTERN_C_BEGIN 35 36 /** 37 * Represents an address in the target process. 38 */ 39 typedef uint64_t LLVMOrcJITTargetAddress; 40 41 /** 42 * A reference to an orc::ExecutionSession instance. 43 */ 44 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef; 45 46 /** 47 * A reference to an orc::SymbolStringPool table entry. 48 */ 49 typedef struct LLVMOrcQuaqueSymbolStringPoolEntryPtr 50 *LLVMOrcSymbolStringPoolEntryRef; 51 52 /** 53 * A reference to an orc::JITDylib instance. 54 */ 55 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef; 56 57 /** 58 * A reference to an orc::JITDylib::DefinitionGenerator. 59 */ 60 typedef struct LLVMOrcOpaqueJITDylibDefinitionGenerator 61 *LLVMOrcJITDylibDefinitionGeneratorRef; 62 63 /** 64 * Predicate function for SymbolStringPoolEntries. 65 */ 66 typedef int (*LLVMOrcSymbolPredicate)(LLVMOrcSymbolStringPoolEntryRef Sym, 67 void *Ctx); 68 69 /** 70 * A reference to an orc::ThreadSafeContext instance. 71 */ 72 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef; 73 74 /** 75 * A reference to an orc::ThreadSafeModule instance. 76 */ 77 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef; 78 79 /** 80 * A reference to an orc::JITTargetMachineBuilder instance. 81 */ 82 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder 83 *LLVMOrcJITTargetMachineBuilderRef; 84 85 /** 86 * A reference to an orc::LLJITBuilder instance. 87 */ 88 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef; 89 90 /** 91 * A reference to an orc::LLJIT instance. 92 */ 93 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef; 94 95 /** 96 * Intern a string in the ExecutionSession's SymbolStringPool and return a 97 * reference to it. This increments the ref-count of the pool entry, and the 98 * returned value should be released once the client is done with it by 99 * calling LLVMOrReleaseSymbolStringPoolEntry. 100 * 101 * Since strings are uniqued within the SymbolStringPool 102 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string 103 * equality. 104 * 105 * Note that this function does not perform linker-mangling on the string. 106 */ 107 LLVMOrcSymbolStringPoolEntryRef 108 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name); 109 110 /** 111 * Reduces the ref-count for of a SymbolStringPool entry. 112 */ 113 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 114 115 /** 116 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if 117 * ownership has not been passed to a JITDylib (e.g. because some error 118 * prevented the client from calling LLVMOrcJITDylibAddGenerator). 119 */ 120 void LLVMOrcDisposeJITDylibDefinitionGenerator( 121 LLVMOrcJITDylibDefinitionGeneratorRef DG); 122 123 /** 124 * Add a JITDylib::DefinitionGenerator to the given JITDylib. 125 * 126 * The JITDylib will take ownership of the given generator: The client is no 127 * longer responsible for managing its memory. 128 */ 129 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD, 130 LLVMOrcJITDylibDefinitionGeneratorRef DG); 131 132 /** 133 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into 134 * the JITDylib. On success the resulting generator is owned by the client. 135 * Ownership is typically transferred by adding the instance to a JITDylib 136 * using LLVMOrcJITDylibAddGenerator, 137 * 138 * The GlobalPrefix argument specifies the character that appears on the front 139 * of linker-mangled symbols for the target platform (e.g. '_' on MachO). 140 * If non-null, this character will be stripped from the start of all symbol 141 * strings before passing the remaining substring to dlsym. 142 * 143 * The optional Filter and Ctx arguments can be used to supply a symbol name 144 * filter: Only symbols for which the filter returns true will be visible to 145 * JIT'd code. If the Filter argument is null then all process symbols will 146 * be visible to JIT'd code. Note that the symbol name passed to the Filter 147 * function is the full mangled symbol: The client is responsible for stripping 148 * the global prefix if present. 149 */ 150 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess( 151 LLVMOrcJITDylibDefinitionGeneratorRef *Result, char GlobalPrefx, 152 LLVMOrcSymbolPredicate Filter, void *FilterCtx); 153 154 /** 155 * Create a ThreadSafeContext containing a new LLVMContext. 156 * 157 * Ownership of the underlying ThreadSafeContext data is shared: Clients 158 * can and should dispose of their ThreadSafeContext as soon as they no longer 159 * need to refer to it directly. Other references (e.g. from ThreadSafeModules 160 * will keep the data alive as long as it is needed. 161 */ 162 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void); 163 164 /** 165 * Get a reference to the wrapped LLVMContext. 166 */ 167 LLVMContextRef 168 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx); 169 170 /** 171 * Dispose of a ThreadSafeContext. 172 */ 173 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx); 174 175 /** 176 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes 177 * ownership of the M argument which should not be disposed of or referenced 178 * after this function returns. 179 * 180 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT 181 * (e.g. by LLVMOrcLLJITAddLLVMIRModule), in which case the client is no longer 182 * responsible for it. If it is not transferred to the JIT then the client 183 * should call LLVMOrcDisposeThreadSafeModule to dispose of it. 184 */ 185 LLVMOrcThreadSafeModuleRef 186 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M, 187 LLVMOrcThreadSafeContextRef TSCtx); 188 189 /** 190 * Dispose of a ThreadSafeModule. This should only be called if ownership has 191 * not been passed to LLJIT (e.g. because some error prevented the client from 192 * adding this to the JIT). 193 */ 194 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM); 195 196 /** 197 * Create a JITTargetMachineBuilder by detecting the host. 198 * 199 * On success the client owns the resulting JITTargetMachineBuilder. It must be 200 * passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed 201 * of by calling LLVMOrcDisposeJITTargetMachineBuilder. 202 */ 203 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost( 204 LLVMOrcJITTargetMachineBuilderRef *Result); 205 206 /** 207 * Create a JITTargetMachineBuilder from the given TargetMachine template. 208 * 209 * This operation takes ownership of the given TargetMachine and destroys it 210 * before returing. The resulting JITTargetMachineBuilder is owned by the client 211 * and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) 212 * or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder. 213 */ 214 LLVMOrcJITTargetMachineBuilderRef 215 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM); 216 217 /** 218 * Dispose of a JITTargetMachineBuilder. 219 */ 220 void LLVMOrcDisposeJITTargetMachineBuilder( 221 LLVMOrcJITTargetMachineBuilderRef JTMB); 222 223 /** 224 * Create an LLJITTargetMachineBuilder. 225 * 226 * The client owns the resulting LLJITBuilder and should dispose of it using 227 * LLVMOrcDisposeLLJITBuilder once they are done with it. 228 */ 229 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void); 230 231 /** 232 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership 233 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented 234 * that function from being called). 235 */ 236 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder); 237 238 /** 239 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT 240 * instance. Calling this function is optional: if it is not called then the 241 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a 242 * JITTargetMachineBuilder. 243 */ 244 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder( 245 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB); 246 247 /** 248 * Create an LLJIT instance from an LLJITBuilder. 249 * 250 * This operation takes ownership of the Builder argument: clients should not 251 * dispose of the builder after calling this function (even if the function 252 * returns an error). If a null Builder argument is provided then a 253 * default-constructed LLJITBuilder will be used. 254 * 255 * On success the resulting LLJIT instance is uniquely owned by the client and 256 * automatically manages the memory of all JIT'd code and all modules that are 257 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the 258 * LLJIT instance will free all memory managed by the JIT, including JIT'd code 259 * and not-yet compiled modules. 260 */ 261 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result, 262 LLVMOrcLLJITBuilderRef Builder); 263 264 /** 265 * Dispose of an LLJIT instance. 266 */ 267 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J); 268 269 /** 270 * Get a reference to the ExecutionSession for this LLJIT instance. 271 * 272 * The ExecutionSession is owned by the LLJIT instance. The client is not 273 * responsible for managing its memory. 274 */ 275 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J); 276 277 /** 278 * Return a reference to the Main JITDylib. 279 * 280 * The JITDylib is owned by the LLJIT instance. The client is not responsible 281 * for managing its memory. 282 */ 283 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J); 284 285 /** 286 * Return the target triple for this LLJIT instance. This string is owned by 287 * the LLJIT instance and should not be freed by the client. 288 */ 289 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J); 290 291 /** 292 * Returns the global prefix character according to the LLJIT's DataLayout. 293 */ 294 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J); 295 296 /** 297 * Mangles the given string according to the LLJIT instance's DataLayout, then 298 * interns the result in the SymbolStringPool and returns a reference to the 299 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to 300 * decrement the ref-count on the pool entry once they are finished with this 301 * value. 302 */ 303 LLVMOrcSymbolStringPoolEntryRef 304 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName); 305 306 /** 307 * Add a buffer representing an object file to the given JITDylib in the given 308 * LLJIT instance. This operation transfers ownership of the buffer to the 309 * LLJIT instance. The buffer should not be disposed of or referenced once this 310 * function returns. 311 */ 312 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, 313 LLVMMemoryBufferRef ObjBuffer); 314 315 /** 316 * Add an IR module to the given JITDylib of the given LLJIT instance. This 317 * operation transfers ownership of the TSM argument to the LLJIT instance. 318 * The TSM argument should not be 3disposed of or referenced once this 319 * function returns. 320 */ 321 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J, 322 LLVMOrcJITDylibRef JD, 323 LLVMOrcThreadSafeModuleRef TSM); 324 /** 325 * Look up the given symbol in the main JITDylib of the given LLJIT instance. 326 * 327 * This operation does not take ownership of the Name argument. 328 */ 329 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J, 330 LLVMOrcJITTargetAddress *Result, 331 const char *Name); 332 333 LLVM_C_EXTERN_C_END 334 335 #endif /* LLVM_C_ORC_H */ 336