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.
79 LinkGraphLinkingLayer(ExecutionSession &ES,
80 jitlink::JITLinkMemoryManager &MemMgr);
81
82 /// Construct an LinkGraphLinkingLayer. Takes ownership of the given
83 /// JITLinkMemoryManager. This method is a temporary hack to simplify
84 /// co-existence with RTDyldObjectLinkingLayer (which also owns its
85 /// allocators).
86 LinkGraphLinkingLayer(ExecutionSession &ES,
87 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr);
88
89 /// Destroy the LinkGraphLinkingLayer.
90 ~LinkGraphLinkingLayer() override;
91
92 /// Add a plugin.
93 LinkGraphLinkingLayer &addPlugin(std::shared_ptr<Plugin> P) {
94 std::lock_guard<std::mutex> Lock(LayerMutex);
95 Plugins.push_back(x: std::move(P));
96 return *this;
97 }
98
99 /// Remove a plugin. This remove applies only to subsequent links (links
100 /// already underway will continue to use the plugin), and does not of itself
101 /// destroy the plugin -- destruction will happen once all shared pointers
102 /// (including those held by in-progress links) are destroyed.
103 void removePlugin(Plugin &P) {
104 std::lock_guard<std::mutex> Lock(LayerMutex);
105 auto I = llvm::find_if(Range&: Plugins, P: [&](const std::shared_ptr<Plugin> &Elem) {
106 return Elem.get() == &P;
107 });
108 assert(I != Plugins.end() && "Plugin not present");
109 Plugins.erase(position: I);
110 }
111
112 /// Emit a LinkGraph.
113 void emit(std::unique_ptr<MaterializationResponsibility> R,
114 std::unique_ptr<jitlink::LinkGraph> G) override;
115
116 /// Instructs this LinkgraphLinkingLayer instance to override the symbol flags
117 /// found in the LinkGraph with the flags supplied by the
118 /// MaterializationResponsibility instance. This is a workaround to support
119 /// symbol visibility in COFF, which does not use the libObject's
120 /// SF_Exported flag. Use only when generating / adding COFF object files.
121 ///
122 /// FIXME: We should be able to remove this if/when COFF properly tracks
123 /// exported symbols.
124 LinkGraphLinkingLayer &
125 setOverrideObjectFlagsWithResponsibilityFlags(bool OverrideObjectFlags) {
126 this->OverrideObjectFlags = OverrideObjectFlags;
127 return *this;
128 }
129
130 /// If set, this LinkGraphLinkingLayer instance will claim responsibility
131 /// for any symbols provided by a given object file that were not already in
132 /// the MaterializationResponsibility instance. Setting this flag allows
133 /// higher-level program representations (e.g. LLVM IR) to be added based on
134 /// only a subset of the symbols they provide, without having to write
135 /// intervening layers to scan and add the additional symbols. This trades
136 /// diagnostic quality for convenience however: If all symbols are enumerated
137 /// up-front then clashes can be detected and reported early (and usually
138 /// deterministically). If this option is set, clashes for the additional
139 /// symbols may not be detected until late, and detection may depend on
140 /// the flow of control through JIT'd code. Use with care.
141 LinkGraphLinkingLayer &
142 setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols) {
143 this->AutoClaimObjectSymbols = AutoClaimObjectSymbols;
144 return *this;
145 }
146
147protected:
148 /// Emit a LinkGraph with the given backing buffer.
149 ///
150 /// This overload is intended for use by ObjectLinkingLayer.
151 void emit(std::unique_ptr<MaterializationResponsibility> R,
152 std::unique_ptr<jitlink::LinkGraph> G,
153 std::unique_ptr<MemoryBuffer> ObjBuf);
154
155 std::function<void(std::unique_ptr<MemoryBuffer>)> ReturnObjectBuffer;
156
157private:
158 using FinalizedAlloc = jitlink::JITLinkMemoryManager::FinalizedAlloc;
159
160 struct SymbolDepGroup {
161 SmallVector<jitlink::Symbol *> Defs;
162 DenseSet<jitlink::Symbol *> Deps;
163 };
164
165 // Provides the basis for calculating orc::SymbolDependenceGroups.
166 static SmallVector<SymbolDepGroup> calculateDepGroups(jitlink::LinkGraph &G);
167
168 Error recordFinalizedAlloc(MaterializationResponsibility &MR,
169 FinalizedAlloc FA);
170 Error handleRemoveResources(JITDylib &JD, ResourceKey K) override;
171 void handleTransferResources(JITDylib &JD, ResourceKey DstKey,
172 ResourceKey SrcKey) override;
173
174 mutable std::mutex LayerMutex;
175 jitlink::JITLinkMemoryManager &MemMgr;
176 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgrOwnership;
177 bool OverrideObjectFlags = false;
178 bool AutoClaimObjectSymbols = false;
179 DenseMap<ResourceKey, std::vector<FinalizedAlloc>> Allocs;
180 std::vector<std::shared_ptr<Plugin>> Plugins;
181};
182
183} // end namespace orc
184} // end namespace llvm
185
186#endif // LLVM_EXECUTIONENGINE_ORC_LINKGRAPHLINKINGLAYER_H
187