[AMDGPU][NFC] Clarify heterogeneous DWARF address/memory spaces

[scott.linder]

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

334

Is the use of "class" intentional here? I thought we were not touching "address class" at all.

702

Same question here, is this intentional?

[t-tye]

Fixed review comments concerning use of class instead of space.

[scott.linder]

LGTM, thank you!

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

 DWARF has the concept of segment addresses. However, the segment cannot be
 specified within a DWARF expression, which is only able to specify the offset
 portion of a segment address. The segment index is only provided by the entity
 that specifies the DWARF expression. Therefore, the segment index is a property
 that can only be put on complete objects, such as a variable. That makes it only
 suitable for describing an entity (such as variable or subprogram code) that is
 in a single kind of memory.
 
-Therefore, AMDGPU uses the DWARF concept of address spaces. For example, a
-variable may be allocated in a register that is partially spilled to the call
-stack which is in the private address space, and partially spilled to the local
-address space.
+AMDGPU uses multiple address spaces. For example, a variable may be allocated in
+a register that is partially spilled to the call stack which is in the private
+address space, and partially spilled to the local address space. DWARF mentions
+address spaces, for example as an argument to the ``DW_OP_xderef*`` operations.
+A new section that defines address classes is added (see
+:ref:`amdgpu-dwarf-address-spaces`).
+
+A new attribute ``DW_AT_LLVM_address_space`` is added to pointer and reference
+types (see :ref:`amdgpu-dwarf-type-modifier-entries`). This allows the compiler
+to specify which address space is being used to represent the pointer or
+reference type.
 
 DWARF uses the concept of an address in many expression operations but does not
 define how it relates to address spaces. For example,
 ``DW_OP_push_object_address`` pushes the address of an object. Other contexts
 implicitly push an address on the stack before evaluating an expression. For
 example, the ``DW_AT_use_location`` attribute of the
 ``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type
 which may apply to objects allocated in different kinds of storage. Therefore,
.. code::
 
   // 4. The size of the register element:
   DW_OP_lit4
 
   // 5. Make a composite location description for dst that is the memory #1 with
   //    the register #2 positioned as an overlay at offset #3 of size #4:
   DW_OP_LLVM_overlay
 
+2.21 Support for Source Language Memory Spaces
+----------------------------------------------
+
+AMDGPU supports languages, such as OpenCL, 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. See :ref:`amdgpu-dwarf-memory-spaces`.
+
+A new attribute ``DW_AT_LLVM_memory_space`` is added to support using memory
+spaces in defining source language pointer and reference types (see
+:ref:`amdgpu-dwarf-type-modifier-entries`) and data object allocation (see
+:ref:`amdgpu-dwarf-data-object-entries`).
+
 .. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
 
 A. Changes Relative to DWARF Version 5
 ======================================
 
 .. note::
 
   This appendix provides changes relative to DWARF Version 5. It has been

 ---------------------------------------
 
 .. note::
 
   This section provides changes to existing debugger information entry
   attributes. These would be incorporated into the corresponding DWARF Version 5
   chapter 4 sections.
 
+.. _amdgpu-dwarf-data-object-entries:
+
 A.4.1 Data Object Entries
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Program variables, formal parameters and constants are represented by debugging
 information entries with the tags ``DW_TAG_variable``,
 ``DW_TAG_formal_parameter`` and ``DW_TAG_constant``, respectively.
 
 *The tag DW_TAG_constant is used for languages that have true named constants.*
.. note::
       ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information
       entries that have been optimized to a constant. Instead,
       ``DW_AT_location`` could be used with a DWARF expression that produces an
       implicit location description now that any location description can be
       used within a DWARF expression. This allows the ``DW_OP_call*`` operations
       to be used to push the location description of any variable regardless of
       how it is optimized.
 
+3.  ``DW_AT_LLVM_memory_space``
+
+    A ``DW_AT_memory_space`` attribute with a constant value representing a source
+    language specific DWARF memory space (see 2.14 "Memory Spaces"). If omitted,
+    defaults to ``DW_MSPACE_none``.
+
+
 A.4.2 Common Block Entries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A common block entry also has a ``DW_AT_location`` attribute whose value is a
 DWARF expression E that describes the location of the common block at run-time.
 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
1.  A ``DW_TAG_base_type`` debugger information entry for a base type T may have
 
     .. 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?
 
+.. _amdgpu-dwarf-type-modifier-entries:
+
 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