diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst --- a/llvm/docs/HowToUpdateDebugInfo.rst +++ b/llvm/docs/HowToUpdateDebugInfo.rst @@ -18,11 +18,123 @@ For more on the philosophy behind LLVM debugging information, see :doc:`SourceLevelDebugging`. -IR-level transformations -======================== +Rules for updating debug locations +================================== -Deleting an Instruction ------------------------ +.. _WhenToPreserveLocation: + +When to preserve an instruction location +---------------------------------------- + +A transformation should preserve the debug location of an instruction if the +instruction either remains in its basic block, or if its basic block is folded +into a predecessor that branches unconditionally. The APIs to use are +``IRBuilder``, or ``Instruction::setDebugLoc``. + +The purpose of this rule is to ensure that common block-local optimizations +preserve the ability to set breakpoints on source lines corresponding to the +instructions they touch. Debugging, as well as SamplePGO accuracy, would be +severely impacted if that ability were lost. + +Examples of transformations that should follow this rule include: + +* Instruction scheduling. Block-local instruction reordering should not drop line + locations, even though this may lead to jumpy single-stepping behavior. + +* Simple jump threading. For example, if block ``B1`` unconditionally jumps to + ``B2``, *and* is its unique predecessor, instructions from ``B2`` can be + hoisted into ``B1``. Line locations from ``B2`` should be preserved. + +* Simple peephole optimizations, like ``(X + X) => (X << 1)``. The location of + the ``shl`` instruction should be the same as the location of the ``add`` + instruction. + +* Tail duplication. For example, if blocks ``B1`` and ``B2`` both + unconditionally branch to ``B3`` and ``B3`` can be folded into its + predecessors, breakpoint locations from ``B3`` should be preserved. + +Examples of transformations for which this rule *does not* apply include: + +* LICM. E.g., if an instruction is moved from the loop body to the preheader, + the rule for :ref:`dropping locations` applies. + +.. _WhenToMergeLocation: + +When to merge instruction locations +----------------------------------- + +A transformation should merge instruction locations if it replaces multiple +instructions with a single merged instruction, *and* that merged instruction +does not correspond to any of the original instructions' locations. The API to +use is ``Instruction::applyMergedLocation``. + +The purpose of this rule is to ensure that a) the single merged instruction +has a location with an accurate scope attached, and b) to prevent misleading +single-stepping (or breakpoint) behavior. Often, merged instructions are memory +accesses which can trap: having an accurate scope attached greatly assists in +crash triage by identifying the (possibly inlined) function where the bad +memory access occurred. This rule is also meant to assist SamplePGO by banning +scenarios in which a sample of a block containing a merged instruction is +misattributed to a block containing one of the instructions-to-be-merged. + +Examples of transformations that should follow this rule include: + +* Merging identical loads/stores which occur on both sides of a CFG diamond + (see the ``MergedLoadStoreMotion`` pass). + +* Merging identical loop-invariant stores (see the LICM utility + ``llvm::promoteLoopAccessesToScalars``). + +* Complex peephole optimizations which combine multiple instructions together, + like ``(A * B) + C => llvm.fma.f32(A, B, C)``. Note that the location of the + ``fma`` does not exactly correspond to the locations of either the ``mul`` or + the ``add`` instructions. + +Examples of transformations for which this rule *does not* apply include: + +* Simple block-local peepholes which delete redundant instructions, like + ``(sext (zext x)) => (zext x)``. The rule for + :ref:`preserving locations` should apply here. + +* Converting an if-then-else CFG diamond into a ``select``. Preserving the + debug locations of speculated instructions can make it seem like a condition + is true when it's not (or vice versa), which leads to a confusing + single-stepping experience. The rule for + :ref:`dropping locations` should apply here. + +* Hoisting identical instructions which appear in several successor blocks into + a predecessor block (see ``BranchFolder::HoistCommonCodeInSuccs``). In this + case there is no single merged instruction. The rule for + :ref:`dropping locations` applies. + +.. _WhenToDropLocation: + +When to drop an instruction location +------------------------------------ + +A transformation should drop debug locations if the rules for +:ref:`preserving` and +:ref:`merging` debug locations do not apply. The API to +use is ``Instruction::setDebugLoc()``. + +The purpose of this rule is to prevent erratic or misleading single-stepping +behavior in situations in which an instruction has no clear, unambiguous +relationship to a source line. + +To handle an instruction without a location, the DWARF generator +defaults to allowing the last-set location after a label to cascade forward, or +to setting a line 0 location with viable scope information if no previous +location is available. + +See the discussion in the section about +:ref:`merging locations` for examples of when the rule for +dropping locations applies. + +Rules for updating debug values +=============================== + +Deleting an IR-level Instruction +-------------------------------- When an ``Instruction`` is deleted, its debug uses change to ``undef``. This is a loss of debug info: the value of a one or more source variables becomes