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