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