[AMDGPU] DWARF proposal review feedback

- Rename DW_OP_LLVM_offset_constu to DW_OP_LLVM_offset_uconst to
  matches DW_OP_plus_uconst.
- Correct DW_OP_LLVM_call_ref to be DW_OP_call_ref.
- Move proposed changes to a separate section to clarify that the
  introduction section is not part of the changes.
- Fix formatting typos and add missing reference.
- Clarify why DW_OP_LLVM_offset et al do not wrap on overflow.
- Correct syntax of augmentation string.

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

Author: t-tye

llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst

@@ -1,20 +1,20 @@
 .. _amdgpu-dwarf-6-proposal-for-heterogeneous-debugging:
 
-====================================================
+****************************************************
 DWARF Version 6 Proposal For Heterogeneous Debugging
-====================================================
+****************************************************
 
 .. contents::
    :local:
 
 .. warning::
 
-   This section describes a **provisional proposal** for DWARF Version 6
+   This document describes a **provisional proposal** for DWARF Version 6
    [:ref:`DWARF <amdgpu-dwarf-DWARF>`] to support heterogeneous debugging. It is
    not currently fully implemented and is subject to change.
 
 Introduction
-------------
+============
 
 This document proposes a set of backwards compatible extensions to DWARF Version
 5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] for consideration of inclusion into a
@@ -100,7 +100,7 @@ denote the current lane, much like ``DW_OP_push_object_address`` denotes the
 current object. The ``DW_OP_*piece`` operations only allow literal indices.
 Therefore, a way to use a computed offset of an arbitrary ___location description
 (such as a vector register) is required. See ``DW_OP_LLVM_push_lane``,
-``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_constu``, and
+``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and
 ``DW_OP_LLVM_bit_offset``.
 
 If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner
@@ -173,16 +173,26 @@ allowing current DWARF expressions to remain legal. See
 
 The ``DW_OP_plus`` and ``DW_OP_minus`` can be defined to operate on a memory
 ___location description in the default target architecture specific address space
-and a generic type value to produce an updated memory ___location description.
-This allows them to continue to be used to offset an address. To generalize
+and a generic type value to produce an updated memory ___location description. This
+allows them to continue to be used to offset an address. To generalize
 offsetting to any ___location description, including ___location descriptions that
-describe when bytes are in registers, are implicit, or a composite of these,
-the ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_constu`` and
-``DW_OP_LLVM_bit_offset`` operations are added. These do not perform wrapping
-which would be hard to define for ___location descriptions of non-memory kinds.
-This allows ``DW_OP_push_object_address`` to push a ___location description that
-may be in a register, or be an implicit value, and the DWARF expression of
-``DW_TAG_ptr_to_member_type`` can contain ``DW_OP_LLVM_offset`` to offset
+describe when bytes are in registers, are implicit, or a composite of these, the
+``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and
+``DW_OP_LLVM_bit_offset`` offset operations are added. Unlike ``DW_OP_plus``,
+``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic operations, these do not
+define that integer overflow causes wrap-around. The offset operations can
+operate on ___location storage of any size. For example, implicit ___location storage
+could be any number of bits in size. It is simpler to define offsets that exceed
+the size of the ___location storage as being ill-formed, than having to force an
+implementation to support potentially infinite precision offsets to allow it to
+correctly track a series of positive and negative offsets that may transiently
+overflow or underflow, but end up in range. This is simple for the arithmetic
+operations as they are defined in terms of two's compliment arithmetic on a base
+type of a fixed size.
+
+Having the offset operations allows ``DW_OP_push_object_address`` to push a
+___location description that may be in a register, or be an implicit value, and the
+DWARF expression of ``DW_TAG_ptr_to_member_type`` can contain them to offset
 within it. ``DW_OP_LLVM_bit_offset`` generalizes DWARF to work with bit fields
 which is not possible in DWARF Version 5.
 
@@ -340,10 +350,17 @@ implemented as an LLVM vendor extension to DWARF Version 5. If accepted these
 names would not include the "\ ``LLVM``\ " and would not use encodings in the
 vendor range.
 
-The proposal is organized to follow the section ordering of DWARF Version 5.
-It includes notes to indicate the corresponding DWARF Version 5 sections to
-which they pertain. Other notes describe additional changes that may be worth
-considering, and to raise questions.
+The proposal is described in
+:ref:`amdgpu-dwarf-proposed-changes-relative-to-dwarf-version-5` and is
+organized to follow the section ordering of DWARF Version 5. It includes notes
+to indicate the corresponding DWARF Version 5 sections to which they pertain.
+Other notes describe additional changes that may be worth considering, and to
+raise questions.
+
+.. _amdgpu-dwarf-proposed-changes-relative-to-dwarf-version-5:
+
+Proposed Changes Relative to DWARF Version 5
+============================================
 
 General Description
 -------------------
@@ -648,7 +665,9 @@ stack assume that the top of the stack (most recently added entry) has index 0.
 They allow the stack entries to be either a value or ___location description.
 
 If any stack entry accessed by a stack operation is an incomplete composite
-___location description, then the DWARF expression is ill-formed.
+___location description (see
+:ref:`amdgpu-dwarf-composite-___location-description-operations`), then the DWARF
+expression is ill-formed.
 
 .. note::
 
@@ -753,14 +772,21 @@ expression.
     unsigned offset, respectively, of a debugging information entry D in the
     current compilation unit.
 
-    ``DW_OP_LLVM_call_ref`` has one operand that is a 4-byte unsigned value in
-    the 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF
-    format, that represents an offset of a debugging information entry D in a
+    ``DW_OP_call_ref`` has one operand that is a 4-byte unsigned value in the
+    32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format,
+    that represents an offset of a debugging information entry D in a
     ``.debug_info`` section, which may be contained in an executable or shared
-    object file other than that containing the operation. For references from one
-    executable or shared object file to another, the relocation must be
+    object file other than that containing the operation. For references from
+    one executable or shared object file to another, the relocation must be
     performed by the consumer.
 
+    .. note:
+
+      It is unclear how crossing from one executable or shared object file to
+      another can work. How would a consumer know which executable or shared
+      object file is being referenced? In an ELF file the DWARF is in a
+      non-ALLOC segment so standard dynamic relocations cannot be used.
+
     *Operand interpretation of* ``DW_OP_call2``\ *,* ``DW_OP_call4``\ *, and*
     ``DW_OP_call_ref`` *is exactly like that for* ``DW_FORM_ref2``\ *,
     ``DW_FORM_ref4``\ *, and* ``DW_FORM_ref_addr``\ *, respectively.*
@@ -1161,7 +1187,7 @@ There are these special value operations currently defined:
     on the stack with the generic type.
 
     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
-    operation can be used and provides greater expressiveness.*
+    *operation can be used and provides greater expressiveness.*
 
 6.  ``DW_OP_xderef_size`` *Deprecated*
 
@@ -1177,7 +1203,7 @@ There are these special value operations currently defined:
     value V retrieved is left on the stack with the generic type.
 
     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
-    operation can be used and provides greater expressiveness.*
+    *operation can be used and provides greater expressiveness.*
 
 7.  ``DW_OP_xderef_type`` *Deprecated*
 
@@ -1195,7 +1221,7 @@ There are these special value operations currently defined:
     retrieved is left on the stack with the type D.
 
     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
-    operation can be used and provides greater expressiveness.*
+    *operation can be used and provides greater expressiveness.*
 
 8.  ``DW_OP_entry_value`` *Deprecated*
 
@@ -1304,9 +1330,9 @@ General Location Description Operations
     to the size of the ___location storage specified by SL, then the DWARF
     expression is ill-formed.
 
-2.  ``DW_OP_LLVM_offset_constu`` *New*
+2.  ``DW_OP_LLVM_offset_uconst`` *New*
 
-    ``DW_OP_LLVM_offset_constu`` has a single unsigned LEB128 integer operand
+    ``DW_OP_LLVM_offset_uconst`` has a single unsigned LEB128 integer operand
     that represents a byte displacement B.
 
     The operation is equivalent to performing ``DW_OP_constu B;
@@ -1316,6 +1342,12 @@ General Location Description Operations
     displacements in two bytes than can be done with* ``DW_OP_lit*;
     DW_OP_LLVM_offset``\ *.*
 
+    .. note::
+
+      Should this be named ``DW_OP_LLVM_offset_uconst`` to match
+      ``DW_OP_plus_uconst``, or ``DW_OP_LLVM_offset_constu`` to match
+      ``DW_OP_constu``?
+
 3.  ``DW_OP_LLVM_bit_offset`` *New*
 
     ``DW_OP_LLVM_bit_offset`` pops two stack entries. The first must be an
@@ -1582,7 +1614,7 @@ type.
     entry corresponding to the current subprogram as described in
     :ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
 
-    The ___location description L is updated as if the ``DW_OP_LLVM_offset_constu
+    The ___location description L is updated as if the ``DW_OP_LLVM_offset_uconst
     B`` operation was applied. The updated L is pushed on the stack.
 
 7.  ``DW_OP_breg0``, ``DW_OP_breg1``, ..., ``DW_OP_breg31``
@@ -1818,7 +1850,7 @@ implicit storage value starting at the bit offset.
 
     * Otherwise the DWARF expression is ill-formed.
 
-    The bit offset of RL is updated as if the ``DW_OP_LLVM_offset_constu B``
+    The bit offset of RL is updated as if the ``DW_OP_LLVM_offset_uconst B``
     operation was applied.
 
     If a ``DW_OP_stack_value`` operation pops a value that is the same as IPV,
@@ -1868,6 +1900,8 @@ reconstruct the value of the object when asked to dereference the pointer
 described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` or
 ``DW_OP_LLVM_aspace_implicit_pointer`` *operation.*
 
+.. _amdgpu-dwarf-composite-___location-description-operations:
+
 Composite Location Description Operations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -2773,7 +2807,7 @@ Debugging Information Entry Attributes
 
     The format for the augmentation string is:
 
-      | ``[``\ *vendor*\ ``v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
+      | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
 
     Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
     version number of the extensions used, and *options* is an optional string
@@ -2861,7 +2895,7 @@ A null-terminated UTF-8 vendor specific augmentation string, which provides
 additional information about the contents of this index. If provided, the
 recommended format for augmentation string is:
 
-  | ``[``\ *vendor*\ ``v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
+  | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
 
 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
 version number of the extensions used in the DWARF of the compilation unit, and
@@ -3089,7 +3123,7 @@ Description Entries. There is at least one CIE in every non-empty
 
     The recommended format for the augmentation string is:
 
-      | ``[``\ *vendor*\ ``v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
+      | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
 
     Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
     version number of the extensions used, and *options* is an optional string
@@ -3583,7 +3617,7 @@ operations.
    DW_OP_LLVM_form_aspace_address     0xe1     0
    DW_OP_LLVM_push_lane               0xe2     0
    DW_OP_LLVM_offset                  0xe3     0
-   DW_OP_LLVM_offset_constu           0xe4     1     ULEB128 byte displacement
+   DW_OP_LLVM_offset_uconst           0xe4     1     ULEB128 byte displacement
    DW_OP_LLVM_bit_offset              0xe5     0
    DW_OP_LLVM_call_frame_entry_reg    0xe6     1     ULEB128 register number
    DW_OP_LLVM_undefined               0xe7     0