1 //===-- UnrollLoopRuntime.cpp - Runtime Loop unrolling utilities ----------===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 // This file implements some loop unrolling utilities for loops with run-time
10 // trip counts. See LoopUnroll.cpp for unrolling loops with compile-time
13 // The functions in this file are used to generate extra code when the
14 // run-time trip count modulo the unroll factor is not 0. When this is the
15 // case, we need to generate code to execute these 'left over' iterations.
17 // The current strategy generates an if-then-else sequence prior to the
18 // unrolled loop to execute the 'left over' iterations before or after the
21 //===----------------------------------------------------------------------===//
23 #include "llvm/ADT/SmallPtrSet.h"
24 #include "llvm/ADT/Statistic.h"
25 #include "llvm/Analysis/AliasAnalysis.h"
26 #include "llvm/Analysis/LoopIterator.h"
27 #include "llvm/Analysis/ScalarEvolution.h"
28 #include "llvm/IR/BasicBlock.h"
29 #include "llvm/IR/Dominators.h"
30 #include "llvm/IR/Metadata.h"
31 #include "llvm/IR/Module.h"
32 #include "llvm/Support/CommandLine.h"
33 #include "llvm/Support/Debug.h"
34 #include "llvm/Support/raw_ostream.h"
35 #include "llvm/Transforms/Utils.h"
36 #include "llvm/Transforms/Utils/BasicBlockUtils.h"
37 #include "llvm/Transforms/Utils/Cloning.h"
38 #include "llvm/Transforms/Utils/LoopUtils.h"
39 #include "llvm/Transforms/Utils/ScalarEvolutionExpander.h"
40 #include "llvm/Transforms/Utils/UnrollLoop.h"
45 #define DEBUG_TYPE "loop-unroll"
47 STATISTIC(NumRuntimeUnrolled,
48 "Number of loops unrolled with run-time trip counts");
49 static cl::opt<bool> UnrollRuntimeMultiExit(
50 "unroll-runtime-multi-exit", cl::init(false), cl::Hidden,
51 cl::desc("Allow runtime unrolling for loops with multiple exits, when "
52 "epilog is generated"));
54 /// Connect the unrolling prolog code to the original loop.
55 /// The unrolling prolog code contains code to execute the
56 /// 'extra' iterations if the run-time trip count modulo the
57 /// unroll count is non-zero.
59 /// This function performs the following:
60 /// - Create PHI nodes at prolog end block to combine values
61 /// that exit the prolog code and jump around the prolog.
62 /// - Add a PHI operand to a PHI node at the loop exit block
63 /// for values that exit the prolog and go around the loop.
64 /// - Branch around the original loop if the trip count is less
65 /// than the unroll factor.
67 static void ConnectProlog(Loop *L, Value *BECount, unsigned Count,
68 BasicBlock *PrologExit,
69 BasicBlock *OriginalLoopLatchExit,
70 BasicBlock *PreHeader, BasicBlock *NewPreHeader,
71 ValueToValueMapTy &VMap, DominatorTree *DT,
72 LoopInfo *LI, bool PreserveLCSSA) {
73 // Loop structure should be the following:
84 BasicBlock *Latch = L->getLoopLatch();
85 assert(Latch && "Loop must have a latch");
86 BasicBlock *PrologLatch = cast<BasicBlock>(VMap[Latch]);
88 // Create a PHI node for each outgoing value from the original loop
89 // (which means it is an outgoing value from the prolog code too).
90 // The new PHI node is inserted in the prolog end basic block.
91 // The new PHI node value is added as an operand of a PHI node in either
92 // the loop header or the loop exit block.
93 for (BasicBlock *Succ : successors(Latch)) {
94 for (PHINode &PN : Succ->phis()) {
95 // Add a new PHI node to the prolog end block and add the
96 // appropriate incoming values.
97 // TODO: This code assumes that the PrologExit (or the LatchExit block for
98 // prolog loop) contains only one predecessor from the loop, i.e. the
99 // PrologLatch. When supporting multiple-exiting block loops, we can have
100 // two or more blocks that have the LatchExit as the target in the
102 PHINode *NewPN = PHINode::Create(PN.getType(), 2, PN.getName() + ".unr",
103 PrologExit->getFirstNonPHI());
104 // Adding a value to the new PHI node from the original loop preheader.
105 // This is the value that skips all the prolog code.
106 if (L->contains(&PN)) {
107 // Succ is loop header.
108 NewPN->addIncoming(PN.getIncomingValueForBlock(NewPreHeader),
111 // Succ is LatchExit.
112 NewPN->addIncoming(UndefValue::get(PN.getType()), PreHeader);
115 Value *V = PN.getIncomingValueForBlock(Latch);
116 if (Instruction *I = dyn_cast<Instruction>(V)) {
117 if (L->contains(I)) {
121 // Adding a value to the new PHI node from the last prolog block
123 NewPN->addIncoming(V, PrologLatch);
125 // Update the existing PHI node operand with the value from the
126 // new PHI node. How this is done depends on if the existing
127 // PHI node is in the original loop block, or the exit block.
128 if (L->contains(&PN))
129 PN.setIncomingValueForBlock(NewPreHeader, NewPN);
131 PN.addIncoming(NewPN, PrologExit);
135 // Make sure that created prolog loop is in simplified form
136 SmallVector<BasicBlock *, 4> PrologExitPreds;
137 Loop *PrologLoop = LI->getLoopFor(PrologLatch);
139 for (BasicBlock *PredBB : predecessors(PrologExit))
140 if (PrologLoop->contains(PredBB))
141 PrologExitPreds.push_back(PredBB);
143 SplitBlockPredecessors(PrologExit, PrologExitPreds, ".unr-lcssa", DT, LI,
144 nullptr, PreserveLCSSA);
147 // Create a branch around the original loop, which is taken if there are no
148 // iterations remaining to be executed after running the prologue.
149 Instruction *InsertPt = PrologExit->getTerminator();
150 IRBuilder<> B(InsertPt);
152 assert(Count != 0 && "nonsensical Count!");
154 // If BECount <u (Count - 1) then (BECount + 1) % Count == (BECount + 1)
155 // This means %xtraiter is (BECount + 1) and all of the iterations of this
156 // loop were executed by the prologue. Note that if BECount <u (Count - 1)
157 // then (BECount + 1) cannot unsigned-overflow.
159 B.CreateICmpULT(BECount, ConstantInt::get(BECount->getType(), Count - 1));
160 // Split the exit to maintain loop canonicalization guarantees
161 SmallVector<BasicBlock *, 4> Preds(predecessors(OriginalLoopLatchExit));
162 SplitBlockPredecessors(OriginalLoopLatchExit, Preds, ".unr-lcssa", DT, LI,
163 nullptr, PreserveLCSSA);
164 // Add the branch to the exit block (around the unrolled loop)
165 B.CreateCondBr(BrLoopExit, OriginalLoopLatchExit, NewPreHeader);
166 InsertPt->eraseFromParent();
168 DT->changeImmediateDominator(OriginalLoopLatchExit, PrologExit);
171 /// Connect the unrolling epilog code to the original loop.
172 /// The unrolling epilog code contains code to execute the
173 /// 'extra' iterations if the run-time trip count modulo the
174 /// unroll count is non-zero.
176 /// This function performs the following:
177 /// - Update PHI nodes at the unrolling loop exit and epilog loop exit
178 /// - Create PHI nodes at the unrolling loop exit to combine
179 /// values that exit the unrolling loop code and jump around it.
180 /// - Update PHI operands in the epilog loop by the new PHI nodes
181 /// - Branch around the epilog loop if extra iters (ModVal) is zero.
183 static void ConnectEpilog(Loop *L, Value *ModVal, BasicBlock *NewExit,
184 BasicBlock *Exit, BasicBlock *PreHeader,
185 BasicBlock *EpilogPreHeader, BasicBlock *NewPreHeader,
186 ValueToValueMapTy &VMap, DominatorTree *DT,
187 LoopInfo *LI, bool PreserveLCSSA) {
188 BasicBlock *Latch = L->getLoopLatch();
189 assert(Latch && "Loop must have a latch");
190 BasicBlock *EpilogLatch = cast<BasicBlock>(VMap[Latch]);
192 // Loop structure should be the following:
206 // Update PHI nodes at NewExit and Exit.
207 for (PHINode &PN : NewExit->phis()) {
208 // PN should be used in another PHI located in Exit block as
209 // Exit was split by SplitBlockPredecessors into Exit and NewExit
210 // Basicaly it should look like:
212 // PN = PHI [I, Latch]
215 // EpilogPN = PHI [PN, EpilogPreHeader]
217 // There is EpilogPreHeader incoming block instead of NewExit as
218 // NewExit was spilt 1 more time to get EpilogPreHeader.
219 assert(PN.hasOneUse() && "The phi should have 1 use");
220 PHINode *EpilogPN = cast<PHINode>(PN.use_begin()->getUser());
221 assert(EpilogPN->getParent() == Exit && "EpilogPN should be in Exit block");
223 // Add incoming PreHeader from branch around the Loop
224 PN.addIncoming(UndefValue::get(PN.getType()), PreHeader);
226 Value *V = PN.getIncomingValueForBlock(Latch);
227 Instruction *I = dyn_cast<Instruction>(V);
228 if (I && L->contains(I))
229 // If value comes from an instruction in the loop add VMap value.
231 // For the instruction out of the loop, constant or undefined value
232 // insert value itself.
233 EpilogPN->addIncoming(V, EpilogLatch);
235 assert(EpilogPN->getBasicBlockIndex(EpilogPreHeader) >= 0 &&
236 "EpilogPN should have EpilogPreHeader incoming block");
237 // Change EpilogPreHeader incoming block to NewExit.
238 EpilogPN->setIncomingBlock(EpilogPN->getBasicBlockIndex(EpilogPreHeader),
240 // Now PHIs should look like:
242 // PN = PHI [I, Latch], [undef, PreHeader]
245 // EpilogPN = PHI [PN, NewExit], [VMap[I], EpilogLatch]
248 // Create PHI nodes at NewExit (from the unrolling loop Latch and PreHeader).
249 // Update corresponding PHI nodes in epilog loop.
250 for (BasicBlock *Succ : successors(Latch)) {
251 // Skip this as we already updated phis in exit blocks.
252 if (!L->contains(Succ))
254 for (PHINode &PN : Succ->phis()) {
255 // Add new PHI nodes to the loop exit block and update epilog
256 // PHIs with the new PHI values.
257 PHINode *NewPN = PHINode::Create(PN.getType(), 2, PN.getName() + ".unr",
258 NewExit->getFirstNonPHI());
259 // Adding a value to the new PHI node from the unrolling loop preheader.
260 NewPN->addIncoming(PN.getIncomingValueForBlock(NewPreHeader), PreHeader);
261 // Adding a value to the new PHI node from the unrolling loop latch.
262 NewPN->addIncoming(PN.getIncomingValueForBlock(Latch), Latch);
264 // Update the existing PHI node operand with the value from the new PHI
265 // node. Corresponding instruction in epilog loop should be PHI.
266 PHINode *VPN = cast<PHINode>(VMap[&PN]);
267 VPN->setIncomingValueForBlock(EpilogPreHeader, NewPN);
271 Instruction *InsertPt = NewExit->getTerminator();
272 IRBuilder<> B(InsertPt);
273 Value *BrLoopExit = B.CreateIsNotNull(ModVal, "lcmp.mod");
274 assert(Exit && "Loop must have a single exit block only");
275 // Split the epilogue exit to maintain loop canonicalization guarantees
276 SmallVector<BasicBlock*, 4> Preds(predecessors(Exit));
277 SplitBlockPredecessors(Exit, Preds, ".epilog-lcssa", DT, LI, nullptr,
279 // Add the branch to the exit block (around the unrolling loop)
280 B.CreateCondBr(BrLoopExit, EpilogPreHeader, Exit);
281 InsertPt->eraseFromParent();
283 DT->changeImmediateDominator(Exit, NewExit);
285 // Split the main loop exit to maintain canonicalization guarantees.
286 SmallVector<BasicBlock*, 4> NewExitPreds{Latch};
287 SplitBlockPredecessors(NewExit, NewExitPreds, ".loopexit", DT, LI, nullptr,
291 /// Create a clone of the blocks in a loop and connect them together.
292 /// If CreateRemainderLoop is false, loop structure will not be cloned,
293 /// otherwise a new loop will be created including all cloned blocks, and the
294 /// iterator of it switches to count NewIter down to 0.
295 /// The cloned blocks should be inserted between InsertTop and InsertBot.
296 /// If loop structure is cloned InsertTop should be new preheader, InsertBot
298 /// Return the new cloned loop that is created when CreateRemainderLoop is true.
300 CloneLoopBlocks(Loop *L, Value *NewIter, const bool CreateRemainderLoop,
301 const bool UseEpilogRemainder, const bool UnrollRemainder,
302 BasicBlock *InsertTop,
303 BasicBlock *InsertBot, BasicBlock *Preheader,
304 std::vector<BasicBlock *> &NewBlocks, LoopBlocksDFS &LoopBlocks,
305 ValueToValueMapTy &VMap, DominatorTree *DT, LoopInfo *LI) {
306 StringRef suffix = UseEpilogRemainder ? "epil" : "prol";
307 BasicBlock *Header = L->getHeader();
308 BasicBlock *Latch = L->getLoopLatch();
309 Function *F = Header->getParent();
310 LoopBlocksDFS::RPOIterator BlockBegin = LoopBlocks.beginRPO();
311 LoopBlocksDFS::RPOIterator BlockEnd = LoopBlocks.endRPO();
312 Loop *ParentLoop = L->getParentLoop();
313 NewLoopsMap NewLoops;
314 NewLoops[ParentLoop] = ParentLoop;
315 if (!CreateRemainderLoop)
316 NewLoops[L] = ParentLoop;
318 // For each block in the original loop, create a new copy,
319 // and update the value map with the newly created values.
320 for (LoopBlocksDFS::RPOIterator BB = BlockBegin; BB != BlockEnd; ++BB) {
321 BasicBlock *NewBB = CloneBasicBlock(*BB, VMap, "." + suffix, F);
322 NewBlocks.push_back(NewBB);
324 // If we're unrolling the outermost loop, there's no remainder loop,
325 // and this block isn't in a nested loop, then the new block is not
326 // in any loop. Otherwise, add it to loopinfo.
327 if (CreateRemainderLoop || LI->getLoopFor(*BB) != L || ParentLoop)
328 addClonedBlockToLoopInfo(*BB, NewBB, LI, NewLoops);
332 // For the first block, add a CFG connection to this newly
334 InsertTop->getTerminator()->setSuccessor(0, NewBB);
339 // The header is dominated by the preheader.
340 DT->addNewBlock(NewBB, InsertTop);
342 // Copy information from original loop to unrolled loop.
343 BasicBlock *IDomBB = DT->getNode(*BB)->getIDom()->getBlock();
344 DT->addNewBlock(NewBB, cast<BasicBlock>(VMap[IDomBB]));
349 // For the last block, if CreateRemainderLoop is false, create a direct
350 // jump to InsertBot. If not, create a loop back to cloned head.
351 VMap.erase((*BB)->getTerminator());
352 BasicBlock *FirstLoopBB = cast<BasicBlock>(VMap[Header]);
353 BranchInst *LatchBR = cast<BranchInst>(NewBB->getTerminator());
354 IRBuilder<> Builder(LatchBR);
355 if (!CreateRemainderLoop) {
356 Builder.CreateBr(InsertBot);
358 PHINode *NewIdx = PHINode::Create(NewIter->getType(), 2,
360 FirstLoopBB->getFirstNonPHI());
362 Builder.CreateSub(NewIdx, ConstantInt::get(NewIdx->getType(), 1),
363 NewIdx->getName() + ".sub");
365 Builder.CreateIsNotNull(IdxSub, NewIdx->getName() + ".cmp");
366 Builder.CreateCondBr(IdxCmp, FirstLoopBB, InsertBot);
367 NewIdx->addIncoming(NewIter, InsertTop);
368 NewIdx->addIncoming(IdxSub, NewBB);
370 LatchBR->eraseFromParent();
374 // Change the incoming values to the ones defined in the preheader or
376 for (BasicBlock::iterator I = Header->begin(); isa<PHINode>(I); ++I) {
377 PHINode *NewPHI = cast<PHINode>(VMap[&*I]);
378 if (!CreateRemainderLoop) {
379 if (UseEpilogRemainder) {
380 unsigned idx = NewPHI->getBasicBlockIndex(Preheader);
381 NewPHI->setIncomingBlock(idx, InsertTop);
382 NewPHI->removeIncomingValue(Latch, false);
384 VMap[&*I] = NewPHI->getIncomingValueForBlock(Preheader);
385 cast<BasicBlock>(VMap[Header])->getInstList().erase(NewPHI);
388 unsigned idx = NewPHI->getBasicBlockIndex(Preheader);
389 NewPHI->setIncomingBlock(idx, InsertTop);
390 BasicBlock *NewLatch = cast<BasicBlock>(VMap[Latch]);
391 idx = NewPHI->getBasicBlockIndex(Latch);
392 Value *InVal = NewPHI->getIncomingValue(idx);
393 NewPHI->setIncomingBlock(idx, NewLatch);
394 if (Value *V = VMap.lookup(InVal))
395 NewPHI->setIncomingValue(idx, V);
398 if (CreateRemainderLoop) {
399 Loop *NewLoop = NewLoops[L];
400 assert(NewLoop && "L should have been cloned");
401 MDNode *LoopID = NewLoop->getLoopID();
403 // Only add loop metadata if the loop is not going to be completely
408 Optional<MDNode *> NewLoopID = makeFollowupLoopID(
409 LoopID, {LLVMLoopUnrollFollowupAll, LLVMLoopUnrollFollowupRemainder});
410 if (NewLoopID.hasValue()) {
411 NewLoop->setLoopID(NewLoopID.getValue());
413 // Do not setLoopAlreadyUnrolled if loop attributes have been defined
418 // Add unroll disable metadata to disable future unrolling for this loop.
419 NewLoop->setLoopAlreadyUnrolled();
426 /// Returns true if we can safely unroll a multi-exit/exiting loop. OtherExits
427 /// is populated with all the loop exit blocks other than the LatchExit block.
428 static bool canSafelyUnrollMultiExitLoop(Loop *L, BasicBlock *LatchExit,
430 bool UseEpilogRemainder) {
432 // We currently have some correctness constrains in unrolling a multi-exit
433 // loop. Check for these below.
435 // We rely on LCSSA form being preserved when the exit blocks are transformed.
439 // TODO: Support multiple exiting blocks jumping to the `LatchExit` when
440 // UnrollRuntimeMultiExit is true. This will need updating the logic in
441 // connectEpilog/connectProlog.
442 if (!LatchExit->getSinglePredecessor()) {
444 dbgs() << "Bailout for multi-exit handling when latch exit has >1 "
448 // FIXME: We bail out of multi-exit unrolling when epilog loop is generated
449 // and L is an inner loop. This is because in presence of multiple exits, the
450 // outer loop is incorrect: we do not add the EpilogPreheader and exit to the
451 // outer loop. This is automatically handled in the prolog case, so we do not
452 // have that bug in prolog generation.
453 if (UseEpilogRemainder && L->getParentLoop())
456 // All constraints have been satisfied.
460 /// Returns true if we can profitably unroll the multi-exit loop L. Currently,
461 /// we return true only if UnrollRuntimeMultiExit is set to true.
462 static bool canProfitablyUnrollMultiExitLoop(
463 Loop *L, SmallVectorImpl<BasicBlock *> &OtherExits, BasicBlock *LatchExit,
464 bool PreserveLCSSA, bool UseEpilogRemainder) {
467 assert(canSafelyUnrollMultiExitLoop(L, LatchExit, PreserveLCSSA,
468 UseEpilogRemainder) &&
469 "Should be safe to unroll before checking profitability!");
472 // Priority goes to UnrollRuntimeMultiExit if it's supplied.
473 if (UnrollRuntimeMultiExit.getNumOccurrences())
474 return UnrollRuntimeMultiExit;
476 // The main pain point with multi-exit loop unrolling is that once unrolled,
477 // we will not be able to merge all blocks into a straight line code.
478 // There are branches within the unrolled loop that go to the OtherExits.
479 // The second point is the increase in code size, but this is true
480 // irrespective of multiple exits.
482 // Note: Both the heuristics below are coarse grained. We are essentially
483 // enabling unrolling of loops that have a single side exit other than the
484 // normal LatchExit (i.e. exiting into a deoptimize block).
485 // The heuristics considered are:
486 // 1. low number of branches in the unrolled version.
487 // 2. high predictability of these extra branches.
488 // We avoid unrolling loops that have more than two exiting blocks. This
489 // limits the total number of branches in the unrolled loop to be atmost
490 // the unroll factor (since one of the exiting blocks is the latch block).
491 SmallVector<BasicBlock*, 4> ExitingBlocks;
492 L->getExitingBlocks(ExitingBlocks);
493 if (ExitingBlocks.size() > 2)
496 // The second heuristic is that L has one exit other than the latchexit and
497 // that exit is a deoptimize block. We know that deoptimize blocks are rarely
498 // taken, which also implies the branch leading to the deoptimize block is
499 // highly predictable.
500 return (OtherExits.size() == 1 &&
501 OtherExits[0]->getTerminatingDeoptimizeCall());
502 // TODO: These can be fine-tuned further to consider code size or deopt states
503 // that are captured by the deoptimize exit block.
504 // Also, we can extend this to support more cases, if we actually
505 // know of kinds of multiexit loops that would benefit from unrolling.
508 /// Insert code in the prolog/epilog code when unrolling a loop with a
509 /// run-time trip-count.
511 /// This method assumes that the loop unroll factor is total number
512 /// of loop bodies in the loop after unrolling. (Some folks refer
513 /// to the unroll factor as the number of *extra* copies added).
514 /// We assume also that the loop unroll factor is a power-of-two. So, after
515 /// unrolling the loop, the number of loop bodies executed is 2,
516 /// 4, 8, etc. Note - LLVM converts the if-then-sequence to a switch
517 /// instruction in SimplifyCFG.cpp. Then, the backend decides how code for
518 /// the switch instruction is generated.
520 /// ***Prolog case***
521 /// extraiters = tripcount % loopfactor
522 /// if (extraiters == 0) jump Loop:
525 /// extraiters -= 1 // Omitted if unroll factor is 2.
526 /// if (extraiters != 0) jump Prol: // Omitted if unroll factor is 2.
527 /// if (tripcount < loopfactor) jump End:
532 /// ***Epilog case***
533 /// extraiters = tripcount % loopfactor
534 /// if (tripcount < loopfactor) jump LoopExit:
535 /// unroll_iters = tripcount - extraiters
536 /// Loop: LoopBody; (executes unroll_iter times);
538 /// if (unroll_iter != 0) jump Loop:
540 /// if (extraiters == 0) jump EpilExit:
541 /// Epil: LoopBody; (executes extraiters times)
542 /// extraiters -= 1 // Omitted if unroll factor is 2.
543 /// if (extraiters != 0) jump Epil: // Omitted if unroll factor is 2.
546 bool llvm::UnrollRuntimeLoopRemainder(
547 Loop *L, unsigned Count, bool AllowExpensiveTripCount,
548 bool UseEpilogRemainder, bool UnrollRemainder, bool ForgetAllSCEV,
549 LoopInfo *LI, ScalarEvolution *SE, DominatorTree *DT, AssumptionCache *AC,
550 const TargetTransformInfo *TTI, bool PreserveLCSSA, Loop **ResultLoop) {
551 LLVM_DEBUG(dbgs() << "Trying runtime unrolling on Loop: \n");
552 LLVM_DEBUG(L->dump());
553 LLVM_DEBUG(UseEpilogRemainder ? dbgs() << "Using epilog remainder.\n"
554 : dbgs() << "Using prolog remainder.\n");
556 // Make sure the loop is in canonical form.
557 if (!L->isLoopSimplifyForm()) {
558 LLVM_DEBUG(dbgs() << "Not in simplify form!\n");
562 // Guaranteed by LoopSimplifyForm.
563 BasicBlock *Latch = L->getLoopLatch();
564 BasicBlock *Header = L->getHeader();
566 BranchInst *LatchBR = cast<BranchInst>(Latch->getTerminator());
568 if (!LatchBR || LatchBR->isUnconditional()) {
569 // The loop-rotate pass can be helpful to avoid this in many cases.
572 << "Loop latch not terminated by a conditional branch.\n");
576 unsigned ExitIndex = LatchBR->getSuccessor(0) == Header ? 1 : 0;
577 BasicBlock *LatchExit = LatchBR->getSuccessor(ExitIndex);
579 if (L->contains(LatchExit)) {
580 // Cloning the loop basic blocks (`CloneLoopBlocks`) requires that one of the
581 // targets of the Latch be an exit block out of the loop.
584 << "One of the loop latch successors must be the exit block.\n");
588 // These are exit blocks other than the target of the latch exiting block.
589 SmallVector<BasicBlock *, 4> OtherExits;
590 L->getUniqueNonLatchExitBlocks(OtherExits);
591 bool isMultiExitUnrollingEnabled =
592 canSafelyUnrollMultiExitLoop(L, LatchExit, PreserveLCSSA,
593 UseEpilogRemainder) &&
594 canProfitablyUnrollMultiExitLoop(L, OtherExits, LatchExit, PreserveLCSSA,
596 // Support only single exit and exiting block unless multi-exit loop unrolling is enabled.
597 if (!isMultiExitUnrollingEnabled &&
598 (!L->getExitingBlock() || OtherExits.size())) {
601 << "Multiple exit/exiting blocks in loop and multi-exit unrolling not "
605 // Use Scalar Evolution to compute the trip count. This allows more loops to
606 // be unrolled than relying on induction var simplification.
610 // Only unroll loops with a computable trip count, and the trip count needs
611 // to be an int value (allowing a pointer type is a TODO item).
612 // We calculate the backedge count by using getExitCount on the Latch block,
613 // which is proven to be the only exiting block in this loop. This is same as
614 // calculating getBackedgeTakenCount on the loop (which computes SCEV for all
616 const SCEV *BECountSC = SE->getExitCount(L, Latch);
617 if (isa<SCEVCouldNotCompute>(BECountSC) ||
618 !BECountSC->getType()->isIntegerTy()) {
619 LLVM_DEBUG(dbgs() << "Could not compute exit block SCEV\n");
623 unsigned BEWidth = cast<IntegerType>(BECountSC->getType())->getBitWidth();
625 // Add 1 since the backedge count doesn't include the first loop iteration.
626 const SCEV *TripCountSC =
627 SE->getAddExpr(BECountSC, SE->getConstant(BECountSC->getType(), 1));
628 if (isa<SCEVCouldNotCompute>(TripCountSC)) {
629 LLVM_DEBUG(dbgs() << "Could not compute trip count SCEV.\n");
633 BasicBlock *PreHeader = L->getLoopPreheader();
634 BranchInst *PreHeaderBR = cast<BranchInst>(PreHeader->getTerminator());
635 const DataLayout &DL = Header->getModule()->getDataLayout();
636 SCEVExpander Expander(*SE, DL, "loop-unroll");
637 if (!AllowExpensiveTripCount &&
638 Expander.isHighCostExpansion(TripCountSC, L, SCEVCheapExpansionBudget,
640 LLVM_DEBUG(dbgs() << "High cost for expanding trip count scev!\n");
644 // This constraint lets us deal with an overflowing trip count easily; see the
645 // comment on ModVal below.
646 if (Log2_32(Count) > BEWidth) {
649 << "Count failed constraint on overflow trip count calculation.\n");
653 // Loop structure is the following:
661 BasicBlock *NewPreHeader;
662 BasicBlock *NewExit = nullptr;
663 BasicBlock *PrologExit = nullptr;
664 BasicBlock *EpilogPreHeader = nullptr;
665 BasicBlock *PrologPreHeader = nullptr;
667 if (UseEpilogRemainder) {
668 // If epilog remainder
669 // Split PreHeader to insert a branch around loop for unrolling.
670 NewPreHeader = SplitBlock(PreHeader, PreHeader->getTerminator(), DT, LI);
671 NewPreHeader->setName(PreHeader->getName() + ".new");
672 // Split LatchExit to create phi nodes from branch above.
673 SmallVector<BasicBlock*, 4> Preds(predecessors(LatchExit));
674 NewExit = SplitBlockPredecessors(LatchExit, Preds, ".unr-lcssa", DT, LI,
675 nullptr, PreserveLCSSA);
676 // NewExit gets its DebugLoc from LatchExit, which is not part of the
678 // Fix this by setting Loop's DebugLoc to NewExit.
679 auto *NewExitTerminator = NewExit->getTerminator();
680 NewExitTerminator->setDebugLoc(Header->getTerminator()->getDebugLoc());
681 // Split NewExit to insert epilog remainder loop.
682 EpilogPreHeader = SplitBlock(NewExit, NewExitTerminator, DT, LI);
683 EpilogPreHeader->setName(Header->getName() + ".epil.preheader");
685 // If prolog remainder
686 // Split the original preheader twice to insert prolog remainder loop
687 PrologPreHeader = SplitEdge(PreHeader, Header, DT, LI);
688 PrologPreHeader->setName(Header->getName() + ".prol.preheader");
689 PrologExit = SplitBlock(PrologPreHeader, PrologPreHeader->getTerminator(),
691 PrologExit->setName(Header->getName() + ".prol.loopexit");
692 // Split PrologExit to get NewPreHeader.
693 NewPreHeader = SplitBlock(PrologExit, PrologExit->getTerminator(), DT, LI);
694 NewPreHeader->setName(PreHeader->getName() + ".new");
696 // Loop structure should be the following:
699 // PreHeader PreHeader
700 // *NewPreHeader *PrologPreHeader
701 // Header *PrologExit
705 // *EpilogPreHeader Latch
706 // LatchExit LatchExit
708 // Calculate conditions for branch around loop for unrolling
709 // in epilog case and around prolog remainder loop in prolog case.
710 // Compute the number of extra iterations required, which is:
711 // extra iterations = run-time trip count % loop unroll factor
712 PreHeaderBR = cast<BranchInst>(PreHeader->getTerminator());
713 Value *TripCount = Expander.expandCodeFor(TripCountSC, TripCountSC->getType(),
715 Value *BECount = Expander.expandCodeFor(BECountSC, BECountSC->getType(),
717 IRBuilder<> B(PreHeaderBR);
719 // Calculate ModVal = (BECount + 1) % Count.
720 // Note that TripCount is BECount + 1.
721 if (isPowerOf2_32(Count)) {
722 // When Count is power of 2 we don't BECount for epilog case, however we'll
723 // need it for a branch around unrolling loop for prolog case.
724 ModVal = B.CreateAnd(TripCount, Count - 1, "xtraiter");
725 // 1. There are no iterations to be run in the prolog/epilog loop.
727 // 2. The addition computing TripCount overflowed.
729 // If (2) is true, we know that TripCount really is (1 << BEWidth) and so
730 // the number of iterations that remain to be run in the original loop is a
731 // multiple Count == (1 << Log2(Count)) because Log2(Count) <= BEWidth (we
732 // explicitly check this above).
734 // As (BECount + 1) can potentially unsigned overflow we count
735 // (BECount % Count) + 1 which is overflow safe as BECount % Count < Count.
736 Value *ModValTmp = B.CreateURem(BECount,
737 ConstantInt::get(BECount->getType(),
739 Value *ModValAdd = B.CreateAdd(ModValTmp,
740 ConstantInt::get(ModValTmp->getType(), 1));
741 // At that point (BECount % Count) + 1 could be equal to Count.
742 // To handle this case we need to take mod by Count one more time.
743 ModVal = B.CreateURem(ModValAdd,
744 ConstantInt::get(BECount->getType(), Count),
748 UseEpilogRemainder ? B.CreateICmpULT(BECount,
749 ConstantInt::get(BECount->getType(),
751 B.CreateIsNotNull(ModVal, "lcmp.mod");
752 BasicBlock *RemainderLoop = UseEpilogRemainder ? NewExit : PrologPreHeader;
753 BasicBlock *UnrollingLoop = UseEpilogRemainder ? NewPreHeader : PrologExit;
754 // Branch to either remainder (extra iterations) loop or unrolling loop.
755 B.CreateCondBr(BranchVal, RemainderLoop, UnrollingLoop);
756 PreHeaderBR->eraseFromParent();
758 if (UseEpilogRemainder)
759 DT->changeImmediateDominator(NewExit, PreHeader);
761 DT->changeImmediateDominator(PrologExit, PreHeader);
763 Function *F = Header->getParent();
764 // Get an ordered list of blocks in the loop to help with the ordering of the
765 // cloned blocks in the prolog/epilog code
766 LoopBlocksDFS LoopBlocks(L);
767 LoopBlocks.perform(LI);
770 // For each extra loop iteration, create a copy of the loop's basic blocks
771 // and generate a condition that branches to the copy depending on the
772 // number of 'left over' iterations.
774 std::vector<BasicBlock *> NewBlocks;
775 ValueToValueMapTy VMap;
777 // For unroll factor 2 remainder loop will have 1 iterations.
778 // Do not create 1 iteration loop.
779 bool CreateRemainderLoop = (Count != 2);
781 // Clone all the basic blocks in the loop. If Count is 2, we don't clone
782 // the loop, otherwise we create a cloned loop to execute the extra
783 // iterations. This function adds the appropriate CFG connections.
784 BasicBlock *InsertBot = UseEpilogRemainder ? LatchExit : PrologExit;
785 BasicBlock *InsertTop = UseEpilogRemainder ? EpilogPreHeader : PrologPreHeader;
786 Loop *remainderLoop = CloneLoopBlocks(
787 L, ModVal, CreateRemainderLoop, UseEpilogRemainder, UnrollRemainder,
788 InsertTop, InsertBot,
789 NewPreHeader, NewBlocks, LoopBlocks, VMap, DT, LI);
791 // Insert the cloned blocks into the function.
792 F->getBasicBlockList().splice(InsertBot->getIterator(),
793 F->getBasicBlockList(),
794 NewBlocks[0]->getIterator(),
797 // Now the loop blocks are cloned and the other exiting blocks from the
798 // remainder are connected to the original Loop's exit blocks. The remaining
799 // work is to update the phi nodes in the original loop, and take in the
800 // values from the cloned region.
801 for (auto *BB : OtherExits) {
802 for (auto &II : *BB) {
804 // Given we preserve LCSSA form, we know that the values used outside the
805 // loop will be used through these phi nodes at the exit blocks that are
806 // transformed below.
807 if (!isa<PHINode>(II))
809 PHINode *Phi = cast<PHINode>(&II);
810 unsigned oldNumOperands = Phi->getNumIncomingValues();
811 // Add the incoming values from the remainder code to the end of the phi
813 for (unsigned i =0; i < oldNumOperands; i++){
814 Value *newVal = VMap.lookup(Phi->getIncomingValue(i));
815 // newVal can be a constant or derived from values outside the loop, and
816 // hence need not have a VMap value. Also, since lookup already generated
817 // a default "null" VMap entry for this value, we need to populate that
818 // VMap entry correctly, with the mapped entry being itself.
820 newVal = Phi->getIncomingValue(i);
821 VMap[Phi->getIncomingValue(i)] = Phi->getIncomingValue(i);
823 Phi->addIncoming(newVal,
824 cast<BasicBlock>(VMap[Phi->getIncomingBlock(i)]));
827 #if defined(EXPENSIVE_CHECKS) && !defined(NDEBUG)
828 for (BasicBlock *SuccBB : successors(BB)) {
829 assert(!(any_of(OtherExits,
830 [SuccBB](BasicBlock *EB) { return EB == SuccBB; }) ||
831 SuccBB == LatchExit) &&
832 "Breaks the definition of dedicated exits!");
837 // Update the immediate dominator of the exit blocks and blocks that are
838 // reachable from the exit blocks. This is needed because we now have paths
839 // from both the original loop and the remainder code reaching the exit
840 // blocks. While the IDom of these exit blocks were from the original loop,
841 // now the IDom is the preheader (which decides whether the original loop or
842 // remainder code should run).
843 if (DT && !L->getExitingBlock()) {
844 SmallVector<BasicBlock *, 16> ChildrenToUpdate;
845 // NB! We have to examine the dom children of all loop blocks, not just
846 // those which are the IDom of the exit blocks. This is because blocks
847 // reachable from the exit blocks can have their IDom as the nearest common
848 // dominator of the exit blocks.
849 for (auto *BB : L->blocks()) {
850 auto *DomNodeBB = DT->getNode(BB);
851 for (auto *DomChild : DomNodeBB->children()) {
852 auto *DomChildBB = DomChild->getBlock();
853 if (!L->contains(LI->getLoopFor(DomChildBB)))
854 ChildrenToUpdate.push_back(DomChildBB);
857 for (auto *BB : ChildrenToUpdate)
858 DT->changeImmediateDominator(BB, PreHeader);
861 // Loop structure should be the following:
864 // PreHeader PreHeader
865 // NewPreHeader PrologPreHeader
866 // Header PrologHeader
869 // NewExit PrologExit
870 // EpilogPreHeader NewPreHeader
871 // EpilogHeader Header
874 // LatchExit LatchExit
876 // Rewrite the cloned instruction operands to use the values created when the
878 for (BasicBlock *BB : NewBlocks) {
879 for (Instruction &I : *BB) {
880 RemapInstruction(&I, VMap,
881 RF_NoModuleLevelChanges | RF_IgnoreMissingLocals);
885 if (UseEpilogRemainder) {
886 // Connect the epilog code to the original loop and update the
888 ConnectEpilog(L, ModVal, NewExit, LatchExit, PreHeader,
889 EpilogPreHeader, NewPreHeader, VMap, DT, LI,
892 // Update counter in loop for unrolling.
893 // I should be multiply of Count.
894 IRBuilder<> B2(NewPreHeader->getTerminator());
895 Value *TestVal = B2.CreateSub(TripCount, ModVal, "unroll_iter");
896 BranchInst *LatchBR = cast<BranchInst>(Latch->getTerminator());
897 B2.SetInsertPoint(LatchBR);
898 PHINode *NewIdx = PHINode::Create(TestVal->getType(), 2, "niter",
899 Header->getFirstNonPHI());
901 B2.CreateSub(NewIdx, ConstantInt::get(NewIdx->getType(), 1),
902 NewIdx->getName() + ".nsub");
904 if (LatchBR->getSuccessor(0) == Header)
905 IdxCmp = B2.CreateIsNotNull(IdxSub, NewIdx->getName() + ".ncmp");
907 IdxCmp = B2.CreateIsNull(IdxSub, NewIdx->getName() + ".ncmp");
908 NewIdx->addIncoming(TestVal, NewPreHeader);
909 NewIdx->addIncoming(IdxSub, Latch);
910 LatchBR->setCondition(IdxCmp);
912 // Connect the prolog code to the original loop and update the
914 ConnectProlog(L, BECount, Count, PrologExit, LatchExit, PreHeader,
915 NewPreHeader, VMap, DT, LI, PreserveLCSSA);
918 // If this loop is nested, then the loop unroller changes the code in the any
919 // of its parent loops, so the Scalar Evolution pass needs to be run again.
920 SE->forgetTopmostLoop(L);
922 // Verify that the Dom Tree is correct.
923 #if defined(EXPENSIVE_CHECKS) && !defined(NDEBUG)
925 assert(DT->verify(DominatorTree::VerificationLevel::Full));
928 // Canonicalize to LoopSimplifyForm both original and remainder loops. We
929 // cannot rely on the LoopUnrollPass to do this because it only does
930 // canonicalization for parent/subloops and not the sibling loops.
931 if (OtherExits.size() > 0) {
932 // Generate dedicated exit blocks for the original loop, to preserve
934 formDedicatedExitBlocks(L, DT, LI, nullptr, PreserveLCSSA);
935 // Generate dedicated exit blocks for the remainder loop if one exists, to
936 // preserve LoopSimplifyForm.
938 formDedicatedExitBlocks(remainderLoop, DT, LI, nullptr, PreserveLCSSA);
941 auto UnrollResult = LoopUnrollResult::Unmodified;
942 if (remainderLoop && UnrollRemainder) {
943 LLVM_DEBUG(dbgs() << "Unrolling remainder loop\n");
945 UnrollLoop(remainderLoop,
946 {/*Count*/ Count - 1, /*TripCount*/ Count - 1,
947 /*Force*/ false, /*AllowRuntime*/ false,
948 /*AllowExpensiveTripCount*/ false, /*PreserveCondBr*/ true,
949 /*PreserveOnlyFirst*/ false, /*TripMultiple*/ 1,
950 /*PeelCount*/ 0, /*UnrollRemainder*/ false, ForgetAllSCEV},
951 LI, SE, DT, AC, TTI, /*ORE*/ nullptr, PreserveLCSSA);
954 if (ResultLoop && UnrollResult != LoopUnrollResult::FullyUnrolled)
955 *ResultLoop = remainderLoop;
956 NumRuntimeUnrolled++;