1//===- Local.h - Functions to perform local transformations -----*- C++ -*-===//
2//
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
6//
7//===----------------------------------------------------------------------===//
8//
9// This family of functions perform various local transformations to the
10// program.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_TRANSFORMS_UTILS_LOCAL_H
15#define LLVM_TRANSFORMS_UTILS_LOCAL_H
16
17#include "llvm/ADT/ArrayRef.h"
18#include "llvm/IR/Dominators.h"
19#include "llvm/Support/CommandLine.h"
20#include "llvm/Transforms/Utils/SimplifyCFGOptions.h"
21#include <cstdint>
22
23namespace llvm {
24
25class DataLayout;
26class Value;
27class WeakTrackingVH;
28class WeakVH;
29template <typename T> class SmallVectorImpl;
30class AAResults;
31class AllocaInst;
32class AssumptionCache;
33class BasicBlock;
34class BranchInst;
35class CallBase;
36class CallInst;
37class DbgVariableIntrinsic;
38class DIBuilder;
39class DomTreeUpdater;
40class Function;
41class Instruction;
42class InvokeInst;
43class LoadInst;
44class MDNode;
45class MemorySSAUpdater;
46class PHINode;
47class StoreInst;
48class TargetLibraryInfo;
49class TargetTransformInfo;
50
51//===----------------------------------------------------------------------===//
52// Local constant propagation.
53//
54
55/// If a terminator instruction is predicated on a constant value, convert it
56/// into an unconditional branch to the constant destination.
57/// This is a nontrivial operation because the successors of this basic block
58/// must have their PHI nodes updated.
59/// Also calls RecursivelyDeleteTriviallyDeadInstructions() on any branch/switch
60/// conditions and indirectbr addresses this might make dead if
61/// DeleteDeadConditions is true.
62bool ConstantFoldTerminator(BasicBlock *BB, bool DeleteDeadConditions = false,
63 const TargetLibraryInfo *TLI = nullptr,
64 DomTreeUpdater *DTU = nullptr);
65
66//===----------------------------------------------------------------------===//
67// Local dead code elimination.
68//
69
70/// Return true if the result produced by the instruction is not used, and the
71/// instruction will return. Certain side-effecting instructions are also
72/// considered dead if there are no uses of the instruction.
73bool isInstructionTriviallyDead(Instruction *I,
74 const TargetLibraryInfo *TLI = nullptr);
75
76/// Return true if the result produced by the instruction would have no side
77/// effects if it was not used. This is equivalent to checking whether
78/// isInstructionTriviallyDead would be true if the use count was 0.
79bool wouldInstructionBeTriviallyDead(const Instruction *I,
80 const TargetLibraryInfo *TLI = nullptr);
81
82/// Return true if the result produced by the instruction has no side effects on
83/// any paths other than where it is used. This is less conservative than
84/// wouldInstructionBeTriviallyDead which is based on the assumption
85/// that the use count will be 0. An example usage of this API is for
86/// identifying instructions that can be sunk down to use(s).
87bool wouldInstructionBeTriviallyDeadOnUnusedPaths(
88 Instruction *I, const TargetLibraryInfo *TLI = nullptr);
89
90/// If the specified value is a trivially dead instruction, delete it.
91/// If that makes any of its operands trivially dead, delete them too,
92/// recursively. Return true if any instructions were deleted.
93bool RecursivelyDeleteTriviallyDeadInstructions(
94 Value *V, const TargetLibraryInfo *TLI = nullptr,
95 MemorySSAUpdater *MSSAU = nullptr,
96 std::function<void(Value *)> AboutToDeleteCallback =
97 std::function<void(Value *)>());
98
99/// Delete all of the instructions in `DeadInsts`, and all other instructions
100/// that deleting these in turn causes to be trivially dead.
101///
102/// The initial instructions in the provided vector must all have empty use
103/// lists and satisfy `isInstructionTriviallyDead`.
104///
105/// `DeadInsts` will be used as scratch storage for this routine and will be
106/// empty afterward.
107void RecursivelyDeleteTriviallyDeadInstructions(
108 SmallVectorImpl<WeakTrackingVH> &DeadInsts,
109 const TargetLibraryInfo *TLI = nullptr, MemorySSAUpdater *MSSAU = nullptr,
110 std::function<void(Value *)> AboutToDeleteCallback =
111 std::function<void(Value *)>());
112
113/// Same functionality as RecursivelyDeleteTriviallyDeadInstructions, but allow
114/// instructions that are not trivially dead. These will be ignored.
115/// Returns true if any changes were made, i.e. any instructions trivially dead
116/// were found and deleted.
117bool RecursivelyDeleteTriviallyDeadInstructionsPermissive(
118 SmallVectorImpl<WeakTrackingVH> &DeadInsts,
119 const TargetLibraryInfo *TLI = nullptr, MemorySSAUpdater *MSSAU = nullptr,
120 std::function<void(Value *)> AboutToDeleteCallback =
121 std::function<void(Value *)>());
122
123/// If the specified value is an effectively dead PHI node, due to being a
124/// def-use chain of single-use nodes that either forms a cycle or is terminated
125/// by a trivially dead instruction, delete it. If that makes any of its
126/// operands trivially dead, delete them too, recursively. Return true if a
127/// change was made.
128bool RecursivelyDeleteDeadPHINode(PHINode *PN,
129 const TargetLibraryInfo *TLI = nullptr,
130 MemorySSAUpdater *MSSAU = nullptr);
131
132/// Scan the specified basic block and try to simplify any instructions in it
133/// and recursively delete dead instructions.
134///
135/// This returns true if it changed the code, note that it can delete
136/// instructions in other blocks as well in this block.
137bool SimplifyInstructionsInBlock(BasicBlock *BB,
138 const TargetLibraryInfo *TLI = nullptr);
139
140/// Replace all the uses of an SSA value in @llvm.dbg intrinsics with
141/// undef. This is useful for signaling that a variable, e.g. has been
142/// found dead and hence it's unavailable at a given program point.
143/// Returns true if the dbg values have been changed.
144bool replaceDbgUsesWithUndef(Instruction *I);
145
146//===----------------------------------------------------------------------===//
147// Control Flow Graph Restructuring.
148//
149
150/// BB is a block with one predecessor and its predecessor is known to have one
151/// successor (BB!). Eliminate the edge between them, moving the instructions in
152/// the predecessor into BB. This deletes the predecessor block.
153void MergeBasicBlockIntoOnlyPred(BasicBlock *BB, DomTreeUpdater *DTU = nullptr);
154
155/// BB is known to contain an unconditional branch, and contains no instructions
156/// other than PHI nodes, potential debug intrinsics and the branch. If
157/// possible, eliminate BB by rewriting all the predecessors to branch to the
158/// successor block and return true. If we can't transform, return false.
159bool TryToSimplifyUncondBranchFromEmptyBlock(BasicBlock *BB,
160 DomTreeUpdater *DTU = nullptr);
161
162/// Check for and eliminate duplicate PHI nodes in this block. This doesn't try
163/// to be clever about PHI nodes which differ only in the order of the incoming
164/// values, but instcombine orders them so it usually won't matter.
165///
166/// This overload removes the duplicate PHI nodes directly.
167bool EliminateDuplicatePHINodes(BasicBlock *BB);
168
169/// Check for and eliminate duplicate PHI nodes in this block. This doesn't try
170/// to be clever about PHI nodes which differ only in the order of the incoming
171/// values, but instcombine orders them so it usually won't matter.
172///
173/// This overload collects the PHI nodes to be removed into the ToRemove set.
174bool EliminateDuplicatePHINodes(BasicBlock *BB,
175 SmallPtrSetImpl<PHINode *> &ToRemove);
176
177/// This function is used to do simplification of a CFG. For example, it
178/// adjusts branches to branches to eliminate the extra hop, it eliminates
179/// unreachable basic blocks, and does other peephole optimization of the CFG.
180/// It returns true if a modification was made, possibly deleting the basic
181/// block that was pointed to. LoopHeaders is an optional input parameter
182/// providing the set of loop headers that SimplifyCFG should not eliminate.
183extern cl::opt<bool> RequireAndPreserveDomTree;
184bool simplifyCFG(BasicBlock *BB, const TargetTransformInfo &TTI,
185 DomTreeUpdater *DTU = nullptr,
186 const SimplifyCFGOptions &Options = {},
187 ArrayRef<WeakVH> LoopHeaders = {});
188
189/// This function is used to flatten a CFG. For example, it uses parallel-and
190/// and parallel-or mode to collapse if-conditions and merge if-regions with
191/// identical statements.
192bool FlattenCFG(BasicBlock *BB, AAResults *AA = nullptr);
193
194/// If this basic block is ONLY a setcc and a branch, and if a predecessor
195/// branches to us and one of our successors, fold the setcc into the
196/// predecessor and use logical operations to pick the right destination.
197bool FoldBranchToCommonDest(BranchInst *BI, llvm::DomTreeUpdater *DTU = nullptr,
198 MemorySSAUpdater *MSSAU = nullptr,
199 const TargetTransformInfo *TTI = nullptr,
200 unsigned BonusInstThreshold = 1);
201
202/// This function takes a virtual register computed by an Instruction and
203/// replaces it with a slot in the stack frame, allocated via alloca.
204/// This allows the CFG to be changed around without fear of invalidating the
205/// SSA information for the value. It returns the pointer to the alloca inserted
206/// to create a stack slot for X.
207AllocaInst *DemoteRegToStack(Instruction &X,
208 bool VolatileLoads = false,
209 Instruction *AllocaPoint = nullptr);
210
211/// This function takes a virtual register computed by a phi node and replaces
212/// it with a slot in the stack frame, allocated via alloca. The phi node is
213/// deleted and it returns the pointer to the alloca inserted.
214AllocaInst *DemotePHIToStack(PHINode *P, Instruction *AllocaPoint = nullptr);
215
216/// If the specified pointer points to an object that we control, try to modify
217/// the object's alignment to PrefAlign. Returns a minimum known alignment of
218/// the value after the operation, which may be lower than PrefAlign.
219///
220/// Increating value alignment isn't often possible though. If alignment is
221/// important, a more reliable approach is to simply align all global variables
222/// and allocation instructions to their preferred alignment from the beginning.
223Align tryEnforceAlignment(Value *V, Align PrefAlign, const DataLayout &DL);
224
225/// Try to ensure that the alignment of \p V is at least \p PrefAlign bytes. If
226/// the owning object can be modified and has an alignment less than \p
227/// PrefAlign, it will be increased and \p PrefAlign returned. If the alignment
228/// cannot be increased, the known alignment of the value is returned.
229///
230/// It is not always possible to modify the alignment of the underlying object,
231/// so if alignment is important, a more reliable approach is to simply align
232/// all global variables and allocation instructions to their preferred
233/// alignment from the beginning.
234Align getOrEnforceKnownAlignment(Value *V, MaybeAlign PrefAlign,
235 const DataLayout &DL,
236 const Instruction *CxtI = nullptr,
237 AssumptionCache *AC = nullptr,
238 const DominatorTree *DT = nullptr);
239
240/// Try to infer an alignment for the specified pointer.
241inline Align getKnownAlignment(Value *V, const DataLayout &DL,
242 const Instruction *CxtI = nullptr,
243 AssumptionCache *AC = nullptr,
244 const DominatorTree *DT = nullptr) {
245 return getOrEnforceKnownAlignment(V, PrefAlign: MaybeAlign(), DL, CxtI, AC, DT);
246}
247
248/// Create a call that matches the invoke \p II in terms of arguments,
249/// attributes, debug information, etc. The call is not placed in a block and it
250/// will not have a name. The invoke instruction is not removed, nor are the
251/// uses replaced by the new call.
252CallInst *createCallMatchingInvoke(InvokeInst *II);
253
254/// This function converts the specified invoke into a normal call.
255CallInst *changeToCall(InvokeInst *II, DomTreeUpdater *DTU = nullptr);
256
257///===---------------------------------------------------------------------===//
258/// Dbg Intrinsic utilities
259///
260
261/// Inserts a llvm.dbg.value intrinsic before a store to an alloca'd value
262/// that has an associated llvm.dbg.declare intrinsic.
263void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
264 StoreInst *SI, DIBuilder &Builder);
265void ConvertDebugDeclareToDebugValue(DPValue *DPV, StoreInst *SI,
266 DIBuilder &Builder);
267
268/// Inserts a llvm.dbg.value intrinsic before a load of an alloca'd value
269/// that has an associated llvm.dbg.declare intrinsic.
270void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
271 LoadInst *LI, DIBuilder &Builder);
272void ConvertDebugDeclareToDebugValue(DPValue *DPV, LoadInst *LI,
273 DIBuilder &Builder);
274
275/// Inserts a llvm.dbg.value intrinsic after a phi that has an associated
276/// llvm.dbg.declare intrinsic.
277void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
278 PHINode *LI, DIBuilder &Builder);
279void ConvertDebugDeclareToDebugValue(DPValue *DPV, PHINode *LI,
280 DIBuilder &Builder);
281
282/// Lowers llvm.dbg.declare intrinsics into appropriate set of
283/// llvm.dbg.value intrinsics.
284bool LowerDbgDeclare(Function &F);
285
286/// Propagate dbg.value intrinsics through the newly inserted PHIs.
287void insertDebugValuesForPHIs(BasicBlock *BB,
288 SmallVectorImpl<PHINode *> &InsertedPHIs);
289
290/// Replaces llvm.dbg.declare instruction when the address it
291/// describes is replaced with a new value. If Deref is true, an
292/// additional DW_OP_deref is prepended to the expression. If Offset
293/// is non-zero, a constant displacement is added to the expression
294/// (between the optional Deref operations). Offset can be negative.
295bool replaceDbgDeclare(Value *Address, Value *NewAddress, DIBuilder &Builder,
296 uint8_t DIExprFlags, int Offset);
297
298/// Replaces multiple llvm.dbg.value instructions when the alloca it describes
299/// is replaced with a new value. If Offset is non-zero, a constant displacement
300/// is added to the expression (after the mandatory Deref). Offset can be
301/// negative. New llvm.dbg.value instructions are inserted at the locations of
302/// the instructions they replace.
303void replaceDbgValueForAlloca(AllocaInst *AI, Value *NewAllocaAddress,
304 DIBuilder &Builder, int Offset = 0);
305
306/// Assuming the instruction \p I is going to be deleted, attempt to salvage
307/// debug users of \p I by writing the effect of \p I in a DIExpression. If it
308/// cannot be salvaged changes its debug uses to undef.
309void salvageDebugInfo(Instruction &I);
310
311/// Implementation of salvageDebugInfo, applying only to instructions in
312/// \p Insns, rather than all debug users from findDbgUsers( \p I).
313/// Mark undef if salvaging cannot be completed.
314void salvageDebugInfoForDbgValues(Instruction &I,
315 ArrayRef<DbgVariableIntrinsic *> Insns,
316 ArrayRef<DPValue *> DPInsns);
317
318/// Given an instruction \p I and DIExpression \p DIExpr operating on
319/// it, append the effects of \p I to the DIExpression operand list
320/// \p Ops, or return \p nullptr if it cannot be salvaged.
321/// \p CurrentLocOps is the number of SSA values referenced by the
322/// incoming \p Ops. \return the first non-constant operand
323/// implicitly referred to by Ops. If \p I references more than one
324/// non-constant operand, any additional operands are added to
325/// \p AdditionalValues.
326///
327/// \example
328////
329/// I = add %a, i32 1
330///
331/// Return = %a
332/// Ops = llvm::dwarf::DW_OP_lit1 llvm::dwarf::DW_OP_add
333///
334/// I = add %a, %b
335///
336/// Return = %a
337/// Ops = llvm::dwarf::DW_OP_LLVM_arg0 llvm::dwarf::DW_OP_add
338/// AdditionalValues = %b
339Value *salvageDebugInfoImpl(Instruction &I, uint64_t CurrentLocOps,
340 SmallVectorImpl<uint64_t> &Ops,
341 SmallVectorImpl<Value *> &AdditionalValues);
342
343/// Point debug users of \p From to \p To or salvage them. Use this function
344/// only when replacing all uses of \p From with \p To, with a guarantee that
345/// \p From is going to be deleted.
346///
347/// Follow these rules to prevent use-before-def of \p To:
348/// . If \p To is a linked Instruction, set \p DomPoint to \p To.
349/// . If \p To is an unlinked Instruction, set \p DomPoint to the Instruction
350/// \p To will be inserted after.
351/// . If \p To is not an Instruction (e.g a Constant), the choice of
352/// \p DomPoint is arbitrary. Pick \p From for simplicity.
353///
354/// If a debug user cannot be preserved without reordering variable updates or
355/// introducing a use-before-def, it is either salvaged (\ref salvageDebugInfo)
356/// or deleted. Returns true if any debug users were updated.
357bool replaceAllDbgUsesWith(Instruction &From, Value &To, Instruction &DomPoint,
358 DominatorTree &DT);
359
360/// Remove all instructions from a basic block other than its terminator
361/// and any present EH pad instructions. Returns a pair where the first element
362/// is the number of instructions (excluding debug info intrinsics) that have
363/// been removed, and the second element is the number of debug info intrinsics
364/// that have been removed.
365std::pair<unsigned, unsigned>
366removeAllNonTerminatorAndEHPadInstructions(BasicBlock *BB);
367
368/// Insert an unreachable instruction before the specified
369/// instruction, making it and the rest of the code in the block dead.
370unsigned changeToUnreachable(Instruction *I, bool PreserveLCSSA = false,
371 DomTreeUpdater *DTU = nullptr,
372 MemorySSAUpdater *MSSAU = nullptr);
373
374/// Convert the CallInst to InvokeInst with the specified unwind edge basic
375/// block. This also splits the basic block where CI is located, because
376/// InvokeInst is a terminator instruction. Returns the newly split basic
377/// block.
378BasicBlock *changeToInvokeAndSplitBasicBlock(CallInst *CI,
379 BasicBlock *UnwindEdge,
380 DomTreeUpdater *DTU = nullptr);
381
382/// Replace 'BB's terminator with one that does not have an unwind successor
383/// block. Rewrites `invoke` to `call`, etc. Updates any PHIs in unwind
384/// successor. Returns the instruction that replaced the original terminator,
385/// which might be a call in case the original terminator was an invoke.
386///
387/// \param BB Block whose terminator will be replaced. Its terminator must
388/// have an unwind successor.
389Instruction *removeUnwindEdge(BasicBlock *BB, DomTreeUpdater *DTU = nullptr);
390
391/// Remove all blocks that can not be reached from the function's entry.
392///
393/// Returns true if any basic block was removed.
394bool removeUnreachableBlocks(Function &F, DomTreeUpdater *DTU = nullptr,
395 MemorySSAUpdater *MSSAU = nullptr);
396
397/// Combine the metadata of two instructions so that K can replace J. Some
398/// metadata kinds can only be kept if K does not move, meaning it dominated
399/// J in the original IR.
400///
401/// Metadata not listed as known via KnownIDs is removed
402void combineMetadata(Instruction *K, const Instruction *J,
403 ArrayRef<unsigned> KnownIDs, bool DoesKMove);
404
405/// Combine the metadata of two instructions so that K can replace J. This
406/// specifically handles the case of CSE-like transformations. Some
407/// metadata can only be kept if K dominates J. For this to be correct,
408/// K cannot be hoisted.
409///
410/// Unknown metadata is removed.
411void combineMetadataForCSE(Instruction *K, const Instruction *J,
412 bool DoesKMove);
413
414/// Copy the metadata from the source instruction to the destination (the
415/// replacement for the source instruction).
416void copyMetadataForLoad(LoadInst &Dest, const LoadInst &Source);
417
418/// Patch the replacement so that it is not more restrictive than the value
419/// being replaced. It assumes that the replacement does not get moved from
420/// its original position.
421void patchReplacementInstruction(Instruction *I, Value *Repl);
422
423// Replace each use of 'From' with 'To', if that use does not belong to basic
424// block where 'From' is defined. Returns the number of replacements made.
425unsigned replaceNonLocalUsesWith(Instruction *From, Value *To);
426
427/// Replace each use of 'From' with 'To' if that use is dominated by
428/// the given edge. Returns the number of replacements made.
429unsigned replaceDominatedUsesWith(Value *From, Value *To, DominatorTree &DT,
430 const BasicBlockEdge &Edge);
431/// Replace each use of 'From' with 'To' if that use is dominated by
432/// the end of the given BasicBlock. Returns the number of replacements made.
433unsigned replaceDominatedUsesWith(Value *From, Value *To, DominatorTree &DT,
434 const BasicBlock *BB);
435
436/// Return true if this call calls a gc leaf function.
437///
438/// A leaf function is a function that does not safepoint the thread during its
439/// execution. During a call or invoke to such a function, the callers stack
440/// does not have to be made parseable.
441///
442/// Most passes can and should ignore this information, and it is only used
443/// during lowering by the GC infrastructure.
444bool callsGCLeafFunction(const CallBase *Call, const TargetLibraryInfo &TLI);
445
446/// Copy a nonnull metadata node to a new load instruction.
447///
448/// This handles mapping it to range metadata if the new load is an integer
449/// load instead of a pointer load.
450void copyNonnullMetadata(const LoadInst &OldLI, MDNode *N, LoadInst &NewLI);
451
452/// Copy a range metadata node to a new load instruction.
453///
454/// This handles mapping it to nonnull metadata if the new load is a pointer
455/// load instead of an integer load and the range doesn't cover null.
456void copyRangeMetadata(const DataLayout &DL, const LoadInst &OldLI, MDNode *N,
457 LoadInst &NewLI);
458
459/// Remove the debug intrinsic instructions for the given instruction.
460void dropDebugUsers(Instruction &I);
461
462/// Hoist all of the instructions in the \p IfBlock to the dominant block
463/// \p DomBlock, by moving its instructions to the insertion point \p InsertPt.
464///
465/// The moved instructions receive the insertion point debug location values
466/// (DILocations) and their debug intrinsic instructions are removed.
467void hoistAllInstructionsInto(BasicBlock *DomBlock, Instruction *InsertPt,
468 BasicBlock *BB);
469
470/// Given a constant, create a debug information expression.
471DIExpression *getExpressionForConstant(DIBuilder &DIB, const Constant &C,
472 Type &Ty);
473
474//===----------------------------------------------------------------------===//
475// Intrinsic pattern matching
476//
477
478/// Try to match a bswap or bitreverse idiom.
479///
480/// If an idiom is matched, an intrinsic call is inserted before \c I. Any added
481/// instructions are returned in \c InsertedInsts. They will all have been added
482/// to a basic block.
483///
484/// A bitreverse idiom normally requires around 2*BW nodes to be searched (where
485/// BW is the bitwidth of the integer type). A bswap idiom requires anywhere up
486/// to BW / 4 nodes to be searched, so is significantly faster.
487///
488/// This function returns true on a successful match or false otherwise.
489bool recognizeBSwapOrBitReverseIdiom(
490 Instruction *I, bool MatchBSwaps, bool MatchBitReversals,
491 SmallVectorImpl<Instruction *> &InsertedInsts);
492
493//===----------------------------------------------------------------------===//
494// Sanitizer utilities
495//
496
497/// Given a CallInst, check if it calls a string function known to CodeGen,
498/// and mark it with NoBuiltin if so. To be used by sanitizers that intend
499/// to intercept string functions and want to avoid converting them to target
500/// specific instructions.
501void maybeMarkSanitizerLibraryCallNoBuiltin(CallInst *CI,
502 const TargetLibraryInfo *TLI);
503
504//===----------------------------------------------------------------------===//
505// Transform predicates
506//
507
508/// Given an instruction, is it legal to set operand OpIdx to a non-constant
509/// value?
510bool canReplaceOperandWithVariable(const Instruction *I, unsigned OpIdx);
511
512//===----------------------------------------------------------------------===//
513// Value helper functions
514//
515
516/// Invert the given true/false value, possibly reusing an existing copy.
517Value *invertCondition(Value *Condition);
518
519
520//===----------------------------------------------------------------------===//
521// Assorted
522//
523
524/// If we can infer one attribute from another on the declaration of a
525/// function, explicitly materialize the maximal set in the IR.
526bool inferAttributesFromOthers(Function &F);
527
528} // end namespace llvm
529
530#endif // LLVM_TRANSFORMS_UTILS_LOCAL_H
531

source code of llvm/include/llvm/Transforms/Utils/Local.h