[llvm] 22825dd - [AMDGPU][Docs] DWARF aspace-aware base types

[Scott Linder via llvm-commits]

Author: Scott Linder
Date: 2024-08-19T19:55:15Z
New Revision: 22825ddd88aa29994a8a260a31c959aed0b35b5b

URL: https://github.com/llvm/llvm-project/commit/22825ddd88aa29994a8a260a31c959aed0b35b5b
DIFF: https://github.com/llvm/llvm-project/commit/22825ddd88aa29994a8a260a31c959aed0b35b5b.diff

LOG: [AMDGPU][Docs] DWARF aspace-aware base types

Propose an extension to base type DIEs such that DW_ATE_address-encoded
base types can include an architecture specific address space. Use this
to implement DW_OP_convert conversions between AMDGPU address space
addresses where meaningful.

Added: 
    

Modified: 
    llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
    llvm/docs/AMDGPUUsage.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
index 7d4e06ebf0493c..b71e80f922250b 100644
--- a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
+++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
@@ -3804,6 +3804,12 @@ A.5.1 Base Type Entries
       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?
 
+2. A ``DW_TAG_base_type`` debugger information entry with the encoding
+   ``DW_ATE_address`` may have a ``DW_AT_LLVM_address_space`` attribute whose
+   value is an architecture specific address space (see
+   :ref:`amdgpu-dwarf-address-spaces`). If ommitted it defaults to
+   ``DW_ASPACE_LLVM_none``.
+
 .. _amdgpu-dwarf-type-modifier-entries:
 
 A.5.3 Type Modifier Entries

diff  --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index 97fca32d4ece66..80140734cbefd6 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -2918,6 +2918,34 @@ controlled by the execution mask. An undefined location description together
 with ``DW_OP_LLVM_extend`` is used to indicate the lane was not active on entry
 to the subprogram. See :ref:`amdgpu-dwarf-dw-at-llvm-lane-pc` for an example.
 
+.. _amdgpu-dwarf-base-type-conversions:
+
+Base Type Conversions
+---------------------
+
+For AMDGPU expressions, ``DW_OP_convert`` may be used to convert between
+``DW_ATE_address``-encoded base types in 
diff erent address spaces.
+
+Conversions are defined as in :ref:`amdgpu-address-spaces` when all relevant
+conditions described there are met, and otherwise result in an evaluation
+error.
+
+.. note::
+
+  For a target which does not support a particular address space, converting to
+  or from that address space is always an evaluation error.
+
+  For targets which support the generic address space, converting from
+  ``DW_ASPACE_AMDGPU_generic`` to ``DW_ASPACE_LLVM_none`` is always defined and
+  requires no change to the literal value of the address.
+
+  Converting from ``DW_ASPACE_AMDGPU_generic`` to any of
+  ``DW_ASPACE_AMDGPU_local``, ``DW_ASPACE_AMDGPU_private_wave`` or
+  ``DW_ASPACE_AMDGPU_private_lane`` is defined when the relevant hardware
+  support is present and setup has been completed. Conversion to
+  ``DW_ASPACE_AMDGPU_private_lane`` additionally requires the context to
+  include the active lane.
+
 Debugger Information Entry Attributes
 -------------------------------------