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