[PATCH] D49572: [docs] Clarify role of DIExpressions within debug intrinsics

[Vedant Kumar via Phabricator via llvm-commits]

vsk created this revision.
vsk added reviewers: rnk, aprantl, bjope.
vsk added a project: debug-info.

This is an attempt to make the semantics of DIExpressions within
llvm.dbg.{addr, declare, value} easier to understand.

In particular it tries to clarify the behavior of llvm.dbg.value with
implicit (direct) vs. concrete (indirect) value operands.  I've included
a note about a possible future direction in which llvm.dbg.value is only
allowed to have implicit value operands.


https://reviews.llvm.org/D49572

Files:
  docs/LangRef.rst
  docs/SourceLevelDebugging.rst


Index: docs/SourceLevelDebugging.rst
===================================================================
--- docs/SourceLevelDebugging.rst
+++ docs/SourceLevelDebugging.rst
@@ -242,7 +242,8 @@
 value.  The first argument is the new value (wrapped as metadata).  The second
 argument is a `local variable <LangRef.html#dilocalvariable>`_ containing a
 description of the variable.  The third argument is a `complex expression
-<LangRef.html#diexpression>`_.
+<LangRef.html#diexpression>`_, with semantics which depend on whether the value
+operand is an implicit or a concrete location.
 
 Object lifetimes and scoping
 ============================
Index: docs/LangRef.rst
===================================================================
--- docs/LangRef.rst
+++ docs/LangRef.rst
@@ -4594,11 +4594,41 @@
 
 DWARF specifies three kinds of simple location descriptions: Register, memory,
 and implicit location descriptions. Register and memory location descriptions
-describe the *location* of a source variable (in the sense that a debugger might
-modify its value), whereas implicit locations describe merely the *value* of a
-source variable. DIExpressions also follow this model: A DIExpression that
-doesn't have a trailing ``DW_OP_stack_value`` will describe an *address* when
-combined with a concrete location.
+describe the *concrete location* of a source variable (in the sense that a
+debugger might modify its value), whereas *implicit locations* describe merely
+the actual *value* of a source variable which might not exist in registers or
+in memory. Note that a location description is defined for certain ranges of a
+program, i.e the location of a variable may change over the course of the
+program.
+
+A DIExpression attached to a ``llvm.dbg.addr`` or ``llvm.dbg.declare``
+intrinsic describes the concrete location of a source variable. A debugger must
+be able to modify the variable via this location. Consequently, this
+DIExpression must not contain ``DW_OP_stack_value``.
+
+The value operand of a ``llvm.dbg.value`` intrinsic may either be a concrete
+location or an implicit one. The following rules apply to a DIExpression
+attached to a ``llvm.dbg.value`` intrinsic:
+
+- If the value operand of the intrinsic is an implicit location, the
+  DIExpression is interpreted as if it contained ``DW_OP_stack_value``,
+  regardless of what the DIExpression contains. The intrinsic describes an
+  implicit location.
+
+- If the value operand of the intrinsic is a concrete location and the
+  DIExpression does not contain ``DW_OP_stack_value``, the intrinsic describes
+  a concrete location.
+
+- If the value operand of the intrinsic is a concrete location and the
+  DIExpression contains ``DW_OP_stack_value``, the DIExpression is interpreted
+  as if it started with a ``DW_OP_deref``, regardless of what else the
+  DIExpression contains. The intrinsic describes an implicit location.
+
+.. note::
+
+   In the future, ``llvm.dbg.value`` may only be allowed to have an implicit
+   value operand. This should simplify DIExpression handling by eliminating two
+   of the special cases described above.
 
 .. code-block:: text
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D49572.156375.patch
Type: text/x-patch
Size: 3159 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180719/823690bf/attachment.bin>