llvm.org GIT mirror llvm / 1731345
[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 Vedant Kumar 1 year, 2 months ago
2 changed file(s) with 35 addition(s) and 9 deletion(s). Raw diff Collapse all Expand all
45874587 ``DIExpression`` nodes represent expressions that are inspired by the DWARF
45884588 expression language. They are used in :ref:`debug intrinsics`
45894589 (such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the
4590 referenced LLVM variable relates to the source language variable.
4591
4592 The current supported vocabulary is limited:
4590 referenced LLVM variable relates to the source language variable. Debug
4591 intrinsics are interpreted left-to-right: start by pushing the value/address
4592 operand of the intrinsic onto a stack, then repeatedly push and evaluate
4593 opcodes from the DIExpression until the final variable description is produced.
4594
4595 The current supported opcode vocabulary is limited:
45934596
45944597 - ``DW_OP_deref`` dereferences the top of the expression stack.
45954598 - ``DW_OP_plus`` pops the last two entries from the expression stack, adds
46094612 - ``DW_OP_stack_value`` marks a constant value.
46104613
46114614 DWARF specifies three kinds of simple location descriptions: Register, memory,
4612 and implicit location descriptions. Register and memory location descriptions
4613 describe the *location* of a source variable (in the sense that a debugger might
4614 modify its value), whereas implicit locations describe merely the *value* of a
4615 source variable. DIExpressions also follow this model: A DIExpression that
4616 doesn't have a trailing ``DW_OP_stack_value`` will describe an *address* when
4617 combined with a concrete location.
4615 and implicit location descriptions. Note that a location description is
4616 defined over certain ranges of a program, i.e the location of a variable may
4617 change over the course of the program. Register and memory location
4618 descriptions describe the *concrete location* of a source variable (in the
4619 sense that a debugger might modify its value), whereas *implicit locations*
4620 describe merely the actual *value* of a source variable which might not exist
4621 in registers or in memory (see ``DW_OP_stack_value``).
4622
4623 A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect
4624 value (the address) of a source variable. The first operand of the intrinsic
4625 must be an address of some kind. A DIExpression attached to the intrinsic
4626 refines this address to produce a concrete location for the source variable.
4627
4628 A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable.
4629 The first operand of the intrinsic may be a direct or indirect value. A
4630 DIExpresion attached to the intrinsic refines the first operand to produce a
4631 direct value. For example, if the first operand is an indirect value, it may be
4632 necessary to insert ``DW_OP_deref`` into the DIExpresion in order to produce a
4633 valid debug intrinsic.
4634
4635 .. note::
4636
4637 A DIExpression is interpreted in the same way regardless of which kind of
4638 debug intrinsic it's attached to.
46184639
46194640 .. code-block:: text
46204641
242242 argument is a `local variable `_ containing a
243243 description of the variable. The third argument is a `complex expression
244244 `_.
245
246 An `llvm.dbg.value` intrinsic describes the *value* of a source variable
247 directly, not its address. Note that the value operand of this intrinsic may
248 be indirect (i.e, a pointer to the source variable), provided that interpreting
249 the complex expression derives the direct value.
245250
246251 Object lifetimes and scoping
247252 ============================