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