[AMDGPU][NFC] Update to DWARF extension for heterogeneous debugging

[t-tye]

Summary

• Update documentation on the DWARF extension for heterogeneous debugging to better reference the DWARF Version 5 standard.
• Numerous other corrections.

[t-tye]

Additional corrections.

[t-tye]

• Add section numbers.

[t-tye]

Improve the summary of the extensions.

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

 .. warning::
 
    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.
 
 .. _amdgpu-dwarf-introduction:
 
-Introduction
-============
+1. Introduction
+===============
 
 AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] has been working on supporting heterogeneous
-computing through the AMD Radeon Open Compute Platform (ROCm) [:ref:`AMD-ROCm
-<amdgpu-dwarf-AMD-ROCm>`]. A heterogeneous computing program can be written in a
-high level language such as C++ or Fortran with OpenMP pragmas, OpenCL, or HIP
-(a portable C++ programming environment for heterogeneous computing [:ref:`HIP
+computing. A heterogeneous computing program can be written in a high level
+language such as C++ or Fortran with OpenMP pragmas, OpenCL, or HIP (a portable
+C++ programming environment for heterogeneous computing [:ref:`HIP
 <amdgpu-dwarf-HIP>`]). A heterogeneous compiler and runtime allows a program to
 execute on multiple devices within the same native process. Devices could
 include CPUs, GPUs, DSPs, FPGAs, or other special purpose accelerators.
 Currently HIP programs execute on systems with CPUs and GPUs.
 
-ROCm is fully open sourced and includes contributions to open source projects
-such as LLVM for compilation [:ref:`LLVM <amdgpu-dwarf-LLVM>`] and GDB for
-debugging [:ref:`GDB <amdgpu-dwarf-GDB>`], as well as collaboration with other
-third party projects such as the GCC compiler [:ref:`GCC <amdgpu-dwarf-GCC>`]
-and the Perforce TotalView HPC debugger [:ref:`Perforce-TotalView
+The AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] ROCm platform [:ref:`AMD-ROCm
+<amdgpu-dwarf-AMD-ROCm>`] is an implementation of the industry standard for
+heterogeneous computing devices defined by the Heterogeneous System Architecture
+(HSA) Foundation [:ref:`HSA <amdgpu-dwarf-HSA>`]. It is open sourced and
+includes contributions to open source projects such as LLVM [:ref:`LLVM
+<amdgpu-dwarf-LLVM>`] for compilation and GDB for debugging [:ref:`GDB
+<amdgpu-dwarf-GDB>`].
+
+The LLVM compiler has upstream support for commercially available AMD GPU
+hardware (AMDGPU) [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The open
+source ROCgdb [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`] GDB based debugger
+also has support for AMDGPU which is being upstreamed. Support for AMDGPU is
+also being added by third parties to the GCC [:ref:`GCC <amdgpu-dwarf-GCC>`]
+compiler and the Perforce TotalView HPC Debugger [:ref:`Perforce-TotalView
 <amdgpu-dwarf-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 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-changes-relative-to-dwarf-version-5` section containing the
+been identified. The :ref:`amdgpu-dwarf-extensions` section gives an overview of
+the extensions devised to address the missing features. The extensions seek to
+be general in nature and backwards compatible with DWARF Version 5. Their goal
+is to be applicable to meeting the needs of any heterogeneous system and not be
+vendor or architecture specific. That is followed by appendix
+:ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` which contains 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 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 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 these extensions
-which is providing experience and insights. We plan to upstream the changes to
-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.
-
-.. _amdgpu-dwarf-motivation:
-
-Motivation
-==========
-
-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 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
-<amdgpu-dwarf-AMD-ROCm>`] which is an implementation of the industry standard
-for heterogeneous computing devices defined by the Heterogeneous System
-Architecture (HSA) Foundation [:ref:`HSA <amdgpu-dwarf-HSA>`]. ROCm includes the
-LLVM compiler [:ref:`LLVM <amdgpu-dwarf-LLVM>`] with upstreamed support for
-AMDGPU [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The goal is to also add
-the GDB debugger [:ref:`GDB <amdgpu-dwarf-GDB>`] with upstreamed support for
-AMDGPU [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`]. In addition, the goal is
-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 extensions are intended to be vendor and architecture neutral. They
-are believed to apply to other heterogeneous 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 extensions also include improved
-support for optimized code on any architecture. Some of the generalizations may
-also benefit other issues that have been raised.
+There are a number of notes included that raise open questions, or provide
+alternative approaches that may be worth considering. Then appendix
+:ref:`amdgpu-dwarf-examples` links to the AMD GPU specific usage of the
+extensions that includes an example. Finally, appendix
+:ref:`amdgpu-dwarf-references` provides references to further information.
+
+.. _amdgpu-dwarf-extensions:
+
+1. Extensions
+=============
 
-The extensions have evolved through collaboration with many individuals and
+The extensions continue to evolve through 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.
+The inputs provided and insights gained so far have been incorporated into this
+current version. The plan is to participate in upstreaming the work and
+addressing any feedback. If there is general interest then some or all of these
+extensions could be submitted as future DWARF standard proposals.
 
-AMDGPU optimized code may spill vector registers to non-global address space
-memory, and this spilling may be done only for lanes that are active on entry
-to the subprogram. To support this, a location description that can be created
-as a masked select is required. See ``DW_OP_LLVM_select_bit_piece``.
-
-Since the active lane mask may be held in a register, a way to get the value
-of a register on entry to a subprogram is required. To support this an
-operation that returns the caller value of a register as specified by the Call
-Frame Information (CFI) is required. See ``DW_OP_LLVM_call_frame_entry_reg``
-and :ref:`amdgpu-dwarf-call-frame-information`.
+The general principles in designing the extensions have been:
 
-Current DWARF uses an empty expression to indicate an undefined location
-description. Since the masked select composite location description operation
-takes more than one location description, it is necessary to have an explicit
-way to specify an undefined location description. Otherwise it is not possible
-to specify that a particular one of the input location descriptions is
-undefined. See ``DW_OP_LLVM_undefined``.
+1.  Be backwards compatible with the DWARF Version 5 [:ref:`DWARF
+    <amdgpu-dwarf-DWARF>`] standard.
+
+2.  Be vendor and architecture neutral. They are intended to apply to other
+    heterogeneous hardware devices including GPUs, DSPs, FPGAs, and other
+    specialized hardware. These collectively include similar characteristics and
+    requirements as AMDGPU devices.
+
+3.  Provide improved optimization support for non-GPU code. For example, some
+    extensions apply to traditional CPU hardware that supports large vector
+    registers. Compilers can map source languages, and source language
+    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.
+
+4.  Fully define well-formed DWARF in a consistent style based on the DWARF
+    Version 5 specification.
+
+It is possible that some of the generalizations may also benefit other DWARF
+issues that have been raised.
+
+The remainder of this section enumerates the extensions and provides motivation
+for each in terms of heterogeneous debugging.
+
+.. _amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack:
+
+2.1 Allow Location Description on the DWARF Expression Stack
+------------------------------------------------------------
+
+DWARF Version 5 does not allow location descriptions to be entries on the DWARF
+expression stack. They can only be the final result of the evaluation of a DWARF
+expression. However, by allowing a location description to be a first-class
+entry on the DWARF expression stack it becomes possible to compose expressions
+containing both values and location descriptions naturally. It allows objects to
+be located in any kind of memory address space, in registers, be implicit
+values, be undefined, or a composite of any of these.
+
+By extending DWARF carefully, all existing DWARF expressions can retain their
+current semantic meaning. DWARF has implicit conversions that convert from a
+value that represents an address in the default address space to a memory
+location description. This can be extended to allow a default address space
+memory location description to be implicitly converted back to its address
+value. This allows all DWARF Version 5 expressions to retain their same meaning,
+while enabling the ability to explicitly create memory location descriptions in
+non-default address spaces and generalizing the power of composite location
+descriptions to any kind of location description.
+
+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 composed
+of any kind of location description, and the ability to support objects located
+at multiple places. Collectively these changes expand the set of architectures
+that can be supported and improves support for optimized code.
+
+Several approaches were considered, and the one presented, together with the
+extensions it enables, appears to be the simplest and cleanest one that offers
+the greatest improvement of DWARF's ability to support debugging optimized GPU
+and non-GPU 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
+location descriptions. It is anticipated that will also be the case for other
+debuggers and compilers.
+
+GDB has been modified to evaluate DWARF Version 5 expressions with location
+descriptions as stack entries and with implicit conversions. All GDB tests have
+passed, except one that turned out to be an invalid test case by DWARF Version 5
+rules. The code in GDB actually became simpler as all evaluation is done on a
+single stack and there was no longer a need to maintain a separate structure for
+the location description results. This gives confidence in backwards
+compatibility.
+
+See :ref:`amdgpu-dwarf-expressions` and nested sections.
+
+This extension is separately described at *Allow Location Descriptions on the
+DWARF Expression Stack* [:ref:`AMDGPU-DWARF-LOC
+<amdgpu-dwarf-AMDGPU-DWARF-LOC>`].
+
+2.2 Generalize CFI to Allow Any Location Description Kind
+---------------------------------------------------------
 
 CFI describes restoring callee saved registers that are spilled. Currently CFI
 only allows a location description that is a register, memory address, or
-implicit location description. AMDGPU optimized code may spill scalar
-registers into portions of vector registers. This requires extending CFI to
-allow any location description. See
-:ref:`amdgpu-dwarf-call-frame-information`.
+implicit location description. AMDGPU optimized code may spill scalar registers
+into portions of vector registers. This requires extending CFI to allow any
+location description kind to be supported.
 
-The vector registers of the AMDGPU are represented as their full wavefront
-size, meaning the wavefront size times the dword size. This reflects the
-actual hardware and allows the compiler to generate DWARF for languages that
-map a thread to the complete wavefront. It also allows more efficient DWARF to
-be generated to describe the CFI as only a single expression is required for
-the whole vector register, rather than a separate expression for each lane's
-dword of the vector register. It also allows the compiler to produce DWARF
-that indexes the vector register if it spills scalar registers into portions
-of a vector register.
+See :ref:`amdgpu-dwarf-call-frame-information`.
 
-Since DWARF stack value entries have a base type and AMDGPU registers are a
-vector of dwords, the ability to specify that a base type is a vector is
-required. See ``DW_AT_LLVM_vector_size``.
+2.3 Generalize DWARF Operation Expressions to Support Multiple Places
+---------------------------------------------------------------------
 
-If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner,
-then the variable DWARF location expressions must compute the location for a
-single lane of the wavefront. Therefore, a DWARF operation is required to 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_uconst``, and
-``DW_OP_LLVM_bit_offset``.
-
-If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner
-the compiler can use the AMDGPU execution mask register to control which lanes
-are active. To describe the conceptual location of non-active lanes a DWARF
-expression is needed that can compute a per lane PC. For efficiency, this is
-done for the wavefront as a whole. This expression benefits by having a masked
-select composite location description operation. This requires an attribute
-for source location of each lane. The AMDGPU may update the execution mask for
-whole wavefront operations and so needs an attribute that computes the current
-active lane mask. See ``DW_OP_LLVM_select_bit_piece``, ``DW_OP_LLVM_extend``,
-``DW_AT_LLVM_lane_pc``, and ``DW_AT_LLVM_active_lane``.
+In DWARF Version 5 a location description is defined as a single location
+description or a location list. A location list is defined as either
+effectively an undefined location description or as one or more single
+location descriptions to describe an object with multiple places.
+
+With
+:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`,
+the ``DW_OP_push_object_address`` and ``DW_OP_call*`` operations can put a
+location description on the stack. Furthermore, debugger information entry
+attributes such as ``DW_AT_data_member_location``, ``DW_AT_use_location``, and
+``DW_AT_vtable_elem_location`` are defined as pushing a location description on
+the expression stack before evaluating the expression.
+
+DWARF Version 5 only allows the stack to contain values and so only a single
+memory address can be on the stack. This makes these operations and attributes
+incapable of handling location descriptions with multiple places, or places
+other than memory.
+
+Since
+:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
+allows 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 how to access
+the field of an object can be evaluated with a location description that has
+multiple places and will result in a location description with multiple places.
+
+With this change, the separate DWARF Version 5 sections that described DWARF
+expressions and location lists are unified into a single section that describes
+DWARF expressions in general. This unification is a natural consequence of, and
+a necessity of, allowing location descriptions to be part of the evaluation
+stack.
+
+See :ref:`amdgpu-dwarf-location-description`.
+
+2.4 Generalize Offsetting of Location Descriptions
+--------------------------------------------------
+
+The ``DW_OP_plus`` and ``DW_OP_minus`` operations 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 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_uconst``, and
+``DW_OP_LLVM_bit_offset`` offset operations are added.
+
+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 an
+evaluation error, 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. Therefore, the
+offset operation define that integer overflow is ill-formed. This is in contrast
+to the ``DW_OP_plus``, ``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic
+operations which define that it causes wrap-around.
+
+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. The
+DWARF expression of ``DW_TAG_ptr_to_member_type`` can use the offset operations
+without regard to what kind of location description was pushed.
+
+Since
+:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` has
+generalized location storage to be bit indexable, ``DW_OP_LLVM_bit_offset``
+generalizes DWARF to work with bit fields. This is generally not possible in
+DWARF Version 5.
+
+The ``DW_OP_*piece`` operations only allow literal indices. A way to use a
+computed offset of an arbitrary location description (such as a vector register)
+is required. The offset operations provide this ability since they can be used
+to compute a location description on the stack.
+
+See ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and
+``DW_OP_LLVM_bit_offset`` in
+:ref:`amdgpu-dwarf-general-location-description-operations`.
+
+2.5 Generalize Creation of Undefined Location Descriptions
+----------------------------------------------------------
+
+Current DWARF uses an empty expression to indicate an undefined location
+description. Since
+:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
+allows location descriptions to be created on the stack, it is necessary to have
+an explicit way to specify an undefined location description.
+
+For example, the ``DW_OP_LLVM_select_bit_piece`` (see
+:ref:`amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware`)
+operation takes more than one location description on the stack. Without this
+ability, it is not possible to specify that a particular one of the input
+location descriptions is undefined.
+
+See the ``DW_OP_LLVM_undefined`` operation in
+:ref:`amdgpu-dwarf-undefined-location-description-operations`.
+
+2.6 Generalize Creation of Composite Location Descriptions
+----------------------------------------------------------
+
+To allow composition of composite location descriptions, an explicit operation
+that indicates the end of the definition of a composite location description is
+required. This can be implied if the end of a DWARF expression is reached,
+allowing current DWARF expressions to remain legal.
+
+See ``DW_OP_LLVM_piece_end`` in
+:ref:`amdgpu-dwarf-composite-location-description-operations`.
+
+2.7 Generalize DWARF Base Objects to Allow Any Location Description Kind
+------------------------------------------------------------------------
+
+The number of registers and the cost of memory operations is much higher for
+AMDGPU than a typical CPU. The compiler attempts to optimize whole variables and
+arrays into registers.
+
+Currently DWARF only allows ``DW_OP_push_object_address`` and related operations
+to work with a global memory location. To support AMDGPU optimized code it is
+required to generalize DWARF to allow any location description to be used. This
+allows registers, or composite location descriptions that may be a mixture of
+memory, registers, or even implicit values.
+
+See ``DW_OP_push_object_address`` in
+:ref:`amdgpu-dwarf-general-location-description-operations`.
+
+2.8 General Support for Address Spaces
+--------------------------------------
 
 AMDGPU needs to be able to describe addresses that are in different kinds of
 memory. Optimized code may need to describe a variable that resides in pieces
 that are in different kinds of storage which may include parts of registers,
 memory that is in a mixture of memory kinds, implicit values, or be undefined.
+
 DWARF has the concept of segment addresses. However, the segment cannot be
 specified within a DWARF expression, which is only able to specify the offset
 portion of a segment address. The segment index is only provided by the entity
-that specifies the DWARF expression. Therefore, the segment index is a
-property that can only be put on complete objects, such as a variable. That
-makes it only suitable for describing an entity (such as variable or
-subprogram code) that is in a single kind of memory. Therefore, AMDGPU uses
-the DWARF concept of address spaces. For example, a variable may be allocated
-in a register that is partially spilled to the call stack which is in the
-private address space, and partially spilled to the local address space.
+that specifies the DWARF expression. Therefore, the segment index is a property
+that can only be put on complete objects, such as a variable. That makes it only
+suitable for describing an entity (such as variable or subprogram code) that is
+in a single kind of memory.
+
+Therefore, AMDGPU uses the DWARF concept of address spaces. For example, a
+variable may be allocated in a register that is partially spilled to the call
+stack which is in the private address space, and partially spilled to the local
+address space.
 
 DWARF uses the concept of an address in many expression operations but does not
 define how it relates to address spaces. For example,
 ``DW_OP_push_object_address`` pushes the address of an object. Other contexts
 implicitly push an address on the stack before evaluating an expression. For
 example, the ``DW_AT_use_location`` attribute of the
-``DW_TAG_ptr_to_member_type``. The expression that uses the address needs to
-do so in a general way and not need to be dependent on the address space of
-the address. For example, a pointer to member value may want to be applied to
-an object that may reside in any address space.
-
-The number of registers and the cost of memory operations is much higher for
-AMDGPU than a typical CPU. The compiler attempts to optimize whole variables
-and arrays into registers. Currently DWARF only allows
-``DW_OP_push_object_address`` and related operations to work with a global
-memory location. To support AMDGPU optimized code it is required to generalize
-DWARF to allow any location description to be used. This allows registers, or
-composite location descriptions that may be a mixture of memory, registers, or
-even implicit values.
-
-DWARF Version 5 does not allow location descriptions to be entries on the
-DWARF stack. They can only be the final result of the evaluation of a DWARF
-expression. However, by allowing a location description to be a first-class
-entry on the DWARF stack it becomes possible to compose expressions containing
-both values and location descriptions naturally. It allows objects to be
-located in any kind of memory address space, in registers, be implicit values,
-be undefined, or a composite of any of these. By extending DWARF carefully,
-all existing DWARF expressions can retain their current semantic meaning.
-DWARF has implicit conversions that convert from a value that represents an
-address in the default address space to a memory location description. This
-can be extended to allow a default address space memory location description
-to be implicitly converted back to its address value. This allows all DWARF
-Version 5 expressions to retain their same meaning, while adding the ability
-to explicitly create memory location descriptions in non-default address
-spaces and generalizing the power of composite location descriptions to any
-kind of location description. See :ref:`amdgpu-dwarf-operation-expressions`.
-
-To allow composition of composite location descriptions, an explicit operation
-that indicates the end of the definition of a composite location description
-is required. This can be implied if the end of a DWARF expression is reached,
-allowing current DWARF expressions to remain legal. See
-``DW_OP_LLVM_piece_end``.
-
-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
-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_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 an evaluation error, 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.
+``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type
+which may apply to objects allocated in different kinds of storage. Therefore,
+it is desirable that the expression that uses the address can do so without
+regard to what kind of storage it specifies, including the address space of a
+memory location description. For example, a pointer to member value may want to
+be applied to an object that may reside in any address space.
 
 The DWARF ``DW_OP_xderef*`` operations allow a value to be converted into an
 address of a specified address space which is then read. But it provides no
 way to create a memory location description for an address in the non-default
 address space. For example, AMDGPU variables can be allocated in the local
-address space at a fixed address. It is required to have an operation to
-create an address in a specific address space that can be used to define the
-location description of the variable. Defining this operation to produce a
-location description allows the size of addresses in an address space to be
-larger than the generic type. See ``DW_OP_LLVM_form_aspace_address``.
-
-If the ``DW_OP_LLVM_form_aspace_address`` operation had to produce a value
-that can be implicitly converted to a memory location description, then it
-would be limited to the size of the generic type which matches the size of the
-default address space. Its value would be undefined and likely not match any
-value in the actual program. By making the result a location description, it
-allows a consumer great freedom in how it implements it. The implicit
-conversion back to a value can be limited only to the default address space to
-maintain compatibility with DWARF Version 5. For other address spaces the
-producer can use the new operations that explicitly specify the address space.
+address space at a fixed address.
 
-``DW_OP_breg*`` treats the register as containing an address in the default
-address space. It is required to be able to specify the address space of the
-register value. See ``DW_OP_LLVM_aspace_bregx``.
+The ``DW_OP_LLVM_form_aspace_address`` (see
+:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is defined
+to create a memory location description from an address and address space. If
+can be used to specify the location of a variable that is allocated in a
+specific address space. This allows the size of addresses in an address space to
+be larger than the generic type. It also allows a consumer great implementation
+freedom. It allows the implicit conversion back to a value to be limited only to
+the default address space to maintain compatibility with DWARF Version 5. For
+other address spaces the producer can use the new operations that explicitly
+specify the address space.
+
+In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been
+defined to produce a value, and an implicit conversion to a memory location
+description was defined, then it would be limited to the size of the generic
+type (which matches the size of the default address space). An implementation
+would likely have to use *reserved ranges* of value to represent different
+address spaces. Such a value would likely not match any address value in the
+actual hardware. That would require the consumer to have special treatment for
+such values.
 
-Similarly, ``DW_OP_implicit_pointer`` treats its implicit pointer value as
-being in the default address space. It is required to be able to specify the
-address space of the pointer value. See
-``DW_OP_LLVM_aspace_implicit_pointer``.
+``DW_OP_breg*`` treats the register as containing an address in the default
+address space. A ``DW_OP_LLVM_aspace_bregx`` (see
+:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is added
+to allow the address space of the address held in a register to be specified.
+
+Similarly, ``DW_OP_implicit_pointer`` treats its implicit pointer value as being
+in the default address space. A ``DW_OP_LLVM_aspace_implicit_pointer``
+(:ref:`amdgpu-dwarf-implicit-location-description-operations`) operation is
+added to allow the address space to be specified.
 
 Almost all uses of addresses in DWARF are limited to defining location
 descriptions, or to be dereferenced to read memory. The exception is
-``DW_CFA_val_offset`` which uses the address to set the value of a register.
-By defining the CFA DWARF expression as being a memory location description,
-it can maintain what address space it is, and that can be used to convert the
-offset address back to an address in that address space. See
+``DW_CFA_val_offset`` which uses the address to set the value of a register. In
+order to support address spaces, the CFA DWARF expression is defined to be a
+memory location description. This allows it to specify an address space which is
+used to convert the offset address back to an address in that address space. See
 :ref:`amdgpu-dwarf-call-frame-information`.
 
-This approach allows all existing DWARF to have the identical semantics. It
-allows the compiler to explicitly specify the address space it is using. For
-example, a compiler could choose to access private memory in a swizzled manner
-when mapping a source language to a wavefront in a SIMT manner, or to access
-it in an unswizzled manner if mapping the same language with the wavefront
-being the thread. It also allows the compiler to mix the address space it uses
-to access private memory. For example, for SIMT it can still spill entire
-vector registers in an unswizzled manner, while using a swizzled private
-memory for SIMT variable access. This approach allows memory location
-descriptions for different address spaces to be combined using the regular
-``DW_OP_*piece`` operations.
+This approach of extending memory location descriptions to support address
+spaces, allows all existing DWARF Version 5 expressions to have the identical
+semantics. It allows the compiler to explicitly specify the address space it is
+using. For example, a compiler could choose to access private memory in a
+swizzled manner when mapping a source language thread to the lane of a wavefront
+in a SIMT manner. Or a compiler could choose to access it in an unswizzled
+manner if mapping the same language with the wavefront being the thread.
+
+It also allows the compiler to mix the address space it uses to access private
+memory. For example, for SIMT it can still spill entire vector registers in an
+unswizzled manner, while using a swizzled private memory for SIMT variable
+access.
+
+This approach also allows memory location descriptions for different address
+spaces to be combined using the regular ``DW_OP_*piece`` operations.
 
-Location descriptions are an abstraction of storage, they give freedom to the
+Location descriptions are an abstraction of storage. They give freedom to the
 consumer on how to implement them. They allow the address space to encode lane
-information so they can be used to read memory with only the memory
-description and no extra arguments. The same set of operations can operate on
+information so they can be used to read memory with only the memory location
+description and no extra information. The same set of operations can operate on
 locations independent of their kind of storage. The ``DW_OP_deref*`` therefore
-can be used on any storage kind. ``DW_OP_xderef*`` is unnecessary, except to
-become a more compact way to convert a non-default address space address
-followed by dereferencing it.
+can be used on any storage kind, including memory location descriptions of
+different address spaces. Therefore, the ``DW_OP_xderef*`` operations are
+unnecessary, except to become a more compact way to encode a non-default address
+space address followed by dereferencing it. See
+:ref:`amdgpu-dwarf-general-operations`.
 
-In DWARF Version 5 a location description is defined as a single location
-description or a location list. A location list is defined as either
-effectively an undefined location description or as one or more single
-location descriptions to describe an object with multiple places. The
-``DW_OP_push_object_address`` and ``DW_OP_call*`` operations can put a
-location description on the stack. Furthermore, debugger information entry
-attributes such as ``DW_AT_data_member_location``, ``DW_AT_use_location``, and
-``DW_AT_vtable_elem_location`` are defined as pushing a location description
-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 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
-how to access the field of an object can be evaluated with a location
-description that has multiple places and will result in a location description
-with multiple places as expected. With this change, the separate DWARF Version
-5 sections that described DWARF expressions and location lists have been
-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.
+2.9 Support for Vector Base Types
+---------------------------------
 
-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
-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 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
-location descriptions. It is anticipated that will also be the case for other
-debuggers and compilers.
+The vector registers of the AMDGPU are represented as their full wavefront
+size, meaning the wavefront size times the dword size. This reflects the
+actual hardware and allows the compiler to generate DWARF for languages that
+map a thread to the complete wavefront. It also allows more efficient DWARF to
+be generated to describe the CFI as only a single expression is required for
+the whole vector register, rather than a separate expression for each lane's
+dword of the vector register. It also allows the compiler to produce DWARF
+that indexes the vector register if it spills scalar registers into portions
+of a vector register.
 
-As an experiment, GDB was modified to evaluate DWARF Version 5 expressions
-with location descriptions as stack entries and implicit conversions. All GDB
-tests have passed, except one that turned out to be an invalid test by DWARF
-Version 5 rules. The code in GDB actually became simpler as all evaluation was
-on the stack and there was no longer a need to maintain a separate structure
-for the location description result. This gives confidence of the backwards
-compatibility.
+Since DWARF stack value entries have a base type and AMDGPU registers are a
+vector of dwords, the ability to specify that a base type is a vector is
+required.
+
+See ``DW_AT_LLVM_vector_size`` in :ref:`amdgpu-dwarf-literal-operations`.
+
+.. _amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions:
+
+2.10 DWARF Operations to Create Vector Composite Location Descriptions
+----------------------------------------------------------------------
+
+AMDGPU optimized code may spill vector registers to non-global address space
+memory, and this spilling may be done only for SIMT lanes that are active on
+entry to the subprogram.
+
+To support this, a composite location description that can be created as a
+masked select is required. In addition, an operation that creates a composite
+location description that is a vector on another location description is needed.
+
+An example that uses these operations is referenced in the
+:ref:`amdgpu-dwarf-examples` appendix.
+
+See ``DW_OP_LLVM_select_bit_piece`` and ``DW_OP_LLVM_extend`` in
+:ref:`amdgpu-dwarf-composite-location-description-operations`.
+
+2.11 DWARF Operation to Access Call Frame Entry Registers
+---------------------------------------------------------
+
+As described in
+:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`,
+a DWARF expression involving the set of SIMT lanes active on entry to a
+subprogram is required. The SIMT active lane mask may be held in a register that
+is modified as the subprogram executes. However, its value may be saved on entry
+to the subprogram.
+
+The  Call Frame Information (CFI) already encodes such register saving, so it is
+more efficient to provide an operation to return the location of a saved
+register than have to generate a loclist to describe the same information. This
+is now possible since
+:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
+allows location descriptions on the stack.
+
+See ``DW_OP_LLVM_call_frame_entry_reg`` in
+:ref:`amdgpu-dwarf-general-location-description-operations` and
+:ref:`amdgpu-dwarf-call-frame-information`.
+
+2.12 Support for Source Languages Mapped to SIMT Hardware
+---------------------------------------------------------
+
+If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner,
+then the variable DWARF location expressions must compute the location for a
+single lane of the wavefront. Therefore, a DWARF operation is required to denote
+the current lane, much like ``DW_OP_push_object_address`` denotes the current
+object.
+
+See ``DW_OP_LLVM_push_lane`` in :ref:`amdgpu-dwarf-base-type-entries`.
+
+.. _amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware:
+
+2.13 Support for Divergent Control Flow of SIMT Hardware
+--------------------------------------------------------
+
+If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner the
+compiler can use the AMDGPU execution mask register to control which lanes are
+active. To describe the conceptual location of non-active lanes requires an
+attribute that has an expression that computes the source location PC for each
+lane.
+
+For efficiency, the expression calculates the source location the wavefront as a
+whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see
+:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`)
+operation.
+
+The AMDGPU may update the execution mask to perform whole wavefront operations.
+Therefore, there is a need for an attribute that computes the current active
+lane mask. This can have an expression that may evaluate to the SIMT active lane
+mask register or to a saved mask when in whole wavefront execution mode.
+
+An example that uses these attributes is referenced in the
+:ref:`amdgpu-dwarf-examples` appendix.
+
+See ``DW_AT_LLVM_lane_pc`` and ``DW_AT_LLVM_active_lane`` in
+:ref:`amdgpu-dwarf-composite-location-description-operations`.
+
+2.14 Define Source Language Address Classes
+-------------------------------------------
+
+AMDGPU supports languages, such as OpenCL [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`],
+that define source language address classes. Support is added to define language
+specific address classes so they can be used in a consistent way by consumers.
+
+It would also be desirable to add support for using address classes in defining
+source language types. DWARF Version 5 only supports using target architecture
+specific address spaces.
+
+See :ref:`amdgpu-dwarf-segment_addresses`.
+
+2.15 Define Augmentation Strings to Support Multiple Extensions
+---------------------------------------------------------------
+
+A ``DW_AT_LLVM_augmentation`` attribute is added to a compilation unit debugger
+information entry to indicate that there is additional target architecture
+specific information in the debugging information entries of that compilation
+unit. This allows a consumer to know what extensions are present in the debugger
+information entries as is possible with the augmentation string of other
+sections. See .
+
+The format that should be used for an augmentation string is also recommended.
+This allows a consumer to parse the string when it contains information from
+multiple vendors. Augmentation strings occur in the ``DW_AT_LLVM_augmentation``
+attribute, in the lookup by name table, and in the CFI Common Information Entry
+(CIE).
+
+See :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`,
+:ref:`amdgpu-dwarf-name-index-section-header`, and
+:ref:`amdgpu-dwarf-structure_of-call-frame-information`.
+
+2.16 Support Embedding Source Text for Online Compilation
+---------------------------------------------------------
+
+AMDGPU supports programming languages that include online compilation where the
+source text may be created at runtime. For example, the OpenCL and HIP language
+runtimes support online compilation. To support is, a way to embed the source
+text in the debug information is provided.
+
+See :ref:`amdgpu-dwarf-line-number-information`.
+
+2.17 Allow MD5 Checksums to be Optionally Present
+-------------------------------------------------
+
+In DWARF Version 5 the file timestamp and file size can be optional, but if the
+MD5 checksum is present it must be valid for all files. This is a problem if
+using link time optimization to combine compilation units where some have MD5
+checksums and some do not. Therefore, sSupport to allow MD5 checksums to be
+optionally present in the line table is added.
+
+See :ref:`amdgpu-dwarf-line-number-information`.
 
-Since the AMDGPU supports languages such as OpenCL [:ref:`OpenCL
-<amdgpu-dwarf-OpenCL>`], there is a need to define source language address
-classes so they can be used in a consistent way by consumers. It would also be
-desirable to add support for using them in defining language types rather than
-the current target architecture specific address spaces. See
-:ref:`amdgpu-dwarf-segment_addresses`.
-
-A ``DW_AT_LLVM_augmentation`` attribute is added to a compilation unit
-debugger information entry to indicate that there is additional target
-architecture specific information in the debugging information entries of that
-compilation unit. This allows a consumer to know what extensions are present
-in the debugger information entries as is possible with the augmentation
-string of other sections. The format that should be used for the augmentation
-string in the lookup by name table and CFI Common Information Entry is also
-recommended to allow a consumer to parse the string when it contains
-information from multiple vendors.
-
-The AMDGPU supports programming languages that include online compilation
-where the source text may be created at runtime. Therefore, a way to embed the
-source text in the debug information is required. For example, the OpenCL
-language runtime supports online compilation. See
-:ref:`amdgpu-dwarf-line-number-information`.
-
-Support to allow MD5 checksums to be optionally present in the line table is
-added. This allows linking together compilation units where some have MD5
-checksums and some do not. In DWARF Version 5 the file timestamp and file size
-can be optional, but if the MD5 checksum is present it must be valid for all
-files. See :ref:`amdgpu-dwarf-line-number-information`.
-
-Support is added for the HIP programming language [:ref:`HIP
-<amdgpu-dwarf-HIP>`] which is supported by the AMDGPU. See
-:ref:`amdgpu-dwarf-language-names`.
-
-The following sections provide the definitions for the additional operations,
-as well as clarifying how existing expression operations, CFI operations, and
-attributes behave with respect to generalized location descriptions that
-support address spaces and location descriptions that support multiple places.
-It has been defined such that it is backwards compatible with DWARF Version 5.
-The definitions are intended to fully define well-formed DWARF in a consistent
-style based on the DWARF Version 5 specification. Non-normative text is shown
-in *italics*.
+2.18 Add the HIP Programing Language
+------------------------------------
+
+The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported
+by the AMDGPU, is added.
+
+See :ref:`amdgpu-dwarf-language-names-table`.
+
+.. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
+
+A. Changes Relative to DWARF Version 5
+======================================
+
+.. note::
+
+  This appendix provides changes relative to DWARF Version 5. It has been
+  defined such that it is backwards compatible with DWARF Version 5.
+  Non-normative text is shown in *italics*. The section numbers generally
+  correspond to those in the DWARF Version 5 standard unless specified
+  otherwise. Definitions are given for the additional operations, as well as
+  clarifying how existing expression operations, CFI operations, and attributes
+  behave with respect to generalized location descriptions that support address
+  spaces and multiple places.
 
   The names for the new operations, attributes, and constants include "\
   ``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 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.
+  be implemented as an LLVM vendor extension to DWARF Version 5.
 
-.. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
+  .. note::
 
-Changes Relative to DWARF Version 5
-===================================
+    Notes are included to describe how the changes are to be applied to the
+    DWARF Version 5 standard. They also describe rational and issues that may
+    need further consideration.
 
-General Description
--------------------
+A.2 General Description
+-----------------------
 
-Attribute Types
-~~~~~~~~~~~~~~~
+A.2.2 Attribute Types
+~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This augments DWARF Version 5 section 2.2 and Table 2.2.
 
-The following table provides the additional attributes. See
-:ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
+The following table provides the additional attributes.
 
 .. table:: Attribute names
    :name: amdgpu-dwarf-attribute-names-table
 
    =========================== ====================================
    Attribute                   Usage
    =========================== ====================================
-   ``DW_AT_LLVM_active_lane``  SIMD or SIMT active lanes
-   ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string
-   ``DW_AT_LLVM_lane_pc``      SIMD or SIMT lane program location
-   ``DW_AT_LLVM_lanes``        SIMD or SIMT thread lane count
-   ``DW_AT_LLVM_vector_size``  Base type vector size
+   ``DW_AT_LLVM_active_lane``  SIMD or SIMT active lanes (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string (see :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`)
+   ``DW_AT_LLVM_lane_pc``      SIMD or SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_lanes``        SIMD or SIMT thread lane count (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_vector_size``  Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`)
    =========================== ====================================
 
 .. _amdgpu-dwarf-expressions:
 
-DWARF Expressions
-~~~~~~~~~~~~~~~~~
+A.2.5 DWARF Expressions
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This section, and its nested sections, replaces DWARF Version 5 section 2.5
   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.
 

 ill-formed or results in an evaluation error.
 
 A DWARF expression can either be encoded as an operation expression (see
 :ref:`amdgpu-dwarf-operation-expressions`), or as a location list expression
 (see :ref:`amdgpu-dwarf-location-list-expressions`).
 
 .. _amdgpu-dwarf-expression-evaluation-context:
 
-DWARF Expression Evaluation Context
-+++++++++++++++++++++++++++++++++++
+A.2.5.1 DWARF Expression Evaluation Context
++++++++++++++++++++++++++++++++++++++++++++
 
 A DWARF expression is evaluated in a context that can include a number of
 context elements.  If multiple context elements are specified then they must be
 self consistent or the result of the evaluation is undefined. The context
 elements that can be specified are:
 
 *A current result kind*
 
   The kind of result required by the DWARF expression evaluation. If specified
   it can be a location description or a value.
 
 *A current thread*
 
   The target architecture thread identifier of the source program thread of
   execution for which a user presented expression is currently being evaluated.
 
   It is required for operations that are related to target architecture threads.
 
-  *For example, the* ``DW_OP_form_tls_address`` *operation and*
-  ``DW_OP_LLVM_form_aspace_address`` *operation when given an address space that
-  is thread specific.*
+  *For example, the* ``DW_OP_regval_type`` *operation, or the*
+  ``DW_OP_form_tls_address`` *and* ``DW_OP_LLVM_form_aspace_address``
+  *operations when given an address space that is thread specific.*
 
 *A current lane*
 
   The target architecture lane identifier of the source program thread of
   execution for which a user presented expression is currently being evaluated.
   This applies to languages that are implemented using a SIMD or SIMT execution
   model.
 
*A current compilation unit*
   the same compilation unit, including indicating if such references use the
   32-bit or 64-bit DWARF format. It can also provide the default address space
   address size if no current target architecture is specified.
 
   *For example, the* ``DW_OP_constx`` *and* ``DW_OP_addrx`` *operations.*
 
   *Note that this compilation unit may not be the same as the compilation unit
   determined from the loaded code object corresponding to the current program
-  location. For example, the evaluation of the expression E associated with a
-  ``DW_AT_location`` attribute of the debug information entry operand of the
-  ``DW_OP_call*`` operations is evaluated with the compilation unit that
-  contains E and not the one that contains the ``DW_OP_call*`` operation
+  location. For example, the evaluation of the expression E associated with a*
+  ``DW_AT_location`` *attribute of the debug information entry operand of the*
+  ``DW_OP_call*`` *operations is evaluated with the compilation unit that
+  contains E and not the one that contains the* ``DW_OP_call*`` *operation
   expression.*
 
 *A current target architecture*
 
   The target architecture.
 
   It is required for operations that specify target architecture specific
   entities.
 
   *For example, target architecture specific entities include DWARF register
   identifiers, DWARF lane identifiers, DWARF address space identifiers, the
   default address space, and the address space address sizes.*
 
   If specified:
 
   * If the current thread is specified, then the current target architecture
     must be the same as the target architecture of the current thread.
 
   * If the current compilation unit is specified, then the current target
-    architecture default address space address size must be the same as he
+    architecture default address space address size must be the same as the
     ``address_size`` field in the header of the current compilation unit and any
     associated entry in the ``.debug_aranges`` section.
 
   * If the current program location is specified, then the current target
     architecture must be the same as the target architecture of any line number
     information entry (see :ref:`amdgpu-dwarf-line-number-information`)
     corresponding to the current program location.
 
   * If the current program location is specified, then the current target
-    architecture default address space address size must be the same as he
+    architecture default address space address size must be the same as the
     ``address_size`` field in the header of any entry corresponding to the
     current program location in the ``.debug_addr``, ``.debug_line``,
     ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and
     ``.debug_loclists.dwo`` sections.
 
   * Otherwise the result is undefined.
 
 *A current object*
 
   The location description of a program object.
 
   It is required for the ``DW_OP_push_object_address`` operation.
 
   *For example, the* ``DW_AT_data_location`` *attribute on type debug
-  information entries specifies the the program object corresponding to a
-  runtime descriptor as the current object when it evaluates its associated
-  expression.*
+  information entries specifies the program object corresponding to a runtime
+  descriptor as the current object when it evaluates its associated expression.*
 
   The result is undefined if the location descriptor is invalid (see
   :ref:`amdgpu-dwarf-location-description`).
 
 *An initial stack*
 
   This is a list of values or location descriptions that will be pushed on the
   operation expression evaluation stack in the order provided before evaluation
   of an operation expression starts.
 
   Some debugger information entries have attributes that evaluate their DWARF
   expression value with initial stack entries. In all other cases the initial
   stack is empty.
 
   The result is undefined if any location descriptors are invalid (see
   :ref:`amdgpu-dwarf-location-description`).
 
 If the evaluation requires a context element that is not specified, then the
 result of the evaluation is an error.
 
-*A DWARF expression for the location description may be able to be evaluated
+*A DWARF expression for a location description may be able to be evaluated
 without a thread, lane, call frame, program location, or architecture context.
 For example, the location of a global variable may be able to be evaluated
 without such context. If the expression evaluates with an error then it may
 indicate the variable has been optimized and so requires more context.*
 
 *The DWARF expression for call frame information (see
 :ref:`amdgpu-dwarf-call-frame-information`) operations are restricted to those
 that do not require the compilation unit context to be specified.*
 
 The DWARF is ill-formed if all the ``address_size`` fields in the headers of all
 the entries in the ``.debug_info``, ``.debug_addr``, ``.debug_line``,
 ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and
 ``.debug_loclists.dwo`` sections corresponding to any given program location do
 not match.
 
 .. _amdgpu-dwarf-expression-value:
 
-DWARF Expression Value
-++++++++++++++++++++++
+A.2.5.2 DWARF Expression Value
+++++++++++++++++++++++++++++++
 
 A value has a type and a literal value. It can represent a literal value of any
 supported base type of the target architecture. The base type specifies the
 size, encoding, and endianity of the literal value.
 
 .. note::
 
   It may be desirable to add an implicit pointer base type encoding. It would be

 
 .. note::
 
   It is unclear if ``DW_ATE_address`` is an integral type. GDB does not seem to
   consider it as integral.
 
 .. _amdgpu-dwarf-location-description:
 
-DWARF Location Description
-++++++++++++++++++++++++++
+A.2.5.3 DWARF Location Description
+++++++++++++++++++++++++++++++++++
 
 *Debugging information must provide consumers a way to find the location of
 program variables, determine the bounds of dynamic arrays and strings, and
 possibly to find the base address of a subprogram’s call frame or the return
 address of a subprogram. Furthermore, to meet the needs of recent computer
 architectures and optimization techniques, debugging information must be able to
 describe the location of an object whose location changes over the object’s
 lifetime, and may reside at multiple locations simultaneously during parts of an

 .. note::
 
   It may be better to add an implicit pointer location storage kind used by the
   ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer``
   operations. It would specify the debugger information entry and byte offset
   provided by the operations.
 
 *Location descriptions are a language independent representation of addressing
-rules. They are created using DWARF operation expressions of arbitrary
-complexity. They can be the result of evaluating a debugger information entry
-attribute that specifies an operation expression. In this usage they can
-describe the location of an object as long as its lifetime is either static or
-the same as the lexical block (see DWARF Version 5 section 3.5) that owns it,
-and it does not move during its lifetime. They can be the result of evaluating a
-debugger information entry attribute that specifies a location list expression.
-In this usage they can describe the location of an object that has a limited
-lifetime, changes its location during its lifetime, or has multiple locations
-over part or all of its lifetime.*
+rules.*
+
+* *They can be the result of evaluating a debugger information entry attribute
+  that specifies an operation expression of arbitrary complexity. In this usage
+  they can describe the location of an object as long as its lifetime is either
+  static or the same as the lexical block (see
+  :ref:`amdgpu-dwarf-lexical-block-entries`) that owns it, and it does not move
+  during its lifetime.*
+
+* *They can be the result of evaluating a debugger information entry attribute
+  that specifies a location list expression. In this usage they can describe the
+  location of an object that has a limited lifetime, changes its location during
+  its lifetime, or has multiple locations over part or all of its lifetime.*
 
 If a location description has more than one single location description, the
 DWARF expression is ill-formed if the object value held in each single location
 description's position within the associated location storage is not the same
 value, except for the parts of the value that are uninitialized.
 
 *A location description that has more than one single location description can
 only be created by a location list expression that has overlapping program

 
 *For example, a location description may specify a register that no longer holds
 the intended program object after a program location change. One way to avoid
 such problems is to recompute location descriptions associated with threads when
 their program locations change.*
 
 .. _amdgpu-dwarf-operation-expressions:
 
-DWARF Operation Expressions
-+++++++++++++++++++++++++++
+A.2.5.4 DWARF Operation Expressions
++++++++++++++++++++++++++++++++++++
 
 An operation expression is comprised of a stream of operations, each consisting
 of an opcode followed by zero or more operands. The number of operands is
 implied by the opcode.
 
 Operations represent a postfix operation on a simple stack machine. Each stack
 entry can hold either a value or a location description. Operations can act on
 entries on the stack, including adding entries and removing entries. If the kind
* If the current result kind is not specified, then:
 
   * Otherwise, the top stack entry is returned. Any other entries on the stack
     are discarded.
 
 An operation expression is encoded as a byte block with some form of prefix that
 specifies the byte count. It can be used:
 
 * as the value of a debugging information entry attribute that is encoded using
-  class ``exprloc`` (see DWARF Version 5 section 7.5.5),
+  class ``exprloc`` (see :ref:`amdgpu-dwarf-classes-and-forms`),
 
 * as the operand to certain operation expression operations,
 
 * as the operand to certain call frame information operations (see
   :ref:`amdgpu-dwarf-call-frame-information`),
 
 * and in location list entries (see
   :ref:`amdgpu-dwarf-location-list-expressions`).
 
 .. _amdgpu-dwarf-stack-operations:
 
-Stack Operations
-################
+A.2.5.4.1 Stack Operations
+##########################
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.5.1.3.
 
 The following operations manipulate the DWARF stack. Operations that index the
 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 (see
 :ref:`amdgpu-dwarf-composite-location-description-operations`), then the DWARF
3.  ``DW_OP_pick``
 
     ``DW_OP_pick`` has a single unsigned 1-byte operand that represents an index
     I. A copy of the stack entry with index I is pushed onto the stack.
 
 4.  ``DW_OP_over``
 
     ``DW_OP_over`` pushes a copy of the entry with index 1.
 
-    *This is equivalent to a ``DW_OP_pick 1`` operation.*
+    *This is equivalent to a* ``DW_OP_pick 1`` *operation.*
 
 5.  ``DW_OP_swap``
 
     ``DW_OP_swap`` swaps the top two stack entries. The entry at the top of the
     stack becomes the second stack entry, and the second stack entry becomes the
     top of the stack.
 
 6.  ``DW_OP_rot``
 
     ``DW_OP_rot`` rotates the first three stack entries. The entry at the top of
     the stack becomes the third stack entry, the second entry becomes the top of
     the stack, and the third entry becomes the second entry.
 
 .. _amdgpu-dwarf-control-flow-operations:
 
-Control Flow Operations
-#######################
+A.2.5.4.2 Control Flow Operations
+#################################
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.5.1.5.
 
 The following operations provide simple control of the flow of a DWARF operation
 expression.
 
 1.  ``DW_OP_nop``
 
     ``DW_OP_nop`` is a place holder. It has no effect on the DWARF stack
     entries.
5.  ``DW_OP_call2, DW_OP_call4, DW_OP_call_ref``
     compilation unit.
 
     ``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 the byte offset DR of a debugging information entry D
     relative to the beginning of the ``.debug_info`` section that contains the
     current compilation unit. D may not be in the current compilation unit.
 
-    .. note:
+    .. note::
 
       DWARF Version 5 states that DR can be an offset in a ``.debug_info``
       section other than the one that contains the current compilation unit. It
       states that relocation of references from one executable or shared object
       file to another must be performed by the consumer. But given that DR is
       defined as an offset in a ``.debug_info`` section this seems impossible.
       If DR was defined as an implementation defined value, then the consumer
       could choose to interpret the value in an implementation defined manner to
* If D has a ``DW_AT_location`` attribute that is encoded as a ``loclist`` or
 
         But this is not attractive as if the attribute is for a variable that
         happens to end with a non-singleton stack, it will not simply put a
         location description on the stack. Presumably the intent of using
         ``DW_OP_call*`` on a variable or formal parameter debugger information
         entry is to push just one location description on the stack. That
         location description may have more than one single location description.
 
-        The previous rule for ``exprloc`` also has the same problem as normally
+        The previous rule for ``exprloc`` also has the same problem, as normally
         a variable or formal parameter location expression may leave multiple
         entries on the stack and only return the top entry.
 
         GDB implements ``DW_OP_call*`` by always executing E on the same stack.
         If the location list has multiple matching entries, it simply picks the
         first one and ignores the rest. This seems fundamentally at odds with
-        the desire to supporting multiple places for variables.
+        the desire to support multiple places for variables.
 
         So, it feels like ``DW_OP_call*`` should both support pushing a location
         description on the stack for a variable or formal parameter, and also
         support being able to execute an operation expression on the same stack.
         Being able to specify a different operation expression for different
         program locations seems a desirable feature to retain.
 
         A solution to that is to have a distinct ``DW_AT_LLVM_proc`` attribute
* If D has a ``DW_AT_location`` attribute that is encoded as a ``loclist`` or
         is the one that contains D, and the initial stack is empty. The location
         description result is pushed on the stack.
 
     * If D has a ``DW_AT_const_value`` attribute with a value V, then it is as
       if a ``DW_OP_implicit_value V`` operation was executed.
 
       *This allows a call operation to be used to compute the location
       description for any variable or formal parameter regardless of whether the
-      producer has optimized it to a constant. This is consistent with the
-      ``DW_OP_implicit_pointer`` operation.*
+      producer has optimized it to a constant. This is consistent with the*
+      ``DW_OP_implicit_pointer`` *operation.*
 
       .. note::
 
         Alternatively, could deprecate using ``DW_AT_const_value`` for
         ``DW_TAG_variable`` and ``DW_TAG_formal_parameter`` debugger information
         entries that are constants and instead use ``DW_AT_location`` with an
         operation expression that results in a location description with one
         implicit location description. Then this rule would not be required.
* Otherwise, there is no effect and no changes are made to the stack.
         attribute. So, should this case be defined as an ill-formed DWARF
         expression?
 
     *The* ``DW_TAG_dwarf_procedure`` *debugging information entry can be used to
     define DWARF procedures that can be called.*
 
 .. _amdgpu-dwarf-value-operations:
 
-Value Operations
-################
+A.2.5.4.3 Value Operations
+##########################
 
 This section describes the operations that push values on the stack.
 
-Each value stack entry has a type and a literal value and can represent a
+Each value stack entry has a type and a literal value. It can represent a
 literal value of any supported base type of the target architecture. The base
 type specifies the size, encoding, and endianity of the literal value.
 
 The base type of value stack entries can be the distinguished generic type.
 
 .. _amdgpu-dwarf-literal-operations:
 
-Literal Operations
-^^^^^^^^^^^^^^^^^^
+A.2.5.4.3.1 Literal Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.5.1.1.
 
 The following operations all push a literal value onto the DWARF stack.
 
 Operations other than ``DW_OP_const_type`` push a value V with the generic type.
 If V is larger than the generic type, then V is truncated to the generic type
 size and the low-order bits used.
 
 1.  ``DW_OP_lit0``, ``DW_OP_lit1``, ..., ``DW_OP_lit31``
6.  ``DW_OP_constx``
     the value of the ``DW_AT_addr_base`` attribute of the associated compilation
     unit. The value N in the ``.debug_addr`` section has the size of the generic
     type. It pushes the value N with the generic type.
 
     *The* ``DW_OP_constx`` *operation is provided for constants that require
     link-time relocation but should not be interpreted by the consumer as a
     relocatable address (for example, offsets to thread-local storage).*
 
-9.  ``DW_OP_const_type``
+7.  ``DW_OP_const_type``
 
     ``DW_OP_const_type`` has three operands. The first is an unsigned LEB128
     integer DR that represents the byte offset of a debugging information entry
     D relative to the beginning of the current compilation unit, that provides
     the type T of the constant value. The second is a 1-byte unsigned integral
     constant S. The third is a block of bytes B, with a length equal to S.
 
     TS is the bit size of the type T. The least significant TS bits of B are
     interpreted as a value V of the type D. It pushes the value V with the type
     D.
 
     The DWARF is ill-formed if D is not a ``DW_TAG_base_type`` debugging
     information entry in the current compilation unit, or if TS divided by 8
     (the byte size) and rounded up to a whole number is not equal to S.
 
     *While the size of the byte block B can be inferred from the type D
     definition, it is encoded explicitly into the operation so that the
     operation can be parsed easily without reference to the* ``.debug_info``
     *section.*
 
-10. ``DW_OP_LLVM_push_lane`` *New*
+8.  ``DW_OP_LLVM_push_lane`` *New*
 
     ``DW_OP_LLVM_push_lane`` pushes the target architecture lane identifier of
     the current lane as a value with the generic type.
 
     *For languages that are implemented using a SIMD or SIMT execution model,
     this is the lane number that corresponds to the source language thread of
     execution upon which the user is focused.*
 
 .. _amdgpu-dwarf-arithmetic-logical-operations:
 
-Arithmetic and Logical Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.3.2 Arithmetic and Logical Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
 
   This section is the same as DWARF Version 5 section 2.5.1.4.
 
 .. _amdgpu-dwarf-type-conversions-operations:
 
-Type Conversion Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.3.3 Type Conversion Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
 
   This section is the same as DWARF Version 5 section 2.5.1.6.
 
 .. _amdgpu-dwarf-general-operations:
 
-Special Value Operations
-^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.3.4 Special Value Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces parts of DWARF Version 5 sections 2.5.1.2, 2.5.1.3, and
+  2.5.1.7.
 
 There are these special value operations currently defined:
 
 1.  ``DW_OP_regval_type``
 
     ``DW_OP_regval_type`` has two operands. The first is an unsigned LEB128
     integer that represents a register number R. The second is an unsigned
     LEB128 integer DR that represents the byte offset of a debugging information
.. note::
 
       This definition allows the base type to be a bit size since there seems no
       reason to restrict it.
 
     It is an evaluation error if any bit of the value is retrieved from the
     undefined location storage or the offset of any bit exceeds the size of the
     location storage LS specified by any single location description SL of L.
 
-    See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules
-    concerning implicit location descriptions created by the
+    See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special
+    rules concerning implicit location descriptions created by the
     ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_implicit_aspace_pointer``
     operations.
 
 5.  ``DW_OP_xderef`` *Deprecated*
 
     ``DW_OP_xderef`` pops two stack entries. The first must be an integral type
     value that represents an address A. The second must be an integral type
     value that represents a target architecture specific address space
7.  ``DW_OP_xderef_type`` *Deprecated*
     to the beginning of the current compilation unit, that provides the type T
     of the result value.
 
     It pops two stack entries. The first must be an integral type value that
     represents an address A. The second must be an integral type value that
     represents a target architecture specific address space identifier AS.
 
     The operation is equivalent to performing ``DW_OP_swap;
-    DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S R``. The value V
-    retrieved is left on the stack with the type D.
+    DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S DR``. The value V
+    retrieved is left on the stack with the type T.
 
     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
     *operation can be used and provides greater expressiveness.*
 
 8.  ``DW_OP_entry_value`` *Deprecated*
 
     ``DW_OP_entry_value`` pushes the value of an expression that is evaluated in
     the context of the calling frame.
 
     *It may be used to determine the value of arguments on entry to the current
     call frame provided they are not clobbered.*
 
     It has two operands. The first is an unsigned LEB128 integer S. The second
     is a block of bytes, with a length equal S, interpreted as a DWARF
     operation expression E.
 
     E is evaluated with the current context, except the result kind is
     unspecified, the call frame is the one that called the current frame, the
     program location is the call site in the calling frame, the object is
     unspecified, and the initial stack is empty. The calling frame information
     is obtained by virtually unwinding the current call frame using the call
     frame information (see :ref:`amdgpu-dwarf-call-frame-information`).
 
     If the result of E is a location description L (see
-    :ref:`amdgpu-dwarf-register-location-descriptions`), and the last operation
-    executed by E is a ``DW_OP_reg*`` for register R with a target architecture
-    specific base type of T, then the contents of the register are retrieved as
-    if a ``DW_OP_deref_type DR`` operation was performed where DR is the offset
-    of a hypothetical debug information entry in the current compilation unit
-    for T. The resulting value V s pushed on the stack.
+    :ref:`amdgpu-dwarf-register-location-description-operations`), and the last
+    operation executed by E is a ``DW_OP_reg*`` for register R with a target
+    architecture specific base type of T, then the contents of the register are
+    retrieved as if a ``DW_OP_deref_type DR`` operation was performed where DR
+    is the offset of a hypothetical debug information entry in the current
+    compilation unit for T. The resulting value V s pushed on the stack.
 
     *Using* ``DW_OP_reg*`` *provides a more compact form for the case where the
     value was in a register on entry to the subprogram.*
 
-    .. note:
+    .. note::
 
       It is unclear how this provides a more compact expression, as
       ``DW_OP_regval_type`` could be used which is marginally larger.
 
     If the result of E is a value V, then V is pushed on the stack.
 
     Otherwise, the DWARF expression is ill-formed.
 
8.  ``DW_OP_entry_value`` *Deprecated*
 
     .. note::
 
       GDB only implements ``DW_OP_entry_value`` when E is exactly
       ``DW_OP_reg*`` or ``DW_OP_breg*; DW_OP_deref*``.
 
 .. _amdgpu-dwarf-location-description-operations:
 
-Location Description Operations
-###############################
+A.2.5.4.4 Location Description Operations
+#########################################
 
 This section describes the operations that push location descriptions on the
 stack.
 
-General Location Description Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _amdgpu-dwarf-general-location-description-operations:
+
+A.2.5.4.4.1 General Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces part of DWARF Version 5 section 2.5.1.3.
 
 1.  ``DW_OP_LLVM_offset`` *New*
 
     ``DW_OP_LLVM_offset`` pops two stack entries. The first must be an integral
     type value that represents a byte displacement B. The second must be a
     location description L.
 
     It adds the value of B scaled by 8 (the byte size) to the bit offset of each
4.  ``DW_OP_push_object_address``
     *This object may correspond to an independent variable that is part of a
     user presented expression that is being evaluated. The object location
     description may be determined from the variable's own debugging information
     entry or it may be a component of an array, structure, or class whose
     address has been dynamically determined by an earlier step during user
     expression evaluation.*
 
     *This operation provides explicit functionality (especially for arrays
-    involving descriptions) that is analogous to the implicit push of the base
-    location description of a structure prior to evaluation of a
-    ``DW_AT_data_member_location`` to access a data member of a structure.*
+    involving descriptors) that is analogous to the implicit push of the base
+    location description of a structure prior to evaluation of a*
+    ``DW_AT_data_member_location`` *to access a data member of a structure.*
 
     .. note::
 
       This operation could be removed and the object location description
       specified as the initial stack as for ``DW_AT_data_member_location``.
 
+      Or this operation could be used instead of needing to specify an initial
+      stack. The latter approach is more composable as access to the object may
+      be needed at any point of the expression, and passing it as the initial
+      stack requires the entire expression to be aware where on the stack it is.
+      If this were done, ``DW_AT_use_location`` would require a
+      ``DW_OP_push_object2_address`` operation for the second object.
+
+      Or a more general way to pass an arbitrary number of arguments in and an
+      operation to get the Nth one such as ``DW_OP_arg N``. A vector of
+      arguments would then be passed in the expression context rather than an
+      initial stack. This could also resolve the issues with ``DW_OP_call*`` by
+      allowing a specific number of arguments passed in and returned to be
+      specified. The ``DW_OP_call*`` operation could then always execute on a
+      separate stack: the number of arguments would be specified in a new call
+      operation and taken from the callers stack, and similarly the number of
+      return results specified and copied from the called stack back to the
+      callee stack when the called expression was complete.
+
       The only attribute that specifies a current object is
       ``DW_AT_data_location`` so the non-normative text seems to overstate how
       this is being used. Or are there other attributes that need to state they
       pass an object?
 
 5.  ``DW_OP_LLVM_call_frame_entry_reg`` *New*
 
     ``DW_OP_LLVM_call_frame_entry_reg`` has a single unsigned LEB128 integer
     operand that represents a target architecture register number R.
 
     It pushes a location description L that holds the value of register R on
     entry to the current subprogram as defined by the call frame information
     (see :ref:`amdgpu-dwarf-call-frame-information`).
 
     *If there is no call frame information defined, then the default rules for
     the target architecture are used. If the register rule is* undefined\ *, then
     the undefined location description is pushed. If the register rule is* same
     value\ *, then a register location description for R is pushed.*
 
 .. _amdgpu-dwarf-undefined-location-description-operations:
 
-Undefined Location Description Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.4.2 Undefined Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.6.1.1.1.
 
 *The undefined location storage represents a piece or all of an object that is
 present in the source but not in the object code (perhaps due to optimization).
 Neither reading nor writing to the undefined location storage is meaningful.*
 
 An undefined location description specifies the undefined location storage.
 There is no concept of the size of the undefined location storage, nor of a bit
 offset for an undefined location description. The ``DW_OP_LLVM_*offset``
 operations leave an undefined location description unchanged. The
 ``DW_OP_*piece`` operations can explicitly or implicitly specify an undefined
 location description, allowing any size and offset to be specified, and results
 in a part with all undefined bits.
 
 1.  ``DW_OP_LLVM_undefined`` *New*
 
     ``DW_OP_LLVM_undefined`` pushes a location description L that comprises one
     undefined location description SL.
 
 .. _amdgpu-dwarf-memory-location-description-operations:
 
-Memory Location Description Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.4.3 Memory Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2,
+  2.5.1.3, and 2.6.1.1.2.
 
 Each of the target architecture specific address spaces has a corresponding
 memory location storage that denotes the linear addressable memory of that
 address space. The size of each memory location storage corresponds to the range
 of the addresses in the corresponding address space.
 
 *It is target architecture defined how address space location storage maps to
 target architecture physical memory. For example, they may be independent
.. note::
   a memory location description in the target architecture default address
   space:
 
     If a stack entry is required to be a location description, but is a value V
     with an integral type, then it is implicitly converted to a location
     description L with a one memory location description SL. If the type size of
     V is less than the generic type size, then the value V is zero extended to
     the size of the generic type. The least significant generic type size bits
-    are treated as a twos-complement unsigned value to be used as an address A.
-    SL specifies memory location storage corresponding to the target
-    architecture default address space with a bit offset equal to A scaled by 8
-    (the byte size).
+    are treated as an unsigned value to be used as an address A. SL specifies
+    memory location storage corresponding to the target architecture default
+    address space with a bit offset equal to A scaled by 8 (the byte size).
 
   The implicit conversion could also be defined as target architecture specific.
   For example, GDB checks if V is an integral type. If it is not it gives an
   error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a
   hook function, then it is called. The target specific hook function can modify
   the 64-bit value, possibly sign extending based on the original value type.
   Finally, GDB treats the 64-bit value V as a memory location address.
 
 If a stack entry is required to be a location description, but it is an implicit
 pointer value IPV with the target architecture default address space, then it is
 implicitly converted to a location description with one single location
 description specified by IPV. See
-:ref:`amdgpu-dwarf-implicit-location-descriptions`.
+:ref:`amdgpu-dwarf-implicit-location-description-operations`.
 
 .. note::
 
   Is this rule required for DWARF Version 5 backwards compatibility? If not, it
   can be eliminated, and the producer can use
   ``DW_OP_LLVM_form_aspace_address``.
 
 If a stack entry is required to be a value, but it is a location description L
3.  ``DW_OP_LLVM_form_aspace_address`` *New*
     ``DW_OP_LLVM_form_aspace_address`` pops top two stack entries. The first
     must be an integral type value that represents a target architecture
     specific address space identifier AS. The second must be an integral type
     value that represents an address A.
 
     The address size S is defined as the address bit size of the target
     architecture specific address space that corresponds to AS.
 
-    A is adjusted to S bits by zero extending if necessary, and then treating the
-    least significant S bits as a twos-complement unsigned value A'.
+    A is adjusted to S bits by zero extending if necessary, and then treating
+    the least significant S bits as an unsigned value A'.
 
     It pushes a location description L with one memory location description SL
     on the stack. SL specifies the memory location storage LS that corresponds
     to AS with a bit offset equal to A' scaled by 8 (the byte size).
 
     If AS is an address space that is specific to context elements, then LS
     corresponds to the location storage associated with the current context.
 
     *For example, if AS is for per thread storage then LS is the location
     storage for the current thread. For languages that are implemented using a
     SIMD or SIMT execution model, then if AS is for per lane storage then LS is
     the location storage for the current lane of the current thread. Therefore,
     if L is accessed by an operation, the location storage selected when the
     location description was created is accessed, and not the location storage
     associated with the current context of the access operation.*
 
     The DWARF expression is ill-formed if AS is not one of the values defined by
     the target architecture specific ``DW_ASPACE_*`` values.
 
-    See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules
-    concerning implicit pointer values produced by dereferencing implicit
+    See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special
+    rules concerning implicit pointer values produced by dereferencing implicit
     location descriptions created by the ``DW_OP_implicit_pointer`` and
     ``DW_OP_LLVM_implicit_aspace_pointer`` operations.
 
 4.  ``DW_OP_form_tls_address``
 
     ``DW_OP_form_tls_address`` pops one stack entry that must be an integral
     type value and treats it as a thread-local storage address TA.
 

 6.  ``DW_OP_fbreg``
 
     ``DW_OP_fbreg`` has a single signed LEB128 integer operand that represents a
     byte displacement B.
 
     The location description L for the *frame base* of the current subprogram is
     obtained from the ``DW_AT_frame_base`` attribute of the debugger information
     entry corresponding to the current subprogram as described in
-    :ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
+    :ref:`amdgpu-dwarf-low-level-information`.
 
     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``
 
     The ``DW_OP_breg<N>`` operations encode the numbers of up to 32 registers,
     numbered from 0 through 31, inclusive. The register number R corresponds to
9.  ``DW_OP_LLVM_aspace_bregx`` *New*
     The DWARF expression is ill-formed if AS is not one of the values defined by
     the target architecture specific ``DW_ASPACE_*`` values.
 
     .. note::
 
       Could also consider adding ``DW_OP_aspace_breg0, DW_OP_aspace_breg1, ...,
       DW_OP_aspace_bref31`` which would save encoding size.
 
-.. _amdgpu-dwarf-register-location-descriptions:
+.. _amdgpu-dwarf-register-location-description-operations:
+
+A.2.5.4.4.4 Register Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Register Location Description Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+  This section replaces DWARF Version 5 section 2.6.1.1.3.
 
 There is a register location storage that corresponds to each of the target
 architecture registers. The size of each register location storage corresponds
 to the size of the corresponding target architecture register.
 
 A register location description specifies a register location storage. The bit
 offset corresponds to a bit position within the register. Bits accessed using a
 register location description access the corresponding target architecture
2.  ``DW_OP_regx``
     recorded context is used to evaluate the call frame information, not the
     current context of the access operation.*
 
 *These operations obtain a register location. To fetch the contents of a
 register, it is necessary to use* ``DW_OP_regval_type``\ *, use one of the*
 ``DW_OP_breg*`` *register-based addressing operations, or use* ``DW_OP_deref*``
 *on a register location description.*
 
-.. _amdgpu-dwarf-implicit-location-descriptions:
+.. _amdgpu-dwarf-implicit-location-description-operations:
+
+A.2.5.4.4.5 Implicit Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Implicit Location Description Operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+  This section replaces DWARF Version 5 section 2.6.1.1.4.
 
 Implicit location storage represents a piece or all of an object which has no
 actual location in the program but whose contents are nonetheless known, either
 as a constant or can be computed from other locations and values in the program.
 
 An implicit location description specifies an implicit location storage. The bit
 offset corresponds to a bit position within the implicit location storage. Bits
 accessed using an implicit location description, access the corresponding
2.  ``DW_OP_stack_value``
     It pushes a location description L with one implicit location description SL
     on the stack. SL specifies LS with a bit offset of 0.
 
     *The* ``DW_OP_stack_value`` *operation specifies that the object does not
     exist in memory, but its value is nonetheless known. In this form, the
     location description specifies the actual value of the object, rather than
     specifying the memory or register storage that holds the value.*
 
-    See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules
-    concerning implicit pointer values produced by dereferencing implicit
+    See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special
+    rules concerning implicit pointer values produced by dereferencing implicit
     location descriptions created by the ``DW_OP_implicit_pointer`` and
     ``DW_OP_LLVM_implicit_aspace_pointer`` operations.
 
     .. note::
 
       Since location descriptions are allowed on the stack, the
       ``DW_OP_stack_value`` operation no longer terminates the DWARF operation
       expression execution as in DWARF Version 5.
3.  ``DW_OP_implicit_pointer``
     If a ``DW_OP_stack_value`` operation pops a value that is the same as IPV,
     then it pushes a location description that is the same as L.
 
     It is an evaluation error if LS or IPV is accessed in any other manner.
 
     *The restrictions on how an implicit pointer location description created
     by* ``DW_OP_implicit_pointer`` *and* ``DW_OP_LLVM_aspace_implicit_pointer``
     *can be used are to simplify the DWARF consumer. Similarly, for an implicit
-    pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ .*
+    pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ *.*
 
 4.  ``DW_OP_LLVM_aspace_implicit_pointer`` *New*
 
     ``DW_OP_LLVM_aspace_implicit_pointer`` has two operands that are the same as
     for ``DW_OP_implicit_pointer``.
 
     It pops one stack entry that must be an integral type value that represents
     a target architecture specific address space identifier AS.

 *D*\ :sub:`1` *and E*\ :sub:`1` *are describing the location of a pointer type
 object. D*\ :sub:`2` *and E*\ :sub:`2` *are describing the location of the
 object pointed to by that pointer object.*
 
 *However, D*\ :sub:`2` *may be any debugging information entry that contains a*
 ``DW_AT_location`` *or* ``DW_AT_const_value`` *attribute (for example,*
 ``DW_TAG_dwarf_procedure``\ *). By using E*\ :sub:`2`\ *, a consumer can
 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
+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
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A.2.5.4.4.6 Composite Location Description Operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.6.1.2.
 
 A composite location storage represents an object or value which may be
 contained in part of another location storage or contained in parts of more
 than one location storage.
 
 Each part has a part location description L and a part bit size S. L can have
 one or more single location descriptions SL. If there are more than one SL then
 that indicates that part is located in more than one place. The bits of each
5.  ``DW_OP_LLVM_select_bit_piece`` *New*
     description SL is pushed on the stack. SL specifies LS with a bit offset of
     0.
 
     The DWARF expression is ill-formed if S or C are 0, or if the bit size of M
     is less than C.
 
 .. _amdgpu-dwarf-location-list-expressions:
 
-DWARF Location List Expressions
-+++++++++++++++++++++++++++++++
+A.2.5.5 DWARF Location List Expressions
++++++++++++++++++++++++++++++++++++++++
+
+.. note::
+
+  This section replaces DWARF Version 5 section 2.6.2.
 
 *To meet the needs of recent computer architectures and optimization techniques,
 debugging information must be able to describe the location of an object whose
 location changes over the object’s lifetime, and may reside at multiple
 locations during parts of an object's lifetime. Location list expressions are
 used in place of operation expressions whenever the object whose location is
 being described has these requirements.*
 
* Otherwise, the operation expression E of each matching location list entry is
   evaluation of E.
 
   The result is a location description that is comprised of the union of the
   single location descriptions of the location description result of each
   matching location list entry.
 
 A location list expression can only be used as the value of a debugger
 information entry attribute that is encoded using class ``loclist`` or
-``loclistsptr`` (see DWARF Version 5 section 7.5.5). The value of the attribute
-provides an index into a separate object file section called ``.debug_loclists``
-or ``.debug_loclists.dwo`` (for split DWARF object files) that contains the
-location list entries.
+``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the
+attribute provides an index into a separate object file section called
+``.debug_loclists`` or ``.debug_loclists.dwo`` (for split DWARF object files)
+that contains the location list entries.
 
 A ``DW_OP_call*`` and ``DW_OP_implicit_pointer`` operation can be used to
 specify a debugger information entry attribute that has a location list
 expression. Several debugger information entry attributes allow DWARF
 expressions that are evaluated with an initial stack that includes a location
 description that may originate from the evaluation of a location list
 expression.
 
 *This location list representation, the* ``loclist`` *and* ``loclistsptr``
 *class, and the related* ``DW_AT_loclists_base`` *attribute are new in DWARF
 Version 5. Together they eliminate most, or all of the code object relocations
 previously needed for location list expressions.*
 
 .. note::
 
   The rest of this section is the same as DWARF Version 5 section 2.6.2.
 
 .. _amdgpu-dwarf-segment_addresses:
 
-Segmented Addresses
-~~~~~~~~~~~~~~~~~~~
+A.2.12 Segmented Addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This augments DWARF Version 5 section 2.12.
 
 DWARF address classes are used for source languages that have the concept of
 memory spaces. They are used in the ``DW_AT_address_class`` attribute for
 pointer type, reference type, subprogram, and subprogram type debugger
.. note::
   The changes will likely add an attribute that has an expression provided by
   the compiler to map from address class to address space. The
   ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer``
   operations may be changed as the current IPV definition may not provide enough
   information when used to cast between address classes. Other attributes and
   operations may be needed. The legal casts between address classes may need to
   be defined on a per language address class basis.
 
-.. _amdgpu-dwarf-debugging-information-entry-attributes:
-
-Debugging Information Entry Attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.3 Program Scope Entries
+-------------------------
 
 .. note::
 
   This section provides changes to existing debugger information entry
-  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``
+  attributes. These would be incorporated into the corresponding DWARF Version 5
+  chapter 3 sections.
 
-    Any debugging information entry describing a data object (which includes
-    variables and parameters) or common blocks may have a ``DW_AT_location``
-    attribute, whose value is a DWARF expression E.
+A.3.1 Unit Entries
+~~~~~~~~~~~~~~~~~~
 
-    The result of the attribute is obtained by evaluating E with a context that
-    has a result kind of a location description, an unspecified object, the
-    compilation unit that contains E, an empty initial stack, and other context
-    elements corresponding to the source language thread of execution upon which
-    the user is focused, if any. The result of the evaluation is the location
-    description of the base of the data object.
+.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries:
 
-    See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules
-    used by the ``DW_OP_call*`` operations.
+A.3.1.1 Full and Partial Compilation Unit Entries
++++++++++++++++++++++++++++++++++++++++++++++++++
 
-    .. note::
 
-      Delete the description of how the ``DW_OP_call*`` operations evaluate a
-      ``DW_AT_location`` attribute as that is now described in the operations.
+  This augments DWARF Version 5 section 3.1.1 and Table 3.1.
 
-    .. note::
+Additional language codes defined for use with the ``DW_AT_language`` attribute
+are defined in :ref:`amdgpu-dwarf-language-names-table`.
 
-      See the discussion about the ``DW_AT_location`` attribute in the
-      ``DW_OP_call*`` operation. Having each attribute only have a single
-      purpose and single execution semantics seems desirable. It makes it easier
-      for the consumer that no longer have to track the context. It makes it
-      easier for the producer as it can rely on a single semantics for each
-      attribute.
+.. table:: Language Names
+   :name: amdgpu-dwarf-language-names-table
 
-      For that reason, limiting the ``DW_AT_location`` attribute to only
-      supporting evaluating the location description of an object, and using a
-      different attribute and encoding class for the evaluation of DWARF
-      expression *procedures* on the same operation expression stack seems
-      desirable.
+   ==================== =============================
+   Language Name        Meaning
+   ==================== =============================
+   ``DW_LANG_LLVM_HIP`` HIP Language.
+   ==================== =============================
 
-2.  ``DW_AT_const_value``
+The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending
+the C++ language.
 
-    .. note::
 
-      Could deprecate using the ``DW_AT_const_value`` attribute for
-      ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information
-      entries that have been optimized to a constant. Instead,
-      ``DW_AT_location`` could be used with a DWARF expression that produces an
-      implicit location description now that any location description can be
-      used within a DWARF expression. This allows the ``DW_OP_call*`` operations
-      to be used to push the location description of any variable regardless of
-      how it is optimized.
+  The following new attribute is added.
 
-3.  ``DW_AT_frame_base``
+1.  A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit
+    may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an
+    augmentation string.
+
+    *The augmentation string allows producers to indicate that there is
+    additional vendor or target specific information in the debugging
+    information entries. For example, this might be information about the
+    version of vendor specific extensions that are being used.*
+
+    If not present, or if the string is empty, then the compilation unit has no
+    augmentation string.
+
+    The format for the augmentation string is:
+
+      | ``[``\ *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
+    providing additional information about the extensions. The version number
+    must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`].
+    The *options* string must not contain the "\ ``]``\ " character.
+
+    For example:
+
+      ::
 
-    A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry
+        [abc:v0.0][def:v1.2:feature-a=on,feature-b=3]
+
+A.3.3 Subroutine and Entry Point Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _amdgpu-dwarf-low-level-information:
+
+A.3.3.5 Low-Level Information
++++++++++++++++++++++++++++++
+
+1.  A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
+    ``DW_TAG_entry_point`` debugger information entry may have a
+    ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E.
+
+    The result of the attribute is obtained by evaluating E with a context that
+    has a result kind of a location description, an unspecified object, the
+    compilation unit that contains E, an empty initial stack, and other context
+    elements corresponding to the source language thread of execution upon which
+    the user is focused, if any. The result of the evaluation is the location
+    description L of the place where the return address for the current call
+    frame's subprogram or entry point is stored.
+
+    The DWARF is ill-formed if L is not comprised of one memory location
+    description for one of the target architecture specific address spaces.
+
+    .. note::
+
+      It is unclear why ``DW_TAG_inlined_subroutine`` has a
+      ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or
+      ``DW_AT_static_link`` attribute. Seems it would either have all of them or
+      none. Since inlined subprograms do not have a call frame it seems they
+      would have none of these attributes.
+
+2.  A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry
     may have a ``DW_AT_frame_base`` attribute, whose value is a DWARF expression
     E.
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
     the user is focused, if any.
 
     The DWARF is ill-formed if E contains an ``DW_OP_fbreg`` operation, or the
     resulting location description L is not comprised of one single location
     description SL.
 
-    If SL a register location description for register R, then L is replaced
+    If SL is a register location description for register R, then L is replaced
     with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This
     computes the frame base memory location description in the target
     architecture default address space.
 
-    *This allows the more compact* ``DW_OPreg*`` *to be used instead of*
+    *This allows the more compact* ``DW_OP_reg*`` *to be used instead of*
     ``DW_OP_breg* 0``\ *.*
 
     .. note::
 
       This rule could be removed and require the producer to create the required
       location description directly using ``DW_OP_call_frame_cfa``,
       ``DW_OP_breg*``, or ``DW_OP_LLVM_aspace_bregx``. This would also then
       allow a target to implement the call frames within a large register.
 
     Otherwise, the DWARF is ill-formed if SL is not a memory location
     description in any of the target architecture specific address spaces.
 
     The resulting L is the *frame base* for the subprogram or entry point.
 
     *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a
     stack pointer register plus or minus some offset.*
 
-4.  ``DW_AT_data_member_location``
-
-    For a ``DW_AT_data_member_location`` attribute there are two cases:
-
-    1.  If the attribute is an integer constant B, it provides the offset in
-        bytes from the beginning of the containing entity.
-
-        The result of the attribute is obtained by evaluating a
-        ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the
-        location description of the beginning of the containing entity.  The
-        result of the evaluation is the location description of the base of the
-        member entry.
-
-        *If the beginning of the containing entity is not byte aligned, then the
-        beginning of the member entry has the same bit displacement within a
-        byte.*
-
-    2.  Otherwise, the attribute must be a DWARF expression E which is evaluated
-        with a context that has a result kind of a location description, an
-        unspecified object, the compilation unit that contains E, an initial
-        stack comprising the location description of the beginning of the
-        containing entity, and other context elements corresponding to the
-        source language thread of execution upon which the user is focused, if
-        any. The result of the evaluation is the location description of the
-        base of the member entry.
-
-    .. note::
-
-      The beginning of the containing entity can now be any location
-      description, including those with more than one single location
-      description, and those with single location descriptions that are of any
-      kind and have any bit offset.
-
-5.  ``DW_AT_use_location``
-
-    The ``DW_TAG_ptr_to_member_type`` debugging information entry has a
-    ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is
-    used to compute the location description of the member of the class to which
-    the pointer to member entry points.
-
-    *The method used to find the location description of a given member of a
-    class, structure, or union is common to any instance of that class,
-    structure, or union and to any instance of the pointer to member type. The
-    method is thus associated with the pointer to member type, rather than with
-    each object that has a pointer to member type.*
-
-    The ``DW_AT_use_location`` DWARF expression is used in conjunction with the
-    location description for a particular object of the given pointer to member
-    type and for a particular structure or class instance.
-
-    The result of the attribute is obtained by evaluating E with a context that
-    has a result kind of a location description, an unspecified object, the
-    compilation unit that contains E, an initial stack comprising two entries,
-    and other context elements corresponding to the source language thread of
-    execution upon which the user is focused, if any. The first stack entry is
-    the value of the pointer to member object itself. The second stack entry is
-    the location description of the base of the entire class, structure, or
-    union instance containing the member whose location is being calculated. The
-    result of the evaluation is the location description of the member of the
-    class to which the pointer to member entry points.
-
-6.  ``DW_AT_data_location``
-
-    The ``DW_AT_data_location`` attribute may be used with any type that
-    provides one or more levels of hidden indirection and/or run-time parameters
-    in its representation. Its value is a DWARF operation expression E which
-    computes the location description of the data for an object. When this
-    attribute is omitted, the location description of the data is the same as
-    the location description of the object.
-
-    The result of the attribute is obtained by evaluating E with a context that
-    has a result kind of a location description, an object that is the location
-    description of the data descriptor, the compilation unit that contains E, an
-    empty initial stack, and other context elements corresponding to the source
-    language thread of execution upon which the user is focused, if any. The
-    result of the evaluation is the location description of the base of the
-    member entry.
-
-    *E will typically involve an operation expression that begins with a*
-    ``DW_OP_push_object_address`` *operation which loads the location
-    description of the object which can then serve as a description in
-    subsequent calculation.*
-
-    .. note::
-
-      Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and
-      ``DW_AT_vtable_elem_location`` allow both operation expressions and
-      location list expressions, why does ``DW_AT_data_location`` not allow
-      both? In all cases they apply to data objects so less likely that
-      optimization would cause different operation expressions for different
-      program location ranges. But if supporting for some then should be for
-      all.
-
-      It seems odd this attribute is not the same as
-      ``DW_AT_data_member_location`` in having an initial stack with the
-      location description of the object since the expression has to need it.
-
-7.  ``DW_AT_vtable_elem_location``
-
-    An entry for a virtual function also has a ``DW_AT_vtable_elem_location``
-    attribute whose value is a DWARF expression E.
-
-    The result of the attribute is obtained by evaluating E with a context that
-    has a result kind of a location description, an unspecified object, the
-    compilation unit that contains E, an initial stack comprising the location
-    description of the object of the enclosing type, and other context elements
-    corresponding to the source language thread of execution upon which the user
-    is focused, if any. The result of the evaluation is the location description
-    of the slot for the function within the virtual function table for the
-    enclosing class.
-
-8.  ``DW_AT_static_link``
-
-    If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information
+3.  If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information
     entry is lexically nested, it may have a ``DW_AT_static_link`` attribute,
     whose value is a DWARF expression E.
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
     the user is focused, if any. The result of the evaluation is the location
     description L of the *canonical frame address* (see
     :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of
     the subprogram instance that immediately lexically encloses the current call
     frame's subprogram or entry point.
 
     The DWARF is ill-formed if L is is not comprised of one memory location
     description for one of the target architecture specific address spaces.
 
-9.  ``DW_AT_return_addr``
+    .. note::
+
+      The following new attributes are added.
 
-    A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
+4.  For languages that are implemented using a SIMD or SIMT execution model, a
+    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
     ``DW_TAG_entry_point`` debugger information entry may have a
-    ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E.
+    ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is
+    the number of lanes per thread. This is the static number of lanes per
+    thread. It is not the dynamic number of lanes with which the thread was
+    initiated, for example, due to smaller or partial work-groups.
+
+    If not present, the default value of 1 is used.
+
+    The DWARF is ill-formed if the value is 0.
+
+5.  For languages that are implemented using a SIMD or SIMT execution model, a
+    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
+    ``DW_TAG_entry_point`` debugging information entry may have a
+    ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E.
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
-    the user is focused, if any. The result of the evaluation is the location
-    description L of the place where the return address for the current call
-    frame's subprogram or entry point is stored.
+    the user is focused, if any.
 
-    The DWARF is ill-formed if L is not comprised of one memory location
-    description for one of the target architecture specific address spaces.
+    The resulting location description L is for a thread lane count sized vector
+    of generic type elements. The thread lane count is the value of the
+    ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program
+    location of the corresponding lane, where the least significant element
+    corresponds to the first target architecture specific lane identifier and so
+    forth. If the lane was not active when the current subprogram was called,
+    its element is an undefined location description.
 
-    .. note::
+    ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where
+    each lane of a SIMT thread is positioned even when it is in divergent
+    control flow that is not active.*
 
-      It is unclear why ``DW_TAG_inlined_subroutine`` has a
-      ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or
-      ``DW_AT_static_link`` attribute. Seems it would either have all of them or
-      none. Since inlined subprograms do not have a call frame it seems they
-      would have none of these attributes.
+    *Typically, the result is a location description with one composite location
+    description with each part being a location description with either one
+    undefined location description or one memory location description.*
+
+    If not present, the thread is not being used in a SIMT manner, and the
+    thread's current program location is used.
+
+6.  For languages that are implemented using a SIMD or SIMT execution model, a
+    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
+    ``DW_TAG_entry_point`` debugger information entry may have a
+    ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E.
+
+    The result of the attribute is obtained by evaluating E with a context that
+    has a result kind of a value, an unspecified object, the compilation unit
+    that contains E, an empty initial stack, and other context elements
+    corresponding to the source language thread of execution upon which the user
+    is focused, if any.
+
+    The DWARF is ill-formed if the resulting value V is not an integral value.
 
-10. ``DW_AT_call_value``, ``DW_AT_call_data_location``, and
-    ``DW_AT_call_data_value``
+    The resulting V is a bit mask of active lanes for the current program
+    location. The N\ :sup:`th` least significant bit of the mask corresponds to
+    the N\ :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is
+    inactive.
 
-    A ``DW_TAG_call_site_parameter`` debugger information entry may have a
+    *Some targets may update the target architecture execution mask for regions
+    of code that must execute with different sets of lanes than the current
+    active lanes. For example, some code must execute with all lanes made
+    temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to
+    provide the means to determine the source language active lanes.*
+
+    If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target
+    architecture execution mask is used.
+
+A.3.4 Call Site Entries and Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A.3.4.2 Call Site Parameters
+++++++++++++++++++++++++++++
+
+1.  A ``DW_TAG_call_site_parameter`` debugger information entry may have a
     ``DW_AT_call_value`` attribute, whose value is a DWARF operation expression
     E\ :sub:`1`\ .
 
     The result of the ``DW_AT_call_value`` attribute is obtained by evaluating
     E\ :sub:`1` with a context that has a result kind of a value, an unspecified
     object, the compilation unit that contains E, an empty initial stack, and
     other context elements corresponding to the source language thread of
     execution upon which the user is focused, if any. The resulting value V\
1.  A ``DW_TAG_call_site_parameter`` debugger information entry may have a
     description, an unspecified object, the compilation unit that contains E, an
     empty initial stack, and other context elements corresponding to the source
     language thread of execution upon which the user is focused, if any. The
     resulting location description L\ :sub:`2` is the location where the
     referenced parameter lives during the call made by the call site. If E\
     :sub:`2` would just be a ``DW_OP_push_object_address``, then the
     ``DW_AT_call_data_location`` attribute may be omitted.
 
+    .. note::
+
+      The DWARF Version 5 implies that `DW_OP_push_object_address` may be used
+      but does not state what object must be specified in the context. Either
+      `DW_OP_push_object_address` cannot be used, or the object to be passed in
+      the context must be defined.
+
     The value of the ``DW_AT_call_data_value`` attribute is obtained by
     evaluating E\ :sub:`3` with a context that has a result kind of a value, an
     unspecified object, the compilation unit that contains E, an empty initial
     stack, and other context elements corresponding to the source language
     thread of execution upon which the user is focused, if any. The resulting
     value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made
     by the call site.
 
-    The result of these attributes is undefined if the current call frame is
-    not for the subprogram containing the ``DW_TAG_call_site_parameter``
-    debugger information entry or the current program location is not for the
-    call site containing the ``DW_TAG_call_site_parameter`` debugger information
-    entry in the current call frame.
+    The result of these attributes is undefined if the current call frame is not
+    for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger
+    information entry or the current program location is not for the call site
+    containing the ``DW_TAG_call_site_parameter`` debugger information entry in
+    the current call frame.
 
     *The consumer may have to virtually unwind to the call site (see*
     :ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these
     attributes. This will ensure the source language thread of execution upon
     which the user is focused corresponds to the call site needed to evaluate
     the expression.*
 
     If it is not possible to avoid the expressions of these attributes from
     accessing registers or memory locations that might be clobbered by the
     subprogram being called by the call site, then the associated attribute
     should not be provided.
 
     *The reason for the restriction is that the parameter may need to be
     accessed during the execution of the callee. The consumer may virtually
     unwind from the called subprogram back to the caller and then evaluate the
     attribute expressions. The call frame information (see*
     :ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore
     registers that have been clobbered, and clobbered memory will no longer have
     the value at the time of the call.*
 
-11. ``DW_AT_LLVM_lanes`` *New*
+.. _amdgpu-dwarf-lexical-block-entries:
 
-    For languages that are implemented using a SIMD or SIMT execution model, a
-    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
-    ``DW_TAG_entry_point`` debugger information entry may have a
-    ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is
-    the number of lanes per thread. This is the static number of lanes per
-    thread. It is not the dynamic number of lanes with which the thread was
-    initiated, for example, due to smaller or partial work-groups.
+A.3.5 Lexical Block Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    If not present, the default value of 1 is used.
+.. note::
 
-    The DWARF is ill-formed if the value is 0.
+  This section is the same as DWARF Version 5 section 3.5.
 
-12. ``DW_AT_LLVM_lane_pc`` *New*
+A.4 Data Object and Object List Entries
+---------------------------------------
 
-    For languages that are implemented using a SIMD or SIMT execution model, a
-    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
-    ``DW_TAG_entry_point`` debugging information entry may have a
-    ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E.
+.. note::
+
+  This section provides changes to existing debugger information entry
+  attributes. These would be incorporated into the corresponding DWARF Version 5
+  chapter 4 sections.
+
+A.4.1 Data Object Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  Any debugging information entry describing a data object (which includes
+    variables and parameters) or common blocks may have a ``DW_AT_location``
+    attribute, whose value is a DWARF expression E.
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
-    the user is focused, if any.
+    the user is focused, if any. The result of the evaluation is the location
+    description of the base of the data object.
 
-    The resulting location description L is for a thread lane count sized vector
-    of generic type elements. The thread lane count is the value of the
-    ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program
-    location of the corresponding lane, where the least significant element
-    corresponds to the first target architecture specific lane identifier and so
-    forth. If the lane was not active when the current subprogram was called,
-    its element is an undefined location description.
+    See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules
+    used by the ``DW_OP_call*`` operations.
 
-    ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where
-    each lane of a SIMT thread is positioned even when it is in divergent
-    control flow that is not active.*
+    .. note::
 
-    *Typically, the result is a location description with one composite location
-    description with each part being a location description with either one
-    undefined location description or one memory location description.*
+      Delete the description of how the ``DW_OP_call*`` operations evaluate a
+      ``DW_AT_location`` attribute as that is now described in the operations.
 
-    If not present, the thread is not being used in a SIMT manner, and the
-    thread's current program location is used.
+    .. note::
 
-13. ``DW_AT_LLVM_active_lane`` *New*
+      See the discussion about the ``DW_AT_location`` attribute in the
+      ``DW_OP_call*`` operation. Having each attribute only have a single
+      purpose and single execution semantics seems desirable. It makes it easier
+      for the consumer that no longer have to track the context. It makes it
+      easier for the producer as it can rely on a single semantics for each
+      attribute.
 
-    For languages that are implemented using a SIMD or SIMT execution model, a
-    ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
-    ``DW_TAG_entry_point`` debugger information entry may have a
-    ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E.
+      For that reason, limiting the ``DW_AT_location`` attribute to only
+      supporting evaluating the location description of an object, and using a
+      different attribute and encoding class for the evaluation of DWARF
+      expression *procedures* on the same operation expression stack seems
+      desirable.
 
-    The result of the attribute is obtained by evaluating E with a context that
-    has a result kind of a value, an unspecified object, the compilation unit
-    that contains E, an empty initial stack, and other context elements
-    corresponding to the source language thread of execution upon which the user
-    is focused, if any.
+2.  ``DW_AT_const_value``
 
-    The DWARF is ill-formed if the resulting value V is not an integral value.
+    .. note::
 
-    The resulting V is a bit mask of active lanes for the current program
-    location. The N\ :sup:`th` least significant bit of the mask corresponds to
-    the N\ :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is
-    inactive.
+      Could deprecate using the ``DW_AT_const_value`` attribute for
+      ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information
+      entries that have been optimized to a constant. Instead,
+      ``DW_AT_location`` could be used with a DWARF expression that produces an
+      implicit location description now that any location description can be
+      used within a DWARF expression. This allows the ``DW_OP_call*`` operations
+      to be used to push the location description of any variable regardless of
+      how it is optimized.
 
-    *Some targets may update the target architecture execution mask for regions
-    of code that must execute with different sets of lanes than the current
-    active lanes. For example, some code must execute with all lanes made
-    temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to
-    provide the means to determine the source language active lanes.*
+A.5 Type Entries
+----------------
 
-    If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target
-    architecture execution mask is used.
+.. note::
+
+  This section provides changes to existing debugger information entry
+  attributes. These would be incorporated into the corresponding DWARF Version 5
+  chapter 5 sections.
+
+.. _amdgpu-dwarf-base-type-entries:
+
+A.5.1 Base Type Entries
+~~~~~~~~~~~~~~~~~~~~~~~
 
-14. ``DW_AT_LLVM_vector_size`` *New*
+.. note::
+
+  The following new attribute is added.
 
-    A ``DW_TAG_base_type`` debugger information entry for a base type T may have
+1.  A ``DW_TAG_base_type`` debugger information entry for a base type T may have
     a ``DW_AT_LLVM_vector_size`` attribute whose value is an integer constant
     that is the vector type size N.
 
     The representation of a vector base type is as N contiguous elements, each
     one having the representation of a base type T' that is the same as T
     without the ``DW_AT_LLVM_vector_size`` attribute.
 
     If a ``DW_TAG_base_type`` debugger information entry does not have a
     ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector
     type.
 
     The DWARF is ill-formed if N is not greater than 0.
 
     .. note::
 
       LLVM has mention of a non-upstreamed debugger information entry that is
       intended to support vector types. However, that was not for a base type so
       would not be suitable as the type of a stack value entry. But perhaps that
       could be replaced by using this attribute.
 
-15. ``DW_AT_LLVM_augmentation`` *New*
+A.5.7 Structure, Union, Class and Interface Type Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit
-    may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an
-    augmentation string.
+A.5.7.3 Derived or Extended Structures, Classes and Interfaces
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-    *The augmentation string allows producers to indicate that there is
-    additional vendor or target specific information in the debugging
-    information entries. For example, this might be information about the
-    version of vendor specific extensions that are being used.*
+1.  For a ``DW_AT_data_member_location`` attribute there are two cases:
 
-    If not present, or if the string is empty, then the compilation unit has no
-    augmentation string.
+    1.  If the attribute is an integer constant B, it provides the offset in
+        bytes from the beginning of the containing entity.
 
-    The format for the augmentation string is:
+        The result of the attribute is obtained by evaluating a
+        ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the
+        location description of the beginning of the containing entity.  The
+        result of the evaluation is the location description of the base of the
+        member entry.
 
-      | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *
+        *If the beginning of the containing entity is not byte aligned, then the
+        beginning of the member entry has the same bit displacement within a
+        byte.*
 
-    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
-    providing additional information about the extensions. The version number
-    must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`].
-    The *options* string must not contain the "\ ``]``\ " character.
+    2.  Otherwise, the attribute must be a DWARF expression E which is evaluated
+        with a context that has a result kind of a location description, an
+        unspecified object, the compilation unit that contains E, an initial
+        stack comprising the location description of the beginning of the
+        containing entity, and other context elements corresponding to the
+        source language thread of execution upon which the user is focused, if
+        any. The result of the evaluation is the location description of the
+        base of the member entry.
 
-    For example:
+    .. note::
 
-      ::
+      The beginning of the containing entity can now be any location
+      description, including those with more than one single location
+      description, and those with single location descriptions that are of any
+      kind and have any bit offset.
 
-        [abc:v0.0][def:v1.2:feature-a=on,feature-b=3]
+A.5.7.8 Member Function Entries
++++++++++++++++++++++++++++++++
 
-Program Scope Entities
-----------------------
+1.  An entry for a virtual function also has a ``DW_AT_vtable_elem_location``
+    attribute whose value is a DWARF expression E.
 
-.. _amdgpu-dwarf-language-names:
+    The result of the attribute is obtained by evaluating E with a context that
+    has a result kind of a location description, an unspecified object, the
+    compilation unit that contains E, an initial stack comprising the location
+    description of the object of the enclosing type, and other context elements
+    corresponding to the source language thread of execution upon which the user
+    is focused, if any. The result of the evaluation is the location description
+    of the slot for the function within the virtual function table for the
+    enclosing class.
 
-Unit Entities
-~~~~~~~~~~~~~
+A.5.14 Pointer to Member Type Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+1.  The ``DW_TAG_ptr_to_member_type`` debugging information entry has a
+    ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is
+    used to compute the location description of the member of the class to which
+    the pointer to member entry points.
 
-  This augments DWARF Version 5 section 3.1.1 and Table 3.1.
+    *The method used to find the location description of a given member of a
+    class, structure, or union is common to any instance of that class,
+    structure, or union and to any instance of the pointer to member type. The
+    method is thus associated with the pointer to member type, rather than with
+    each object that has a pointer to member type.*
 
-Additional language codes defined for use with the ``DW_AT_language`` attribute
-are defined in :ref:`amdgpu-dwarf-language-names-table`.
+    The ``DW_AT_use_location`` DWARF expression is used in conjunction with the
+    location description for a particular object of the given pointer to member
+    type and for a particular structure or class instance.
 
-.. table:: Language Names
-   :name: amdgpu-dwarf-language-names-table
+    The result of the attribute is obtained by evaluating E with a context that
+    has a result kind of a location description, an unspecified object, the
+    compilation unit that contains E, an initial stack comprising two entries,
+    and other context elements corresponding to the source language thread of
+    execution upon which the user is focused, if any. The first stack entry is
+    the value of the pointer to member object itself. The second stack entry is
+    the location description of the base of the entire class, structure, or
+    union instance containing the member whose location is being calculated. The
+    result of the evaluation is the location description of the member of the
+    class to which the pointer to member entry points.
 
-   ==================== =============================
-   Language Name        Meaning
-   ==================== =============================
-   ``DW_LANG_LLVM_HIP`` HIP Language.
-   ==================== =============================
+A.5.16 Dynamic Type Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending
-the C++ language.
+1.  The ``DW_AT_data_location`` attribute may be used with any type that
+    provides one or more levels of hidden indirection and/or run-time parameters
+    in its representation. Its value is a DWARF operation expression E which
+    computes the location description of the data for an object. When this
+    attribute is omitted, the location description of the data is the same as
+    the location description of the object.
 
-Other Debugger Information
---------------------------
+    The result of the attribute is obtained by evaluating E with a context that
+    has a result kind of a location description, an object that is the location
+    description of the data descriptor, the compilation unit that contains E, an
+    empty initial stack, and other context elements corresponding to the source
+    language thread of execution upon which the user is focused, if any. The
+    result of the evaluation is the location description of the base of the
+    member entry.
 
-Accelerated Access
-~~~~~~~~~~~~~~~~~~
+    *E will typically involve an operation expression that begins with a*
+    ``DW_OP_push_object_address`` *operation which loads the location
+    description of the object which can then serve as a descriptor in subsequent
+    calculation.*
+
+    .. note::
+
+      Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and
+      ``DW_AT_vtable_elem_location`` allow both operation expressions and
+      location list expressions, why does ``DW_AT_data_location`` not allow
+      both? In all cases they apply to data objects so less likely that
+      optimization would cause different operation expressions for different
+      program location ranges. But if supporting for some then should be for
+      all.
+
+      It seems odd this attribute is not the same as
+      ``DW_AT_data_member_location`` in having an initial stack with the
+      location description of the object since the expression has to need it.
+
+A.6 Other Debugging Information
+-------------------------------
+
+.. note::
+
+  This section provides changes to existing debugger information entry
+  attributes. These would be incorporated into the corresponding DWARF Version 5
+  chapter 6 sections.
+
+A.6.1 Accelerated Access
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. _amdgpu-dwarf-lookup-by-name:
 
-Lookup By Name
-++++++++++++++
+A.6.1.1 Lookup By Name
+++++++++++++++++++++++
 
-Contents of the Name Index
-##########################
+A.6.1.1.1 Contents of the Name Index
+####################################
 
 .. note::
 
   The following provides changes to DWARF Version 5 section 6.1.1.1.
 
   The rule for debugger information entries included in the name index in the
   optional ``.debug_names`` section is extended to also include named
   ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location``
   attribute that includes a ``DW_OP_LLVM_form_aspace_address`` operation.
 
 The name index must contain an entry for each debugging information entry that
 defines a named subprogram, label, variable, type, or namespace, subject to the
 following rules:
 
 * ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location``
   attribute that includes a ``DW_OP_addr``, ``DW_OP_LLVM_form_aspace_address``,
   or ``DW_OP_form_tls_address`` operation are included; otherwise, they are
   excluded.
 
-Data Representation of the Name Index
-#####################################
+A.6.1.1.4 Data Representation of the Name Index
+###############################################
 
-Section Header
-^^^^^^^^^^^^^^
+.. _amdgpu-dwarf-name-index-section-header:
+
+
+A.6.1.1.4.1 Section Header
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
 
   The following provides an addition to DWARF Version 5 section 6.1.1.4.1 item
   14 ``augmentation_string``.
 
 A null-terminated UTF-8 vendor specific augmentation string, which provides
 additional information about the contents of this index. If provided, the

 .. note::
 
   This is different to the definition in DWARF Version 5 but is consistent with
   the other augmentation strings and allows multiple vendor extensions to be
   supported.
 
 .. _amdgpu-dwarf-line-number-information:
 
-Line Number Information
-~~~~~~~~~~~~~~~~~~~~~~~
+A.6.2 Line Number Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Line Number Program Header
-++++++++++++++++++++++++++++++
+A.6.2.4 The Line Number Program Header
+++++++++++++++++++++++++++++++++++++++
 
-Standard Content Descriptions
-#############################
+A.6.2.4.1 Standard Content Descriptions
+#######################################
 
 .. note::
 
   This augments DWARF Version 5 section 6.2.4.1.
 
 .. _amdgpu-dwarf-line-number-information-dw-lnct-llvm-source:
 
 1.  ``DW_LNCT_LLVM_source``
2.  ``DW_LNCT_LLVM_is_MD5``
     ``DW_LNCT_LLVM_is_MD5`` is always paired with the ``DW_FORM_udata`` form.
 
     *This allows a compilation unit to have a mixture of files with and without
     MD5 checksums. This can happen when multiple relocatable files are linked
     together.*
 
 .. _amdgpu-dwarf-call-frame-information:
 
-Call Frame Information
-~~~~~~~~~~~~~~~~~~~~~~
+A.6.4 Call Frame Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This section provides changes to existing call frame information and defines
   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.
 
-  These changes would be incorporated into the DWARF Version 5 section 6.1.
+  These changes would be incorporated into the DWARF Version 5 section 6.4.
 
 .. _amdgpu-dwarf-structure_of-call-frame-information:
 
-Structure of Call Frame Information
-+++++++++++++++++++++++++++++++++++
+A.6.4.1 Structure of Call Frame Information
++++++++++++++++++++++++++++++++++++++++++++
 
 The register rules are:
 
 *undefined*
   A register that has this rule has no recoverable value in the previous frame.
   The previous value of this register is the undefined location description (see
   :ref:`amdgpu-dwarf-undefined-location-description-operations`).
 

 
 6.  ``padding`` (array of ubyte)
 
     Enough ``DW_CFA_nop`` instructions to make the size of this entry match the
     length value above.
 
 .. _amdgpu-dwarf-call-frame-instructions:
 
-Call Frame Instructions
-+++++++++++++++++++++++
+A.6.4.2 Call Frame Instructions
++++++++++++++++++++++++++++++++
 
 Some call frame instructions have operands that are encoded as DWARF operation
 expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF
 operations that can be used in E have the following restrictions:
 
 * ``DW_OP_addrx``, ``DW_OP_call2``, ``DW_OP_call4``, ``DW_OP_call_ref``,
   ``DW_OP_const_type``, ``DW_OP_constx``, ``DW_OP_convert``,
   ``DW_OP_deref_type``, ``DW_OP_fbreg``, ``DW_OP_implicit_pointer``,
* ``DW_OP_LLVM_call_frame_entry_reg`` is not allowed if evaluating E causes a
   ``DW_OP_LLVM_call_frame_entry_reg`` *operation that specifies register R1.*
 
 *Call frame instructions to which these restrictions apply include*
 ``DW_CFA_def_cfa_expression``\ *,* ``DW_CFA_expression``\ *, and*
 ``DW_CFA_val_expression``\ *.*
 
 .. _amdgpu-dwarf-row-creation-instructions:
 
-Row Creation Instructions
-#########################
+A.6.4.2.1 Row Creation Instructions
+###################################
 
 .. note::
 
   These instructions are the same as in DWARF Version 5 section 6.4.2.1.
 
 .. _amdgpu-dwarf-cfa-definition-instructions:
 
-CFA Definition Instructions
-###########################
+A.6.4.2.2 CFA Definition Instructions
+#####################################
 
 1.  ``DW_CFA_def_cfa``
 
     The ``DW_CFA_def_cfa`` instruction takes two unsigned LEB128 operands
     representing a register number R and a (non-factored) byte displacement B.
     AS is set to the target architecture default address space identifier. The
     required action is to define the current CFA rule to be the result of
     evaluating the DWARF operation expression ``DW_OP_constu AS;
     DW_OP_aspace_bregx R, B`` as a location description.
 
 2.  ``DW_CFA_def_cfa_sf``
 
     The ``DW_CFA_def_cfa_sf`` instruction takes two operands: an unsigned LEB128
     value representing a register number R and a signed LEB128 factored byte
     displacement B. AS is set to the target architecture default address space
     identifier. The required action is to define the current CFA rule to be the
     result of evaluating the DWARF operation expression ``DW_OP_constu AS;
-    DW_OP_aspace_bregx R, B*data_alignment_factor`` as a location description.
+    DW_OP_aspace_bregx R, B * data_alignment_factor`` as a location description.
 
     *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second
     operand is signed and factored.*
 
 3.  ``DW_CFA_LLVM_def_aspace_cfa`` *New*
 
     The ``DW_CFA_LLVM_def_aspace_cfa`` instruction takes three unsigned LEB128
     operands representing a register number R, a (non-factored) byte
     displacement B, and a target architecture specific address space identifier
     AS. The required action is to define the current CFA rule to be the result
     of evaluating the DWARF operation expression ``DW_OP_constu AS;
     DW_OP_aspace_bregx R, B`` as a location description.
 
     If AS is not one of the values defined by the target architecture specific
     ``DW_ASPACE_*`` values then the DWARF expression is ill-formed.
 
 4.  ``DW_CFA_LLVM_def_aspace_cfa_sf`` *New*
 
     The ``DW_CFA_def_cfa_sf`` instruction takes three operands: an unsigned
     LEB128 value representing a register number R, a signed LEB128 factored byte
     displacement B, and an unsigned LEB128 value representing a target
     architecture specific address space identifier AS. The required action is to
     define the current CFA rule to be the result of evaluating the DWARF
     operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R,
-    B*data_alignment_factor`` as a location description.
+    B * data_alignment_factor`` as a location description.
 
     If AS is not one of the values defined by the target architecture specific
     ``DW_ASPACE_*`` values, then the DWARF expression is ill-formed.
 
     *The action is the same as* ``DW_CFA_aspace_def_cfa``\ *, except that the
     second operand is signed and factored.*
 
 5.  ``DW_CFA_def_cfa_register``
6.  ``DW_CFA_def_cfa_offset``
     If the subprogram has no current CFA rule, or the rule was defined by a
     ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.
 
 7.  ``DW_CFA_def_cfa_offset_sf``
 
     The ``DW_CFA_def_cfa_offset_sf`` instruction takes a signed LEB128 operand
     representing a factored byte displacement B. The required action is to
     define the current CFA rule to be the result of evaluating the DWARF
-    operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R,
-    B*data_alignment_factor`` as a location description. R and AS are the old
-    CFA register number and address space respectively.
+    operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, B *
+    data_alignment_factor`` as a location description. R and AS are the old CFA
+    register number and address space respectively.
 
     If the subprogram has no current CFA rule, or the rule was defined by a
     ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.
 
     *The action is the same as* ``DW_CFA_def_cfa_offset``\ *, except that the
     operand is signed and factored.*
 
 8.  ``DW_CFA_def_cfa_expression``
 
     The ``DW_CFA_def_cfa_expression`` instruction takes a single operand encoded
     as a ``DW_FORM_exprloc`` value representing a DWARF operation expression E.
     The required action is to define the current CFA rule to be the result of
     evaluating E with the current context, except the result kind is a location
     description, the compilation unit is unspecified, the object is unspecified,
     and an empty initial stack.
 
     *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on
     the DWARF expression operations that can be used in E.*
 
     The DWARF is ill-formed if the result of evaluating E is not a memory byte
     address location description.
 
 .. _amdgpu-dwarf-register-rule-instructions:
 
-Register Rule Instructions
-##########################
+A.6.4.2.3 Register Rule Instructions
+####################################
 
 1.  ``DW_CFA_undefined``
 
     The ``DW_CFA_undefined`` instruction takes a single unsigned LEB128 operand
     that represents a register number R. The required action is to set the rule
     for the register specified by R to ``undefined``.
 
 2.  ``DW_CFA_same_value``
 
     The ``DW_CFA_same_value`` instruction takes a single unsigned LEB128 operand
     that represents a register number R. The required action is to set the rule
     for the register specified by R to ``same value``.
 
 3.  ``DW_CFA_offset``
 
     The ``DW_CFA_offset`` instruction takes two operands: a register number R
     (encoded with the opcode) and an unsigned LEB128 constant representing a
     factored displacement B. The required action is to change the rule for the
-    register specified by R to be an *offset(B\*data_alignment_factor)* rule.
+    register specified by R to be an *offset(B \* data_alignment_factor)* rule.
 
     .. note::
 
       Seems this should be named ``DW_CFA_offset_uf`` since the offset is
       unsigned factored.
 
 4.  ``DW_CFA_offset_extended``
 
5.  ``DW_CFA_offset_extended_sf``
     factored displacement B. This instruction is identical to
     ``DW_CFA_offset_extended``, except that B is signed.
 
 6.  ``DW_CFA_val_offset``
 
     The ``DW_CFA_val_offset`` instruction takes two unsigned LEB128 operands
     representing a register number R and a factored displacement B. The required
     action is to change the rule for the register indicated by R to be a
-    *val_offset(B\*data_alignment_factor)* rule.
+    *val_offset(B \* data_alignment_factor)* rule.
 
     .. note::
 
       Seems this should be named ``DW_CFA_val_offset_uf`` since the displacement
       is unsigned factored.
 
     .. note::
 

 
 12. ``DW_CFA_restore_extended``
 
     The ``DW_CFA_restore_extended`` instruction takes a single unsigned LEB128
     operand that represents a register number R. This instruction is identical
     to ``DW_CFA_restore``, except for the encoding and size of the register
     operand.
 
-Row State Instructions
-######################
+A.6.4.2.4 Row State Instructions
+################################
 
 .. note::
 
   These instructions are the same as in DWARF Version 5 section 6.4.2.4.
 
-Padding Instruction
-###################
+A.6.4.2.5 Padding Instruction
+#############################
 
 .. note::
 
   These instructions are the same as in DWARF Version 5 section 6.4.2.5.
 
-Call Frame Instruction Usage
-++++++++++++++++++++++++++++
+A.6.4.3 Call Frame Instruction Usage
+++++++++++++++++++++++++++++++++++++
 
 .. note::
 
   The same as in DWARF Version 5 section 6.4.3.
 
 .. _amdgpu-dwarf-call-frame-calling-address:
 
-Call Frame Calling Address
-++++++++++++++++++++++++++
+A.6.4.4 Call Frame Calling Address
+++++++++++++++++++++++++++++++++++
 
 .. note::
 
   The same as in DWARF Version 5 section 6.4.4.
 
-Data Representation
--------------------
+A.7 Data Representation
+-----------------------
+
+.. note::
+
+  This section provides changes to existing debugger information entry
+  attributes. These would be incorporated into the corresponding DWARF Version 5
+  chapter 7 sections.
 
 .. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats:
 
-32-Bit and 64-Bit DWARF Formats
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.7.4 32-Bit and 64-Bit DWARF Formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
-  This augments DWARF Version 5 section 7.4.
-
-1.  Within the body of the ``.debug_info`` section, certain forms of attribute
-    value depend on the choice of DWARF format as follows. For the 32-bit DWARF
-    format, the value is a 4-byte unsigned integer; for the 64-bit DWARF format,
-    the value is an 8-byte unsigned integer.
+  This augments DWARF Version 5 section 7.4 list item 3's table.
 
-    .. table:: ``.debug_info`` section attribute form roles
-      :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table
 
-      ================================== ===================================
-      Form                               Role
-      ================================== ===================================
-      DW_FORM_line_strp                  offset in ``.debug_line_str``
-      DW_FORM_ref_addr                   offset in ``.debug_info``
-      DW_FORM_sec_offset                 offset in a section other than
-                                         ``.debug_info`` or ``.debug_str``
-      DW_FORM_strp                       offset in ``.debug_str``
-      DW_FORM_strp_sup                   offset in ``.debug_str`` section of
-                                         supplementary object file
-      DW_OP_call_ref                     offset in ``.debug_info``
-      DW_OP_implicit_pointer             offset in ``.debug_info``
-      DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info``
-      ================================== ===================================
 
-Format of Debugging Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.7.5 Format of Debugging Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Attribute Encodings
-+++++++++++++++++++
+A.7.5.4 Attribute Encodings
++++++++++++++++++++++++++++
 
 .. note::
 
   This augments DWARF Version 5 section 7.5.4 and Table 7.5.
 
 The following table gives the encoding of the additional debugging information
 entry attributes.
 
 .. table:: Attribute encodings
    :name: amdgpu-dwarf-attribute-encodings-table
 
    ================================== ====== ===================================
    Attribute Name                     Value  Classes
    ================================== ====== ===================================
    DW_AT_LLVM_active_lane             0x3e08 exprloc, loclist
    DW_AT_LLVM_augmentation            0x3e09 string
    DW_AT_LLVM_lanes                   0x3e0a constant
    DW_AT_LLVM_lane_pc                 0x3e0b exprloc, loclist
    DW_AT_LLVM_vector_size             0x3e0c constant
    ================================== ====== ===================================
 
-DWARF Expressions
-~~~~~~~~~~~~~~~~~
+.. _amdgpu-dwarf-classes-and-forms:
+
+A.7.5.5 Classes and Forms
++++++++++++++++++++++++++
+
+.. note::
+
+  The same as in DWARF Version 5 section 7.5.5.
+
+A.7.7 DWARF Expressions
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   Rename DWARF Version 5 section 7.7 to reflect the unification of location
   descriptions into DWARF expressions.
 
-Operation Expressions
-+++++++++++++++++++++
+A.7.7.1 Operation Expressions
++++++++++++++++++++++++++++++
 
 .. note::
 
   Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect the
   unification of location descriptions into DWARF expressions.
 
   This augments DWARF Version 5 section 7.7.1 and Table 7.9.
 
DW_OP_LLVM_aspace_implicit_pointer 0xe9     2     4-byte or 8-byte offset of DIE,
                                                      SLEB128 byte displacement
    DW_OP_LLVM_piece_end               0xea     0
    DW_OP_LLVM_extend                  0xeb     2     ULEB128 bit size,
                                                      ULEB128 count
    DW_OP_LLVM_select_bit_piece        0xec     2     ULEB128 bit size,
                                                      ULEB128 count
    ================================== ===== ======== ===============================
 
-Location List Expressions
-+++++++++++++++++++++++++
+A.7.7.3 Location List Expressions
++++++++++++++++++++++++++++++++++
 
 .. note::
 
   Rename DWARF Version 5 section 7.7.3 to reflect that location lists are a kind
   of DWARF expression.
 
-Source Languages
-~~~~~~~~~~~~~~~~
+A.7.12 Source Languages
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This augments DWARF Version 5 section 7.12 and Table 7.17.
 
 The following table gives the encoding of the additional DWARF languages.
 
 .. table:: Language encodings
    :name: amdgpu-dwarf-language-encodings-table
 
    ==================== ====== ===================
    Language Name        Value  Default Lower Bound
    ==================== ====== ===================
    ``DW_LANG_LLVM_HIP`` 0x8100 0
    ==================== ====== ===================
 
-Address Class and Address Space Encodings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.7.13 Address Class and Address Space Encodings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This replaces DWARF Version 5 section 7.13.
 
 The encodings of the constants used for the currently defined address classes
 are given in :ref:`amdgpu-dwarf-address-class-encodings-table`.
 
 .. table:: Address class encodings
    :name: amdgpu-dwarf-address-class-encodings-table
 
    ========================== ======
    Address Class Name         Value
    ========================== ======
    ``DW_ADDR_none``           0x0000
    ``DW_ADDR_LLVM_global``    0x0001
    ``DW_ADDR_LLVM_constant``  0x0002
    ``DW_ADDR_LLVM_group``     0x0003
    ``DW_ADDR_LLVM_private``   0x0004
    ``DW_ADDR_LLVM_lo_user``   0x8000
    ``DW_ADDR_LLVM_hi_user``   0xffff
    ========================== ======
 
-Line Number Information
-~~~~~~~~~~~~~~~~~~~~~~~
+A.7.22 Line Number Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This augments DWARF Version 5 section 7.22 and Table 7.27.
 
 The following table gives the encoding of the additional line number header
 entry formats.
 
 .. table:: Line number header entry format encodings
   :name: amdgpu-dwarf-line-number-header-entry-format-encodings-table
 
   ====================================  ====================
   Line number header entry format name  Value
   ====================================  ====================
   ``DW_LNCT_LLVM_source``               0x2001
   ``DW_LNCT_LLVM_is_MD5``               0x2002
   ====================================  ====================
 
-Call Frame Information
-~~~~~~~~~~~~~~~~~~~~~~
+A.7.24 Call Frame Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This augments DWARF Version 5 section 7.24 and Table 7.29.
 
 The following table gives the encoding of the additional call frame information
 instructions.
 
 .. table:: Call frame instruction encodings
    :name: amdgpu-dwarf-call-frame-instruction-encodings-table
 
    ============================= ====== ====== ================ ================ =====================
    Instruction                   High 2 Low 6  Operand 1        Operand 2        Operand 3
                                  Bits   Bits
    ============================= ====== ====== ================ ================ =====================
    DW_CFA_LLVM_def_aspace_cfa    0      0x30   ULEB128 register ULEB128 offset   ULEB128 address space
    DW_CFA_LLVM_def_aspace_cfa_sf 0      0x31   ULEB128 register SLEB128 offset   ULEB128 address space
    ============================= ====== ====== ================ ================ =====================
 
-Attributes by Tag Value (Informative)
--------------------------------------
+A. Attributes by Tag Value (Informative)
+----------------------------------------
 
 .. note::
 
   This augments DWARF Version 5 Appendix A and Table A.1.
 
 The following table provides the additional attributes that are applicable to
 debugger information entries.
 
``DW_TAG_inlined_subroutine`` * ``DW_AT_LLVM_active_lane``
                                  * ``DW_AT_LLVM_lanes``
    ``DW_TAG_subprogram``         * ``DW_AT_LLVM_active_lane``
                                  * ``DW_AT_LLVM_lane_pc``
                                  * ``DW_AT_LLVM_lanes``
    ============================= =============================
 
 .. _amdgpu-dwarf-examples:
 
-Examples
-========
+B. Examples
+===========
 
 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::
 
   Change examples to use ``DW_OP_LLVM_offset`` instead of ``DW_OP_add`` when
   acting on a location description.
 
   Need to provide examples of new features.
 
 .. _amdgpu-dwarf-references:
 
-References
-==========
+C. References
+=============
 
     .. _amdgpu-dwarf-AMD:
 
 1.  [AMD] `Advanced Micro Devices <https://www.amd.com/>`__
 
+    .. _amdgpu-dwarf-AMD-ROCgdb:
+
+2.  [AMD-ROCgdb] `AMD ROCm Debugger (ROCgdb) <https://github.com/ROCm-Developer-Tools/ROCgdb>`__
+
     .. _amdgpu-dwarf-AMD-ROCm:
 
-2.  [AMD-ROCm] `AMD ROCm Platform <https://rocm-documentation.readthedocs.io>`__
+3.  [AMD-ROCm] `AMD ROCm Platform <https://rocm-documentation.readthedocs.io>`__
 
-    .. _amdgpu-dwarf-AMD-ROCgdb:
+    .. _amdgpu-dwarf-AMDGPU-DWARF-LOC:
 
-3.  [AMD-ROCgdb] `AMD ROCm Debugger (ROCgdb) <https://github.com/ROCm-Developer-Tools/ROCgdb>`__
+4.  [AMDGPU-DWARF-LOC] `Allow Location Descriptions on the DWARF Expression Stack <https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html>`__
 
     .. _amdgpu-dwarf-AMDGPU-LLVM:
 
-4.  [AMDGPU-LLVM] `User Guide for AMDGPU LLVM Backend <https://llvm.org/docs/AMDGPUUsage.html>`__
+5.  [AMDGPU-LLVM] `User Guide for AMDGPU LLVM Backend <https://llvm.org/docs/AMDGPUUsage.html>`__
 
     .. _amdgpu-dwarf-CUDA:
 
-5.  [CUDA] `Nvidia CUDA Language <https://docs.nvidia.com/cuda/cuda-c-programming-guide/>`__
+6.  [CUDA] `Nvidia CUDA Language <https://docs.nvidia.com/cuda/cuda-c-programming-guide/>`__
 
     .. _amdgpu-dwarf-DWARF:
 
-6.  [DWARF] `DWARF Debugging Information Format <http://dwarfstd.org/>`__
+7.  [DWARF] `DWARF Debugging Information Format <http://dwarfstd.org/>`__
 
     .. _amdgpu-dwarf-ELF:
 
-7.  [ELF] `Executable and Linkable Format (ELF) <http://www.sco.com/developers/gabi/>`__
+8.  [ELF] `Executable and Linkable Format (ELF) <http://www.sco.com/developers/gabi/>`__
 
     .. _amdgpu-dwarf-GCC:
 
-8.  [GCC] `GCC: The GNU Compiler Collection <https://www.gnu.org/software/gcc/>`__
+9.  [GCC] `GCC: The GNU Compiler Collection <https://www.gnu.org/software/gcc/>`__
 
     .. _amdgpu-dwarf-GDB:
 
-9.  [GDB] `GDB: The GNU Project Debugger <https://www.gnu.org/software/gdb/>`__
+10. [GDB] `GDB: The GNU Project Debugger <https://www.gnu.org/software/gdb/>`__
 
     .. _amdgpu-dwarf-HIP:
 
-10. [HIP] `HIP Programming Guide <https://rocm-documentation.readthedocs.io/en/latest/Programming_Guides/Programming-Guides.html#hip-programing-guide>`__
+11. [HIP] `HIP Programming Guide <https://rocm-documentation.readthedocs.io/en/latest/Programming_Guides/Programming-Guides.html#hip-programing-guide>`__
 
     .. _amdgpu-dwarf-HSA:
 
-11. [HSA] `Heterogeneous System Architecture (HSA) Foundation <http://www.hsafoundation.com/>`__
+12. [HSA] `Heterogeneous System Architecture (HSA) Foundation <http://www.hsafoundation.com/>`__
 
     .. _amdgpu-dwarf-LLVM:
 
-12. [LLVM] `The LLVM Compiler Infrastructure <https://llvm.org/>`__
+13. [LLVM] `The LLVM Compiler Infrastructure <https://llvm.org/>`__
 
     .. _amdgpu-dwarf-OpenCL:
 
-13. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__
+14. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__
 
     .. _amdgpu-dwarf-Perforce-TotalView:
 
-14. [Perforce-TotalView] `Perforce TotalView HPC Debugging Software <https://totalview.io/products/totalview>`__
+15. [Perforce-TotalView] `Perforce TotalView HPC Debugging Software <https://totalview.io/products/totalview>`__
 
     .. _amdgpu-dwarf-SEMVER:
 
-15. [SEMVER] `Semantic Versioning <https://semver.org/>`__
+16. [SEMVER] `Semantic Versioning <https://semver.org/>`__

llvm/docs/AMDGPUUsage.rst

 controlled by the execution mask. An undefined location description together
 with ``DW_OP_LLVM_extend`` is used to indicate the lane was not active on entry
 to the subprogram. See :ref:`amdgpu-dwarf-dw-at-llvm-lane-pc` for an example.
 
 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 *DWARF Extensions For Heterogeneous Debugging* section
-:ref:`amdgpu-dwarf-debugging-information-entry-attributes`.
+used by AMDGPU. See the sections in DWARF Version 5 section 3.3.5 and 3.1.1
+which are updated by *DWARF Extensions For Heterogeneous Debugging* section
+:ref:`amdgpu-dwarf-low-level-information` and
+:ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`.
 
 .. _amdgpu-dwarf-dw-at-llvm-lane-pc:
 
 ``DW_AT_LLVM_lane_pc``
 ~~~~~~~~~~~~~~~~~~~~~~
 
 For AMDGPU, the ``DW_AT_LLVM_lane_pc`` attribute is used to specify the program
 location of the separate lanes of a SIMT thread.