\."

\." the following line may be removed if the ff ligature works on your machine

.lg 0

\." set up heading formats

.ds HF 3 3 3 3 3 2 2

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

.nr Hs 5

.nr Hb 5

\." ==============================================

\." Put current date in the following at each rev

.ds vE rev 1.66, 04 July 2007

\." ==============================================

\." ==============================================

.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

..

.nr Cl 4

.SA 1

.TL

A Consumer Library Interface to DWARF 

.AF ""

.AU "David Anderson"

.PF "'\*(vE'- \\\\nP -''"

.AS 1

This document describes an interface to a library of functions

.FS 

UNIX is a registered trademark of UNIX System Laboratories, Inc.

in the United States and other countries.

.FE

to access DWARF debugging information entries and DWARF line number

information (and other DWARF2/3 information). 

It does not make recommendations as to how the functions

described in this document should be implemented nor does it

suggest possible optimizations. 

.P

The document is oriented to reading DWARF version 2 

and version 3.

There are certain sections which are SGI-specific (those

are clearly identified in the document).

.P

\*(vE

.AE

.MT 4

.H 1 "INTRODUCTION"

This document describes an interface to \fIlibdwarf\fP, a

library of functions to provide access to DWARF debugging information

records, DWARF line number information, DWARF address range and global 

names information, weak names information, DWARF frame description 

information, DWARF static function names, DWARF static variables, and 

DWARF type information.

.P

The document has long mentioned the  

"Unix International Programming Languages Special Interest Group" 

(PLSIG), under whose auspices the

DWARF committtee was formed around 1991.

"Unix International"  

was disbanded in the 1990's and no longer exists.

.P

The DWARF committee published DWARF2 July 27, 1993.

.P

In the mid 1990's this document and the library it describes

(which the committee never endorsed, having decided

not to endorse or approve any particular library interface)

was made available on the internet by Silcon Graphics, Inc.

.P

In 2005 the DWARF committee began an affiliation with FreeStandards.org.

In 2007 FreeStandards.org merged with The Linux Foundation.

The DWARF committee dropped its affiliation with FreeStandards.org

in 2007 and established the dwarfstd.org website.

See "http://www.dwarfstd.org" for current

information on standardization activities 

and a copy of the standard.

.H 2 "Copyright"

Copyright 1993-2006 Silicon Graphics, Inc.

Copyright 2007 David Anderson. 

Permission is hereby granted to 

copy or republish or use any or all of this document without

restriction except that when publishing more than a small amount

of the document

please acknowledge Silicon Graphics, Inc and David Anderson.

This document is distributed in the hope that it would be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

.P

.H 2 "Purpose and Scope"

The purpose of this document is to document a library of functions 

to access DWARF debugging information. There is no effort made in 

this document to address the creation of these records as those

issues are addressed separately 

(see "A Producer Library Interface to DWARF").

.P

Additionally, the focus of this document is the functional interface,

and as such, implementation as well as optimization issues are

intentionally ignored.

.H 2 "Document History"

.P

A document was written about 1991 which had similar

layout and interfaces. 

Written by people from Hal Corporation,

That document described a library for reading DWARF1.

The authors distributed paper copies to the committee

with the clearly expressed intent to propose the document as

a supported interface definition.

The committee decided not to pursue a library definition.

.P

SGI wrote the document you are now reading in 1993

with a similar layout and content and organization, but 

it was complete document rewrite with the intent to read DWARF2

(the DWARF version then in existence).

The intent was (and is) to also cover

future revisions of DWARF.

All the function interfaces were changed 

in 1994 to uniformly

return a simple integer success-code (see DW_DLV_OK etc), 

generally following

the recomendations in the chapter titled "Candy Machine Interfaces"

of "Writing Solid Code", a book by

Steve Maguire (published by Microsoft Press).

.H 2 "Definitions"

DWARF debugging information entries (DIEs) are the segments of information 

placed in the \f(CW.debug_*\fP sections by compilers, assemblers, and 

linkage editors that, in conjunction with line number entries, are 

necessary for symbolic source-level debugging.  

Refer to the latest

"\fIDWARF Debugging Information Format\fP" from www.dwarfstd.org for a more 

complete description of these entries.

.P

This document adopts all the terms and definitions in "\fIDWARF Debugging 

Information Format\fP" versions 2 and 3.  

It originally focused on the implementation at

Silicon Graphics, Inc., but now

attempts to be more generally useful.

.H 2 "Overview"

The remaining sections of this document describe the proposed interface

to \f(CWlibdwarf\fP, first by describing the purpose of additional types

defined by the interface, followed by descriptions of the available 

operations.  This document assumes you are thoroughly familiar with the 

information contained in the \fIDWARF Debugging Information Format\fP 

document. 

.P

We separate the functions into several categories to emphasize that not 

all consumers want to use all the functions.  We call the categories 

Debugger, Internal-level, High-level, and Miscellaneous not because one is more 

important than another but as a way of making the rather large set of 

function calls easier to understand.

.P

Unless otherwise specified, all functions and structures should be

taken as being designed for Debugger consumers.

.P

The Debugger Interface of this library is intended to be used by debuggers. 

The interface is low-level (close to dwarf) but suppresses irrelevant detail.

A debugger will want to absorb all of some sections at startup and will 

want to see little or nothing of some sections except at need.  And even 

then will probably want to absorb only the information in a single compilation 

unit at a time.  A debugger does not care about

implementation details of the library.

.P

The Internal-level Interface is for a DWARF prettyprinter and checker.  

A 

thorough prettyprinter will want to know all kinds of internal things 

(like actual FORM numbers and actual offsets) so it can check for 

appropriate structure in the DWARF data and print (on request) all 

that internal information for human users and libdwarf authors and 

compiler-writers.  

Calls in this interface provide data a debugger 

does not care about.

.P

The High-level Interface is for higher level access

(it's not really a high level interface!).  

Programs such as 

disassemblers will want to be able to display relevant information 

about functions and line numbers without having to invest too much 

effort in looking at DWARF.

.P

The miscellaneous interface is just what is left over: the error handler 

functions.

.P

The following is a brief mention of the changes in this libdwarf from 

the libdwarf draft for DWARF Version 1 and recent changes.

.H 2 "Items Changed"

.P

Added support for various DWARF3 features, but primarily

a new frame-information interface tailorable at run-time

to more than a single ABI.

See dwarf_set_frame_rule_inital_value() and dwarf_set_frame_rule_table_size().

See also dwarf_get_fde_info_for_reg3() and

dwarf_get_fde_info_for_cfa_reg3().  (April 2006)

.P

Added support for DWARF3 .debug_pubtypes section.

Corrected various leaks (revising dealloc() calls, adding

new functions) and corrected dwarf_formstring() documentation.

.P 

Added dwarf_srclines_dealloc() as the previous deallocation

method documented for data returned by

dwarf_srclines() was incapable of freeing

all the allocated storage (14 July 2005).

.P

dwarf_nextglob(), dwarf_globname(), and dwarf_globdie() were all changed 

to operate on the items in the .debug_pubnames section.

.P

All functions were modified to return solely an error code.

Data is returned through pointer arguments.

This makes writing safe and correct library-using-code far easier.

For justification for this approach, see the book by

Steve Maguire titled "Writing Solid Code" at your bookstore.

.H 2 "Items Removed"

.P

Dwarf_Type

was removed since types are no longer special.

.P

dwarf_typeof()

was removed since types are no longer special.

.P

Dwarf_Ellist

was removed since element lists no longer are a special format.

.P

Dwarf_Bounds

was removed since bounds have been generalized.

.P

dwarf_nextdie()

was replaced by dwarf_next_cu_header() to reflect the

real way DWARF is organized.

The dwarf_nextdie() was only useful for getting to compilation

unit beginnings, so it does not seem harmful to remove it in favor

of a more direct function.

.P

dwarf_childcnt() is removed on grounds

that no good use was apparent.

.P

dwarf_prevline() and dwarf_nextline() were removed on grounds this

is better left to a debugger to do.

Similarly, dwarf_dieline() was removed.

.P

dwarf_is1stline() was removed as it was not meaningful for the

revised DWARF line operations.

.P

Any libdwarf implementation might well decide to support all the

removed functionality and to retain the DWARF Version 1 meanings

of that functionality.  

This would be difficult because the

original libdwarf draft

specification used traditional C library interfaces which

confuse the values returned by successful calls with

exceptional conditions like failures and 'no more data' indications.

.H 2 "Revision History"

.VL 15

.LI "March 93"

Work on DWARF2 SGI draft begins

.LI "June 94"

The function returns are changed to return an error/success code

only.

.LI "April 2006:

Support for DWARF3 consumer operations is close to completion.

.LE

.H 1 "Types Definitions"

.H 2 "General Description"

The \fIlibdwarf.h\fP header file contains typedefs and preprocessor 

definitions of types and symbolic names used to reference objects 

of \fIlibdwarf\fP. The types defined by typedefs contained in 

\fIlibdwarf.h\fP all use the convention of adding \f(CWDwarf_\fP 

as a prefix and can be placed in three categories: 

.BL

.LI

Scalar types : The scalar types defined in \fIlibdwarf.h\fP are

defined primarily for notational convenience and identification.

Depending on the individual definition, they are interpreted as a 

value, a pointer, or as a flag.

.LI

Aggregate types : Some values can not be represented by a single 

scalar type; they must be represented by a collection of, or as a 

union of, scalar and/or aggregate types. 

.LI

Opaque types : The complete definition of these types is intentionally

omitted; their use is as handles for query operations, which will yield

either an instance of another opaque type to be used in another query, or 

an instance of a scalar or aggregate type, which is the actual result.

.P

.H 2 "Scalar Types"

The following are the defined by \fIlibdwarf.h\fP:

.DS

\f(CW

typedef int                Dwarf_Bool;

typedef unsigned long long Dwarf_Off;

typedef unsigned long long Dwarf_Unsigned;

typedef unsigned short     Dwarf_Half;

typedef unsigned char      Dwarf_Small;

typedef signed long long   Dwarf_Signed;

typedef unsigned long long Dwarf_Addr;

typedef void 		   *Dwarf_Ptr;

typedef void   (*Dwarf_Handler)(Dwarf_Error *error, Dwarf_Ptr errarg);

.DE

.nr aX \n(Fg+1

Dwarf_Ptr is an address for use by the host program calling the library,

not for representing pc-values/addresses within the target object file.

Dwarf_Addr is for pc-values within the target object file.  The sample 

scalar type assignments above are for a \fIlibdwarf.h\fP that can read 

and write

32-bit or 64-bit binaries on a 32-bit or 64-bit host machine.

The types must be  defined appropriately

for each implementation of libdwarf.

A description of these scalar types in the SGI/MIPS

environment is given in Figure \n(aX.

.DS

.TS

center box, tab(:);

lfB lfB lfB lfB

l c c l.

NAME:SIZE:ALIGNMENT:PURPOSE

_

Dwarf_Bool:4:4:Boolean states

Dwarf_Off:8:8:Unsigned file offset

Dwarf_Unsigned:8:8:Unsigned large integer

Dwarf_Half:2:2:Unsigned medium integer

Dwarf_Small:1:1:Unsigned small integer

Dwarf_Signed:8:8:Signed large integer

Dwarf_Addr:8:8:Program address

:::(target program)

Dwarf_Ptr:4|8:4|8:Dwarf section pointer 

:::(host program)

Dwarf_Handler:4|8:4|8:Pointer to

:::error handler function 

.TE

.FG "Scalar Types"

.DE

.H 2 "Aggregate Types"

The following aggregate types are defined by 

\fIlibdwarf.h\fP:

\f(CWDwarf_Loc\fP,

\f(CWDwarf_Locdesc\fP,

\f(CWDwarf_Block\fP, 

\f(CWDwarf_Frame_Op\fP. 

\f(CWDwarf_Regtable\fP. 

\f(CWDwarf_Regtable3\fP. 

While most of \f(CWlibdwarf\fP acts on or returns simple values or

opaque pointer types, this small set of structures seems useful.

.H 3 "Location Record"

The \f(CWDwarf_Loc\fP type identifies a single atom of a location description

or a location expression.

.DS

\f(CWtypedef struct {

        Dwarf_Small        lr_atom;

        Dwarf_Unsigned     lr_number;

        Dwarf_Unsigned     lr_number2;

        Dwarf_Unsigned     lr_offset;  

} Dwarf_Loc;\fP

.DE

The \f(CWlr_atom\fP identifies the atom corresponding to the \f(CWDW_OP_*\fP 

definition in \fIdwarf.h\fP and it represents the operation to be performed 

in order to locate the item in question.

.P

The \f(CWlr_number\fP field is the operand to be used in the calculation

specified by the \f(CWlr_atom\fP field; not all atoms use this field.

Some atom operations imply signed numbers so it is necessary to cast 

this to a \f(CWDwarf_Signed\fP type for those operations.

.P

The \f(CWlr_number2\fP field is the second operand specified by the 

\f(CWlr_atom\fP field; only \f(CWDW_OP_BREGX\fP has this field.  Some 

atom operations imply signed numbers so it may be necessary to cast 

this to a \f(CWDwarf_Signed\fP type for those operations.

.P

The \f(CWlr_offset\fP field is the byte offset (within the block the 

location record came from) of the atom specified by the \f(CWlr_atom\fP 

field.  This is set on all atoms.  This is useful for operations 

\f(CWDW_OP_SKIP\fP and \f(CWDW_OP_BRA\fP.

.H 3 "Location Description"

The \f(CWDwarf_Locdesc\fP type represents an ordered list of 

\f(CWDwarf_Loc\fP records used in the calculation to locate 

an item.  Note that in many cases, the location can only be 

calculated at runtime of the associated program.

.DS

\f(CWtypedef struct {

        Dwarf_Addr        ld_lopc;

        Dwarf_Addr        ld_hipc;

        Dwarf_Unsigned    ld_cents;

        Dwarf_Loc*        ld_s;

} Dwarf_Locdesc;\fP

.DE

The \f(CWld_lopc\fP and \f(CWld_hipc\fP fields provide an address range for

which this location descriptor is valid.  Both of these fields are set to

\fIzero\fP if the location descriptor is valid throughout the scope of the

item it is associated with.  These addresses are virtual memory addresses, 

not offsets-from-something.  The virtual memory addresses do not account 

for dso movement (none of the pc values from libdwarf do that, it is up to 

the consumer to do that).

.P

The \f(CWld_cents\fP field contains a count of the number of \f(CWDwarf_Loc\fP 

entries pointed to by the \f(CWld_s\fP field.

.P

The \f(CWld_s\fP field points to an array of \f(CWDwarf_Loc\fP records. 

.H 3 "Data Block"

.SP

The \f(CWDwarf_Block\fP type is used to contain the value of an attribute

whose form is either \f(CWDW_FORM_block1\fP, \f(CWDW_FORM_block2\fP, 

\f(CWDW_FORM_block4\fP, \f(CWDW_FORM_block8\fP, or \f(CWDW_FORM_block\fP.

Its intended use is to deliver the value for an attribute of any of these 

forms.

.DS

\f(CWtypedef struct {

        Dwarf_Unsigned     bl_len;

        Dwarf_Ptr          bl_data;

} Dwarf_Block;\fP

.DE

.P

The \f(CWbl_len\fP field contains the length in bytes of the data pointed

to by the \f(CWbl_data\fP field. 

.P

The \f(CWbl_data\fP field contains a pointer to the uninterpreted data.

Since we use  a \f(CWDwarf_Ptr\fP here one must copy the pointer to some 

other type (typically an \f(CWunsigned char *\fP) so one can add increments 

to index through the data.  The data pointed to by \f(CWbl_data\fP is not 

necessarily at any useful alignment.

.H 3 "Frame Operation Codes: DWARF 2"

This interface is adequate for DWARF2 but not for DWARF3.

A separate interface usable for DWARF3 and for DWARF2 is described below.

.P

The DWARF2 \f(CWDwarf_Frame_Op\fP type is used to contain the data of a single

instruction of an instruction-sequence of low-level information from the 

section containing frame information.  This is ordinarily used by 

Internal-level Consumers trying to print everything in detail.

.DS

\f(CWtypedef struct {

	Dwarf_Small  fp_base_op;

	Dwarf_Small  fp_extended_op;

	Dwarf_Half   fp_register;

	Dwarf_Signed fp_offset;

	Dwarf_Offset fp_instr_offset;

} Dwarf_Frame_Op;

.DE

\f(CWfp_base_op\fP is the 2-bit basic op code.  \f(CWfp_extended_op\fP is 

the 6-bit extended opcode (if \f(CWfp_base_op\fP indicated there was an 

extended op code) and is zero otherwise.

.P

\f(CWfp_register\fP 

is any (or the first) register value as defined

in the \f(CWCall Frame Instruction Encodings\fP figure

in the \f(CWdwarf\fP document.

If not used with the Op it is 0.

.P

\f(CWfp_offset\fP

is the address, delta, offset, or second register as defined

in the \f(CWCall Frame Instruction Encodings\fP figure

in the \f(CWdwarf\fP document.

If this is an \f(CWaddress\fP then the value should be cast to

\f(CW(Dwarf_Addr)\fP before being used.

In any implementation this field *must* be as large as the

larger of Dwarf_Signed and Dwarf_Addr for this to work properly.

If not used with the op it is 0.

.P

\f(CWfp_instr_offset\fP is the byte_offset (within the instruction

stream of the frame instructions) of this operation.  It starts at 0

for a given frame descriptor.

.H 3 "Frame Regtable: DWARF 2"

This interface is adequate for DWARF2 but not for DWARF3.

A separate interface usable for DWARF3 and for DWARF2 is described below.

.P

The \f(CWDwarf_Regtable\fP type is used to contain the 

register-restore information for all registers at a given

PC value.

Normally used by debuggers.

.DS

/* DW_REG_TABLE_SIZE must reflect the number of registers

 *(DW_FRAME_LAST_REG_NUM) as defined in dwarf.h

 */

#define DW_REG_TABLE_SIZE  <fill in size here, 66 for MIPS/IRIX>

\f(CWtypedef struct {

    struct {

        Dwarf_Small         dw_offset_relevant;

        Dwarf_Half          dw_regnum;

        Dwarf_Addr          dw_offset;

    }                       rules[DW_REG_TABLE_SIZE];

} Dwarf_Regtable;\fP

.DE

.P

The array is indexed by register number.