1/*===-- llvm-c/OrcEE.h - OrcV2 C bindings ExecutionEngine utils -*- 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 ExecutionEngine based utils, e.g. *|
11|* RTDyldObjectLinkingLayer (based on RuntimeDyld) in Orc. *|
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_ORCEE_H
25#define LLVM_C_ORCEE_H
26
27#include "llvm-c/Error.h"
28#include "llvm-c/ExecutionEngine.h"
29#include "llvm-c/Orc.h"
30#include "llvm-c/TargetMachine.h"
31#include "llvm-c/Types.h"
32#include "llvm-c/Visibility.h"
33
34LLVM_C_EXTERN_C_BEGIN
35
36typedef void *(*LLVMMemoryManagerCreateContextCallback)(void *CtxCtx);
37typedef void (*LLVMMemoryManagerNotifyTerminatingCallback)(void *CtxCtx);
38
39/**
40 * @defgroup LLVMCExecutionEngineORCEE ExecutionEngine-based ORC Utils
41 * @ingroup LLVMCExecutionEngine
42 *
43 * @{
44 */
45
46/**
47 * Create a ObjectLinkingLayer instance using the standard JITLink
48 * InProcessMemoryManager for memory management.
49 */
50LLVM_C_ABI LLVMErrorRef
51LLVMOrcCreateObjectLinkingLayerWithInProcessMemoryManager(
52 LLVMOrcObjectLayerRef *Result, LLVMOrcExecutionSessionRef ES);
53
54/**
55 * Create a RTDyldObjectLinkingLayer instance using the standard
56 * SectionMemoryManager for memory management.
57 */
58LLVM_C_ABI LLVMOrcObjectLayerRef
59LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManager(
60 LLVMOrcExecutionSessionRef ES);
61
62/**
63 * Create a RTDyldObjectLinkingLayer instance using the standard
64 * SectionMemoryManager for memory management. If ReserveAlloc is true then
65 * a contiguous range of memory will be reserved for each object file.
66 */
67LLVM_C_ABI LLVMOrcObjectLayerRef
68LLVMOrcCreateRTDyldObjectLinkingLayerWithSectionMemoryManagerReserveAlloc(
69 LLVMOrcExecutionSessionRef ES, LLVMBool ReserveAlloc);
70
71/**
72 * Create a RTDyldObjectLinkingLayer instance using MCJIT-memory-manager-like
73 * callbacks.
74 *
75 * This is intended to simplify transitions for existing MCJIT clients. The
76 * callbacks used are similar (but not identical) to the callbacks for
77 * LLVMCreateSimpleMCJITMemoryManager: Unlike MCJIT, RTDyldObjectLinkingLayer
78 * will create a new memory manager for each object linked by calling the given
79 * CreateContext callback. This allows for code removal by destroying each
80 * allocator individually. Every allocator will be destroyed (if it has not been
81 * already) at RTDyldObjectLinkingLayer destruction time, and the
82 * NotifyTerminating callback will be called to indicate that no further
83 * allocation contexts will be created.
84 *
85 * To implement MCJIT-like behavior clients can implement CreateContext,
86 * NotifyTerminating, and Destroy as:
87 *
88 * void *CreateContext(void *CtxCtx) { return CtxCtx; }
89 * void NotifyTerminating(void *CtxCtx) { MyOriginalDestroy(CtxCtx); }
90 * void Destroy(void *Ctx) { }
91 *
92 * This scheme simply reuses the CreateContextCtx pointer as the one-and-only
93 * allocation context.
94 */
95LLVM_C_ABI LLVMOrcObjectLayerRef
96LLVMOrcCreateRTDyldObjectLinkingLayerWithMCJITMemoryManagerLikeCallbacks(
97 LLVMOrcExecutionSessionRef ES, void *CreateContextCtx,
98 LLVMMemoryManagerCreateContextCallback CreateContext,
99 LLVMMemoryManagerNotifyTerminatingCallback NotifyTerminating,
100 LLVMMemoryManagerAllocateCodeSectionCallback AllocateCodeSection,
101 LLVMMemoryManagerAllocateDataSectionCallback AllocateDataSection,
102 LLVMMemoryManagerFinalizeMemoryCallback FinalizeMemory,
103 LLVMMemoryManagerDestroyCallback Destroy);
104
105/**
106 * Add the given listener to the given RTDyldObjectLinkingLayer.
107 *
108 * Note: Layer must be an RTDyldObjectLinkingLayer instance or
109 * behavior is undefined.
110 */
111LLVM_C_ABI void LLVMOrcRTDyldObjectLinkingLayerRegisterJITEventListener(
112 LLVMOrcObjectLayerRef RTDyldObjLinkingLayer,
113 LLVMJITEventListenerRef Listener);
114
115/**
116 * @}
117 */
118
119LLVM_C_EXTERN_C_END
120
121#endif /* LLVM_C_ORCEE_H */
122