llvm/include/llvm-c/Orc.h

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