Issue 090128.1: Line Number Table to Support Profiling

Author: Cary Coutant
Champion: Cary Coutant
Date submitted: 2009-01-28
Date revised:
Date closed:
Type: Enhancement
Status: Accepted with modifications
DWARF Version: 4
Background
----------

PC sampling is often used to profile the execution paths of an
application, and the sampled data needs to be fed back to the compiler
for profile-based opimization. In order to map the individual PC
samples to the original source code, the optimizer needs to use the
DWARF line number table. This approach works in general, but it is
currently unable to distinguish among multiple paths of execution on a
single source line.

In order to distinguish these additional paths of execution, we
propose to add an additional column to the DWARF line number table,
which will hold a "discriminator", a simple integer to discriminate
between the n different execution paths associated with a given line
of source code. The optimizer, when processing the profiling
information, will be able to use this extra column of information to
determine which basic block a given PC sample corresponds to.

Additional background material can be found on the DWARF wiki:
http://wiki.dwarfstd.org/index.php?title=Path_Discriminators


Proposed Changes to the DWARF Specification
-------------------------------------------

Page and section numbers are keyed to the June 24, 2008 Working Draft
of the DWARF Version 4 specification.

In Section 6.2.2, "State Machine Registers," on Page 100, add the
following new register, after "column":

  discriminator
     An unsigned integer identifying the basic block that
     the current instruction belongs to. Discriminator
     values are assigned arbitrarily by the DWARF producer
     and serve to distinguish among several basic blocks
     that may all be associated with the same source file,
     line, and column. Where only one basic block exists for
     a given source position, the discriminator value should
     be zero.

On page 101, add the following row to the table showing the initial
state of the registers at the beginning of each sequence, after
"column":

  discriminator    0

In Section 6.2.5.1, "Special Opcodes," on page 105, add the following step:

  7.  Set the discriminator register to 0.

Change "All of the special opcodes do those same six things" to "All
of the special opcodes do those same seven things".

In Section 6.2.5.2, "Standard Opcodes," on page 107, change the
description of DW_LNS_copy as follows:

  The DW_LNS_copy opcode takes no operands... Then it sets
  the discriminator register to 0, and sets the basic_block,
  prologue_end and epilogue_begin registers to "false."

In Section 6.2.5.3, "Extended Opcodes," on page 111, add the following
new extended opcode:

  4.  DW_LNE_set_discriminator

      The DW_LNE_set_discriminator opcode takes a single
      parameter, an unsigned LEB128 integer. It sets the
      discriminator register to the new value.

In Section 7.21, "Line Number Information," in Figure 38, on page 164,
add the following row:

  DW_LNE_set_discriminator     0x04

---
Accepted Feb. 3, 2009 with following changes: 
 - Replace "basic block" with "block" (basic block has a more 
   restrictive meaning)
 - Add non-normative text describing use