[DebugInfo][NFC] Add instr-ref documentation, migration guide

[jryans]

Summary

This used to be D102158, but all the code it describes got re-written, so I figured I'd take another shot at documenting the new instruction referencing variable locations, this time from a higher level. Happily there's no longer any need to describe LiveDebugValues in any detail seeing how it's all SSA-based now.

Probably the most important part is the explanation of what targets need to do to support instruction referencing. The list is small, mostly because there's nothing especially complicated that targets need to do: just instrument their target-specific optimisations and implement the stack spill/restore recognition target hooks.

This is a small amount of text (which is a virtue), I'm extremely happy to expand on anything.

[aprantl]

Nice! Should we link to this document from other documents?

llvm/docs/InstrRefDebugInfo.md

3

Can we concretize "final stages" by explicitly calling out MIR or AsmPrinter?

4

Could you add a "who should read this document" sentence?

[djtodoro]

Thanks!

llvm/docs/InstrRefDebugInfo.md

83

I think this can have a see also referring to the https://llvm.org/docs/SourceLevelDebugging.html#livedebugvalues-expansion-of-variable-locations.

144

nit: are we missing a = here? (and below)

170

double ;;

[jryans]

@jmorse It would be great to get this landed, as it's quite a useful reference to have around. 😄 If the main blocker is lack of time, I'd be happy to take over and work through the review comments so this can move forward.

[jmorse]

In D113586#3480392, @jryans wrote:

@jmorse It would be great to get this landed, as it's quite a useful reference to have around. 😄 If the main blocker is lack of time, I'd be happy to take over and work through the review comments so this can move forward.

Ah. Uh. Not lack of time really, it's just been a mental hurdle to get my mind back into documentation-writing mode.

If you're interested in driving this forwards it'd be highly appreciated. I'll probably get around to this in another week or two otherwise, I'm periodically reminded elsewhere that I should have landed this ages ago.

[jryans]

In D113586#3480424, @jmorse wrote:

If you're interested in driving this forwards it'd be highly appreciated. I'll probably get around to this in another week or two otherwise, I'm periodically reminded elsewhere that I should have landed this ages ago.

The next few weeks are a bit busy for me with holidays and conferences, but once that settles down, I should be able to get this polished up if you haven't already done so by then.

[jryans]

I've had a bit of time to work on this, so I'll post my revised version momentarily... I wasn't sure if I should commandeer this revision or start my own, but I figured commandeering this one seemed best to keep the conversation in one place.

[jryans]

I've made various small improvements in this version:

• Added incoming links to the new doc
• Added a doc title
• Linked to LiveDebugValues in the source-level debugging doc
• Clarified when this work happens
• Add notes on who should read this doc
• Tweaked spelling and style

[jmorse]

All those revisions / updates look good to me -- @StephenTozer @Orlando would you be able to give another look-over?

[jmorse]

Also, many thanks for driving this. After much introspection, I think that every time I came back to this document I tried to rewrite it from scratch, which is kind of a blocker against forward progress :(.

[Orlando]

LGTM with some nits addressed, thanks! I've hit accepted but please leave this up for a day or so in case anyone else has any further comments.

llvm/docs/InstrRefDebugInfo.md

13

nit: variable's

42

nit: instruction's

91

nit: is separated -> are separated?

96

nit: LLVM's

154–155

nit: I found the first sentence of this paragraph a little difficult to parse - possible alternative suggested above.

161

nit: Removing this comma improves readability IMO.

168

nit: should register defines be register definitions? I'm not sure if this is just terminology I'm not familiar with.

[jryans]

In D113586#3519424, @jmorse wrote:

Also, many thanks for driving this. After much introspection, I think that every time I came back to this document I tried to rewrite it from scratch, which is kind of a blocker against forward progress :(.

No worries, happy to help. 😄 I also considered making some bigger changes, but in the end I felt it was better to first land what's here so it's more widely available, and then we can always improve further in future changes.

[jryans]

llvm/docs/InstrRefDebugInfo.md

168

Ah yes, I believe so, "definition" is the more common term in LLVM and also the more typical way I heard it phrased generally, so I've changed this to match your suggestion. There a few spots that do call them "defines", but my guess it's that's mainly because of the enum value RegState::Define perhaps leading people to call them "defines".

[jryans]

Addressed review feedback.

llvm/docs/InstrRefDebugInfo.md

+# Instruction referencing for debug info
+
+This document explains how LLVM uses value tracking, or instruction
+referencing, to determine variable locations for debug info in the code
+generation stage of compilation. This content is aimed at those working on code
+generation targets and optimisation passes. It may also be of interest to anyone
+curious about low-level debug info handling.
+
+# Problem statement
+
+At the end of compilation, LLVM must produce a DWARF location list (or similar)
+describing what register or stack location a variable can be found in, for each
+instruction in that variables lexical scope. We could track the virtual
+register that the variable resides in through compilation, however this is
+vulnerable to register optimisations during regalloc, and instruction
+movements.
+
+# Solution: instruction referencing
+
+Rather than identify the virtual register that a variable value resides in,
+instead in instruction referencing mode, LLVM refers to the machine instruction
+and operand position that the value is defined in. Consider the LLVM IR way of
+referring to instruction values:
+
+  %2 = add i32 %0, %1
+  call void @llvm.dbg.value(metadata i32 %2,
+
+In LLVM IR, the IR Value is synonymous with the instruction that computes the
+value, to the extent that in memory a Value is a pointer to the computing
+instruction. Instruction referencing implements this relationship in the
+codegen backend of LLVM, after instruction selection. Consider the X86 assembly
+below and instruction referencing debug info, corresponding to the earlier
+LLVM IR:
+
+  %2:gr32 = ADD32rr %0, %1, implicit-def $eflags, debug-instr-number 1
+  DBG_INSTR_REF 1, 0, !123, !456, debug-location !789
+
+While the function remains in SSA form, virtual register %2 is sufficient to
+identify the value computed by the instruction -- however the function
+eventually leaves SSA form, and register optimisations will obscure which
+register the desired value is in. Instead, a more consistent way of identifying
+the instructions value is to refer to the MachineOperand where the value is
+defined: independently of which register is defined by that MachineOperand. In
+the code above, the DBG_INSTR_REF instruction refers to instruction number one,
+operand zero, while the ADD32rr has a debug-instr-number attribute attached
+indicating that it is instruction number one.
+
+De-coupling variable locations from registers avoids difficulties involving
+register allocation and optimisation, but requires additional instrumentation
+when the instructions are optimised instead. Optimisations that replace
+instructions with optimised versions that compute the same value must either
+preserve the instruction number, or record a substitution from the old
+instruction / operand number pair to the new instruction / operand pair -- see
+MachineFunction::substituteDebugValuesForInst. If debug info maintenance is not
+performed, or an instruction is eliminated as dead code, the variable location
+is safely dropped and marked "optimised out". The exception is instructions
+that are mutated rather than replaced, which always need debug info
+maintenance.
+
+# Register allocator considerations
+
+When the register allocator runs, debugging instructions do not directly refer
+to any virtual registers, and thus there is no need for expensive location
+maintenance during regalloc (i.e., LiveDebugVariables). Debug instructions are
+unlinked from the function, then linked back in after register allocation
+completes.
+
+The exception is PHI instructions: these become implicit definitions at control
+flow merges once regalloc finishes, and any debug numbers attached to PHI
+instructions are lost. To circumvent this, debug numbers of PHIs are recorded
+at the start of register allocation (phi-node-elimination), then DBG_PHI
+instructions are inserted after regalloc finishes. This requires some
+maintenance of which register a variable is located in during regalloc, but at
+single positions (block entry points) rather than ranges of instructions.
+
+An example, before regalloc:
+
+  bb.2:
+    %2 = PHI %1, %bb.0, %2, %bb.1, debug-instr-number 1
+
+After:
+
+  bb.2:
+    DBG_PHI $rax, 1
+
+# LiveDebugValues
+
+After optimisations and code layout complete, information about variable
+values must be translated into variable locations, i.e. registers and stack
+slots. This is performed in the [LiveDebugValues pass][LiveDebugValues], where
+the debug instructions and machine code is separated out into two independent
+functions:
+ * One that assigns values to variable names,
+ * One that assigns values to machine registers and stack slots.
+
+LLVMs existing SSA tools are used to place PHIs for each function, between
+variable values and the values contained in machine locations, with value
+propagation eliminating any un-necessary PHIs. The two can then be joined up
+to map variables to values, then values to locations, for each instruction in
+the function.
+
+Key to this process is being able to identify the movement of values between
+registers and stack locations, so that the location of values can be preserved
+for the full time that they are resident in the machine.
+
+# Required target support and transition guide
+
+Instruction referencing will work on any target, but likely with poor coverage.
+Supporting instruction referencing well requires:
+ * Target hooks to be implemented to allow LiveDebugValues to follow values through the machine,
+ * Target-specific optimisations to be instrumented, to preserve instruction numbers.
+
+## Target hooks
+
+TargetInstrInfo::isCopyInstrImpl must be implemented to recognise any
+instructions that are copy-like -- LiveDebugValues uses this to identify when
+values move between registers.
+
+TargetInstrInfo::isLoadFromStackSlotPostFE and
+TargetInstrInfo::isStoreToStackSlotPostFE are needed to identify spill and
+restore instructions. Each should return the destination or source register
+respectively. LiveDebugValues will track the movement of a value from / to
+the stack slot. In addition, any instruction that writes to a stack spill
+should have a MachineMemoryOperand attached, so that LiveDebugValues can
+recognise that a slot has been clobbered.
+
+## Target-specific optimisation instrumentation
+
+Optimisations come in two flavours: those that mutate a MachineInstr to make
+it do something different, and those that create a new instruction to replace
+the operation of the old.
+
+The former _must_ be instrumented -- the relevant question is whether any
+register def in any operand will produce a different value, as a result of the
+mutation. If the answer is yes, then there is a risk that a DBG_INSTR_REF
+instruction referring to that operand will end up assigning the different
+value to a variable, presenting the debugging developer with an unexpected
+variable value. In such scenarios, call MachineInstr::dropDebugNumber() on the
+mutated instruction to erase its instruction number. Any DBG_INSTR_REF
+referring to it will produce an empty variable location instead, that appears
+as "optimised out" in the debugger.
+
+For the latter flavour of optimisation, to increase coverage you should record
+an instruction number substitution: a mapping from the old instruction number /
+operand pair to new instruction number / operand pair. Consider if we replace
+a three-address add instruction with a two-address add:
+
+  %2:gr32 = ADD32rr %0, %1, debug-instr-number 1
+
+becomes
+
+  %2:gr32 = ADD32rr %0(tied-def 0), %1, debug-instr-number 2
+
+With a substitution recorded in the MachineFunction that what was instruction
+number 1 operand 0, is now instruction number 2 operand 0. In LiveDebugValues,
+DBG_INSTR_REFs will be mapped through the substitution table to find the most
+recent instruction number / operand number of the value it refers to.
+
+Use MachineFunction::substituteDebugValuesForInst to automatically produce
+substitutions between an old and new instruction. It assumes that any operand
+that is a def in the old instruction, is a def in the new instruction at the
+same operand position. This works most of the time, for example in the example
+above.
+
+If operand numbers do not line up between the old and new instruction, use
+MachineInstr::getDebugInstrNum to acquire the instruction number for the new
+instruction, and MachineFunction::makeDebugValueSubstitution to record the
+mapping between register defines in the old and new instructions. If some
+values computed by the old instruction are no longer computed by the new
+instruction, record no substitution -- LiveDebugValues will safely drop the
+now unavailable variable value.
+
+Should your target clone instructions, much the same as the TailDuplicator
+optimisation pass, do not attempt to preserve the instruction numbers or
+record any substitutions. MachineFunction::CloneMachineInstr should drop the
+instruction number of any cloned instruction, to avoid duplicate numbers
+appearing to LiveDebugValues. Dealing with duplicated instructions is a
+natural extension to instruction referencing that's currently unimplemented.
+
+[LiveDebugValues]: SourceLevelDebugging.html#livedebugvalues-expansion-of-variable-locations

llvm/docs/MIRLangRef.rst

 above would be identified by the pair ``<1, 0>``.
 
 The first two operands of the ``DBG_INSTR_REF`` above record the instruction
 and operand number ``<1, 0>``, identifying the value defined by the ``MOV64ri``.
 The additional operands to ``DBG_INSTR_REF`` are identical to ``DBG_VALUE``,
 and the ``DBG_INSTR_REF`` s position records where the variable takes on the
 designated value in the same way.
 
-More information about how these constructs are used will appear on the source
-level debugging page in due course, see also :doc:`SourceLevelDebugging` and :doc:`HowToUpdateDebugInfo`.
+More information about how these constructs are used is available in
+:doc:`InstrRefDebugInfo`. The related documents :doc:`SourceLevelDebugging` and
+:doc:`HowToUpdateDebugInfo` may be useful as well.

llvm/docs/UserGuides.rst

.. toctree::
    ExtendingLLVM
    GoldPlugin
    HowToBuildOnARM
    HowToBuildWithPGO
    HowToBuildWindowsItaniumPrograms
    HowToCrossCompileBuiltinsOnArm
    HowToCrossCompileLLVM
    HowToUpdateDebugInfo
+   InstrRefDebugInfo
    LinkTimeOptimization
    LoopTerminology
    MarkdownQuickstartTemplate
    MemorySSA
    MergeFunctions
    MCJITDesignAndImplementation
    MisExpect
    ORCv2

 
 :doc:`Remarks`
    A reference on the implementation of remarks in LLVM.
 
 :doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
    This document describes the design and philosophy behind the LLVM
    source-level debugger.
 
+:doc:`How to Update Debug Info <HowToUpdateDebugInfo>`
+   This document specifies how to correctly update debug info in various kinds
+   of code transformations.
+
+:doc:`InstrRefDebugInfo`
+   This document explains how LLVM uses value tracking, or instruction
+   referencing, to determine variable locations for debug info in the final
+   stages of compilation.
+
 Code Generation
 ---------------
 
 :doc:`WritingAnLLVMBackend`
    Information on how to write LLVM backends for machine targets.
 
 :doc:`CodeGenerator`
    The design and implementation of the LLVM code generator.  Useful if you are