xref: /freebsd/contrib/llvm-project/llvm/include/llvm/Transforms/Utils/Local.h (revision ec0ea6efa1ad229d75c394c1a9b9cac33af2b1d3)
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 
36 namespace llvm {
37 
38 class AAResults;
39 class AllocaInst;
40 class AssumptionCache;
41 class BasicBlock;
42 class BranchInst;
43 class CallBase;
44 class CallInst;
45 class DbgDeclareInst;
46 class DbgVariableIntrinsic;
47 class DbgValueInst;
48 class DIBuilder;
49 class DomTreeUpdater;
50 class Function;
51 class Instruction;
52 class InvokeInst;
53 class LoadInst;
54 class MDNode;
55 class MemorySSAUpdater;
56 class PHINode;
57 class StoreInst;
58 class TargetLibraryInfo;
59 class 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.
72 bool 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.
82 bool 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.
88 bool 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.
94 bool 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.
108 void 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.
118 bool 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.
129 bool 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.
138 bool 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.
145 bool 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.
154 void 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.
160 bool 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.
166 bool 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.
174 extern cl::opt<bool> RequireAndPreserveDomTree;
175 bool 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.
183 bool 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.
188 bool 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.
198 AllocaInst *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.
205 AllocaInst *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.
216 Align 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.
223 inline 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.
234 CallInst *createCallMatchingInvoke(InvokeInst *II);
235 
236 /// This function converts the specified invoek into a normall call.
237 void 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.
245 void 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.
250 void 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.
255 void ConvertDebugDeclareToDebugValue(DbgVariableIntrinsic *DII,
256                                      PHINode *LI, DIBuilder &Builder);
257 
258 /// Lowers llvm.dbg.declare intrinsics into appropriate set of
259 /// llvm.dbg.value intrinsics.
260 bool LowerDbgDeclare(Function &F);
261 
262 /// Propagate dbg.value intrinsics through the newly inserted PHIs.
263 void 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.
271 bool 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.
279 void 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.
285 void 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.
292 void 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.
300 DIExpression *salvageDebugInfoImpl(Instruction &I, DIExpression *DIExpr,
301                                    bool StackVal, unsigned LocNo,
302                                    SmallVectorImpl<Value *> &AdditionalValues);
303 
304 /// Point debug users of \p From to \p To or salvage them. Use this function
305 /// only when replacing all uses of \p From with \p To, with a guarantee that
306 /// \p From is going to be deleted.
307 ///
308 /// Follow these rules to prevent use-before-def of \p To:
309 ///   . If \p To is a linked Instruction, set \p DomPoint to \p To.
310 ///   . If \p To is an unlinked Instruction, set \p DomPoint to the Instruction
311 ///     \p To will be inserted after.
312 ///   . If \p To is not an Instruction (e.g a Constant), the choice of
313 ///     \p DomPoint is arbitrary. Pick \p From for simplicity.
314 ///
315 /// If a debug user cannot be preserved without reordering variable updates or
316 /// introducing a use-before-def, it is either salvaged (\ref salvageDebugInfo)
317 /// or deleted. Returns true if any debug users were updated.
318 bool replaceAllDbgUsesWith(Instruction &From, Value &To, Instruction &DomPoint,
319                            DominatorTree &DT);
320 
321 /// Remove all instructions from a basic block other than its terminator
322 /// and any present EH pad instructions. Returns a pair where the first element
323 /// is the number of instructions (excluding debug info instrinsics) that have
324 /// been removed, and the second element is the number of debug info intrinsics
325 /// that have been removed.
326 std::pair<unsigned, unsigned>
327 removeAllNonTerminatorAndEHPadInstructions(BasicBlock *BB);
328 
329 /// Insert an unreachable instruction before the specified
330 /// instruction, making it and the rest of the code in the block dead.
331 unsigned changeToUnreachable(Instruction *I, 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.
339 BasicBlock *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.
349 void 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.
354 bool 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
362 void 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.
371 void 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).
376 void 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.
381 void 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.
385 unsigned 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.
389 unsigned 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.
393 unsigned 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.
404 bool 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.
410 void 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.
416 void copyRangeMetadata(const DataLayout &DL, const LoadInst &OldLI, MDNode *N,
417                        LoadInst &NewLI);
418 
419 /// Remove the debug intrinsic instructions for the given instruction.
420 void 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.
427 void 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.
445 bool 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.
457 void 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?
466 bool 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.
473 Value *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.
482 bool inferAttributesFromOthers(Function &F);
483 
484 } // end namespace llvm
485 
486 #endif // LLVM_TRANSFORMS_UTILS_LOCAL_H
487