LLVM 19.0.0git
ObjectLinkingLayer.h
Go to the documentation of this file.
1//===-- ObjectLinkingLayer.h - JITLink-based jit linking layer --*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// Contains the definition for an JITLink-based, in-process object linking
10// layer.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_EXECUTIONENGINE_ORC_OBJECTLINKINGLAYER_H
15#define LLVM_EXECUTIONENGINE_ORC_OBJECTLINKINGLAYER_H
16
17#include "llvm/ADT/STLExtras.h"
18#include "llvm/ADT/StringRef.h"
23#include "llvm/Support/Error.h"
24#include <algorithm>
25#include <cassert>
26#include <functional>
27#include <list>
28#include <memory>
29#include <utility>
30#include <vector>
31
32namespace llvm {
33
34namespace jitlink {
35class EHFrameRegistrar;
36class LinkGraph;
37class Symbol;
38} // namespace jitlink
39
40namespace orc {
41
42class ObjectLinkingLayerJITLinkContext;
43
44/// An ObjectLayer implementation built on JITLink.
45///
46/// Clients can use this class to add relocatable object files to an
47/// ExecutionSession, and it typically serves as the base layer (underneath
48/// a compiling layer like IRCompileLayer) for the rest of the JIT.
49class ObjectLinkingLayer : public RTTIExtends<ObjectLinkingLayer, ObjectLayer>,
50 private ResourceManager {
52
53public:
54 static char ID;
55
56 /// Plugin instances can be added to the ObjectLinkingLayer to receive
57 /// callbacks when code is loaded or emitted, and when JITLink is being
58 /// configured.
59 class Plugin {
60 public:
64
65 virtual ~Plugin();
69
70 // Deprecated. Don't use this in new code. There will be a proper mechanism
71 // for capturing object buffers.
75 MemoryBufferRef InputObject) {}
76
79 return Error::success();
80 }
84 ResourceKey SrcKey) = 0;
85
86 /// Return any dependencies that synthetic symbols (e.g. init symbols)
87 /// have on symbols in the LinkGraph.
88 /// This is used by the ObjectLinkingLayer to update the dependencies for
89 /// the synthetic symbols.
93 }
94 };
95
97 std::function<void(std::unique_ptr<MemoryBuffer>)>;
98
99 /// Construct an ObjectLinkingLayer using the ExecutorProcessControl
100 /// instance's memory manager.
102
103 /// Construct an ObjectLinkingLayer using a custom memory manager.
106
107 /// Construct an ObjectLinkingLayer. Takes ownership of the given
108 /// JITLinkMemoryManager. This method is a temporary hack to simplify
109 /// co-existence with RTDyldObjectLinkingLayer (which also owns its
110 /// allocators).
112 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr);
113
114 /// Destruct an ObjectLinkingLayer.
116
117 /// Set an object buffer return function. By default object buffers are
118 /// deleted once the JIT has linked them. If a return function is set then
119 /// it will be called to transfer ownership of the buffer instead.
121 this->ReturnObjectBuffer = std::move(ReturnObjectBuffer);
122 }
123
124 /// Add a pass-config modifier.
125 ObjectLinkingLayer &addPlugin(std::unique_ptr<Plugin> P) {
126 std::lock_guard<std::mutex> Lock(LayerMutex);
127 Plugins.push_back(std::move(P));
128 return *this;
129 }
130
131 /// Add a LinkGraph to the JITDylib targeted by the given tracker.
132 Error add(ResourceTrackerSP, std::unique_ptr<jitlink::LinkGraph> G);
133
134 /// Add a LinkGraph to the given JITDylib.
135 Error add(JITDylib &JD, std::unique_ptr<jitlink::LinkGraph> G) {
136 return add(JD.getDefaultResourceTracker(), std::move(G));
137 }
138
139 // Un-hide ObjectLayer add methods.
140 using ObjectLayer::add;
141
142 /// Emit an object file.
143 void emit(std::unique_ptr<MaterializationResponsibility> R,
144 std::unique_ptr<MemoryBuffer> O) override;
145
146 /// Emit a LinkGraph.
147 void emit(std::unique_ptr<MaterializationResponsibility> R,
148 std::unique_ptr<jitlink::LinkGraph> G);
149
150 /// Instructs this ObjectLinkingLayer instance to override the symbol flags
151 /// found in the AtomGraph with the flags supplied by the
152 /// MaterializationResponsibility instance. This is a workaround to support
153 /// symbol visibility in COFF, which does not use the libObject's
154 /// SF_Exported flag. Use only when generating / adding COFF object files.
155 ///
156 /// FIXME: We should be able to remove this if/when COFF properly tracks
157 /// exported symbols.
160 this->OverrideObjectFlags = OverrideObjectFlags;
161 return *this;
162 }
163
164 /// If set, this ObjectLinkingLayer instance will claim responsibility
165 /// for any symbols provided by a given object file that were not already in
166 /// the MaterializationResponsibility instance. Setting this flag allows
167 /// higher-level program representations (e.g. LLVM IR) to be added based on
168 /// only a subset of the symbols they provide, without having to write
169 /// intervening layers to scan and add the additional symbols. This trades
170 /// diagnostic quality for convenience however: If all symbols are enumerated
171 /// up-front then clashes can be detected and reported early (and usually
172 /// deterministically). If this option is set, clashes for the additional
173 /// symbols may not be detected until late, and detection may depend on
174 /// the flow of control through JIT'd code. Use with care.
176 setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols) {
177 this->AutoClaimObjectSymbols = AutoClaimObjectSymbols;
178 return *this;
179 }
180
181private:
183
184 void modifyPassConfig(MaterializationResponsibility &MR,
186 jitlink::PassConfiguration &PassConfig);
187 void notifyLoaded(MaterializationResponsibility &MR);
188 Error notifyEmitted(MaterializationResponsibility &MR, FinalizedAlloc FA);
189
190 Error handleRemoveResources(JITDylib &JD, ResourceKey K) override;
191 void handleTransferResources(JITDylib &JD, ResourceKey DstKey,
192 ResourceKey SrcKey) override;
193
194 mutable std::mutex LayerMutex;
196 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgrOwnership;
197 bool OverrideObjectFlags = false;
198 bool AutoClaimObjectSymbols = false;
199 ReturnObjectBufferFunction ReturnObjectBuffer;
201 std::vector<std::unique_ptr<Plugin>> Plugins;
202};
203
205public:
208 std::unique_ptr<jitlink::EHFrameRegistrar> Registrar);
211 jitlink::PassConfiguration &PassConfig) override;
216 ResourceKey SrcKey) override;
217
218private:
219 std::mutex EHFramePluginMutex;
221 std::unique_ptr<jitlink::EHFrameRegistrar> Registrar;
224};
225
226} // end namespace orc
227} // end namespace llvm
228
229#endif // LLVM_EXECUTIONENGINE_ORC_OBJECTLINKINGLAYER_H
dxil metadata emit
RelaxConfig Config
Definition: ELF_riscv.cpp:506
#define G(x, y, z)
Definition: MD5.cpp:56
#define P(N)
This file contains some templates that are useful if you are working with the STL at all.
Implements a dense probed hash-table based set.
Definition: DenseSet.h:271
Lightweight error class with error context and mandatory checking.
Definition: Error.h:160
static ErrorSuccess success()
Create a success value.
Definition: Error.h:334
Inheritance utility for extensible RTTI.
void notifyTransferringResources(JITDylib &JD, ResourceKey DstKey, ResourceKey SrcKey) override
Error notifyEmitted(MaterializationResponsibility &MR) override
Error notifyFailed(MaterializationResponsibility &MR) override
Error notifyRemovingResources(JITDylib &JD, ResourceKey K) override
void modifyPassConfig(MaterializationResponsibility &MR, jitlink::LinkGraph &G, jitlink::PassConfiguration &PassConfig) override
An ExecutionSession represents a running JIT program.
Definition: Core.h:1425
Represents a JIT'd dynamic library.
Definition: Core.h:989
ResourceTrackerSP getDefaultResourceTracker()
Get the default resource tracker for this JITDylib.
Definition: Core.cpp:691
Tracks responsibility for materialization, and mediates interactions between MaterializationUnits and...
Definition: Core.h:555
virtual Error add(ResourceTrackerSP RT, std::unique_ptr< MemoryBuffer > O, MaterializationUnit::Interface I)
Adds a MaterializationUnit for the object file in the given memory buffer to the JITDylib for the giv...
Definition: Layer.cpp:170
Plugin instances can be added to the ObjectLinkingLayer to receive callbacks when code is loaded or e...
virtual Error notifyRemovingResources(JITDylib &JD, ResourceKey K)=0
virtual void notifyMaterializing(MaterializationResponsibility &MR, jitlink::LinkGraph &G, jitlink::JITLinkContext &Ctx, MemoryBufferRef InputObject)
virtual Error notifyFailed(MaterializationResponsibility &MR)=0
DenseMap< SymbolStringPtr, JITLinkSymbolSet > SyntheticSymbolDependenciesMap
virtual void notifyLoaded(MaterializationResponsibility &MR)
virtual Error notifyEmitted(MaterializationResponsibility &MR)
virtual void modifyPassConfig(MaterializationResponsibility &MR, jitlink::LinkGraph &G, jitlink::PassConfiguration &Config)
virtual SyntheticSymbolDependenciesMap getSyntheticSymbolDependencies(MaterializationResponsibility &MR)
Return any dependencies that synthetic symbols (e.g.
virtual void notifyTransferringResources(JITDylib &JD, ResourceKey DstKey, ResourceKey SrcKey)=0
An ObjectLayer implementation built on JITLink.
ObjectLinkingLayer & setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols)
If set, this ObjectLinkingLayer instance will claim responsibility for any symbols provided by a give...
ObjectLinkingLayer & setOverrideObjectFlagsWithResponsibilityFlags(bool OverrideObjectFlags)
Instructs this ObjectLinkingLayer instance to override the symbol flags found in the AtomGraph with t...
void setReturnObjectBuffer(ReturnObjectBufferFunction ReturnObjectBuffer)
Set an object buffer return function.
std::function< void(std::unique_ptr< MemoryBuffer >)> ReturnObjectBufferFunction
ObjectLinkingLayer & addPlugin(std::unique_ptr< Plugin > P)
Add a pass-config modifier.
Error add(ResourceTrackerSP, std::unique_ptr< jitlink::LinkGraph > G)
Add a LinkGraph to the JITDylib targeted by the given tracker.
void emit(std::unique_ptr< MaterializationResponsibility > R, std::unique_ptr< jitlink::LinkGraph > G)
Emit a LinkGraph.
~ObjectLinkingLayer()
Destruct an ObjectLinkingLayer.
ObjectLinkingLayer(ExecutionSession &ES, std::unique_ptr< jitlink::JITLinkMemoryManager > MemMgr)
Construct an ObjectLinkingLayer.
Error add(JITDylib &JD, std::unique_ptr< jitlink::LinkGraph > G)
Add a LinkGraph to the given JITDylib.
Listens for ResourceTracker operations.
Definition: Core.h:104
uintptr_t ResourceKey
Definition: Core.h:53
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18