include/llvm/ParameterAttributes.h

   1 //===-- llvm/ParameterAttributes.h - Container for ParamAttrs ---*- 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 contains the types necessary to represent the parameter attributes
  11 // associated with functions and their calls.
  12 //
  13 // The implementations of these classes live in lib/VMCore/Function.cpp.
  14 //
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef LLVM_PARAMETER_ATTRIBUTES_H
  18 #define LLVM_PARAMETER_ATTRIBUTES_H
  19
  20 #include "llvm/ADT/SmallVector.h"
  21 #include "llvm/ADT/FoldingSet.h"
  22 #include <cassert>
  23
  24 namespace llvm {
  25 namespace ParamAttr {
  26
  27 /// Function parameters and results can have attributes to indicate how they
  28 /// should be treated by optimizations and code generation. This enumeration
  29 /// lists the attributes that can be associated with parameters or function
  30 /// results.
  31 /// @brief Function parameter attributes.
  32 enum Attributes {
  33   None       = 0,       ///< No attributes have been set
  34   ZExt       = 1 << 0,  ///< Zero extended before/after call
  35   SExt       = 1 << 1,  ///< Sign extended before/after call
  36   NoReturn   = 1 << 2,  ///< Mark the function as not returning
  37   InReg      = 1 << 3,  ///< Force argument to be passed in register
  38   StructRet  = 1 << 4,  ///< Hidden pointer to structure to return
  39   NoUnwind   = 1 << 5,  ///< Function doesn't unwind stack
  40   NoAlias    = 1 << 6,  ///< Considered to not alias after call
  41   ByVal      = 1 << 7,  ///< Pass structure by value
  42   Nest       = 1 << 8,  ///< Nested function static chain
  43   ReadNone   = 1 << 9,  ///< Function does not access memory
  44   ReadOnly   = 1 << 10  ///< Function only reads from memory
  45 };
  46
  47 /// These attributes can safely be dropped from a function or a function call:
  48 /// doing so may reduce the number of optimizations performed, but it will not
  49 /// change a correct program into an incorrect one.
  50 /// @brief Attributes that do not change the calling convention.
  51 const uint16_t Informative = NoReturn | NoUnwind | NoAlias |
  52                              ReadNone | ReadOnly;
  53
  54 /// @brief Attributes that only apply to function parameters.
  55 const uint16_t ParameterOnly = ByVal | InReg | Nest | StructRet;
  56
  57 /// @brief Attributes that only apply to function return values.
  58 const uint16_t ReturnOnly = NoReturn | NoUnwind | ReadNone | ReadOnly;
  59
  60 /// @brief Attributes that only apply to integers.
  61 const uint16_t IntegerTypeOnly = SExt | ZExt;
  62
  63 /// @brief Attributes that only apply to pointers.
  64 const uint16_t PointerTypeOnly = ByVal | Nest | NoAlias | StructRet;
  65
  66 /// @brief Attributes that do not apply to void type function return values.
  67 const uint16_t VoidTypeIncompatible = IntegerTypeOnly | PointerTypeOnly |
  68                                       ParameterOnly;
  69
  70 /// @brief Attributes that are mutually incompatible.
  71 const uint16_t MutuallyIncompatible[3] = {
  72   ByVal | InReg | Nest  | StructRet,
  73   ZExt  | SExt,
  74   ReadNone | ReadOnly
  75 };
  76
  77 } // end namespace ParamAttr
  78
  79 /// This is just a pair of values to associate a set of parameter attributes
  80 /// with a parameter index.
  81 /// @brief ParameterAttributes with a parameter index.
  82 struct ParamAttrsWithIndex {
  83   uint16_t attrs; ///< The attributes that are set, or'd together
  84   uint16_t index; ///< Index of the parameter for which the attributes apply
  85
  86   static ParamAttrsWithIndex get(uint16_t idx, uint16_t attrs) {
  87     ParamAttrsWithIndex P;
  88     P.index = idx;
  89     P.attrs = attrs;
  90     return P;
  91   }
  92 };
  93
  94 /// @brief A vector of attribute/index pairs.
  95 typedef SmallVector<ParamAttrsWithIndex,4> ParamAttrsVector;
  96
  97 /// @brief A more friendly way to reference the attributes.
  98 typedef ParamAttr::Attributes ParameterAttributes;
  99
 100 /// This class represents a list of attribute/index pairs for parameter
 101 /// attributes. Each entry in the list contains the index of a function
 102 /// parameter and the associated ParameterAttributes. If a parameter's index is
 103 /// not present in the list, then no attributes are set for that parameter. The
 104 /// list may also be empty, but this does not occur in practice. An item in
 105 /// the list with an index of 0 refers to the function as a whole or its result.
 106 /// To construct a ParamAttrsList, you must first fill a ParamAttrsVector with
 107 /// the attribute/index pairs you wish to set.  The list of attributes can be
 108 /// turned into a string of mnemonics suitable for LLVM Assembly output.
 109 /// Various accessors are provided to obtain information about the attributes.
 110 /// Note that objects of this class are "uniqued". The \p get method can return
 111 /// the pointer of an existing and identical instance. Consequently, reference
 112 /// counting is necessary in order to determine when the last reference to a
 113 /// ParamAttrsList of a given shape is dropped. Users of this class should use
 114 /// the addRef and dropRef methods to add/drop references. When the reference
 115 /// count goes to zero, the ParamAttrsList object is deleted.
 116 /// This class is used by Function, CallInst and InvokeInst to represent their
 117 /// sets of parameter attributes.
 118 /// @brief A List of ParameterAttributes.
 119 class ParamAttrsList : public FoldingSetNode {
 120   /// @name Construction
 121   /// @{
 122   private:
 123     // ParamAttrsList is uniqued, these should not be publicly available
 124     void operator=(const ParamAttrsList &); // Do not implement
 125     ParamAttrsList(const ParamAttrsList &); // Do not implement
 126     ~ParamAttrsList();                      // Private implementation
 127
 128     /// Only the \p get method can invoke this when it wants to create a
 129     /// new instance.
 130     /// @brief Construct an ParamAttrsList from a ParamAttrsVector
 131     explicit ParamAttrsList(const ParamAttrsVector &attrVec);
 132
 133   public:
 134     /// This method ensures the uniqueness of ParamAttrsList instances.  The
 135     /// argument is a vector of attribute/index pairs as represented by the
 136     /// ParamAttrsWithIndex structure.  The index values must be in strictly
 137     /// increasing order and ParamAttr::None is not allowed.  The vector is
 138     /// used to construct the ParamAttrsList instance.  If an instance with
 139     /// identical vector pairs exists, it will be returned instead of creating
 140     /// a new instance.
 141     /// @brief Get a ParamAttrsList instance.
 142     static const ParamAttrsList *get(const ParamAttrsVector &attrVec);
 143
 144     /// Returns the ParamAttrsList obtained by modifying PAL using the supplied
 145     /// list of attribute/index pairs.  Any existing attributes for the given
 146     /// index are replaced by the given attributes.  If there were no attributes
 147     /// then the new ones are inserted.  Attributes can be deleted by replacing
 148     /// them with ParamAttr::None.  Index values must be strictly increasing.
 149     /// @brief Get a new ParamAttrsList instance by modifying an existing one.
 150     static const ParamAttrsList *getModified(const ParamAttrsList *PAL,
 151                                              const ParamAttrsVector &modVec);
 152
 153     /// @brief Add the specified attributes to those in PAL at index idx.
 154     static const ParamAttrsList *includeAttrs(const ParamAttrsList *PAL,
 155                                               uint16_t idx, uint16_t attrs);
 156
 157     /// @brief Remove the specified attributes from those in PAL at index idx.
 158     static const ParamAttrsList *excludeAttrs(const ParamAttrsList *PAL,
 159                                               uint16_t idx, uint16_t attrs);
 160
 161     /// Returns whether each of the specified lists of attributes can be safely
 162     /// replaced with the other in a function or a function call.
 163     /// @brief Whether one attribute list can safely replace the other.
 164     static bool areCompatible(const ParamAttrsList *A, const ParamAttrsList *B);
 165
 166   /// @}
 167   /// @name Accessors
 168   /// @{
 169   public:
 170     /// The parameter attributes for the \p indexth parameter are returned.
 171     /// The 0th parameter refers to the return type of the function. Note that
 172     /// the \p param_index is an index into the function's parameters, not an
 173     /// index into this class's list of attributes. The result of getParamIndex
 174     /// is always suitable input to this function.
 175     /// @returns The all the ParameterAttributes for the \p indexth parameter
 176     /// as a uint16_t of enumeration values OR'd together.
 177     /// @brief Get the attributes for a parameter
 178     uint16_t getParamAttrs(uint16_t param_index) const;
 179
 180     /// This checks to see if the \p ith function parameter has the parameter
 181     /// attribute given by \p attr set.
 182     /// @returns true if the parameter attribute is set
 183     /// @brief Determine if a ParameterAttributes is set
 184     bool paramHasAttr(uint16_t i, ParameterAttributes attr) const {
 185       return getParamAttrs(i) & attr;
 186     }
 187
 188     /// The set of ParameterAttributes set in Attributes is converted to a
 189     /// string of equivalent mnemonics. This is, presumably, for writing out
 190     /// the mnemonics for the assembly writer.
 191     /// @brief Convert parameter attribute bits to text
 192     static std::string getParamAttrsText(uint16_t Attributes);
 193
 194     /// The \p Indexth parameter attribute is converted to string.
 195     /// @brief Get the text for the parmeter attributes for one parameter.
 196     std::string getParamAttrsTextByIndex(uint16_t Index) const {
 197       return getParamAttrsText(getParamAttrs(Index));
 198     }
 199
 200     /// @brief Comparison operator for ParamAttrsList
 201     bool operator < (const ParamAttrsList& that) const {
 202       if (this->attrs.size() < that.attrs.size())
 203         return true;
 204       if (this->attrs.size() > that.attrs.size())
 205         return false;
 206       for (unsigned i = 0; i < attrs.size(); ++i) {
 207         if (attrs[i].index < that.attrs[i].index)
 208           return true;
 209         if (attrs[i].index > that.attrs[i].index)
 210           return false;
 211         if (attrs[i].attrs < that.attrs[i].attrs)
 212           return true;
 213         if (attrs[i].attrs > that.attrs[i].attrs)
 214           return false;
 215       }
 216       return false;
 217     }
 218
 219     /// Returns the parameter index of a particular parameter attribute in this
 220     /// list of attributes. Note that the attr_index is an index into this
 221     /// class's list of attributes, not the index of a parameter. The result
 222     /// is the index of the parameter. Clients generally should not use this
 223     /// method. It is used internally by LLVM.
 224     /// @brief Get a parameter index
 225     uint16_t getParamIndex(unsigned attr_index) const {
 226       return attrs[attr_index].index;
 227     }
 228
 229     uint16_t getParamAttrsAtIndex(unsigned attr_index) const {
 230       return attrs[attr_index].attrs;
 231     }
 232
 233     /// Determines how many parameter attributes are set in this ParamAttrsList.
 234     /// This says nothing about how many parameters the function has. It also
 235     /// says nothing about the highest parameter index that has attributes.
 236     /// Clients generally should not use this method. It is used internally by
 237     /// LLVM.
 238     /// @returns the number of parameter attributes in this ParamAttrsList.
 239     /// @brief Return the number of parameter attributes this type has.
 240     unsigned size() const { return attrs.size(); }
 241
 242     /// @brief Return the number of references to this ParamAttrsList.
 243     unsigned numRefs() const { return refCount; }
 244
 245   /// @}
 246   /// @name Mutators
 247   /// @{
 248   public:
 249     /// Classes retaining references to ParamAttrsList objects should call this
 250     /// method to increment the reference count. This ensures that the
 251     /// ParamAttrsList object will not disappear until the class drops it.
 252     /// @brief Add a reference to this instance.
 253     void addRef() const { refCount++; }
 254
 255     /// Classes retaining references to ParamAttrsList objects should call this
 256     /// method to decrement the reference count and possibly delete the
 257     /// ParamAttrsList object. This ensures that ParamAttrsList objects are
 258     /// cleaned up only when the last reference to them is dropped.
 259     /// @brief Drop a reference to this instance.
 260     void dropRef() const {
 261       assert(refCount != 0 && "dropRef without addRef");
 262       if (--refCount == 0)
 263         delete this;
 264     }
 265
 266   /// @}
 267   /// @name Implementation Details
 268   /// @{
 269   public:
 270     void Profile(FoldingSetNodeID &ID) const {
 271       Profile(ID, attrs);
 272     }
 273     static void Profile(FoldingSetNodeID &ID, const ParamAttrsVector &Attrs);
 274     void dump() const;
 275
 276   /// @}
 277   /// @name Data
 278   /// @{
 279   private:
 280     ParamAttrsVector attrs;     ///< The list of attributes
 281     mutable unsigned refCount;  ///< The number of references to this object
 282   /// @}
 283 };
 284
 285 } // End llvm namespace
 286
 287 #endif