[Dwarf-discuss] Proposal: Error: DW_OP_entry_value description and examples

[Robinson, Paul]

# Error: DW_OP_entry_value description and examples

## Overview

DW_OP_entry_value provides a way to compute a value as if the value
had been computed on entry to the current subprogram. Its operand is
either a DWARF expression, which assumes nothing is already on the
DWARF stack and leaves one value on the DWARF stack; or, it is a
register location description, and the content of the register (as it
was on entry to the subprogram) is implicitly read and pushed on the
DWARF stack. The register location description is simply a more compact 
representation of the common case of reading a register; for example, 
the producer can emit "DW_OP_reg1" instead of "DW_OP_breg1 0" with the 
same result.

However, the description and examples aren't completely consistent, and
in some cases are wrong. This proposal corrects the language and examples.

## Proposed Changes

### Section 2.5.1.7 Special Operations, p.37

The first sentence of the description of DW_OP_entry_value reads:

    The DW_OP_entry_value operation pushes the value that the described
    location held upon entering the current subprogram.

A DWARF expression does not describe a location, so this should read:

    The DW_OP_entry_value operation evaluates an expression or register
    location description as if it had been evaluated upon entering the
    current subprogram, and pushes the value of the expression or content
    of the register, respectively.

### Appendix D.1.3, pp.291-292

There are six examples of DW_OP_entry_value, some of which are not
consistent with the description and some of which are just plain wrong.
The six examples are:

    DW_OP_entry_value 2 DW_OP_breg1 0
    DW_OP_entry_value 1 DW_OP_reg1
    DW_OP_entry_value 2 DW_OP_breg1 0 DW_OP_stack_value
    DW_OP_entry_value 1 DW_OP_reg1 DW_OP_stack_value
    DW_OP_entry_value 3 DW_OP_breg4 16 DW_OP_deref DW_OP_stack_value
    DW_OP_entry_value 1 DW_OP_reg5 DW_OP_plus_uconst 16

The first two illustrate the smaller expression allowed by the special
case for a register location description; they are fine.

The third is just wrong and should be deleted. DW_OP_stack_value converts
a memory location description into a value, but what precedes it is not
a memory location description. Without the stack_value, it's identical to
the first example.

The fourth is just wrong and should be deleted. DW_OP_reg1 names a register
but pushes nothing on the stack, so DW_OP_stack_value is incorrect; and
without that, it's identical to the second example.

The fifth should not have DW_OP_stack_value at the end; the expression
already leaves a value on the stack.

The sixth is incorrectly using DW_OP_reg5, which is allowed in a location
description but not in a simple DWARF expression. The expression could be:
    DW_OP_entry_value 2 DW_OP_breg5 16

The textual description of the sixth example should also be revised.
Currently it reads:
    The address of the memory location is calculated by adding 16 to the
    value contained in register 5 upon erringing the current subprogram.
    <i>Note that unlike the previous DW_OP_entry_value examples, this one
    does not end with DW_OP_stack_value.</i>

This should be changed to:
    Add 16 to the value register 5 had upon entering the current subprogram
    and push the result.

(The italicized text after the sixth example should be removed entirely;
there is no reason ever to use DW_OP_stack_value in these expressions.)