diff --git a/llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst rename from llvm/docs/AMDGPUDwarfProposalForHeterogeneousDebugging.rst rename to llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst --- 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 `] to support heterogeneous debugging. It is not currently fully implemented and is subject to change. @@ -37,43 +37,37 @@ To support debugging heterogeneous programs several features that are not provided by current DWARF Version 5 [:ref:`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 @@ Motivation ========== -This document proposes a set of backwards compatible extensions to DWARF Version -5 [:ref:`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 `] 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 `] open source Radeon Open Compute Platform (ROCm) [:ref:`AMD-ROCm @@ -102,21 +95,21 @@ compiler [:ref:`GCC `] and the Perforce TotalView HPC debugger [:ref:`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 @@ 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 @@ 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 differently, but does +For those familiar with the definition of location descriptions in DWARF Version +5, the definitions in these extensions are presented differently, 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 @@ 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 @@ 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 @@ .. 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 @@ 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 @@ 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 @@ .. 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 @@ .. 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 different memory areas for @@ -2751,7 +2745,7 @@ 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 @@ 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 @@ .. 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 @@ .. 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 @@ .. 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 @@ 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 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -21,7 +21,7 @@ AMDGPUOperandSyntax AMDGPUInstructionSyntax AMDGPUInstructionNotation - AMDGPUDwarfProposalForHeterogeneousDebugging + AMDGPUDwarfExtensionsForHeterogeneousDebugging Introduction ============ @@ -1160,14 +1160,14 @@ .. 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 @@ ------------------------ 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 @@ ``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 @@ ------------------------ 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 @@ 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 @@ 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 @@ 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 `. The Clang option used to control source embedding in AMDGPU is defined in