include/llvm/IR/Attributes.h

   1 //===-- llvm/Attributes.h - Container for Attributes ------------*- 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 /// \brief This file contains the simple types necessary to represent the
  12 /// attributes associated with functions and their calls.
  13 ///
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_ATTRIBUTES_H
  17 #define LLVM_ATTRIBUTES_H
  18
  19 #include "llvm/ADT/ArrayRef.h"
  20 #include "llvm/ADT/DenseSet.h"
  21 #include <string>
  22
  23 namespace llvm {
  24
  25 class AttrBuilder;
  26 class AttributeImpl;
  27 class LLVMContext;
  28 class Type;
  29
  30 //===----------------------------------------------------------------------===//
  31 /// \class
  32 /// \brief Functions, function parameters, and return types can have attributes
  33 /// to indicate how they should be treated by optimizations and code
  34 /// generation. This class represents one of those attributes. It's light-weight
  35 /// and should be passed around by-value.
  36 class Attribute {
  37 public:
  38   /// This enumeration lists the attributes that can be associated with
  39   /// parameters, function results or the function itself.
  40   ///
  41   /// Note: uwtable is about the ABI or the user mandating an entry in the
  42   /// unwind table. The nounwind attribute is about an exception passing by the
  43   /// function.
  44   ///
  45   /// In a theoretical system that uses tables for profiling and sjlj for
  46   /// exceptions, they would be fully independent. In a normal system that uses
  47   /// tables for both, the semantics are:
  48   ///
  49   /// nil                = Needs an entry because an exception might pass by.
  50   /// nounwind           = No need for an entry
  51   /// uwtable            = Needs an entry because the ABI says so and because
  52   ///                      an exception might pass by.
  53   /// uwtable + nounwind = Needs an entry because the ABI says so.
  54
  55   enum AttrKind {
  56     // IR-Level Attributes
  57     None,                  ///< No attributes have been set
  58     AddressSafety,         ///< Address safety checking is on.
  59     Alignment,             ///< Alignment of parameter (5 bits)
  60                            ///< stored as log2 of alignment with +1 bias
  61                            ///< 0 means unaligned (different from align(1))
  62     AlwaysInline,          ///< inline=always
  63     ByVal,                 ///< Pass structure by value
  64     InlineHint,            ///< Source said inlining was desirable
  65     InReg,                 ///< Force argument to be passed in register
  66     MinSize,               ///< Function must be optimized for size first
  67     Naked,                 ///< Naked function
  68     Nest,                  ///< Nested function static chain
  69     NoAlias,               ///< Considered to not alias after call
  70     NoCapture,             ///< Function creates no aliases of pointer
  71     NoDuplicate,           ///< Call cannot be duplicated
  72     NoImplicitFloat,       ///< Disable implicit floating point insts
  73     NoInline,              ///< inline=never
  74     NonLazyBind,           ///< Function is called early and/or
  75                            ///< often, so lazy binding isn't worthwhile
  76     NoRedZone,             ///< Disable redzone
  77     NoReturn,              ///< Mark the function as not returning
  78     NoUnwind,              ///< Function doesn't unwind stack
  79     OptimizeForSize,       ///< opt_size
  80     ReadNone,              ///< Function does not access memory
  81     ReadOnly,              ///< Function only reads from memory
  82     ReturnsTwice,          ///< Function can return twice
  83     SExt,                  ///< Sign extended before/after call
  84     StackAlignment,        ///< Alignment of stack for function (3 bits)
  85                            ///< stored as log2 of alignment with +1 bias 0
  86                            ///< means unaligned (different from
  87                            ///< alignstack=(1))
  88     StackProtect,          ///< Stack protection.
  89     StackProtectReq,       ///< Stack protection required.
  90     StructRet,             ///< Hidden pointer to structure to return
  91     UWTable,               ///< Function must be in a unwind table
  92     ZExt                   ///< Zero extended before/after call
  93   };
  94 private:
  95   AttributeImpl *pImpl;
  96   Attribute(AttributeImpl *A) : pImpl(A) {}
  97 public:
  98   Attribute() : pImpl(0) {}
  99
 100   /// \brief Return a uniquified Attribute object. This takes the uniquified
 101   /// value from the Builder and wraps it in the Attribute class.
 102   static Attribute get(LLVMContext &Context, ArrayRef<AttrKind> Vals);
 103   static Attribute get(LLVMContext &Context, AttrBuilder &B);
 104
 105   /// \brief Return true if the attribute is present.
 106   bool hasAttribute(AttrKind Val) const;
 107
 108   /// \brief Return true if attributes exist
 109   bool hasAttributes() const;
 110
 111   /// \brief Return true if the attributes are a non-null intersection.
 112   bool hasAttributes(const Attribute &A) const;
 113
 114   /// \brief Returns the alignment field of an attribute as a byte alignment
 115   /// value.
 116   unsigned getAlignment() const;
 117
 118   /// \brief Returns the stack alignment field of an attribute as a byte
 119   /// alignment value.
 120   unsigned getStackAlignment() const;
 121
 122   bool operator==(AttrKind K) const;
 123   bool operator!=(AttrKind K) const;
 124
 125   // FIXME: Remove these 'operator' methods.
 126   bool operator==(const Attribute &A) const {
 127     return pImpl == A.pImpl;
 128   }
 129   bool operator!=(const Attribute &A) const {
 130     return pImpl != A.pImpl;
 131   }
 132
 133   uint64_t getBitMask() const;
 134
 135   /// \brief Which attributes cannot be applied to a type.
 136   static Attribute typeIncompatible(Type *Ty);
 137
 138   /// \brief This returns an integer containing an encoding of all the LLVM
 139   /// attributes found in the given attribute bitset.  Any change to this
 140   /// encoding is a breaking change to bitcode compatibility.
 141   static uint64_t encodeLLVMAttributesForBitcode(Attribute Attrs);
 142
 143   /// \brief This returns an attribute bitset containing the LLVM attributes
 144   /// that have been decoded from the given integer.  This function must stay in
 145   /// sync with 'encodeLLVMAttributesForBitcode'.
 146   static Attribute decodeLLVMAttributesForBitcode(LLVMContext &C,
 147                                                   uint64_t EncodedAttrs);
 148
 149   /// \brief The Attribute is converted to a string of equivalent mnemonic. This
 150   /// is, presumably, for writing out the mnemonics for the assembly writer.
 151   std::string getAsString() const;
 152 };
 153
 154 //===----------------------------------------------------------------------===//
 155 /// \class
 156 /// \brief Provide DenseMapInfo for Attribute::AttrKind.
 157 template<> struct DenseMapInfo<Attribute::AttrKind> {
 158   static inline Attribute::AttrKind getEmptyKey() {
 159     return Attribute::AttrKind(-1);
 160   }
 161   static inline Attribute::AttrKind getTombstoneKey() {
 162     return Attribute::AttrKind(~0UL - 1L);
 163   }
 164   static unsigned getHashValue(const Attribute::AttrKind &Val) {
 165     return (unsigned)(Val * 37UL);
 166   }
 167   static bool isEqual(const Attribute::AttrKind &LHS,
 168                       const Attribute::AttrKind &RHS) {
 169     return LHS == RHS;
 170   }
 171 };
 172
 173 //===----------------------------------------------------------------------===//
 174 /// \class
 175 /// \brief This class is used in conjunction with the Attribute::get method to
 176 /// create an Attribute object. The object itself is uniquified. The Builder's
 177 /// value, however, is not. So this can be used as a quick way to test for
 178 /// equality, presence of attributes, etc.
 179 class AttrBuilder {
 180   DenseSet<Attribute::AttrKind> AttrSet;
 181   uint64_t Alignment;
 182   uint64_t StackAlignment;
 183
 184   uint64_t Bits;  // FIXME: Remove after encoding the attr list in the bc file.
 185 public:
 186   AttrBuilder() : Alignment(0), StackAlignment(0), Bits(0) {}
 187   explicit AttrBuilder(uint64_t B) : Bits(B) {}
 188   AttrBuilder(const Attribute &A) : Bits(A.getBitMask()) {}
 189
 190   /// \brief Clear out the builder's internals.
 191   void clear();
 192
 193   /// \brief Add an attribute to the builder.
 194   AttrBuilder &addAttribute(Attribute::AttrKind Val);
 195
 196   /// \brief Remove an attribute from the builder.
 197   AttrBuilder &removeAttribute(Attribute::AttrKind Val);
 198
 199   /// \brief Add the attributes from A to the builder.
 200   AttrBuilder &addAttributes(const Attribute &A);
 201
 202   /// \brief Remove the attributes from A from the builder.
 203   AttrBuilder &removeAttributes(const Attribute &A);
 204
 205   /// \brief Return true if the builder has IR-level attributes.
 206   bool hasAttributes() const;
 207
 208   /// \brief Return true if the builder has any attribute that's in the
 209   /// specified attribute.
 210   bool hasAttributes(const Attribute &A) const;
 211
 212   /// \brief Return true if the builder has an alignment attribute.
 213   bool hasAlignmentAttr() const;
 214
 215   /// \brief Retrieve the alignment attribute, if it exists.
 216   uint64_t getAlignment() const;
 217
 218   /// \brief Retrieve the stack alignment attribute, if it exists.
 219   uint64_t getStackAlignment() const;
 220
 221   /// \brief This turns an int alignment (which must be a power of 2) into the
 222   /// form used internally in Attribute.
 223   AttrBuilder &addAlignmentAttr(unsigned Align);
 224
 225   /// \brief This turns an int stack alignment (which must be a power of 2) into
 226   /// the form used internally in Attribute.
 227   AttrBuilder &addStackAlignmentAttr(unsigned Align);
 228
 229   /// \brief Add the raw value to the internal representation.
 230   ///
 231   /// N.B. This should be used ONLY for decoding LLVM bitcode!
 232   AttrBuilder &addRawValue(uint64_t Val);
 233
 234   /// \brief Remove attributes that are used on functions only.
 235   void removeFunctionOnlyAttrs() {
 236     removeAttribute(Attribute::NoReturn)
 237       .removeAttribute(Attribute::NoUnwind)
 238       .removeAttribute(Attribute::ReadNone)
 239       .removeAttribute(Attribute::ReadOnly)
 240       .removeAttribute(Attribute::NoInline)
 241       .removeAttribute(Attribute::AlwaysInline)
 242       .removeAttribute(Attribute::OptimizeForSize)
 243       .removeAttribute(Attribute::StackProtect)
 244       .removeAttribute(Attribute::StackProtectReq)
 245       .removeAttribute(Attribute::NoRedZone)
 246       .removeAttribute(Attribute::NoImplicitFloat)
 247       .removeAttribute(Attribute::Naked)
 248       .removeAttribute(Attribute::InlineHint)
 249       .removeAttribute(Attribute::StackAlignment)
 250       .removeAttribute(Attribute::UWTable)
 251       .removeAttribute(Attribute::NonLazyBind)
 252       .removeAttribute(Attribute::ReturnsTwice)
 253       .removeAttribute(Attribute::AddressSafety)
 254       .removeAttribute(Attribute::MinSize)
 255       .removeAttribute(Attribute::NoDuplicate);
 256   }
 257
 258   uint64_t getBitMask() const { return Bits; }
 259
 260   bool operator==(const AttrBuilder &B) const {
 261     return Bits == B.Bits;
 262   }
 263   bool operator!=(const AttrBuilder &B) const {
 264     return Bits != B.Bits;
 265   }
 266
 267   bool operator==(Attribute::AttrKind A) const;
 268   bool operator!=(Attribute::AttrKind A) const;
 269 };
 270
 271 //===----------------------------------------------------------------------===//
 272 /// \class
 273 /// \brief This is just a pair of values to associate a set of attributes with
 274 /// an index.
 275 struct AttributeWithIndex {
 276   Attribute Attrs;  ///< The attributes that are set, or'd together.
 277   unsigned Index;   ///< Index of the parameter for which the attributes apply.
 278                     ///< Index 0 is used for return value attributes.
 279                     ///< Index ~0U is used for function attributes.
 280
 281   static AttributeWithIndex get(LLVMContext &C, unsigned Idx,
 282                                 ArrayRef<Attribute::AttrKind> Attrs) {
 283     return get(Idx, Attribute::get(C, Attrs));
 284   }
 285   static AttributeWithIndex get(unsigned Idx, Attribute Attrs) {
 286     AttributeWithIndex P;
 287     P.Index = Idx;
 288     P.Attrs = Attrs;
 289     return P;
 290   }
 291 };
 292
 293 //===----------------------------------------------------------------------===//
 294 // AttributeSet Smart Pointer
 295 //===----------------------------------------------------------------------===//
 296
 297 class AttributeSetImpl;
 298
 299 //===----------------------------------------------------------------------===//
 300 /// \class
 301 /// \brief This class manages the ref count for the opaque AttributeSetImpl
 302 /// object and provides accessors for it.
 303 class AttributeSet {
 304 public:
 305   enum AttrIndex {
 306     ReturnIndex = 0U,
 307     FunctionIndex = ~0U
 308   };
 309 private:
 310   /// \brief The attributes that we are managing.  This can be null to represent
 311   /// the empty attributes list.
 312   AttributeSetImpl *AttrList;
 313
 314   /// \brief The attributes for the specified index are returned.  Attributes
 315   /// for the result are denoted with Idx = 0.
 316   Attribute getAttributes(unsigned Idx) const;
 317
 318   explicit AttributeSet(AttributeSetImpl *LI) : AttrList(LI) {}
 319 public:
 320   AttributeSet() : AttrList(0) {}
 321   AttributeSet(const AttributeSet &P) : AttrList(P.AttrList) {}
 322   const AttributeSet &operator=(const AttributeSet &RHS);
 323
 324   //===--------------------------------------------------------------------===//
 325   // Attribute List Construction and Mutation
 326   //===--------------------------------------------------------------------===//
 327
 328   /// \brief Return an AttributeSet with the specified parameters in it.
 329   static AttributeSet get(LLVMContext &C, ArrayRef<AttributeWithIndex> Attrs);
 330
 331   /// \brief Add the specified attribute at the specified index to this
 332   /// attribute list.  Since attribute lists are immutable, this returns the new
 333   /// list.
 334   AttributeSet addAttr(LLVMContext &C, unsigned Idx, Attribute Attrs) const;
 335
 336   /// \brief Remove the specified attribute at the specified index from this
 337   /// attribute list.  Since attribute lists are immutable, this returns the new
 338   /// list.
 339   AttributeSet removeAttr(LLVMContext &C, unsigned Idx, Attribute Attrs) const;
 340
 341   //===--------------------------------------------------------------------===//
 342   // Attribute List Accessors
 343   //===--------------------------------------------------------------------===//
 344
 345   /// \brief The attributes for the specified index are returned.
 346   Attribute getParamAttributes(unsigned Idx) const {
 347     return getAttributes(Idx);
 348   }
 349
 350   /// \brief The attributes for the ret value are returned.
 351   Attribute getRetAttributes() const {
 352     return getAttributes(ReturnIndex);
 353   }
 354
 355   /// \brief The function attributes are returned.
 356   Attribute getFnAttributes() const {
 357     return getAttributes(FunctionIndex);
 358   }
 359
 360   /// \brief Return the alignment for the specified function parameter.
 361   unsigned getParamAlignment(unsigned Idx) const {
 362     return getAttributes(Idx).getAlignment();
 363   }
 364
 365   /// \brief Return true if the attribute exists at the given index.
 366   bool hasAttribute(unsigned Index, Attribute::AttrKind Kind) const;
 367
 368   /// \brief Return true if attribute exists at the given index.
 369   bool hasAttributes(unsigned Index) const;
 370
 371   /// \brief Get the stack alignment.
 372   unsigned getStackAlignment(unsigned Index) const;
 373
 374   /// \brief Return the attributes at the index as a string.
 375   std::string getAsString(unsigned Index) const;
 376
 377   uint64_t getBitMask(unsigned Index) const;
 378
 379   /// \brief Return true if the specified attribute is set for at least one
 380   /// parameter or for the return value.
 381   bool hasAttrSomewhere(Attribute::AttrKind Attr) const;
 382
 383   /// operator==/!= - Provide equality predicates.
 384   bool operator==(const AttributeSet &RHS) const {
 385     return AttrList == RHS.AttrList;
 386   }
 387   bool operator!=(const AttributeSet &RHS) const {
 388     return AttrList != RHS.AttrList;
 389   }
 390
 391   //===--------------------------------------------------------------------===//
 392   // Attribute List Introspection
 393   //===--------------------------------------------------------------------===//
 394
 395   /// \brief Return a raw pointer that uniquely identifies this attribute list.
 396   void *getRawPointer() const {
 397     return AttrList;
 398   }
 399
 400   // Attributes are stored as a dense set of slots, where there is one slot for
 401   // each argument that has an attribute.  This allows walking over the dense
 402   // set instead of walking the sparse list of attributes.
 403
 404   /// \brief Return true if there are no attributes.
 405   bool isEmpty() const {
 406     return AttrList == 0;
 407   }
 408
 409   /// \brief Return the number of slots used in this attribute list.  This is
 410   /// the number of arguments that have an attribute set on them (including the
 411   /// function itself).
 412   unsigned getNumSlots() const;
 413
 414   /// \brief Return the AttributeWithIndex at the specified slot.  This holds a
 415   /// index number plus a set of attributes.
 416   const AttributeWithIndex &getSlot(unsigned Slot) const;
 417
 418   void dump() const;
 419 };
 420
 421 } // end llvm namespace
 422
 423 #endif