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 * @defgroup LLVMCExecutionEngineORC On-Request-Compilation 38 * @ingroup LLVMCExecutionEngine 39 * 40 * @{ 41 */ 42 43 /** 44 * Represents an address in the executor process. 45 */ 46 typedef uint64_t LLVMOrcJITTargetAddress; 47 48 /** 49 * Represents an address in the executor process. 50 */ 51 typedef uint64_t LLVMOrcExecutorAddress; 52 53 /** 54 * Represents generic linkage flags for a symbol definition. 55 */ 56 typedef enum { 57 LLVMJITSymbolGenericFlagsNone = 0, 58 LLVMJITSymbolGenericFlagsExported = 1U << 0, 59 LLVMJITSymbolGenericFlagsWeak = 1U << 1, 60 LLVMJITSymbolGenericFlagsCallable = 1U << 2, 61 LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3 62 } LLVMJITSymbolGenericFlags; 63 64 /** 65 * Represents target specific flags for a symbol definition. 66 */ 67 typedef uint8_t LLVMJITSymbolTargetFlags; 68 69 /** 70 * Represents the linkage flags for a symbol definition. 71 */ 72 typedef struct { 73 uint8_t GenericFlags; 74 uint8_t TargetFlags; 75 } LLVMJITSymbolFlags; 76 77 /** 78 * Represents an evaluated symbol address and flags. 79 */ 80 typedef struct { 81 LLVMOrcExecutorAddress Address; 82 LLVMJITSymbolFlags Flags; 83 } LLVMJITEvaluatedSymbol; 84 85 /** 86 * A reference to an orc::ExecutionSession instance. 87 */ 88 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef; 89 90 /** 91 * Error reporter function. 92 */ 93 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err); 94 95 /** 96 * A reference to an orc::SymbolStringPool. 97 */ 98 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef; 99 100 /** 101 * A reference to an orc::SymbolStringPool table entry. 102 */ 103 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry 104 *LLVMOrcSymbolStringPoolEntryRef; 105 106 /** 107 * Represents a pair of a symbol name and LLVMJITSymbolFlags. 108 */ 109 typedef struct { 110 LLVMOrcSymbolStringPoolEntryRef Name; 111 LLVMJITSymbolFlags Flags; 112 } LLVMOrcCSymbolFlagsMapPair; 113 114 /** 115 * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used 116 * to construct a SymbolFlagsMap. 117 */ 118 typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs; 119 120 /** 121 * Represents a pair of a symbol name and an evaluated symbol. 122 */ 123 typedef struct { 124 LLVMOrcSymbolStringPoolEntryRef Name; 125 LLVMJITEvaluatedSymbol Sym; 126 } LLVMOrcCSymbolMapPair; 127 128 /** 129 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be 130 * used to construct a SymbolMap. 131 */ 132 typedef LLVMOrcCSymbolMapPair *LLVMOrcCSymbolMapPairs; 133 134 /** 135 * Represents a SymbolAliasMapEntry 136 */ 137 typedef struct { 138 LLVMOrcSymbolStringPoolEntryRef Name; 139 LLVMJITSymbolFlags Flags; 140 } LLVMOrcCSymbolAliasMapEntry; 141 142 /** 143 * Represents a pair of a symbol name and SymbolAliasMapEntry. 144 */ 145 typedef struct { 146 LLVMOrcSymbolStringPoolEntryRef Name; 147 LLVMOrcCSymbolAliasMapEntry Entry; 148 } LLVMOrcCSymbolAliasMapPair; 149 150 /** 151 * Represents a list of (SymbolStringPtr, (SymbolStringPtr, JITSymbolFlags)) 152 * pairs that can be used to construct a SymbolFlagsMap. 153 */ 154 typedef LLVMOrcCSymbolAliasMapPair *LLVMOrcCSymbolAliasMapPairs; 155 156 /** 157 * A reference to an orc::JITDylib instance. 158 */ 159 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef; 160 161 /** 162 * Represents a list of LLVMOrcSymbolStringPoolEntryRef and the associated 163 * length. 164 */ 165 typedef struct { 166 LLVMOrcSymbolStringPoolEntryRef *Symbols; 167 size_t Length; 168 } LLVMOrcCSymbolsList; 169 170 /** 171 * Represents a pair of a JITDylib and LLVMOrcCSymbolsList. 172 */ 173 typedef struct { 174 LLVMOrcJITDylibRef JD; 175 LLVMOrcCSymbolsList Names; 176 } LLVMOrcCDependenceMapPair; 177 178 /** 179 * Represents a list of (JITDylibRef, (LLVMOrcSymbolStringPoolEntryRef*, 180 * size_t)) pairs that can be used to construct a SymbolDependenceMap. 181 */ 182 typedef LLVMOrcCDependenceMapPair *LLVMOrcCDependenceMapPairs; 183 184 /** 185 * Lookup kind. This can be used by definition generators when deciding whether 186 * to produce a definition for a requested symbol. 187 * 188 * This enum should be kept in sync with llvm::orc::LookupKind. 189 */ 190 typedef enum { 191 LLVMOrcLookupKindStatic, 192 LLVMOrcLookupKindDLSym 193 } LLVMOrcLookupKind; 194 195 /** 196 * JITDylib lookup flags. This can be used by definition generators when 197 * deciding whether to produce a definition for a requested symbol. 198 * 199 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags. 200 */ 201 typedef enum { 202 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly, 203 LLVMOrcJITDylibLookupFlagsMatchAllSymbols 204 } LLVMOrcJITDylibLookupFlags; 205 206 /** 207 * An element type for a JITDylib search order. 208 */ 209 typedef struct { 210 LLVMOrcJITDylibRef JD; 211 LLVMOrcJITDylibLookupFlags JDLookupFlags; 212 } LLVMOrcCJITDylibSearchOrderElement; 213 214 /** 215 * A JITDylib search order. 216 * 217 * The list is terminated with an element containing a null pointer for the JD 218 * field. 219 */ 220 typedef LLVMOrcCJITDylibSearchOrderElement *LLVMOrcCJITDylibSearchOrder; 221 222 /** 223 * Symbol lookup flags for lookup sets. This should be kept in sync with 224 * llvm::orc::SymbolLookupFlags. 225 */ 226 typedef enum { 227 LLVMOrcSymbolLookupFlagsRequiredSymbol, 228 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol 229 } LLVMOrcSymbolLookupFlags; 230 231 /** 232 * An element type for a symbol lookup set. 233 */ 234 typedef struct { 235 LLVMOrcSymbolStringPoolEntryRef Name; 236 LLVMOrcSymbolLookupFlags LookupFlags; 237 } LLVMOrcCLookupSetElement; 238 239 /** 240 * A set of symbols to look up / generate. 241 * 242 * The list is terminated with an element containing a null pointer for the 243 * Name field. 244 * 245 * If a client creates an instance of this type then they are responsible for 246 * freeing it, and for ensuring that all strings have been retained over the 247 * course of its life. Clients receiving a copy from a callback are not 248 * responsible for managing lifetime or retain counts. 249 */ 250 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet; 251 252 /** 253 * A reference to a uniquely owned orc::MaterializationUnit instance. 254 */ 255 typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef; 256 257 /** 258 * A reference to a uniquely owned orc::MaterializationResponsibility instance. 259 * 260 * Ownership must be passed to a lower-level layer in a JIT stack. 261 */ 262 typedef struct LLVMOrcOpaqueMaterializationResponsibility 263 *LLVMOrcMaterializationResponsibilityRef; 264 265 /** 266 * A MaterializationUnit materialize callback. 267 * 268 * Ownership of the Ctx and MR arguments passes to the callback which must 269 * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment 270 * for that type). 271 * 272 * If this callback is called then the LLVMOrcMaterializationUnitDestroy 273 * callback will NOT be called. 274 */ 275 typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)( 276 void *Ctx, LLVMOrcMaterializationResponsibilityRef MR); 277 278 /** 279 * A MaterializationUnit discard callback. 280 * 281 * Ownership of JD and Symbol remain with the caller: These arguments should 282 * not be disposed of or released. 283 */ 284 typedef void (*LLVMOrcMaterializationUnitDiscardFunction)( 285 void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol); 286 287 /** 288 * A MaterializationUnit destruction callback. 289 * 290 * If a custom MaterializationUnit is destroyed before its Materialize 291 * function is called then this function will be called to provide an 292 * opportunity for the underlying program representation to be destroyed. 293 */ 294 typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx); 295 296 /** 297 * A reference to an orc::ResourceTracker instance. 298 */ 299 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef; 300 301 /** 302 * A reference to an orc::DefinitionGenerator. 303 */ 304 typedef struct LLVMOrcOpaqueDefinitionGenerator 305 *LLVMOrcDefinitionGeneratorRef; 306 307 /** 308 * An opaque lookup state object. Instances of this type can be captured to 309 * suspend a lookup while a custom generator function attempts to produce a 310 * definition. 311 * 312 * If a client captures a lookup state object then they must eventually call 313 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required 314 * in order to release memory allocated for the lookup state, even if errors 315 * have occurred while the lookup was suspended (if these errors have made the 316 * lookup impossible to complete then it will issue its own error before 317 * destruction). 318 */ 319 typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef; 320 321 /** 322 * A custom generator function. This can be used to create a custom generator 323 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting 324 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to 325 * receive callbacks when lookups fail to match existing definitions. 326 * 327 * GeneratorObj will contain the address of the custom generator object. 328 * 329 * Ctx will contain the context object passed to 330 * LLVMOrcCreateCustomCAPIDefinitionGenerator. 331 * 332 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This 333 * can optionally be modified to make the definition generation process 334 * asynchronous: If the LookupStateRef value is copied, and the original 335 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the 336 * asynchronous definition process has been completed clients must call 337 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be 338 * done unconditionally, even if errors have occurred in the mean time, to 339 * free the lookup state memory and notify the query object of the failures). 340 * If LookupState is captured this function must return LLVMErrorSuccess. 341 * 342 * The Kind argument can be inspected to determine the lookup kind (e.g. 343 * as-if-during-static-link, or as-if-during-dlsym). 344 * 345 * The JD argument specifies which JITDylib the definitions should be generated 346 * into. 347 * 348 * The JDLookupFlags argument can be inspected to determine whether the original 349 * lookup included non-exported symbols. 350 * 351 * Finally, the LookupSet argument contains the set of symbols that could not 352 * be found in JD already (the set of generation candidates). 353 */ 354 typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)( 355 LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx, 356 LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind, 357 LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags, 358 LLVMOrcCLookupSet LookupSet, size_t LookupSetSize); 359 360 /** 361 * Disposer for a custom generator. 362 * 363 * Will be called by ORC when the JITDylib that the generator is attached to 364 * is destroyed. 365 */ 366 typedef void (*LLVMOrcDisposeCAPIDefinitionGeneratorFunction)(void *Ctx); 367 368 /** 369 * Predicate function for SymbolStringPoolEntries. 370 */ 371 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx, 372 LLVMOrcSymbolStringPoolEntryRef Sym); 373 374 /** 375 * A reference to an orc::ThreadSafeContext instance. 376 */ 377 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef; 378 379 /** 380 * A reference to an orc::ThreadSafeModule instance. 381 */ 382 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef; 383 384 /** 385 * A function for inspecting/mutating IR modules, suitable for use with 386 * LLVMOrcThreadSafeModuleWithModuleDo. 387 */ 388 typedef LLVMErrorRef (*LLVMOrcGenericIRModuleOperationFunction)( 389 void *Ctx, LLVMModuleRef M); 390 391 /** 392 * A reference to an orc::JITTargetMachineBuilder instance. 393 */ 394 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder 395 *LLVMOrcJITTargetMachineBuilderRef; 396 397 /** 398 * A reference to an orc::ObjectLayer instance. 399 */ 400 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef; 401 402 /** 403 * A reference to an orc::ObjectLinkingLayer instance. 404 */ 405 typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef; 406 407 /** 408 * A reference to an orc::IRTransformLayer instance. 409 */ 410 typedef struct LLVMOrcOpaqueIRTransformLayer *LLVMOrcIRTransformLayerRef; 411 412 /** 413 * A function for applying transformations as part of an transform layer. 414 * 415 * Implementations of this type are responsible for managing the lifetime 416 * of the Module pointed to by ModInOut: If the LLVMModuleRef value is 417 * overwritten then the function is responsible for disposing of the incoming 418 * module. If the module is simply accessed/mutated in-place then ownership 419 * returns to the caller and the function does not need to do any lifetime 420 * management. 421 * 422 * Clients can call LLVMOrcLLJITGetIRTransformLayer to obtain the transform 423 * layer of a LLJIT instance, and use LLVMOrcIRTransformLayerSetTransform 424 * to set the function. This can be used to override the default transform 425 * layer. 426 */ 427 typedef LLVMErrorRef (*LLVMOrcIRTransformLayerTransformFunction)( 428 void *Ctx, LLVMOrcThreadSafeModuleRef *ModInOut, 429 LLVMOrcMaterializationResponsibilityRef MR); 430 431 /** 432 * A reference to an orc::ObjectTransformLayer instance. 433 */ 434 typedef struct LLVMOrcOpaqueObjectTransformLayer 435 *LLVMOrcObjectTransformLayerRef; 436 437 /** 438 * A function for applying transformations to an object file buffer. 439 * 440 * Implementations of this type are responsible for managing the lifetime 441 * of the memory buffer pointed to by ObjInOut: If the LLVMMemoryBufferRef 442 * value is overwritten then the function is responsible for disposing of the 443 * incoming buffer. If the buffer is simply accessed/mutated in-place then 444 * ownership returns to the caller and the function does not need to do any 445 * lifetime management. 446 * 447 * The transform is allowed to return an error, in which case the ObjInOut 448 * buffer should be disposed of and set to null. 449 */ 450 typedef LLVMErrorRef (*LLVMOrcObjectTransformLayerTransformFunction)( 451 void *Ctx, LLVMMemoryBufferRef *ObjInOut); 452 453 /** 454 * A reference to an orc::IndirectStubsManager instance. 455 */ 456 typedef struct LLVMOrcOpaqueIndirectStubsManager 457 *LLVMOrcIndirectStubsManagerRef; 458 459 /** 460 * A reference to an orc::LazyCallThroughManager instance. 461 */ 462 typedef struct LLVMOrcOpaqueLazyCallThroughManager 463 *LLVMOrcLazyCallThroughManagerRef; 464 465 /** 466 * A reference to an orc::DumpObjects object. 467 * 468 * Can be used to dump object files to disk with unique names. Useful as an 469 * ObjectTransformLayer transform. 470 */ 471 typedef struct LLVMOrcOpaqueDumpObjects *LLVMOrcDumpObjectsRef; 472 473 /** 474 * Attach a custom error reporter function to the ExecutionSession. 475 * 476 * The error reporter will be called to deliver failure notices that can not be 477 * directly reported to a caller. For example, failure to resolve symbols in 478 * the JIT linker is typically reported via the error reporter (callers 479 * requesting definitions from the JIT will typically be delivered a 480 * FailureToMaterialize error instead). 481 */ 482 void LLVMOrcExecutionSessionSetErrorReporter( 483 LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError, 484 void *Ctx); 485 486 /** 487 * Return a reference to the SymbolStringPool for an ExecutionSession. 488 * 489 * Ownership of the pool remains with the ExecutionSession: The caller is 490 * not required to free the pool. 491 */ 492 LLVMOrcSymbolStringPoolRef 493 LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES); 494 495 /** 496 * Clear all unreferenced symbol string pool entries. 497 * 498 * This can be called at any time to release unused entries in the 499 * ExecutionSession's string pool. Since it locks the pool (preventing 500 * interning of any new strings) it is recommended that it only be called 501 * infrequently, ideally when the caller has reason to believe that some 502 * entries will have become unreferenced, e.g. after removing a module or 503 * closing a JITDylib. 504 */ 505 void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP); 506 507 /** 508 * Intern a string in the ExecutionSession's SymbolStringPool and return a 509 * reference to it. This increments the ref-count of the pool entry, and the 510 * returned value should be released once the client is done with it by 511 * calling LLVMOrcReleaseSymbolStringPoolEntry. 512 * 513 * Since strings are uniqued within the SymbolStringPool 514 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string 515 * equality. 516 * 517 * Note that this function does not perform linker-mangling on the string. 518 */ 519 LLVMOrcSymbolStringPoolEntryRef 520 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name); 521 522 /** 523 * Callback type for ExecutionSession lookups. 524 * 525 * If Err is LLVMErrorSuccess then Result will contain a pointer to a 526 * list of ( SymbolStringPtr, JITEvaluatedSymbol ) pairs of length NumPairs. 527 * 528 * If Err is a failure value then Result and Ctx are undefined and should 529 * not be accessed. The Callback is responsible for handling the error 530 * value (e.g. by calling LLVMGetErrorMessage + LLVMDisposeErrorMessage). 531 * 532 * The caller retains ownership of the Result array and will release all 533 * contained symbol names. Clients are responsible for retaining any symbol 534 * names that they wish to hold after the function returns. 535 */ 536 typedef void (*LLVMOrcExecutionSessionLookupHandleResultFunction)( 537 LLVMErrorRef Err, LLVMOrcCSymbolMapPairs Result, size_t NumPairs, 538 void *Ctx); 539 540 /** 541 * Look up symbols in an execution session. 542 * 543 * This is a wrapper around the general ExecutionSession::lookup function. 544 * 545 * The SearchOrder argument contains a list of (JITDylibs, JITDylibSearchFlags) 546 * pairs that describe the search order. The JITDylibs will be searched in the 547 * given order to try to find the symbols in the Symbols argument. 548 * 549 * The Symbols argument should contain a null-terminated array of 550 * (SymbolStringPtr, SymbolLookupFlags) pairs describing the symbols to be 551 * searched for. This function takes ownership of the elements of the Symbols 552 * array. The Name fields of the Symbols elements are taken to have been 553 * retained by the client for this function. The client should *not* release the 554 * Name fields, but are still responsible for destroying the array itself. 555 * 556 * The HandleResult function will be called once all searched for symbols have 557 * been found, or an error occurs. The HandleResult function will be passed an 558 * LLVMErrorRef indicating success or failure, and (on success) a 559 * null-terminated LLVMOrcCSymbolMapPairs array containing the function result, 560 * and the Ctx value passed to the lookup function. 561 * 562 * The client is fully responsible for managing the lifetime of the Ctx object. 563 * A common idiom is to allocate the context prior to the lookup and deallocate 564 * it in the handler. 565 * 566 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE! 567 */ 568 void LLVMOrcExecutionSessionLookup( 569 LLVMOrcExecutionSessionRef ES, LLVMOrcLookupKind K, 570 LLVMOrcCJITDylibSearchOrder SearchOrder, size_t SearchOrderSize, 571 LLVMOrcCLookupSet Symbols, size_t SymbolsSize, 572 LLVMOrcExecutionSessionLookupHandleResultFunction HandleResult, void *Ctx); 573 574 /** 575 * Increments the ref-count for a SymbolStringPool entry. 576 */ 577 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 578 579 /** 580 * Reduces the ref-count for of a SymbolStringPool entry. 581 */ 582 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 583 584 /** 585 * Return the c-string for the given symbol. This string will remain valid until 586 * the entry is freed (once all LLVMOrcSymbolStringPoolEntryRefs have been 587 * released). 588 */ 589 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S); 590 591 /** 592 * Reduces the ref-count of a ResourceTracker. 593 */ 594 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT); 595 596 /** 597 * Transfers tracking of all resources associated with resource tracker SrcRT 598 * to resource tracker DstRT. 599 */ 600 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT, 601 LLVMOrcResourceTrackerRef DstRT); 602 603 /** 604 * Remove all resources associated with the given tracker. See 605 * ResourceTracker::remove(). 606 */ 607 LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT); 608 609 /** 610 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if 611 * ownership has not been passed to a JITDylib (e.g. because some error 612 * prevented the client from calling LLVMOrcJITDylibAddGenerator). 613 */ 614 void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG); 615 616 /** 617 * Dispose of a MaterializationUnit. 618 */ 619 void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU); 620 621 /** 622 * Create a custom MaterializationUnit. 623 * 624 * Name is a name for this MaterializationUnit to be used for identification 625 * and logging purposes (e.g. if this MaterializationUnit produces an 626 * object buffer then the name of that buffer will be derived from this name). 627 * 628 * The Syms list contains the names and linkages of the symbols provided by this 629 * unit. This function takes ownership of the elements of the Syms array. The 630 * Name fields of the array elements are taken to have been retained for this 631 * function. The client should *not* release the elements of the array, but is 632 * still responsible for destroying the array itself. 633 * 634 * The InitSym argument indicates whether or not this MaterializationUnit 635 * contains static initializers. If three are no static initializers (the common 636 * case) then this argument should be null. If there are static initializers 637 * then InitSym should be set to a unique name that also appears in the Syms 638 * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag 639 * set. This function takes ownership of the InitSym, which should have been 640 * retained twice on behalf of this function: once for the Syms entry and once 641 * for InitSym. If clients wish to use the InitSym value after this function 642 * returns they must retain it once more for themselves. 643 * 644 * If any of the symbols in the Syms list is looked up then the Materialize 645 * function will be called. 646 * 647 * If any of the symbols in the Syms list is overridden then the Discard 648 * function will be called. 649 * 650 * The caller owns the underling MaterializationUnit and is responsible for 651 * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing 652 * of it by calling LLVMOrcDisposeMaterializationUnit. 653 */ 654 LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit( 655 const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms, 656 size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym, 657 LLVMOrcMaterializationUnitMaterializeFunction Materialize, 658 LLVMOrcMaterializationUnitDiscardFunction Discard, 659 LLVMOrcMaterializationUnitDestroyFunction Destroy); 660 661 /** 662 * Create a MaterializationUnit to define the given symbols as pointing to 663 * the corresponding raw addresses. 664 * 665 * This function takes ownership of the elements of the Syms array. The Name 666 * fields of the array elements are taken to have been retained for this 667 * function. This allows the following pattern... 668 * 669 * size_t NumPairs; 670 * LLVMOrcCSymbolMapPairs Sym; 671 * -- Build Syms array -- 672 * LLVMOrcMaterializationUnitRef MU = 673 * LLVMOrcAbsoluteSymbols(Syms, NumPairs); 674 * 675 * ... without requiring cleanup of the elements of the Sym array afterwards. 676 * 677 * The client is still responsible for deleting the Sym array itself. 678 * 679 * If a client wishes to reuse elements of the Sym array after this call they 680 * must explicitly retain each of the elements for themselves. 681 */ 682 LLVMOrcMaterializationUnitRef 683 LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs); 684 685 /** 686 * Create a MaterializationUnit to define lazy re-expots. These are callable 687 * entry points that call through to the given symbols. 688 * 689 * This function takes ownership of the CallableAliases array. The Name 690 * fields of the array elements are taken to have been retained for this 691 * function. This allows the following pattern... 692 * 693 * size_t NumPairs; 694 * LLVMOrcCSymbolAliasMapPairs CallableAliases; 695 * -- Build CallableAliases array -- 696 * LLVMOrcMaterializationUnitRef MU = 697 * LLVMOrcLazyReexports(LCTM, ISM, JD, CallableAliases, NumPairs); 698 * 699 * ... without requiring cleanup of the elements of the CallableAliases array afterwards. 700 * 701 * The client is still responsible for deleting the CallableAliases array itself. 702 * 703 * If a client wishes to reuse elements of the CallableAliases array after this call they 704 * must explicitly retain each of the elements for themselves. 705 */ 706 LLVMOrcMaterializationUnitRef LLVMOrcLazyReexports( 707 LLVMOrcLazyCallThroughManagerRef LCTM, LLVMOrcIndirectStubsManagerRef ISM, 708 LLVMOrcJITDylibRef SourceRef, LLVMOrcCSymbolAliasMapPairs CallableAliases, 709 size_t NumPairs); 710 // TODO: ImplSymbolMad SrcJDLoc 711 712 /** 713 * Disposes of the passed MaterializationResponsibility object. 714 * 715 * This should only be done after the symbols covered by the object have either 716 * been resolved and emitted (via 717 * LLVMOrcMaterializationResponsibilityNotifyResolved and 718 * LLVMOrcMaterializationResponsibilityNotifyEmitted) or failed (via 719 * LLVMOrcMaterializationResponsibilityFailMaterialization). 720 */ 721 void LLVMOrcDisposeMaterializationResponsibility( 722 LLVMOrcMaterializationResponsibilityRef MR); 723 724 /** 725 * Returns the target JITDylib that these symbols are being materialized into. 726 */ 727 LLVMOrcJITDylibRef LLVMOrcMaterializationResponsibilityGetTargetDylib( 728 LLVMOrcMaterializationResponsibilityRef MR); 729 730 /** 731 * Returns the ExecutionSession for this MaterializationResponsibility. 732 */ 733 LLVMOrcExecutionSessionRef 734 LLVMOrcMaterializationResponsibilityGetExecutionSession( 735 LLVMOrcMaterializationResponsibilityRef MR); 736 737 /** 738 * Returns the symbol flags map for this responsibility instance. 739 * 740 * The length of the array is returned in NumPairs and the caller is responsible 741 * for the returned memory and needs to call LLVMOrcDisposeCSymbolFlagsMap. 742 * 743 * To use the returned symbols beyond the livetime of the 744 * MaterializationResponsibility requires the caller to retain the symbols 745 * explicitly. 746 */ 747 LLVMOrcCSymbolFlagsMapPairs LLVMOrcMaterializationResponsibilityGetSymbols( 748 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumPairs); 749 750 /** 751 * Disposes of the passed LLVMOrcCSymbolFlagsMap. 752 * 753 * Does not release the entries themselves. 754 */ 755 void LLVMOrcDisposeCSymbolFlagsMap(LLVMOrcCSymbolFlagsMapPairs Pairs); 756 757 /** 758 * Returns the initialization pseudo-symbol, if any. This symbol will also 759 * be present in the SymbolFlagsMap for this MaterializationResponsibility 760 * object. 761 * 762 * The returned symbol is not retained over any mutating operation of the 763 * MaterializationResponsbility or beyond the lifetime thereof. 764 */ 765 LLVMOrcSymbolStringPoolEntryRef 766 LLVMOrcMaterializationResponsibilityGetInitializerSymbol( 767 LLVMOrcMaterializationResponsibilityRef MR); 768 769 /** 770 * Returns the names of any symbols covered by this 771 * MaterializationResponsibility object that have queries pending. This 772 * information can be used to return responsibility for unrequested symbols 773 * back to the JITDylib via the delegate method. 774 */ 775 LLVMOrcSymbolStringPoolEntryRef * 776 LLVMOrcMaterializationResponsibilityGetRequestedSymbols( 777 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumSymbols); 778 779 /** 780 * Disposes of the passed LLVMOrcSymbolStringPoolEntryRef* . 781 * 782 * Does not release the symbols themselves. 783 */ 784 void LLVMOrcDisposeSymbols(LLVMOrcSymbolStringPoolEntryRef *Symbols); 785 786 /** 787 * Notifies the target JITDylib that the given symbols have been resolved. 788 * This will update the given symbols' addresses in the JITDylib, and notify 789 * any pending queries on the given symbols of their resolution. The given 790 * symbols must be ones covered by this MaterializationResponsibility 791 * instance. Individual calls to this method may resolve a subset of the 792 * symbols, but all symbols must have been resolved prior to calling emit. 793 * 794 * This method will return an error if any symbols being resolved have been 795 * moved to the error state due to the failure of a dependency. If this 796 * method returns an error then clients should log it and call 797 * LLVMOrcMaterializationResponsibilityFailMaterialization. If no dependencies 798 * have been registered for the symbols covered by this 799 * MaterializationResponsibility then this method is guaranteed to return 800 * LLVMErrorSuccess. 801 */ 802 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyResolved( 803 LLVMOrcMaterializationResponsibilityRef MR, LLVMOrcCSymbolMapPairs Symbols, 804 size_t NumPairs); 805 806 /** 807 * Notifies the target JITDylib (and any pending queries on that JITDylib) 808 * that all symbols covered by this MaterializationResponsibility instance 809 * have been emitted. 810 * 811 * This method will return an error if any symbols being resolved have been 812 * moved to the error state due to the failure of a dependency. If this 813 * method returns an error then clients should log it and call 814 * LLVMOrcMaterializationResponsibilityFailMaterialization. 815 * If no dependencies have been registered for the symbols covered by this 816 * MaterializationResponsibility then this method is guaranteed to return 817 * LLVMErrorSuccess. 818 */ 819 LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyEmitted( 820 LLVMOrcMaterializationResponsibilityRef MR); 821 822 /** 823 * Attempt to claim responsibility for new definitions. This method can be 824 * used to claim responsibility for symbols that are added to a 825 * materialization unit during the compilation process (e.g. literal pool 826 * symbols). Symbol linkage rules are the same as for symbols that are 827 * defined up front: duplicate strong definitions will result in errors. 828 * Duplicate weak definitions will be discarded (in which case they will 829 * not be added to this responsibility instance). 830 * 831 * This method can be used by materialization units that want to add 832 * additional symbols at materialization time (e.g. stubs, compile 833 * callbacks, metadata) 834 */ 835 LLVMErrorRef LLVMOrcMaterializationResponsibilityDefineMaterializing( 836 LLVMOrcMaterializationResponsibilityRef MR, 837 LLVMOrcCSymbolFlagsMapPairs Pairs, size_t NumPairs); 838 839 /** 840 * Notify all not-yet-emitted covered by this MaterializationResponsibility 841 * instance that an error has occurred. 842 * This will remove all symbols covered by this MaterializationResponsibility 843 * from the target JITDylib, and send an error to any queries waiting on 844 * these symbols. 845 */ 846 void LLVMOrcMaterializationResponsibilityFailMaterialization( 847 LLVMOrcMaterializationResponsibilityRef MR); 848 849 /** 850 * Transfers responsibility to the given MaterializationUnit for all 851 * symbols defined by that MaterializationUnit. This allows 852 * materializers to break up work based on run-time information (e.g. 853 * by introspecting which symbols have actually been looked up and 854 * materializing only those). 855 */ 856 LLVMErrorRef LLVMOrcMaterializationResponsibilityReplace( 857 LLVMOrcMaterializationResponsibilityRef MR, 858 LLVMOrcMaterializationUnitRef MU); 859 860 /** 861 * Delegates responsibility for the given symbols to the returned 862 * materialization responsibility. Useful for breaking up work between 863 * threads, or different kinds of materialization processes. 864 * 865 * The caller retains responsibility of the the passed 866 * MaterializationResponsibility. 867 */ 868 LLVMErrorRef LLVMOrcMaterializationResponsibilityDelegate( 869 LLVMOrcMaterializationResponsibilityRef MR, 870 LLVMOrcSymbolStringPoolEntryRef *Symbols, size_t NumSymbols, 871 LLVMOrcMaterializationResponsibilityRef *Result); 872 873 /** 874 * Adds dependencies to a symbol that the MaterializationResponsibility is 875 * responsible for. 876 * 877 * This function takes ownership of Dependencies struct. The Names 878 * array have been retained for this function. This allows the following 879 * pattern... 880 * 881 * LLVMOrcSymbolStringPoolEntryRef Names[] = {...}; 882 * LLVMOrcCDependenceMapPair Dependence = {JD, {Names, sizeof(Names)}} 883 * LLVMOrcMaterializationResponsibilityAddDependencies(JD, Name, &Dependence, 884 * 1); 885 * 886 * ... without requiring cleanup of the elements of the Names array afterwards. 887 * 888 * The client is still responsible for deleting the Dependencies.Names array 889 * itself. 890 */ 891 void LLVMOrcMaterializationResponsibilityAddDependencies( 892 LLVMOrcMaterializationResponsibilityRef MR, 893 LLVMOrcSymbolStringPoolEntryRef Name, 894 LLVMOrcCDependenceMapPairs Dependencies, size_t NumPairs); 895 896 /** 897 * Adds dependencies to all symbols that the MaterializationResponsibility is 898 * responsible for. See LLVMOrcMaterializationResponsibilityAddDependencies for 899 * notes about memory responsibility. 900 */ 901 void LLVMOrcMaterializationResponsibilityAddDependenciesForAll( 902 LLVMOrcMaterializationResponsibilityRef MR, 903 LLVMOrcCDependenceMapPairs Dependencies, size_t NumPairs); 904 905 /** 906 * Create a "bare" JITDylib. 907 * 908 * The client is responsible for ensuring that the JITDylib's name is unique, 909 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 910 * 911 * This call does not install any library code or symbols into the newly 912 * created JITDylib. The client is responsible for all configuration. 913 */ 914 LLVMOrcJITDylibRef 915 LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES, 916 const char *Name); 917 918 /** 919 * Create a JITDylib. 920 * 921 * The client is responsible for ensuring that the JITDylib's name is unique, 922 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 923 * 924 * If a Platform is attached to the ExecutionSession then 925 * Platform::setupJITDylib will be called to install standard platform symbols 926 * (e.g. standard library interposes). If no Platform is installed then this 927 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will 928 * always return success. 929 */ 930 LLVMErrorRef 931 LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES, 932 LLVMOrcJITDylibRef *Result, 933 const char *Name); 934 935 /** 936 * Returns the JITDylib with the given name, or NULL if no such JITDylib 937 * exists. 938 */ 939 LLVMOrcJITDylibRef 940 LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES, 941 const char *Name); 942 943 /** 944 * Return a reference to a newly created resource tracker associated with JD. 945 * The tracker is returned with an initial ref-count of 1, and must be released 946 * with LLVMOrcReleaseResourceTracker when no longer needed. 947 */ 948 LLVMOrcResourceTrackerRef 949 LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD); 950 951 /** 952 * Return a reference to the default resource tracker for the given JITDylib. 953 * This operation will increase the retain count of the tracker: Clients should 954 * call LLVMOrcReleaseResourceTracker when the result is no longer needed. 955 */ 956 LLVMOrcResourceTrackerRef 957 LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD); 958 959 /** 960 * Add the given MaterializationUnit to the given JITDylib. 961 * 962 * If this operation succeeds then JITDylib JD will take ownership of MU. 963 * If the operation fails then ownership remains with the caller who should 964 * call LLVMOrcDisposeMaterializationUnit to destroy it. 965 */ 966 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD, 967 LLVMOrcMaterializationUnitRef MU); 968 969 /** 970 * Calls remove on all trackers associated with this JITDylib, see 971 * JITDylib::clear(). 972 */ 973 LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD); 974 975 /** 976 * Add a DefinitionGenerator to the given JITDylib. 977 * 978 * The JITDylib will take ownership of the given generator: The client is no 979 * longer responsible for managing its memory. 980 */ 981 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD, 982 LLVMOrcDefinitionGeneratorRef DG); 983 984 /** 985 * Create a custom generator. 986 * 987 * The F argument will be used to implement the DefinitionGenerator's 988 * tryToGenerate method (see 989 * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction). 990 * 991 * Ctx is a context object that will be passed to F. This argument is 992 * permitted to be null. 993 * 994 * Dispose is the disposal function for Ctx. This argument is permitted to be 995 * null (in which case the client is responsible for the lifetime of Ctx). 996 */ 997 LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator( 998 LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx, 999 LLVMOrcDisposeCAPIDefinitionGeneratorFunction Dispose); 1000 1001 /** 1002 * Continue a lookup that was suspended in a generator (see 1003 * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction). 1004 */ 1005 void LLVMOrcLookupStateContinueLookup(LLVMOrcLookupStateRef S, 1006 LLVMErrorRef Err); 1007 1008 /** 1009 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into 1010 * the JITDylib. On success the resulting generator is owned by the client. 1011 * Ownership is typically transferred by adding the instance to a JITDylib 1012 * using LLVMOrcJITDylibAddGenerator, 1013 * 1014 * The GlobalPrefix argument specifies the character that appears on the front 1015 * of linker-mangled symbols for the target platform (e.g. '_' on MachO). 1016 * If non-null, this character will be stripped from the start of all symbol 1017 * strings before passing the remaining substring to dlsym. 1018 * 1019 * The optional Filter and Ctx arguments can be used to supply a symbol name 1020 * filter: Only symbols for which the filter returns true will be visible to 1021 * JIT'd code. If the Filter argument is null then all process symbols will 1022 * be visible to JIT'd code. Note that the symbol name passed to the Filter 1023 * function is the full mangled symbol: The client is responsible for stripping 1024 * the global prefix if present. 1025 */ 1026 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess( 1027 LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx, 1028 LLVMOrcSymbolPredicate Filter, void *FilterCtx); 1029 1030 /** 1031 * Get a LLVMOrcCreateDynamicLibararySearchGeneratorForPath that will reflect 1032 * library symbols into the JITDylib. On success the resulting generator is 1033 * owned by the client. Ownership is typically transferred by adding the 1034 * instance to a JITDylib using LLVMOrcJITDylibAddGenerator, 1035 * 1036 * The GlobalPrefix argument specifies the character that appears on the front 1037 * of linker-mangled symbols for the target platform (e.g. '_' on MachO). 1038 * If non-null, this character will be stripped from the start of all symbol 1039 * strings before passing the remaining substring to dlsym. 1040 * 1041 * The optional Filter and Ctx arguments can be used to supply a symbol name 1042 * filter: Only symbols for which the filter returns true will be visible to 1043 * JIT'd code. If the Filter argument is null then all library symbols will 1044 * be visible to JIT'd code. Note that the symbol name passed to the Filter 1045 * function is the full mangled symbol: The client is responsible for stripping 1046 * the global prefix if present. 1047 * 1048 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE! 1049 * 1050 */ 1051 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForPath( 1052 LLVMOrcDefinitionGeneratorRef *Result, const char *FileName, 1053 char GlobalPrefix, LLVMOrcSymbolPredicate Filter, void *FilterCtx); 1054 1055 /** 1056 * Get a LLVMOrcCreateStaticLibrarySearchGeneratorForPath that will reflect 1057 * static library symbols into the JITDylib. On success the resulting 1058 * generator is owned by the client. Ownership is typically transferred by 1059 * adding the instance to a JITDylib using LLVMOrcJITDylibAddGenerator, 1060 * 1061 * Call with the optional TargetTriple argument will succeed if the file at 1062 * the given path is a static library or a MachO universal binary containing a 1063 * static library that is compatible with the given triple. Otherwise it will 1064 * return an error. 1065 * 1066 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE! 1067 * 1068 */ 1069 LLVMErrorRef LLVMOrcCreateStaticLibrarySearchGeneratorForPath( 1070 LLVMOrcDefinitionGeneratorRef *Result, LLVMOrcObjectLayerRef ObjLayer, 1071 const char *FileName, const char *TargetTriple); 1072 1073 /** 1074 * Create a ThreadSafeContext containing a new LLVMContext. 1075 * 1076 * Ownership of the underlying ThreadSafeContext data is shared: Clients 1077 * can and should dispose of their ThreadSafeContext as soon as they no longer 1078 * need to refer to it directly. Other references (e.g. from ThreadSafeModules) 1079 * will keep the data alive as long as it is needed. 1080 */ 1081 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void); 1082 1083 /** 1084 * Get a reference to the wrapped LLVMContext. 1085 */ 1086 LLVMContextRef 1087 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx); 1088 1089 /** 1090 * Dispose of a ThreadSafeContext. 1091 */ 1092 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx); 1093 1094 /** 1095 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes 1096 * ownership of the M argument which should not be disposed of or referenced 1097 * after this function returns. 1098 * 1099 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT 1100 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer 1101 * responsible for it. If it is not transferred to the JIT then the client 1102 * should call LLVMOrcDisposeThreadSafeModule to dispose of it. 1103 */ 1104 LLVMOrcThreadSafeModuleRef 1105 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M, 1106 LLVMOrcThreadSafeContextRef TSCtx); 1107 1108 /** 1109 * Dispose of a ThreadSafeModule. This should only be called if ownership has 1110 * not been passed to LLJIT (e.g. because some error prevented the client from 1111 * adding this to the JIT). 1112 */ 1113 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM); 1114 1115 /** 1116 * Apply the given function to the module contained in this ThreadSafeModule. 1117 */ 1118 LLVMErrorRef 1119 LLVMOrcThreadSafeModuleWithModuleDo(LLVMOrcThreadSafeModuleRef TSM, 1120 LLVMOrcGenericIRModuleOperationFunction F, 1121 void *Ctx); 1122 1123 /** 1124 * Create a JITTargetMachineBuilder by detecting the host. 1125 * 1126 * On success the client owns the resulting JITTargetMachineBuilder. It must be 1127 * passed to a consuming operation (e.g. 1128 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 1129 * LLVMOrcDisposeJITTargetMachineBuilder. 1130 */ 1131 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost( 1132 LLVMOrcJITTargetMachineBuilderRef *Result); 1133 1134 /** 1135 * Create a JITTargetMachineBuilder from the given TargetMachine template. 1136 * 1137 * This operation takes ownership of the given TargetMachine and destroys it 1138 * before returing. The resulting JITTargetMachineBuilder is owned by the client 1139 * and must be passed to a consuming operation (e.g. 1140 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 1141 * LLVMOrcDisposeJITTargetMachineBuilder. 1142 */ 1143 LLVMOrcJITTargetMachineBuilderRef 1144 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM); 1145 1146 /** 1147 * Dispose of a JITTargetMachineBuilder. 1148 */ 1149 void LLVMOrcDisposeJITTargetMachineBuilder( 1150 LLVMOrcJITTargetMachineBuilderRef JTMB); 1151 1152 /** 1153 * Returns the target triple for the given JITTargetMachineBuilder as a string. 1154 * 1155 * The caller owns the resulting string as must dispose of it by calling 1156 * LLVMDisposeMessage 1157 */ 1158 char *LLVMOrcJITTargetMachineBuilderGetTargetTriple( 1159 LLVMOrcJITTargetMachineBuilderRef JTMB); 1160 1161 /** 1162 * Sets the target triple for the given JITTargetMachineBuilder to the given 1163 * string. 1164 */ 1165 void LLVMOrcJITTargetMachineBuilderSetTargetTriple( 1166 LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple); 1167 1168 /** 1169 * Add an object to an ObjectLayer to the given JITDylib. 1170 * 1171 * Adds a buffer representing an object file to the given JITDylib using the 1172 * given ObjectLayer instance. This operation transfers ownership of the buffer 1173 * to the ObjectLayer instance. The buffer should not be disposed of or 1174 * referenced once this function returns. 1175 * 1176 * Resources associated with the given object will be tracked by the given 1177 * JITDylib's default ResourceTracker. 1178 */ 1179 LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer, 1180 LLVMOrcJITDylibRef JD, 1181 LLVMMemoryBufferRef ObjBuffer); 1182 1183 /** 1184 * Add an object to an ObjectLayer using the given ResourceTracker. 1185 * 1186 * Adds a buffer representing an object file to the given ResourceTracker's 1187 * JITDylib using the given ObjectLayer instance. This operation transfers 1188 * ownership of the buffer to the ObjectLayer instance. The buffer should not 1189 * be disposed of or referenced once this function returns. 1190 * 1191 * Resources associated with the given object will be tracked by 1192 * ResourceTracker RT. 1193 */ 1194 LLVMErrorRef 1195 LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer, 1196 LLVMOrcResourceTrackerRef RT, 1197 LLVMMemoryBufferRef ObjBuffer); 1198 1199 /** 1200 * Emit an object buffer to an ObjectLayer. 1201 * 1202 * Ownership of the responsibility object and object buffer pass to this 1203 * function. The client is not responsible for cleanup. 1204 */ 1205 void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer, 1206 LLVMOrcMaterializationResponsibilityRef R, 1207 LLVMMemoryBufferRef ObjBuffer); 1208 1209 /** 1210 * Dispose of an ObjectLayer. 1211 */ 1212 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer); 1213 1214 void LLVMOrcIRTransformLayerEmit(LLVMOrcIRTransformLayerRef IRTransformLayer, 1215 LLVMOrcMaterializationResponsibilityRef MR, 1216 LLVMOrcThreadSafeModuleRef TSM); 1217 1218 /** 1219 * Set the transform function of the provided transform layer, passing through a 1220 * pointer to user provided context. 1221 */ 1222 void LLVMOrcIRTransformLayerSetTransform( 1223 LLVMOrcIRTransformLayerRef IRTransformLayer, 1224 LLVMOrcIRTransformLayerTransformFunction TransformFunction, void *Ctx); 1225 1226 /** 1227 * Set the transform function on an LLVMOrcObjectTransformLayer. 1228 */ 1229 void LLVMOrcObjectTransformLayerSetTransform( 1230 LLVMOrcObjectTransformLayerRef ObjTransformLayer, 1231 LLVMOrcObjectTransformLayerTransformFunction TransformFunction, void *Ctx); 1232 1233 /** 1234 * Create a LocalIndirectStubsManager from the given target triple. 1235 * 1236 * The resulting IndirectStubsManager is owned by the client 1237 * and must be disposed of by calling LLVMOrcDisposeDisposeIndirectStubsManager. 1238 */ 1239 LLVMOrcIndirectStubsManagerRef 1240 LLVMOrcCreateLocalIndirectStubsManager(const char *TargetTriple); 1241 1242 /** 1243 * Dispose of an IndirectStubsManager. 1244 */ 1245 void LLVMOrcDisposeIndirectStubsManager(LLVMOrcIndirectStubsManagerRef ISM); 1246 1247 LLVMErrorRef LLVMOrcCreateLocalLazyCallThroughManager( 1248 const char *TargetTriple, LLVMOrcExecutionSessionRef ES, 1249 LLVMOrcJITTargetAddress ErrorHandlerAddr, 1250 LLVMOrcLazyCallThroughManagerRef *LCTM); 1251 1252 /** 1253 * Dispose of an LazyCallThroughManager. 1254 */ 1255 void LLVMOrcDisposeLazyCallThroughManager( 1256 LLVMOrcLazyCallThroughManagerRef LCTM); 1257 1258 /** 1259 * Create a DumpObjects instance. 1260 * 1261 * DumpDir specifies the path to write dumped objects to. DumpDir may be empty 1262 * in which case files will be dumped to the working directory. 1263 * 1264 * IdentifierOverride specifies a file name stem to use when dumping objects. 1265 * If empty then each MemoryBuffer's identifier will be used (with a .o suffix 1266 * added if not already present). If an identifier override is supplied it will 1267 * be used instead, along with an incrementing counter (since all buffers will 1268 * use the same identifier, the resulting files will be named <ident>.o, 1269 * <ident>.2.o, <ident>.3.o, and so on). IdentifierOverride should not contain 1270 * an extension, as a .o suffix will be added by DumpObjects. 1271 */ 1272 LLVMOrcDumpObjectsRef LLVMOrcCreateDumpObjects(const char *DumpDir, 1273 const char *IdentifierOverride); 1274 1275 /** 1276 * Dispose of a DumpObjects instance. 1277 */ 1278 void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects); 1279 1280 /** 1281 * Dump the contents of the given MemoryBuffer. 1282 */ 1283 LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects, 1284 LLVMMemoryBufferRef *ObjBuffer); 1285 1286 /** 1287 * @} 1288 */ 1289 1290 LLVM_C_EXTERN_C_END 1291 1292 #endif /* LLVM_C_ORC_H */ 1293