Issue 251017.2: Incremental Location Lists Using Overlays
| Author: | Cary Coutant |
|---|---|
| Champion: | |
| Date submitted: | 2025-10-17 |
| Date revised: | 2026-02-24 |
| Date closed: | |
| Type: | Enhancement |
| Status: | Open |
| DWARF version: | 6 |
This proposal depends on Issue 251120.1, “DWARF Operation to Create Runtime Overlay Composite Location Description,” and on Issue 251017.1, “Compound Storage as a Generalization of Composite Storage and Multiple Locations.”
This proposal is a spin-off from Issue 251017.1, which originally had this title. That proposal now covers the concept of compound storage as a generalization of composite storage and multiple locations; this new proposal now covers the idea of using location lists to build up a compound location incrementally.
Background
In Issue 251120.1, “DWARF Operation to Create Runtime Overlay Composite Location Description”, a set of overlay operators is proposed that produce a composite location by taking a base location and overlaying a new location on top of a range of bits from that base location, overriding the original location with the new one for that range of bits. As a simple example, consider the location of a variable of a struct type with three 32-bit fields, whose default location is on the stack at offset 0x40 relative to the frame base FB:
+--------------------------+
| a | b | c | (Memory at FB + 0x40)
+--------------------------+
+0 +4 +8
DW_AT_location: [ DW_OP_fbreg(0x40) ]
If the compiler chooses to promote the field b to reg1 for some section of code, we would describe this as an overlay on top of the memory location, of 4 bytes starting at offset 4 and a new location of reg1:
+--------+
| b | (reg1)
+--------------------------+
| a |////////| c | (Memory at FB + 0x40)
+--------------------------+
+0 +4 +8
Now presume that field c is promoted to reg2 in the PC range pc3..pc4. If the two ranges do not overlap, the composite would look like the following in the range pc3..pc4:
+--------+
| c | (reg2)
+--------------------------+
| a | b |////////| (Memory at FB + 0x40)
+--------------------------+
+0 +4 +8
The location list for this would be:
DW_AT_location: <loclist1>
loclist1:
DW_LLE_start_end(pc1..pc2)
[
DW_OP_fbreg(0x40) # base location
DW_OP_reg1 # new location
DW_OP_lit4 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_start_end(pc3..pc4)
[
DW_OP_fbreg(0x40) # base location
DW_OP_reg2 # new location
DW_OP_lit8 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_default_location
[
DW_OP_fbreg(0x40) # default location
]
DW_LLE_end_of_list
If the two ranges overlap or one contains the other, however, then the composite would look like the following when the PC is in both ranges:
+--------+
| c | (reg2)
+--------+--------+
| b | (reg1)
+--------------------------+
| a |////////|////////| (Memory at FB + 0x40)
+--------------------------+
+0 +4 +8
The location list would now need a separate entry for the overlapping region. For the case where pc1 < pc3 < pc2 < pc4, for example:
DW_AT_location: <loclist2>
loclist2:
DW_LLE_start_end(pc1..pc3) # Only b is promoted
[
DW_OP_fbreg(0x40) # base location
DW_OP_reg1 # new location
DW_OP_lit4 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_start_end(pc3..pc2) # Both b and c are promoted
[
DW_OP_fbreg(0x40) # base location
DW_OP_reg1 # new location
DW_OP_lit4 # offset
DW_OP_lit4 # length
DW_OP_overlay
DW_OP_reg2 # new location
DW_OP_lit8 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_start_end(pc2..pc4) # Only c is promoted
[
DW_OP_fbreg(0x40) # base location
DW_OP_reg2 # new location
DW_OP_lit8 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_default_location
[
DW_OP_fbreg(0x40) # default location
]
DW_LLE_end_of_list
Comparison with Ron’s Mappings Proposal
In Issue 250408.1, Ron proposes a new
DW_AT_mappings attribute and a set of mapping operators
that would allow the default location to remain in the
DW_AT_location attribute, and would place the temporary
mapping(s) in a location list:
DW_AT_location: [ DW_OP_fbreg(0x40) ]
DW_AT_mappings: <loclist2>
loclist2:
DW_LLE_start_end(pc1..pc2)
[
DW_OP_fbreg(0x44) # start of overlay (address, not offset)
DW_OP_reg1 # new location
DW_OP_lit4 # size of overlay
DW_OP_map
]
DW_LLE_start_end(pc3..pc4)
[
DW_OP_fbreg(0x48) # start of overlay (address, not offset)
DW_OP_reg2 # new location
DW_OP_lit4 # size of overlay
DW_OP_map
]
DW_LLE_end_of_list
(Note that Ron’s proposal includes a more compact alternative that would work
here, using the DW_OP_mapc operation.)
The mapping operators in the location list apply implicitly to the base location
given in the DW_AT_location attribute, and can cascade, so that overlapping
location lists can build a composite location incrementally.
The fundamental difference between the two approaches is that the overlay operators construct a composite location for the complete data object under consideration, while the mapping operators are designed to conditionally apply based on the range of bits that they cover; i.e., if the consumer is looking for the location of a specific field of the data object, it ignores any mapping operators that don’t cover the bits of that field. Thus, in the overlay approach, the consumer builds a complete composite location description of the entire object, then looks up where the bits of interest are to be found; in the mappings approach, the consumer determines which bits are of interest, then evaluates the mapping expressions that apply to those bits.
Ron’s proposal also introduces a new way to describe multiple locations. Instead of having overlapping PC ranges in a location list, each of which provides a complete description of one live location for the object, the new proposal provides a new map-multiple operator that describes multiple live locations for a range of bits.
Incremental Location Lists
This proposal keeps the traditional approach of describing the entire composite location, but redefines the way location lists work, allowing the composite location to be built up incrementally starting from a default location, and adding overlays for each matching PC range.
In this proposal, the location list begins with a base location entry, and new temporary locations based on the PC (e.g., register promotions) are presented as bounded location expressions following that. The entire location list is treated as one location description, except that each bounded location expression is skipped if its PC range does not contain the current PC.
In the example presented above, where field b has been promoted to reg1 in the PC range pc1..pc2, and field c is promoted to reg2 in the PC range pc3..pc4, we would have the following:
DW_AT_location: <loclist3>
loclist3:
DW_LLE_base_location
[
DW_OP_fbreg(0x40) # default location
]
DW_LLE_start_end(pc1..pc2)
[
DW_OP_reg1 # new location
DW_OP_lit4 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_start_end(pc3..pc4)
[
DW_OP_reg2 # new location
DW_OP_lit8 # offset
DW_OP_lit4 # length
DW_OP_overlay
]
DW_LLE_end_of_list
For a parallelized loop, where successive slices of an array are loaded into a vector register, the offset can be computed (e.g., via the loop index variable), and the length would represent the parallelization factor (2 in this simplified example):
+----------------+
| [n] | [n+1] | (vreg1)
+------------------------------------------+
| [0] | ... |////////////////| ... | (Memory at FB + 0x40)
+------------------------------------------+
+0 +4*n
DW_AT_location: <loclist4>
loclist4:
DW_LLE_default_location
[
DW_OP_fbreg(0x40) # default location
]
DW_LLE_start_end(pc1..pc2)
[
DW_OP_regx(vreg1) # new location
DW_OP_call(DIE ref to loop index var i)
DW_OP_deref_type(DIE ref to type of i)
DW_OP_lit4
DW_OP_mul # offset
DW_OP_lit8 # length
DW_OP_overlay
]
DW_LLE_end_of_list
Proposal
At the end of Section 2.5 Values and Locations, replace the paragraphs about location lists with the following:
A location list (see Section 3.19 on page 66), 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 counter values.
When evaluating a location list, the default location list entry is evaluated first, producing a default location. Each subsequent location list entry whose PC range includes the current PC is then evaluated, in order, as a continuation of the default location expression. If there is no default location list entry, an undefined location is implicitly pushed onto the stack.
The range entries of a location list typically describe a data object that has been moved or copied, in whole or in part, to a new location (e.g., promoted to a register). If a portion of the object has been moved or copied, an overlay operation can be used to produce a composite location based on the preceding location operations. If the entire object is moved to a new location, the location computed by the preceding operations can be ignored and simply replaced with a new location. Entries in a location list may have overlapping PC ranges, and each matching entry is evaluated incrementally, producing a final location.
In Section 3.19 Location Lists, replace the first two bullets with:
Default location expression. This kind of entry provides a DWARF operations that specify the default or base location of an object. This is the location where the object is found when no bounded location expression applies, and these operations are evaluated before any subsequent bounded location expressions. The lifetime of a base location for an object local to a subroutine excludes any prologue or epilogue ranges.
If there is no default location expression, or if the object is local to a subroutine and the PC is in a prologue or epilogue range, an undefined location is implicitly pushed before continuing.
Bounded location expression. This kind of entry provides DWARF operations that are evaluated only when the current PC is within the given range; i.e., when the current PC is greater than or equal to the starting address and less than the ending address. The location expression is valid even if the address range includes addresses within a prologue or epilogue range.
Location list entries are evaluated incrementally. After the default location expression is evaluated, each bounded location expression is conditionally executed as a continuation of the previous: if the current PC falls within the indicated range, the expression is executed; otherwise, the expression is skipped.
There are several kinds of bounded location expression entries which differ in the way that they specify the starting and ending addresses.
In the case of a bounded location expression where the range is defined by a starting address and either an ending address or a length, a starting address consisting of the reserved address value (see Section 2.4.1 on page 26) indicates a non-existent range, which is equivalent to omitting the description.
In earlier versions of DWARF, bounded location descriptions are evaluated independently. If no such bounded locations match, a default location description entry at the end of the list is evaluated.
2026-02-24: Split incremental location lists proposal out from Issue 251017.1. Revised description of incremental evaluation.
