[llvm] e24f5f3 - [AMDGPU] DWARF proposal changes
via llvm-commits
llvm-commits at lists.llvm.org
Wed Jul 29 22:08:03 PDT 2020
Author: Tony
Date: 2020-07-30T05:07:09Z
New Revision: e24f5f314914cff02958b023f2ecfc3cb413372e
URL: https://github.com/llvm/llvm-project/commit/e24f5f314914cff02958b023f2ecfc3cb413372e
DIFF: https://github.com/llvm/llvm-project/commit/e24f5f314914cff02958b023f2ecfc3cb413372e.diff
LOG: [AMDGPU] DWARF proposal changes
- Clarify that these are extensions to DWARF 5 and not as yet a
proposal.
Reviewed By: scott.linder
Differential Revision: https://reviews.llvm.org/D70523
Added:
llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
Modified:
llvm/docs/AMDGPUUsage.rst
Removed:
llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst
################################################################################
diff --git a/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
similarity index 97%
rename from llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst
rename to llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
index 8253519f7dfe..b6df0c92201a 100644
--- a/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst
+++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
@@ -1,15 +1,15 @@
-.. _amdgpu-dwarf-proposal-for-heterogeneous-debugging:
+.. _amdgpu-dwarf-extensions-for-heterogeneous-debugging:
-******************************************
-DWARF Proposal For Heterogeneous Debugging
-******************************************
+********************************************
+DWARF Extensions For Heterogeneous Debugging
+********************************************
.. contents::
:local:
.. warning::
- This document describes a **provisional proposal** for DWARF Version 6
+ This document describes **provisional extensions** to DWARF Version 5
[:ref:`DWARF <amdgpu-dwarf-DWARF>`] to support heterogeneous debugging. It is
not currently fully implemented and is subject to change.
@@ -37,43 +37,37 @@ and the Perforce TotalView HPC debugger [:ref:`Perforce-TotalView
To support debugging heterogeneous programs several features that are not
provided by current DWARF Version 5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] have
-been identified. This document contains a collection of proposals to address
+been identified. This document contains a collection of extensions to address
providing those features.
The :ref:`amdgpu-dwarf-motivation` section describes the issues that are being
addressed for heterogeneous computing. That is followed by the
-:ref:`amdgpu-dwarf-proposed-changes-relative-to-dwarf-version-5` section
-containing the proposed textual changes relative to the DWARF Version 5
-standard. Then there is an :ref:`amdgpu-dwarf-examples` section that links to
-the AMD GPU specific usage of the features in the proposal that includes an
-example. Finally, there is a :ref:`amdgpu-dwarf-references` section. There are a
-number of notes included that raise open questions, or provide alternative
-approaches considered. The draft proposal seeks to be general in nature and
-backwards compatible with DWARF Version 5. Its goal is to be applicable to
-meeting the needs of any heterogeneous system and not be vendor or architecture
-specific.
-
-A fundamental aspect of the draft proposal is that it allows DWARF expression
-location descriptions as stack elements. The draft proposal is based on DWARF
+:ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` section containing the
+textual changes for the extensions relative to the DWARF Version 5 standard.
+Then there is an :ref:`amdgpu-dwarf-examples` section that links to the AMD GPU
+specific usage of the extensions that includes an example. Finally, there is a
+:ref:`amdgpu-dwarf-references` section. There are a number of notes included
+that raise open questions, or provide alternative approaches considered. The
+extensions seek to be general in nature and backwards compatible with DWARF
+Version 5. The goal is to be applicable to meeting the needs of any
+heterogeneous system and not be vendor or architecture specific.
+
+A fundamental aspect of the extensions is that it allows DWARF expression
+location descriptions as stack elements. The extensions are based on DWARF
Version 5 and maintains compatibility with DWARF Version 5. After attempting
-several alternatives, the current thinking is that such an addition to DWARF
-Version 5 is the simplest and cleanest way to support debugging optimized GPU
+several alternatives, the current thinking is that such extensions to DWARF
+Version 5 are the simplest and cleanest ways to support debugging optimized GPU
code. It also appears to be generally useful and may be able to address other
reported DWARF issues, as well as being helpful in providing better optimization
support for non-GPU code.
-General feedback on this draft proposal is sought, together with suggestions on
-how to clarify, simplify, or organize it before submitting it as a formal DWARF
-proposal. The current draft proposal is large and may need to be split into
-separate proposals before formal submission. Any suggestions on how best to do
-that are appreciated. However, at the initial review stage it is believed there
-is value in presenting a unified proposal as there are mutual dependencies
-between the various parts that would not be as apparent if it was broken up into
-separate independent proposals.
+General feedback on these extensions is sought, together with suggestions on how
+to clarify, simplify, or organize them. If their is general interest then some
+or all of these extensions could be submitted as future DWARF proposals.
-We are in the process of modifying LLVM and GDB to support this draft proposal
+We are in the process of modifying LLVM and GDB to support these extensions
which is providing experience and insights. We plan to upstream the changes to
-those projects for any final form of the proposal.
+those projects for any final form of the extensions.
The author very much appreciates the input provided so far by many others which
has been incorporated into this current version.
@@ -83,11 +77,10 @@ has been incorporated into this current version.
Motivation
==========
-This document proposes a set of backwards compatible extensions to DWARF Version
-5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] for consideration of inclusion into a
-future DWARF Version 6 standard to support heterogeneous debugging.
+This document presents a set of backwards compatible extensions to DWARF Version
+5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] to support heterogeneous debugging.
-The remainder of this section provides motivation for each proposed feature in
+The remainder of this section provides motivation for each extension in
terms of heterogeneous debugging on commercially available AMD GPU hardware
(AMDGPU). The goal is to add support to the AMD [:ref:`AMD <amdgpu-dwarf-AMD>`]
open source Radeon Open Compute Platform (ROCm) [:ref:`AMD-ROCm
@@ -102,21 +95,21 @@ to work with third parties to enable support for AMDGPU debugging in the GCC
compiler [:ref:`GCC <amdgpu-dwarf-GCC>`] and the Perforce TotalView HPC debugger
[:ref:`Perforce-TotalView <amdgpu-dwarf-Perforce-TotalView>`].
-However, the proposal is intended to be vendor and architecture neutral. It is
-believed to apply to other heterogenous hardware devices including GPUs, DSPs,
-FPGAs, and other specialized hardware. These collectively include similar
-characteristics and requirements as AMDGPU devices. Parts of the proposal can
+However, the extensions are intended to be vendor and architecture neutral. They
+are believed to apply to other heterogenous hardware devices including GPUs,
+DSPs, FPGAs, and other specialized hardware. These collectively include similar
+characteristics and requirements as AMDGPU devices. Some of the extension can
also apply to traditional CPU hardware that supports large vector registers.
Compilers can map source languages and extensions that describe large scale
parallel execution onto the lanes of the vector registers. This is common in
-programming languages used in ML and HPC. The proposal also includes improved
+programming languages used in ML and HPC. The extensions also include improved
support for optimized code on any architecture. Some of the generalizations may
also benefit other issues that have been raised.
-The proposal has evolved though collaboration with many individuals and active
-prototyping within the GDB debugger and LLVM compiler. Input has also been very
-much appreciated from the developers working on the Perforce TotalView HPC
-Debugger and GCC compiler.
+The extensions have evolved though collaboration with many individuals and
+active prototyping within the GDB debugger and LLVM compiler. Input has also
+been very much appreciated from the developers working on the Perforce TotalView
+HPC Debugger and GCC compiler.
The AMDGPU has several features that require additional DWARF functionality in
order to support optimized code.
@@ -332,8 +325,8 @@ attributes such as ``DW_AT_data_member_location``, ``DW_AT_use_location``, and
on the expression stack before evaluating the expression. However, DWARF
Version 5 only allows the stack to contain values and so only a single memory
address can be on the stack which makes these incapable of handling location
-descriptions with multiple places, or places other than memory. Since this
-proposal allows the stack to contain location descriptions, the operations are
+descriptions with multiple places, or places other than memory. Since these
+extensions allow the stack to contain location descriptions, the operations are
generalized to support location descriptions that can have multiple places.
This is backwards compatible with DWARF Version 5 and allows objects with
multiple places to be supported. For example, the expression that describes
@@ -345,8 +338,8 @@ unified into a single section that describes DWARF expressions in general.
This unification seems to be a natural consequence and a necessity of allowing
location descriptions to be part of the evaluation stack.
-For those familiar with the definition of location descriptions in DWARF
-Version 5, the definition in this proposal is presented
diff erently, but does
+For those familiar with the definition of location descriptions in DWARF Version
+5, the definitions in these extensions are presented
diff erently, but does
in fact define the same concept with the same fundamental semantics. However,
it does so in a way that allows the concept to extend to support address
spaces, bit addressing, the ability for composite location descriptions to be
@@ -354,7 +347,7 @@ composed of any kind of location description, and the ability to support
objects located at multiple places. Collectively these changes expand the set
of processors that can be supported and improves support for optimized code.
-Several approaches were considered, and the one proposed appears to be the
+Several approaches were considered, and the one presented appears to be the
cleanest and offers the greatest improvement of DWARF's ability to support
optimized code. Examining the GDB debugger and LLVM compiler, it appears only
to require modest changes as they both already have to support general use of
@@ -412,22 +405,22 @@ style based on the DWARF Version 5 specification. Non-normative text is shown
in *italics*.
The names for the new operations, attributes, and constants include "\
-``LLVM``\ " and are encoded with vendor specific codes so this proposal can be
-implemented as an LLVM vendor extension to DWARF Version 5. If accepted these
+``LLVM``\ " and are encoded with vendor specific codes so these extensions can
+be 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 described in
-:ref:`amdgpu-dwarf-proposed-changes-relative-to-dwarf-version-5` and is
+The extensions are described in
+:ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` and are
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:
+.. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
-Proposed Changes Relative to DWARF Version 5
-============================================
+Changes Relative to DWARF Version 5
+===================================
General Description
-------------------
@@ -463,7 +456,7 @@ DWARF Expressions
.. note::
This section, and its nested sections, replaces DWARF Version 5 section 2.5
- and section 2.6. The new proposed DWARF expression operations are defined as
+ and section 2.6. The new DWARF expression operation extensions are defined as
well as clarifying the extensions to already existing DWARF Version 5
operations. It is based on the text of the existing DWARF Version 5 standard.
@@ -1432,8 +1425,8 @@ There are these special value operations currently defined:
register hook reads bytes from the next register (or reads out of bounds
for the last register!). Removing use of the target hook does not cause
any test failures in common architectures (except an illegal hand written
- assembly test). If a target architecture requires this behavior, this
- proposal allows a composite location description to be used to combine
+ assembly test). If a target architecture requires this behavior, these
+ extensions allow a composite location description to be used to combine
multiple registers.
2. ``DW_OP_deref``
@@ -1507,17 +1500,18 @@ There are these special value operations currently defined:
This definition makes it an evaluation error if L is a register location
description that has less than TS bits remaining in the register storage.
- Particularly since this proposal extends location descriptions to have a
- bit offset, it would be odd to define this as performing sign extension
+ Particularly since these extensions extend location descriptions to have
+ a bit offset, it would be odd to define this as performing sign extension
based on the type, or be target architecture dependent, as the number of
remaining bits could be any number. This matches the GDB implementation
for ``DW_OP_deref_type``.
- This proposal defines ``DW_OP_*breg*`` in terms of ``DW_OP_regval_type``.
- ``DW_OP_regval_type`` is defined in terms of ``DW_OP_regx``, which uses a
- 0 bit offset, and ``DW_OP_deref_type``. Therefore, it requires the
- register size to be greater or equal to the address size of the address
- space. This matches the GDB implementation for ``DW_OP_*breg*``.
+ These extensions define ``DW_OP_*breg*`` in terms of
+ ``DW_OP_regval_type``. ``DW_OP_regval_type`` is defined in terms of
+ ``DW_OP_regx``, which uses a 0 bit offset, and ``DW_OP_deref_type``.
+ Therefore, it requires the register size to be greater or equal to the
+ address size of the address space. This matches the GDB implementation for
+ ``DW_OP_*breg*``.
The DWARF is ill-formed if D is not in the current compilation unit, D is
not a ``DW_TAG_base_type`` debugging information entry, or if TS divided by
@@ -2410,7 +2404,7 @@ compatible with the definitions in DWARF Version 5.*
.. note::
- Since this proposal allows location descriptions to be entries on the
+ Since these extensions allow location descriptions to be entries on the
stack, a simpler operation to create composite location descriptions. For
example, just one operation that specifies how many parts, and pops pairs
of stack entries for the part size and location description. Not only
@@ -2693,15 +2687,15 @@ DWARF address space identifiers are used by:
.. note::
- With the definition of DWARF address classes and DWARF address spaces in this
- proposal, DWARF Version 5 table 2.7 needs to be updated. It seems it is an
+ With the definition of DWARF address classes and DWARF address spaces in these
+ extensions, DWARF Version 5 table 2.7 needs to be updated. It seems it is an
example of DWARF address spaces and not DWARF address classes.
.. note::
- With the expanded support for DWARF address spaces in this proposal, it may be
- worth examining if DWARF segments can be eliminated and DWARF address spaces
- used instead.
+ With the expanded support for DWARF address spaces in these extensions, it may
+ be worth examining if DWARF segments can be eliminated and DWARF address
+ spaces used instead.
That may involve extending DWARF address spaces to also be used to specify
code locations. In target architectures that use
diff erent memory areas for
@@ -2751,7 +2745,7 @@ DWARF address space identifiers are used by:
debugger information entry type modifier that can be applied to a pointer type
and reference type. The ``DW_AT_address_class`` attribute could be re-defined
to not be target architecture specific and instead define generalized language
- values (as is proposed above for DWARF address classes in the table
+ values (as presented above for DWARF address classes in the table
:ref:`amdgpu-dwarf-address-class-table`) that will support OpenCL and other
languages using memory spaces. The ``DW_AT_address_class`` attribute could be
defined to not be applied to pointer types or reference types, but instead
@@ -2772,7 +2766,7 @@ DWARF address space identifiers are used by:
variable allocation in address classes. Such variable allocation would result
in the variable's location description needing an address space.
- The approach proposed in :ref:`amdgpu-dwarf-address-class-table` is to define
+ The approach presented in :ref:`amdgpu-dwarf-address-class-table` is to define
the default ``DW_ADDR_none`` to be the generic address class and not the
global address class. This matches how CLANG and LLVM have added support for
CUDA-like languages on top of existing C++ language support. This allows all
@@ -2827,7 +2821,7 @@ Debugging Information Entry Attributes
.. note::
This section provides changes to existing debugger information entry
- attributes and defines attributes added by the proposal. These would be
+ attributes and defines attributes added by these extensions. These would be
incorporated into the appropriate DWARF Version 5 chapter 2 sections.
1. ``DW_AT_location``
@@ -3419,8 +3413,8 @@ Call Frame Information
.. note::
This section provides changes to existing call frame information and defines
- instructions added by the proposal. Additional support is added for address
- spaces. Register unwind DWARF expressions are generalized to allow any
+ instructions added by these extensions. Additional support is added for
+ address spaces. Register unwind DWARF expressions are generalized to allow any
location description, including those with composite and implicit location
descriptions.
@@ -3578,7 +3572,7 @@ Frame Description Entries (FDE). There is at least one CIE in every non-empty
.. note::
- Would this be increased to 5 to reflect the changes in the proposal?
+ Would this be increased to 5 to reflect the changes in these extensions?
4. ``augmentation`` (sequence of UTF-8 characters)
@@ -4243,8 +4237,9 @@ debugger information entries.
Examples
========
-The AMD GPU specific usage of the features in the proposal, including examples,
-is available at :ref:`amdgpu-dwarf-debug-information`.
+The AMD GPU specific usage of the features in these extensions, including
+examples, is available at *User Guide for AMDGPU Backend* section
+:ref:`amdgpu-dwarf-debug-information`.
.. note::
diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index f709bb8cf8e2..0a29f9e8f413 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -21,7 +21,7 @@ User Guide for AMDGPU Backend
AMDGPUOperandSyntax
AMDGPUInstructionSyntax
AMDGPUInstructionNotation
- AMDGPUDwarfProposalForHeterogeneousDebugging
+ AMDGPUDwarfExtensionsForHeterogeneousDebugging
Introduction
============
@@ -1160,14 +1160,14 @@ DWARF Debug Information
.. warning::
- This section describes a **provisional proposal** for AMDGPU DWARF [DWARF]_
- that is not currently fully implemented and is subject to change.
+ This section describes **provisional support** for AMDGPU DWARF [DWARF]_ that
+ is not currently fully implemented and is subject to change.
AMDGPU generates DWARF [DWARF]_ debugging information ELF sections (see
:ref:`amdgpu-elf-code-object`) which contain information that maps the code
object executable code and data to the source language constructs. It can be
used by tools such as debuggers and profilers. It uses features defined in
-:doc:`AMDGPUDwarfProposalForHeterogeneousDebugging` that are made available in
+:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging` that are made available in
DWARF Version 4 and DWARF Version 5 as an LLVM vendor extension.
This section defines the AMDGPU target architecture specific DWARF mappings.
@@ -1299,8 +1299,8 @@ Address Class Identifier
------------------------
The DWARF address class represents the source language memory space. See DWARF
-Version 5 section 2.12 which is updated by the propoal in
-:ref:`amdgpu-dwarf-segment_addresses`.
+Version 5 section 2.12 which is updated by the *DWARF Extensions For
+Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses`.
The DWARF address class mapping used for AMDGPU is defined in
:ref:`amdgpu-dwarf-address-class-mapping-table`.
@@ -1321,8 +1321,8 @@ The DWARF address class mapping used for AMDGPU is defined in
``DW_ADDR_AMDGPU_region`` 0x8000 Region (GDS)
========================= ====== =================
-The DWARF address class values defined in the proposal at
-:ref:`amdgpu-dwarf-segment_addresses` are used.
+The DWARF address class values defined in the *DWARF Extensions For
+Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses` are used.
In addition, ``DW_ADDR_AMDGPU_region`` is encoded as a vendor extension. This is
available for use for the AMD extension for access to the hardware GDS memory
@@ -1341,8 +1341,8 @@ Address Space Identifier
------------------------
DWARF address spaces correspond to target architecture specific linear
-addressable memory areas. See DWARF Version 5 section 2.12 and
-:ref:`amdgpu-dwarf-segment_addresses`.
+addressable memory areas. See DWARF Version 5 section 2.12 and *DWARF Extensions
+For Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses`.
The DWARF address space mapping used for AMDGPU is defined in
:ref:`amdgpu-dwarf-address-space-mapping-table`.
@@ -1447,8 +1447,8 @@ DWARF lane identifies specify a target architecture lane position for hardware
that executes in a SIMD or SIMT manner, and on which a source language maps its
threads of execution onto those lanes. The DWARF lane identifier is pushed by
the ``DW_OP_LLVM_push_lane`` DWARF expression operation. See DWARF Version 5
-section 2.5 which is updated by the proposal in
-:ref:`amdgpu-dwarf-operation-expressions`.
+section 2.5 which is updated by *DWARF Extensions For Heterogeneous Debugging*
+section :ref:`amdgpu-dwarf-operation-expressions`.
For AMDGPU, the lane identifier corresponds to the hardware lane ID of a
wavefront. It is numbered from 0 to the wavefront size minus 1.
@@ -1483,7 +1483,8 @@ Debugger Information Entry Attributes
This section describes how certain debugger information entry attributes are
used by AMDGPU. See the sections in DWARF Version 5 section 2 which are updated
-by the proposal in :ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
+by *DWARF Extensions For Heterogeneous Debugging* section
+:ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
.. _amdgpu-dwarf-dw-at-llvm-lane-pc:
@@ -1938,8 +1939,8 @@ DWARF Version 5 section 6.2.4):
Source text for online-compiled programs (for example, those compiled by the
OpenCL language runtime) may be embedded into the DWARF Version 5 line table.
-See DWARF Version 5 section 6.2.4.1 which is updated by the proposal in
-:ref:`DW_LNCT_LLVM_source
+See DWARF Version 5 section 6.2.4.1 which is updated by *DWARF Extensions For
+Heterogeneous Debugging* section :ref:`DW_LNCT_LLVM_source
<amdgpu-dwarf-line-number-information-dw-lnct-llvm-source>`.
The Clang option used to control source embedding in AMDGPU is defined in
More information about the llvm-commits
mailing list