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