llvm/include/llvm-c/LLJIT.h

   1 /*===----------- llvm-c/LLJIT.h - OrcV2 LLJIT 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 the LLJIT class in                 *|
  11 |* libLLVMOrcJIT.a, which provides a simple MCJIT-like ORC JIT.               *|
  12 |*                                                                            *|
  13 |* Many exotic languages can interoperate with C code but have a harder time  *|
  14 |* with C++ due to name mangling. So in addition to C, this interface enables *|
  15 |* tools written in such languages.                                           *|
  16 |*                                                                            *|
  17 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
  18 |*       changed without warning. Only C API usage documentation is           *|
  19 |*       provided. See the C++ documentation for all higher level ORC API     *|
  20 |*       details.                                                             *|
  21 |*                                                                            *|
  22 \*===----------------------------------------------------------------------===*/
  23
  24 #ifndef LLVM_C_LLJIT_H
  25 #define LLVM_C_LLJIT_H
  26
  27 #include "llvm-c/Error.h"
  28 #include "llvm-c/Orc.h"
  29 #include "llvm-c/TargetMachine.h"
  30 #include "llvm-c/Types.h"
  31
  32 LLVM_C_EXTERN_C_BEGIN
  33
  34 /**
  35  * A function for constructing an ObjectLinkingLayer instance to be used
  36  * by an LLJIT instance.
  37  *
  38  * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to
  39  * set the creator function to use when constructing an LLJIT instance.
  40  * This can be used to override the default linking layer implementation
  41  * that would otherwise be chosen by LLJITBuilder.
  42  *
  43  * Object linking layers returned by this function will become owned by the
  44  * LLJIT instance. The client is not responsible for managing their lifetimes
  45  * after the function returns.
  46  */
  47 typedef LLVMOrcObjectLayerRef (
  48     *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)(
  49     void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple);
  50
  51 /**
  52  * A reference to an orc::LLJITBuilder instance.
  53  */
  54 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;
  55
  56 /**
  57  * A reference to an orc::LLJIT instance.
  58  */
  59 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;
  60
  61 /**
  62  * Create an LLVMOrcLLJITBuilder.
  63  *
  64  * The client owns the resulting LLJITBuilder and should dispose of it using
  65  * LLVMOrcDisposeLLJITBuilder once they are done with it.
  66  */
  67 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);
  68
  69 /**
  70  * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership
  71  * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented
  72  * that function from being called).
  73  */
  74 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);
  75
  76 /**
  77  * Set the JITTargetMachineBuilder to be used when constructing the LLJIT
  78  * instance. Calling this function is optional: if it is not called then the
  79  * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a
  80  * JITTargetMachineBuilder.
  81  *
  82  * This function takes ownership of the JTMB argument: clients should not
  83  * dispose of the JITTargetMachineBuilder after calling this function.
  84  */
  85 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(
  86     LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);
  87
  88 /**
  89  * Set an ObjectLinkingLayer creator function for this LLJIT instance.
  90  */
  91 void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator(
  92     LLVMOrcLLJITBuilderRef Builder,
  93     LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx);
  94
  95 /**
  96  * Create an LLJIT instance from an LLJITBuilder.
  97  *
  98  * This operation takes ownership of the Builder argument: clients should not
  99  * dispose of the builder after calling this function (even if the function
 100  * returns an error). If a null Builder argument is provided then a
 101  * default-constructed LLJITBuilder will be used.
 102  *
 103  * On success the resulting LLJIT instance is uniquely owned by the client and
 104  * automatically manages the memory of all JIT'd code and all modules that are
 105  * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the
 106  * LLJIT instance will free all memory managed by the JIT, including JIT'd code
 107  * and not-yet compiled modules.
 108  */
 109 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,
 110                                 LLVMOrcLLJITBuilderRef Builder);
 111
 112 /**
 113  * Dispose of an LLJIT instance.
 114  */
 115 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);
 116
 117 /**
 118  * Get a reference to the ExecutionSession for this LLJIT instance.
 119  *
 120  * The ExecutionSession is owned by the LLJIT instance. The client is not
 121  * responsible for managing its memory.
 122  */
 123 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);
 124
 125 /**
 126  * Return a reference to the Main JITDylib.
 127  *
 128  * The JITDylib is owned by the LLJIT instance. The client is not responsible
 129  * for managing its memory.
 130  */
 131 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);
 132
 133 /**
 134  * Return the target triple for this LLJIT instance. This string is owned by
 135  * the LLJIT instance and should not be freed by the client.
 136  */
 137 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);
 138
 139 /**
 140  * Returns the global prefix character according to the LLJIT's DataLayout.
 141  */
 142 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);
 143
 144 /**
 145  * Mangles the given string according to the LLJIT instance's DataLayout, then
 146  * interns the result in the SymbolStringPool and returns a reference to the
 147  * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to
 148  * decrement the ref-count on the pool entry once they are finished with this
 149  * value.
 150  */
 151 LLVMOrcSymbolStringPoolEntryRef
 152 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);
 153
 154 /**
 155  * Add a buffer representing an object file to the given JITDylib in the given
 156  * LLJIT instance. This operation transfers ownership of the buffer to the
 157  * LLJIT instance. The buffer should not be disposed of or referenced once this
 158  * function returns.
 159  *
 160  * Resources associated with the given object will be tracked by the given
 161  * JITDylib's default resource tracker.
 162  */
 163 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD,
 164                                        LLVMMemoryBufferRef ObjBuffer);
 165
 166 /**
 167  * Add a buffer representing an object file to the given ResourceTracker's
 168  * JITDylib in the given LLJIT instance. This operation transfers ownership of
 169  * the buffer to the LLJIT instance. The buffer should not be disposed of or
 170  * referenced once this function returns.
 171  *
 172  * Resources associated with the given object will be tracked by ResourceTracker
 173  * RT.
 174  */
 175 LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J,
 176                                              LLVMOrcResourceTrackerRef RT,
 177                                              LLVMMemoryBufferRef ObjBuffer);
 178
 179 /**
 180  * Add an IR module to the given JITDylib in the given LLJIT instance. This
 181  * operation transfers ownership of the TSM argument to the LLJIT instance.
 182  * The TSM argument should not be disposed of or referenced once this
 183  * function returns.
 184  *
 185  * Resources associated with the given Module will be tracked by the given
 186  * JITDylib's default resource tracker.
 187  */
 188 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J,
 189                                          LLVMOrcJITDylibRef JD,
 190                                          LLVMOrcThreadSafeModuleRef TSM);
 191
 192 /**
 193  * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT
 194  * instance. This operation transfers ownership of the TSM argument to the LLJIT
 195  * instance. The TSM argument should not be disposed of or referenced once this
 196  * function returns.
 197  *
 198  * Resources associated with the given Module will be tracked by ResourceTracker
 199  * RT.
 200  */
 201 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J,
 202                                                LLVMOrcResourceTrackerRef JD,
 203                                                LLVMOrcThreadSafeModuleRef TSM);
 204
 205 /**
 206  * Look up the given symbol in the main JITDylib of the given LLJIT instance.
 207  *
 208  * This operation does not take ownership of the Name argument.
 209  */
 210 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,
 211                                 LLVMOrcExecutorAddress *Result,
 212                                 const char *Name);
 213
 214 /**
 215  * Returns a non-owning reference to the LLJIT instance's object linking layer.
 216  */
 217 LLVMOrcObjectLayerRef LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J);
 218
 219 /**
 220  * Returns a non-owning reference to the LLJIT instance's object linking layer.
 221  */
 222 LLVMOrcObjectTransformLayerRef
 223 LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J);
 224
 225 /**
 226  * Returns a non-owning reference to the LLJIT instance's IR transform layer.
 227  */
 228 LLVMOrcIRTransformLayerRef LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J);
 229
 230 /**
 231  * Get the LLJIT instance's default data layout string.
 232  *
 233  * This string is owned by the LLJIT instance and does not need to be freed
 234  * by the caller.
 235  */
 236 const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J);
 237
 238 LLVM_C_EXTERN_C_END
 239
 240 #endif /* LLVM_C_LLJIT_H */