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,115 @@ 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 must 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 *unique* predecessor. 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 must follow this rule include: + +* Instruction scheduling. Block-local instruction reordering must 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 must be the same as the location of the ``add`` + instruction. + +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 must merge instruction locations if it replaces multiple +instructions with a single merged instruction, *and* the merged instruction is +in a different block than at least one of the instructions-to-be-merged. 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 attach 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 must 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``). + +Examples of transformations for which this rule *does not* apply include: + +* Speculative execution of *different* instructions from both sides of a CFG + diamond. The rule for :ref:`dropping locations` applies. + +* 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. + +* Complex peephole optimizations which combine multiple non-identical + instructions together, like ``(A * B) + C => llvm.fma.f32(A, B, C)``. This is + a block-local optimization. However, note that the location of the ``fma`` + doesn't exactly correspond to the locations of the ``mul`` or ``add`` + instructions. The rule for :ref:`dropping locations` + applies. + +.. _WhenToDropLocation: + +When to drop an instruction location +------------------------------------ + +A transformation must drop debug locations (or apply artificial 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 minimize erratic single-stepping behavior and to +prevent misleading breakpoint behavior. 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. + +When creating a new instruction that doesn't map back to a source line, use an +artificial line 0 location instead of setting no location at all. The API to +use for this is ``DILocation::get()``. + +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