1//===-- LinkGraphLinkingLayer.h - Link LinkGraphs with JITLink --*- 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// LinkGraphLinkingLayer and associated utilities.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_EXECUTIONENGINE_ORC_LINKGRAPHLINKINGLAYER_H
14#define LLVM_EXECUTIONENGINE_ORC_LINKGRAPHLINKINGLAYER_H
15
16#include "llvm/ADT/STLExtras.h"
17#include "llvm/ADT/StringRef.h"
18#include "llvm/ExecutionEngine/JITLink/JITLinkMemoryManager.h"
19#include "llvm/ExecutionEngine/Orc/Core.h"
20#include "llvm/ExecutionEngine/Orc/Layer.h"
21#include "llvm/ExecutionEngine/Orc/LinkGraphLayer.h"
22#include "llvm/Support/Compiler.h"
23#include "llvm/Support/Error.h"
24#include <algorithm>
25#include <cassert>
26#include <functional>
27#include <memory>
28#include <mutex>
29#include <utility>
30#include <vector>
31
32class LinkGraphLinkingLayerTests;
33
34namespace llvm {
35
36namespace jitlink {
37class EHFrameRegistrar;
38} // namespace jitlink
39
40namespace orc {
41
42/// LinkGraphLinkingLayer links LinkGraphs into the Executor using JITLink.
43///
44/// Clients can use this class to add LinkGraphs to an ExecutionSession, and it
45/// serves as a base for the ObjectLinkingLayer that can link object files.
46class LLVM_ABI LinkGraphLinkingLayer : public LinkGraphLayer,
47 private ResourceManager {
48 friend class ::LinkGraphLinkingLayerTests;
49 class JITLinkCtx;
50
51public:
52 /// Plugin instances can be added to the ObjectLinkingLayer to receive
53 /// callbacks when code is loaded or emitted, and when JITLink is being
54 /// configured.
55 class LLVM_ABI Plugin {
56 public:
57 virtual ~Plugin();
58 virtual void modifyPassConfig(MaterializationResponsibility &MR,
59 jitlink::LinkGraph &G,
60 jitlink::PassConfiguration &Config) {}
61
62 // Deprecated. Don't use this in new code. There will be a proper mechanism
63 // for capturing object buffers.
64 virtual void notifyMaterializing(MaterializationResponsibility &MR,
65 jitlink::LinkGraph &G,
66 jitlink::JITLinkContext &Ctx,
67 MemoryBufferRef InputObject) {}
68
69 virtual Error notifyEmitted(MaterializationResponsibility &MR) {
70 return Error::success();
71 }
72 virtual Error notifyFailed(MaterializationResponsibility &MR) = 0;
73 virtual Error notifyRemovingResources(JITDylib &JD, ResourceKey K) = 0;
74 virtual void notifyTransferringResources(JITDylib &JD, ResourceKey DstKey,
75 ResourceKey SrcKey) = 0;
76 };
77
78 /// Construct a LinkGraphLinkingLayer using the ExecutorProcessControl
79 /// instance's memory manager.
80 LinkGraphLinkingLayer(ExecutionSession &ES);
81
82 /// Construct a LinkGraphLinkingLayer using a custom memory manager.
83 LinkGraphLinkingLayer(ExecutionSession &ES,
84 jitlink::JITLinkMemoryManager &MemMgr);
85
86 /// Construct an LinkGraphLinkingLayer. Takes ownership of the given
87 /// JITLinkMemoryManager. This method is a temporary hack to simplify
88 /// co-existence with RTDyldObjectLinkingLayer (which also owns its
89 /// allocators).
90 LinkGraphLinkingLayer(ExecutionSession &ES,
91 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr);
92
93 /// Destroy the LinkGraphLinkingLayer.
94 ~LinkGraphLinkingLayer() override;
95
96 /// Add a plugin.
97 LinkGraphLinkingLayer &addPlugin(std::shared_ptr<Plugin> P) {
98 std::lock_guard<std::mutex> Lock(LayerMutex);
99 Plugins.push_back(x: std::move(P));
100 return *this;
101 }
102
103 /// Remove a plugin. This remove applies only to subsequent links (links
104 /// already underway will continue to use the plugin), and does not of itself
105 /// destroy the plugin -- destruction will happen once all shared pointers
106 /// (including those held by in-progress links) are destroyed.
107 void removePlugin(Plugin &P) {
108 std::lock_guard<std::mutex> Lock(LayerMutex);
109 auto I = llvm::find_if(Range&: Plugins, P: [&](const std::shared_ptr<Plugin> &Elem) {
110 return Elem.get() == &P;
111 });
112 assert(I != Plugins.end() && "Plugin not present");
113 Plugins.erase(position: I);
114 }
115
116 /// Emit a LinkGraph.
117 void emit(std::unique_ptr<MaterializationResponsibility> R,
118 std::unique_ptr<jitlink::LinkGraph> G) override;
119
120 /// Instructs this LinkgraphLinkingLayer instance to override the symbol flags
121 /// found in the LinkGraph with the flags supplied by the
122 /// MaterializationResponsibility instance. This is a workaround to support
123 /// symbol visibility in COFF, which does not use the libObject's
124 /// SF_Exported flag. Use only when generating / adding COFF object files.
125 ///
126 /// FIXME: We should be able to remove this if/when COFF properly tracks
127 /// exported symbols.
128 LinkGraphLinkingLayer &
129 setOverrideObjectFlagsWithResponsibilityFlags(bool OverrideObjectFlags) {
130 this->OverrideObjectFlags = OverrideObjectFlags;
131 return *this;
132 }
133
134 /// If set, this LinkGraphLinkingLayer instance will claim responsibility
135 /// for any symbols provided by a given object file that were not already in
136 /// the MaterializationResponsibility instance. Setting this flag allows
137 /// higher-level program representations (e.g. LLVM IR) to be added based on
138 /// only a subset of the symbols they provide, without having to write
139 /// intervening layers to scan and add the additional symbols. This trades
140 /// diagnostic quality for convenience however: If all symbols are enumerated
141 /// up-front then clashes can be detected and reported early (and usually
142 /// deterministically). If this option is set, clashes for the additional
143 /// symbols may not be detected until late, and detection may depend on
144 /// the flow of control through JIT'd code. Use with care.
145 LinkGraphLinkingLayer &
146 setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols) {
147 this->AutoClaimObjectSymbols = AutoClaimObjectSymbols;
148 return *this;
149 }
150
151protected:
152 /// Emit a LinkGraph with the given backing buffer.
153 ///
154 /// This overload is intended for use by ObjectLinkingLayer.
155 void emit(std::unique_ptr<MaterializationResponsibility> R,
156 std::unique_ptr<jitlink::LinkGraph> G,
157 std::unique_ptr<MemoryBuffer> ObjBuf);
158
159 std::function<void(std::unique_ptr<MemoryBuffer>)> ReturnObjectBuffer;
160
161private:
162 using FinalizedAlloc = jitlink::JITLinkMemoryManager::FinalizedAlloc;
163
164 struct SymbolDepGroup {
165 SmallVector<jitlink::Symbol *> Defs;
166 DenseSet<jitlink::Symbol *> Deps;
167 };
168
169 // Provides the basis for calculating orc::SymbolDependenceGroups.
170 static SmallVector<SymbolDepGroup> calculateDepGroups(jitlink::LinkGraph &G);
171
172 Error recordFinalizedAlloc(MaterializationResponsibility &MR,
173 FinalizedAlloc FA);
174 Error handleRemoveResources(JITDylib &JD, ResourceKey K) override;
175 void handleTransferResources(JITDylib &JD, ResourceKey DstKey,
176 ResourceKey SrcKey) override;
177
178 mutable std::mutex LayerMutex;
179 jitlink::JITLinkMemoryManager &MemMgr;
180 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgrOwnership;
181 bool OverrideObjectFlags = false;
182 bool AutoClaimObjectSymbols = false;
183 DenseMap<ResourceKey, std::vector<FinalizedAlloc>> Allocs;
184 std::vector<std::shared_ptr<Plugin>> Plugins;
185};
186
187} // end namespace orc
188} // end namespace llvm
189
190#endif // LLVM_EXECUTIONENGINE_ORC_LINKGRAPHLINKINGLAYER_H
191