maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[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
This commit is contained in:
Tony 2020-04-20 16:55:34 -04:00
parent dd2c639c3c
commit 756ba3548c
1 changed files with 69 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst
View File

@ -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