include/llvm/ExecutionEngine/JITSymbol.h

   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
  29 namespace llvm {
  30
  31 class GlobalValue;
  32
  33 namespace object {
  34
  35 class SymbolRef;
  36
  37 } // end namespace object
  38
  39 /// Represents an address in the target process's address space.
  40 using JITTargetAddress = uint64_t;
  41
  42 /// Convert a JITTargetAddress to a pointer.
  43 template <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
  50 template <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.
  55 class JITSymbolFlags {
  56 public:
  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
 150 private:
 151   TargetFlagsType TargetFlags = 0;
 152   FlagNames Flags = None;
 153 };
 154
 155 inline JITSymbolFlags operator&(const JITSymbolFlags &LHS,
 156                                 const JITSymbolFlags::FlagNames &RHS) {
 157   JITSymbolFlags Tmp = LHS;
 158   Tmp &= RHS;
 159   return Tmp;
 160 }
 161
 162 inline 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.
 171 class ARMJITSymbolFlags {
 172 public:
 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
 184 private:
 185   JITSymbolFlags::TargetFlagsType Flags = 0;
 186 };
 187
 188 /// Represents a symbol that has been evaluated to an address already.
 189 class JITEvaluatedSymbol {
 190 public:
 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
 212 private:
 213   JITTargetAddress Address = 0;
 214   JITSymbolFlags Flags;
 215 };
 216
 217 /// Represents a symbol in the JIT.
 218 class JITSymbol {
 219 public:
 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
 309 private:
 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.
 324 class JITSymbolResolver {
 325 public:
 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
 346 private:
 347   virtual void anchor();
 348 };
 349
 350 /// Legacy symbol resolution interface.
 351 class LegacyJITSymbolResolver : public JITSymbolResolver {
 352 public:
 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
 384 private:
 385   virtual void anchor();
 386 };
 387
 388 } // end namespace llvm
 389
 390 #endif // LLVM_EXECUTIONENGINE_JITSYMBOL_H