1 '\"#ident	"%W%"

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

     3 '\"

     4 '\" $Revision: 1.2 $

     5 '\"

     6 '\" DESCRIPTION

     7 '\"

     8 '\"	Requirements for 

     9 '\"

    10 '\" COMPILATION

    11 '\"

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

    13 '\"

    14 '\"	local mileage may vary

    15 '\"

    16 '\" AUTHOR

    17 '\"

    18 '\"	UNIX International Programming Languages SIG

    19 '\"

    20 '\" COPYRIGHT

    21 '\"

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

    23 '\"

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

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

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

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

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

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

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

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

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

    33 '\"	

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

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

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

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

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

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

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

    41 '\"	

    42 '\"	NOTICE:

    43 '\"	

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

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

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

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

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

    49 '\"	UNIX International members.

    50 '\"

    51 '\" $Log$

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

    53 '\" Initial revision

    54 '\"

    55 '\"

    56 '\"     Abbrevs for funny typeset words

    57 .pl-0.25i

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

    59 .ds iX \*(aX International

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

    61 '\"

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

    63 .nr uI 1

    64 '\"

    65 '\"     Make the appropriate replacements in this section!

    66 '\"

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

    68 '\"     tT is the formal document title

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

    70 '\"     tD is the short document title

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

    72 .ds tT DWARF Debugging Information Format 

    73 .ds tP 

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

    75 .ds tD DWARF Debugging Information Format

    76 .ds tE Programming Languages SIG

    77 '\"

    78 '\"     Define headers and footers macro

    79 '\"

    80 .ds fA Revision: 2.0.0

    81 '\"

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

    83 .ds fB

    84 .ds fC July 27, 1993

    85 .ds fE Industry Review Draft

    86 .ds fF \*(tD

    87 .PH "''''"

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

    89 .tr ~

    90 .SA 1

    91 .S 10

    92 .nr Ej 1

    93 .nr Hs 5

    94 .nr Hu 1

    95 .nr Hb 5

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

    97 .ds HF 3 3 3 3 3 1 1

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

    99 '\"

   100 '\"     First page, print title and authors

   101 '\"

   102 .S +4

   103 .DS C

   104 

   105 

   106 

   107 

   108 

   109 

   110 \fB\*(tT

   111 

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

   113 

   114 .DE

   115 .S

   116 .sp 3i

   117 \*(iX

   118 .br

   119 \*(tE

   120 .br

   121 \*(fA (\*(fC)

   122 .SK

   123 .if \n(uI\{ 

   124 .DS C

   125 .in -.25i

   126 .B "Published by:"

   127 .R

   128 

   129 \*(iX

   130 Waterview Corporate Center

   131 20 Waterview Boulevard

   132 Parsippany, NJ  07054

   133 

   134 for further information, contact:

   135 Vice President of Marketing

   136 

   137 Phone:	+1 201-263-8400

   138 Fax:	+1 201-263-8401

   139 .DE

   140 .P

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

   142 .P

   143 Permission to use, copy, modify, and distribute this

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

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

   146 copyright notice and this permission notice appear in supporting

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

   148 advertising or publicity pertaining to distribution of the software 

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

   150 no representations about the suitability of this documentation for any 

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

   152 .P

   153 UNIX INTERNATIONAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION, 

   154 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO 

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

   156 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF 

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

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

   159 PERFORMANCE OF THIS DOCUMENTATION.

   160 .sp 2l

   161 .if \n(uI\{

   162 NOTICE:

   163 .P

   164 \*(iX is making this documentation available as a

   165 reference point for the industry.  

   166 While \*(iX believes that this specification is well

   167 defined in this first release of the document,

   168 minor changes may be made prior to products meeting this specification

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

   170 .sp 1l \}

   171 Trademarks:

   172 .P

   173 Intel386 is a trademark of Intel Corporation.

   174 .br

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

   176 in the United States and other countries.

   177 .br

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

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

   180 .SK

   181 '\".VM 0 2

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

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

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

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

   186 '\".

   187 '\"     Reset page numbers

   188 '\"

   189 .nr P 1

   190 .nr % 1

   191 '\"

   192 '\"     Define headers and footers

   193 '\"

   194 .FH

   195 '\"     Turn on the page numbering in the footers

   196 .ds fB Page %

   197 '\"

   198 '\"     MACROEND

   199 '\"

   200 .if n .fp 2 R

   201 .if n .fp 3 R

   202 .tr ~  

   203 \fR

   204 .S 11

   205 .SA 1

   206 .tr ~

   207 .OP

   208 .ds | |

   209 .ds ~ ~

   210 .ds ' '

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

   212 .if n .ds Cw \fB

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

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

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

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

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

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

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

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

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

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

   223 ..

   224 '\" macros used by index generating tool

   225 .deIX

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

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

   228 ..

   229 .deix

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

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

   232 ..

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

   234 .HU "FOREWORD"

   235 This document specifies the second generation of symbolic debugging

   236 information based on the DWARF format that 

   237 has been developed by the \*(iX

   238 Programming Languages Special Interest Group (SIG).

   239 It is being circulated for industry review.  

   240 The first version of the DWARF specification was published

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

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

   243 denser encoding of the DWARF information.  Because of the new

   244 encoding, DWARF Version 2 is not binary compatible with

   245 DWARF Version 1.

   246 .P 

   247 At this point, the SIG believes that this document sufficiently

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

   249 Fortran90, Modula2 and Pascal, and we have

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

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

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

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

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

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

   256 and will be forwarded to the SIG.

   257 .SP

   258 .SP

   259 .SP

   260 .in +20

   261 UNIX International

   262 .br

   263 Waterview Corporate Center

   264 .br

   265 20 Waterview Boulevard

   266 .br

   267 Parsippany, NJ 07054

   268 .br

   269 Phone:	+1 201-263-8400

   270 .br

   271 Fax:	+1 201-263-8401

   272 .br

   273 .in -20

   274 .nr H1 0

   275 .OP

   276 .H 1 "INTRODUCTION"

   277 \fR

   278 This document defines the format for the information generated by

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

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

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

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

   283 form that is economically extensible to different languages while retaining

   284 backward compatibility.

   285 .P

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

   287 addition of new debugging information to accommodate new languages or

   288 debugger capabilities while remaining compatible with other languages or

   289 different debuggers.

   290 .H 2 "Purpose and Scope"

   291 The debugging information format described in this document is designed to

   292 meet the symbolic, source-level debugging needs of 

   293 different languages in a unified fashion by

   294 requiring language independent debugging information whenever possible.

   295 .IX C++ %caa

   296 .IX virtual functions

   297 .IX Fortran

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

   299 accommodated by creating attributes that are used only for those

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

   301 that this document sufficiently covers the 

   302 .IX languages

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

   304 Modula2 and Pascal.

   305 .IX C %c

   306 .IX Modula2

   307 .IX Pascal

   308 .IX FORTRAN77

   309 .IX Fortran90

   310 .P

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

   312 .IX Version 2

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

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

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

   316 rather than the information content itself.  The basic structure of 

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

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

   319 one or more attributes (name/value pairs). 

   320 .IX debugging information entries

   321 .IX attributes

   322 The Version 2 representation, however,

   323 is much more compact than the Version 1 representation.

   324 .IX Version 1

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

   326 of additional complexity or greater difficulty in producing and processing

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

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

   329 .P

   330 Because the representation of information has changed from Version 1 to

   331 Version 2, Version 2 DWARF information is not binary compatible

   332 .IX compatibility

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

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

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

   336 .Cf .debug_info .

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

   338 .P

   339 The intended audience for this document are the developers of 

   340 both producers and consumers of debugging information, typically

   341 language compilers, debuggers and other tools that need to interpret

   342 a binary program in terms of its original source.

   343 .H 2 "Overview"

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

   345 this document.  The first piece is the informational content

   346 of the debugging entries.  The second piece

   347 is the way the debugging information is encoded and 

   348 represented in an object file.

   349 .P

   350 The informational content is described in sections two

   351 through six.

   352 Section two describes the overall structure of

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

   354 the different debugging information entries.  

   355 Sections three, four and five describe the specific debugging

   356 information entries and how they communicate the

   357 necessary information about the source program to a debugger.

   358 Section six describes debugging information contained

   359 outside of the debugging information entries, themselves.

   360 The encoding of the DWARF information is

   361 presented in section seven.

   362 .P

   363 Section eight describes some future directions for the DWARF

   364 specification.

   365 .P

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

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

   368 material, and not part of the format definition itself.

   369 .H 2 "Vendor Extensibility"

   370 .IX vendor extensions

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

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

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

   374 Therefore the document provides

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

   376 base type encodings, location operations, language names,

   377 calling conventions and call frame instructions

   378 by reserving a portion of the name space and valid values 

   379 for these constructs for vendor specific additions.  Future versions

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

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

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

   383 details.

   384 .H 2 "Changes from Version 1"

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

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

   387 .IX Version 1

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

   389 .BL

   390 .LI

   391 Debugging information entries have been moved from the 

   392 .Cf .debug

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

   394 to the 

   395 .Cf .debug_info

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

   397 section of an object file.

   398 .LI

   399 .IX tags

   400 .IX attributes, names

   401 .IX attributes, forms

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

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

   404 .IX abbreviations table

   405 .LI

   406 Explicit sibling pointers have been made optional.  Each

   407 .IX debugging information entries, siblings

   408 entry now specifies (through the abbreviations table) whether

   409 or not it has children.

   410 .IX debugging information entries, child entries

   411 .LI

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

   413 length constant data form.  Attribute values may now have any 

   414 .IX variable length data

   415 .IX attributes, forms

   416 .IX attributes, values

   417 form within a given class of forms.

   418 .LI

   419 Location descriptions have been replaced by a new, more compact

   420 and more expressive format.

   421 .IX locations, descriptions

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

   423 whose location changes during its lifetime.

   424 .IX locations, lists

   425 .LI

   426 There is a new format for line number information

   427 that provides information

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

   429 Line number information is now in the 

   430 .IX line number information

   431 .Cf .debug_line

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

   433 section of an object file.

   434 .LI

   435 The representation of the type of a declaration has been

   436 reworked.

   437 .IX declarations, types of

   438 .LI

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

   440 .IX macro information

   441 .IX pre-processor

   442 .LI

   443 Debugging information entries now provide for the representation

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

   445 .IX declarations, non-defining

   446 .LI

   447 More complete support for Modula2 and Pascal has been added.

   448 .LI

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

   450 .IX segmented address space

   451 .IX address space, segmented

   452 .LI

   453 A new section provides an encoding for information about call

   454 frame activations.

   455 .IX call frame information

   456 .IX activations

   457 .LI

   458 The representation of enumeration and array types has been

   459 .IX enumerations

   460 .IX arrays

   461 reworked so that DWARF presents only a single way of

   462 representing lists of items.

   463 .LI

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

   465 .IX C++ %caa

   466 .IX templates

   467 .IX exceptions

   468 .LE

   469 .OP

   470 .H 1 "GENERAL DESCRIPTION"

   471 .H 2   "The Debugging Information Entry"

   472 DWARF uses a series of debugging information entries to define a

   473 .IX debugging information entries

   474 low-level representation of a source program. Each debugging

   475 information entry is described by an identifying tag and

   476 contains a series of attributes. 

   477 The tag specifies the class to which an entry

   478 belongs, and the attributes define the specific characteristics

   479 of the entry.

   480 .P

   481 .nr aX \n(Fg+1

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

   483 .IX tags

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

   485 .P

   486 The debugging information entries in DWARF Version 2 are intended

   487 to exist in the 

   488 .Cf .debug_info

   489 section of an object file.

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

   491 .DF

   492 .TS

   493 center box;

   494 lf(CW) lf(CW)

   495 . 

   496 DW_TAG_access_declaration	DW_TAG_array_type

   497 DW_TAG_base_type	DW_TAG_catch_block

   498 DW_TAG_class_type	DW_TAG_common_block

   499 DW_TAG_common_inclusion	DW_TAG_compile_unit

   500 DW_TAG_const_type	DW_TAG_constant

   501 DW_TAG_entry_point	DW_TAG_enumeration_type

   502 DW_TAG_enumerator	DW_TAG_file_type

   503 DW_TAG_formal_parameter	DW_TAG_friend

   504 DW_TAG_imported_declaration	DW_TAG_inheritance

   505 DW_TAG_inlined_subroutine	DW_TAG_label

   506 DW_TAG_lexical_block	DW_TAG_member

   507 DW_TAG_module	DW_TAG_namelist

   508 DW_TAG_namelist_item	DW_TAG_packed_type

   509 DW_TAG_pointer_type	DW_TAG_ptr_to_member_type

   510 DW_TAG_reference_type	DW_TAG_set_type

   511 DW_TAG_string_type	DW_TAG_structure_type

   512 DW_TAG_subprogram	DW_TAG_subrange_type

   513 DW_TAG_subroutine_type	DW_TAG_template_type_param

   514 DW_TAG_template_value_param	DW_TAG_thrown_type

   515 DW_TAG_try_block	DW_TAG_typedef

   516 DW_TAG_union_type	DW_TAG_unspecified_parameters

   517 DW_TAG_variable	DW_TAG_variant

   518 DW_TAG_variant_part	DW_TAG_volatile_type

   519 DW_TAG_with_stmt

   520 .TE

   521 .FG "Tag names"

   522 .DE

   523 .H 2 "Attribute Types"

   524 Each attribute value is characterized by an attribute name.

   525 .IX attributes

   526 .IX attributes, names

   527 The set of attribute names is 

   528 .nr aX \n(Fg+1

   529 listed in Figure \n(aX.

   530 .DF

   531 .TS

   532 center box;

   533 lf(CW) lf(CW)

   534 . 

   535 DW_AT_abstract_origin	DW_AT_accessibility

   536 DW_AT_address_class	DW_AT_artificial

   537 DW_AT_base_types	DW_AT_bit_offset

   538 DW_AT_bit_size	DW_AT_byte_size

   539 DW_AT_calling_convention	DW_AT_common_reference

   540 DW_AT_comp_dir	DW_AT_const_value

   541 DW_AT_containing_type	DW_AT_count

   542 DW_AT_data_member_location	DW_AT_decl_column

   543 DW_AT_decl_file	DW_AT_decl_line

   544 DW_AT_declaration	DW_AT_default_value

   545 DW_AT_discr	DW_AT_discr_list

   546 DW_AT_discr_value	DW_AT_encoding

   547 DW_AT_external	DW_AT_frame_base

   548 DW_AT_friend	DW_AT_high_pc

   549 DW_AT_identifier_case	DW_AT_import

   550 DW_AT_inline	DW_AT_is_optional

   551 DW_AT_language	DW_AT_location

   552 DW_AT_low_pc	DW_AT_lower_bound

   553 DW_AT_macro_info	DW_AT_name

   554 DW_AT_namelist_item	DW_AT_ordering

   555 DW_AT_priority	DW_AT_producer

   556 DW_AT_prototyped	DW_AT_return_addr

   557 DW_AT_segment	DW_AT_sibling

   558 DW_AT_specification	DW_AT_start_scope

   559 DW_AT_static_link	DW_AT_stmt_list

   560 DW_AT_stride_size	DW_AT_string_length

   561 DW_AT_type	DW_AT_upper_bound

   562 DW_AT_use_location	DW_AT_variable_parameter

   563 DW_AT_virtuality	DW_AT_visibility

   564 DW_AT_vtable_elem_location

   565 .TE	

   566 .FG "Attribute names"

   567 .DE

   568 .P

   569 The permissible values for an attribute belong to one or more classes

   570 .IX attributes, values

   571 .IX attributes, forms

   572 of attribute value forms.  Each form class may be represented in one or more

   573 ways.  For instance, some attribute values consist of a single piece

   574 of constant data.  ``Constant data'' is the class of attribute value

   575 that those attributes may have.  There are several representations

   576 of constant data, however (one, two, four, eight bytes and variable

   577 length data).  The particular representation for any given instance

   578 of an attribute is encoded along with the attribute name as part

   579 of the information that guides the interpretation of a debugging

   580 information entry.   Attribute value forms may belong

   581 to one of the following classes.

   582 .VL 18

   583 .LI address

   584 .IX attributes, addresses

   585 Refers to some location in the address space of the described program.

   586 .LI block

   587 .IX attributes, blocks

   588 An arbitrary number of uninterpreted bytes of data.

   589 .LI constant

   590 .IX attributes, constants

   591 One, two, four or eight bytes of uninterpreted data, or data encoded

   592 in the variable length format known as LEB128 (see section 7.6).

   593 .IX variable length data

   594 .IX LEB128

   595 .LI flag

   596 .IX attributes, flags

   597 A small constant that indicates the presence or absence of an attribute.

   598 .LI reference

   599 .IX attributes, references

   600 Refers to some member of the set of debugging information entries that describe

   601 the program.  There are two types of reference.  The first is an

   602 offset relative to the beginning of the compilation unit in

   603 which the reference occurs and must refer to an entry within

   604 that same compilation unit.  The second type of reference

   605 is the address of any debugging information entry within

   606 the same executable or shared object; it may refer to an entry

   607 in a different compilation unit from the unit containing the

   608 reference.

   609 .LI string

   610 .IX attributes, strings

   611 A null-terminated sequence of zero or more (non-null) bytes.

   612 Data in this form are generally printable strings.  Strings

   613 may be represented directly in the debugging information entry

   614 or as an offset in a separate string table.

   615 .LE

   616 .P

   617 There are no limitations on the ordering of attributes within a debugging

   618 .IX attributes, ordering

   619 information entry, but to prevent ambiguity,

   620 no more than one attribute with a given name may appear in any debugging

   621 information entry.

   622 .H 2 "Relationship of Debugging Information Entries"

   623 .I

   624 A variety of needs can be met by permitting a single debugging

   625 information entry to ``own'' an arbitrary number of other debugging

   626 entries and by permitting the same debugging information entry to be

   627 one of many owned by another debugging information entry.

   628 This makes it possible to describe, for example,

   629 the static block structure within

   630 a source file, show the members of a structure, union, or class, and associate

   631 declarations with source files or source files with shared objects.

   632 .P

   633 .R

   634 The ownership relation

   635 of debugging information entries is achieved naturally

   636 .IX debugging information entries

   637 because the debugging information is represented as a tree.

   638 The nodes of the tree are the debugging information entries

   639 themselves.  The child entries of any node are exactly those

   640 .IX debugging information entries, child entries

   641 debugging information entries owned by that node.\*F

   642 .FS

   643 While the ownership relation of the debugging information

   644 entries is represented as a tree, other relations among

   645 the entries exist, for example, a pointer from an entry

   646 representing a variable to another entry representing

   647 the type of that variable.  If all such relations are

   648 taken into account, the debugging entries form a graph,

   649 not a tree.

   650 .FE

   651 .P

   652 The tree itself is represented by flattening it in prefix

   653 order.  Each debugging information entry

   654 is defined either to have child entries or not to have child entries

   655 (see section 7.5.3).

   656 If an entry is defined not to have children, the next physically

   657 succeeding entry is the sibling of the prior entry.  If an entry

   658 .IX debugging information entries, siblings

   659 is defined to have children, the next physically succeeding entry

   660 is the first child of the prior entry.  Additional children of the parent

   661 entry are represented as siblings of the first child.  A chain

   662 of sibling entries is terminated by a null entry.

   663 .IX debugging information entries, null entries

   664 .P

   665 In cases where a producer of debugging information

   666 feels that it will be important for consumers of that information

   667 to quickly scan chains of sibling entries, ignoring the children

   668 of individual siblings, that producer may attach an

   669 .Cf AT_sibling

   670 attribute to any debugging information entry.  The value of

   671 this attribute is a reference to the sibling entry of the

   672 entry to which the attribute is attached.

   673 .H 2 "Location Descriptions"

   674 .I

   675 The debugging information must provide consumers a way to find the location

   676 of program variables, determine the bounds of dynamic arrays and strings

   677 and possibly to find the base address of a subroutine's stack frame or

   678 the return address of a subroutine.  Furthermore, to meet the needs

   679 of recent computer architectures and optimization techniques, the debugging

   680 information must be able to describe the location of an object

   681 whose location changes over the object's lifetime.

   682 .P

   683 .R

   684 Information about the location of program objects is provided by

   685 location descriptions.  Location

   686 .IX locations, descriptions

   687 descriptions can be either of two forms: 

   688 .AL

   689 .LI

   690 \fILocation expressions\fP which are a language independent representation of 

   691 addressing rules

   692 .IX locations, expressions

   693 of arbitrary complexity built from a few basic

   694 building blocks, or \fIoperations\fP.  They are sufficient for describing

   695 the location of any object as long as its lifetime is either static

   696 or the same as the lexical block that owns it, and it does not move throughout 

   697 its lifetime.  

   698 .LI

   699 \fILocation lists\fP which are used to describe objects that 

   700 .IX locations, lists

   701 have a limited lifetime or change their location throughout their

   702 lifetime.  Location lists are more completely described below.

   703 .LE

   704 .P

   705 The two forms are distinguished in a context sensitive manner.  As the value

   706 of an attribute, a location expression is 

   707 encoded as a block and a location list is encoded as a constant offset into

   708 a location list table.

   709 .P

   710 .I

   711 Note: The Version 1 concept of "location descriptions" was replaced in Version 2 

   712 with this new abstraction because it is denser and more descriptive.  

   713 .IX Version 1

   714 .IX Version 2

   715 .R

   716 .H 3 "Location Expressions"

   717 A location expression consists of zero or more location operations.

   718 .IX locations, expressions

   719 An expression with zero operations 

   720 is used to denote an object that is

   721 present in the source code but not present in the object code

   722 (perhaps because of optimization).  

   723 .IX optimized code

   724 The location operations fall into two categories, register names and

   725 addressing operations.  Register names always appear alone and indicate

   726 that the referred object is contained inside a particular 

   727 register.  Addressing operations are memory address computation 

   728 rules.  All location operations are encoded as a stream of opcodes that

   729 are each followed by zero or more literal operands.  The number of operands

   730 is determined by the opcode.

   731 .H 3 "Register Name Operators"

   732 .IX locations, register name operators

   733 The following operations can be used to name a register.

   734 .P

   735 .I

   736 Note that the 

   737 register number represents a DWARF specific mapping of numbers onto

   738 the actual registers of a given architecture.

   739 The mapping should be chosen to gain optimal density and 

   740 should be shared by all users of a given architecture. 

   741 The \*(tE recommends

   742 that this mapping be defined by the ABI\*F

   743 .IX ABI

   744 .FS

   745 \fISystem V Application Binary Interface\fP, consisting of the generic

   746 interface and processor supplements for each target architecture.

   747 .FE

   748 authoring committee for each

   749 architecture.

   750 .R

   751 .AL

   752 .LI

   753 .Cf DW_OP_reg0 , " DW_OP_reg1" ", ..., " DW_OP_reg31

   754 .br

   755 The

   756 \f(CWDW_OP_reg\fP\fIn\fP

   757 operations encode the names of up to 32 registers, numbered from

   758 0 through 31, inclusive.  The object addressed is in register \fIn\fP.

   759 .LI

   760 .Cf DW_OP_regx

   761 .br

   762 The

   763 .Cf DW_OP_regx

   764 operation has a single unsigned LEB128 literal operand that encodes the 

   765 name of a register.

   766 .LE

   767 .H 3 "Addressing Operations"

   768 .IX locations, stack

   769 Each addressing operation represents a postfix operation on a simple stack 

   770 machine.  Each element of the stack is the size of an

   771 address on the target machine.

   772 The value on the top of the stack after

   773 ``executing'' the location expression is taken to be the result (the address

   774 of the object, or the value of the array bound, or the length of a

   775 dynamic string).  In the case of locations used for structure members, 

   776 .IX members, locations

   777 the computation assumes that the base address of the containing structure

   778 has been pushed on the stack before evaluation of the addressing operation.

   779 .R

   780 .H 4 "Literal Encodings"

   781 .IX locations, literal encodings

   782 The following operations all push a value onto the addressing stack.

   783 .AL

   784 .LI

   785 .Cf DW_OP_lit0 , " DW_OP_lit1" ", ..., " DW_OP_lit31

   786 .br

   787 The

   788 \f(CWDW_OP_lit\fP\fIn\fP operations encode the unsigned 

   789 literal values from 0 through 31, inclusive.

   790 .LI

   791 .Cf DW_OP_addr

   792 .br

   793 The

   794 .Cf DW_OP_addr

   795 operation has a single operand that encodes a

   796 machine address and whose size is the size of an address on the

   797 target machine.

   798 .LI

   799 .Cf DW_OP_const1u

   800 .br

   801 The single operand of the

   802 .Cf DW_OP_const1u

   803 operation provides a 1-byte unsigned integer constant.

   804 .LI

   805 .Cf DW_OP_const1s

   806 .br

   807 The single operand of the

   808 .Cf DW_OP_const1s

   809 operation provides a

   810 1-byte signed integer constant.

   811 .LI

   812 .Cf DW_OP_const2u

   813 .br

   814 The single operand of the

   815 .Cf DW_OP_const2u

   816 operation provides a

   817 2-byte unsigned integer constant.

   818 .LI

   819 .Cf DW_OP_const2s

   820 .br

   821 The single operand of the

   822 .Cf DW_OP_const2s

   823 operation provides a

   824 2-byte signed integer constant.

   825 .LI

   826 .Cf DW_OP_const4u

   827 .br

   828 The single operand of the

   829 .Cf DW_OP_const4u

   830 operation provides a

   831 4-byte unsigned integer constant.

   832 .LI

   833 .Cf DW_OP_const4s

   834 .br

   835 The single operand of the

   836 .Cf DW_OP_const4s

   837 operation provides a

   838 4-byte signed integer constant.

   839 .LI

   840 .Cf DW_OP_const8u

   841 .br

   842 The single operand of the

   843 .Cf DW_OP_const8u

   844 operation provides an

   845 8-byte unsigned integer constant.

   846 .LI

   847 .Cf DW_OP_const8s

   848 .br

   849 The single operand of the

   850 .Cf DW_OP_const8s

   851 operation provides an

   852 8-byte signed integer constant.

   853 .LI

   854 .Cf DW_OP_constu

   855 .br

   856 The single operand of the

   857 .Cf DW_OP_constu

   858 operation provides an

   859 unsigned LEB128 integer constant.

   860 .LI

   861 .Cf DW_OP_consts

   862 .br

   863 The single operand of the

   864 .Cf DW_OP_consts

   865 operation provides a

   866 signed LEB128 integer constant.

   867 .LE

   868 .H 4 "Register Based Addressing"

   869 .IX locations, register based addressing

   870 The following operations push a value onto the stack that 

   871 is the result of adding the contents of a register with 

   872 a given signed offset.  

   873 .AL

   874 .LI

   875 .Cf DW_OP_fbreg

   876 .br

   877 The

   878 \f(CWDW_OP_fbreg\fP

   879 operation provides a signed LEB128 offset from the address specified 

   880 by the location descriptor in the 

   881 .Cf DW_AT_frame_base 

   882 attribute of the current 

   883 .IX subroutines, frame base

   884 function.  \fI(This is typically a "stack pointer" register 

   885 plus or minus some

   886 offset.  On more sophisticated systems it might be a location list that

   887 adjusts the offset according to changes in the stack pointer as

   888 the PC changes.)\fP

   889 .LI

   890 .Cf DW_OP_breg0 , " DW_OP_breg1" ", ..., " DW_OP_breg31

   891 .br

   892 The single operand of the

   893 \f(CWDW_OP_breg\fP\fIn\fP

   894 operations provides a signed LEB128 offset from the specified register.

   895 .LI

   896 .Cf DW_OP_bregx

   897 .br

   898 The

   899 .Cf DW_OP_bregx

   900 operation has two operands:  a signed LEB128 offset from the specified register

   901 which is defined with an unsigned LEB128 number.

   902 .LE

   903 .H 4 "Stack Operations"

   904 .IX locations, stack

   905 The following operations 

   906 manipulate the ``location stack.''

   907 Location operations that index the location stack assume that

   908 the top of the stack (most recently added entry) has index 0.

   909 .AL

   910 .LI

   911 .Cf DW_OP_dup

   912 .br

   913 The

   914 .Cf DW_OP_dup 

   915 operation duplicates the value at the top of the location stack.

   916 .LI

   917 .Cf DW_OP_drop

   918 .br

   919 The

   920 .Cf DW_OP_drop 

   921 operation pops the value at the top of the stack.

   922 .LI

   923 .Cf DW_OP_pick

   924 .br

   925 The single operand of the

   926 .Cf DW_OP_pick

   927 operation provides a 1-byte index.  The stack entry with the specified index

   928 (0 through 255, inclusive) is pushed on the stack.

   929 .LI

   930 .Cf DW_OP_over

   931 .br

   932 The

   933 .Cf DW_OP_over

   934 operation duplicates the entry currently second in the stack

   935 at the top of the stack.  This is equivalent to an

   936 .Cf DW_OP_pick

   937 operation, with index 1.

   938 .LI

   939 .Cf DW_OP_swap

   940 .br

   941 The

   942 .Cf DW_OP_swap

   943 operation swaps the top two stack entries.   The entry at

   944 the top of the stack becomes the second stack entry, and

   945 the second entry becomes the top of the stack.

   946 .LI

   947 .Cf DW_OP_rot

   948 .br

   949 The

   950 .Cf DW_OP_rot

   951 operation rotates the first three stack entries.   The entry at

   952 the top of the stack becomes the third stack entry, the second entry

   953 becomes the top of the stack, and the third entry becomes the second

   954 entry.

   955 .LI

   956 .Cf DW_OP_deref

   957 .br

   958 The

   959 .Cf DW_OP_deref

   960 operation pops the top stack entry and treats it as an address.

   961 The value retrieved from that address is pushed.  The size of the

   962 data retrieved from the dereferenced address is the size of an address

   963 on the target machine.

   964 .LI

   965 .Cf DW_OP_deref_size

   966 .br

   967 The

   968 .Cf DW_OP_deref_size

   969 operation behaves like the 

   970 .Cf DW_OP_deref

   971 operation: it 

   972 pops the top stack entry and treats it as an address.

   973 The value retrieved from that address is pushed.  

   974 In the 

   975 .Cf DW_OP_deref_size

   976 operation, however,

   977 the size in bytes of the

   978 data retrieved from the dereferenced address is specified by the

   979 single operand.  This operand is a 1-byte unsigned integral constant

   980 whose value may not be larger than the size of an address on

   981 the target machine.  The data retrieved is zero extended to the size

   982 of an address on the target machine before being pushed on

   983 the expression stack.

   984 .LI

   985 .Cf DW_OP_xderef

   986 .br

   987 The

   988 .Cf DW_OP_xderef

   989 .IX address space, multiple

   990 operation provides an extended dereference mechanism.  The entry at the

   991 top of the stack is treated as an address.  The second stack entry

   992 is treated as an ``address space identifier'' for those architectures

   993 that support multiple address spaces.  The top two stack elements

   994 are popped, a data item is retrieved through an implementation-defined

   995 address calculation and pushed as the new stack top.  The size of the

   996 data retrieved from the dereferenced address is the size of an address

   997 on the target machine.

   998 .LI

   999 .Cf DW_OP_xderef_size

  1000 .br

  1001 The

  1002 .Cf DW_OP_xderef_size

  1003 operation behaves like the 

  1004 .Cf DW_OP_xderef

  1005 operation: the entry at the

  1006 top of the stack is treated as an address.  The second stack entry

  1007 is treated as an ``address space identifier'' for those architectures

  1008 that support multiple address spaces.  The top two stack elements

  1009 are popped, a data item is retrieved through an implementation-defined

  1010 address calculation and pushed as the new stack top.  

  1011 In the 

  1012 .Cf DW_OP_xderef_size

  1013 operation, however,

  1014 the size in bytes of the

  1015 data retrieved from the dereferenced address is specified by the

  1016 single operand.  This operand is a 1-byte unsigned integral constant

  1017 whose value may not be larger than the size of an address on

  1018 the target machine.  The data retrieved is zero extended to the size

  1019 of an address on the target machine before being pushed on

  1020 the expression stack.

  1021 .LE

  1022 .H 4 "Arithmetic and Logical Operations"

  1023 .IX locations, arithmetic operations

  1024 .IX locations, logical operations

  1025 The following provide arithmetic and logical operations.

  1026 The arithmetic operations perform ``addressing arithmetic,''

  1027 that is, unsigned arithmetic that wraps on an address-sized 

  1028 boundary.  The operations do not cause an exception on overflow.

  1029 .AL

  1030 .LI

  1031 .Cf DW_OP_abs

  1032 .br

  1033 The

  1034 .Cf DW_OP_abs

  1035 operation pops the top stack entry and pushes its absolute value.

  1036 .LI

  1037 .Cf DW_OP_and

  1038 .br

  1039 The

  1040 .Cf DW_OP_and

  1041 operation pops the top two stack values, performs a bitwise \fIand\fP 

  1042 operation on the two, and pushes the result.

  1043 .LI

  1044 .Cf DW_OP_div

  1045 .br

  1046 The

  1047 .Cf DW_OP_div

  1048 operation pops the top two stack values, divides the former second entry

  1049 by the former top of the stack 

  1050 using signed division, 

  1051 and pushes the result.

  1052 .LI

  1053 .Cf DW_OP_minus

  1054 .br

  1055 The

  1056 .Cf DW_OP_minus

  1057 operation pops the top two stack values, subtracts the former top of the stack

  1058 from the former second entry, and pushes the result.

  1059 .LI

  1060 .Cf DW_OP_mod

  1061 .br

  1062 The

  1063 .Cf DW_OP_mod

  1064 operation pops the top two stack values and pushes the result of the 

  1065 calculation: former second stack entry modulo the former top of the

  1066 stack.

  1067 .LI

  1068 .Cf DW_OP_mul

  1069 .br

  1070 The

  1071 .Cf DW_OP_mul

  1072 operation pops the top two stack entries, multiplies them together,

  1073 and pushes the result.

  1074 .LI

  1075 .Cf DW_OP_neg

  1076 .br

  1077 The

  1078 .Cf DW_OP_neg

  1079 operation pops the top stack entry, and pushes its negation.

  1080 .LI

  1081 .Cf DW_OP_not

  1082 .br

  1083 The

  1084 .Cf DW_OP_not

  1085 operation pops the top stack entry, and pushes its bitwise complement.

  1086 .LI

  1087 .Cf DW_OP_or

  1088 .br

  1089 The

  1090 .Cf DW_OP_or

  1091 operation pops the top two stack entries, performs a bitwise \fIor\fP 

  1092 operation on the two, and pushes the result.

  1093 .LI

  1094 .Cf DW_OP_plus

  1095 .br

  1096 The

  1097 .Cf DW_OP_plus

  1098 operation pops the top two stack entries, adds them together,

  1099 and pushes the result.

  1100 .LI

  1101 .Cf DW_OP_plus_uconst

  1102 .br

  1103 The

  1104 .Cf DW_OP_plus_uconst

  1105 operation pops the top stack entry, adds it to the unsigned LEB128

  1106 constant operand and pushes the result.

  1107 .I

  1108 This operation is supplied specifically to be able to encode more field

  1109 offsets in two bytes than can be done with "\f(CWDW_OP_lit\fP\fIn\fP\f(CW DW_OP_add\fP".

  1110 .R

  1111 .LI

  1112 .Cf DW_OP_shl

  1113 .br

  1114 The

  1115 .Cf DW_OP_shl

  1116 operation pops the top two stack entries, shifts the former second

  1117 entry left by the number of bits specified by the former top of

  1118 the stack, and pushes the result.

  1119 .LI

  1120 .Cf DW_OP_shr

  1121 .br

  1122 The

  1123 .Cf DW_OP_shr

  1124 operation pops the top two stack entries, shifts the former second

  1125 entry right (logically) by the number of bits specified by the former top of

  1126 the stack, and pushes the result.

  1127 .LI

  1128 .Cf DW_OP_shra

  1129 .br

  1130 The

  1131 .Cf DW_OP_shra

  1132 operation pops the top two stack entries, shifts the former second

  1133 entry right (arithmetically) by the number of bits specified by the former top of

  1134 the stack, and pushes the result.

  1135 .LI