xref: /freebsd/contrib/llvm-project/llvm/include/llvm/Transforms/Utils/Local.h (revision e32fecd0c2c3ee37c47ee100f169e7eb0282a873)
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 
23 namespace llvm {
24 
25 class DataLayout;
26 class Value;
27 class WeakTrackingVH;
28 class WeakVH;
29 template <typename T> class SmallVectorImpl;
30 class AAResults;
31 class AllocaInst;
32 class AssumptionCache;
33 class BasicBlock;
34 class BranchInst;
35 class CallBase;
36 class CallInst;
37 class DbgVariableIntrinsic;
38 class DIBuilder;
39 class DomTreeUpdater;
40 class Function;
41 class Instruction;
42 class InvokeInst;
43 class LoadInst;
44 class MDNode;
45 class MemorySSAUpdater;
46 class PHINode;
47 class StoreInst;
48 class TargetLibraryInfo;
49 class 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.
62 bool 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.
73 bool 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.
79 bool wouldInstructionBeTriviallyDead(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).
87 bool 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.
93 bool 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.
107 void 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.
117 bool 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.
128 bool 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.
137 bool 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.
144 bool 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.
153 void 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.
159 bool 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 bool EliminateDuplicatePHINodes(BasicBlock *BB);
166 
167 /// This function is used to do simplification of a CFG.  For example, it
168 /// adjusts branches to branches to eliminate the extra hop, it eliminates
169 /// unreachable basic blocks, and does other peephole optimization of the CFG.
170 /// It returns true if a modification was made, possibly deleting the basic
171 /// block that was pointed to. LoopHeaders is an optional input parameter
172 /// providing the set of loop headers that SimplifyCFG should not eliminate.
173 extern cl::opt<bool> RequireAndPreserveDomTree;
174 bool simplifyCFG(BasicBlock *BB, const TargetTransformInfo &TTI,
175                  DomTreeUpdater *DTU = nullptr,
176                  const SimplifyCFGOptions &Options = {},
177                  ArrayRef<WeakVH> LoopHeaders = {});
178 
179 /// This function is used to flatten a CFG. For example, it uses parallel-and
180 /// and parallel-or mode to collapse if-conditions and merge if-regions with
181 /// identical statements.
182 bool FlattenCFG(BasicBlock *BB, AAResults *AA = nullptr);
183 
184 /// If this basic block is ONLY a setcc and a branch, and if a predecessor
185 /// branches to us and one of our successors, fold the setcc into the
186 /// predecessor and use logical operations to pick the right destination.
187 bool FoldBranchToCommonDest(BranchInst *BI, llvm::DomTreeUpdater *DTU = nullptr,
188                             MemorySSAUpdater *MSSAU = nullptr,
189                             const TargetTransformInfo *TTI = nullptr,
190                             unsigned BonusInstThreshold = 1);
191 
192 /// This function takes a virtual register computed by an Instruction and
193 /// replaces it with a slot in the stack frame, allocated via alloca.
194 /// This allows the CFG to be changed around without fear of invalidating the
195 /// SSA information for the value. It returns the pointer to the alloca inserted
196 /// to create a stack slot for X.
197 AllocaInst *DemoteRegToStack(Instruction &X,
198                              bool VolatileLoads = false,
199                              Instruction *AllocaPoint = nullptr);
200 
201 /// This function takes a virtual register computed by a phi node and replaces
202 /// it with a slot in the stack frame, allocated via alloca. The phi node is
203 /// deleted and it returns the pointer to the alloca inserted.
204 AllocaInst *DemotePHIToStack(PHINode *P, Instruction *AllocaPoint = nullptr);
205 
206 /// Try to ensure that the alignment of \p V is at least \p PrefAlign bytes. If
207 /// the owning object can be modified and has an alignment less than \p
208 /// PrefAlign, it will be increased and \p PrefAlign returned. If the alignment
209 /// cannot be increased, the known alignment of the value is returned.
210 ///
211 /// It is not always possible to modify the alignment of the underlying object,
212 /// so if alignment is important, a more reliable approach is to simply align
213 /// all global variables and allocation instructions to their preferred
214 /// alignment from the beginning.
215 Align getOrEnforceKnownAlignment(Value *V, MaybeAlign PrefAlign,
216                                  const DataLayout &DL,
217                                  const Instruction *CxtI = nullptr,
218                                  AssumptionCache *AC = nullptr,
219                                  const DominatorTree *DT = nullptr);
220 
221 /// Try to infer an alignment for the specified pointer.
222 inline Align getKnownAlignment(Value *V, const DataLayout &DL,
223                                const Instruction *CxtI = nullptr,
224                                AssumptionCache *AC = nullptr,
225                                const DominatorTree *DT = nullptr) {
226   return getOrEnforceKnownAlignment(V, MaybeAlign(), DL, CxtI, AC, DT);
227 }
228 
229 /// Create a call that matches the invoke \p II in terms of arguments,
230 /// attributes, debug information, etc. The call is not placed in a block and it
231 /// will not have a name. The invoke instruction is not removed, nor are the
232 /// uses replaced by the new call.
233 CallInst *createCallMatchingInvoke(InvokeInst *II);
234 
235 /// This function converts the specified invoek into a normall call.
236 CallInst *changeToCall(InvokeInst *II, DomTreeUpdater *DTU = nullptr);
237 
238 ///===---------------------------------------------------------------------===//
239 ///  Dbg Intrinsic utilities
240 ///
241 
242 /// Inserts a llvm.dbg.value intrinsic before a store to an alloca'd value
243 /// that has an associated llvm.dbg.declare or llvm.dbg.addr intrinsic.
244 void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
245                                      StoreInst *SI, DIBuilder &Builder);
246 
247 /// Inserts a llvm.dbg.value intrinsic before a load of an alloca'd value
248 /// that has an associated llvm.dbg.declare or llvm.dbg.addr intrinsic.
249 void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
250                                      LoadInst *LI, DIBuilder &Builder);
251 
252 /// Inserts a llvm.dbg.value intrinsic after a phi that has an associated
253 /// llvm.dbg.declare or llvm.dbg.addr intrinsic.
254 void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
255                                      PHINode *LI, DIBuilder &Builder);
256 
257 /// Lowers llvm.dbg.declare intrinsics into appropriate set of
258 /// llvm.dbg.value intrinsics.
259 bool LowerDbgDeclare(Function &F);
260 
261 /// Propagate dbg.value intrinsics through the newly inserted PHIs.
262 void insertDebugValuesForPHIs(BasicBlock *BB,
263                               SmallVectorImpl<PHINode *> &InsertedPHIs);
264 
265 /// Replaces llvm.dbg.declare instruction when the address it
266 /// describes is replaced with a new value. If Deref is true, an
267 /// additional DW_OP_deref is prepended to the expression. If Offset
268 /// is non-zero, a constant displacement is added to the expression
269 /// (between the optional Deref operations). Offset can be negative.
270 bool replaceDbgDeclare(Value *Address, Value *NewAddress, DIBuilder &Builder,
271                        uint8_t DIExprFlags, int Offset);
272 
273 /// Replaces multiple llvm.dbg.value instructions when the alloca it describes
274 /// is replaced with a new value. If Offset is non-zero, a constant displacement
275 /// is added to the expression (after the mandatory Deref). Offset can be
276 /// negative. New llvm.dbg.value instructions are inserted at the locations of
277 /// the instructions they replace.
278 void replaceDbgValueForAlloca(AllocaInst *AI, Value *NewAllocaAddress,
279                               DIBuilder &Builder, int Offset = 0);
280 
281 /// Assuming the instruction \p I is going to be deleted, attempt to salvage
282 /// debug users of \p I by writing the effect of \p I in a DIExpression. If it
283 /// cannot be salvaged changes its debug uses to undef.
284 void salvageDebugInfo(Instruction &I);
285 
286 
287 /// Implementation of salvageDebugInfo, applying only to instructions in
288 /// \p Insns, rather than all debug users from findDbgUsers( \p I).
289 /// Returns true if any debug users were updated.
290 /// Mark undef if salvaging cannot be completed.
291 void salvageDebugInfoForDbgValues(Instruction &I,
292                                   ArrayRef<DbgVariableIntrinsic *> Insns);
293 
294 /// Given an instruction \p I and DIExpression \p DIExpr operating on
295 /// it, append the effects of \p I to the DIExpression operand list
296 /// \p Ops, or return \p nullptr if it cannot be salvaged.
297 /// \p CurrentLocOps is the number of SSA values referenced by the
298 /// incoming \p Ops.  \return the first non-constant operand
299 /// implicitly referred to by Ops. If \p I references more than one
300 /// non-constant operand, any additional operands are added to
301 /// \p AdditionalValues.
302 ///
303 /// \example
304 ////
305 ///   I = add %a, i32 1
306 ///
307 ///   Return = %a
308 ///   Ops = llvm::dwarf::DW_OP_lit1 llvm::dwarf::DW_OP_add
309 ///
310 ///   I = add %a, %b
311 ///
312 ///   Return = %a
313 ///   Ops = llvm::dwarf::DW_OP_LLVM_arg0 llvm::dwarf::DW_OP_add
314 ///   AdditionalValues = %b
315 Value *salvageDebugInfoImpl(Instruction &I, uint64_t CurrentLocOps,
316                             SmallVectorImpl<uint64_t> &Ops,
317                             SmallVectorImpl<Value *> &AdditionalValues);
318 
319 /// Point debug users of \p From to \p To or salvage them. Use this function
320 /// only when replacing all uses of \p From with \p To, with a guarantee that
321 /// \p From is going to be deleted.
322 ///
323 /// Follow these rules to prevent use-before-def of \p To:
324 ///   . If \p To is a linked Instruction, set \p DomPoint to \p To.
325 ///   . If \p To is an unlinked Instruction, set \p DomPoint to the Instruction
326 ///     \p To will be inserted after.
327 ///   . If \p To is not an Instruction (e.g a Constant), the choice of
328 ///     \p DomPoint is arbitrary. Pick \p From for simplicity.
329 ///
330 /// If a debug user cannot be preserved without reordering variable updates or
331 /// introducing a use-before-def, it is either salvaged (\ref salvageDebugInfo)
332 /// or deleted. Returns true if any debug users were updated.
333 bool replaceAllDbgUsesWith(Instruction &From, Value &To, Instruction &DomPoint,
334                            DominatorTree &DT);
335 
336 /// Remove all instructions from a basic block other than its terminator
337 /// and any present EH pad instructions. Returns a pair where the first element
338 /// is the number of instructions (excluding debug info intrinsics) that have
339 /// been removed, and the second element is the number of debug info intrinsics
340 /// that have been removed.
341 std::pair<unsigned, unsigned>
342 removeAllNonTerminatorAndEHPadInstructions(BasicBlock *BB);
343 
344 /// Insert an unreachable instruction before the specified
345 /// instruction, making it and the rest of the code in the block dead.
346 unsigned changeToUnreachable(Instruction *I, bool PreserveLCSSA = false,
347                              DomTreeUpdater *DTU = nullptr,
348                              MemorySSAUpdater *MSSAU = nullptr);
349 
350 /// Convert the CallInst to InvokeInst with the specified unwind edge basic
351 /// block.  This also splits the basic block where CI is located, because
352 /// InvokeInst is a terminator instruction.  Returns the newly split basic
353 /// block.
354 BasicBlock *changeToInvokeAndSplitBasicBlock(CallInst *CI,
355                                              BasicBlock *UnwindEdge,
356                                              DomTreeUpdater *DTU = nullptr);
357 
358 /// Replace 'BB's terminator with one that does not have an unwind successor
359 /// block. Rewrites `invoke` to `call`, etc. Updates any PHIs in unwind
360 /// successor.
361 ///
362 /// \param BB  Block whose terminator will be replaced.  Its terminator must
363 ///            have an unwind successor.
364 void removeUnwindEdge(BasicBlock *BB, DomTreeUpdater *DTU = nullptr);
365 
366 /// Remove all blocks that can not be reached from the function's entry.
367 ///
368 /// Returns true if any basic block was removed.
369 bool removeUnreachableBlocks(Function &F, DomTreeUpdater *DTU = nullptr,
370                              MemorySSAUpdater *MSSAU = nullptr);
371 
372 /// Combine the metadata of two instructions so that K can replace J. Some
373 /// metadata kinds can only be kept if K does not move, meaning it dominated
374 /// J in the original IR.
375 ///
376 /// Metadata not listed as known via KnownIDs is removed
377 void combineMetadata(Instruction *K, const Instruction *J,
378                      ArrayRef<unsigned> KnownIDs, bool DoesKMove);
379 
380 /// Combine the metadata of two instructions so that K can replace J. This
381 /// specifically handles the case of CSE-like transformations. Some
382 /// metadata can only be kept if K dominates J. For this to be correct,
383 /// K cannot be hoisted.
384 ///
385 /// Unknown metadata is removed.
386 void combineMetadataForCSE(Instruction *K, const Instruction *J,
387                            bool DoesKMove);
388 
389 /// Copy the metadata from the source instruction to the destination (the
390 /// replacement for the source instruction).
391 void copyMetadataForLoad(LoadInst &Dest, const LoadInst &Source);
392 
393 /// Patch the replacement so that it is not more restrictive than the value
394 /// being replaced. It assumes that the replacement does not get moved from
395 /// its original position.
396 void patchReplacementInstruction(Instruction *I, Value *Repl);
397 
398 // Replace each use of 'From' with 'To', if that use does not belong to basic
399 // block where 'From' is defined. Returns the number of replacements made.
400 unsigned replaceNonLocalUsesWith(Instruction *From, Value *To);
401 
402 /// Replace each use of 'From' with 'To' if that use is dominated by
403 /// the given edge.  Returns the number of replacements made.
404 unsigned replaceDominatedUsesWith(Value *From, Value *To, DominatorTree &DT,
405                                   const BasicBlockEdge &Edge);
406 /// Replace each use of 'From' with 'To' if that use is dominated by
407 /// the end of the given BasicBlock. Returns the number of replacements made.
408 unsigned replaceDominatedUsesWith(Value *From, Value *To, DominatorTree &DT,
409                                   const BasicBlock *BB);
410 
411 /// Return true if this call calls a gc leaf function.
412 ///
413 /// A leaf function is a function that does not safepoint the thread during its
414 /// execution.  During a call or invoke to such a function, the callers stack
415 /// does not have to be made parseable.
416 ///
417 /// Most passes can and should ignore this information, and it is only used
418 /// during lowering by the GC infrastructure.
419 bool callsGCLeafFunction(const CallBase *Call, const TargetLibraryInfo &TLI);
420 
421 /// Copy a nonnull metadata node to a new load instruction.
422 ///
423 /// This handles mapping it to range metadata if the new load is an integer
424 /// load instead of a pointer load.
425 void copyNonnullMetadata(const LoadInst &OldLI, MDNode *N, LoadInst &NewLI);
426 
427 /// Copy a range metadata node to a new load instruction.
428 ///
429 /// This handles mapping it to nonnull metadata if the new load is a pointer
430 /// load instead of an integer load and the range doesn't cover null.
431 void copyRangeMetadata(const DataLayout &DL, const LoadInst &OldLI, MDNode *N,
432                        LoadInst &NewLI);
433 
434 /// Remove the debug intrinsic instructions for the given instruction.
435 void dropDebugUsers(Instruction &I);
436 
437 /// Hoist all of the instructions in the \p IfBlock to the dominant block
438 /// \p DomBlock, by moving its instructions to the insertion point \p InsertPt.
439 ///
440 /// The moved instructions receive the insertion point debug location values
441 /// (DILocations) and their debug intrinsic instructions are removed.
442 void hoistAllInstructionsInto(BasicBlock *DomBlock, Instruction *InsertPt,
443                               BasicBlock *BB);
444 
445 //===----------------------------------------------------------------------===//
446 //  Intrinsic pattern matching
447 //
448 
449 /// Try to match a bswap or bitreverse idiom.
450 ///
451 /// If an idiom is matched, an intrinsic call is inserted before \c I. Any added
452 /// instructions are returned in \c InsertedInsts. They will all have been added
453 /// to a basic block.
454 ///
455 /// A bitreverse idiom normally requires around 2*BW nodes to be searched (where
456 /// BW is the bitwidth of the integer type). A bswap idiom requires anywhere up
457 /// to BW / 4 nodes to be searched, so is significantly faster.
458 ///
459 /// This function returns true on a successful match or false otherwise.
460 bool recognizeBSwapOrBitReverseIdiom(
461     Instruction *I, bool MatchBSwaps, bool MatchBitReversals,
462     SmallVectorImpl<Instruction *> &InsertedInsts);
463 
464 //===----------------------------------------------------------------------===//
465 //  Sanitizer utilities
466 //
467 
468 /// Given a CallInst, check if it calls a string function known to CodeGen,
469 /// and mark it with NoBuiltin if so.  To be used by sanitizers that intend
470 /// to intercept string functions and want to avoid converting them to target
471 /// specific instructions.
472 void maybeMarkSanitizerLibraryCallNoBuiltin(CallInst *CI,
473                                             const TargetLibraryInfo *TLI);
474 
475 //===----------------------------------------------------------------------===//
476 //  Transform predicates
477 //
478 
479 /// Given an instruction, is it legal to set operand OpIdx to a non-constant
480 /// value?
481 bool canReplaceOperandWithVariable(const Instruction *I, unsigned OpIdx);
482 
483 //===----------------------------------------------------------------------===//
484 //  Value helper functions
485 //
486 
487 /// Invert the given true/false value, possibly reusing an existing copy.
488 Value *invertCondition(Value *Condition);
489 
490 
491 //===----------------------------------------------------------------------===//
492 //  Assorted
493 //
494 
495 /// If we can infer one attribute from another on the declaration of a
496 /// function, explicitly materialize the maximal set in the IR.
497 bool inferAttributesFromOthers(Function &F);
498 
499 } // end namespace llvm
500 
501 #endif // LLVM_TRANSFORMS_UTILS_LOCAL_H
502