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

[jmorse]

Summary

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.

~

This is a result of discussion in D61940, note that my understanding of the rationale behind LLVMs current behaviour is mostly guided by [0].

[0] https://bugs.llvm.org/show_bug.cgi?id=40188#c8

[bjope]

Looks good to me (matching my assumptions about why prolog/epilog is special).
Just a minor nit inline.

docs/SourceLevelDebugging.rst

586

I guess the formatting was choosen to avoid unnecessary diffs.
I usually end up reading the .rst files as plain text more often than I read the docs using some browser etc. which makes this look weird.
nit: Not sure what the common practice is, but I don't mind if line breaks are updated for the full sentence/paragraph.

[rnk]

My initial reaction to the commit message was to disagree with it. In optimized builds, the SDAG builder does a bunch of work to track variable locations of arguments starting at function entry before the prologue is through. I think you can say something more general, which is that variables whose location is described by dbg.declare only ever have one location. That memory location may not be valid during the prologue. This documents what happens when you try to mix dbg.declare with dbg.value. In that case, dbg.declare wins.

[echristo]

I'm tagging in Roland here since he and I were just discussing this the other day. I'm not entirely sure what we want to document here as I'm torn on whether or not we should be doing more here.

[rnk]

In D63083#1536577, @rnk wrote:

My initial reaction to the commit message was to disagree with it.

I should add, it's really just the commit message that I find confusing. I think the documentation as written clearly documents LLVM's existing behavior.

[jmorse]

Whitespace change to ease reading of .rst, split summary into being an actual commit message

[jmorse]

In D63083#1536776, @rnk wrote:

I should add, it's really just the commit message that I find confusing. I think the documentation as written clearly documents LLVM's existing behavior.

Curses -- I've been treating the phab summary more as a "message to reviewers" rather than a commit message (I should have clocked this would cause confusion). I've edited in an actual commit message, up to the tilde character.

In D63083#1536602, @echristo wrote:

I'm tagging in Roland here since he and I were just discussing this the other day. I'm not entirely sure what we want to document here as I'm torn on whether or not we should be doing more here.

Cool -- by "more", you mean describe more variable locations in prologues / epilogues? This isn't an area of deep experience for me, I'd be interested in the reasoning for extending that information (is the explanation this patch adds to the documentation wrong/incomplete?)

docs/SourceLevelDebugging.rst

586

Indeed @ the formatting, I've updated the diff to normalise the formatting, keeping this uncommitted for the moment due to the extra interest.

[jmorse]

Semi-ping: while this is approved, the extra interest suggested I should delay committing in case there's more discussion. Without hearing anything else, I'll land this in the next couple of days.

[aprantl]

I think this is good to go.

[rnk]

lgtm

docs/SourceLevelDebugging.rst

 instructions to line numbers is a simple association. For variable locations
 however the story is more complex. As each ``llvm.dbg.value`` intrinsic
 represents a source-level assignment of a value to a source variable, the
 variable location intrinsics effectively embed a small imperative program
 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
 
 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
 ---------------------------------------------------
 
 Instruction selection creates a MIR function from an IR function, and just as
 it transforms ``intermediate`` instructions into machine instructions, so must
 ``intermediate`` variable locations become machine variable locations.
 Within IR, variable locations are always identified by a Value, but in MIR
 there can be different types of variable locations. In addition, some IR

 corresponding to each ``llvm.dbg.value`` and ``llvm.dbg.addr`` intrinsic are
 inserted. These ``DBG_VALUE`` instructions appear thus:
 
 .. code-block:: text
 
   DBG_VALUE %1, $noreg, !123, !DIExpression()
 
 And have the following operands:
- * The first operand can record the variable location as a register, an
+ * 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
    latter.
  * Operand 3 is the Variable field of the original debug intrinsic.