a97c196ced0dfd2319e1ad1741243b9a50c9f92b
[oota-llvm.git] / include / llvm / IR / Function.h
1 //===-- llvm/Function.h - Class to represent a single function --*- 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 declaration of the Function class, which represents a
11 // single function/procedure in LLVM.
12 //
13 // A function basically consists of a list of basic blocks, a list of arguments,
14 // and a symbol table.
15 //
16 //===----------------------------------------------------------------------===//
17
18 #ifndef LLVM_IR_FUNCTION_H
19 #define LLVM_IR_FUNCTION_H
20
21 #include "llvm/ADT/iterator_range.h"
22 #include "llvm/ADT/Optional.h"
23 #include "llvm/IR/Argument.h"
24 #include "llvm/IR/Attributes.h"
25 #include "llvm/IR/BasicBlock.h"
26 #include "llvm/IR/CallingConv.h"
27 #include "llvm/IR/GlobalObject.h"
28 #include "llvm/IR/OperandTraits.h"
29 #include "llvm/Support/Compiler.h"
30
31 namespace llvm {
32
33 class FunctionType;
34 class LLVMContext;
35 class DISubprogram;
36
37 template <>
38 struct SymbolTableListSentinelTraits<Argument>
39     : public ilist_half_embedded_sentinel_traits<Argument> {};
40
41 class Function : public GlobalObject, public ilist_node<Function> {
42 public:
43   typedef SymbolTableList<Argument> ArgumentListType;
44   typedef SymbolTableList<BasicBlock> BasicBlockListType;
45
46   // BasicBlock iterators...
47   typedef BasicBlockListType::iterator iterator;
48   typedef BasicBlockListType::const_iterator const_iterator;
49
50   typedef ArgumentListType::iterator arg_iterator;
51   typedef ArgumentListType::const_iterator const_arg_iterator;
52
53 private:
54   // Important things that make up a function!
55   BasicBlockListType  BasicBlocks;        ///< The basic blocks
56   mutable ArgumentListType ArgumentList;  ///< The formal arguments
57   ValueSymbolTable *SymTab;               ///< Symbol table of args/instructions
58   AttributeSet AttributeSets;             ///< Parameter attributes
59   FunctionType *Ty;
60
61   /*
62    * Value::SubclassData
63    *
64    * bit 0  : HasLazyArguments
65    * bit 1  : HasPrefixData
66    * bit 2  : HasPrologueData
67    * bit 3-6: CallingConvention
68    */
69
70   /// Bits from GlobalObject::GlobalObjectSubclassData.
71   enum {
72     /// Whether this function is materializable.
73     IsMaterializableBit = 1 << 0,
74     HasMetadataHashEntryBit = 1 << 1
75   };
76   void setGlobalObjectBit(unsigned Mask, bool Value) {
77     setGlobalObjectSubClassData((~Mask & getGlobalObjectSubClassData()) |
78                                 (Value ? Mask : 0u));
79   }
80
81   friend class SymbolTableListTraits<Function>;
82
83   void setParent(Module *parent);
84
85   /// hasLazyArguments/CheckLazyArguments - The argument list of a function is
86   /// built on demand, so that the list isn't allocated until the first client
87   /// needs it.  The hasLazyArguments predicate returns true if the arg list
88   /// hasn't been set up yet.
89   bool hasLazyArguments() const {
90     return getSubclassDataFromValue() & (1<<0);
91   }
92   void CheckLazyArguments() const {
93     if (hasLazyArguments())
94       BuildLazyArguments();
95   }
96   void BuildLazyArguments() const;
97
98   Function(const Function&) = delete;
99   void operator=(const Function&) = delete;
100
101   /// Function ctor - If the (optional) Module argument is specified, the
102   /// function is automatically inserted into the end of the function list for
103   /// the module.
104   ///
105   Function(FunctionType *Ty, LinkageTypes Linkage,
106            const Twine &N = "", Module *M = nullptr);
107
108 public:
109   static Function *Create(FunctionType *Ty, LinkageTypes Linkage,
110                           const Twine &N = "", Module *M = nullptr) {
111     return new(1) Function(Ty, Linkage, N, M);
112   }
113
114   ~Function() override;
115
116   /// \brief Provide fast operand accessors
117   DECLARE_TRANSPARENT_OPERAND_ACCESSORS(Value);
118
119   /// \brief Get the personality function associated with this function.
120   bool hasPersonalityFn() const { return getNumOperands() != 0; }
121   Constant *getPersonalityFn() const {
122     assert(hasPersonalityFn());
123     return cast<Constant>(Op<0>());
124   }
125   void setPersonalityFn(Constant *C);
126
127   Type *getReturnType() const;           // Return the type of the ret val
128   FunctionType *getFunctionType() const; // Return the FunctionType for me
129
130   /// getContext - Return a reference to the LLVMContext associated with this
131   /// function.
132   LLVMContext &getContext() const;
133
134   /// isVarArg - Return true if this function takes a variable number of
135   /// arguments.
136   bool isVarArg() const;
137
138   bool isMaterializable() const;
139   void setIsMaterializable(bool V);
140
141   /// getIntrinsicID - This method returns the ID number of the specified
142   /// function, or Intrinsic::not_intrinsic if the function is not an
143   /// intrinsic, or if the pointer is null.  This value is always defined to be
144   /// zero to allow easy checking for whether a function is intrinsic or not.
145   /// The particular intrinsic functions which correspond to this value are
146   /// defined in llvm/Intrinsics.h.
147   Intrinsic::ID getIntrinsicID() const LLVM_READONLY { return IntID; }
148   bool isIntrinsic() const { return getName().startswith("llvm."); }
149
150   /// \brief Recalculate the ID for this function if it is an Intrinsic defined
151   /// in llvm/Intrinsics.h.  Sets the intrinsic ID to Intrinsic::not_intrinsic
152   /// if the name of this function does not match an intrinsic in that header.
153   /// Note, this method does not need to be called directly, as it is called
154   /// from Value::setName() whenever the name of this function changes.
155   void recalculateIntrinsicID();
156
157   /// getCallingConv()/setCallingConv(CC) - These method get and set the
158   /// calling convention of this function.  The enum values for the known
159   /// calling conventions are defined in CallingConv.h.
160   CallingConv::ID getCallingConv() const {
161     return static_cast<CallingConv::ID>(getSubclassDataFromValue() >> 3);
162   }
163   void setCallingConv(CallingConv::ID CC) {
164     setValueSubclassData((getSubclassDataFromValue() & 7) |
165                          (static_cast<unsigned>(CC) << 3));
166   }
167
168   /// @brief Return the attribute list for this Function.
169   AttributeSet getAttributes() const { return AttributeSets; }
170
171   /// @brief Set the attribute list for this Function.
172   void setAttributes(AttributeSet attrs) { AttributeSets = attrs; }
173
174   /// @brief Add function attributes to this function.
175   void addFnAttr(Attribute::AttrKind N) {
176     setAttributes(AttributeSets.addAttribute(getContext(),
177                                              AttributeSet::FunctionIndex, N));
178   }
179
180   /// @brief Remove function attributes from this function.
181   void removeFnAttr(Attribute::AttrKind N) {
182     setAttributes(AttributeSets.removeAttribute(
183         getContext(), AttributeSet::FunctionIndex, N));
184   }
185
186   /// @brief Add function attributes to this function.
187   void addFnAttr(StringRef Kind) {
188     setAttributes(
189       AttributeSets.addAttribute(getContext(),
190                                  AttributeSet::FunctionIndex, Kind));
191   }
192   void addFnAttr(StringRef Kind, StringRef Value) {
193     setAttributes(
194       AttributeSets.addAttribute(getContext(),
195                                  AttributeSet::FunctionIndex, Kind, Value));
196   }
197
198   /// Set the entry count for this function.
199   void setEntryCount(uint64_t Count);
200
201   /// Get the entry count for this function.
202   Optional<uint64_t> getEntryCount() const;
203
204   /// @brief Return true if the function has the attribute.
205   bool hasFnAttribute(Attribute::AttrKind Kind) const {
206     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex, Kind);
207   }
208   bool hasFnAttribute(StringRef Kind) const {
209     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex, Kind);
210   }
211
212   /// @brief Return the attribute for the given attribute kind.
213   Attribute getFnAttribute(Attribute::AttrKind Kind) const {
214     return AttributeSets.getAttribute(AttributeSet::FunctionIndex, Kind);
215   }
216   Attribute getFnAttribute(StringRef Kind) const {
217     return AttributeSets.getAttribute(AttributeSet::FunctionIndex, Kind);
218   }
219
220   /// \brief Return the stack alignment for the function.
221   unsigned getFnStackAlignment() const {
222     return AttributeSets.getStackAlignment(AttributeSet::FunctionIndex);
223   }
224
225   /// hasGC/getGC/setGC/clearGC - The name of the garbage collection algorithm
226   ///                             to use during code generation.
227   bool hasGC() const;
228   const char *getGC() const;
229   void setGC(const char *Str);
230   void clearGC();
231
232   /// @brief adds the attribute to the list of attributes.
233   void addAttribute(unsigned i, Attribute::AttrKind attr);
234
235   /// @brief adds the attributes to the list of attributes.
236   void addAttributes(unsigned i, AttributeSet attrs);
237
238   /// @brief removes the attributes from the list of attributes.
239   void removeAttributes(unsigned i, AttributeSet attr);
240
241   /// @brief adds the dereferenceable attribute to the list of attributes.
242   void addDereferenceableAttr(unsigned i, uint64_t Bytes);
243
244   /// @brief adds the dereferenceable_or_null attribute to the list of
245   /// attributes.
246   void addDereferenceableOrNullAttr(unsigned i, uint64_t Bytes);
247
248   /// @brief Extract the alignment for a call or parameter (0=unknown).
249   unsigned getParamAlignment(unsigned i) const {
250     return AttributeSets.getParamAlignment(i);
251   }
252
253   /// @brief Extract the number of dereferenceable bytes for a call or
254   /// parameter (0=unknown).
255   uint64_t getDereferenceableBytes(unsigned i) const {
256     return AttributeSets.getDereferenceableBytes(i);
257   }
258
259   /// @brief Extract the number of dereferenceable_or_null bytes for a call or
260   /// parameter (0=unknown).
261   uint64_t getDereferenceableOrNullBytes(unsigned i) const {
262     return AttributeSets.getDereferenceableOrNullBytes(i);
263   }
264
265   /// @brief Determine if the function does not access memory.
266   bool doesNotAccessMemory() const {
267     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
268                                       Attribute::ReadNone);
269   }
270   void setDoesNotAccessMemory() {
271     addFnAttr(Attribute::ReadNone);
272   }
273
274   /// @brief Determine if the function does not access or only reads memory.
275   bool onlyReadsMemory() const {
276     return doesNotAccessMemory() ||
277       AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
278                                  Attribute::ReadOnly);
279   }
280   void setOnlyReadsMemory() {
281     addFnAttr(Attribute::ReadOnly);
282   }
283
284   /// @brief Determine if the call can access memmory only using pointers based
285   /// on its arguments.
286   bool onlyAccessesArgMemory() const {
287     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
288                                       Attribute::ArgMemOnly);
289   }
290   void setOnlyAccessesArgMemory() { addFnAttr(Attribute::ArgMemOnly); }
291
292   /// @brief Determine if the function cannot return.
293   bool doesNotReturn() const {
294     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
295                                       Attribute::NoReturn);
296   }
297   void setDoesNotReturn() {
298     addFnAttr(Attribute::NoReturn);
299   }
300
301   /// @brief Determine if the function cannot unwind.
302   bool doesNotThrow() const {
303     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
304                                       Attribute::NoUnwind);
305   }
306   void setDoesNotThrow() {
307     addFnAttr(Attribute::NoUnwind);
308   }
309
310   /// @brief Determine if the call cannot be duplicated.
311   bool cannotDuplicate() const {
312     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
313                                       Attribute::NoDuplicate);
314   }
315   void setCannotDuplicate() {
316     addFnAttr(Attribute::NoDuplicate);
317   }
318
319   /// @brief Determine if the call is convergent.
320   bool isConvergent() const {
321     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
322                                       Attribute::Convergent);
323   }
324   void setConvergent() {
325     addFnAttr(Attribute::Convergent);
326   }
327
328
329   /// @brief True if the ABI mandates (or the user requested) that this
330   /// function be in a unwind table.
331   bool hasUWTable() const {
332     return AttributeSets.hasAttribute(AttributeSet::FunctionIndex,
333                                       Attribute::UWTable);
334   }
335   void setHasUWTable() {
336     addFnAttr(Attribute::UWTable);
337   }
338
339   /// @brief True if this function needs an unwind table.
340   bool needsUnwindTableEntry() const {
341     return hasUWTable() || !doesNotThrow();
342   }
343
344   /// @brief Determine if the function returns a structure through first
345   /// pointer argument.
346   bool hasStructRetAttr() const {
347     return AttributeSets.hasAttribute(1, Attribute::StructRet) ||
348            AttributeSets.hasAttribute(2, Attribute::StructRet);
349   }
350
351   /// @brief Determine if the parameter or return value is marked with NoAlias
352   /// attribute.
353   /// @param n The parameter to check. 1 is the first parameter, 0 is the return
354   bool doesNotAlias(unsigned n) const {
355     return AttributeSets.hasAttribute(n, Attribute::NoAlias);
356   }
357   void setDoesNotAlias(unsigned n) {
358     addAttribute(n, Attribute::NoAlias);
359   }
360
361   /// @brief Determine if the parameter can be captured.
362   /// @param n The parameter to check. 1 is the first parameter, 0 is the return
363   bool doesNotCapture(unsigned n) const {
364     return AttributeSets.hasAttribute(n, Attribute::NoCapture);
365   }
366   void setDoesNotCapture(unsigned n) {
367     addAttribute(n, Attribute::NoCapture);
368   }
369
370   bool doesNotAccessMemory(unsigned n) const {
371     return AttributeSets.hasAttribute(n, Attribute::ReadNone);
372   }
373   void setDoesNotAccessMemory(unsigned n) {
374     addAttribute(n, Attribute::ReadNone);
375   }
376
377   bool onlyReadsMemory(unsigned n) const {
378     return doesNotAccessMemory(n) ||
379       AttributeSets.hasAttribute(n, Attribute::ReadOnly);
380   }
381   void setOnlyReadsMemory(unsigned n) {
382     addAttribute(n, Attribute::ReadOnly);
383   }
384
385   /// Optimize this function for minimum size (-Oz).
386   bool optForMinSize() const { return hasFnAttribute(Attribute::MinSize); };
387
388   /// Optimize this function for size (-Os) or minimum size (-Oz).
389   bool optForSize() const {
390     return hasFnAttribute(Attribute::OptimizeForSize) || optForMinSize();
391   }
392
393   /// copyAttributesFrom - copy all additional attributes (those not needed to
394   /// create a Function) from the Function Src to this one.
395   void copyAttributesFrom(const GlobalValue *Src) override;
396
397   /// deleteBody - This method deletes the body of the function, and converts
398   /// the linkage to external.
399   ///
400   void deleteBody() {
401     dropAllReferences();
402     setLinkage(ExternalLinkage);
403   }
404
405   /// removeFromParent - This method unlinks 'this' from the containing module,
406   /// but does not delete it.
407   ///
408   void removeFromParent() override;
409
410   /// eraseFromParent - This method unlinks 'this' from the containing module
411   /// and deletes it.
412   ///
413   void eraseFromParent() override;
414
415   /// Get the underlying elements of the Function... the basic block list is
416   /// empty for external functions.
417   ///
418   const ArgumentListType &getArgumentList() const {
419     CheckLazyArguments();
420     return ArgumentList;
421   }
422   ArgumentListType &getArgumentList() {
423     CheckLazyArguments();
424     return ArgumentList;
425   }
426   static ArgumentListType Function::*getSublistAccess(Argument*) {
427     return &Function::ArgumentList;
428   }
429
430   const BasicBlockListType &getBasicBlockList() const { return BasicBlocks; }
431         BasicBlockListType &getBasicBlockList()       { return BasicBlocks; }
432   static BasicBlockListType Function::*getSublistAccess(BasicBlock*) {
433     return &Function::BasicBlocks;
434   }
435
436   const BasicBlock       &getEntryBlock() const   { return front(); }
437         BasicBlock       &getEntryBlock()         { return front(); }
438
439   //===--------------------------------------------------------------------===//
440   // Symbol Table Accessing functions...
441
442   /// getSymbolTable() - Return the symbol table...
443   ///
444   inline       ValueSymbolTable &getValueSymbolTable()       { return *SymTab; }
445   inline const ValueSymbolTable &getValueSymbolTable() const { return *SymTab; }
446
447   //===--------------------------------------------------------------------===//
448   // BasicBlock iterator forwarding functions
449   //
450   iterator                begin()       { return BasicBlocks.begin(); }
451   const_iterator          begin() const { return BasicBlocks.begin(); }
452   iterator                end  ()       { return BasicBlocks.end();   }
453   const_iterator          end  () const { return BasicBlocks.end();   }
454
455   size_t                   size() const { return BasicBlocks.size();  }
456   bool                    empty() const { return BasicBlocks.empty(); }
457   const BasicBlock       &front() const { return BasicBlocks.front(); }
458         BasicBlock       &front()       { return BasicBlocks.front(); }
459   const BasicBlock        &back() const { return BasicBlocks.back();  }
460         BasicBlock        &back()       { return BasicBlocks.back();  }
461
462 /// @name Function Argument Iteration
463 /// @{
464
465   arg_iterator arg_begin() {
466     CheckLazyArguments();
467     return ArgumentList.begin();
468   }
469   const_arg_iterator arg_begin() const {
470     CheckLazyArguments();
471     return ArgumentList.begin();
472   }
473   arg_iterator arg_end() {
474     CheckLazyArguments();
475     return ArgumentList.end();
476   }
477   const_arg_iterator arg_end() const {
478     CheckLazyArguments();
479     return ArgumentList.end();
480   }
481
482   iterator_range<arg_iterator> args() {
483     return iterator_range<arg_iterator>(arg_begin(), arg_end());
484   }
485
486   iterator_range<const_arg_iterator> args() const {
487     return iterator_range<const_arg_iterator>(arg_begin(), arg_end());
488   }
489
490 /// @}
491
492   size_t arg_size() const;
493   bool arg_empty() const;
494
495   bool hasPrefixData() const {
496     return getSubclassDataFromValue() & (1<<1);
497   }
498
499   Constant *getPrefixData() const;
500   void setPrefixData(Constant *PrefixData);
501
502   bool hasPrologueData() const {
503     return getSubclassDataFromValue() & (1<<2);
504   }
505
506   Constant *getPrologueData() const;
507   void setPrologueData(Constant *PrologueData);
508
509   /// viewCFG - This function is meant for use from the debugger.  You can just
510   /// say 'call F->viewCFG()' and a ghostview window should pop up from the
511   /// program, displaying the CFG of the current function with the code for each
512   /// basic block inside.  This depends on there being a 'dot' and 'gv' program
513   /// in your path.
514   ///
515   void viewCFG() const;
516
517   /// viewCFGOnly - This function is meant for use from the debugger.  It works
518   /// just like viewCFG, but it does not include the contents of basic blocks
519   /// into the nodes, just the label.  If you are only interested in the CFG
520   /// this can make the graph smaller.
521   ///
522   void viewCFGOnly() const;
523
524   /// Methods for support type inquiry through isa, cast, and dyn_cast:
525   static inline bool classof(const Value *V) {
526     return V->getValueID() == Value::FunctionVal;
527   }
528
529   /// dropAllReferences() - This method causes all the subinstructions to "let
530   /// go" of all references that they are maintaining.  This allows one to
531   /// 'delete' a whole module at a time, even though there may be circular
532   /// references... first all references are dropped, and all use counts go to
533   /// zero.  Then everything is deleted for real.  Note that no operations are
534   /// valid on an object that has "dropped all references", except operator
535   /// delete.
536   ///
537   /// Since no other object in the module can have references into the body of a
538   /// function, dropping all references deletes the entire body of the function,
539   /// including any contained basic blocks.
540   ///
541   void dropAllReferences();
542
543   /// hasAddressTaken - returns true if there are any uses of this function
544   /// other than direct calls or invokes to it, or blockaddress expressions.
545   /// Optionally passes back an offending user for diagnostic purposes.
546   ///
547   bool hasAddressTaken(const User** = nullptr) const;
548
549   /// isDefTriviallyDead - Return true if it is trivially safe to remove
550   /// this function definition from the module (because it isn't externally
551   /// visible, does not have its address taken, and has no callers).  To make
552   /// this more accurate, call removeDeadConstantUsers first.
553   bool isDefTriviallyDead() const;
554
555   /// callsFunctionThatReturnsTwice - Return true if the function has a call to
556   /// setjmp or other function that gcc recognizes as "returning twice".
557   bool callsFunctionThatReturnsTwice() const;
558
559   /// \brief Check if this has any metadata.
560   bool hasMetadata() const { return hasMetadataHashEntry(); }
561
562   /// \brief Get the current metadata attachment, if any.
563   ///
564   /// Returns \c nullptr if such an attachment is missing.
565   /// @{
566   MDNode *getMetadata(unsigned KindID) const;
567   MDNode *getMetadata(StringRef Kind) const;
568   /// @}
569
570   /// \brief Set a particular kind of metadata attachment.
571   ///
572   /// Sets the given attachment to \c MD, erasing it if \c MD is \c nullptr or
573   /// replacing it if it already exists.
574   /// @{
575   void setMetadata(unsigned KindID, MDNode *MD);
576   void setMetadata(StringRef Kind, MDNode *MD);
577   /// @}
578
579   /// \brief Get all current metadata attachments.
580   void
581   getAllMetadata(SmallVectorImpl<std::pair<unsigned, MDNode *>> &MDs) const;
582
583   /// \brief Drop metadata not in the given list.
584   ///
585   /// Drop all metadata from \c this not included in \c KnownIDs.
586   void dropUnknownMetadata(ArrayRef<unsigned> KnownIDs);
587
588   /// \brief Set the attached subprogram.
589   ///
590   /// Calls \a setMetadata() with \a LLVMContext::MD_dbg.
591   void setSubprogram(DISubprogram *SP);
592
593   /// \brief Get the attached subprogram.
594   ///
595   /// Calls \a getMetadata() with \a LLVMContext::MD_dbg and casts the result
596   /// to \a DISubprogram.
597   DISubprogram *getSubprogram() const;
598
599 private:
600   // Shadow Value::setValueSubclassData with a private forwarding method so that
601   // subclasses cannot accidentally use it.
602   void setValueSubclassData(unsigned short D) {
603     Value::setValueSubclassData(D);
604   }
605
606   bool hasMetadataHashEntry() const {
607     return getGlobalObjectSubClassData() & HasMetadataHashEntryBit;
608   }
609   void setHasMetadataHashEntry(bool HasEntry) {
610     setGlobalObjectBit(HasMetadataHashEntryBit, HasEntry);
611   }
612
613   void clearMetadata();
614 };
615
616 template <>
617 struct OperandTraits<Function> : public OptionalOperandTraits<Function> {};
618
619 DEFINE_TRANSPARENT_OPERAND_ACCESSORS(Function, Value)
620
621 } // End llvm namespace
622
623 #endif