[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


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@363654 91177308-0d34-0410-b5e6-96231b3b80d8

docs/SourceLevelDebugging.rst

@@ -531,6 +531,7 @@ within the LLVM IR. By the end of CodeGen, this becomes a mapping from each
 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 addition, instruction scheduling can
 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`` instructions appear thus:
   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