include/llvm/IR/Metadata.h

   1 //===-- llvm/Metadata.h - Metadata definitions ------------------*- 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 /// @file
  11 /// This file contains the declarations for metadata subclasses.
  12 /// They represent the different flavors of metadata that live in LLVM.
  13 //
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_IR_METADATA_H
  17 #define LLVM_IR_METADATA_H
  18
  19 #include "llvm/ADT/ArrayRef.h"
  20 #include "llvm/ADT/DenseMap.h"
  21 #include "llvm/ADT/FoldingSet.h"
  22 #include "llvm/ADT/ilist_node.h"
  23 #include "llvm/ADT/iterator_range.h"
  24 #include "llvm/IR/Value.h"
  25
  26 namespace llvm {
  27 class LLVMContext;
  28 class Module;
  29 template<typename ValueSubClass, typename ItemParentClass>
  30   class SymbolTableListTraits;
  31
  32
  33 enum LLVMConstants : uint32_t {
  34   DEBUG_METADATA_VERSION = 2  // Current debug info version number.
  35 };
  36
  37 /// \brief Root of the metadata hierarchy.
  38 ///
  39 /// This is a root class for typeless data in the IR.
  40 ///
  41 /// TODO: Detach from the Value hierarchy.
  42 class Metadata : public Value {
  43 protected:
  44   Metadata(Type *Type, unsigned ID) : Value(Type, ID) {}
  45
  46 public:
  47   static bool classof(const Value *V) {
  48     return V->getValueID() == MDNodeVal;
  49   }
  50 };
  51
  52 //===----------------------------------------------------------------------===//
  53 /// \brief A single uniqued string.
  54 ///
  55 /// These are used to efficiently contain a byte sequence for metadata.
  56 /// MDString is always unnamed.
  57 ///
  58 /// TODO: Inherit from Metadata.
  59 class MDString : public Value {
  60   virtual void anchor();
  61   MDString(const MDString &) LLVM_DELETED_FUNCTION;
  62
  63   explicit MDString(LLVMContext &C);
  64 public:
  65   static MDString *get(LLVMContext &Context, StringRef Str);
  66   static MDString *get(LLVMContext &Context, const char *Str) {
  67     return get(Context, Str ? StringRef(Str) : StringRef());
  68   }
  69
  70   StringRef getString() const { return getName(); }
  71
  72   unsigned getLength() const { return (unsigned)getName().size(); }
  73
  74   typedef StringRef::iterator iterator;
  75
  76   /// \brief Pointer to the first byte of the string.
  77   iterator begin() const { return getName().begin(); }
  78
  79   /// \brief Pointer to one byte past the end of the string.
  80   iterator end() const { return getName().end(); }
  81
  82   /// \brief Methods for support type inquiry through isa, cast, and dyn_cast.
  83   static bool classof(const Value *V) {
  84     return V->getValueID() == MDStringVal;
  85   }
  86 };
  87
  88 /// \brief A collection of metadata nodes that might be associated with a
  89 /// memory access used by the alias-analysis infrastructure.
  90 struct AAMDNodes {
  91   explicit AAMDNodes(MDNode *T = nullptr, MDNode *S = nullptr,
  92                      MDNode *N = nullptr)
  93       : TBAA(T), Scope(S), NoAlias(N) {}
  94
  95   bool operator==(const AAMDNodes &A) const {
  96     return TBAA == A.TBAA && Scope == A.Scope && NoAlias == A.NoAlias;
  97   }
  98
  99   bool operator!=(const AAMDNodes &A) const { return !(*this == A); }
 100
 101   LLVM_EXPLICIT operator bool() const { return TBAA || Scope || NoAlias; }
 102
 103   /// \brief The tag for type-based alias analysis.
 104   MDNode *TBAA;
 105
 106   /// \brief The tag for alias scope specification (used with noalias).
 107   MDNode *Scope;
 108
 109   /// \brief The tag specifying the noalias scope.
 110   MDNode *NoAlias;
 111 };
 112
 113 // Specialize DenseMapInfo for AAMDNodes.
 114 template<>
 115 struct DenseMapInfo<AAMDNodes> {
 116   static inline AAMDNodes getEmptyKey() {
 117     return AAMDNodes(DenseMapInfo<MDNode *>::getEmptyKey(), 0, 0);
 118   }
 119   static inline AAMDNodes getTombstoneKey() {
 120     return AAMDNodes(DenseMapInfo<MDNode *>::getTombstoneKey(), 0, 0);
 121   }
 122   static unsigned getHashValue(const AAMDNodes &Val) {
 123     return DenseMapInfo<MDNode *>::getHashValue(Val.TBAA) ^
 124            DenseMapInfo<MDNode *>::getHashValue(Val.Scope) ^
 125            DenseMapInfo<MDNode *>::getHashValue(Val.NoAlias);
 126   }
 127   static bool isEqual(const AAMDNodes &LHS, const AAMDNodes &RHS) {
 128     return LHS == RHS;
 129   }
 130 };
 131
 132 class MDNodeOperand;
 133
 134 //===----------------------------------------------------------------------===//
 135 /// \brief Generic tuple of metadata.
 136 class MDNode : public Metadata, public FoldingSetNode {
 137   MDNode(const MDNode &) LLVM_DELETED_FUNCTION;
 138   void operator=(const MDNode &) LLVM_DELETED_FUNCTION;
 139   friend class MDNodeOperand;
 140   friend class LLVMContextImpl;
 141   friend struct FoldingSetTrait<MDNode>;
 142
 143   /// \brief If the MDNode is uniqued cache the hash to speed up lookup.
 144   unsigned Hash;
 145
 146   /// \brief Subclass data enums.
 147   enum {
 148     /// FunctionLocalBit - This bit is set if this MDNode is function local.
 149     /// This is true when it (potentially transitively) contains a reference to
 150     /// something in a function, like an argument, basicblock, or instruction.
 151     FunctionLocalBit = 1 << 0,
 152
 153     /// NotUniquedBit - This is set on MDNodes that are not uniqued because they
 154     /// have a null operand.
 155     NotUniquedBit    = 1 << 1,
 156
 157     /// DestroyFlag - This bit is set by destroy() so the destructor can assert
 158     /// that the node isn't being destroyed with a plain 'delete'.
 159     DestroyFlag      = 1 << 2
 160   };
 161
 162   /// \brief FunctionLocal enums.
 163   enum FunctionLocalness {
 164     FL_Unknown = -1,
 165     FL_No = 0,
 166     FL_Yes = 1
 167   };
 168
 169   /// \brief Replace each instance of the given operand with a new value.
 170   void replaceOperand(MDNodeOperand *Op, Value *NewVal);
 171   ~MDNode();
 172
 173   MDNode(LLVMContext &C, ArrayRef<Value*> Vals, bool isFunctionLocal);
 174
 175   static MDNode *getMDNode(LLVMContext &C, ArrayRef<Value*> Vals,
 176                            FunctionLocalness FL, bool Insert = true);
 177 public:
 178   static MDNode *get(LLVMContext &Context, ArrayRef<Value*> Vals);
 179   /// \brief Construct MDNode with an explicit function-localness.
 180   ///
 181   /// Don't analyze Vals; trust isFunctionLocal.
 182   static MDNode *getWhenValsUnresolved(LLVMContext &Context,
 183                                        ArrayRef<Value*> Vals,
 184                                        bool isFunctionLocal);
 185
 186   static MDNode *getIfExists(LLVMContext &Context, ArrayRef<Value*> Vals);
 187
 188   /// \brief Return a temporary MDNode
 189   ///
 190   /// For use in constructing cyclic MDNode structures. A temporary MDNode is
 191   /// not uniqued, may be RAUW'd, and must be manually deleted with
 192   /// deleteTemporary.
 193   static MDNode *getTemporary(LLVMContext &Context, ArrayRef<Value*> Vals);
 194
 195   /// \brief Deallocate a node created by getTemporary.
 196   ///
 197   /// The node must not have any users.
 198   static void deleteTemporary(MDNode *N);
 199
 200   /// \brief Replace a specific operand.
 201   void replaceOperandWith(unsigned i, Value *NewVal);
 202
 203   /// \brief Return specified operand.
 204   Value *getOperand(unsigned i) const LLVM_READONLY;
 205
 206   /// \brief Return number of MDNode operands.
 207   unsigned getNumOperands() const { return NumOperands; }
 208
 209   /// \brief Return whether MDNode is local to a function.
 210   bool isFunctionLocal() const {
 211     return (getSubclassDataFromValue() & FunctionLocalBit) != 0;
 212   }
 213
 214   /// \brief Return the first function-local operand's function.
 215   ///
 216   /// If this metadata is function-local and recursively has a function-local
 217   /// operand, return the first such operand's parent function.  Otherwise,
 218   /// return null. getFunction() should not be used for performance- critical
 219   /// code because it recursively visits all the MDNode's operands.
 220   const Function *getFunction() const;
 221
 222   /// \brief Calculate a unique identifier for this MDNode.
 223   void Profile(FoldingSetNodeID &ID) const;
 224
 225   /// \brief Methods for support type inquiry through isa, cast, and dyn_cast:
 226   static bool classof(const Value *V) {
 227     return V->getValueID() == MDNodeVal;
 228   }
 229
 230   /// \brief Check whether MDNode is a vtable access.
 231   bool isTBAAVtableAccess() const;
 232
 233   /// \brief Methods for metadata merging.
 234   static MDNode *concatenate(MDNode *A, MDNode *B);
 235   static MDNode *intersect(MDNode *A, MDNode *B);
 236   static MDNode *getMostGenericTBAA(MDNode *A, MDNode *B);
 237   static AAMDNodes getMostGenericAA(const AAMDNodes &A, const AAMDNodes &B);
 238   static MDNode *getMostGenericFPMath(MDNode *A, MDNode *B);
 239   static MDNode *getMostGenericRange(MDNode *A, MDNode *B);
 240 private:
 241   /// \brief Delete this node.  Only when there are no uses.
 242   void destroy();
 243
 244   bool isNotUniqued() const {
 245     return (getSubclassDataFromValue() & NotUniquedBit) != 0;
 246   }
 247   void setIsNotUniqued();
 248
 249   // Shadow Value::setValueSubclassData with a private forwarding method so that
 250   // any future subclasses cannot accidentally use it.
 251   void setValueSubclassData(unsigned short D) {
 252     Value::setValueSubclassData(D);
 253   }
 254 };
 255
 256 //===----------------------------------------------------------------------===//
 257 /// \brief A tuple of MDNodes.
 258 ///
 259 /// Despite its name, a NamedMDNode isn't itself an MDNode. NamedMDNodes belong
 260 /// to modules, have names, and contain lists of MDNodes.
 261 ///
 262 /// TODO: Inherit from Metadata.
 263 class NamedMDNode : public ilist_node<NamedMDNode> {
 264   friend class SymbolTableListTraits<NamedMDNode, Module>;
 265   friend struct ilist_traits<NamedMDNode>;
 266   friend class LLVMContextImpl;
 267   friend class Module;
 268   NamedMDNode(const NamedMDNode &) LLVM_DELETED_FUNCTION;
 269
 270   std::string Name;
 271   Module *Parent;
 272   void *Operands; // SmallVector<TrackingVH<MDNode>, 4>
 273
 274   void setParent(Module *M) { Parent = M; }
 275
 276   explicit NamedMDNode(const Twine &N);
 277
 278   template<class T1, class T2>
 279   class op_iterator_impl :
 280       public std::iterator<std::bidirectional_iterator_tag, T2> {
 281     const NamedMDNode *Node;
 282     unsigned Idx;
 283     op_iterator_impl(const NamedMDNode *N, unsigned i) : Node(N), Idx(i) { }
 284
 285     friend class NamedMDNode;
 286
 287   public:
 288     op_iterator_impl() : Node(nullptr), Idx(0) { }
 289
 290     bool operator==(const op_iterator_impl &o) const { return Idx == o.Idx; }
 291     bool operator!=(const op_iterator_impl &o) const { return Idx != o.Idx; }
 292     op_iterator_impl &operator++() {
 293       ++Idx;
 294       return *this;
 295     }
 296     op_iterator_impl operator++(int) {
 297       op_iterator_impl tmp(*this);
 298       operator++();
 299       return tmp;
 300     }
 301     op_iterator_impl &operator--() {
 302       --Idx;
 303       return *this;
 304     }
 305     op_iterator_impl operator--(int) {
 306       op_iterator_impl tmp(*this);
 307       operator--();
 308       return tmp;
 309     }
 310
 311     T1 operator*() const { return Node->getOperand(Idx); }
 312   };
 313
 314 public:
 315   /// \brief Drop all references and remove the node from parent module.
 316   void eraseFromParent();
 317
 318   /// \brief Remove all uses and clear node vector.
 319   void dropAllReferences();
 320
 321   ~NamedMDNode();
 322
 323   /// \brief Get the module that holds this named metadata collection.
 324   inline Module *getParent() { return Parent; }
 325   inline const Module *getParent() const { return Parent; }
 326
 327   MDNode *getOperand(unsigned i) const;
 328   unsigned getNumOperands() const;
 329   void addOperand(MDNode *M);
 330   StringRef getName() const;
 331   void print(raw_ostream &ROS) const;
 332   void dump() const;
 333
 334   // ---------------------------------------------------------------------------
 335   // Operand Iterator interface...
 336   //
 337   typedef op_iterator_impl<MDNode *, MDNode> op_iterator;
 338   op_iterator op_begin() { return op_iterator(this, 0); }
 339   op_iterator op_end()   { return op_iterator(this, getNumOperands()); }
 340
 341   typedef op_iterator_impl<const MDNode *, MDNode> const_op_iterator;
 342   const_op_iterator op_begin() const { return const_op_iterator(this, 0); }
 343   const_op_iterator op_end()   const { return const_op_iterator(this, getNumOperands()); }
 344
 345   inline iterator_range<op_iterator>  operands() {
 346     return iterator_range<op_iterator>(op_begin(), op_end());
 347   }
 348   inline iterator_range<const_op_iterator> operands() const {
 349     return iterator_range<const_op_iterator>(op_begin(), op_end());
 350   }
 351 };
 352
 353 } // end llvm namespace
 354
 355 #endif