Update encodings in AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

[scott.linder]

Summary

Repurpose the DW_OP_LLVM_aspace_implicit_pointer encoding (0xe9) as the
encoding for a new operation DW_OP_LLVM_user which prefixes all other
new operations.

[dblaikie]

Sounds good

[dblaikie]

Oh, naming though - DW_OP_LLVM_extension, perhaps? But I don't mind too much - the name isn't load bearing anyway, we can always rename it if we find a more descriptive name idf we're preserving the semantics

[scott.linder]

In D147265#4241322, @dblaikie wrote:

Oh, naming though - DW_OP_LLVM_extension, perhaps? But I don't mind too much - the name isn't load bearing anyway, we can always rename it if we find a more descriptive name idf we're preserving the semantics

Yeah, I'm amenable to any name, the user naming was just to be similar to DW_OP_{lo,hi}_user as that is the feature from DWARF we are extending

llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst

 spaces. 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`).
 
+2.22 Expression Operation Vendor Extensibility Opcode
+-----------------------------------------------------
+
+The vendor extension encoding space for DWARF expression operations
+accommodates only 32 unique operations. In practice, the lack of a central
+registry and a desire for backwards compatibility means vendor extensions are
+never retired, even when standard versions are accepted into DWARF proper. This
+has produced a situation where the effective encoding space available for new
+vendor extensions is miniscule today.
+
+To expand this encoding space a new DWARF operation ``DW_OP_LLVM_user`` is
+added which acts as a "prefix" for vendor extensions. It is followed by a
+ULEB128 encoded vendor extension opcode, which is then followed by the operands
+of the corresponding vendor extension operation.
+
+This approach allows all remaining operations defined in these extensions to be
+encoded without conflicting with existing vendor extensions.
+
+See ``DW_OP_LLVM_user`` in :ref:`amdgpu-dwarf-vendor-extensions-operations`.
+
 .. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
 
 A. Changes Relative to DWARF Version 5
 ======================================
 
 .. note::
 
   This appendix provides changes relative to DWARF Version 5. It has been
   defined such that it is backwards compatible with DWARF Version 5.
   Non-normative text is shown in *italics*. The section numbers generally
   correspond to those in the DWARF Version 5 standard unless specified
   otherwise. Definitions are given for the additional operations, as well as
   clarifying how existing expression operations, CFI operations, and attributes
   behave with respect to generalized location descriptions that support address
   spaces and multiple places.
 
   The names for the new operations, attributes, and constants include "\
-  ``LLVM``\ " and are encoded with vendor specific codes so these extensions can
-  be implemented as an LLVM vendor extension to DWARF Version 5.
+  ``LLVM``\ " and are encoded with vendor specific codes so these extensions
+  can be implemented as an LLVM vendor extension to DWARF Version 5. New
+  operations other than ``DW_OP_LLVM_user`` are "prefixed" by
+  ``DW_OP_LLVM_user`` to make enough encoding space available for their
+  implementation.
 
   .. note::
 
     Notes are included to describe how the changes are to be applied to the
     DWARF Version 5 standard. They also describe rational and issues that may
     need further consideration.
 
 A.2 General Description

 * as the operand to certain operation expression operations,
 
 * as the operand to certain call frame information operations (see
   :ref:`amdgpu-dwarf-call-frame-information`),
 
 * and in location list entries (see
   :ref:`amdgpu-dwarf-location-list-expressions`).
 
+.. _amdgpu-dwarf-vendor-extensions-operations:
+
+A.2.5.4.0 Vendor Extension Operations
+#####################################
+
+1.  ``DW_OP_LLVM_user``
+
+  ``DW_OP_LLVM_user`` encodes a vendor extension operation. It has at least one
+  operand: a ULEB128 constant identifying a vendor extension operation. The
+  remaining operands are defined by the vendor extension. The vendor extension
+  opcode 0 is reserved and cannot be used by any vendor extension.
+
+  *The DW_OP_user encoding space can be understood to supplement the space
+  defined by DW_OP_lo_user and DW_OP_hi_user that is allocated by the standard
+  for the same purpose.*
+
 .. _amdgpu-dwarf-stack-operations:
 
 A.2.5.4.1 Stack Operations
 ##########################
 
 .. note::
 
   This section replaces DWARF Version 5 section 2.5.1.3.

 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.
+  This augments DWARF Version 5 section 7.7.1 and Table 7.9, and adds a new
+  table describing vendor extension operations for ``DW_OP_LLVM_user``.
 
 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`.
+that operation, followed by zero or more bytes of additional data. The encoding
+for the operation ``DW_OP_LLVM_user`` is described in
+:ref:`amdgpu-dwarf-operation-encodings-table`, and the encoding of all
+``DW_OP_LLVM_user`` vendor extensions operations are described in
+:ref:`amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table`.
 
 .. table:: DWARF Operation Encodings
    :name: amdgpu-dwarf-operation-encodings-table
 
-   ====================================== ===== ======== ===============================
+   ====================================== ===== ======== =========================================================================================
    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,
-                                                         ULEB128 byte displacement
-   ``DW_OP_LLVM_aspace_implicit_pointer`` 0xe9     2     4-byte or 8-byte offset of DIE,
+   ====================================== ===== ======== =========================================================================================
+   ``DW_OP_LLVM_user``                    0xe9     1+    ULEB128 vendor extension opcode, followed by vendor extension operands
+                                                         defined in :ref:`amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table`
+   ====================================== ===== ======== =========================================================================================
+
+.. table:: DWARF DW_OP_LLVM_user Vendor Extension Operation Encodings
+   :name: amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table
+
+   ====================================== ========= ========== ===============================
+   Operation                              Vendor    Number     Notes
+                                          Extension of
+                                          Opcode    Additional
+                                                    Operands
+   ====================================== ========= ========== ===============================
+   ``DW_OP_LLVM_form_aspace_address``     0x02          0
+   ``DW_OP_LLVM_push_lane``               0x03          0
+   ``DW_OP_LLVM_offset``                  0x04          0
+   ``DW_OP_LLVM_offset_uconst``           0x05          1      ULEB128 byte displacement
+   ``DW_OP_LLVM_bit_offset``              0x06          0
+   ``DW_OP_LLVM_call_frame_entry_reg``    0x07          1      ULEB128 register number
+   ``DW_OP_LLVM_undefined``               0x08          0
+   ``DW_OP_LLVM_aspace_bregx``            0x09          2      ULEB128 register number,
                                                                SLEB128 byte displacement
-   ``DW_OP_LLVM_piece_end``               0xea     0
-   ``DW_OP_LLVM_extend``                  0xeb     2     ULEB128 bit size,
+   ``DW_OP_LLVM_piece_end``               0x0a          0
+   ``DW_OP_LLVM_extend``                  0x0b          2      ULEB128 bit size,
                                                                ULEB128 count
-   ``DW_OP_LLVM_select_bit_piece``        0xec     2     ULEB128 bit size,
+   ``DW_OP_LLVM_select_bit_piece``        0x0c          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_aspace_implicit_pointer`` TBA           2      4-byte or 8-byte offset of DIE,
+                                                               SLEB128 byte displacement
+   ``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.