[llvm] r363654 - [DebugInfo][Docs] Document that prologue/epilogue variable location changes are ignored

[Jeremy Morse via llvm-commits]

Author: jmorse
Date: Tue Jun 18 01:52:38 2019
New Revision: 363654

URL: http://llvm.org/viewvc/llvm-project?rev=363654&view=rev
Log:
[DebugInfo][Docs] Document that prologue/epilogue variable location changes are ignored

This patch documents that LLVM does not describe all changes in variable
locations during the prologue and the epilogue. The debugger doesn't /
shouldn't step through that portion of the function anyway, and describing
every location through such stages would bloat location lists.

Perform some minor cleanup at the same time,
 * Fix an enumerated list
 * Document that dbg.declare intrinsics have their variable location recorded
   in a MachineFunction table, not with DBG_VALUE meta-insts
 * Adds frame-indexes to the list of things that can be operands to
   DBG_VALUEs.

Differential Revision: https://reviews.llvm.org/D63083

Modified:
    llvm/trunk/docs/SourceLevelDebugging.rst

Modified: llvm/trunk/docs/SourceLevelDebugging.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/SourceLevelDebugging.rst?rev=363654&r1=363653&r2=363654&view=diff
==============================================================================
--- llvm/trunk/docs/SourceLevelDebugging.rst (original)
+++ llvm/trunk/docs/SourceLevelDebugging.rst Tue Jun 18 01:52:38 2019
@@ -531,6 +531,7 @@ within the LLVM IR. By the end of CodeGe
 variable to their machine locations over ranges of instructions.
 From IR to object emission, the major transformations which affect variable
 location fidelity are:
+
 1. Instruction Selection
 2. Register allocation
 3. Block layout
@@ -539,6 +540,14 @@ each of which are discussed below. In ad
 significantly change the ordering of the program, and occurs in a number of
 different passes.
 
+Some variable locations are not transformed during CodeGen. Stack locations
+specified by ``llvm.dbg.declare`` are valid and unchanging for the entire
+duration of the function, and are recorded in a simple MachineFunction table.
+Location changes in the prologue and epilogue of a function are also ignored:
+frame setup and destruction may take several instructions, require a
+disproportionate amount of debugging information in the output binary to
+describe, and should be stepped over by debuggers anyway.
+
 Variable locations in Instruction Selection and MIR
 ---------------------------------------------------
 
@@ -573,10 +582,10 @@ inserted. These ``DBG_VALUE`` instructio
   DBG_VALUE %1, $noreg, !123, !DIExpression()
 
 And have the following operands:
- * The first operand can record the variable location as a register, an
-   immediate, or the base address register if the original debug intrinsic
-   referred to memory. ``$noreg`` indicates the variable location is undefined,
-   equivalent to an ``undef`` dbg.value operand.
+ * The first operand can record the variable location as a register,
+   a frame index, an immediate, or the base address register if the original
+   debug intrinsic referred to memory. ``$noreg`` indicates the variable
+   location is undefined, equivalent to an ``undef`` dbg.value operand.
  * The type of the second operand indicates whether the variable location is
    directly referred to by the DBG_VALUE, or whether it is indirect. The
    ``$noreg`` register signifies the former, an immediate operand (0) the