Issue 230524.1: Location Descriptions on the DWARF Stack

Tony Tye, Cary Coutant

This is one of several proposals for GPU support, extracted from
AMD's work on [DWARF Extensions for Heterogeneous Debugging][1] for the
LLVM compiler.

This is a large proposal, in part due to some document reorganization
and terminology changes that permeate the DWARF spec.
To help the reader see the proposed changes in context,
a [redline comparison][2] of the affected parts of the DWARF spec
is available.

Background
----------

The DWARF 5 concept of location descriptions (Section 2.6) limits their
use to cases where the location described is final, and not subject to
some further modification, with two exceptions. First, if the location
description is a memory location description, it is a simple DWARF
expression (Section 2.5) that can be modified by further DWARF
expression operators. Second, for any form of location description, it
can be offset by a fixed number of bits by using a `DW_OP_bit_piece`
composition operator.

Where do these limitations matter?

Consider the case of a FORTRAN array (as shown in Appendix D in D.2.1)
that has been partially promoted to a register or registers. The
evaluation of its lower and upper bounds depends on the location of the
array as provided by `DW_OP_push_object_address`. If the array is not
entirely in memory, this operation is not able to provide the address of
the object, as it can only provide a memory address. If
`DW_OP_push_object_address` were allowed to push a composite location
description on the stack, we could apply further operations to locate
the bounds of the array.

Similarly, consider the case of a pointer-to-member type in C++, where
the object (or part of the object) has been promoted to a register. In
this case, `DW_AT_use_location` is not able to provide the address of
the object. In optimized code, it sometimes would need to provide a
register location description or a composite location description, but
these cannot be pushed onto the DWARF stack. If `DW_AT_use_location`
were allowed to push a composite location description on the stack, we
could apply further operations to determine the register location of the
member being referenced.

Also consider the case where a `DW_OP_call*` operator is used to get the
location of a variable. If the variable happens to be in a register at
the current PC, the call operator cannot succeed, as it cannot push
anything but a memory address on the stack.

All of these cases have a common limiting factor: that location
descriptions cannot be pushed onto the stack, and subsequently operated
on to produce derived location descriptions.

Overview
--------

This proposal removes that limitation. A DWARF expression may evaluate
to either a value or a location. Location descriptions are now simply
DWARF expressions that evaluate to a location, and are now called
location expressions.

The DWARF stack is extended so that it can hold elements that are either
(typed) values or (single) locations. The operators in Section 2.6 that
previously defined register and implicit locations are now considered
part of a DWARF expression, and are no longer "terminal" in the sense
that they cannot be part of a larger expression.

The literal encoding operations, defined in Section 2.5.1.1, push values
onto the stack, except for `DW_OP_addr` and `DW_OP_addrx`, which push
memory locations. These latter two operations are moved to a new
section.

Stack operations, defined in Section 2.5.1.3, can operate on values or
locations, or any combination of the two.

Most existing arithmetic and logical operators, defined in Section 2.5.1.4,
continue to be limited to operating on values only.

The `DW_OP_deref*` operator is extended to operate on
any location, and provide the value contained at that
location, whether in memory, in a register, in implicit storage, or a
composite value.

The `DW_OP_push_object_address`, renamed `DW_OP_push_object_location` operator pushes a location,
which may be a memory address (as before), or a register, implicit
storage, or a composite.

The `DW_AT_use_location` attribute provides an expression used to compute
the address of a member for a pointer-to-member type, and expects the
evaluation mechanism to provide the value of the pointer and the
location of the object as implicitly-pushed elements on the stack. The
latter element is now allowed to be any location.

Two new operators, `DW_OP_offset` and `DW_OP_bit_offset`, are introduced
that allow a location on the stack to be modified by a byte
or a bit offset.

The composite location operators, `DW_OP_piece` and `DW_OP_bit_piece`,
are redefined to build up a composite location, which is held in the top
element of the stack. A new operator, `DW_OP_composite`, is added
to begin a new (empty) composite location.

The `DW_OP_call*` operators are now allowed to leave a location
on the stack.

A new Section 2.5 "Values and Locations" is added, and the old Sections
2.5, "DWARF Expressions," and 2.6, "Location Descriptions," are moved into a
new Chapter 3, "DWARF Expressions," and reorganized as follows:

- (Remove) 2.5 DWARF Expressions
- (Remove) 2.6 Location Descriptions

- (New) 2.5 Values and Locations

- (New) Chapter 3: DWARF Expressions
    - 3.1 DWARF Expression Evaluation Context (was 2.5.1)
    - 3.2 Stack Operations (was 2.5.2.3)
    - 3.3 Literal and Constant Operations (was 2.5.2.1)
    - 3.4 Register Value Operations (was 2.5.2.2)
    - 3.5 Arithmetic and Logical Operations (was 2.5.2.4)
    - 3.6 Context Query Operations (new)
    - 3.7 Memory Locations (was 2.6.1.1.2)
    - 3.8 Register Locations (was 2.6.1.1.3)
    - 3.9 Undefined Locations (was 2.6.1.1.1)
    - 3.10 Implicit Locations (was 2.6.1.1.4)
    - 3.11 Implicit Pointer Locations (was 2.6.1.1.4)
    - 3.12 Composite Locations (was 2.6.1.2)
    - 3.13 Dereferencing Operations (new)
    - 3.14 Offset Operations (new)
    - 3.15 Control Flow Operations (was 2.5.2.5)
    - 3.16 Type Conversions (was 2.5.2.6)
    - 3.17 Special Operations (was 2.5.2.7)
    - 3.18 Value Lists (was 2.5.2)
    - 3.19 Location Lists (was 2.6.2)

Proposed Changes
----------------

### Section 2.2 Attribute Types

In Table 2.3, Classes of attribute value, in the rows for "exprval" and
"locdesc," replace the reference to Sections 2.5 and 2.6 with
references to Chapter 3. In the row for "locdesc," change "locdesc" to
"exprloc" and change "location description" to "location expression"
(2 places).

Rename class `locdesc` to `exprloc` throughout the document.

### Section (OLD) 2.5 DWARF Expressions [REMOVED]

This section is moved from Chapter 2 into a new Chapter 3.

### Section (OLD) 2.6 Location Descriptions [REMOVED]

This section is moved from Chapter 2 into a new Chapter 3.

### Section (NEW) 2.5 Values and Locations [NEW]

Add the following as a new subsection:

> As described in Section 2.2, DWARF attributes may have
> different classes of values. In many cases, attribute values
> directly provide the numeric value of a property such as
> bounds of an array, the size of a type, the value of a
> named constant in the program, or a string value such as
> the name of a variable or type.
> In other cases, they provide the *location* of a data
> object, such as the address of a variable or common block
> (see Section 4.1), instead of directly providing the value
> of the object.
> 
> The attribute value classes *constant* and *string* are used
> to provide static values for properties, but often the
> values need to be computed dynamically. The classes
> *exprval* and *vallist* indicate that the attribute value is
> to be computed by evaluating a DWARF expression (described
> in Chapter 3).
> 
> A DWARF expression of class *exprval* can be used to compute
> a value that cannot be given statically, such as the upper
> bound of a dynamic array.
> 
> Sometimes, an attribute value may depend on the program
> counter, such as the loop vectorization factor. A value list
> (see Section 3.17), encoded using class *vallist*, can be
> used in this case. A value list is a list of DWARF
> expressions, each associated with a range of program
> counters.
> 
> The class *address* is used to provide a static
> memory address for an object located in memory, and the
> classes *exprloc* and *loclist* indicate that the location
> of an object is to be computed by evaluating a DWARF
> expression. In these cases, where the DWARF expression is
> expected to produce a location, the expression is called a
> “location expression.”
> 
> *(In DWARF 5, the term “location description” was used to
> refer both to a sequence of DWARF operations that evaluates
> to a location, and to the result of that evaluation. For
> DWARF 6, we use the terms “location expression” for the
> expression and “location” for the result of
> evaluating the expression.)*
> 
> The class *exprloc* is used to provide a location
> expression that yields a single location. This is
> sufficient to describe the location of an object whose
> lifetime is either static or the same as the lexical block
> that owns it (excluding any prologue or epilogue ranges),
> and that does not move during its lifetime.
> 
> A location list (see Section 3.18), encoded using class
> *loclist*, describes objects that have a limited lifetime
> or that change their location during their lifetime. A
> location list is a list of location expressions, each
> associated with a range of program counters.
> 
> A location list may have overlapping PC ranges, and thus may
> yield multiple locations at a given PC.
> In this case, the consumer may assume that the object value
> stored is the same in all locations, excluding bits of the
> object that serve as padding. Non-padding bits that are
> undefined (for example, as a result of optimization) must be
> undefined in all the locations.
> 
> *A location list that yields multiple locations can be
> used to describe objects that reside in more than one
> piece of storage at the same time. An object may have more
> than one location as a result of optimization. For
> example, a value that is only read may be promoted from
> memory to a register for some region of code, but later
> code may revert to reading the value from memory as the
> register may be used for other purposes.*
> 
> DWARF can describe the location of program objects in
> several kinds of storage, such as a memory address space or
> a register. Each kind of storage is treated as a linear
> stream of bits of finite size, organized into bytes and/or
> words. The ordering of bits uses the bit numbering and
> direction conventions that are appropriate to the target
> architecture and the ABI.
> *For example, on a little-endian architecture, bits are
> numbered within bytes and words from least-significant
> to most-significant (right-to-left), while on a big-endian
> architecture, bits are numbered left-to-right.*
> 
> A location names a block of storage and a
> (non-negative, zero-based) bit offset relative to the start
> of that storage. It gives the location of the program
> object, which occupies a sequence of contiguous bits
> starting at that location.
> The bit offset of a location must be less than the size of
> the named block of storage (for a zero-length block of
> storage, the offset must be 0).
> 
> DWARF can describe locations in six kinds of storage:
> 
>   - Memory.
>     Corresponds to the target architecture memory address
>     spaces. There is always a default address space, and the
>     target architecture may define additional address
>     spaces.
>     Each memory storage block is the size of the corresponding
>     address space.
>     *(The offset can be thought of as a byte or word address
>     combined with a bit offset within the byte or word.)*
> 
>   - Registers.
>     Corresponds to the target architecture registers.
>     Each register storage block is the size of the corresponding
>     register.
> 
>   - Undefined storage.
>     Indicates no value is available, as when a variable has
>     been optimized out. The location names a block of
>     imaginary storage that cannot be read.
>     Writing to undefined storage has no effect.
>     The size of an undefined storage block is the same as

Author:	Tony Tye, Cary Coutant
Champion:	Cary Coutant
Date submitted:	2023-05-24
Date revised:	2025-10-23
Date closed:	2025-10-13
Type:	Enhancement
Status:	Accepted
DWARF version:	6