LLVM  12.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/StringMap.h"
19 #include "llvm/ADT/StringRef.h"
24 #include "llvm/Support/Error.h"
25 #include <algorithm>
26 #include <cassert>
27 #include <functional>
28 #include <list>
29 #include <memory>
30 #include <string>
31 #include <utility>
32 #include <vector>
33 
34 namespace llvm {
35 
36 namespace jitlink {
37 class EHFrameRegistrar;
38 class Symbol;
39 } // namespace jitlink
40 
41 namespace object {
42 class ObjectFile;
43 } // namespace object
44 
45 namespace orc {
46 
47 class ObjectLinkingLayerJITLinkContext;
48 
49 /// An ObjectLayer implementation built on JITLink.
50 ///
51 /// Clients can use this class to add relocatable object files to an
52 /// ExecutionSession, and it typically serves as the base layer (underneath
53 /// a compiling layer like IRCompileLayer) for the rest of the JIT.
56 
57 public:
58  /// Plugin instances can be added to the ObjectLinkingLayer to receive
59  /// callbacks when code is loaded or emitted, and when JITLink is being
60  /// configured.
61  class Plugin {
62  public:
63  using JITLinkSymbolVector = std::vector<const jitlink::Symbol *>;
65 
66  virtual ~Plugin();
68  const Triple &TT,
69  jitlink::PassConfiguration &Config) {}
70 
73  return Error::success();
74  }
75  virtual Error notifyFailed(MaterializationResponsibility &MR) = 0;
76  virtual Error notifyRemovingResources(ResourceKey K) = 0;
77  virtual void notifyTransferringResources(ResourceKey DstKey,
78  ResourceKey SrcKey) = 0;
79 
80  /// Return any dependencies that synthetic symbols (e.g. init symbols)
81  /// have on locally scoped jitlink::Symbols. This is used by the
82  /// ObjectLinkingLayer to update the dependencies for the synthetic
83  /// symbols.
84  virtual LocalDependenciesMap
86  return LocalDependenciesMap();
87  }
88  };
89 
91  std::function<void(std::unique_ptr<MemoryBuffer>)>;
92 
93  /// Construct an ObjectLinkingLayer.
96 
97  /// Construct an ObjectLinkingLayer. Takes ownership of the given
98  /// JITLinkMemoryManager. This method is a temporary hack to simplify
99  /// co-existence with RTDyldObjectLinkingLayer (which also owns its
100  /// allocators).
102  std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr);
103 
104  /// Destruct an ObjectLinkingLayer.
106 
107  /// Set an object buffer return function. By default object buffers are
108  /// deleted once the JIT has linked them. If a return function is set then
109  /// it will be called to transfer ownership of the buffer instead.
111  this->ReturnObjectBuffer = std::move(ReturnObjectBuffer);
112  }
113 
114  /// Add a pass-config modifier.
115  ObjectLinkingLayer &addPlugin(std::unique_ptr<Plugin> P) {
116  std::lock_guard<std::mutex> Lock(LayerMutex);
117  Plugins.push_back(std::move(P));
118  return *this;
119  }
120 
121  /// Emit the object.
122  void emit(std::unique_ptr<MaterializationResponsibility> R,
123  std::unique_ptr<MemoryBuffer> O) override;
124 
125  /// Instructs this ObjectLinkingLayer instance to override the symbol flags
126  /// found in the AtomGraph with the flags supplied by the
127  /// MaterializationResponsibility instance. This is a workaround to support
128  /// symbol visibility in COFF, which does not use the libObject's
129  /// SF_Exported flag. Use only when generating / adding COFF object files.
130  ///
131  /// FIXME: We should be able to remove this if/when COFF properly tracks
132  /// exported symbols.
135  this->OverrideObjectFlags = OverrideObjectFlags;
136  return *this;
137  }
138 
139  /// If set, this ObjectLinkingLayer instance will claim responsibility
140  /// for any symbols provided by a given object file that were not already in
141  /// the MaterializationResponsibility instance. Setting this flag allows
142  /// higher-level program representations (e.g. LLVM IR) to be added based on
143  /// only a subset of the symbols they provide, without having to write
144  /// intervening layers to scan and add the additional symbols. This trades
145  /// diagnostic quality for convenience however: If all symbols are enumerated
146  /// up-front then clashes can be detected and reported early (and usually
147  /// deterministically). If this option is set, clashes for the additional
148  /// symbols may not be detected until late, and detection may depend on
149  /// the flow of control through JIT'd code. Use with care.
151  setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols) {
152  this->AutoClaimObjectSymbols = AutoClaimObjectSymbols;
153  return *this;
154  }
155 
156 private:
157  using AllocPtr = std::unique_ptr<jitlink::JITLinkMemoryManager::Allocation>;
158 
159  void modifyPassConfig(MaterializationResponsibility &MR, const Triple &TT,
160  jitlink::PassConfiguration &PassConfig);
161  void notifyLoaded(MaterializationResponsibility &MR);
162  Error notifyEmitted(MaterializationResponsibility &MR, AllocPtr Alloc);
163 
164  Error handleRemoveResources(ResourceKey K) override;
165  void handleTransferResources(ResourceKey DstKey, ResourceKey SrcKey) override;
166 
167  mutable std::mutex LayerMutex;
169  std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgrOwnership;
170  bool OverrideObjectFlags = false;
171  bool AutoClaimObjectSymbols = false;
172  ReturnObjectBufferFunction ReturnObjectBuffer;
174  std::vector<std::unique_ptr<Plugin>> Plugins;
175 };
176 
178 public:
180  ExecutionSession &ES,
181  std::unique_ptr<jitlink::EHFrameRegistrar> Registrar);
182  void modifyPassConfig(MaterializationResponsibility &MR, const Triple &TT,
183  jitlink::PassConfiguration &PassConfig) override;
184  Error notifyEmitted(MaterializationResponsibility &MR) override;
185  Error notifyFailed(MaterializationResponsibility &MR) override;
186  Error notifyRemovingResources(ResourceKey K) override;
187  void notifyTransferringResources(ResourceKey DstKey,
188  ResourceKey SrcKey) override;
189 
190 private:
191 
192  struct EHFrameRange {
193  JITTargetAddress Addr = 0;
194  size_t Size;
195  };
196 
197  std::mutex EHFramePluginMutex;
198  ExecutionSession &ES;
199  std::unique_ptr<jitlink::EHFrameRegistrar> Registrar;
202 };
203 
204 } // end namespace orc
205 } // end namespace llvm
206 
207 #endif // LLVM_EXECUTIONENGINE_ORC_OBJECTLINKINGLAYER_H
Listens for ResourceTracker operations.
Definition: Core.h:93
This class represents lattice values for constants.
Definition: AllocatorList.h:23
std::function< void(std::unique_ptr< MemoryBuffer >)> ReturnObjectBufferFunction
static sys::Mutex Lock
uintptr_t ResourceKey
Definition: Core.h:46
Plugin instances can be added to the ObjectLinkingLayer to receive callbacks when code is loaded or e...
virtual Error notifyEmitted(MaterializationResponsibility &MR)
ObjectLinkingLayer & setOverrideObjectFlagsWithResponsibilityFlags(bool OverrideObjectFlags)
Instructs this ObjectLinkingLayer instance to override the symbol flags found in the AtomGraph with t...
An ObjectLayer implementation built on JITLink.
Tracks responsibility for materialization, and mediates interactions between MaterializationUnits and...
Definition: Core.h:490
std::vector< const jitlink::Symbol * > JITLinkSymbolVector
void setReturnObjectBuffer(ReturnObjectBufferFunction ReturnObjectBuffer)
Set an object buffer return function.
uint64_t JITTargetAddress
Represents an address in the target process&#39;s address space.
Definition: JITSymbol.h:42
virtual void notifyLoaded(MaterializationResponsibility &MR)
static ManagedStatic< std::vector< std::string > > Plugins
#define P(N)
virtual LocalDependenciesMap getSyntheticSymbolLocalDependencies(MaterializationResponsibility &MR)
Return any dependencies that synthetic symbols (e.g.
Triple - Helper class for working with autoconf configuration names.
Definition: Triple.h:45
static ErrorSuccess success()
Create a success value.
Definition: Error.h:332
An ExecutionSession represents a running JIT program.
Definition: Core.h:1216
ObjectLinkingLayer & addPlugin(std::unique_ptr< Plugin > P)
Add a pass-config modifier.
virtual void modifyPassConfig(MaterializationResponsibility &MR, const Triple &TT, jitlink::PassConfiguration &Config)
uint32_t Size
Definition: Profile.cpp:46
ObjectLinkingLayer & setAutoClaimResponsibilityForObjectSymbols(bool AutoClaimObjectSymbols)
If set, this ObjectLinkingLayer instance will claim responsibility for any symbols provided by a give...
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
Interface for Layers that accept object files.
Definition: Layer.h:132
OutputIt move(R &&Range, OutputIt Out)
Provide wrappers to std::move which take ranges instead of having to pass begin/end explicitly...
Definition: STLExtras.h:1556