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