[AMDGPU][NFC] Heterogeneous DWARF extensions update

[t-tye]

Summary

• Clarify CFI rules in heterogeneous DWARF extensions

• Added DWARF source language memory spaces.

• Added DWARF architecture address spaces.

• Other minor corrections.

[t-tye]

Add common block DW_AT_location description.

[scott.linder]

LGTM save a few nits/questions

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

3614

This "attribute" is outside of the code-backticks in other places, did you intend to put it inside here?

3701

This comma seems extraneous

4681

I assume this is saying "the rest of the existing DWARF5 text as-is"?

4683

This is just removing the text "For references from one shared object or static executable file to another, the relocation and identification of the target object must be performed by the consumer", right? Is this because it is redundant (and covered by the non-normative notes)?

4876

Is the second column required for this to parse, or to match the two-column layout in the spec?

[t-tye]

Fix review comments.

[t-tye]

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

3614

Fixed.

3701

Fixed.

4681

Correct.

4683

DWARF does not provide any means to identify a reference from one linked object to another. For all practical purposes, DW_OP_call_ref, DW_OP_implicit_pointer, and DW_FORM_ref_addr can only be used to refer to an offset within the same executable or shared object. Their purpose is for references between compilation units, not between linked objects. Therefore mention of the consumer resolving the reference to another executable/shared object has been removed from all three places.

4876

It was the only way I found to stop the parser complaining about a single table being expected.

[scott.linder]

LGTM, thank you!

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

4683

OK, I see now, thank you for clarifying!

4876

Makes sense, I assumed as much, just making sure it wasn't an oversight

llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md

5.  `DW_OP_swap`
     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.
 
+<i>Examples illustrating many of these stack operations are found in Appendix
+D.1.2 on page 289.</i>
+
 ##### 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`
1.  `DW_OP_implicit_value`
     It pushes location description L with one implicit location description SL
     on the stack. SL specifies LS with a bit offset of 0.
 
 2.  `DW_OP_stack_value`
 
     `DW_OP_stack_value` pops one stack entry that must be a value V.
 
     An implicit location storage LS is created with the literal value V using
-    the size, encoding, and enianity specified by V's base type.
+    the size, encoding, and endianity specified by V's base type.
 
     It pushes a location description L with one implicit location description SL
     on the stack. SL specifies LS with a bit offset of 0.
 
     <i>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.</i>
 
     See `DW_OP_implicit_pointer` (following) for special rules concerning
     implicit pointer values produced by dereferencing implicit location
     descriptions created by the `DW_OP_implicit_pointer` operation.
 
-    > 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.
+    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`
 
     <i>An optimizing compiler may eliminate a pointer, while still retaining the
     value that the pointer addressed. `DW_OP_implicit_pointer` allows a producer
     to describe this value.</i>
 
     <i>`DW_OP_implicit_pointer` specifies an object is a pointer to the target
6.  <i>expression(E)</i>
     E is evaluated with the current context, except the result kind is a
     location description, the compilation unit is unspecified, the object is
     unspecified, and an initial stack comprising the location description of the
     current CFA (see [2.5.4 DWARF Operation
     Expressions](#dwarf-operation-expressions)).
 
 7.  <i>val_expression(E)</i>
 
-    The previous value of this register is the value produced by evaluating the
-    DWARF operation expression E (see [2.5.4 DWARF Operation
+    The previous value of this register is located at the implicit location
+    description created from the value produced by evaluating the DWARF
+    operation expression E (see [2.5.4 DWARF Operation
     Expressions](#dwarf-operation-expressions)).
 
     E is evaluated with the current context, except the result kind is a value,
     the compilation unit is unspecified, the object is unspecified, and an
     initial stack comprising the location description of the current CFA (see
     [2.5.4 DWARF Operation Expressions](#dwarf-operation-expressions)).
 
     The DWARF is ill-formed if the resulting value type size does not match the

 > NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.1.
 
 ##### 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.
-    The required action is to define the current CFA rule to be the result of
-    evaluating the DWARF operation expression `DW_OP_bregx R, B` as a location
-    description.
+    The required action is to define the current CFA rule to be equivalent to
+    the result of evaluating the DWARF operation expression `DW_OP_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. The required action is to define the current CFA rule to be
-    the result of evaluating the DWARF operation expression `DW_OP_bregx R, B *
-    data_alignment_factor` as a location description.
+    equivalent to the result of evaluating the DWARF operation expression
+    `DW_OP_bregx R, B * data_alignment_factor` as a location description.
 
     <i>The action is the same as `DW_CFA_def_cfa`, except that the second
     operand is signed and factored.</i>
 
 3.  `DW_CFA_def_cfa_register`
 
     The `DW_CFA_def_cfa_register` instruction takes a single unsigned LEB128
     operand representing a register number R. The required action is to define
-    the current CFA rule to be the result of evaluating the DWARF operation
-    expression `DW_OP_bregx R, B` as a location description. B is the old CFA
-    byte displacement.
+    the current CFA rule to be equivalent to the result of evaluating the DWARF
+    operation expression `DW_OP_bregx R, B` as a location description. B is the
+    old CFA byte displacement.
 
     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.
 
 4.  `DW_CFA_def_cfa_offset`
 
     The `DW_CFA_def_cfa_offset` instruction takes a single unsigned LEB128
     operand representing a (non-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_bregx R, B` as a location description. R
-    is the old CFA register number.
+    action is to define the current CFA rule to be equivalent to the result of
+    evaluating the DWARF operation expression `DW_OP_bregx R, B` as a location
+    description. R is the old CFA register number.
 
     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.
 
 5.  `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_bregx R, B * data_alignment_factor` as a
+    define the current CFA rule to be equivalent to the result of evaluating the
+    DWARF operation expression `DW_OP_bregx R, B * data_alignment_factor` as a
     location description. R is the old CFA register number.
 
     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.
 
     <i>The action is the same as `DW_CFA_def_cfa_offset`, except that the
     operand is signed and factored.</i>
 
 6.  `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.
+    The required action is to define the current CFA rule to be equivalent to
+    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.
 
     <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
     restrictions on the DWARF expression operations that can be used in E.</i>
 
     The DWARF is ill-formed if the result of evaluating E is not a memory byte
     address location description.
 
 ##### A.6.4.2.3 Register Rule Instructions

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

 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.
 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
+:ref:`amdgpu-dwarf-further-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:
 
 2. Extensions
 =============
 

 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.
+:ref:`amdgpu-dwarf-further-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

 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.
+:ref:`amdgpu-dwarf-further-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
+2.14 Define Source Language Memory 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.
+that define source language memory classes. Support is added to define language
+specific memory spaces 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.
+Support for using memory spaces in defining source language types and data
+object allocation is also added.
 
-See :ref:`amdgpu-dwarf-segment_addresses`.
+See :ref:`amdgpu-dwarf-memory-spaces`.
 
 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
.. note::
 
   This augments DWARF Version 5 section 2.2 and Table 2.2.
 
 The following table provides the additional attributes.
 
 .. table:: Attribute names
    :name: amdgpu-dwarf-attribute-names-table
 
-   =========================== ====================================
-   Attribute                   Usage
-   =========================== ====================================
-   ``DW_AT_LLVM_active_lane``  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``      SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`)
-   ``DW_AT_LLVM_lanes``        SIMT lane count (see :ref:`amdgpu-dwarf-low-level-information`)
-   ``DW_AT_LLVM_iterations``   Concurrent iteration count (see :ref:`amdgpu-dwarf-low-level-information`)
-   ``DW_AT_LLVM_vector_size``  Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`)
-   =========================== ====================================
+   ============================ ====================================
+   Attribute                    Usage
+   ============================ ====================================
+   ``DW_AT_LLVM_active_lane``   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``       SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_lanes``         SIMT lane count (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_iterations``    Concurrent iteration count (see :ref:`amdgpu-dwarf-low-level-information`)
+   ``DW_AT_LLVM_vector_size``   Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`)
+   ``DW_AT_LLVM_address_space`` Architecture specific address space (see :ref:`amdgpu-dwarf-address-spaces`)
+   ``DW_AT_LLVM_memory_space``  Pointer or reference types (see 5.3 "Type Modifier Entries")
+                                Data objects (see 4.1 "Data Object Entries")
+   ============================ ====================================
 
 .. _amdgpu-dwarf-expressions:
 
 A.2.5 DWARF Expressions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 

 (see :ref:`amdgpu-dwarf-location-list-expressions`).
 
 .. _amdgpu-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
+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.
 

 result of the evaluation is an error.
 
 *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 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:
5.  ``DW_OP_swap``
     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.
 
+*Examples illustrating many of these stack operations are found in Appendix
+D.1.2 on page 289.*
+
 .. _amdgpu-dwarf-control-flow-operations:
 
 A.2.5.4.2 Control Flow Operations
 #################################
 
 .. note::
 
   This section replaces DWARF Version 5 section 2.5.1.5.

 address space that corresponds to the memory location storage associated with
 the memory location description.
 
 A location description that is comprised of one byte address memory location
 description SL is defined to be a memory byte address location description. It
 has a byte address equal to A and an address space equal to AS of the
 corresponding SL.
 
-``DW_ASPACE_none`` is defined as the target architecture default address space.
-See :ref:`amdgpu-dwarf-segment_addresses`.
+``DW_ASPACE_LLVM_none`` is defined as the target architecture default address
+space. See :ref:`amdgpu-dwarf-address-spaces`.
 
 If a stack entry is required to be a location description, but it is a value V
 with the generic type, then it is implicitly converted to a location description
 L with one memory location description SL. SL specifies the memory location
 storage that corresponds to the target architecture default address space with a
 bit offset equal to V scaled by 8 (the byte size).
 
 .. note::
3.  ``DW_OP_LLVM_form_aspace_address`` *New*
     storage for the current thread. For languages that are implemented using a
     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.
+    the target architecture specific ``DW_ASPACE_LLVM_*`` values.
 
     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_aspace_implicit_pointer`` operations.
 
 4.  ``DW_OP_form_tls_address``
 
9.  ``DW_OP_LLVM_aspace_bregx`` *New*
     entry that is required to be an integral type value that represents a target
     architecture specific address space identifier AS.
 
     The action is the same as for ``DW_OP_breg<N>``, except that R is used as
     the register number, B is used as the byte displacement, and AS is used as
     the address space identifier.
 
     The DWARF expression is ill-formed if AS is not one of the values defined by
-    the target architecture specific ``DW_ASPACE_*`` values.
+    the target architecture specific ``DW_ASPACE_LLVM_*`` values.
 
     .. note::
 
       Could also consider adding ``DW_OP_LLVM_aspace_breg0,
       DW_OP_LLVM_aspace_breg1, ..., DW_OP_LLVM_aspace_bref31`` which would save
       encoding size.
 
 .. _amdgpu-dwarf-register-location-description-operations:
1.  ``DW_OP_implicit_value``
     It pushes location description L with one implicit location description SL
     on the stack. SL specifies LS with a bit offset of 0.
 
 2.  ``DW_OP_stack_value``
 
     ``DW_OP_stack_value`` pops one stack entry that must be a value V.
 
     An implicit location storage LS is created with the literal value V using
-    the size, encoding, and enianity specified by V's base type.
+    the size, encoding, and endianity specified by V's base type.
 
     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 ``DW_OP_implicit_pointer`` (following) for special rules concerning
     implicit pointer values produced by dereferencing implicit location
     descriptions created by the ``DW_OP_implicit_pointer`` and
     ``DW_OP_LLVM_aspace_implicit_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.
+    Note: Since location descriptions are allowed on the stack, the
 
 3.  ``DW_OP_implicit_pointer``
 
     *An optimizing compiler may eliminate a pointer, while still retaining the
     value that the pointer addressed.* ``DW_OP_implicit_pointer`` *allows a
     producer to describe this value.*
 
     ``DW_OP_implicit_pointer`` *specifies an object is a pointer to the target
4.  ``DW_OP_LLVM_aspace_implicit_pointer`` *New*
     It pops one stack entry that must be an integral type value that represents
     a target architecture specific address space identifier AS.
 
     The location description L that is pushed on the stack is the same as for
     ``DW_OP_implicit_pointer``, except that the address space identifier used is
     AS.
 
     The DWARF expression is ill-formed if AS is not one of the values defined by
-    the target architecture specific ``DW_ASPACE_*`` values.
+    the target architecture specific ``DW_ASPACE_LLVM_*`` values.
 
     .. note::
 
       This definition of ``DW_OP_LLVM_aspace_implicit_pointer`` may change when
       full support for address classes is added as required for languages such
       as OpenCL/SyCL.
 
 *Typically a* ``DW_OP_implicit_pointer`` *or*
5.  ``DW_OP_LLVM_select_bit_piece`` *New*
 
     A location description L comprised of one complete composite location
     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.
 
+    .. note::
+
+      Should the count operand for DW_OP_extend and DW_OP_select_bit_piece be
+      changed to get the count value off the stack? This would allow support for
+      architectures that have variable length vector instructions such as ARM
+      and RISC-V.
+
 6.  ``DW_OP_LLVM_overlay`` *New*
 
     ``DW_OP_LLVM_overlay`` pops four stack entries. The first must be an
     integral type value that represents the overlay byte size value S. The
     second must be an integral type value that represents the overlay byte
     offset value O. The third must be a location description that represents the
     overlay location description OL. The fourth must be a location description
     that represents the base location description BL.

 *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:
+.. _amdgpu-dwarf-address-spaces:
 
-A.2.12 Segmented Addresses
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.2.13 Address Spaces
+~~~~~~~~~~~~~~~~~~~~~
 
 .. 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
-information entries.
-
-Each DWARF address class is conceptually a separate source language memory space
-with its own lifetime and aliasing rules. DWARF address classes are used to
-specify the source language memory spaces that pointer type and reference type
-values refer, and to specify the source language memory space in which variables
-are allocated.
-
-The set of currently defined source language DWARF address classes, together
-with source language mappings, is given in
-:ref:`amdgpu-dwarf-address-class-table`.
-
-Vendor defined source language address classes may be defined using codes in the
-range ``DW_ADDR_LLVM_lo_user`` to ``DW_ADDR_LLVM_hi_user``.
-
-.. table:: Address class
-   :name: amdgpu-dwarf-address-class-table
-
-   ========================= ============ ========= ========= =========
-   Address Class Name        Meaning      C/C++     OpenCL    CUDA/HIP
-   ========================= ============ ========= ========= =========
-   ``DW_ADDR_none``          generic      *default* generic   *default*
-   ``DW_ADDR_LLVM_global``   global                 global
-   ``DW_ADDR_LLVM_constant`` constant               constant  constant
-   ``DW_ADDR_LLVM_group``    thread-group           local     shared
-   ``DW_ADDR_LLVM_private``  thread                 private
-   ``DW_ADDR_LLVM_lo_user``
-   ``DW_ADDR_LLVM_hi_user``
-   ========================= ============ ========= ========= =========
+  This is a new section after DWARF Version 5 section 2.12 Segmented Addresses.
 
 DWARF address spaces correspond to target architecture specific linear
 addressable memory areas. They are used in DWARF expression location
 descriptions to describe in which target architecture specific memory area data
 resides.
 
 *Target architecture specific DWARF address spaces may correspond to hardware
 supported facilities such as memory utilizing base address registers, scratchpad
 memory, and memory with special interleaving. The size of addresses in these
 address spaces may vary. Their access and allocation may be hardware managed
 with each thread or group of threads having access to independent storage. For
 these reasons they may have properties that do not allow them to be viewed as
 part of the unified global virtual address space accessible by all threads.*
 
 *It is target architecture specific whether multiple DWARF address spaces are
-supported and how source language DWARF address classes map to target
-architecture specific DWARF address spaces. A target architecture may map
-multiple source language DWARF address classes to the same target architecture
-specific DWARF address class. Optimization may determine that variable lifetime
-and access pattern allows them to be allocated in faster scratchpad memory
-represented by a different DWARF address space.*
+supported and how source language memory spaces map to target architecture
+specific DWARF address spaces. A target architecture may map multiple source
+language memory spaces to the same target architecture specific DWARF address
+class. Optimization may determine that variable lifetime and access pattern
+allows them to be allocated in faster scratchpad memory represented by a
+different DWARF address space than the default for the source language memory
+space.*
 
 Although DWARF address space identifiers are target architecture specific,
-``DW_ASPACE_none`` is a common address space supported by all target
-architectures.
+``DW_ASPACE_LLVM_none`` is a common address space supported by all target
+architectures, and defined as the target architecture default address space.
 
 DWARF address space identifiers are used by:
 
-* The DWARF expression operations: ``DW_OP_LLVM_aspace_bregx``,
-  ``DW_OP_LLVM_form_aspace_address``, ``DW_OP_LLVM_aspace_implicit_pointer``,
-  and ``DW_OP_xderef*``.
+* The ``DW_AT_LLVM_address_space`` attribute.
 
-* The CFI instructions: ``DW_CFA_LLVM_def_aspace_cfa`` and
-  ``DW_CFA_LLVM_def_aspace_cfa_sf``.
+* The DWARF expression operations: ``DW_OP_aspace_bregx``,
+  ``DW_OP_form_aspace_address``, ``DW_OP_aspace_implicit_pointer``, and
+  ``DW_OP_xderef*``.
 
-.. note::
-
-  With the definition of DWARF address classes and DWARF address spaces in these
-  extensions, DWARF Version 5 table 2.7 needs to be updated. It seems it is an
-  example of DWARF address spaces and not DWARF address classes.
+* The CFI instructions: ``DW_CFA_def_aspace_cfa`` and
+  ``DW_CFA_def_aspace_cfa_sf``.
 
 .. note::
 
-  With the expanded support for DWARF address spaces in these extensions, it may
-  be worth examining if DWARF segments can be eliminated and DWARF address
-  spaces used instead.
+  Currently, DWARF defines address class values as being target architecture
+  specific, and defines a DW_AT_address_class attribute. With the removal of
+  DW_AT_segment in DWARF 6, it is unclear how the address class is intended to
+  be used as the term is not used elsewhere. Should these be replaced by this
+  proposal's more complete address space? Or are they intended to represent
+  source language memory spaces such as in OpenCL?
 
-  That may involve extending DWARF address spaces to also be used to specify
-  code locations. In target architectures that use different memory areas for
-  code and data this would seem a natural use for DWARF address spaces. This
-  would allow DWARF expression location descriptions to be used to describe the
-  location of subprograms and entry points that are used in expressions
-  involving subprogram pointer type values.
+.. _amdgpu-dwarf-memory-spaces:
 
-  Currently, DWARF expressions assume data and code resides in the same default
-  DWARF address space, and only the address ranges in DWARF location list
-  entries and in the ``.debug_aranges`` section for accelerated access for
-  addresses allow DWARF segments to be used to distinguish.
+A.2.14 Memory Spaces
+~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
-  Currently, DWARF defines address class values as being target architecture
-  specific. It is unclear how language specific memory spaces are intended to be
-  represented in DWARF using these.
+  This is a new section after DWARF Version 5 section 2.12 Segmented Addresses.
 
-  For example, OpenCL defines memory spaces (called address spaces in OpenCL)
-  for ``global``, ``local``, ``constant``, and ``private``. These are part of
-  the type system and are modifiers to pointer types. In addition, OpenCL
-  defines ``generic`` pointers that can reference either the ``global``,
-  ``local``, or ``private`` memory spaces. To support the OpenCL language the
-  debugger would want to support casting pointers between the ``generic`` and
-  other memory spaces, querying what memory space a ``generic`` pointer value is
-  currently referencing, and possibly using pointer casting to form an address
-  for a specific memory space out of an integral value.
-
-  The method to use to dereference a pointer type or reference type value is
-  defined in DWARF expressions using ``DW_OP_xderef*`` which uses a target
-  architecture specific address space.
-
-  DWARF defines the ``DW_AT_address_class`` attribute on pointer type and
-  reference type debugger information entries. It specifies the method to use to
-  dereference them. Why is the value of this not the same as the address space
-  value used in ``DW_OP_xderef*``? In both cases it is target architecture
-  specific and the architecture presumably will use the same set of methods to
-  dereference pointers in both cases.
-
-  Since ``DW_AT_address_class`` uses a target architecture specific value, it
-  cannot in general capture the source language memory space type modifier
-  concept. On some architectures all source language memory space modifiers may
-  actually use the same method for dereferencing pointers.
-
-  One possibility is for DWARF to add an ``DW_TAG_LLVM_address_class_type``
-  debugger information entry type modifier that can be applied to a pointer type
-  and reference type. The ``DW_AT_address_class`` attribute could be re-defined
-  to not be target architecture specific and instead define generalized language
-  values (as presented above for DWARF address classes in the table
-  :ref:`amdgpu-dwarf-address-class-table`) that will support OpenCL and other
-  languages using memory spaces. The ``DW_AT_address_class`` attribute could be
-  defined to not be applied to pointer types or reference types, but instead
-  only to the new ``DW_TAG_LLVM_address_class_type`` type modifier debugger
-  information entry.
-
-  If a pointer type or reference type is not modified by
-  ``DW_TAG_LLVM_address_class_type`` or if ``DW_TAG_LLVM_address_class_type``
-  has no ``DW_AT_address_class`` attribute, then the pointer type or reference
-  type would be defined to use the ``DW_ADDR_none`` address class as currently.
-  Since modifiers can be chained, it would need to be defined if multiple
-  ``DW_TAG_LLVM_address_class_type`` modifiers were legal, and if so if the
-  outermost one is the one that takes precedence.
-
-  A target architecture implementation that supports multiple address spaces
-  would need to map ``DW_ADDR_none`` appropriately to support CUDA-like
-  languages that have no address classes in the type system but do support
-  variable allocation in address classes. Such variable allocation would result
-  in the variable's location description needing an address space.
+DWARF memory spaces are used for source languages that have the concept of
+memory spaces. They are used in the ``DW_AT_LLVM_memory_space`` attribute for
+pointer type, reference type, variable, formal parameter, and constant debugger
+information entries.
 
-  The approach presented in :ref:`amdgpu-dwarf-address-class-table` is to define
-  the default ``DW_ADDR_none`` to be the generic address class and not the
-  global address class. This matches how CLANG and LLVM have added support for
-  CUDA-like languages on top of existing C++ language support. This allows all
-  addresses to be generic by default which matches CUDA-like languages.
+Each DWARF memory space is conceptually a separate source language memory space
+with its own lifetime and aliasing rules. DWARF memory spaces are used to
+specify the source language memory spaces that pointer type and reference type
+values refer, and to specify the source language memory space in which variables
+are allocated.
 
-  An alternative approach is to define ``DW_ADDR_none`` as being the global
-  address class and then change ``DW_ADDR_LLVM_global`` to
-  ``DW_ADDR_LLVM_generic``. This would match the reality that languages that do
-  not support multiple memory spaces only have one default global memory space.
-  Generally, in these languages if they expose that the target architecture
-  supports multiple address spaces, the default one is still the global memory
-  space. Then a language that does support multiple memory spaces has to
-  explicitly indicate which pointers have the added ability to reference more
-  than the global memory space. However, compilers generating DWARF for
-  CUDA-like languages would then have to define every CUDA-like language pointer
-  type or reference type using ``DW_TAG_LLVM_address_class_type`` with a
-  ``DW_AT_address_class`` attribute of ``DW_ADDR_LLVM_generic`` to match the
-  language semantics.
-
-  A new ``DW_AT_LLVM_address_space`` attribute could be defined that can be
-  applied to pointer type, reference type, subprogram, and subprogram type to
-  describe how objects having the given type are dereferenced or called (the
-  role that ``DW_AT_address_class`` currently provides). The values of
-  ``DW_AT_LLVM_address_space`` would be target architecture specific and the
-  same as used in ``DW_OP_xderef*``.
+Although DWARF memory space identifiers are source language specific,
+``DW_MSPACE_LLVM_none`` is a common memory space supported by all source
+languages, and defined as the source language default memory space.
+
+The set of currently defined DWARF memory spaces, together with source language
+mappings, is given in :ref:`amdgpu-dwarf-source-language-memory-spaces-table`.
+
+Vendor defined source language memory spaces may be defined using codes in the
+range ``DW_MSPACE_LLVM_lo_user`` to ``DW_MSPACE_LLVM_hi_user``.
+
+.. table:: Source language memory spaces
+   :name: amdgpu-dwarf-source-language-memory-spaces-table
+
+   =========================== ============ ============== ============== ==============
+   Memory Space Name           Meaning      C/C++          OpenCL         CUDA/HIP
+   =========================== ============ ============== ============== ==============
+   ``DW_MSPACE_LLVM_none``     generic      *default*      generic        *default*
+   ``DW_MSPACE_LLVM_global``   global                      global
+   ``DW_MSPACE_LLVM_constant`` constant                    constant       constant
+   ``DW_MSPACE_LLVM_group``    thread-group                local          shared
+   ``DW_MSPACE_LLVM_private``  thread                      private
+   ``DW_MSPACE_LLVM_lo_user``
+   ``DW_MSPACE_LLVM_hi_user``
+   =========================== ============ ============== ============== ==============
 
 .. note::
 
-  Some additional changes will be made to support languages such as OpenCL/SyCL
-  that allow address class pointer casting and queries.
-
-  This requires the compiler to provide the mapping from address space to
-  address class which may be runtime and not target architecture dependent. Some
-  implementations may have a one-to-one mapping from source language address
-  class to target architecture address space, and some may have a many-to-one
-  mapping which requires knowledge of the address class when determining if
-  pointer address class casts are allowed.
+  The approach presented in
+  :ref:`amdgpu-dwarf-source-language-memory-spaces-table` is to define the
+  default ``DW_MSPACE_LLVM_none`` to be the generic address class and not the
+  global address class. This matches how CLANG and LLVM have added support for
+  CUDA-like languages on top of existing C++ language support. This allows all
+  addresses to be generic by default which matches CUDA-like languages.
 
-  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.
+  An alternative approach is to define ``DW_MSPACE_LLVM_none`` as being the
+  global memory space and then change ``DW_MSPACE_LLVM_global`` to
+  ``DW_MSPACE_LLVM_generic``. This would match the reality that languages that
+  do not support multiple memory spaces only have one default global memory
+  space. Generally, in these languages if they expose that the target
+  architecture supports multiple memory spaces, the default one is still the
+  global memory space. Then a language that does support multiple memory spaces
+  has to explicitly indicate which pointers have the added ability to reference
+  more than the global memory space. However, compilers generating DWARF for
+  CUDA-like languages would then have to define every CUDA-like language pointer
+  type or reference type with a ``DW_AT_LLVM_memory_space`` attribute of
+  ``DW_MSPACE_LLVM_generic`` to match the language semantics.
 
 A.3 Program Scope Entries
 -------------------------
 
 .. note::
 
   This section provides changes to existing debugger information entry
   attributes. These would be incorporated into the corresponding DWARF Version 5
2.  A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry
     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.*
 
+    *The frame base for a subprogram is typically an address relative to the
+    first unit of storage allocated for the subprogram's stack frame. The*
+    ``DW_AT_frame_base`` *attribute can be used in several ways:*
+
+    1.  *In subprograms that need location lists to locate local variables, the*
+        ``DW_AT_frame_base`` *can hold the needed location list, while all
+        variables' location descriptions can be simpler ones involving the frame
+        base.*
+
+    2.  *It can be used in resolving "up-level" addressing within
+        nested routines. (See also* ``DW_AT_static_link``\ *, below)*
+
+    *Some languages support nested subroutines. In such languages, it is
+    possible to reference the local variables of an outer subroutine from within
+    an inner subroutine. The* ``DW_AT_static_link`` *and* ``DW_AT_frame_base``
+    *attributes allow debuggers to support this same kind of referencing.*
+
 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 not comprised of one memory location
     description for one of the target architecture specific address spaces.
 
+    In the context of supporting nested subroutines, the DW_AT_frame_base
+    attribute value obeys the following constraints:
+
+    1.  It computes a value that does not change during the life of the
+        subprogram, and
+
+    2.  The computed value is unique among instances of the same subroutine.
+
+    *For typical DW_AT_frame_base use, this means that a recursive subroutine's
+    stack frame must have non-zero size.*
+
+    *If a debugger is attempting to resolve an up-level reference to a variable,
+    it uses the nesting structure of DWARF to determine which subroutine is the
+    lexical parent and the* ``DW_AT_static_link`` *value to identify the
+    appropriate active frame of the parent. It can then attempt to find the
+    reference within the context of the parent.*
+
     .. note::
 
       The following new attributes are added.
 
 4.  For languages that are implemented using a 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
7.  A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or
     If not present, the default value of 1 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
+1.  The call site entry may own ``DW_TAG_call_site_parameter`` debugging
+    information entries representing the parameters passed to the call. Call
+    site parameter entries occur in the same order as the corresponding
+    parameters in the source. Each such entry has a ``DW_AT_location`` attribute
+    which is a location description. This location description describes where
+    the parameter is passed (usually either some register, or a memory location
+    expressible as the contents of the stack register plus some offset).
+
+2.  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\
2.  A ``DW_TAG_call_site_parameter`` debugger information entry may have a
     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
+      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.
+      ``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.
2.  A ``DW_TAG_call_site_parameter`` debugger information entry may have a
     *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.*
 
+3.  Each call site parameter entry may also have a ``DW_AT_call_parameter``
+    attribute which contains a reference to a ``DW_TAG_formal_parameter`` entry,
+    ``DW_AT_type attribute`` referencing the type of the parameter or
+    ``DW_AT_name`` attribute describing the parameter's name.
+
+*Examples using call site entries and related attributes are found in Appendix
+D.15.*
+
 .. _amdgpu-dwarf-lexical-block-entries:
 
 A.3.5 Lexical Block Entries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   This section is the same as DWARF Version 5 section 3.5.
1.  Any debugging information entry describing a data object (which includes
 
     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.
 
     See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules
     used by the ``DW_OP_call*`` operations.
 
     .. 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.
 
     .. note::
1.  A ``DW_TAG_base_type`` debugger information entry for a base type T may have
 
     .. 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.
 
+    .. note::
+
+      Compare this with the ``DW_AT_GNU_vector`` extension supported by GNU. Is
+      it better to add an attribute to the existing ``DW_TAG_base_type`` debug
+      entry, or allow some forms of ``DW_TAG_array_type`` (those that have the
+      ``DW_AT_GNU_vector`` attribute) to be used as stack entry value types?
+
+A.5.3 Type Modifier Entries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+  This section, augments DWARF Version 5 section 5.3.
+
+A modified type entry describing a pointer or reference type (using
+``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or
+``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_memory_space``
+attribute with a constant value representing a source language specific DWARF
+memory space (see :ref:`amdgpu-dwarf-memory-spaces`). If omitted, defaults to
+DW_MSPACE_LLVM_none.
+
+A modified type entry describing a pointer or reference type (using
+``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or
+``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_address_space``
+attribute with a constant value AS representing an architecture specific DWARF
+address space (see :ref:`amdgpu-dwarf-address-spaces`). If omitted, defaults to
+``DW_ASPACE_LLVM_none``. DR is the offset of a hypothetical debug information
+entry D in the current compilation unit for an integral base type matching the
+address size of AS. An object P having the given pointer or reference type are
+dereferenced as if the ``DW_OP_push_object_address; DW_OP_deref_type DR;
+DW_OP_constu AS; DW_OP_form_aspace_address`` operation expression was evaluated
+with the current context except: the result kind is location description; the
+initial stack is empty; and the object is the location description of P.
+
+.. note::
+
+  What if the current context does not have a current target architecture
+  defined?
+
+.. note::
+
+  With the expanded support for DWARF address spaces, it may be worth examining
+  if they can be used for what was formerly supported by DWARF 5 segments. That
+  would include specifying the address space of all code addresses (compilation
+  units, subprograms, subprogram entries, labels, subprogram types, etc.).
+  Either the code address attributes could be extended to allow a exprloc form
+  (so that ``DW_OP_form_aspace_address`` can be used) or the
+  ``DW_AT_LLVM_address_space`` attribute be allowed on all DIEs that allow
+  ``DW_AT_segment``.
+
 A.5.7 Structure, Union, Class and Interface Type Entries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A.5.7.3 Derived or Extended Structures, Classes and Interfaces
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 1.  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
+        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
1.  The ``DW_TAG_ptr_to_member_type`` debugging information entry has a
     class to which the pointer to member entry points.
 
 A.5.18 Dynamic Properties of Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A.5.18.1 Data Location
 ++++++++++++++++++++++
 
+*Some languages may represent objects using descriptors to hold information,
+including a location and/or run-time parameters, about the data that represents
+the value for that object.*
+
 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.
 
     The result of the attribute is obtained by evaluating E with a context that
*expression(E)*
   :ref:`amdgpu-dwarf-operation-expressions`).
 
   E is evaluated with the current context, except the result kind is a location
   description, the compilation unit is unspecified, the object is unspecified,
   and an initial stack comprising the location description of the current CFA
   (see :ref:`amdgpu-dwarf-operation-expressions`).
 
 *val_expression(E)*
-  The previous value of this register is the value produced by evaluating the
-  DWARF operation expression E (see :ref:`amdgpu-dwarf-operation-expressions`).
+  The previous value of this register is located at the implicit location
+  description created from the value produced by evaluating the DWARF operation
+  expression E (see :ref:`amdgpu-dwarf-operation-expressions`).
 
   E is evaluated with the current context, except the result kind is a value,
   the compilation unit is unspecified, the object is unspecified, and an initial
   stack comprising the location description of the current CFA (see
   :ref:`amdgpu-dwarf-operation-expressions`).
 
   The DWARF is ill-formed if the resulting value type size does not match the
   register size.
 
   .. note::
 
     This has limited usefulness as the DWARF expression E can only produce
     values up to the size of the generic type. This is due to not allowing any
     operations that specify a type in a CFI operation expression. This makes it
     unusable for registers that are larger than the generic type. However,
     *expression(E)* can be used to create an implicit location description of
     any size.
 
 *architectural*
   The rule is defined externally to this specification by the augmenter.
 
+*This table would be extremely large if actually constructed as described. Most
+of the entries at any point in the table are identical to the ones above them.
+The whole table can be represented quite compactly by recording just the
+differences starting at the beginning address of each subroutine in the
+program.*
+
+The virtual unwind information is encoded in a self-contained section called
+``.debug_frame``. Entries in a ``.debug_frame`` section are aligned on a
+multiple of the address size relative to the start of the section and come in
+two forms: a Common Information Entry (CIE) and a Frame Description Entry (FDE).
+
+*If the range of code addresses for a function is not contiguous, there may be
+multiple CIEs and FDEs corresponding to the parts of that function.*
+
 A Common Information Entry (CIE) holds information that is shared among many
 Frame Description Entries (FDE). There is at least one CIE in every non-empty
 ``.debug_frame`` section. A CIE contains the following fields, in order:
 
 1.  ``length`` (initial length)
 
     A constant that gives the number of bytes of the CIE structure, not
-    including the length field itself. The size of the length field plus the
-    value of length must be an integral multiple of the address size specified
-    in the ``address_size`` field.
+    including the length field itself (see Section 7.2.2 Initial Length Values).
+    The size of the length field plus the value of length must be an integral
+    multiple of the address size specified in the ``address_size`` field.
 
 2.  ``CIE_id`` (4 or 8 bytes, see
     :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`)
 
     A constant that is used to distinguish CIEs from FDEs.
 
     In the 32-bit DWARF format, the value of the CIE id in the CIE header is
     0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.
 
 3.  ``version`` (ubyte)
 
-    A version number. This number is specific to the call frame information and
-    is independent of the DWARF version number.
+    A version number (see Section 7.24 Call Frame Information). This number is
+    specific to the call frame information and is independent of the DWARF
+    version number.
 
     The value of the CIE version number is 4.
 
     .. note::
 
       Would this be increased to 5 to reflect the changes in these extensions?
 
 4.  ``augmentation`` (sequence of UTF-8 characters)
11. ``padding`` (array of ubyte)
     Enough ``DW_CFA_nop`` instructions to make the size of this entry match the
     length value above.
 
 An FDE contains the following fields, in order:
 
 1.  ``length`` (initial length)
 
     A constant that gives the number of bytes of the header and instruction
-    stream for this subprogram, not including the length field itself. The size
-    of the length field plus the value of length must be an integral multiple of
-    the address size.
+    stream for this subprogram, not including the length field itself (see
+    Section 7.2.2 Initial Length Values). The size of the length field plus the
+    value of length must be an integral multiple of the address size.
 
 2.  ``CIE_pointer`` (4 or 8 bytes, see
     :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`)
 
     A constant offset into the ``.debug_frame`` section that denotes the CIE
     that is associated with this FDE.
 
 3.  ``initial_location`` (segment selector and target address)
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:
 
 A.6.4.2 Call Frame Instructions
 +++++++++++++++++++++++++++++++
 
+Each call frame instruction is defined to take 0 or more operands. Some of the
+operands may be encoded as part of the opcode (see
+:ref:`amdgpu-dwarf-call-frame-information-encoding`). The instructions are
+defined in the following sections.
+
 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_regval_type``, ``DW_OP_reinterpret``, and ``DW_OP_xderef_type``

 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;
+    required action is to define the current CFA rule to be equivalent to the
+    result of evaluating the DWARF operation expression ``DW_OP_constu AS;
     DW_OP_LLVM_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_LLVM_aspace_bregx R, B * data_alignment_factor`` as a location
-    description.
+    identifier. The required action is to define the current CFA rule to be
+    equivalent to the result of evaluating the DWARF operation expression
+    ``DW_OP_constu AS; DW_OP_LLVM_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_LLVM_aspace_bregx R, B`` as a location description.
+    AS. The required action is to define the current CFA rule to be equivalent
+    to the result of evaluating the DWARF operation expression ``DW_OP_constu
+    AS; DW_OP_LLVM_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.
+    ``DW_ASPACE_LLVM_*`` values then the DWARF expression is ill-formed.
 
 4.  ``DW_CFA_LLVM_def_aspace_cfa_sf`` *New*
 
     The ``DW_CFA_LLVM_def_aspace_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_LLVM_aspace_bregx R, B *
-    data_alignment_factor`` as a location description.
+    action is to define the current CFA rule to be equivalent to the result of
+    evaluating the DWARF operation expression ``DW_OP_constu AS;
+    DW_OP_LLVM_aspace_bregx R, 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.
+    ``DW_ASPACE_LLVM_*`` 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``
 
     The ``DW_CFA_def_cfa_register`` instruction takes a single unsigned LEB128
     operand representing a register number R. 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_LLVM_aspace_bregx R, B`` as a location
-    description. B and AS are the old CFA byte displacement and address space
-    respectively.
+    the current CFA rule to be equivalent to the result of evaluating the DWARF
+    operation expression ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B`` as a
+    location description. B and AS are the old CFA byte displacement 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.
 
 6.  ``DW_CFA_def_cfa_offset``
 
     The ``DW_CFA_def_cfa_offset`` instruction takes a single unsigned LEB128
     operand representing a (non-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_LLVM_aspace_bregx R, B``
-    as a location description. R and AS are the old CFA register number and
-    address space respectively.
+    action is to define the current CFA rule to be equivalent to the result of
+    evaluating the DWARF operation expression ``DW_OP_constu AS;
+    DW_OP_LLVM_aspace_bregx R, B`` 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.
 
 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_LLVM_aspace_bregx R, B *
+    define the current CFA rule to be equivalent to the result of evaluating the
+    DWARF operation expression ``DW_OP_constu AS; DW_OP_LLVM_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.
+    The required action is to define the current CFA rule to be equivalent to
+    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:

 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
-   DW_AT_LLVM_iterations              0x3e0a constant, exprloc, loclist
+   ``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
+   ``DW_AT_LLVM_iterations``          0x3e0a constant, exprloc, loclist
+   ``DW_AT_LLVM_address_space``       TBA    constant
+   ``DW_AT_LLVM_memory_space``        TBA    constant
    ================================== ====== ===================================
 
 .. _amdgpu-dwarf-classes-and-forms:
 
 A.7.5.5 Classes and Forms
 +++++++++++++++++++++++++
 
 .. note::
 
-  The same as in DWARF Version 5 section 7.5.5.
+  The following modifies the matching text in DWARF Version 5 section 7.5.5.
+
+* reference
+    There are four types of reference.
+
+      - The first type of reference...
+
+      - The second type of reference can identify any debugging information
+        entry within a .debug_info section; in particular, it may refer to an
+        entry in a different compilation unit from the unit containing the
+        reference, and may refer to an entry in a different shared object file.
+        This type of reference (DW_FORM_ref_addr) is an offset from the
+        beginning of the .debug_info section of the target executable or shared
+        object file, or, for references within a supplementary object file, an
+        offset from the beginning of the local .debug_info section; it is
+        relocatable in a relocatable object file and frequently relocated in an
+        executable or shared object file. In the 32-bit DWARF format, this
+        offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an
+        8-byte unsigned value (see
+        :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`).
+
+        *A debugging information entry that may be referenced by another
+        compilation unit using DW_FORM_ref_addr must have a global symbolic
+        name.*
+
+        *For a reference from one executable or shared object file to another,
+        the reference is resolved by the debugger to identify the executable or
+        shared object file and the offset into that file's* ``.debug_info``
+        *section in the same fashion as the run time loader, either when the
+        debug information is first read, or when the reference is used.*
 
 A.7.7 DWARF Expressions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   Rename DWARF Version 5 section 7.7 to reflect the unification of location
   descriptions into DWARF 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.
 
-The following table gives the encoding of the additional DWARF expression
-operations.
+A DWARF operation expression is stored in a block of contiguous bytes. The bytes
+form a sequence of operations. Each operation is a 1-byte code that identifies
+that operation, followed by zero or more bytes of additional data. The encodings
+for the operations are described in
+:ref:`amdgpu-dwarf-operation-encodings-table`.
 
 .. table:: DWARF Operation Encodings
    :name: amdgpu-dwarf-operation-encodings-table
 
-   ================================== ===== ======== ===============================
-   Operation                          Code  Number   Notes
+   ====================================== ===== ======== ===============================
+   Operation                              Code  Number   Notes
                                                 of
                                                 Operands
-   ================================== ===== ======== ===============================
-   DW_OP_LLVM_form_aspace_address     0xe1     0
-   DW_OP_LLVM_push_lane               0xe2     0
-   DW_OP_LLVM_offset                  0xe3     0
-   DW_OP_LLVM_offset_uconst           0xe4     1     ULEB128 byte displacement
-   DW_OP_LLVM_bit_offset              0xe5     0
-   DW_OP_LLVM_call_frame_entry_reg    0xe6     1     ULEB128 register number
-   DW_OP_LLVM_undefined               0xe7     0
-   DW_OP_LLVM_aspace_bregx            0xe8     2     ULEB128 register number,
+   ====================================== ===== ======== ===============================
+   ``DW_OP_LLVM_form_aspace_address``     0xe1     0
+   ``DW_OP_LLVM_push_lane``               0xe2     0
+   ``DW_OP_LLVM_offset``                  0xe3     0
+   ``DW_OP_LLVM_offset_uconst``           0xe4     1     ULEB128 byte displacement
+   ``DW_OP_LLVM_bit_offset``              0xe5     0
+   ``DW_OP_LLVM_call_frame_entry_reg``    0xe6     1     ULEB128 register number
+   ``DW_OP_LLVM_undefined``               0xe7     0
+   ``DW_OP_LLVM_aspace_bregx``            0xe8     2     ULEB128 register number,
                                                          ULEB128 byte displacement
-   DW_OP_LLVM_aspace_implicit_pointer 0xe9     2     4-byte or 8-byte offset of DIE,
+   ``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,
+   ``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,
+   ``DW_OP_LLVM_select_bit_piece``        0xec     2     ULEB128 bit size,
                                                          ULEB128 count
-   DW_OP_LLVM_push_iteration          TBA      0
-   DW_OP_LLVM_overlay                 TBA      0
-   DW_OP_LLVM_bit_overlay             TBA      0
-   ================================== ===== ======== ===============================
+   ``DW_OP_LLVM_push_iteration``          TBA      0
+   ``DW_OP_LLVM_overlay``                 TBA      0
+   ``DW_OP_LLVM_bit_overlay``             TBA      0
+   ====================================== ===== ======== ===============================
 
 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.
.. table:: Language encodings
    :name: amdgpu-dwarf-language-encodings-table
 
    ==================== ====== ===================
    Language Name        Value  Default Lower Bound
    ==================== ====== ===================
    ``DW_LANG_LLVM_HIP`` 0x8100 0
    ==================== ====== ===================
 
-A.7.13 Address Class and Address Space Encodings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A.7.14 Address Space Encodings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
-  This replaces DWARF Version 5 section 7.13.
+  This is a new section after DWARF Version 5 section 7.13 "Address Class and
+  Address Space Encodings".
 
-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
-   ========================== ======
+The value of the common address space encoding ``DW_ASPACE_LLVM_none`` is 0.
+
+A.7.15 Memory Space Encodings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+  This is a new section after DWARF Version 5 section 7.13 "Address Class and
+  Address Space Encodings".
+
+The encodings of the constants used for the currently defined memory spaces
+are given in :ref:`amdgpu-dwarf-memory-space-encodings-table`.
+
+.. table:: Memory space encodings
+   :name: amdgpu-dwarf-memory-space-encodings-table
+
+   =========================== ======
+   Memory Space Name           Value
+   =========================== ======
+   ``DW_MSPACE_LLVM_none``     0x0000
+   ``DW_MSPACE_LLVM_global``   0x0001
+   ``DW_MSPACE_LLVM_constant`` 0x0002
+   ``DW_MSPACE_LLVM_group``    0x0003
+   ``DW_MSPACE_LLVM_private``  0x0004
+   ``DW_MSPACE_LLVM_lo_user``  0x8000
+   ``DW_MSPACE_LLVM_hi_user``  0xffff
+   =========================== ======
 
 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
   ====================================  ====================
 
+.. _amdgpu-dwarf-call-frame-information-encoding:
+
 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
+   ================================= ====== ====== ================ ================ =====================
+   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
-   ============================= ====== ====== ================ ================ =====================
+   ================================= ====== ====== ================ ================ =====================
+   ``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
+   ================================= ====== ====== ================ ================ =====================
+
+A.7.32 Type Signature Computation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+  This augments (in alphebetical order) DWARF Version 5 section 7.32, Table
+  7.32.
+
+.. table:: Attributes used in type signature computation
+   :name: amdgpu-dwarf-attributes-used-in-type-signature-computation-table
+
+   ================================== =======
+   ``DW_AT_LLVM_address_space``
+   ``DW_AT_LLVM_memory_space``
+   ``DW_AT_LLVM_vector_size``
+   ================================== =======
 
 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.
 
 .. table:: Attributes by tag value
    :name: amdgpu-dwarf-attributes-by-tag-value-table
 
-   ============================= =============================
-   Tag Name                      Applicable Attributes
-   ============================= =============================
-   ``DW_TAG_base_type``          * ``DW_AT_LLVM_vector_size``
-   ``DW_TAG_compile_unit``       * ``DW_AT_LLVM_augmentation``
-   ``DW_TAG_entry_point``        * ``DW_AT_LLVM_active_lane``
+   ================================== =============================
+   Tag Name                           Applicable Attributes
+   ================================== =============================
+   ``DW_TAG_base_type``               * ``DW_AT_LLVM_vector_size``
+   ``DW_TAG_pointer_type``            * ``DW_AT_LLVM_address_space``
+                                      * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_reference_type``          * ``DW_AT_LLVM_address_space``
+                                      * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_rvalue_reference_type``   * ``DW_AT_LLVM_address_space``
+                                      * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_variable``                * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_formal_parameter``        * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_constant``                * ``DW_AT_LLVM_memory_space``
+   ``DW_TAG_compile_unit``            * ``DW_AT_LLVM_augmentation``
+   ``DW_TAG_entry_point``             * ``DW_AT_LLVM_active_lane``
                                       * ``DW_AT_LLVM_lane_pc``
                                       * ``DW_AT_LLVM_lanes``
                                       * ``DW_AT_LLVM_iterations``
-   ``DW_TAG_inlined_subroutine`` * ``DW_AT_LLVM_active_lane``
+   ``DW_TAG_inlined_subroutine``      * ``DW_AT_LLVM_active_lane``
                                       * ``DW_AT_LLVM_lane_pc``
                                       * ``DW_AT_LLVM_lanes``
                                       * ``DW_AT_LLVM_iterations``
-   ``DW_TAG_subprogram``         * ``DW_AT_LLVM_active_lane``
+   ``DW_TAG_subprogram``              * ``DW_AT_LLVM_active_lane``
                                       * ``DW_AT_LLVM_lane_pc``
                                       * ``DW_AT_LLVM_lanes``
                                       * ``DW_AT_LLVM_iterations``
-   ============================= =============================
+   ================================== =============================
+
+D. Examples (Informative)
+-------------------------
+
+.. note::
+
+  This modifies the corresponding DWARF Version 5 Appendix D examples.
+
+D.1 General Description Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+D.1.3 DWARF Location Description Examples
++++++++++++++++++++++++++++++++++++++++++
+
+``DW_OP_offset_uconst 4``
+  A structure member is four bytes from the start of the structure instance. The
+  location description of the base of the structure instance is assumed to be
+  already on the stack.
+
+``DW_OP_entry_value 1 DW_OP_reg5 DW_OP_offset_uconst 16``
+  The address of the memory location is calculated by adding 16 to the value
+  contained in register 5 upon entering the current subprogram.
+
+D.2 Aggregate Examples
+~~~~~~~~~~~~~~~~~~~~~~
+
+D.2.1 Fortran Simple Array Example
+++++++++++++++++++++++++++++++++++
+
+Figure D.4: Fortran array example: DWARF description
+
+.. code::
+  :number-lines:
+
+  -------------------------------------------------------------------------------
+  ! Description for type of 'ap'
+  !
+  1$: DW_TAG_array_type
+          ! No name, default (Fortran) ordering, default stride
+          DW_AT_type(reference to REAL)
+          DW_AT_associated(expression=    ! Test 'ptr_assoc' flag
+              DW_OP_push_object_address
+              DW_OP_lit<n>                ! where n == offset(ptr_assoc)
+              DW_OP_offset
+              DW_OP_deref
+              DW_OP_lit1                  ! mask for 'ptr_assoc' flag
+              DW_OP_and)
+          DW_AT_data_location(expression= ! Get raw data address
+              DW_OP_push_object_address
+              DW_OP_lit<n>                ! where n == offset(base)
+              DW_OP_offset
+              DW_OP_deref)                ! Type of index of array 'ap'
+  2$:     DW_TAG_subrange_type
+              ! No name, default stride
+              DW_AT_type(reference to INTEGER)
+              DW_AT_lower_bound(expression=
+                  DW_OP_push_object_address
+                  DW_OP_lit<n>            ! where n ==
+                                          !   offset(desc, dims) +
+                                          !   offset(dims_str, lower_bound)
+                  DW_OP_offset
+                  DW_OP_deref)
+              DW_AT_upper_bound(expression=
+                  DW_OP_push_object_address
+                  DW_OP_lit<n>            ! where n ==
+                                          !   offset(desc, dims) +
+                                          !   offset(dims_str, upper_bound)
+                  DW_OP_offset
+                  DW_OP_deref)
+  !  Note: for the m'th dimension, the second operator becomes
+  !  DW_OP_lit<n> where
+  !       n == offset(desc, dims)          +
+  !                (m-1)*sizeof(dims_str)  +
+  !                 offset(dims_str, [lower|upper]_bound)
+  !  That is, the expression does not get longer for each successive
+  !  dimension (other than to express the larger offsets involved).
+  3$: DW_TAG_structure_type
+          DW_AT_name("array_ptr")
+          DW_AT_byte_size(constant sizeof(REAL) + sizeof(desc<1>))
+  4$:     DW_TAG_member
+              DW_AT_name("myvar")
+              DW_AT_type(reference to REAL)
+              DW_AT_data_member_location(constant 0)
+  5$:     DW_TAG_member
+              DW_AT_name("ap");
+              DW_AT_type(reference to 1$)
+              DW_AT_data_member_location(constant sizeof(REAL))
+  6$: DW_TAG_array_type
+          ! No name, default (Fortran) ordering, default stride
+          DW_AT_type(reference to 3$)
+          DW_AT_allocated(expression=       ! Test 'ptr_alloc' flag
+              DW_OP_push_object_address
+              DW_OP_lit<n>                  ! where n == offset(ptr_alloc)
+              DW_OP_offset
+              DW_OP_deref
+              DW_OP_lit2                    ! Mask for 'ptr_alloc' flag
+              DW_OP_and)
+          DW_AT_data_location(expression=   ! Get raw data address
+              DW_OP_push_object_address
+              DW_OP_lit<n>                  ! where n == offset(base)
+              DW_OP_offset
+              DW_OP_deref)
+  7$:     DW_TAG_subrange_type
+              ! No name, default stride
+              DW_AT_type(reference to INTEGER)
+              DW_AT_lower_bound(expression=
+                  DW_OP_push_object_address
+                  DW_OP_lit<n>              ! where n == ...
+                  DW_OP_offset
+                  DW_OP_deref)
+              DW_AT_upper_bound(expression=
+                  DW_OP_push_object_address
+                  DW_OP_lit<n>              ! where n == ...
+                  DW_OP_offset
+                  DW_OP_deref)
+  8$: DW_TAG_variable
+          DW_AT_name("arrayvar")
+          DW_AT_type(reference to 6$)
+          DW_AT_location(expression=
+              ...as appropriate...)         ! Assume static allocation
+  -------------------------------------------------------------------------------
+
+D.2.3 Fortran 2008 Assumed-rank Array Example
++++++++++++++++++++++++++++++++++++++++++++++
+
+Figure D.13: Sample DWARF for the array descriptor in Figure D.12
+
+.. code::
+  :number-lines:
+
+  ----------------------------------------------------------------------------
+  10$:  DW_TAG_array_type
+          DW_AT_type(reference to real)
+          DW_AT_rank(expression=
+              DW_OP_push_object_address
+              DW_OP_lit<n>
+              DW_OP_offset
+              DW_OP_deref)
+          DW_AT_data_location(expression=
+              DW_OP_push_object_address
+              DW_OP_lit<n>
+              DW_OP_offset
+              DW_OP_deref)
+  11$:     DW_TAG_generic_subrange
+              DW_AT_type(reference to integer)
+              !   offset of rank in descriptor
+              !   offset of data in descriptor
+              DW_AT_lower_bound(expression=
+              !   Looks up the lower bound of dimension i.
+              !   Operation                       ! Stack effect
+              !   (implicit)                      ! i
+                  DW_OP_lit<n>                    ! i sizeof(dim)
+                  DW_OP_mul                       ! dim[i]
+                  DW_OP_lit<n>                    ! dim[i] offsetof(dim)
+                  DW_OP_plus                      ! dim[i]+offset
+                  DW_OP_push_object_address       ! dim[i]+offsetof(dim) objptr
+                  DW_OP_swap                      ! objptr dim[i]+offsetof(dim)
+                  DW_OP_offset                    ! objptr.dim[i]
+                  DW_OP_lit<n>                    ! objptr.dim[i] offsetof(lb)
+                  DW_OP_offset                    ! objptr.dim[i].lowerbound
+                  DW_OP_deref)                    ! *objptr.dim[i].lowerbound
+              DW_AT_upper_bound(expression=
+              !   Looks up the upper bound of dimension i.
+                  DW_OP_lit<n>                    ! sizeof(dim)
+                  DW_OP_mul
+                  DW_OP_lit<n>                    ! offsetof(dim)
+                  DW_OP_plus
+                  DW_OP_push_object_address
+                  DW_OP_swap
+                  DW_OP_offset
+                  DW_OP_lit<n>                    ! offset of upperbound in dim
+                  DW_OP_offset
+                  DW_OP_deref)
+              DW_AT_byte_stride(expression=
+              !   Looks up the byte stride of dimension i.
+                  ...
+              !   (analogous to DW_AT_upper_bound)
+                  )
+  ----------------------------------------------------------------------------
+
+.. note::
+
+  This example suggests that ``DW_AT_lower_bound`` and ``DW_AT_upper_bound``
+  evaluate an exprloc with an initial stack containing the rank value. The
+  attribute definition should be updated to state this.
+
+D.2.6 Ada Example
++++++++++++++++++
+
+Figure D.20: Ada example: DWARF description
+
+.. code::
+  :number-lines:
+
+  ----------------------------------------------------------------------------
+  11$:  DW_TAG_variable
+            DW_AT_name("M")
+            DW_AT_type(reference to INTEGER)
+  12$:  DW_TAG_array_type
+            ! No name, default (Ada) order, default stride
+            DW_AT_type(reference to INTEGER)
+  13$:      DW_TAG_subrange_type
+                DW_AT_type(reference to INTEGER)
+                DW_AT_lower_bound(constant 1)
+                DW_AT_upper_bound(reference to variable M at 11$)
+  14$:  DW_TAG_variable
+            DW_AT_name("VEC1")
+            DW_AT_type(reference to array type at 12$)
+        ...
+  21$:  DW_TAG_subrange_type
+            DW_AT_name("TEENY")
+            DW_AT_type(reference to INTEGER)
+            DW_AT_lower_bound(constant 1)
+            DW_AT_upper_bound(constant 100)
+        ...
+  26$:  DW_TAG_structure_type
+            DW_AT_name("REC2")
+  27$:      DW_TAG_member
+                DW_AT_name("N")
+                DW_AT_type(reference to subtype TEENY at 21$)
+                DW_AT_data_member_location(constant 0)
+  28$:      DW_TAG_array_type
+                ! No name, default (Ada) order, default stride
+                ! Default data location
+                DW_AT_type(reference to INTEGER)
+  29$:          DW_TAG_subrange_type
+                    DW_AT_type(reference to subrange TEENY at 21$)
+                    DW_AT_lower_bound(constant 1)
+                    DW_AT_upper_bound(reference to member N at 27$)
+  30$:      DW_TAG_member
+                DW_AT_name("VEC2")
+                DW_AT_type(reference to array "subtype" at 28$)
+                DW_AT_data_member_location(machine=
+                    DW_OP_lit<n>                ! where n == offset(REC2, VEC2)
+                    DW_OP_offset)
+        ...
+  41$:  DW_TAG_variable
+            DW_AT_name("OBJ2B")
+            DW_AT_type(reference to REC2 at 26$)
+            DW_AT_location(...as appropriate...)
+  ----------------------------------------------------------------------------
 
-.. _amdgpu-dwarf-examples:
+.. _amdgpu-dwarf-further-examples:
 
-B. Examples
-===========
+C. Further 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:
 
-C. References
+D. References
 =============
 
     .. _amdgpu-dwarf-AMD:
 
 1.  [AMD] `Advanced Micro Devices <https://www.amd.com/>`__
 
     .. _amdgpu-dwarf-AMD-ROCgdb:
 

llvm/docs/AMDGPUUsage.rst

 to the wavefront mode of the generated code will be used.
 
 If code is generated to execute in a 32-bit process address space, then the
 32-bit process address space register definitions are used. If code is generated
 to execute in a 64-bit process address space, then the 64-bit process address
 space register definitions are used. The ``amdgcn`` target only supports the
 64-bit process address space.
 
-.. _amdgpu-dwarf-address-class-identifier:
+.. _amdgpu-dwarf-memory-space-identifier:
 
-Address Class Identifier
-------------------------
+Memory Space Identifier
+-----------------------
 
-The DWARF address class represents the source language memory space. See DWARF
+The DWARF memory space represents the source language memory space. See DWARF
 Version 5 section 2.12 which is updated by the *DWARF Extensions For
-Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses`.
+Heterogeneous Debugging* section :ref:`amdgpu-dwarf-memory-spaces`.
 
-The DWARF address class mapping used for AMDGPU is defined in
-:ref:`amdgpu-dwarf-address-class-mapping-table`.
+The DWARF memory space mapping used for AMDGPU is defined in
+:ref:`amdgpu-dwarf-memory-space-mapping-table`.
 
-.. table:: AMDGPU DWARF Address Class Mapping
-   :name: amdgpu-dwarf-address-class-mapping-table
+.. table:: AMDGPU DWARF Memory Space Mapping
+   :name: amdgpu-dwarf-memory-space-mapping-table
 
-   ========================= ====== =================
-   DWARF                            AMDGPU
-   -------------------------------- -----------------
-   Address Class Name        Value  Address Space
-   ========================= ====== =================
-   ``DW_ADDR_none``          0x0000 Generic (Flat)
-   ``DW_ADDR_LLVM_global``   0x0001 Global
-   ``DW_ADDR_LLVM_constant`` 0x0002 Global
-   ``DW_ADDR_LLVM_group``    0x0003 Local (group/LDS)
-   ``DW_ADDR_LLVM_private``  0x0004 Private (Scratch)
-   ``DW_ADDR_AMDGPU_region`` 0x8000 Region (GDS)
-   ========================= ====== =================
+   =========================== ====== =================
+   DWARF                              AMDGPU
+   ---------------------------------- -----------------
+   Memory Space Name           Value  Memory Space
+   =========================== ====== =================
+   ``DW_MSPACE_LLVM_none``     0x0000 Generic (Flat)
+   ``DW_MSPACE_LLVM_global``   0x0001 Global
+   ``DW_MSPACE_LLVM_constant`` 0x0002 Global
+   ``DW_MSPACE_LLVM_group``    0x0003 Local (group/LDS)
+   ``DW_MSPACE_LLVM_private``  0x0004 Private (Scratch)
+   ``DW_MSPACE_AMDGPU_region`` 0x8000 Region (GDS)
+   =========================== ====== =================
 
-The DWARF address class values defined in the *DWARF Extensions For
-Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses` are used.
+The DWARF memory space values defined in the *DWARF Extensions For Heterogeneous
+Debugging* section :ref:`amdgpu-dwarf-memory-spaces` are used.
 
 In addition, ``DW_ADDR_AMDGPU_region`` is encoded as a vendor extension. This is
 available for use for the AMD extension for access to the hardware GDS memory
 which is scratchpad memory allocated per device.
 
-For AMDGPU if no ``DW_AT_address_class`` attribute is present, then the default
-address class of ``DW_ADDR_none`` is used.
+For AMDGPU if no ``DW_AT_LLVM_memory_space`` attribute is present, then the
+default memory space of ``DW_MSPACE_LLVM_none`` is used.
 
 See :ref:`amdgpu-dwarf-address-space-identifier` for information on the AMDGPU
-mapping of DWARF address classes to DWARF address spaces, including address size
+mapping of DWARF memory spaces to DWARF address spaces, including address size
 and NULL value.
 
 .. _amdgpu-dwarf-address-space-identifier:
 
 Address Space Identifier
 ------------------------
 
 DWARF address spaces correspond to target architecture specific linear
 addressable memory areas. See DWARF Version 5 section 2.12 and *DWARF Extensions
-For Heterogeneous Debugging* section :ref:`amdgpu-dwarf-segment_addresses`.
+For Heterogeneous Debugging* section :ref:`amdgpu-dwarf-address-spaces`.
 
 The DWARF address space mapping used for AMDGPU is defined in
 :ref:`amdgpu-dwarf-address-space-mapping-table`.
 
 .. table:: AMDGPU DWARF Address Space Mapping
    :name: amdgpu-dwarf-address-space-mapping-table
 
-   ======================================= ===== ======= ======== ================= =======================
-   DWARF                                                          AMDGPU            Notes
-   --------------------------------------- ----- ---------------- ----------------- -----------------------
-   Address Space Name                      Value Address Bit Size Address Space
-   --------------------------------------- ----- ------- -------- ----------------- -----------------------
+   ======================================= ===== ======= ======== ===================== =======================
+   DWARF                                                          AMDGPU                Notes
+   --------------------------------------- ----- ---------------- --------------------- -----------------------
+   Address Space Name                      Value Address Bit Size LLVM IR Address Space
+   --------------------------------------- ----- ------- -------- --------------------- -----------------------
    ..                                            64-bit  32-bit
                                                  process process
                                                  address address
                                                  space   space
-   ======================================= ===== ======= ======== ================= =======================
-   ``DW_ASPACE_none``                      0x00  64      32       Global            *default address space*
+   ======================================= ===== ======= ======== ===================== =======================
+   ``DW_ASPACE_LLVM_none``                 0x00  64      32       Global                *default address space*
    ``DW_ASPACE_AMDGPU_generic``            0x01  64      32       Generic (Flat)
    ``DW_ASPACE_AMDGPU_region``             0x02  32      32       Region (GDS)
    ``DW_ASPACE_AMDGPU_local``              0x03  32      32       Local (group/LDS)
    *Reserved*                              0x04
-   ``DW_ASPACE_AMDGPU_private_lane``       0x05  32      32       Private (Scratch) *focused lane*
-   ``DW_ASPACE_AMDGPU_private_wave``       0x06  32      32       Private (Scratch) *unswizzled wavefront*
-   ======================================= ===== ======= ======== ================= =======================
+   ``DW_ASPACE_AMDGPU_private_lane``       0x05  32      32       Private (Scratch)     *focused lane*
+   ``DW_ASPACE_AMDGPU_private_wave``       0x06  32      32       Private (Scratch)     *unswizzled wavefront*
+   ======================================= ===== ======= ======== ===================== =======================
 
-See :ref:`amdgpu-address-spaces` for information on the AMDGPU address spaces
-including address size and NULL value.
+See :ref:`amdgpu-address-spaces` for information on the AMDGPU LLVM IR address
+spaces including address size and NULL value.
 
-The ``DW_ASPACE_none`` address space is the default target architecture address
-space used in DWARF operations that do not specify an address space. It
+The ``DW_ASPACE_LLVM_none`` address space is the default target architecture
+address space used in DWARF operations that do not specify an address space. It
 therefore has to map to the global address space so that the ``DW_OP_addr*`` and
 related operations can refer to addresses in the program code.
 
 The ``DW_ASPACE_AMDGPU_generic`` address space allows location expressions to
 specify the flat address space. If the address corresponds to an address in the
 local address space, then it corresponds to the wavefront that is executing the
 focused thread of execution. If the address corresponds to an address in the
 private address space, then it corresponds to the lane that is executing the