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