||Two-Level Line Tables
Section 6.2, pg 128
This proposal introduces a new two-level line number table to
DWARF, splitting the current line number table into two parts: a
"logicals" table, and an "actuals" table. The actuals table would
be optional, and when omitted, the logicals table would
correspond to the DWARF v4 line number table.
In a two-level line number table, the logicals table would
provide a mapping from each logical statement in a program to a
recommended breakpoint location, and the actuals table would
provide a mapping from PC location to a logical statement
represented in the logicals table. The separation allows the line
number table to represent directly the nesting of inline
functions so that consumers would not need to parse the DIE tree
in order to show inlined calls.
For further background information and possible future
extensions, see the DWARF Wiki page:
In Section 6.2 ("Line Number Information"), add the following
non-normative text at the end of the section:
For optimized code, where instruction scheduling may reorder
instructions across statement boundaries, where loop
optimizations may clone code and move instructions across
loop iterations, and where inlining may introduce
instructions from an inlined call into the instruction
stream, an alternate representation with two matrices may be
used. One matrix (the "logical line table") would have a row
for each "logical" source statement. If the emitted object
code for a source statement has been cloned into two
different locations, there would be a separate row for each.
The code for a source statement in an inlined function would
have a separate row for each instance, and would refer to its
calling context -- i.e., the logical source statement within
which it was called. The matrix would have columns for:
* the source file name
* the source line number
* the source column number
* the function name
* recommended breakpoint location for this statement
* the calling context (a reference to another row)
* and so on
A second matrix (the "actual line table") would have a row
for each instruction in the emitted object code, and would
have columns for:
* the logical statement (a reference to a row in the first
* whether this instruction is the beginning of a basic
* and so on
Both of these matrices can be stored using the same byte-code
language mentioned above.
In Section 6.2.2 ("State Machine Registers"), add the following
rows to Table 6.2:
Register name Meaning
context An unsigned integer indicating a row number
in the logical line table that represents
the calling context for the current
logical statement. Rows are numbered
beginning at 1. The value 0 indicates that
the current logical statement is not part
of an inlined call.
function_name An unsigned integer representing the name
of the function containing the current
logical statement. This value is either a
string offset relative to the start of the
.debug_str section, or the index of an
entry in the .debug_str_offsets section,
depending on a flag in the line number
program header (see Section 6.2.4).
Following Table 6.2, add the following notes:
When only a single line number table is used, the context
register is not used.
When both a logical line table and an actual line table are
used, the basic_block and isa registers are not used in the
logical line table. The file, column, is_stmt, prologue_end,
epilogue_begin, discriminator, context, and function_name
registers are not used in the actual line table. In the
actual line table, the line register represents a row in the
logicals table rather than an actual line number. Rows in the
logical line table are numbered starting at 1.
Following Table 6.2, add the following rows to the (unnumbered)
table showing the state of the registers at the beginning of each
In Section 6.2.4 ("The Line Number Program Header"), modify
item 3, insert items 4 and 5, and renumber all subsequent items:
The number of bytes following the header_length field to
the first byte of the line number program for the logical
line table (or for the line number table is there is no
actuals table). In the 32-bit DWARF format, this field is
a 4-byte unsigned length; in the 64-bit DWARF format,
this field is an 8-byte unsigned length (see Section 7.4).
The offset in bytes from the end of the header to the
first byte of the line number program for the actual line
table. If there is only one line number table, this field
is 0. In the 32-bit DWARF format, this field is a 4-byte
unsigned length; in the 64-bit DWARF format, this field
is an 8-byte unsigned length (see Section 7.4).
5. function_name_form (ubyte)
The format of the function_name register. If this value
is DW_FORM_strp, the function_name register contains an
offset relative to the start of the .debug_str section.
If this value is DW_FORM_strx, the function_name
register contains an index of an entry in the
(In Section 126.96.36.199, "Special Opcodes", no change is necessary,
unless we want to explicitly point out that the new context and
function_name registers are left unchanged by the special
In Section 188.8.131.52 ("Standard Opcodes"), add the following new
The DW_LNS_inlined_call opcode takes two unsigned LEB128
operands. It sets the context register to the value of
the first operand, and the function_name register to the
value of the second operand.
This opcode may also be used to set the context register
to zero, to indicate that a logical statement is not part
of an inlined call.
In Section 184.108.40.206 ("Extended Opcodes"), add the following new
The DW_LNE_set_function_name opcode takes a single
unsigned LEB128 operand. It sets the function_name
register to the new value.
10/21/2014 - Deferred to DWARF Version 6