[DebugInfo][Docs] Document MIR language debug-info constructs

[jmorse]

Summary

In D85741 Adrian suggested the experimental instruction referencing meta-instruction should be documented; further analysis shows that actually we don't document any debug info features of MIR. This patch adds explanations for debug-location, DBG_VALUE and other things, plus DBG_INSTR_REF.

Rather than trying to describe what these things mean, I've linked to source level debugging; IMO better to document the syntax in the MIR language reference, and the meaning elsewhere.

[aprantl]

Thanks!

llvm/docs/MIRLangRef.rst

797

debug information is a more common term I think

801

Can you unify all headlines to use the same capitalization rules?

816

typo: Fixed Variable Locations

842

vari*a*ble

[MaskRay]

llvm/docs/MIRLangRef.rst

797

Both GCC documentation and DWARF specifications refer to this term as "debugging information". There are many places using "debug information" as well. I think perhaps "debugging information" is indeed more formal and using it here may be fine.

[djtodoro]

llvm/docs/MIRLangRef.rst

894

I recommend adding references (SEE ALSO) to the how-to-update-debug-info and source-level-debugging pages.

[jmorse]

(Revise to address comments)

[jmorse]

llvm/docs/MIRLangRef.rst

797

I've no strong opinion on the wording; alright to leave it as it is?

801

Have rewritten "locations" to be lower case

llvm/docs/MIRLangRef.rst

 .. TODO: Describe the frame information YAML mapping.
 .. TODO: Describe the syntax of the stack object machine operands and their
    YAML definitions.
 .. TODO: Describe the syntax of the block address machine operands.
 .. TODO: Describe the syntax of the metadata machine operands, and the
    instructions debug location attribute.
 .. TODO: Describe the syntax of the register live out machine operands.
 .. TODO: Describe the syntax of the machine memory operands.
+
+Debug-Info constructs
+---------------------
+
+Most of the debugging information in a MIR file is to be found in the metadata
+of the embedded module. Within a machine function, that metadata is referred to
+by various constructs to describe source locations and variable locations.
+
+Source locations
+^^^^^^^^^^^^^^^^
+
+Every MIR instruction may optionally have a trailing reference to a
+``DILocation`` metadata node, after all operands and symbols, but before
+memory operands:
+
+.. code-block:: text
+
+   $rbp = MOV64rr $rdi, debug-location !12
+
+The source location attachment is synonymous with the ``!dbg`` metadata
+attachment in LLVM-IR. The absence of a source location attachment will be
+represented by an empty ``DebugLoc`` object in the machine instruction.
+
+Fixed variable locations
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several ways of specifying variable locations. The simpliest is
+describing a variable that is permanently located on the stack. In the stack
+or fixedStack attribute of the machine function, the variable, scope, and
+any qualifying location modifier are provided:
+
+.. code-block:: text
+
+    - { id: 0, name: offset.addr, offset: -24, size: 8, alignment: 8, stack-id: default,
+     4  debug-info-variable: '!1', debug-info-expression: '!DIExpression()',
+        debug-info-location: '!2' }
+
+Where:
+
+- ``debug-info-variable`` identifies a DILocalVariable metadata node,
+
+- ``debug-info-expression`` adds qualifiers to the variable location,
+
+- ``debug-info-location`` identifies a DILocation metadata node.
+
+These metadata attributes correspond to the operands of a ``llvm.dbg.declare``
+IR intrinsic, see the :ref:`source level debugging<format_common_intrinsics>`
+documentation.
+
+Varying variable locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Variables that are not always on the stack or change location are specified
+with the ``DBG_VALUE``  meta machine instruction. It is synonymous with the
+``llvm.dbg.value`` IR intrinsic, and is written:
+
+.. code-block:: text
+
+    DBG_VALUE $rax, $noreg, !123, !DIExpression(), debug-location !456
+
+The operands to which respectively:
+
+1. Identifies a machine location such as a register, immediate, or frame index,
+
+2. Is either $noreg, or immediate value zero if an extra level of indirection is to be added to the first operand,
+
+3. Identifies a ``DILocalVariable`` metadata node,
+
+4. Specifies an expression qualifying the variable location, either inline or as a metadata node reference,
+
+While the source location identifies the ``DILocation`` for the scope of the
+variable. The second operand (``IsIndirect``) is deprecated and to be deleted.
+All additional qualifiers for the variable location should be made through the
+expression metadata.
+
+Instruction referencing locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This experimental feature aims to separate the specification of variable
+*values* from the program point where a variable takes on that value. Changes
+in variable value occur in the same manner as ``DBG_VALUE`` meta instructions
+but using ``DBG_INSTR_REF``. Variable values are identified by a pair of
+instruction number and operand number. Consider the example below:
+
+.. code-block:: text
+
+    $rbp = MOV64ri 0, debug-instr-number 1, debug-location !12
+    DBG_INSTR_REF 1, 0, !123, !DIExpression(), debug-location !456
+
+Instruction numbers are directly attached to machine instructions with an
+optional ``debug-instr-number`` attachment, before the optional
+``debug-location`` attachment. The value defined in ``$rbp`` in the code
+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`.