[llvm] [LangRef] Clarify definition of fragments and debug intrinsics (PR #82019)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-debuginfo

Author: Scott Linder (slinder1)

<details>
<summary>Changes</summary>

Try to give a more complete description of what we call a "fragment", and define "spatial overlap" between variables and fragments to make the details of when one intrinsic ends the effects of another more direct and complete.

Also change the description of the debug intrinsics to the pseudo-grammar style from LangRef.

---
Full diff: https://github.com/llvm/llvm-project/pull/82019.diff


1 Files Affected:

- (modified) llvm/docs/SourceLevelDebugging.rst (+49-17) 


``````````diff
diff --git a/llvm/docs/SourceLevelDebugging.rst b/llvm/docs/SourceLevelDebugging.rst
index e1df7c355ee092..ccd455a59f5a5b 100644
--- a/llvm/docs/SourceLevelDebugging.rst
+++ b/llvm/docs/SourceLevelDebugging.rst
@@ -130,6 +130,40 @@ debugging information influences optimization passes then it will be reported
 as a failure.  See :doc:`TestingGuide` for more information on LLVM test
 infrastructure and how to run various tests.
 
+.. _variables_and_variable_fragments:
+
+Variables and Variable Fragments
+================================
+
+Source language variables (or just "variables") are represented by `local
+variable <LangRef.html#dilocalvariable>`_ and `global variable
+<LangRef.html#diglobalvariable>`_ metadata nodes.
+
+When variables are not allocated to contiguous memory or to a single LLVM value
+the metadata must record enough information to describe each "piece" or
+"fragment" of the source variable. Each fragment is a contiguous span of bits
+of the variable it is a part of.
+
+This is achieved by encoding fragment information at the end of the
+``DIExpression`` with the ``DW_OP_LLVM_fragment`` operation, whose operands are
+the bit offset of the fragment relative to the start of the variable, and the
+fragment size in bits.
+
+.. note::
+
+   The ``DW_OP_LLVM_fragment`` operation acts only to encode the fragment
+   information, and does not have an effect on the semantics of the expression.
+
+A debug intrinsic which refers to a ``DIExpression`` ending with a fragment
+operation provides information about the fragment of the variable it refers to,
+rather than the whole variable.
+
+An equivalence relation over the set of all variables and variable fragments
+called "spatially overlapping" is defined in order to describe when intrinsics
+terminate the effects of other intrinsics. A variable spatially overlaps with
+itself and all fragments of itself. Fragments additionally spatially overlap
+with other fragments sharing one common bit of the same variable.
+
 .. _format:
 
 Debugging information format
@@ -180,7 +214,9 @@ track source local variables through optimization and code generation.
 
 .. code-block:: llvm
 
-  void @llvm.dbg.declare(metadata, metadata, metadata)
+  void @llvm.dbg.declare(metadata <type> <value>,
+                         metadata <!DILocalVariable>,
+                         metadata <!DIExpression>)
 
 This intrinsic provides information about a local element (e.g., variable).
 The first argument is metadata holding the address of variable, typically a
@@ -221,7 +257,9 @@ agree on the memory location.
 
 .. code-block:: llvm
 
-  void @llvm.dbg.value(metadata, metadata, metadata)
+  void @llvm.dbg.value(metadata <<type> <value>|!DIArgList>,
+                       metadata <!DILocalVariable>,
+                       metadata <!DIExpression>)
 
 This intrinsic provides information when a user source variable is set to a new
 value.  The first argument is the new value (wrapped as metadata).  The second
@@ -243,12 +281,12 @@ the complex expression derives the direct value.
 
 .. code-block:: llvm
 
-  void @llvm.dbg.assign(Value *Value,
-                        DIExpression *ValueExpression,
-                        DILocalVariable *Variable,
-                        DIAssignID *ID,
-                        Value *Address,
-                        DIExpression *AddressExpression)
+  void @llvm.dbg.assign(metadata <<type> <value>|!DIArgList>,
+                        metadata <!DIExpression>,
+                        metadata <!DILocalVariable>,
+                        metadata <!DIAssignID>,
+                        metadata <type> <value>,
+                        metadata <!DIExpression>)
 
 This intrinsic marks the position in IR where a source assignment occurred. It
 encodes the value of the variable. It references the store, if any, that
@@ -259,13 +297,6 @@ argument is a ``DIAssignID`` used to reference a store. The fifth is the
 destination of the store (wrapped as metadata), and the sixth is a `complex
 expression <LangRef.html#diexpression>`_ that modifies it.
 
-The formal LLVM-IR signature is:
-
-.. code-block:: llvm
-
-  void @llvm.dbg.assign(metadata, metadata, metadata, metadata, metadata, metadata)
-
-
 See :doc:`AssignmentTracking` for more info.
 
 Object lifetimes and scoping
@@ -417,8 +448,9 @@ values through compilation, when objects are promoted to SSA values an
 ``llvm.dbg.value`` intrinsic is created for each assignment, recording the
 variable's new location. Compared with the ``llvm.dbg.declare`` intrinsic:
 
-* A dbg.value terminates the effect of any preceding dbg.values for (any
-  overlapping fragments of) the specified variable.
+* A dbg.value terminates the effect of any preceding dbg.values for any
+  spatially overlapping variables or fragments of the specified variable or
+  fragment.
 * The dbg.value's position in the IR defines where in the instruction stream
   the variable's value changes.
 * Operands can be constants, indicating the variable is assigned a

``````````

</details>


https://github.com/llvm/llvm-project/pull/82019