Home | History | Annotate | Download | only in IR 
      1 //===-- llvm/GlobalValue.h - Class to represent a global value --*- 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 // This file is a common base class of all globally definable objects.  As such,
     11 // it is subclassed by GlobalVariable, GlobalAlias and by Function.  This is
     12 // used because you can do certain things with these global objects that you
     13 // can't do to anything else.  For example, use the address of one as a
     14 // constant.
     15 //
     16 //===----------------------------------------------------------------------===//
     17 
     18 #ifndef LLVM_IR_GLOBALVALUE_H
     19 #define LLVM_IR_GLOBALVALUE_H
     20 
     21 #include "llvm/ADT/StringRef.h"
     22 #include "llvm/ADT/Twine.h"
     23 #include "llvm/IR/Constant.h"
     24 #include "llvm/IR/DerivedTypes.h"
     25 #include "llvm/IR/Value.h"
     26 #include "llvm/Support/Casting.h"
     27 #include "llvm/Support/ErrorHandling.h"
     28 #include "llvm/Support/MD5.h"
     29 #include <cassert>
     30 #include <cstdint>
     31 #include <string>
     32 
     33 namespace llvm {
     34 
     35 class Comdat;
     36 class ConstantRange;
     37 class Error;
     38 class GlobalObject;
     39 class Module;
     40 
     41 namespace Intrinsic {
     42   enum ID : unsigned;
     43 } // end namespace Intrinsic
     44 
     45 class GlobalValue : public Constant {
     46 public:
     47   /// @brief An enumeration for the kinds of linkage for global values.
     48   enum LinkageTypes {
     49     ExternalLinkage = 0,///< Externally visible function
     50     AvailableExternallyLinkage, ///< Available for inspection, not emission.
     51     LinkOnceAnyLinkage, ///< Keep one copy of function when linking (inline)
     52     LinkOnceODRLinkage, ///< Same, but only replaced by something equivalent.
     53     WeakAnyLinkage,     ///< Keep one copy of named function when linking (weak)
     54     WeakODRLinkage,     ///< Same, but only replaced by something equivalent.
     55     AppendingLinkage,   ///< Special purpose, only applies to global arrays
     56     InternalLinkage,    ///< Rename collisions when linking (static functions).
     57     PrivateLinkage,     ///< Like Internal, but omit from symbol table.
     58     ExternalWeakLinkage,///< ExternalWeak linkage description.
     59     CommonLinkage       ///< Tentative definitions.
     60   };
     61 
     62   /// @brief An enumeration for the kinds of visibility of global values.
     63   enum VisibilityTypes {
     64     DefaultVisibility = 0,  ///< The GV is visible
     65     HiddenVisibility,       ///< The GV is hidden
     66     ProtectedVisibility     ///< The GV is protected
     67   };
     68 
     69   /// @brief Storage classes of global values for PE targets.
     70   enum DLLStorageClassTypes {
     71     DefaultStorageClass   = 0,
     72     DLLImportStorageClass = 1, ///< Function to be imported from DLL
     73     DLLExportStorageClass = 2  ///< Function to be accessible from DLL.
     74   };
     75 
     76 protected:
     77   GlobalValue(Type *Ty, ValueTy VTy, Use *Ops, unsigned NumOps,
     78               LinkageTypes Linkage, const Twine &Name, unsigned AddressSpace)
     79       : Constant(PointerType::get(Ty, AddressSpace), VTy, Ops, NumOps),
     80         ValueType(Ty), Linkage(Linkage), Visibility(DefaultVisibility),
     81         UnnamedAddrVal(unsigned(UnnamedAddr::None)),
     82         DllStorageClass(DefaultStorageClass), ThreadLocal(NotThreadLocal),
     83         HasLLVMReservedName(false), IntID((Intrinsic::ID)0U), Parent(nullptr) {
     84     setName(Name);
     85   }
     86 
     87   Type *ValueType;
     88 
     89   static const unsigned GlobalValueSubClassDataBits = 18;
     90 
     91   // All bitfields use unsigned as the underlying type so that MSVC will pack
     92   // them.
     93   unsigned Linkage : 4;       // The linkage of this global
     94   unsigned Visibility : 2;    // The visibility style of this global
     95   unsigned UnnamedAddrVal : 2; // This value's address is not significant
     96   unsigned DllStorageClass : 2; // DLL storage class
     97 
     98   unsigned ThreadLocal : 3; // Is this symbol "Thread Local", if so, what is
     99                             // the desired model?
    100 
    101   /// True if the function's name starts with "llvm.".  This corresponds to the
    102   /// value of Function::isIntrinsic(), which may be true even if
    103   /// Function::intrinsicID() returns Intrinsic::not_intrinsic.
    104   unsigned HasLLVMReservedName : 1;
    105 
    106 private:
    107   friend class Constant;
    108 
    109   // Give subclasses access to what otherwise would be wasted padding.
    110   // (18 + 4 + 2 + 2 + 2 + 3 + 1) == 32.
    111   unsigned SubClassData : GlobalValueSubClassDataBits;
    112 
    113   void destroyConstantImpl();
    114   Value *handleOperandChangeImpl(Value *From, Value *To);
    115 
    116   /// Returns true if the definition of this global may be replaced by a
    117   /// differently optimized variant of the same source level function at link
    118   /// time.
    119   bool mayBeDerefined() const {
    120     switch (getLinkage()) {
    121     case WeakODRLinkage:
    122     case LinkOnceODRLinkage:
    123     case AvailableExternallyLinkage:
    124       return true;
    125 
    126     case WeakAnyLinkage:
    127     case LinkOnceAnyLinkage:
    128     case CommonLinkage:
    129     case ExternalWeakLinkage:
    130     case ExternalLinkage:
    131     case AppendingLinkage:
    132     case InternalLinkage:
    133     case PrivateLinkage:
    134       return isInterposable();
    135     }
    136 
    137     llvm_unreachable("Fully covered switch above!");
    138   }
    139 
    140 protected:
    141   /// \brief The intrinsic ID for this subclass (which must be a Function).
    142   ///
    143   /// This member is defined by this class, but not used for anything.
    144   /// Subclasses can use it to store their intrinsic ID, if they have one.
    145   ///
    146   /// This is stored here to save space in Function on 64-bit hosts.
    147   Intrinsic::ID IntID;
    148 
    149   unsigned getGlobalValueSubClassData() const {
    150     return SubClassData;
    151   }
    152   void setGlobalValueSubClassData(unsigned V) {
    153     assert(V < (1 << GlobalValueSubClassDataBits) && "It will not fit");
    154     SubClassData = V;
    155   }
    156 
    157   Module *Parent;             // The containing module.
    158 
    159   // Used by SymbolTableListTraits.
    160   void setParent(Module *parent) {
    161     Parent = parent;
    162   }
    163 
    164   ~GlobalValue() {
    165     removeDeadConstantUsers();   // remove any dead constants using this.
    166   }
    167 
    168 public:
    169   enum ThreadLocalMode {
    170     NotThreadLocal = 0,
    171     GeneralDynamicTLSModel,
    172     LocalDynamicTLSModel,
    173     InitialExecTLSModel,
    174     LocalExecTLSModel
    175   };
    176 
    177   GlobalValue(const GlobalValue &) = delete;
    178 
    179   unsigned getAlignment() const;
    180 
    181   enum class UnnamedAddr {
    182     None,
    183     Local,
    184     Global,
    185   };
    186 
    187   bool hasGlobalUnnamedAddr() const {
    188     return getUnnamedAddr() == UnnamedAddr::Global;
    189   }
    190 
    191   /// Returns true if this value's address is not significant in this module.
    192   /// This attribute is intended to be used only by the code generator and LTO
    193   /// to allow the linker to decide whether the global needs to be in the symbol
    194   /// table. It should probably not be used in optimizations, as the value may
    195   /// have uses outside the module; use hasGlobalUnnamedAddr() instead.
    196   bool hasAtLeastLocalUnnamedAddr() const {
    197     return getUnnamedAddr() != UnnamedAddr::None;
    198   }
    199 
    200   UnnamedAddr getUnnamedAddr() const {
    201     return UnnamedAddr(UnnamedAddrVal);
    202   }
    203   void setUnnamedAddr(UnnamedAddr Val) { UnnamedAddrVal = unsigned(Val); }
    204 
    205   static UnnamedAddr getMinUnnamedAddr(UnnamedAddr A, UnnamedAddr B) {
    206     if (A == UnnamedAddr::None || B == UnnamedAddr::None)
    207       return UnnamedAddr::None;
    208     if (A == UnnamedAddr::Local || B == UnnamedAddr::Local)
    209       return UnnamedAddr::Local;
    210     return UnnamedAddr::Global;
    211   }
    212 
    213   bool hasComdat() const { return getComdat() != nullptr; }
    214   const Comdat *getComdat() const;
    215   Comdat *getComdat() {
    216     return const_cast<Comdat *>(
    217                            static_cast<const GlobalValue *>(this)->getComdat());
    218   }
    219 
    220   VisibilityTypes getVisibility() const { return VisibilityTypes(Visibility); }
    221   bool hasDefaultVisibility() const { return Visibility == DefaultVisibility; }
    222   bool hasHiddenVisibility() const { return Visibility == HiddenVisibility; }
    223   bool hasProtectedVisibility() const {
    224     return Visibility == ProtectedVisibility;
    225   }
    226   void setVisibility(VisibilityTypes V) {
    227     assert((!hasLocalLinkage() || V == DefaultVisibility) &&
    228            "local linkage requires default visibility");
    229     Visibility = V;
    230   }
    231 
    232   /// If the value is "Thread Local", its value isn't shared by the threads.
    233   bool isThreadLocal() const { return getThreadLocalMode() != NotThreadLocal; }
    234   void setThreadLocal(bool Val) {
    235     setThreadLocalMode(Val ? GeneralDynamicTLSModel : NotThreadLocal);
    236   }
    237   void setThreadLocalMode(ThreadLocalMode Val) {
    238     assert(Val == NotThreadLocal || getValueID() != Value::FunctionVal);
    239     ThreadLocal = Val;
    240   }
    241   ThreadLocalMode getThreadLocalMode() const {
    242     return static_cast<ThreadLocalMode>(ThreadLocal);
    243   }
    244 
    245   DLLStorageClassTypes getDLLStorageClass() const {
    246     return DLLStorageClassTypes(DllStorageClass);
    247   }
    248   bool hasDLLImportStorageClass() const {
    249     return DllStorageClass == DLLImportStorageClass;
    250   }
    251   bool hasDLLExportStorageClass() const {
    252     return DllStorageClass == DLLExportStorageClass;
    253   }
    254   void setDLLStorageClass(DLLStorageClassTypes C) { DllStorageClass = C; }
    255 
    256   bool hasSection() const { return !getSection().empty(); }
    257   StringRef getSection() const;
    258 
    259   /// Global values are always pointers.
    260   PointerType *getType() const { return cast<PointerType>(User::getType()); }
    261 
    262   Type *getValueType() const { return ValueType; }
    263 
    264   static LinkageTypes getLinkOnceLinkage(bool ODR) {
    265     return ODR ? LinkOnceODRLinkage : LinkOnceAnyLinkage;
    266   }
    267   static LinkageTypes getWeakLinkage(bool ODR) {
    268     return ODR ? WeakODRLinkage : WeakAnyLinkage;
    269   }
    270 
    271   static bool isExternalLinkage(LinkageTypes Linkage) {
    272     return Linkage == ExternalLinkage;
    273   }
    274   static bool isAvailableExternallyLinkage(LinkageTypes Linkage) {
    275     return Linkage == AvailableExternallyLinkage;
    276   }
    277   static bool isLinkOnceODRLinkage(LinkageTypes Linkage) {
    278     return Linkage == LinkOnceODRLinkage;
    279   }
    280   static bool isLinkOnceLinkage(LinkageTypes Linkage) {
    281     return Linkage == LinkOnceAnyLinkage || Linkage == LinkOnceODRLinkage;
    282   }
    283   static bool isWeakAnyLinkage(LinkageTypes Linkage) {
    284     return Linkage == WeakAnyLinkage;
    285   }
    286   static bool isWeakODRLinkage(LinkageTypes Linkage) {
    287     return Linkage == WeakODRLinkage;
    288   }
    289   static bool isWeakLinkage(LinkageTypes Linkage) {
    290     return isWeakAnyLinkage(Linkage) || isWeakODRLinkage(Linkage);
    291   }
    292   static bool isAppendingLinkage(LinkageTypes Linkage) {
    293     return Linkage == AppendingLinkage;
    294   }
    295   static bool isInternalLinkage(LinkageTypes Linkage) {
    296     return Linkage == InternalLinkage;
    297   }
    298   static bool isPrivateLinkage(LinkageTypes Linkage) {
    299     return Linkage == PrivateLinkage;
    300   }
    301   static bool isLocalLinkage(LinkageTypes Linkage) {
    302     return isInternalLinkage(Linkage) || isPrivateLinkage(Linkage);
    303   }
    304   static bool isExternalWeakLinkage(LinkageTypes Linkage) {
    305     return Linkage == ExternalWeakLinkage;
    306   }
    307   static bool isCommonLinkage(LinkageTypes Linkage) {
    308     return Linkage == CommonLinkage;
    309   }
    310   static bool isValidDeclarationLinkage(LinkageTypes Linkage) {
    311     return isExternalWeakLinkage(Linkage) || isExternalLinkage(Linkage);
    312   }
    313 
    314   /// Whether the definition of this global may be replaced by something
    315   /// non-equivalent at link time. For example, if a function has weak linkage
    316   /// then the code defining it may be replaced by different code.
    317   static bool isInterposableLinkage(LinkageTypes Linkage) {
    318     switch (Linkage) {
    319     case WeakAnyLinkage:
    320     case LinkOnceAnyLinkage:
    321     case CommonLinkage:
    322     case ExternalWeakLinkage:
    323       return true;
    324 
    325     case AvailableExternallyLinkage:
    326     case LinkOnceODRLinkage:
    327     case WeakODRLinkage:
    328     // The above three cannot be overridden but can be de-refined.
    329 
    330     case ExternalLinkage:
    331     case AppendingLinkage:
    332     case InternalLinkage:
    333     case PrivateLinkage:
    334       return false;
    335     }
    336     llvm_unreachable("Fully covered switch above!");
    337   }
    338 
    339   /// Whether the definition of this global may be discarded if it is not used
    340   /// in its compilation unit.
    341   static bool isDiscardableIfUnused(LinkageTypes Linkage) {
    342     return isLinkOnceLinkage(Linkage) || isLocalLinkage(Linkage) ||
    343            isAvailableExternallyLinkage(Linkage);
    344   }
    345 
    346   /// Whether the definition of this global may be replaced at link time.  NB:
    347   /// Using this method outside of the code generators is almost always a
    348   /// mistake: when working at the IR level use isInterposable instead as it
    349   /// knows about ODR semantics.
    350   static bool isWeakForLinker(LinkageTypes Linkage)  {
    351     return Linkage == WeakAnyLinkage || Linkage == WeakODRLinkage ||
    352            Linkage == LinkOnceAnyLinkage || Linkage == LinkOnceODRLinkage ||
    353            Linkage == CommonLinkage || Linkage == ExternalWeakLinkage;
    354   }
    355 
    356   /// Return true if the currently visible definition of this global (if any) is
    357   /// exactly the definition we will see at runtime.
    358   ///
    359   /// Non-exact linkage types inhibits most non-inlining IPO, since a
    360   /// differently optimized variant of the same function can have different
    361   /// observable or undefined behavior than in the variant currently visible.
    362   /// For instance, we could have started with
    363   ///
    364   ///   void foo(int *v) {
    365   ///     int t = 5 / v[0];
    366   ///     (void) t;
    367   ///   }
    368   ///
    369   /// and "refined" it to
    370   ///
    371   ///   void foo(int *v) { }
    372   ///
    373   /// However, we cannot infer readnone for `foo`, since that would justify
    374   /// DSE'ing a store to `v[0]` across a call to `foo`, which can cause
    375   /// undefined behavior if the linker replaces the actual call destination with
    376   /// the unoptimized `foo`.
    377   ///
    378   /// Inlining is okay across non-exact linkage types as long as they're not
    379   /// interposable (see \c isInterposable), since in such cases the currently
    380   /// visible variant is *a* correct implementation of the original source
    381   /// function; it just isn't the *only* correct implementation.
    382   bool isDefinitionExact() const {
    383     return !mayBeDerefined();
    384   }
    385 
    386   /// Return true if this global has an exact defintion.
    387   bool hasExactDefinition() const {
    388     // While this computes exactly the same thing as
    389     // isStrongDefinitionForLinker, the intended uses are different.  This
    390     // function is intended to help decide if specific inter-procedural
    391     // transforms are correct, while isStrongDefinitionForLinker's intended use
    392     // is in low level code generation.
    393     return !isDeclaration() && isDefinitionExact();
    394   }
    395 
    396   /// Return true if this global's definition can be substituted with an
    397   /// *arbitrary* definition at link time.  We cannot do any IPO or inlinining
    398   /// across interposable call edges, since the callee can be replaced with
    399   /// something arbitrary at link time.
    400   bool isInterposable() const { return isInterposableLinkage(getLinkage()); }
    401 
    402   bool hasExternalLinkage() const { return isExternalLinkage(getLinkage()); }
    403   bool hasAvailableExternallyLinkage() const {
    404     return isAvailableExternallyLinkage(getLinkage());
    405   }
    406   bool hasLinkOnceLinkage() const { return isLinkOnceLinkage(getLinkage()); }
    407   bool hasLinkOnceODRLinkage() const {
    408     return isLinkOnceODRLinkage(getLinkage());
    409   }
    410   bool hasWeakLinkage() const { return isWeakLinkage(getLinkage()); }
    411   bool hasWeakAnyLinkage() const { return isWeakAnyLinkage(getLinkage()); }
    412   bool hasWeakODRLinkage() const { return isWeakODRLinkage(getLinkage()); }
    413   bool hasAppendingLinkage() const { return isAppendingLinkage(getLinkage()); }
    414   bool hasInternalLinkage() const { return isInternalLinkage(getLinkage()); }
    415   bool hasPrivateLinkage() const { return isPrivateLinkage(getLinkage()); }
    416   bool hasLocalLinkage() const { return isLocalLinkage(getLinkage()); }
    417   bool hasExternalWeakLinkage() const {
    418     return isExternalWeakLinkage(getLinkage());
    419   }
    420   bool hasCommonLinkage() const { return isCommonLinkage(getLinkage()); }
    421   bool hasValidDeclarationLinkage() const {
    422     return isValidDeclarationLinkage(getLinkage());
    423   }
    424 
    425   void setLinkage(LinkageTypes LT) {
    426     if (isLocalLinkage(LT))
    427       Visibility = DefaultVisibility;
    428     Linkage = LT;
    429   }
    430   LinkageTypes getLinkage() const { return LinkageTypes(Linkage); }
    431 
    432   bool isDiscardableIfUnused() const {
    433     return isDiscardableIfUnused(getLinkage());
    434   }
    435 
    436   bool isWeakForLinker() const { return isWeakForLinker(getLinkage()); }
    437 
    438 protected:
    439   /// Copy all additional attributes (those not needed to create a GlobalValue)
    440   /// from the GlobalValue Src to this one.
    441   void copyAttributesFrom(const GlobalValue *Src);
    442 
    443 public:
    444   /// If the given string begins with the GlobalValue name mangling escape
    445   /// character '\1', drop it.
    446   ///
    447   /// This function applies a specific mangling that is used in PGO profiles,
    448   /// among other things. If you're trying to get a symbol name for an
    449   /// arbitrary GlobalValue, this is not the function you're looking for; see
    450   /// Mangler.h.
    451   static StringRef dropLLVMManglingEscape(StringRef Name) {
    452     if (!Name.empty() && Name[0] == '\1')
    453       return Name.substr(1);
    454     return Name;
    455   }
    456 
    457   /// Return the modified name for a global value suitable to be
    458   /// used as the key for a global lookup (e.g. profile or ThinLTO).
    459   /// The value's original name is \c Name and has linkage of type
    460   /// \c Linkage. The value is defined in module \c FileName.
    461   static std::string getGlobalIdentifier(StringRef Name,
    462                                          GlobalValue::LinkageTypes Linkage,
    463                                          StringRef FileName);
    464 
    465   /// Return the modified name for this global value suitable to be
    466   /// used as the key for a global lookup (e.g. profile or ThinLTO).
    467   std::string getGlobalIdentifier() const;
    468 
    469   /// Declare a type to represent a global unique identifier for a global value.
    470   /// This is a 64 bits hash that is used by PGO and ThinLTO to have a compact
    471   /// unique way to identify a symbol.
    472   using GUID = uint64_t;
    473 
    474   /// Return a 64-bit global unique ID constructed from global value name
    475   /// (i.e. returned by getGlobalIdentifier()).
    476   static GUID getGUID(StringRef GlobalName) { return MD5Hash(GlobalName); }
    477 
    478   /// Return a 64-bit global unique ID constructed from global value name
    479   /// (i.e. returned by getGlobalIdentifier()).
    480   GUID getGUID() const { return getGUID(getGlobalIdentifier()); }
    481 
    482   /// @name Materialization
    483   /// Materialization is used to construct functions only as they're needed.
    484   /// This
    485   /// is useful to reduce memory usage in LLVM or parsing work done by the
    486   /// BitcodeReader to load the Module.
    487   /// @{
    488 
    489   /// If this function's Module is being lazily streamed in functions from disk
    490   /// or some other source, this method can be used to check to see if the
    491   /// function has been read in yet or not.
    492   bool isMaterializable() const;
    493 
    494   /// Make sure this GlobalValue is fully read.
    495   Error materialize();
    496 
    497 /// @}
    498 
    499   /// Return true if the primary definition of this global value is outside of
    500   /// the current translation unit.
    501   bool isDeclaration() const;
    502 
    503   bool isDeclarationForLinker() const {
    504     if (hasAvailableExternallyLinkage())
    505       return true;
    506 
    507     return isDeclaration();
    508   }
    509 
    510   /// Returns true if this global's definition will be the one chosen by the
    511   /// linker.
    512   ///
    513   /// NB! Ideally this should not be used at the IR level at all.  If you're
    514   /// interested in optimization constraints implied by the linker's ability to
    515   /// choose an implementation, prefer using \c hasExactDefinition.
    516   bool isStrongDefinitionForLinker() const {
    517     return !(isDeclarationForLinker() || isWeakForLinker());
    518   }
    519 
    520   // Returns true if the alignment of the value can be unilaterally
    521   // increased.
    522   bool canIncreaseAlignment() const;
    523 
    524   const GlobalObject *getBaseObject() const;
    525   GlobalObject *getBaseObject() {
    526     return const_cast<GlobalObject *>(
    527                        static_cast<const GlobalValue *>(this)->getBaseObject());
    528   }
    529 
    530   /// Returns whether this is a reference to an absolute symbol.
    531   bool isAbsoluteSymbolRef() const;
    532 
    533   /// If this is an absolute symbol reference, returns the range of the symbol,
    534   /// otherwise returns None.
    535   Optional<ConstantRange> getAbsoluteSymbolRange() const;
    536 
    537   /// This method unlinks 'this' from the containing module, but does not delete
    538   /// it.
    539   void removeFromParent();
    540 
    541   /// This method unlinks 'this' from the containing module and deletes it.
    542   void eraseFromParent();
    543 
    544   /// Get the module that this global value is contained inside of...
    545   Module *getParent() { return Parent; }
    546   const Module *getParent() const { return Parent; }
    547 
    548   // Methods for support type inquiry through isa, cast, and dyn_cast:
    549   static bool classof(const Value *V) {
    550     return V->getValueID() == Value::FunctionVal ||
    551            V->getValueID() == Value::GlobalVariableVal ||
    552            V->getValueID() == Value::GlobalAliasVal ||
    553            V->getValueID() == Value::GlobalIFuncVal;
    554   }
    555 };
    556 
    557 } // end namespace llvm
    558 
    559 #endif // LLVM_IR_GLOBALVALUE_H
    560