LLVM  4.0.0
BasicBlockUtils.h
Go to the documentation of this file.
1 //===-- Transform/Utils/BasicBlockUtils.h - BasicBlock Utils ----*- 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 family of functions perform manipulations on basic blocks, and
11 // instructions contained within basic blocks.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_TRANSFORMS_UTILS_BASICBLOCKUTILS_H
16 #define LLVM_TRANSFORMS_UTILS_BASICBLOCKUTILS_H
17 
18 // FIXME: Move to this file: BasicBlock::removePredecessor, BB::splitBasicBlock
19 
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/IR/BasicBlock.h"
22 #include "llvm/IR/CFG.h"
23 #include "llvm/IR/InstrTypes.h"
24 #include <cassert>
25 
26 namespace llvm {
27 
28 class MemoryDependenceResults;
29 class DominatorTree;
30 class LoopInfo;
31 class Instruction;
32 class MDNode;
33 class ReturnInst;
34 class TargetLibraryInfo;
35 
36 /// Delete the specified block, which must have no predecessors.
37 void DeleteDeadBlock(BasicBlock *BB);
38 
39 /// We know that BB has one predecessor. If there are any single-entry PHI nodes
40 /// in it, fold them away. This handles the case when all entries to the PHI
41 /// nodes in a block are guaranteed equal, such as when the block has exactly
42 /// one predecessor.
44  MemoryDependenceResults *MemDep = nullptr);
45 
46 /// Examine each PHI in the given block and delete it if it is dead. Also
47 /// recursively delete any operands that become dead as a result. This includes
48 /// tracing the def-use list from the PHI to see if it is ultimately unused or
49 /// if it reaches an unused cycle. Return true if any PHIs were deleted.
50 bool DeleteDeadPHIs(BasicBlock *BB, const TargetLibraryInfo *TLI = nullptr);
51 
52 /// Attempts to merge a block into its predecessor, if possible. The return
53 /// value indicates success or failure.
54 bool MergeBlockIntoPredecessor(BasicBlock *BB, DominatorTree *DT = nullptr,
55  LoopInfo *LI = nullptr,
56  MemoryDependenceResults *MemDep = nullptr);
57 
58 /// Replace all uses of an instruction (specified by BI) with a value, then
59 /// remove and delete the original instruction.
61  BasicBlock::iterator &BI, Value *V);
62 
63 /// Replace the instruction specified by BI with the instruction specified by I.
64 /// Copies DebugLoc from BI to I, if I doesn't already have a DebugLoc. The
65 /// original instruction is deleted and BI is updated to point to the new
66 /// instruction.
68  BasicBlock::iterator &BI, Instruction *I);
69 
70 /// Replace the instruction specified by From with the instruction specified by
71 /// To. Copies DebugLoc from BI to I, if I doesn't already have a DebugLoc.
72 void ReplaceInstWithInst(Instruction *From, Instruction *To);
73 
74 /// Option class for critical edge splitting.
75 ///
76 /// This provides a builder interface for overriding the default options used
77 /// during critical edge splitting.
84 
86  LoopInfo *LI = nullptr)
89 
91  MergeIdenticalEdges = true;
92  return *this;
93  }
94 
96  DontDeleteUselessPHIs = true;
97  return *this;
98  }
99 
101  PreserveLCSSA = true;
102  return *this;
103  }
104 };
105 
106 /// If this edge is a critical edge, insert a new node to split the critical
107 /// edge. This will update the analyses passed in through the option struct.
108 /// This returns the new block if the edge was split, null otherwise.
109 ///
110 /// If MergeIdenticalEdges in the options struct is true (not the default),
111 /// *all* edges from TI to the specified successor will be merged into the same
112 /// critical edge block. This is most commonly interesting with switch
113 /// instructions, which may have many edges to any one destination. This
114 /// ensures that all edges to that dest go to one block instead of each going
115 /// to a different block, but isn't the standard definition of a "critical
116 /// edge".
117 ///
118 /// It is invalid to call this function on a critical edge that starts at an
119 /// IndirectBrInst. Splitting these edges will almost always create an invalid
120 /// program because the address of the new block won't be the one that is jumped
121 /// to.
122 ///
123 BasicBlock *SplitCriticalEdge(TerminatorInst *TI, unsigned SuccNum,
124  const CriticalEdgeSplittingOptions &Options =
125  CriticalEdgeSplittingOptions());
126 
127 inline BasicBlock *
129  const CriticalEdgeSplittingOptions &Options =
132  Options);
133 }
134 
135 /// If the edge from *PI to BB is not critical, return false. Otherwise, split
136 /// all edges between the two blocks and return true. This updates all of the
137 /// same analyses as the other SplitCriticalEdge function. If P is specified, it
138 /// updates the analyses described above.
140  const CriticalEdgeSplittingOptions &Options =
142  bool MadeChange = false;
143  TerminatorInst *TI = (*PI)->getTerminator();
144  for (unsigned i = 0, e = TI->getNumSuccessors(); i != e; ++i)
145  if (TI->getSuccessor(i) == Succ)
146  MadeChange |= !!SplitCriticalEdge(TI, i, Options);
147  return MadeChange;
148 }
149 
150 /// If an edge from Src to Dst is critical, split the edge and return true,
151 /// otherwise return false. This method requires that there be an edge between
152 /// the two blocks. It updates the analyses passed in the options struct
153 inline BasicBlock *
155  const CriticalEdgeSplittingOptions &Options =
157  TerminatorInst *TI = Src->getTerminator();
158  unsigned i = 0;
159  while (true) {
160  assert(i != TI->getNumSuccessors() && "Edge doesn't exist!");
161  if (TI->getSuccessor(i) == Dst)
162  return SplitCriticalEdge(TI, i, Options);
163  ++i;
164  }
165 }
166 
167 /// Loop over all of the edges in the CFG, breaking critical edges as they are
168 /// found. Returns the number of broken edges.
169 unsigned SplitAllCriticalEdges(Function &F,
170  const CriticalEdgeSplittingOptions &Options =
171  CriticalEdgeSplittingOptions());
172 
173 /// Split the edge connecting specified block.
175  DominatorTree *DT = nullptr, LoopInfo *LI = nullptr);
176 
177 /// Split the specified block at the specified instruction - everything before
178 /// SplitPt stays in Old and everything starting with SplitPt moves to a new
179 /// block. The two blocks are joined by an unconditional branch and the loop
180 /// info is updated.
181 BasicBlock *SplitBlock(BasicBlock *Old, Instruction *SplitPt,
182  DominatorTree *DT = nullptr, LoopInfo *LI = nullptr);
183 
184 /// This method introduces at least one new basic block into the function and
185 /// moves some of the predecessors of BB to be predecessors of the new block.
186 /// The new predecessors are indicated by the Preds array. The new block is
187 /// given a suffix of 'Suffix'. Returns new basic block to which predecessors
188 /// from Preds are now pointing.
189 ///
190 /// If BB is a landingpad block then additional basicblock might be introduced.
191 /// It will have Suffix+".split_lp". See SplitLandingPadPredecessors for more
192 /// details on this case.
193 ///
194 /// This currently updates the LLVM IR, DominatorTree, LoopInfo, and LCCSA but
195 /// no other analyses. In particular, it does not preserve LoopSimplify
196 /// (because it's complicated to handle the case where one of the edges being
197 /// split is an exit of a loop with other exits).
198 ///
199 BasicBlock *SplitBlockPredecessors(BasicBlock *BB, ArrayRef<BasicBlock *> Preds,
200  const char *Suffix,
201  DominatorTree *DT = nullptr,
202  LoopInfo *LI = nullptr,
203  bool PreserveLCSSA = false);
204 
205 /// This method transforms the landing pad, OrigBB, by introducing two new basic
206 /// blocks into the function. One of those new basic blocks gets the
207 /// predecessors listed in Preds. The other basic block gets the remaining
208 /// predecessors of OrigBB. The landingpad instruction OrigBB is clone into both
209 /// of the new basic blocks. The new blocks are given the suffixes 'Suffix1' and
210 /// 'Suffix2', and are returned in the NewBBs vector.
211 ///
212 /// This currently updates the LLVM IR, DominatorTree, LoopInfo, and LCCSA but
213 /// no other analyses. In particular, it does not preserve LoopSimplify
214 /// (because it's complicated to handle the case where one of the edges being
215 /// split is an exit of a loop with other exits).
216 ///
218  ArrayRef<BasicBlock *> Preds,
219  const char *Suffix, const char *Suffix2,
220  SmallVectorImpl<BasicBlock *> &NewBBs,
221  DominatorTree *DT = nullptr,
222  LoopInfo *LI = nullptr,
223  bool PreserveLCSSA = false);
224 
225 /// This method duplicates the specified return instruction into a predecessor
226 /// which ends in an unconditional branch. If the return instruction returns a
227 /// value defined by a PHI, propagate the right value into the return. It
228 /// returns the new return instruction in the predecessor.
229 ReturnInst *FoldReturnIntoUncondBranch(ReturnInst *RI, BasicBlock *BB,
230  BasicBlock *Pred);
231 
232 /// Split the containing block at the specified instruction - everything before
233 /// SplitBefore stays in the old basic block, and the rest of the instructions
234 /// in the BB are moved to a new block. The two blocks are connected by a
235 /// conditional branch (with value of Cmp being the condition).
236 /// Before:
237 /// Head
238 /// SplitBefore
239 /// Tail
240 /// After:
241 /// Head
242 /// if (Cond)
243 /// ThenBlock
244 /// SplitBefore
245 /// Tail
246 ///
247 /// If Unreachable is true, then ThenBlock ends with
248 /// UnreachableInst, otherwise it branches to Tail.
249 /// Returns the NewBasicBlock's terminator.
250 ///
251 /// Updates DT and LI if given.
252 TerminatorInst *SplitBlockAndInsertIfThen(Value *Cond, Instruction *SplitBefore,
253  bool Unreachable,
254  MDNode *BranchWeights = nullptr,
255  DominatorTree *DT = nullptr,
256  LoopInfo *LI = nullptr);
257 
258 /// SplitBlockAndInsertIfThenElse is similar to SplitBlockAndInsertIfThen,
259 /// but also creates the ElseBlock.
260 /// Before:
261 /// Head
262 /// SplitBefore
263 /// Tail
264 /// After:
265 /// Head
266 /// if (Cond)
267 /// ThenBlock
268 /// else
269 /// ElseBlock
270 /// SplitBefore
271 /// Tail
272 void SplitBlockAndInsertIfThenElse(Value *Cond, Instruction *SplitBefore,
273  TerminatorInst **ThenTerm,
274  TerminatorInst **ElseTerm,
275  MDNode *BranchWeights = nullptr);
276 
277 /// Check whether BB is the merge point of a if-region.
278 /// If so, return the boolean condition that determines which entry into
279 /// BB will be taken. Also, return by references the block that will be
280 /// entered from if the condition is true, and the block that will be
281 /// entered if the condition is false.
282 ///
283 /// This does no checking to see if the true/false blocks have large or unsavory
284 /// instructions in them.
285 Value *GetIfCondition(BasicBlock *BB, BasicBlock *&IfTrue,
286  BasicBlock *&IfFalse);
287 
288 } // end namespace llvm
289 
290 #endif // LLVM_TRANSFORMS_UTILS_BASICBLOCKUTILS_H
void ReplaceInstWithInst(BasicBlock::InstListType &BIL, BasicBlock::iterator &BI, Instruction *I)
Replace the instruction specified by BI with the instruction specified by I.
void SplitBlockAndInsertIfThenElse(Value *Cond, Instruction *SplitBefore, TerminatorInst **ThenTerm, TerminatorInst **ElseTerm, MDNode *BranchWeights=nullptr)
SplitBlockAndInsertIfThenElse is similar to SplitBlockAndInsertIfThen, but also creates the ElseBlock...
size_t i
BasicBlock * SplitBlock(BasicBlock *Old, Instruction *SplitPt, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr)
Split the specified block at the specified instruction - everything before SplitPt stays in Old and e...
Various leaf nodes.
Definition: ISDOpcodes.h:60
void DeleteDeadBlock(BasicBlock *BB)
Delete the specified block, which must have no predecessors.
unsigned SplitAllCriticalEdges(Function &F, const CriticalEdgeSplittingOptions &Options=CriticalEdgeSplittingOptions())
Loop over all of the edges in the CFG, breaking critical edges as they are found. ...
Option class for critical edge splitting.
#define F(x, y, z)
Definition: MD5.cpp:51
Function Alias Analysis false
bool DeleteDeadPHIs(BasicBlock *BB, const TargetLibraryInfo *TLI=nullptr)
Examine each PHI in the given block and delete it if it is dead.
void ReplaceInstWithValue(BasicBlock::InstListType &BIL, BasicBlock::iterator &BI, Value *V)
Replace all uses of an instruction (specified by BI) with a value, then remove and delete the origina...
Concrete subclass of DominatorTreeBase that is used to compute a normal dominator tree...
Definition: Dominators.h:96
unsigned getNumSuccessors() const
Return the number of successors that this terminator has.
Definition: InstrTypes.h:74
BasicBlock * SplitCriticalEdge(TerminatorInst *TI, unsigned SuccNum, const CriticalEdgeSplittingOptions &Options=CriticalEdgeSplittingOptions())
If this edge is a critical edge, insert a new node to split the critical edge.
CriticalEdgeSplittingOptions & setMergeIdenticalEdges()
SymbolTableList< Instruction > InstListType
Definition: BasicBlock.h:54
Subclasses of this class are all able to terminate a basic block.
Definition: InstrTypes.h:52
LLVM Basic Block Representation.
Definition: BasicBlock.h:51
BasicBlock * getSuccessor(unsigned idx) const
Return the specified successor.
Definition: InstrTypes.h:79
void SplitLandingPadPredecessors(BasicBlock *OrigBB, ArrayRef< BasicBlock * > Preds, const char *Suffix, const char *Suffix2, SmallVectorImpl< BasicBlock * > &NewBBs, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr, bool PreserveLCSSA=false)
This method transforms the landing pad, OrigBB, by introducing two new basic blocks into the function...
Value * GetIfCondition(BasicBlock *BB, BasicBlock *&IfTrue, BasicBlock *&IfFalse)
Check whether BB is the merge point of a if-region.
TerminatorInst * SplitBlockAndInsertIfThen(Value *Cond, Instruction *SplitBefore, bool Unreachable, MDNode *BranchWeights=nullptr, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr)
Split the containing block at the specified instruction - everything before SplitBefore stays in the ...
CriticalEdgeSplittingOptions & setPreserveLCSSA()
CriticalEdgeSplittingOptions(DominatorTree *DT=nullptr, LoopInfo *LI=nullptr)
void FoldSingleEntryPHINodes(BasicBlock *BB, MemoryDependenceResults *MemDep=nullptr)
We know that BB has one predecessor.
bool MergeBlockIntoPredecessor(BasicBlock *BB, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr, MemoryDependenceResults *MemDep=nullptr)
Attempts to merge a block into its predecessor, if possible.
#define I(x, y, z)
Definition: MD5.cpp:54
TerminatorInst * getTerminator()
Returns the terminator instruction if the block is well formed or null if the block is not well forme...
Definition: BasicBlock.cpp:124
ReturnInst * FoldReturnIntoUncondBranch(ReturnInst *RI, BasicBlock *BB, BasicBlock *Pred)
This method duplicates the specified return instruction into a predecessor which ends in an unconditi...
BasicBlock * SplitBlockPredecessors(BasicBlock *BB, ArrayRef< BasicBlock * > Preds, const char *Suffix, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr, bool PreserveLCSSA=false)
This method introduces at least one new basic block into the function and moves some of the predecess...
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
CriticalEdgeSplittingOptions & setDontDeleteUselessPHIs()
unsigned getSuccessorIndex() const
This is used to interface between code that wants to operate on terminator instructions directly...
Definition: InstrTypes.h:174
BasicBlock * SplitEdge(BasicBlock *From, BasicBlock *To, DominatorTree *DT=nullptr, LoopInfo *LI=nullptr)
Split the edge connecting specified block.
InstListType::iterator iterator
Instruction iterators...
Definition: BasicBlock.h:83