'\"#ident	"%W%"

'\" $Source: /plroot/cmplrs.src/v7.4.5m/.RCS/PL/libdwarf/RCS/dwarf.v2.mm,v $

'\"

'\" $Revision: 1.2 $

'\"

'\" DESCRIPTION

'\"

'\"	Requirements for 

'\"

'\" COMPILATION

'\"

'\"	pic file.mm | tbl | troff -mm

'\"

'\"	local mileage may vary

'\"

'\" AUTHOR

'\"

'\"	UNIX International Programming Languages SIG

'\"

'\" COPYRIGHT

'\"

'\"	Copyright (c) 1992,1993, UNIX International

'\"

'\"	Permission to use, copy, modify, and distribute this documentation for

'\"	any purpose and without fee is hereby granted, provided that the above

'\"	copyright notice appears in all copies and that both that copyright

'\"	notice and this permission notice appear in supporting documentation,

'\"	and that the name UNIX International not be used in advertising or

'\"	publicity pertaining to distribution of the software without specific,

'\"	written prior permission.  UNIX International makes no representations

'\"	about the suitability of this documentation for any purpose.  It is

'\"	provided "as is" without express or implied warranty.

'\"	

'\"	UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

'\"	DOCUMENTATION, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND

'\"	FITNESS.  IN NO EVENT SHALL UNIX INTERNATIONAL BE LIABLE FOR ANY

'\"	SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER

'\"	RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF

'\"	CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN

'\"	CONNECTION WITH THE USE OR PERFORMANCE OF THIS DOCUMENTATION.

'\"	

'\"	NOTICE:

'\"	

'\"	UNIX International is making this documentation available as a

'\"	reference point for the industry.  While UNIX International believes

'\"	that this specification is well defined in this first release of the

'\"	document, minor changes may be made prior to products meeting this

'\"	specification being made available from UNIX System Laboratories or 

'\"	UNIX International members.

'\"

'\" $Log$

'\" Revision 1.1  1994/05/18 18:50:42  davea

'\" Initial revision

'\"

'\"

'\"     Abbrevs for funny typeset words

.pl-0.25i

.ds aX U\s-2NIX\s+2

.ds iX \*(aX International

.ds uL \s-2AT&T\ USL\s+2

'\"

'\"  uI should be set to 1 if the publication and copyright page is needed.

.nr uI 1

'\"

'\"     Make the appropriate replacements in this section!

'\"

'\"     Set the ND date to the current date.

'\"     tT is the formal document title

'\"     tP is the name of the Project (if appropriate)

'\"     tD is the short document title

'\"     tE is the work group name (may be the same as the project name)

.ds tT DWARF Debugging Information Format 

.ds tP 

'\"             Document name (i.e., without project name)

.ds tD DWARF Debugging Information Format

.ds tE Programming Languages SIG

'\"

'\"     Define headers and footers macro

'\"

.ds fA Revision: 2.0.0

'\"

'\"     fB null to remove page numbers on cover page

.ds fB

.ds fC July 27, 1993

.ds fE Industry Review Draft

.ds fF \*(tD

.PH "''''"

.PF "''\*(fE''"

.tr ~

.SA 1

.S 10

.nr Ej 1

.nr Hs 5

.nr Hu 1

.nr Hb 5

.ds HP +2 +2 +1 +0 +0 +0 +0

.ds HF 3 3 3 3 3 1 1

.if n .ds HF 1 1 1 1 1 1 1 1

'\"

'\"     First page, print title and authors

'\"

.S +4

.DS C

\fB\*(tT

\s-2\*(tP\s+2\fP

.DE

.S

.sp 3i

\*(iX

.br

\*(tE

.br

\*(fA (\*(fC)

.SK

.if \n(uI\{ 

.DS C

.in -.25i

.B "Published by:"

.R

\*(iX

Waterview Corporate Center

20 Waterview Boulevard

Parsippany, NJ  07054

for further information, contact:

Vice President of Marketing

Phone:	+1 201-263-8400

Fax:	+1 201-263-8401

.DE

.P

Copyright \(co 1992, 1993 \*(iX, Inc.

.P

Permission to use, copy, modify, and distribute this

documentation for any purpose and without fee is hereby granted, provided

that the above copyright notice appears in all copies and that both that

copyright notice and this permission notice appear in supporting

documentation, and that the name \*(iX not be used in 

advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.  \*(iX makes

no representations about the suitability of this documentation for any 

purpose.  It is provided "as is" without express or implied warranty.

.P

UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, 

INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO 

EVENT SHALL UNIX INTERNATIONAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR 

CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF 

USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR 

OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 

PERFORMANCE OF THIS DOCUMENTATION.

.sp 2l

.if \n(uI\{

NOTICE:

.P

\*(iX is making this documentation available as a

reference point for the industry.  

While \*(iX believes that this specification is well

defined in this first release of the document,

minor changes may be made prior to products meeting this specification

being made available from \*(aX System Laboratories or \*(iX members.

.sp 1l \}

Trademarks:

.P

Intel386 is a trademark of Intel Corporation.

.br

\*(aX\(rg is a registered trademark of \*(aX System Laboratories 

in the United States and other countries.

.br

.OH "'''\s10\\\\*(tE\s0'"

.EH "'\s10\\\\*(tD\s0'''"

.SK

'\".VM 0 2

.PF "''\s10\\\\*(fE\s0''"

.OF "'\s10\\\\*(fA'\\\\*(fB'\\\\*(fC\s0'"

.EF "'\s10\\\\*(fA'\\\\*(fB'\\\\*(fC\s0'"

'\" -----------------------------------------------------------------------

'\".

'\"     Reset page numbers

'\"

.nr P 1

.nr % 1

'\"

'\"     Define headers and footers

'\"

.FH

'\"     Turn on the page numbering in the footers

.ds fB Page %

'\"

'\"     MACROEND

'\"

.if n .fp 2 R

.if n .fp 3 R

.tr ~  

\fR

.S 11

.SA 1

.tr ~

.OP

.ds | |

.ds ~ ~

.ds ' '

.if t .ds Cw \&\f(CW

.if n .ds Cw \fB

.de Cf		\" Place every other arg in Cw font, beginning with first

.if \\n(.$=1 \&\*(Cw\\$1\fP

.if \\n(.$=2 \&\*(Cw\\$1\fP\\$2

.if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP

.if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4

.if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP

.if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6

.if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP

.if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8

.if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\*(Cw

..

'\" macros used by index generating tool

.deIX

.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%

.el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9

..

.deix

.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%

.el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9

..

.ta .5i +.5i +.5i +.5i +.5i +.5i +.5i +.5i

.HU "FOREWORD"

This document specifies the second generation of symbolic debugging

information based on the DWARF format that 

has been developed by the \*(iX

Programming Languages Special Interest Group (SIG).

It is being circulated for industry review.  

The first version of the DWARF specification was published

by \*(iX in January, 1992.  The current version adds significant

new functionality, but its main thrust is to achieve a much

denser encoding of the DWARF information.  Because of the new

encoding, DWARF Version 2 is not binary compatible with

DWARF Version 1.

.P 

At this point, the SIG believes that this document sufficiently

supports the debugging needs of C, C++, FORTRAN 77, 

Fortran90, Modula2 and Pascal, and we have

released it for public comment.  We will accept comments on this

document until September 30, 1994.  Comments may be directed via email

to the SIG mailing list (plsig@ui.org).  If you are unable

to send email, paper mail, FAX, or machine readable copy 

on \*(aX, MS-DOS, or Macintosh compatible media can be 

sent to \*(iX at the address listed below, 

and will be forwarded to the SIG.

.SP

.SP

.SP

.in +20

UNIX International

.br

Waterview Corporate Center

.br

20 Waterview Boulevard

.br

Parsippany, NJ 07054

.br

Phone:	+1 201-263-8400

.br

Fax:	+1 201-263-8401

.br

.in -20

.nr H1 0

.OP

.H 1 "INTRODUCTION"

\fR

This document defines the format for the information generated by

compilers, assemblers and linkage editors that is necessary for symbolic,

source-level debugging.  The debugging information format does not favor the

design of any compiler or debugger.  Instead, the goal is to create a method of

communicating an accurate picture of the source program to any debugger in a

form that is economically extensible to different languages while retaining

backward compatibility.

.P

The design of the debugging information format is open-ended, allowing for the

addition of new debugging information to accommodate new languages or

debugger capabilities while remaining compatible with other languages or

different debuggers.

.H 2 "Purpose and Scope"

The debugging information format described in this document is designed to

meet the symbolic, source-level debugging needs of 

different languages in a unified fashion by

requiring language independent debugging information whenever possible.

.IX C++ %caa

.IX virtual functions

.IX Fortran

Individual needs, such as C++ virtual functions or Fortran common blocks are

accommodated by creating attributes that are used only for those

languages.  The \*(iX \*(tE believes 

that this document sufficiently covers the 

.IX languages

debugging information needs of C, C++, FORTRAN77, Fortran90, 

Modula2 and Pascal.

.IX C %c

.IX Modula2

.IX Pascal

.IX FORTRAN77

.IX Fortran90

.P

This document describes DWARF Version 2, the second generation of debugging

.IX Version 2

information based on the DWARF format.  While DWARF Version 2 provides

new debugging information not available in Version 1, the primary focus

of the changes for Version 2 is the representation of the information,

rather than the information content itself.  The basic structure of 

the Version 2 format remains as in Version 1: the debugging information

is represented as a series of debugging information entries, each containing

one or more attributes (name/value pairs). 

.IX debugging information entries

.IX attributes

The Version 2 representation, however,

is much more compact than the Version 1 representation.

.IX Version 1

In some cases, this greater density has been achieved at the expense

of additional complexity or greater difficulty in producing and processing

the DWARF information.  We believe that the reduction in I/O and in

memory paging should more than make up for any increase in processing time.

.P

Because the representation of information has changed from Version 1 to

Version 2, Version 2 DWARF information is not binary compatible

.IX compatibility

with Version 1 information.  To make it easier for consumers to

support both Version 1 and Version 2 DWARF information, the Version

2 information has been moved to a different object file section,

.Cf .debug_info .

.IX \f(CW.debug_info\fP %debugai

.P

The intended audience for this document are the developers of 

both producers and consumers of debugging information, typically

language compilers, debuggers and other tools that need to interpret

a binary program in terms of its original source.

.H 2 "Overview"

There are two major pieces to the description of the DWARF format in

this document.  The first piece is the informational content

of the debugging entries.  The second piece

is the way the debugging information is encoded and 

represented in an object file.

.P

The informational content is described in sections two

through six.

Section two describes the overall structure of

the information and attributes that are common to many or all of

the different debugging information entries.  

Sections three, four and five describe the specific debugging

information entries and how they communicate the

necessary information about the source program to a debugger.

Section six describes debugging information contained

outside of the debugging information entries, themselves.

The encoding of the DWARF information is

presented in section seven.

.P

Section eight describes some future directions for the DWARF

specification.

.P

In the following sections, text in normal font describes required aspects

of the DWARF format.  Text in \fIitalics\fP is explanatory or supplementary 

material, and not part of the format definition itself.

.H 2 "Vendor Extensibility"

.IX vendor extensions

This document does not attempt to cover all interesting languages or even

to cover all of the interesting debugging information needs for its primary

target languages (C, C++, FORTRAN77, Fortran90, Modula2, Pascal). 

Therefore the document provides

vendors a way to define their own debugging information tags, attributes,

base type encodings, location operations, language names,

calling conventions and call frame instructions

by reserving a portion of the name space and valid values 

for these constructs for vendor specific additions.  Future versions

of this document will not use names or values reserved for vendor specific

additions.  All names and values not reserved for vendor additions, however,

are reserved for future versions of this document.  See section 7 for

details.

.H 2 "Changes from Version 1"

The following is a list of the major changes made to the DWARF Debugging

Information Format since Version 1 of the format was published (January

.IX Version 1

20, 1992).  The list is not meant to be exhaustive.

.BL

.LI

Debugging information entries have been moved from the 

.Cf .debug

.IX \f(CW.debug\fP %debugaaa

to the 

.Cf .debug_info

.IX \f(CW.debug_info\fP %debugai

section of an object file.

.LI

.IX tags

.IX attributes, names

.IX attributes, forms

The tag, attribute names and attribute forms encodings have been moved

out of the debugging information itself to a separate abbreviations table.

.IX abbreviations table

.LI

Explicit sibling pointers have been made optional.  Each

.IX debugging information entries, siblings

entry now specifies (through the abbreviations table) whether

or not it has children.

.IX debugging information entries, child entries

.LI

New more compact attribute forms have been added, including a variable

length constant data form.  Attribute values may now have any 

.IX variable length data

.IX attributes, forms

.IX attributes, values

form within a given class of forms.

.LI

Location descriptions have been replaced by a new, more compact

and more expressive format.

.IX locations, descriptions

There is now a way of expressing multiple locations for an object

whose location changes during its lifetime.

.IX locations, lists

.LI

There is a new format for line number information

that provides information

for code contributed to a compilation unit from an included file.

Line number information is now in the 

.IX line number information

.Cf .debug_line

.IX \f(CW.debug_line\fP %debugali

section of an object file.

.LI

The representation of the type of a declaration has been

reworked.

.IX declarations, types of

.LI

A new section provides an encoding for pre-processor macro information.

.IX macro information

.IX pre-processor

.LI

Debugging information entries now provide for the representation

of non-defining declarations of objects, functions or types.

.IX declarations, non-defining

.LI

More complete support for Modula2 and Pascal has been added.

.LI

There is now a way of describing locations for segmented address spaces.

.IX segmented address space

.IX address space, segmented

.LI

A new section provides an encoding for information about call

frame activations.

.IX call frame information

.IX activations

.LI

The representation of enumeration and array types has been

.IX enumerations

.IX arrays

reworked so that DWARF presents only a single way of

representing lists of items.

.LI

Support has been added for C++ templates and exceptions.

.IX C++ %caa

.IX templates

.IX exceptions

.LE

.OP

.H 1 "GENERAL DESCRIPTION"

.H 2   "The Debugging Information Entry"

DWARF uses a series of debugging information entries to define a

.IX debugging information entries

low-level representation of a source program. Each debugging

information entry is described by an identifying tag and

contains a series of attributes. 

The tag specifies the class to which an entry

belongs, and the attributes define the specific characteristics

of the entry.

.P

.nr aX \n(Fg+1

The set of required tag names is listed in Figure \n(aX.

.IX tags

The debugging information entries they identify are described in sections three, four and five.

.P

The debugging information entries in DWARF Version 2 are intended

to exist in the 

.Cf .debug_info

section of an object file.

.IX \f(CW.debug_info\fP %debugai

.DF

.TS

center box;

lf(CW) lf(CW)

. 

DW_TAG_access_declaration	DW_TAG_array_type

DW_TAG_base_type	DW_TAG_catch_block

DW_TAG_class_type	DW_TAG_common_block

DW_TAG_common_inclusion	DW_TAG_compile_unit

DW_TAG_const_type	DW_TAG_constant

DW_TAG_entry_point	DW_TAG_enumeration_type

DW_TAG_enumerator	DW_TAG_file_type

DW_TAG_formal_parameter	DW_TAG_friend

DW_TAG_imported_declaration	DW_TAG_inheritance

DW_TAG_inlined_subroutine	DW_TAG_label

DW_TAG_lexical_block	DW_TAG_member

DW_TAG_module	DW_TAG_namelist

DW_TAG_namelist_item	DW_TAG_packed_type

DW_TAG_pointer_type	DW_TAG_ptr_to_member_type

DW_TAG_reference_type	DW_TAG_set_type

DW_TAG_string_type	DW_TAG_structure_type

DW_TAG_subprogram	DW_TAG_subrange_type

DW_TAG_subroutine_type	DW_TAG_template_type_param

DW_TAG_template_value_param	DW_TAG_thrown_type

DW_TAG_try_block	DW_TAG_typedef

DW_TAG_union_type	DW_TAG_unspecified_parameters

DW_TAG_variable	DW_TAG_variant

DW_TAG_variant_part	DW_TAG_volatile_type

DW_TAG_with_stmt

.TE

.FG "Tag names"

.DE

.H 2 "Attribute Types"

Each attribute value is characterized by an attribute name.

.IX attributes

.IX attributes, names

The set of attribute names is 

.nr aX \n(Fg+1

listed in Figure \n(aX.