1 //===- JITSymbol.h - JIT symbol abstraction ---------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 // Abstraction for target process addresses.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_EXECUTIONENGINE_JITSYMBOL_H
14 #define LLVM_EXECUTIONENGINE_JITSYMBOL_H
25 #include "llvm/ADT/BitmaskEnum.h"
26 #include "llvm/ADT/FunctionExtras.h"
27 #include "llvm/ADT/StringRef.h"
28 #include "llvm/Support/Error.h"
33 class GlobalValueSummary;
39 } // end namespace object
41 /// Represents an address in the target process's address space.
42 using JITTargetAddress = uint64_t;
44 /// Convert a JITTargetAddress to a pointer.
46 /// Note: This is a raw cast of the address bit pattern to the given pointer
47 /// type. When casting to a function pointer in order to execute JIT'd code
48 /// jitTargetAddressToFunction should be preferred, as it will also perform
49 /// pointer signing on targets that require it.
50 template <typename T> T jitTargetAddressToPointer(JITTargetAddress Addr) {
51 static_assert(std::is_pointer<T>::value, "T must be a pointer type");
52 uintptr_t IntPtr = static_cast<uintptr_t>(Addr);
53 assert(IntPtr == Addr && "JITTargetAddress value out of range for uintptr_t");
54 return reinterpret_cast<T>(IntPtr);
57 /// Convert a JITTargetAddress to a callable function pointer.
59 /// Casts the given address to a callable function pointer. This operation
60 /// will perform pointer signing for platforms that require it (e.g. arm64e).
61 template <typename T> T jitTargetAddressToFunction(JITTargetAddress Addr) {
62 static_assert(std::is_pointer<T>::value &&
63 std::is_function<std::remove_pointer_t<T>>::value,
64 "T must be a function pointer type");
65 return jitTargetAddressToPointer<T>(Addr);
68 /// Convert a pointer to a JITTargetAddress.
69 template <typename T> JITTargetAddress pointerToJITTargetAddress(T *Ptr) {
70 return static_cast<JITTargetAddress>(reinterpret_cast<uintptr_t>(Ptr));
73 /// Flags for symbols in the JIT.
74 class JITSymbolFlags {
76 using UnderlyingType = uint8_t;
77 using TargetFlagsType = uint8_t;
79 enum FlagNames : UnderlyingType {
87 MaterializationSideEffectsOnly = 1U << 6,
88 LLVM_MARK_AS_BITMASK_ENUM( // LargestValue =
89 MaterializationSideEffectsOnly)
92 /// Default-construct a JITSymbolFlags instance.
93 JITSymbolFlags() = default;
95 /// Construct a JITSymbolFlags instance from the given flags.
96 JITSymbolFlags(FlagNames Flags) : Flags(Flags) {}
98 /// Construct a JITSymbolFlags instance from the given flags and target
100 JITSymbolFlags(FlagNames Flags, TargetFlagsType TargetFlags)
101 : TargetFlags(TargetFlags), Flags(Flags) {}
103 /// Implicitly convert to bool. Returs true if any flag is set.
104 explicit operator bool() const { return Flags != None || TargetFlags != 0; }
106 /// Compare for equality.
107 bool operator==(const JITSymbolFlags &RHS) const {
108 return Flags == RHS.Flags && TargetFlags == RHS.TargetFlags;
111 /// Bitwise AND-assignment for FlagNames.
112 JITSymbolFlags &operator&=(const FlagNames &RHS) {
117 /// Bitwise OR-assignment for FlagNames.
118 JITSymbolFlags &operator|=(const FlagNames &RHS) {
123 /// Return true if there was an error retrieving this symbol.
124 bool hasError() const {
125 return (Flags & HasError) == HasError;
128 /// Returns true if the Weak flag is set.
129 bool isWeak() const {
130 return (Flags & Weak) == Weak;
133 /// Returns true if the Common flag is set.
134 bool isCommon() const {
135 return (Flags & Common) == Common;
138 /// Returns true if the symbol isn't weak or common.
139 bool isStrong() const {
140 return !isWeak() && !isCommon();
143 /// Returns true if the Exported flag is set.
144 bool isExported() const {
145 return (Flags & Exported) == Exported;
148 /// Returns true if the given symbol is known to be callable.
149 bool isCallable() const { return (Flags & Callable) == Callable; }
151 /// Returns true if this symbol is a materialization-side-effects-only
152 /// symbol. Such symbols do not have a real address. They exist to trigger
153 /// and support synchronization of materialization side effects, e.g. for
154 /// collecting initialization information. These symbols will vanish from
155 /// the symbol table immediately upon reaching the ready state, and will
156 /// appear to queries as if they were never defined (except that query
157 /// callback execution will be delayed until they reach the ready state).
158 /// MaterializationSideEffectOnly symbols should only be queried using the
159 /// SymbolLookupFlags::WeaklyReferencedSymbol flag (see
160 /// llvm/include/llvm/ExecutionEngine/Orc/Core.h).
161 bool hasMaterializationSideEffectsOnly() const {
162 return (Flags & MaterializationSideEffectsOnly) ==
163 MaterializationSideEffectsOnly;
166 /// Get the underlying flags value as an integer.
167 UnderlyingType getRawFlagsValue() const {
168 return static_cast<UnderlyingType>(Flags);
171 /// Return a reference to the target-specific flags.
172 TargetFlagsType& getTargetFlags() { return TargetFlags; }
174 /// Return a reference to the target-specific flags.
175 const TargetFlagsType& getTargetFlags() const { return TargetFlags; }
177 /// Construct a JITSymbolFlags value based on the flags of the given global
179 static JITSymbolFlags fromGlobalValue(const GlobalValue &GV);
181 /// Construct a JITSymbolFlags value based on the flags of the given global
183 static JITSymbolFlags fromSummary(GlobalValueSummary *S);
185 /// Construct a JITSymbolFlags value based on the flags of the given libobject
187 static Expected<JITSymbolFlags>
188 fromObjectSymbol(const object::SymbolRef &Symbol);
191 TargetFlagsType TargetFlags = 0;
192 FlagNames Flags = None;
195 inline JITSymbolFlags operator&(const JITSymbolFlags &LHS,
196 const JITSymbolFlags::FlagNames &RHS) {
197 JITSymbolFlags Tmp = LHS;
202 inline JITSymbolFlags operator|(const JITSymbolFlags &LHS,
203 const JITSymbolFlags::FlagNames &RHS) {
204 JITSymbolFlags Tmp = LHS;
209 /// ARM-specific JIT symbol flags.
210 /// FIXME: This should be moved into a target-specific header.
211 class ARMJITSymbolFlags {
213 ARMJITSymbolFlags() = default;
220 operator JITSymbolFlags::TargetFlagsType&() { return Flags; }
222 static ARMJITSymbolFlags fromObjectSymbol(const object::SymbolRef &Symbol);
225 JITSymbolFlags::TargetFlagsType Flags = 0;
228 /// Represents a symbol that has been evaluated to an address already.
229 class JITEvaluatedSymbol {
231 JITEvaluatedSymbol() = default;
233 /// Create a 'null' symbol.
234 JITEvaluatedSymbol(std::nullptr_t) {}
236 /// Create a symbol for the given address and flags.
237 JITEvaluatedSymbol(JITTargetAddress Address, JITSymbolFlags Flags)
238 : Address(Address), Flags(Flags) {}
240 /// Create a symbol from the given pointer with the given flags.
241 template <typename T>
242 static JITEvaluatedSymbol
243 fromPointer(T *P, JITSymbolFlags Flags = JITSymbolFlags::Exported) {
244 return JITEvaluatedSymbol(pointerToJITTargetAddress(P), Flags);
247 /// An evaluated symbol converts to 'true' if its address is non-zero.
248 explicit operator bool() const { return Address != 0; }
250 /// Return the address of this symbol.
251 JITTargetAddress getAddress() const { return Address; }
253 /// Return the flags for this symbol.
254 JITSymbolFlags getFlags() const { return Flags; }
256 /// Set the flags for this symbol.
257 void setFlags(JITSymbolFlags Flags) { this->Flags = std::move(Flags); }
260 JITTargetAddress Address = 0;
261 JITSymbolFlags Flags;
264 /// Represents a symbol in the JIT.
267 using GetAddressFtor = unique_function<Expected<JITTargetAddress>()>;
269 /// Create a 'null' symbol, used to represent a "symbol not found"
270 /// result from a successful (non-erroneous) lookup.
271 JITSymbol(std::nullptr_t)
274 /// Create a JITSymbol representing an error in the symbol lookup
275 /// process (e.g. a network failure during a remote lookup).
277 : Err(std::move(Err)), Flags(JITSymbolFlags::HasError) {}
279 /// Create a symbol for a definition with a known address.
280 JITSymbol(JITTargetAddress Addr, JITSymbolFlags Flags)
281 : CachedAddr(Addr), Flags(Flags) {}
283 /// Construct a JITSymbol from a JITEvaluatedSymbol.
284 JITSymbol(JITEvaluatedSymbol Sym)
285 : CachedAddr(Sym.getAddress()), Flags(Sym.getFlags()) {}
287 /// Create a symbol for a definition that doesn't have a known address
289 /// @param GetAddress A functor to materialize a definition (fixing the
290 /// address) on demand.
292 /// This constructor allows a JIT layer to provide a reference to a symbol
293 /// definition without actually materializing the definition up front. The
294 /// user can materialize the definition at any time by calling the getAddress
296 JITSymbol(GetAddressFtor GetAddress, JITSymbolFlags Flags)
297 : GetAddress(std::move(GetAddress)), CachedAddr(0), Flags(Flags) {}
299 JITSymbol(const JITSymbol&) = delete;
300 JITSymbol& operator=(const JITSymbol&) = delete;
302 JITSymbol(JITSymbol &&Other)
303 : GetAddress(std::move(Other.GetAddress)), Flags(std::move(Other.Flags)) {
304 if (Flags.hasError())
305 Err = std::move(Other.Err);
307 CachedAddr = std::move(Other.CachedAddr);
310 JITSymbol& operator=(JITSymbol &&Other) {
311 GetAddress = std::move(Other.GetAddress);
312 Flags = std::move(Other.Flags);
313 if (Flags.hasError())
314 Err = std::move(Other.Err);
316 CachedAddr = std::move(Other.CachedAddr);
321 if (Flags.hasError())
324 CachedAddr.~JITTargetAddress();
327 /// Returns true if the symbol exists, false otherwise.
328 explicit operator bool() const {
329 return !Flags.hasError() && (CachedAddr || GetAddress);
332 /// Move the error field value out of this JITSymbol.
334 if (Flags.hasError())
335 return std::move(Err);
336 return Error::success();
339 /// Get the address of the symbol in the target address space. Returns
340 /// '0' if the symbol does not exist.
341 Expected<JITTargetAddress> getAddress() {
342 assert(!Flags.hasError() && "getAddress called on error value");
344 if (auto CachedAddrOrErr = GetAddress()) {
345 GetAddress = nullptr;
346 CachedAddr = *CachedAddrOrErr;
347 assert(CachedAddr && "Symbol could not be materialized.");
349 return CachedAddrOrErr.takeError();
354 JITSymbolFlags getFlags() const { return Flags; }
357 GetAddressFtor GetAddress;
359 JITTargetAddress CachedAddr;
362 JITSymbolFlags Flags;
365 /// Symbol resolution interface.
367 /// Allows symbol flags and addresses to be looked up by name.
368 /// Symbol queries are done in bulk (i.e. you request resolution of a set of
369 /// symbols, rather than a single one) to reduce IPC overhead in the case of
370 /// remote JITing, and expose opportunities for parallel compilation.
371 class JITSymbolResolver {
373 using LookupSet = std::set<StringRef>;
374 using LookupResult = std::map<StringRef, JITEvaluatedSymbol>;
375 using OnResolvedFunction = unique_function<void(Expected<LookupResult>)>;
377 virtual ~JITSymbolResolver() = default;
379 /// Returns the fully resolved address and flags for each of the given
382 /// This method will return an error if any of the given symbols can not be
383 /// resolved, or if the resolution process itself triggers an error.
384 virtual void lookup(const LookupSet &Symbols,
385 OnResolvedFunction OnResolved) = 0;
387 /// Returns the subset of the given symbols that should be materialized by
388 /// the caller. Only weak/common symbols should be looked up, as strong
389 /// definitions are implicitly always part of the caller's responsibility.
390 virtual Expected<LookupSet>
391 getResponsibilitySet(const LookupSet &Symbols) = 0;
394 virtual void anchor();
397 /// Legacy symbol resolution interface.
398 class LegacyJITSymbolResolver : public JITSymbolResolver {
400 /// Performs lookup by, for each symbol, first calling
401 /// findSymbolInLogicalDylib and if that fails calling
403 void lookup(const LookupSet &Symbols, OnResolvedFunction OnResolved) final;
405 /// Performs flags lookup by calling findSymbolInLogicalDylib and
406 /// returning the flags value for that symbol.
407 Expected<LookupSet> getResponsibilitySet(const LookupSet &Symbols) final;
409 /// This method returns the address of the specified symbol if it exists
410 /// within the logical dynamic library represented by this JITSymbolResolver.
411 /// Unlike findSymbol, queries through this interface should return addresses
412 /// for hidden symbols.
414 /// This is of particular importance for the Orc JIT APIs, which support lazy
415 /// compilation by breaking up modules: Each of those broken out modules
416 /// must be able to resolve hidden symbols provided by the others. Clients
417 /// writing memory managers for MCJIT can usually ignore this method.
419 /// This method will be queried by RuntimeDyld when checking for previous
420 /// definitions of common symbols.
421 virtual JITSymbol findSymbolInLogicalDylib(const std::string &Name) = 0;
423 /// This method returns the address of the specified function or variable.
424 /// It is used to resolve symbols during module linking.
426 /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will
427 /// skip all relocations for that symbol, and the client will be responsible
428 /// for handling them manually.
429 virtual JITSymbol findSymbol(const std::string &Name) = 0;
432 virtual void anchor();
435 } // end namespace llvm
437 #endif // LLVM_EXECUTIONENGINE_JITSYMBOL_H