[PATCH] D135394: [AMDGPU][NFC] Update DW_OP_LLVM_overlay documentation

[Tony Tye via Phabricator via llvm-commits]

t-tye created this revision.
t-tye added reviewers: kzhuravl, scott.linder, zoran.zaric.
Herald added subscribers: kosarev, kerbowa, tpr, dstuttard, yaxunl, jvesely.
Herald added a project: All.
t-tye requested review of this revision.
Herald added subscribers: llvm-commits, wdng.
Herald added a project: LLVM.

Update DWARF Extensions For Heterogeneous Debugging proposal for the
DW_OP_LLVM_overlay operation:

1. Add an example.
2. Correct definition to specify both operands of the DW_OP_bit_piece operations.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D135394

Files:
  llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst


Index: llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
===================================================================
--- llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
+++ llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst
@@ -627,6 +627,49 @@
 offset and size. See ``DW_OP_LLVM_overlay`` and ``DW_OP_LLVM_bit_overlay`` in
 :ref:`amdgpu-dwarf-composite-location-description-operations`.
 
+Consider an array that has been partially registerized such that the currently
+processed elements are held in registers, whereas the remainder of the array
+remains in memory. Consider the loop in this C function, for example:
+
+.. code::
+  :number-lines:
+
+  extern void foo(uint32_t dst[], uint32_t src[], int len) {
+    for (int i = 0; i < len; ++i)
+      dst[i] += src[i];
+  }
+
+Inside the loop body, the machine code loads ``src[i]`` and ``dst[i]`` into
+registers, adds them, and stores the result back into ``dst[i]``.
+
+Considering the location of ``dst`` and ``src`` in the loop body, the elements
+``dst[i]`` and ``src[i]`` would be located in registers, all other elements are
+located in memory. Let register ``R0`` contain the base address of ``dst``,
+register ``R1`` contain ``i``, and register ``R2`` contain the registerized
+``dst[i]`` element. We can describe the location of ``dst`` as a memory location
+with a register location overlaid at a runtime offset involving ``i``:
+
+.. code::
+  :number-lines:
+
+  // 1. Memory location description of dst elements located in memory:
+  DW_OP_breg0 0
+
+  // 2. Register location description of element dst[i] is located in R2:
+  DW_OP_reg2
+
+  // 3. Offset of the register within the memory of dst:
+  DW_OP_breg1 0
+  DW_OP_lit4
+  DW_OP_mul
+
+  // 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
+
 .. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:
 
 A. Changes Relative to DWARF Version 5
@@ -2861,11 +2904,10 @@
     overlay starting at the overlay offset BO and covering overlay bit size BS.*
 
     1.  If BO is not 0 then push BL followed by performing the ``DW_OP_bit_piece
-        BO`` operation.
-    2.  Push OL followed by performing the ``DW_OP_bit_piece BS`` operation.
+        BS, BO`` operation.
+    2.  Push OL followed by performing the ``DW_OP_bit_piece BS, 0`` operation.
     3.  If *rbss(BL)* is greater than BO plus BS, push BL followed by performing
-        the ``DW_OP_LLVM_bit_offset (BO + BS); DW_OP_bit_piece (rbss(BL) - BO -
-        BS)`` operations.
+        the ``DW_OP_bit_piece (rbss(BL) - BO - BS), (BO + BS)`` operation.
     4.  Perform the ``DW_OP_LLVM_piece_end`` operation.
 
 .. _amdgpu-dwarf-location-list-expressions:


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D135394.465849.patch
Type: text/x-patch
Size: 2867 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20221006/ab5ef941/attachment.bin>