Issue 161230.1: Indexing into location and range lists sections (revisited)

Author: Ron Brender
Champion: Ron Brender
Date submitted: 2016-12-30
Date revised:
Date closed:
Type: Ambiguity
Status: Accepted
DWARF Version: 5
Section 7.28 and 7.29, pg 240 & 241
This is a replacement for Issue Proposal 161120.1.

On October 18, Jakub reported an ambiguity regarding the ability to
index into the new location lists and range lists representations 
(which are described in Sections 2.6.2 and 2.17.3). The problem shows
up primarily in Sections 7.28 and 7.29:

1) The proposal that introduced the new representations intended that
both DW_FORM_sec_offset and DW_FORM_loclistx be allowed as ways to
index into the .debug_loclists section. Similarly, DW_FORM_sec_offsets
and DW_FORM_rnglistx can index into the .debug_rnglists section. To
this end, class loclistx includes both DW_FORM_sec_offset and DW_FORM_loclistx
while class rnglistx includes both DW_FORM_sec_offset and DW_FORM_rnglistx.

Note that DW_FORM_sec_offset uses an 4- or 8-byte offset relative to 
the beginning of the section, while DW_FORM_loclistx and DW_FORM_rnglistx
use ULEB indexes that indirect through the offsets table of those respective
sections.

2) However, Section 7.28 requires that "There is one offset for each 
range list." and Section 7.29 similarly requires that "There is one offset 
for each location list."

3) The problem is that there is no need for an offsets table if only
DW_FORM_sec_offset is used--but this appears not to be an option.

The proposal in Issue 161120.1 sought to resolve this ambiguity by removing
the option to use DW_FORM_sec_offset and keeping the requirement for a 
non-zero length offset table. That proposal was opposed by Jakub
based on implementation experience indicating that DW_FORM_sec_offset can
sometimes result in a size advantage. The proposal was not accepted at the
December 6 Committee meeting.

This proposal resolves the issue by explicitly allowing a zero length
offsets table (in which case DW_FORM_sec_offset must be used).

Proposal
--------

1) In section 7.28, page 240 of the (Public Review draft), replace bullet 5 and the 
following two paragraphs with:

    5. offset_entry_count (uword)
       A 4-byte count of the number of offsets that follow the header. This count
       may be zero.

    Immediately following the header is an array of offsets. This array is followed by
    a series of range lists.

    If the offset_entry_count is non-zero, there is one offset for each range list. The
    contents of the ith offset is the offset (an unsigned integer) from the beginning of
    the offset array to the location of the ith range list. In the 32-bit DWARF format,
    each offset is 4-bytes in size; in the 64-bit DWARF format, each offset is 8-bytes in
    size (see Section 7.4 on page 196).

    *If the offset_entry_count is zero, then DW_FORM_rnglistx cannot be used to access
    a range list; DW_FORM_sec_offset must be used instead. If the offset_entry_count
    is non-zero, then DW_FORM_rnglistx may be used to access a range list; this is
    necessary in split units and otherwise may be more compact than using
    DW_FORM_sec_offset.*

    Range lists are described in Section 2.17.3 on page 52.

2) 1) In section 7.29, page 241 of the (Public Review draft), replace bullet 5 and the 
following two paragraphs with:

    5. offset_entry_count (uword)
       A 4-byte count of the number of offsets that follow the header. This count
       may be zero.

    Immediately following the header is an array of offsets. This array is followed by
    a series of location lists.

    If the offset_entry_count is non-zero, there is one offset for each location list.
    The contents of the ith offset is the offset (an unsigned integer) from the
    beginning of the offset array to the location of the ith location list. In the 32-bit
    DWARF format, each offset is 4-bytes in size; in the 64-bit DWARF format, each
    offset is 8-bytes in size (see Section 7.4 on page 196).

    *If the offset_entry_count is zero, then DW_FORM_loclistx cannot be used to access
    a location list; DW_FORM_sec_offset must be used instead. If the
    offset_entry_count is non-zero, then DW_FORM_loclistx may be used to access a
    location list; this is necessary in split units and otherwise may be more compact than
    using DW_FORM_sec_offset.*

    Location lists are described in Section 2.6.2 on page 43.

--
Accepted 1/3/2017.