From: Vedant Kumar Date: Sat, 28 Jul 2018 00:33:47 +0000 (+0000) Subject: [docs] Clarify role of DIExpressions within debug intrinsics X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=17313457855ccd20700c6e9e084038026460517c;p=llvm [docs] Clarify role of DIExpressions within debug intrinsics This should make the semantics of DIExpressions within llvm.dbg.{addr, declare, value} easier to understand. Differential Revision: https://reviews.llvm.org/D49572 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@338182 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 38bed417104..a60c9b515ab 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -4588,9 +4588,12 @@ DIExpression ``DIExpression`` nodes represent expressions that are inspired by the DWARF expression language. They are used in :ref:`debug intrinsics` (such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the -referenced LLVM variable relates to the source language variable. +referenced LLVM variable relates to the source language variable. Debug +intrinsics are interpreted left-to-right: start by pushing the value/address +operand of the intrinsic onto a stack, then repeatedly push and evaluate +opcodes from the DIExpression until the final variable description is produced. -The current supported vocabulary is limited: +The current supported opcode vocabulary is limited: - ``DW_OP_deref`` dereferences the top of the expression stack. - ``DW_OP_plus`` pops the last two entries from the expression stack, adds @@ -4610,12 +4613,30 @@ The current supported vocabulary is limited: - ``DW_OP_stack_value`` marks a constant value. 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. +and implicit location descriptions. Note that a location description is +defined over certain ranges of a program, i.e the location of a variable may +change over the course of the program. Register and memory location +descriptions 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 (see ``DW_OP_stack_value``). + +A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect +value (the address) of a source variable. The first operand of the intrinsic +must be an address of some kind. A DIExpression attached to the intrinsic +refines this address to produce a concrete location for the source variable. + +A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable. +The first operand of the intrinsic may be a direct or indirect value. A +DIExpresion attached to the intrinsic refines the first operand to produce a +direct value. For example, if the first operand is an indirect value, it may be +necessary to insert ``DW_OP_deref`` into the DIExpresion in order to produce a +valid debug intrinsic. + +.. note:: + + A DIExpression is interpreted in the same way regardless of which kind of + debug intrinsic it's attached to. .. code-block:: text diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index 3fa738c7e44..7064c403ef1 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -244,6 +244,11 @@ argument is a `local variable `_ containing a description of the variable. The third argument is a `complex expression `_. +An `llvm.dbg.value` intrinsic describes the *value* of a source variable +directly, not its address. Note that the value operand of this intrinsic may +be indirect (i.e, a pointer to the source variable), provided that interpreting +the complex expression derives the direct value. + Object lifetimes and scoping ============================