1//===- JITSymbol.h - JIT symbol abstraction ---------------------*- C++ -*-===//
2//
3// The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// Abstraction for target process addresses.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_EXECUTIONENGINE_JITSYMBOL_H
15#define LLVM_EXECUTIONENGINE_JITSYMBOL_H
16
17#include <algorithm>
18#include <cassert>
19#include <cstddef>
20#include <cstdint>
21#include <functional>
22#include <map>
23#include <set>
24#include <string>
25
26#include "llvm/ADT/BitmaskEnum.h"
27#include "llvm/ADT/StringRef.h"
28#include "llvm/Support/Error.h"
29
30namespace llvm {
31
32class GlobalValue;
33
34namespace object {
35
36class SymbolRef;
37
38} // end namespace object
39
40/// Represents an address in the target process's address space.
41using JITTargetAddress = uint64_t;
42
43/// Convert a JITTargetAddress to a pointer.
44template <typename T> T jitTargetAddressToPointer(JITTargetAddress Addr) {
45 static_assert(std::is_pointer<T>::value, "T must be a pointer type");
46 uintptr_t IntPtr = static_cast<uintptr_t>(Addr);
47 assert(IntPtr == Addr && "JITTargetAddress value out of range for uintptr_t");
48 return reinterpret_cast<T>(IntPtr);
49}
50
51template <typename T> JITTargetAddress pointerToJITTargetAddress(T *Ptr) {
52 return static_cast<JITTargetAddress>(reinterpret_cast<uintptr_t>(Ptr));
53}
54
55/// Flags for symbols in the JIT.
56class JITSymbolFlags {
57public:
58 using UnderlyingType = uint8_t;
59 using TargetFlagsType = uint64_t;
60
61 enum FlagNames : UnderlyingType {
62 None = 0,
63 HasError = 1U << 0,
64 Weak = 1U << 1,
65 Common = 1U << 2,
66 Absolute = 1U << 3,
67 Exported = 1U << 4,
68 Callable = 1U << 5,
69 Lazy = 1U << 6,
70 Materializing = 1U << 7,
71 LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ Materializing)
72 };
73
74 static JITSymbolFlags stripTransientFlags(JITSymbolFlags Orig) {
75 return static_cast<FlagNames>(Orig.Flags & ~Lazy & ~Materializing);
76 }
77
78 /// Default-construct a JITSymbolFlags instance.
79 JITSymbolFlags() = default;
80
81 /// Construct a JITSymbolFlags instance from the given flags.
82 JITSymbolFlags(FlagNames Flags) : Flags(Flags) {}
83
84 /// Construct a JITSymbolFlags instance from the given flags and target
85 /// flags.
86 JITSymbolFlags(FlagNames Flags, TargetFlagsType TargetFlags)
87 : Flags(Flags), TargetFlags(TargetFlags) {}
88
89 /// Implicitly convert to bool. Returs true if any flag is set.
90 explicit operator bool() const { return Flags != None || TargetFlags != 0; }
91
92 /// Compare for equality.
93 bool operator==(const JITSymbolFlags &RHS) const {
94 return Flags == RHS.Flags && TargetFlags == RHS.TargetFlags;
95 }
96
97 /// Bitwise AND-assignment for FlagNames.
98 JITSymbolFlags &operator&=(const FlagNames &RHS) {
99 Flags &= RHS;
100 return *this;
101 }
102
103 /// Bitwise OR-assignment for FlagNames.
104 JITSymbolFlags &operator|=(const FlagNames &RHS) {
105 Flags |= RHS;
106 return *this;
107 }
108
109 /// Return true if there was an error retrieving this symbol.
110 bool hasError() const {
111 return (Flags & HasError) == HasError;
112 }
113
114 /// Returns true if this is a lazy symbol.
115 /// This flag is used internally by the JIT APIs to track
116 /// materialization states.
117 bool isLazy() const { return Flags & Lazy; }
118
119 /// Returns true if this symbol is in the process of being
120 /// materialized.
121 bool isMaterializing() const { return Flags & Materializing; }
122
123 /// Returns true if this symbol is fully materialized.
124 /// (i.e. neither lazy, nor materializing).
125 bool isMaterialized() const { return !(Flags & (Lazy | Materializing)); }
126
127 /// Returns true if the Weak flag is set.
128 bool isWeak() const {
129 return (Flags & Weak) == Weak;
130 }
131
132 /// Returns true if the Common flag is set.
133 bool isCommon() const {
134 return (Flags & Common) == Common;
135 }
136
137 /// Returns true if the symbol isn't weak or common.
138 bool isStrong() const {
139 return !isWeak() && !isCommon();
140 }
141
142 /// Returns true if the Exported flag is set.
143 bool isExported() const {
144 return (Flags & Exported) == Exported;
145 }
146
147 /// Returns true if the given symbol is known to be callable.
148 bool isCallable() const { return (Flags & Callable) == Callable; }
149
150 /// Get the underlying flags value as an integer.
151 UnderlyingType getRawFlagsValue() const {
152 return static_cast<UnderlyingType>(Flags);
153 }
154
155 /// Return a reference to the target-specific flags.
156 TargetFlagsType& getTargetFlags() { return TargetFlags; }
157
158 /// Return a reference to the target-specific flags.
159 const TargetFlagsType& getTargetFlags() const { return TargetFlags; }
160
161 /// Construct a JITSymbolFlags value based on the flags of the given global
162 /// value.
163 static JITSymbolFlags fromGlobalValue(const GlobalValue &GV);
164
165 /// Construct a JITSymbolFlags value based on the flags of the given libobject
166 /// symbol.
167 static Expected<JITSymbolFlags>
168 fromObjectSymbol(const object::SymbolRef &Symbol);
169
170private:
171 FlagNames Flags = None;
172 TargetFlagsType TargetFlags = 0;
173};
174
175inline JITSymbolFlags operator&(const JITSymbolFlags &LHS,
176 const JITSymbolFlags::FlagNames &RHS) {
177 JITSymbolFlags Tmp = LHS;
178 Tmp &= RHS;
179 return Tmp;
180}
181
182inline JITSymbolFlags operator|(const JITSymbolFlags &LHS,
183 const JITSymbolFlags::FlagNames &RHS) {
184 JITSymbolFlags Tmp = LHS;
185 Tmp |= RHS;
186 return Tmp;
187}
188
189/// ARM-specific JIT symbol flags.
190/// FIXME: This should be moved into a target-specific header.
191class ARMJITSymbolFlags {
192public:
193 ARMJITSymbolFlags() = default;
194
195 enum FlagNames {
196 None = 0,
197 Thumb = 1 << 0
198 };
199
200 operator JITSymbolFlags::TargetFlagsType&() { return Flags; }
201
202 static ARMJITSymbolFlags fromObjectSymbol(const object::SymbolRef &Symbol);
203
204private:
205 JITSymbolFlags::TargetFlagsType Flags = 0;
206};
207
208/// Represents a symbol that has been evaluated to an address already.
209class JITEvaluatedSymbol {
210public:
211 JITEvaluatedSymbol() = default;
212
213 /// Create a 'null' symbol.
214 JITEvaluatedSymbol(std::nullptr_t) {}
215
216 /// Create a symbol for the given address and flags.
217 JITEvaluatedSymbol(JITTargetAddress Address, JITSymbolFlags Flags)
218 : Address(Address), Flags(Flags) {}
219
220 /// An evaluated symbol converts to 'true' if its address is non-zero.
221 explicit operator bool() const { return Address != 0; }
222
223 /// Return the address of this symbol.
224 JITTargetAddress getAddress() const { return Address; }
225
226 /// Return the flags for this symbol.
227 JITSymbolFlags getFlags() const { return Flags; }
228
229 /// Set the flags for this symbol.
230 void setFlags(JITSymbolFlags Flags) { this->Flags = std::move(Flags); }
231
232private:
233 JITTargetAddress Address = 0;
234 JITSymbolFlags Flags;
235};
236
237/// Represents a symbol in the JIT.
238class JITSymbol {
239public:
240 using GetAddressFtor = std::function<Expected<JITTargetAddress>()>;
241
242 /// Create a 'null' symbol, used to represent a "symbol not found"
243 /// result from a successful (non-erroneous) lookup.
244 JITSymbol(std::nullptr_t)
245 : CachedAddr(0) {}
246
247 /// Create a JITSymbol representing an error in the symbol lookup
248 /// process (e.g. a network failure during a remote lookup).
249 JITSymbol(Error Err)
250 : Err(std::move(Err)), Flags(JITSymbolFlags::HasError) {}
251
252 /// Create a symbol for a definition with a known address.
253 JITSymbol(JITTargetAddress Addr, JITSymbolFlags Flags)
254 : CachedAddr(Addr), Flags(Flags) {}
255
256 /// Construct a JITSymbol from a JITEvaluatedSymbol.
257 JITSymbol(JITEvaluatedSymbol Sym)
258 : CachedAddr(Sym.getAddress()), Flags(Sym.getFlags()) {}
259
260 /// Create a symbol for a definition that doesn't have a known address
261 /// yet.
262 /// @param GetAddress A functor to materialize a definition (fixing the
263 /// address) on demand.
264 ///
265 /// This constructor allows a JIT layer to provide a reference to a symbol
266 /// definition without actually materializing the definition up front. The
267 /// user can materialize the definition at any time by calling the getAddress
268 /// method.
269 JITSymbol(GetAddressFtor GetAddress, JITSymbolFlags Flags)
270 : GetAddress(std::move(GetAddress)), CachedAddr(0), Flags(Flags) {}
271
272 JITSymbol(const JITSymbol&) = delete;
273 JITSymbol& operator=(const JITSymbol&) = delete;
274
275 JITSymbol(JITSymbol &&Other)
276 : GetAddress(std::move(Other.GetAddress)), Flags(std::move(Other.Flags)) {
277 if (Flags.hasError())
278 Err = std::move(Other.Err);
279 else
280 CachedAddr = std::move(Other.CachedAddr);
281 }
282
283 JITSymbol& operator=(JITSymbol &&Other) {
284 GetAddress = std::move(Other.GetAddress);
285 Flags = std::move(Other.Flags);
286 if (Flags.hasError())
287 Err = std::move(Other.Err);
288 else
289 CachedAddr = std::move(Other.CachedAddr);
290 return *this;
291 }
292
293 ~JITSymbol() {
294 if (Flags.hasError())
295 Err.~Error();
296 else
297 CachedAddr.~JITTargetAddress();
298 }
299
300 /// Returns true if the symbol exists, false otherwise.
301 explicit operator bool() const {
302 return !Flags.hasError() && (CachedAddr || GetAddress);
303 }
304
305 /// Move the error field value out of this JITSymbol.
306 Error takeError() {
307 if (Flags.hasError())
308 return std::move(Err);
309 return Error::success();
310 }
311
312 /// Get the address of the symbol in the target address space. Returns
313 /// '0' if the symbol does not exist.
314 Expected<JITTargetAddress> getAddress() {
315 assert(!Flags.hasError() && "getAddress called on error value");
316 if (GetAddress) {
317 if (auto CachedAddrOrErr = GetAddress()) {
318 GetAddress = nullptr;
319 CachedAddr = *CachedAddrOrErr;
320 assert(CachedAddr && "Symbol could not be materialized.");
321 } else
322 return CachedAddrOrErr.takeError();
323 }
324 return CachedAddr;
325 }
326
327 JITSymbolFlags getFlags() const { return Flags; }
328
329private:
330 GetAddressFtor GetAddress;
331 union {
332 JITTargetAddress CachedAddr;
333 Error Err;
334 };
335 JITSymbolFlags Flags;
336};
337
338/// Symbol resolution interface.
339///
340/// Allows symbol flags and addresses to be looked up by name.
341/// Symbol queries are done in bulk (i.e. you request resolution of a set of
342/// symbols, rather than a single one) to reduce IPC overhead in the case of
343/// remote JITing, and expose opportunities for parallel compilation.
344class JITSymbolResolver {
345public:
346 using LookupSet = std::set<StringRef>;
347 using LookupResult = std::map<StringRef, JITEvaluatedSymbol>;
348 using OnResolvedFunction = std::function<void(Expected<LookupResult>)>;
349
350 virtual ~JITSymbolResolver() = default;
351
352 /// Returns the fully resolved address and flags for each of the given
353 /// symbols.
354 ///
355 /// This method will return an error if any of the given symbols can not be
356 /// resolved, or if the resolution process itself triggers an error.
357 virtual void lookup(const LookupSet &Symbols,
358 OnResolvedFunction OnResolved) = 0;
359
360 /// Returns the subset of the given symbols that should be materialized by
361 /// the caller. Only weak/common symbols should be looked up, as strong
362 /// definitions are implicitly always part of the caller's responsibility.
363 virtual Expected<LookupSet>
364 getResponsibilitySet(const LookupSet &Symbols) = 0;
365
366private:
367 virtual void anchor();
368};
369
370/// Legacy symbol resolution interface.
371class LegacyJITSymbolResolver : public JITSymbolResolver {
372public:
373 /// Performs lookup by, for each symbol, first calling
374 /// findSymbolInLogicalDylib and if that fails calling
375 /// findSymbol.
376 void lookup(const LookupSet &Symbols, OnResolvedFunction OnResolved) final;
377
378 /// Performs flags lookup by calling findSymbolInLogicalDylib and
379 /// returning the flags value for that symbol.
380 Expected<LookupSet> getResponsibilitySet(const LookupSet &Symbols) final;
381
382 /// This method returns the address of the specified symbol if it exists
383 /// within the logical dynamic library represented by this JITSymbolResolver.
384 /// Unlike findSymbol, queries through this interface should return addresses
385 /// for hidden symbols.
386 ///
387 /// This is of particular importance for the Orc JIT APIs, which support lazy
388 /// compilation by breaking up modules: Each of those broken out modules
389 /// must be able to resolve hidden symbols provided by the others. Clients
390 /// writing memory managers for MCJIT can usually ignore this method.
391 ///
392 /// This method will be queried by RuntimeDyld when checking for previous
393 /// definitions of common symbols.
394 virtual JITSymbol findSymbolInLogicalDylib(const std::string &Name) = 0;
395
396 /// This method returns the address of the specified function or variable.
397 /// It is used to resolve symbols during module linking.
398 ///
399 /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will
400 /// skip all relocations for that symbol, and the client will be responsible
401 /// for handling them manually.
402 virtual JITSymbol findSymbol(const std::string &Name) = 0;
403
404private:
405 virtual void anchor();
406};
407
408} // end namespace llvm
409
410#endif // LLVM_EXECUTIONENGINE_JITSYMBOL_H
411