diff --git a/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst --- a/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst +++ b/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 `] 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 `] for consideration of inclusion into a @@ -100,7 +100,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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