DWARF program information

The DWARF program information is block-structured for compatibility with the C/C++ (and other) language structures. DWARF does not duplicate information, such as the processor architecture, that is contained in the executable object.

The basic descriptive entity in a DWARF file is the debugging information entry (DIE). DIEs can describe data types, variables, or functions, as well as other executable code blocks. A line table maps the executable instructions to the source that generated them.

The primary data types, built directly on the hardware, are the base types. DWARF base types provide the lowest level mapping between the simple data types and how they are implemented on the target machine's hardware. Other data types are constructed as collections or compositions of these base types.

A DWARF file is structured as follows:
  • Each DWARF file is divided into debug sections.
  • Each debug section provides information for a single compilation unit (CU) and contains one or more DIE sections.
  • Each DIE section is identified with a unit header, which specifies the offset of the DIE section, and contains one or more DIEs.
  • Each DIE has:
    • A tag that identifies the DIE. Each tag name has the DW_TAG prefix.
    • A section offset, which shows the relative position of the DIE within the DIE section.
    • A list of attributes, which fills in details and further describes the entity. Each attribute name has the DW_AT prefix.

      A DIE can have zero or more unique attributes. Each attribute must be unique to the DIE. In other words, a DIE cannot have two attributes of the same type but a DIE attribute type can be present in more than one DIE.

    • Zero or more children DIEs.

      Each descriptive entity in DWARF (except for the topmost entry which describes the source file) is contained within a parent entry and may contain child entities. If a DIE section contains multiple entities, all are siblings.

    • Nested-level indicators, which identify the parent/child relationship of the DIEs in the DIE section.

For detailed information about the DWARF format, see DWARF Debugging Standard.

Example of a DWARF file

The example of a DWARF file is based on the output from the dwarfdump example program, and does not reflect an actual DWARF file that you might see in a normal program.

The example shows one debug section with one DIE section, which has two DIEs. 

.debug_section_name                         1
<unit header offset =0>unit_hdr_off:        2
<0><   11>      DW_TAG_DIE01                3
                DW_AT_01          value00   4

<1><   20>      DW_TAG_DIE02                5
                DW_AT_01          value01   6
                DW_AT_02          value02   
                DW_AT_03          value03
Notes:
  1. The name of each DWARF debug section starts with .debug.
  2. The start of each DIE section is indicated by a line such as 
    <unit header offset =0>unit_hdr_off:
    The unit header offset indicates the relative location of the DIE sections within the DWARF debug section.
  3. The start of the parent DIE is indicated by the line:<0>< 11> DW_TAG_DIE01, where:
    • <0> is the nested-level indicator that identifies the DIE as the parent of all DIEs in the DIE section with a nested-level indicator of <1>.
    • <11> is the section offset.
    • DW_TAG_DIE01 is the DIE tag.
  4. In the parent DIE, the attribute DW_AT_01 is defined with value00. DW_AT_01 is also used in DW_TAG_DIE02.
  5. The start of the child DIE is indicated by the line:<1>< 20> DW_TAG_DIE02, where:
    • <1> is the nested-level indicator that identifies DW_TAG_DIE01 as a child of DW_TAG_DIE01.
    • <20> is the section offset.
    • DW_TAG_DIE02 is the DIE tag.
  6. In the child DIE, the attribute DW_AT_01 is defined with value01. DW_AT_01 is also used in DW_TAG_DIE01.