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