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 * Represents generic linkage flags for a symbol definition. 43 */ 44 typedef enum { 45 LLVMJITSymbolGenericFlagsExported = 1U << 0, 46 LLVMJITSymbolGenericFlagsWeak = 1U << 1 47 } LLVMJITSymbolGenericFlags; 48 49 /** 50 * Represents target specific flags for a symbol definition. 51 */ 52 typedef uint8_t LLVMJITTargetSymbolFlags; 53 54 /** 55 * Represents the linkage flags for a symbol definition. 56 */ 57 typedef struct { 58 uint8_t GenericFlags; 59 uint8_t TargetFlags; 60 } LLVMJITSymbolFlags; 61 62 /** 63 * Represents an evaluated symbol address and flags. 64 */ 65 typedef struct { 66 LLVMOrcJITTargetAddress Address; 67 LLVMJITSymbolFlags Flags; 68 } LLVMJITEvaluatedSymbol; 69 70 /** 71 * A reference to an orc::ExecutionSession instance. 72 */ 73 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef; 74 75 /** 76 * Error reporter function. 77 */ 78 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err); 79 80 /** 81 * A reference to an orc::SymbolStringPool. 82 */ 83 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef; 84 85 /** 86 * A reference to an orc::SymbolStringPool table entry. 87 */ 88 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry 89 *LLVMOrcSymbolStringPoolEntryRef; 90 91 /** 92 * Represents a pair of a symbol name and an evaluated symbol. 93 */ 94 typedef struct { 95 LLVMOrcSymbolStringPoolEntryRef Name; 96 LLVMJITEvaluatedSymbol Sym; 97 } LLVMJITCSymbolMapPair; 98 99 /** 100 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be 101 * used to construct a SymbolMap. 102 */ 103 typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs; 104 105 /** 106 * Lookup kind. This can be used by definition generators when deciding whether 107 * to produce a definition for a requested symbol. 108 * 109 * This enum should be kept in sync with llvm::orc::LookupKind. 110 */ 111 typedef enum { 112 LLVMOrcLookupKindStatic, 113 LLVMOrcLookupKindDLSym 114 } LLVMOrcLookupKind; 115 116 /** 117 * JITDylib lookup flags. This can be used by definition generators when 118 * deciding whether to produce a definition for a requested symbol. 119 * 120 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags. 121 */ 122 typedef enum { 123 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly, 124 LLVMOrcJITDylibLookupFlagsMatchAllSymbols 125 } LLVMOrcJITDylibLookupFlags; 126 127 /** 128 * Symbol lookup flags for lookup sets. This should be kept in sync with 129 * llvm::orc::SymbolLookupFlags. 130 */ 131 typedef enum { 132 LLVMOrcSymbolLookupFlagsRequiredSymbol, 133 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol 134 } LLVMOrcSymbolLookupFlags; 135 136 /** 137 * An element type for a symbol lookup set. 138 */ 139 typedef struct { 140 LLVMOrcSymbolStringPoolEntryRef Name; 141 LLVMOrcSymbolLookupFlags LookupFlags; 142 } LLVMOrcCLookupSetElement; 143 144 /** 145 * A set of symbols to look up / generate. 146 * 147 * The list is terminated with an element containing a null pointer for the 148 * Name field. 149 * 150 * If a client creates an instance of this type then they are responsible for 151 * freeing it, and for ensuring that all strings have been retained over the 152 * course of its life. Clients receiving a copy from a callback are not 153 * responsible for managing lifetime or retain counts. 154 */ 155 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet; 156 157 /** 158 * A reference to an orc::MaterializationUnit. 159 */ 160 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef; 161 162 /** 163 * A reference to an orc::JITDylib instance. 164 */ 165 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef; 166 167 /** 168 * A reference to an orc::ResourceTracker instance. 169 */ 170 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef; 171 172 /** 173 * A reference to an orc::DefinitionGenerator. 174 */ 175 typedef struct LLVMOrcOpaqueDefinitionGenerator 176 *LLVMOrcDefinitionGeneratorRef; 177 178 /** 179 * An opaque lookup state object. Instances of this type can be captured to 180 * suspend a lookup while a custom generator function attempts to produce a 181 * definition. 182 * 183 * If a client captures a lookup state object then they must eventually call 184 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required 185 * in order to release memory allocated for the lookup state, even if errors 186 * have occurred while the lookup was suspended (if these errors have made the 187 * lookup impossible to complete then it will issue its own error before 188 * destruction). 189 */ 190 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef; 191 192 /** 193 * A custom generator function. This can be used to create a custom generator 194 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting 195 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to 196 * receive callbacks when lookups fail to match existing definitions. 197 * 198 * GeneratorObj will contain the address of the custom generator object. 199 * 200 * Ctx will contain the context object passed to 201 * LLVMOrcCreateCustomCAPIDefinitionGenerator. 202 * 203 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This 204 * can optionally be modified to make the definition generation process 205 * asynchronous: If the LookupStateRef value is copied, and the original 206 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the 207 * asynchronous definition process has been completed clients must call 208 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be 209 * done unconditionally, even if errors have occurred in the mean time, to 210 * free the lookup state memory and notify the query object of the failures. If 211 * LookupState is captured this function must return LLVMErrorSuccess. 212 * 213 * The Kind argument can be inspected to determine the lookup kind (e.g. 214 * as-if-during-static-link, or as-if-during-dlsym). 215 * 216 * The JD argument specifies which JITDylib the definitions should be generated 217 * into. 218 * 219 * The JDLookupFlags argument can be inspected to determine whether the original 220 * lookup included non-exported symobls. 221 * 222 * Finally, the LookupSet argument contains the set of symbols that could not 223 * be found in JD already (the set of generation candidates). 224 */ 225 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)( 226 LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx, 227 LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind, 228 LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags, 229 LLVMOrcCLookupSet LookupSet, size_t LookupSetSize); 230 231 /** 232 * Predicate function for SymbolStringPoolEntries. 233 */ 234 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx, 235 LLVMOrcSymbolStringPoolEntryRef Sym); 236 237 /** 238 * A reference to an orc::ThreadSafeContext instance. 239 */ 240 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef; 241 242 /** 243 * A reference to an orc::ThreadSafeModule instance. 244 */ 245 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef; 246 247 /** 248 * A reference to an orc::JITTargetMachineBuilder instance. 249 */ 250 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder 251 *LLVMOrcJITTargetMachineBuilderRef; 252 253 /** 254 * A reference to an orc::ObjectLayer instance. 255 */ 256 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef; 257 258 /** 259 * Attach a custom error reporter function to the ExecutionSession. 260 * 261 * The error reporter will be called to deliver failure notices that can not be 262 * directly reported to a caller. For example, failure to resolve symbols in 263 * the JIT linker is typically reported via the error reporter (callers 264 * requesting definitions from the JIT will typically be delivered a 265 * FailureToMaterialize error instead). 266 */ 267 void LLVMOrcExecutionSessionSetErrorReporter( 268 LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError, 269 void *Ctx); 270 271 /** 272 * Return a reference to the SymbolStringPool for an ExecutionSession. 273 * 274 * Ownership of the pool remains with the ExecutionSession: The caller is 275 * not required to free the pool. 276 */ 277 LLVMOrcSymbolStringPoolRef 278 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES); 279 280 /** 281 * Clear all unreferenced symbol string pool entries. 282 * 283 * This can be called at any time to release unused entries in the 284 * ExecutionSession's string pool. Since it locks the pool (preventing 285 * interning of any new strings) it is recommended that it only be called 286 * infrequently, ideally when the caller has reason to believe that some 287 * entries will have become unreferenced, e.g. after removing a module or 288 * closing a JITDylib. 289 */ 290 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP); 291 292 /** 293 * Intern a string in the ExecutionSession's SymbolStringPool and return a 294 * reference to it. This increments the ref-count of the pool entry, and the 295 * returned value should be released once the client is done with it by 296 * calling LLVMOrReleaseSymbolStringPoolEntry. 297 * 298 * Since strings are uniqued within the SymbolStringPool 299 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string 300 * equality. 301 * 302 * Note that this function does not perform linker-mangling on the string. 303 */ 304 LLVMOrcSymbolStringPoolEntryRef 305 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name); 306 307 /** 308 * Increments the ref-count for a SymbolStringPool entry. 309 */ 310 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 311 312 /** 313 * Reduces the ref-count for of a SymbolStringPool entry. 314 */ 315 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 316 317 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S); 318 319 /** 320 * Reduces the ref-count of a ResourceTracker. 321 */ 322 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT); 323 324 /** 325 * Transfers tracking of all resources associated with resource tracker SrcRT 326 * to resource tracker DstRT. 327 */ 328 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT, 329 LLVMOrcResourceTrackerRef DstRT); 330 331 /** 332 * Remove all resources associated with the given tracker. See 333 * ResourceTracker::remove(). 334 */ 335 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT); 336 337 /** 338 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if 339 * ownership has not been passed to a JITDylib (e.g. because some error 340 * prevented the client from calling LLVMOrcJITDylibAddGenerator). 341 */ 342 void LLVMOrcDisposeDefinitionGenerator( 343 LLVMOrcDefinitionGeneratorRef DG); 344 345 /** 346 * Dispose of a MaterializationUnit. 347 */ 348 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU); 349 350 /** 351 * Create a MaterializationUnit to define the given symbols as pointing to 352 * the corresponding raw addresses. 353 */ 354 LLVMOrcMaterializationUnitRef 355 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs); 356 357 /** 358 * Create a "bare" JITDylib. 359 * 360 * The client is responsible for ensuring that the JITDylib's name is unique, 361 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 362 * 363 * This call does not install any library code or symbols into the newly 364 * created JITDylib. The client is responsible for all configuration. 365 */ 366 LLVMOrcJITDylibRef 367 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES, 368 const char *Name); 369 370 /** 371 * Create a JITDylib. 372 * 373 * The client is responsible for ensuring that the JITDylib's name is unique, 374 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 375 * 376 * If a Platform is attached to the ExecutionSession then 377 * Platform::setupJITDylib will be called to install standard platform symbols 378 * (e.g. standard library interposes). If no Platform is installed then this 379 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will 380 * always return success. 381 */ 382 LLVMErrorRef 383 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES, 384 LLVMOrcJITDylibRef *Result, 385 const char *Name); 386 387 /** 388 * Returns the JITDylib with the given name, or NULL if no such JITDylib 389 * exists. 390 */ 391 LLVMOrcJITDylibRef LLVMOrcExecutionSessionGetJITDylibByName(const char *Name); 392 393 /** 394 * Return a reference to a newly created resource tracker associated with JD. 395 * The tracker is returned with an initial ref-count of 1, and must be released 396 * with LLVMOrcReleaseResourceTracker when no longer needed. 397 */ 398 LLVMOrcResourceTrackerRef 399 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD); 400 401 /** 402 * Return a reference to the default resource tracker for the given JITDylib. 403 * This operation will increase the retain count of the tracker: Clients should 404 * call LLVMOrcReleaseResourceTracker when the result is no longer needed. 405 */ 406 LLVMOrcResourceTrackerRef 407 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD); 408 409 /** 410 * Add the given MaterializationUnit to the given JITDylib. 411 * 412 * If this operation succeeds then JITDylib JD will take ownership of MU. 413 * If the operation fails then ownership remains with the caller who should 414 * call LLVMOrcDisposeMaterializationUnit to destroy it. 415 */ 416 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD, 417 LLVMOrcMaterializationUnitRef MU); 418 419 /** 420 * Calls remove on all trackers associated with this JITDylib, see 421 * JITDylib::clear(). 422 */ 423 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD); 424 425 /** 426 * Add a DefinitionGenerator to the given JITDylib. 427 * 428 * The JITDylib will take ownership of the given generator: The client is no 429 * longer responsible for managing its memory. 430 */ 431 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD, 432 LLVMOrcDefinitionGeneratorRef DG); 433 434 /** 435 * Create a custom generator. 436 */ 437 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator( 438 LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx); 439 440 /** 441 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into 442 * the JITDylib. On success the resulting generator is owned by the client. 443 * Ownership is typically transferred by adding the instance to a JITDylib 444 * using LLVMOrcJITDylibAddGenerator, 445 * 446 * The GlobalPrefix argument specifies the character that appears on the front 447 * of linker-mangled symbols for the target platform (e.g. '_' on MachO). 448 * If non-null, this character will be stripped from the start of all symbol 449 * strings before passing the remaining substring to dlsym. 450 * 451 * The optional Filter and Ctx arguments can be used to supply a symbol name 452 * filter: Only symbols for which the filter returns true will be visible to 453 * JIT'd code. If the Filter argument is null then all process symbols will 454 * be visible to JIT'd code. Note that the symbol name passed to the Filter 455 * function is the full mangled symbol: The client is responsible for stripping 456 * the global prefix if present. 457 */ 458 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess( 459 LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx, 460 LLVMOrcSymbolPredicate Filter, void *FilterCtx); 461 462 /** 463 * Create a ThreadSafeContext containing a new LLVMContext. 464 * 465 * Ownership of the underlying ThreadSafeContext data is shared: Clients 466 * can and should dispose of their ThreadSafeContext as soon as they no longer 467 * need to refer to it directly. Other references (e.g. from ThreadSafeModules) 468 * will keep the data alive as long as it is needed. 469 */ 470 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void); 471 472 /** 473 * Get a reference to the wrapped LLVMContext. 474 */ 475 LLVMContextRef 476 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx); 477 478 /** 479 * Dispose of a ThreadSafeContext. 480 */ 481 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx); 482 483 /** 484 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes 485 * ownership of the M argument which should not be disposed of or referenced 486 * after this function returns. 487 * 488 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT 489 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer 490 * responsible for it. If it is not transferred to the JIT then the client 491 * should call LLVMOrcDisposeThreadSafeModule to dispose of it. 492 */ 493 LLVMOrcThreadSafeModuleRef 494 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M, 495 LLVMOrcThreadSafeContextRef TSCtx); 496 497 /** 498 * Dispose of a ThreadSafeModule. This should only be called if ownership has 499 * not been passed to LLJIT (e.g. because some error prevented the client from 500 * adding this to the JIT). 501 */ 502 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM); 503 504 /** 505 * Create a JITTargetMachineBuilder by detecting the host. 506 * 507 * On success the client owns the resulting JITTargetMachineBuilder. It must be 508 * passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed 509 * of by calling LLVMOrcDisposeJITTargetMachineBuilder. 510 */ 511 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost( 512 LLVMOrcJITTargetMachineBuilderRef *Result); 513 514 /** 515 * Create a JITTargetMachineBuilder from the given TargetMachine template. 516 * 517 * This operation takes ownership of the given TargetMachine and destroys it 518 * before returing. The resulting JITTargetMachineBuilder is owned by the client 519 * and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) 520 * or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder. 521 */ 522 LLVMOrcJITTargetMachineBuilderRef 523 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM); 524 525 /** 526 * Dispose of a JITTargetMachineBuilder. 527 */ 528 void LLVMOrcDisposeJITTargetMachineBuilder( 529 LLVMOrcJITTargetMachineBuilderRef JTMB); 530 531 /** 532 * Dispose of an ObjectLayer. 533 */ 534 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer); 535 536 LLVM_C_EXTERN_C_END 537 538 #endif /* LLVM_C_ORC_H */ 539