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 LLVMJITSymbolGenericFlagsCallable = 1U << 2, 48 LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3 49 } LLVMJITSymbolGenericFlags; 50 51 /** 52 * Represents target specific flags for a symbol definition. 53 */ 54 typedef uint8_t LLVMJITSymbolTargetFlags; 55 56 /** 57 * Represents the linkage flags for a symbol definition. 58 */ 59 typedef struct { 60 uint8_t GenericFlags; 61 uint8_t TargetFlags; 62 } LLVMJITSymbolFlags; 63 64 /** 65 * Represents an evaluated symbol address and flags. 66 */ 67 typedef struct { 68 LLVMOrcJITTargetAddress Address; 69 LLVMJITSymbolFlags Flags; 70 } LLVMJITEvaluatedSymbol; 71 72 /** 73 * A reference to an orc::ExecutionSession instance. 74 */ 75 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef; 76 77 /** 78 * Error reporter function. 79 */ 80 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err); 81 82 /** 83 * A reference to an orc::SymbolStringPool. 84 */ 85 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef; 86 87 /** 88 * A reference to an orc::SymbolStringPool table entry. 89 */ 90 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry 91 *LLVMOrcSymbolStringPoolEntryRef; 92 93 /** 94 * Represents a pair of a symbol name and LLVMJITSymbolFlags. 95 */ 96 typedef struct { 97 LLVMOrcSymbolStringPoolEntryRef Name; 98 LLVMJITSymbolFlags Flags; 99 } LLVMOrcCSymbolFlagsMapPair; 100 101 /** 102 * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used 103 * to construct a SymbolFlagsMap. 104 */ 105 typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs; 106 107 /** 108 * Represents a pair of a symbol name and an evaluated symbol. 109 */ 110 typedef struct { 111 LLVMOrcSymbolStringPoolEntryRef Name; 112 LLVMJITEvaluatedSymbol Sym; 113 } LLVMJITCSymbolMapPair; 114 115 /** 116 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be 117 * used to construct a SymbolMap. 118 */ 119 typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs; 120 121 /** 122 * Lookup kind. This can be used by definition generators when deciding whether 123 * to produce a definition for a requested symbol. 124 * 125 * This enum should be kept in sync with llvm::orc::LookupKind. 126 */ 127 typedef enum { 128 LLVMOrcLookupKindStatic, 129 LLVMOrcLookupKindDLSym 130 } LLVMOrcLookupKind; 131 132 /** 133 * JITDylib lookup flags. This can be used by definition generators when 134 * deciding whether to produce a definition for a requested symbol. 135 * 136 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags. 137 */ 138 typedef enum { 139 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly, 140 LLVMOrcJITDylibLookupFlagsMatchAllSymbols 141 } LLVMOrcJITDylibLookupFlags; 142 143 /** 144 * Symbol lookup flags for lookup sets. This should be kept in sync with 145 * llvm::orc::SymbolLookupFlags. 146 */ 147 typedef enum { 148 LLVMOrcSymbolLookupFlagsRequiredSymbol, 149 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol 150 } LLVMOrcSymbolLookupFlags; 151 152 /** 153 * An element type for a symbol lookup set. 154 */ 155 typedef struct { 156 LLVMOrcSymbolStringPoolEntryRef Name; 157 LLVMOrcSymbolLookupFlags LookupFlags; 158 } LLVMOrcCLookupSetElement; 159 160 /** 161 * A set of symbols to look up / generate. 162 * 163 * The list is terminated with an element containing a null pointer for the 164 * Name field. 165 * 166 * If a client creates an instance of this type then they are responsible for 167 * freeing it, and for ensuring that all strings have been retained over the 168 * course of its life. Clients receiving a copy from a callback are not 169 * responsible for managing lifetime or retain counts. 170 */ 171 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet; 172 173 /** 174 * A reference to a uniquely owned orc::MaterializationUnit instance. 175 */ 176 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef; 177 178 /** 179 * A reference to a uniquely owned orc::MaterializationResponsibility instance. 180 * 181 * Ownership must be passed to a lower-level layer in a JIT stack. 182 */ 183 typedef struct LLVMOrcOpaqueMaterializationResponsibility 184 *LLVMOrcMaterializationResponsibilityRef; 185 186 /** 187 * A reference to an orc::JITDylib instance. 188 */ 189 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef; 190 191 /** 192 * A MaterializationUnit materialize callback. 193 * 194 * Ownership of the Ctx and MR arguments passes to the callback which must 195 * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment 196 * for that type). 197 * 198 * If this callback is called then the LLVMOrcMaterializationUnitDestroy 199 * callback will NOT be called. 200 */ 201 typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)( 202 void *Ctx, LLVMOrcMaterializationResponsibilityRef MR); 203 204 /** 205 * A MaterializationUnit discard callback. 206 * 207 * Ownership of JD and Symbol remain with the caller: These arguments should 208 * not be disposed of or released. 209 */ 210 typedef void (*LLVMOrcMaterializationUnitDiscardFunction)( 211 void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol); 212 213 /** 214 * A MaterializationUnit destruction callback. 215 * 216 * If a custom MaterializationUnit is destroyed before its Materialize 217 * function is called then this function will be called to provide an 218 * opportunity for the underlying program representation to be destroyed. 219 */ 220 typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx); 221 222 /** 223 * A reference to an orc::ResourceTracker instance. 224 */ 225 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef; 226 227 /** 228 * A reference to an orc::DefinitionGenerator. 229 */ 230 typedef struct LLVMOrcOpaqueDefinitionGenerator 231 *LLVMOrcDefinitionGeneratorRef; 232 233 /** 234 * An opaque lookup state object. Instances of this type can be captured to 235 * suspend a lookup while a custom generator function attempts to produce a 236 * definition. 237 * 238 * If a client captures a lookup state object then they must eventually call 239 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required 240 * in order to release memory allocated for the lookup state, even if errors 241 * have occurred while the lookup was suspended (if these errors have made the 242 * lookup impossible to complete then it will issue its own error before 243 * destruction). 244 */ 245 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef; 246 247 /** 248 * A custom generator function. This can be used to create a custom generator 249 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting 250 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to 251 * receive callbacks when lookups fail to match existing definitions. 252 * 253 * GeneratorObj will contain the address of the custom generator object. 254 * 255 * Ctx will contain the context object passed to 256 * LLVMOrcCreateCustomCAPIDefinitionGenerator. 257 * 258 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This 259 * can optionally be modified to make the definition generation process 260 * asynchronous: If the LookupStateRef value is copied, and the original 261 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the 262 * asynchronous definition process has been completed clients must call 263 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be 264 * done unconditionally, even if errors have occurred in the mean time, to 265 * free the lookup state memory and notify the query object of the failures). 266 * If LookupState is captured this function must return LLVMErrorSuccess. 267 * 268 * The Kind argument can be inspected to determine the lookup kind (e.g. 269 * as-if-during-static-link, or as-if-during-dlsym). 270 * 271 * The JD argument specifies which JITDylib the definitions should be generated 272 * into. 273 * 274 * The JDLookupFlags argument can be inspected to determine whether the original 275 * lookup included non-exported symobls. 276 * 277 * Finally, the LookupSet argument contains the set of symbols that could not 278 * be found in JD already (the set of generation candidates). 279 */ 280 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)( 281 LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx, 282 LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind, 283 LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags, 284 LLVMOrcCLookupSet LookupSet, size_t LookupSetSize); 285 286 /** 287 * Predicate function for SymbolStringPoolEntries. 288 */ 289 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx, 290 LLVMOrcSymbolStringPoolEntryRef Sym); 291 292 /** 293 * A reference to an orc::ThreadSafeContext instance. 294 */ 295 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef; 296 297 /** 298 * A reference to an orc::ThreadSafeModule instance. 299 */ 300 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef; 301 302 /** 303 * A reference to an orc::JITTargetMachineBuilder instance. 304 */ 305 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder 306 *LLVMOrcJITTargetMachineBuilderRef; 307 308 /** 309 * A reference to an orc::ObjectLayer instance. 310 */ 311 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef; 312 313 /** 314 * A reference to an orc::ObjectLinkingLayer instance. 315 */ 316 typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef; 317 318 /** 319 * Attach a custom error reporter function to the ExecutionSession. 320 * 321 * The error reporter will be called to deliver failure notices that can not be 322 * directly reported to a caller. For example, failure to resolve symbols in 323 * the JIT linker is typically reported via the error reporter (callers 324 * requesting definitions from the JIT will typically be delivered a 325 * FailureToMaterialize error instead). 326 */ 327 void LLVMOrcExecutionSessionSetErrorReporter( 328 LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError, 329 void *Ctx); 330 331 /** 332 * Return a reference to the SymbolStringPool for an ExecutionSession. 333 * 334 * Ownership of the pool remains with the ExecutionSession: The caller is 335 * not required to free the pool. 336 */ 337 LLVMOrcSymbolStringPoolRef 338 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES); 339 340 /** 341 * Clear all unreferenced symbol string pool entries. 342 * 343 * This can be called at any time to release unused entries in the 344 * ExecutionSession's string pool. Since it locks the pool (preventing 345 * interning of any new strings) it is recommended that it only be called 346 * infrequently, ideally when the caller has reason to believe that some 347 * entries will have become unreferenced, e.g. after removing a module or 348 * closing a JITDylib. 349 */ 350 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP); 351 352 /** 353 * Intern a string in the ExecutionSession's SymbolStringPool and return a 354 * reference to it. This increments the ref-count of the pool entry, and the 355 * returned value should be released once the client is done with it by 356 * calling LLVMOrReleaseSymbolStringPoolEntry. 357 * 358 * Since strings are uniqued within the SymbolStringPool 359 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string 360 * equality. 361 * 362 * Note that this function does not perform linker-mangling on the string. 363 */ 364 LLVMOrcSymbolStringPoolEntryRef 365 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name); 366 367 /** 368 * Increments the ref-count for a SymbolStringPool entry. 369 */ 370 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 371 372 /** 373 * Reduces the ref-count for of a SymbolStringPool entry. 374 */ 375 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 376 377 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S); 378 379 /** 380 * Reduces the ref-count of a ResourceTracker. 381 */ 382 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT); 383 384 /** 385 * Transfers tracking of all resources associated with resource tracker SrcRT 386 * to resource tracker DstRT. 387 */ 388 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT, 389 LLVMOrcResourceTrackerRef DstRT); 390 391 /** 392 * Remove all resources associated with the given tracker. See 393 * ResourceTracker::remove(). 394 */ 395 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT); 396 397 /** 398 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if 399 * ownership has not been passed to a JITDylib (e.g. because some error 400 * prevented the client from calling LLVMOrcJITDylibAddGenerator). 401 */ 402 void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG); 403 404 /** 405 * Dispose of a MaterializationUnit. 406 */ 407 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU); 408 409 /** 410 * Create a custom MaterializationUnit. 411 * 412 * Name is a name for this MaterializationUnit to be used for identification 413 * and logging purposes (e.g. if this MaterializationUnit produces an 414 * object buffer then the name of that buffer will be derived from this name). 415 * 416 * The Syms list contains the names and linkages of the symbols provided by this 417 * unit. This function takes ownership of the elements of the Syms array. The 418 * Name fields of the array elements are taken to have been retained for this 419 * function. The client should *not* release the elements of the array, but is 420 * still responsible for destroyingthe array itself. 421 * 422 * The InitSym argument indicates whether or not this MaterializationUnit 423 * contains static initializers. If three are no static initializers (the common 424 * case) then this argument should be null. If there are static initializers 425 * then InitSym should be set to a unique name that also appears in the Syms 426 * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag 427 * set. This function takes ownership of the InitSym, which should have been 428 * retained twice on behalf of this function: once for the Syms entry and once 429 * for InitSym. If clients wish to use the InitSym value after this function 430 * returns they must retain it once more for themselves. 431 * 432 * If any of the symbols in the Syms list is looked up then the Materialize 433 * function will be called. 434 * 435 * If any of the symbols in the Syms list is overridden then the Discard 436 * function will be called. 437 * 438 * The caller owns the underling MaterializationUnit and is responsible for 439 * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing 440 * of it by calling LLVMOrcDisposeMaterializationUnit. 441 */ 442 LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit( 443 const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms, 444 size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym, 445 LLVMOrcMaterializationUnitMaterializeFunction Materialize, 446 LLVMOrcMaterializationUnitDiscardFunction Discard, 447 LLVMOrcMaterializationUnitDestroyFunction Destroy); 448 449 /** 450 * Create a MaterializationUnit to define the given symbols as pointing to 451 * the corresponding raw addresses. 452 * 453 * This function takes ownership of the elements of the Syms array. The Name 454 * fields of the array elements are taken to have been retained for this 455 * function. This allows the following pattern... 456 * 457 * size_t NumPairs; 458 * LLVMOrcCSymbolMapPairs Sym; 459 * -- Build Syms array -- 460 * LLVMOrcMaterializationUnitRef MU = 461 * LLVMOrcAbsoluteSymbols(Syms, NumPairs); 462 * 463 * ... without requiring cleanup of the elements of the Sym array afterwards. 464 * 465 * The client is still responsible for deleting the Sym array itself. 466 * 467 * If a client wishes to reuse elements of the Sym array after this call they 468 * must explicitly retain each of the elements for themselves. 469 */ 470 LLVMOrcMaterializationUnitRef 471 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs); 472 473 /** 474 * Create a "bare" JITDylib. 475 * 476 * The client is responsible for ensuring that the JITDylib's name is unique, 477 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 478 * 479 * This call does not install any library code or symbols into the newly 480 * created JITDylib. The client is responsible for all configuration. 481 */ 482 LLVMOrcJITDylibRef 483 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES, 484 const char *Name); 485 486 /** 487 * Create a JITDylib. 488 * 489 * The client is responsible for ensuring that the JITDylib's name is unique, 490 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 491 * 492 * If a Platform is attached to the ExecutionSession then 493 * Platform::setupJITDylib will be called to install standard platform symbols 494 * (e.g. standard library interposes). If no Platform is installed then this 495 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will 496 * always return success. 497 */ 498 LLVMErrorRef 499 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES, 500 LLVMOrcJITDylibRef *Result, 501 const char *Name); 502 503 /** 504 * Returns the JITDylib with the given name, or NULL if no such JITDylib 505 * exists. 506 */ 507 LLVMOrcJITDylibRef 508 LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES, 509 const char *Name); 510 511 /** 512 * Return a reference to a newly created resource tracker associated with JD. 513 * The tracker is returned with an initial ref-count of 1, and must be released 514 * with LLVMOrcReleaseResourceTracker when no longer needed. 515 */ 516 LLVMOrcResourceTrackerRef 517 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD); 518 519 /** 520 * Return a reference to the default resource tracker for the given JITDylib. 521 * This operation will increase the retain count of the tracker: Clients should 522 * call LLVMOrcReleaseResourceTracker when the result is no longer needed. 523 */ 524 LLVMOrcResourceTrackerRef 525 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD); 526 527 /** 528 * Add the given MaterializationUnit to the given JITDylib. 529 * 530 * If this operation succeeds then JITDylib JD will take ownership of MU. 531 * If the operation fails then ownership remains with the caller who should 532 * call LLVMOrcDisposeMaterializationUnit to destroy it. 533 */ 534 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD, 535 LLVMOrcMaterializationUnitRef MU); 536 537 /** 538 * Calls remove on all trackers associated with this JITDylib, see 539 * JITDylib::clear(). 540 */ 541 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD); 542 543 /** 544 * Add a DefinitionGenerator to the given JITDylib. 545 * 546 * The JITDylib will take ownership of the given generator: The client is no 547 * longer responsible for managing its memory. 548 */ 549 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD, 550 LLVMOrcDefinitionGeneratorRef DG); 551 552 /** 553 * Create a custom generator. 554 */ 555 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator( 556 LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx); 557 558 /** 559 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into 560 * the JITDylib. On success the resulting generator is owned by the client. 561 * Ownership is typically transferred by adding the instance to a JITDylib 562 * using LLVMOrcJITDylibAddGenerator, 563 * 564 * The GlobalPrefix argument specifies the character that appears on the front 565 * of linker-mangled symbols for the target platform (e.g. '_' on MachO). 566 * If non-null, this character will be stripped from the start of all symbol 567 * strings before passing the remaining substring to dlsym. 568 * 569 * The optional Filter and Ctx arguments can be used to supply a symbol name 570 * filter: Only symbols for which the filter returns true will be visible to 571 * JIT'd code. If the Filter argument is null then all process symbols will 572 * be visible to JIT'd code. Note that the symbol name passed to the Filter 573 * function is the full mangled symbol: The client is responsible for stripping 574 * the global prefix if present. 575 */ 576 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess( 577 LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx, 578 LLVMOrcSymbolPredicate Filter, void *FilterCtx); 579 580 /** 581 * Create a ThreadSafeContext containing a new LLVMContext. 582 * 583 * Ownership of the underlying ThreadSafeContext data is shared: Clients 584 * can and should dispose of their ThreadSafeContext as soon as they no longer 585 * need to refer to it directly. Other references (e.g. from ThreadSafeModules) 586 * will keep the data alive as long as it is needed. 587 */ 588 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void); 589 590 /** 591 * Get a reference to the wrapped LLVMContext. 592 */ 593 LLVMContextRef 594 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx); 595 596 /** 597 * Dispose of a ThreadSafeContext. 598 */ 599 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx); 600 601 /** 602 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes 603 * ownership of the M argument which should not be disposed of or referenced 604 * after this function returns. 605 * 606 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT 607 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer 608 * responsible for it. If it is not transferred to the JIT then the client 609 * should call LLVMOrcDisposeThreadSafeModule to dispose of it. 610 */ 611 LLVMOrcThreadSafeModuleRef 612 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M, 613 LLVMOrcThreadSafeContextRef TSCtx); 614 615 /** 616 * Dispose of a ThreadSafeModule. This should only be called if ownership has 617 * not been passed to LLJIT (e.g. because some error prevented the client from 618 * adding this to the JIT). 619 */ 620 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM); 621 622 /** 623 * Create a JITTargetMachineBuilder by detecting the host. 624 * 625 * On success the client owns the resulting JITTargetMachineBuilder. It must be 626 * passed to a consuming operation (e.g. 627 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 628 * LLVMOrcDisposeJITTargetMachineBuilder. 629 */ 630 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost( 631 LLVMOrcJITTargetMachineBuilderRef *Result); 632 633 /** 634 * Create a JITTargetMachineBuilder from the given TargetMachine template. 635 * 636 * This operation takes ownership of the given TargetMachine and destroys it 637 * before returing. The resulting JITTargetMachineBuilder is owned by the client 638 * and must be passed to a consuming operation (e.g. 639 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 640 * LLVMOrcDisposeJITTargetMachineBuilder. 641 */ 642 LLVMOrcJITTargetMachineBuilderRef 643 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM); 644 645 /** 646 * Dispose of a JITTargetMachineBuilder. 647 */ 648 void LLVMOrcDisposeJITTargetMachineBuilder( 649 LLVMOrcJITTargetMachineBuilderRef JTMB); 650 651 /** 652 * Returns the target triple for the given JITTargetMachineBuilder as a string. 653 * 654 * The caller owns the resulting string as must dispose of it by calling 655 * LLVMDisposeMessage 656 */ 657 char *LLVMOrcJITTargetMachineBuilderGetTargetTriple( 658 LLVMOrcJITTargetMachineBuilderRef JTMB); 659 660 /** 661 * Sets the target triple for the given JITTargetMachineBuilder to the given 662 * string. 663 */ 664 void LLVMOrcJITTargetMachineBuilderSetTargetTriple( 665 LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple); 666 667 /** 668 * Add an object to an ObjectLayer to the given JITDylib. 669 * 670 * Adds a buffer representing an object file to the given JITDylib using the 671 * given ObjectLayer instance. This operation transfers ownership of the buffer 672 * to the ObjectLayer instance. The buffer should not be disposed of or 673 * referenced once this function returns. 674 * 675 * Resources associated with the given object will be tracked by the given 676 * JITDylib's default ResourceTracker. 677 */ 678 LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer, 679 LLVMOrcJITDylibRef JD, 680 LLVMMemoryBufferRef ObjBuffer); 681 682 /** 683 * Add an object to an ObjectLayer using the given ResourceTracker. 684 * 685 * Adds a buffer representing an object file to the given ResourceTracker's 686 * JITDylib using the given ObjectLayer instance. This operation transfers 687 * ownership of the buffer to the ObjectLayer instance. The buffer should not 688 * be disposed of or referenced once this function returns. 689 * 690 * Resources associated with the given object will be tracked by 691 * ResourceTracker RT. 692 */ 693 LLVMErrorRef 694 LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer, 695 LLVMOrcResourceTrackerRef RT, 696 LLVMMemoryBufferRef ObjBuffer); 697 698 /** 699 * Emit an object buffer to an ObjectLayer. 700 * 701 * Ownership of the responsibility object and object buffer pass to this 702 * function. The client is not responsible for cleanup. 703 */ 704 void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer, 705 LLVMOrcMaterializationResponsibilityRef R, 706 LLVMMemoryBufferRef ObjBuffer); 707 708 /** 709 * Dispose of an ObjectLayer. 710 */ 711 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer); 712 713 LLVM_C_EXTERN_C_END 714 715 #endif /* LLVM_C_ORC_H */ 716