\." $Revision: 1.12 $

\." $Date: 2002/01/14 23:40:11 $

\."

\."

\." 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.20, 4 Sep 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 3

.SA 1

.TL

A Producer Library Interface to DWARF

.AF ""

.AU "David Anderson"

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

.AS 1

This document describes an interface to a library of functions

to create DWARF debugging information entries and DWARF line number

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 creating DWARF version 2.

Support for creating DWARF3 is intended but such support

is not yet fully present.

.P

\*(vE 

.AE

.MT 4

.H 1 "INTRODUCTION"

This document describes an interface to \f(CWlibdwarf\fP, a

library of functions to provide creation of DWARF debugging information

records, DWARF line number information, DWARF address range and

pubnames information, weak names information, and DWARF frame description 

information.

.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.

.H 2 "Purpose and Scope"

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

create DWARF debugging information.  Reading (consuming) of such records 

is discussed in a separate document.

The functions in this document have mostly been implemented at 

Silicon Graphics

and are being used by the code generator to provide debugging information.

Some functions (and support for some extensions) were provided

by Sun Microsystems.

.P

The focus of this document is the functional interface,

and as such, implementation and optimization issues are

intentionally ignored.

.P

Error handling, error codes, and certain \f(CWLibdwarf\fP codes are discussed

in the "\fIA Consumer Library Interface to DWARF\fP", which should 

be read (or at least skimmed) before reading this document.

.P

However the general style of functions here 

in the producer librar is rather C-traditional

with various types as return values (quite different

from the consumer library interfaces).   The style

generally follows the style of the original DWARF1 reader

proposed as an interface to DWARF.

When the style of the reader interfaces was changed (1994) in the

dwarf reader ( See the "Document History"

section of "A Consumer Library Interface to DWARF")

the interfaces here were not changed as it seemed like

too much of a change for the two applications then using

the interface!  So this interface remains in the traditional C style

of returning various data types with various (somewhat inconsistent)

means of indicating failure.

.H 2 "Document History"

This document originally prominently referenced

"UNIX International Programming Languages Special Interest Group " 

(PLSIG).

Both  UNIX International and the

affiliated  Programming Languages Special Interest Group

are defunct

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

in the United States and other countries).

Nothing except the general interface style is actually

related to anything shown to the PLSIG

(this document was open sourced with libdwarf in the mid 1990's).

.P

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

DWARF standards and committee activities.

.H 2 "Definitions"

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

placed in the \f(CW.debug_info\fP  and related

sections by compilers, assemblers, and linkage 

editors that, in conjunction with line number entries, are necessary for 

symbolic source-level debugging.  

Refer to the document 

"\fIDWARF Debugging Information Format\fP" from UI PLSIG for a more complete 

description of these entries.

.P

This document adopts all the terms and definitions in

"\fIDWARF Debugging Information Format\fP" version 2.

and the "\fIA Consumer Library Interface to DWARF\fP".

.P

In addition, this document refers to Elf, the ATT/USL System V

Release 4 object format.

This is because the library was first developed for that object

format.

Hopefully the functions defined here can easily be

applied to other object formats.

.H 2 "Overview"

The remaining sections of this document describe a proposed producer 

(compiler or assembler) interface to \fILibdwarf\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, and 

"\fIA Consumer Library Interface to DWARF\fP".

.P

The interface necessarily knows a little bit about the object format

(which is assumed to be Elf).  We make an attempt to make this knowledge 

as limited as possible.  For example, \fILibdwarf\fP does not do the 

writing of object data to the disk.  The producer program does that.

.H 2 "Revision History"

.VL 15

.LI "March 1993"

Work on dwarf2 sgi producer draft begins

.LI "March 1999"

Adding a function to allow any number of trips

thru the dwarf_get_section_bytes() call.

.LI "April 10 1999"

Added support for assembler text output of dwarf

(as when the output must pass thru an assembler).

Revamped internals for better performance and

simpler provision for differences in ABI.

.LI "Sep 1, 1999"

Added support for little- and cross- endian

debug info creation.

.LI "May 7  2007"

This library interface now cleans up, deallocating

all memory it uses (the application simply calls

dwarf_producer_finish(dbg)).

.LE

.H 1 "Type 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 \fI Libdwarf \fP .  

The types defined by typedefs contained in \fI libdwarf.h\fP 

all use the convention of adding \fI Dwarf_ \fP 

as a prefix to

indicate that they refer to objects used by Libdwarf.  

The prefix \fI Dwarf_P_\fP is used for objects 

referenced by the \fI Libdwarf\fP 

Producer when there are similar but distinct 

objects used by the Consumer.

.H 2 "Namespace issues"

Application programs should avoid creating names

beginning with 

\f(CWDwarf_\fP

\f(CWdwarf_\fP

or 

\f(CWDW_\fP

as these are reserved to dwarf and libdwarf.

.H 1 "libdwarf and Elf and relocations"

Much of the description below presumes that Elf is the object

format in use.

The library is probably usable with other object formats

that allow arbitrary sections to be created.

.H 2 "binary or assembler output"

With 

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

(see below)

it is assumed that the calling app will simply

write the streams and relocations directly into

an Elf file, without going thru an assembler.

With 

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP 

the calling app must either 

A) generate binary relocation streams and write

the generated debug information streams and

the relocation streams direct to an elf file

or

B) generate assembler output text for an assembler

to read and produce an object file. 

With case B) the libdwarf-calling application must

use the relocation information to change

points of each binary stream into references to 

symbolic names.  

It is necessary for the assembler to be

willing to accept and generate relocations

for references from arbitrary byte boundaries.

For example:

.sp

.nf

.in +4

 .data 0a0bcc    #producing 3 bytes of data.

 .word mylabel   #producing a reference

 .word endlabel - startlable #producing absolute length

.in -4

.fi

.sp

.H 2 "libdwarf relationship to Elf"

When the documentation below refers to 'an elf section number'

it is really only dependent on getting (via the callback

function passed by the caller of

\f(CWdwarf_producer_init()\fP)

a sequence of integers back (with 1 as the lowest).

When the documentation below refers to 'an Elf symbol index'

it is really dependent on 

Elf symbol numbers

only if

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

are being generated (see below).

With 

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

the library is generating Elf relocations

and the section numbers in binary form so

the section numbers and symbol indices must really 

be Elf (or elf-like) numbers.

With

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP 

the values passed as symbol indexes can be any

integer set or even pointer set.

All that libdwarf assumes is that where values

are unique they get unique values.

Libdwarf does not generate any kind of symbol table

from the numbers and does not check their

uniqueness or lack thereof.

.H 2 "libdwarf and relocations"

With

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP 

libdwarf creates binary streams of debug information

and arrays of relocation information describing

the necessary relocation.

The Elf section numbers and symbol numbers appear

nowhere in the binary streams. Such appear

only in the relocation information and the passed-back

information from calls requesting the relocation information.

As a consequence, the 'symbol indices' can be

any pointer or integer value as the caller must

arrange that the output deal with relocations.

With 

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

all the relocations are directly created by libdwarf

as binary streams (libdwarf only creates the streams

in memory,

it does not write them to disk).

.H 2 "symbols, addresses, and offsets"

The following applies to calls that

pass in symbol indices, addresses, and offsets, such

as

\f(CWdwarf_add_AT_targ_address() \fP 

\f(CWdwarf_add_arange_b()\fP 

and

\f(CWdwarf_add_frame_fde_b()\fP.

With 

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

a passed in address is one of:

a) a section offset and the (non-global) symbol index of

a section symbol.

b) A symbol index (global symbol) and a zero offset.

With \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP

the same approach can be used, or, instead,

a passed in address may be

c) a symbol handle and an offset.

In this case, since it is up to the calling app to

generate binary relocations (if appropriate)

or to turn the binary stream into 

a text stream (for input to an assembler, if appropriate)

the application has complete control of the interpretation

of the symbol handles.

.H 1 "Memory Management"

Several of the functions that comprise the \fILibdwarf\fP 

producer interface dynamically allocate values and some

return pointers to those spaces.

The dynamically allocated spaces 

can not be reclaimed  (and must

not be freed)  except by \f(CWdwarf_producer_finish(dbg)\fP.  

All data for a particular \f(CWDwarf_P_Debug\fP descriptor

is separate from the data for any other 

\f(CWDwarf_P_Debug\fP descriptor in use in the library-calling

application.

.H 2 "Read-only Properties"

All pointers returned by or as a result of a \fILibdwarf\fP call should 

be assumed to point to read-only memory.  

Except as defined by this document, the results are undefined for 

\fILibdwarf\fP clients that attempt to write to a region pointed to by a 

return value from a \fILibdwarf\fP call.

.H 2 "Storage Deallocation"

Calling \f(CWdwarf_producer_finish(dbg)\fP frees all the space, and 

invalidates all pointers returned from \f(CWLibdwarf\fP functions on 

or descended from \f(CWdbg\fP).

.H 1 "Functional Interface"

This section describes the functions available in the \fILibdwarf\fP

library.  Each function description includes its definition, followed 

by a paragraph describing the function's operation.

.P

The functions may be categorized into groups: 

\fIinitialization and termination operations\fP,

\fIdebugging information entry creation\fP,

\fIElf section callback function\fP,

\fIattribute creation\fP,

\fIexpression creation\fP, 

\fIline number creation\fP, 

\fIfast-access (aranges) creation\fP, 

\fIfast-access (pubnames) creation\fP, 

\fIfast-access (weak names) creation\fP,

\fImacro information creation\fP, 

\fIlow level (.debug_frame) creation\fP, 

and

\fIlocation list (.debug_loc) creation\fP. 

.P

The following sections describe these functions.

.H 2 "Initialization and Termination Operations"

These functions setup \f(CWLibdwarf\fP to accumulate debugging information

for an object, usually a compilation-unit, provided by the producer.

The actual addition of information is done by functions in the other

sections of this document.  Once all the information has been added,

functions from this section are used to transform the information to

appropriate byte streams, and help to write out the byte streams to

disk.

Typically then, a producer application 

would create a \f(CWDwarf_P_Debug\fP 

descriptor to gather debugging information for a particular

compilation-unit using \f(CWdwarf_producer_init()\fP.  

The producer application would 

use this \f(CWDwarf_P_Debug\fP descriptor to accumulate debugging 

information for this object using functions from other sections of 

this document.  

Once all the information had been added, it would 

call \f(CWdwarf_transform_to_disk_form()\fP to convert the accumulated 

information into byte streams in accordance with the \f(CWDWARF\fP 

standard.  

The application would then repeatedly call 

\f(CWdwarf_get_section_bytes()\fP 

for each of the \f(CW.debug_*\fP created.  

This gives the producer 

information about the data bytes to be written to disk.  

At this point, 

the producer would release all resource used by \f(CWLibdwarf\fP for 

this object by calling \f(CWdwarf_producer_finish()\fP.

It is also possible to create assembler-input character streams

from the byte streams created by this library.

This feature requires slightly different interfaces than

direct binary output.

The details are mentioned in the text.

.H 3 "dwarf_producer_init()"

.DS

\f(CWDwarf_P_Debug dwarf_producer_init(

        Dwarf_Unsigned flags,

        Dwarf_Callback_Func func,

        Dwarf_Handler errhand,

        Dwarf_Ptr errarg,

        Dwarf_Error *error) \fP

.DE

The function \f(CWdwarf_producer_init() \fP returns a new 

\f(CWDwarf_P_Debug\fP descriptor that can be used to add \f(CWDwarf\fP 

information to the object.  

On error it returns \f(CWDW_DLV_BADADDR\fP.  

\f(CWflags\fP determine whether the target object is 64-bit or 32-bit.  

\f(CWfunc\fP is a pointer to a function called-back from \f(CWLibdwarf\fP 

whenever \f(CWLibdwarf\fP needs to create a new object section (as it will 

for each .debug_* section and related relocation section).  

\f(CWerrhand\fP 

is a pointer to a function that will be used for handling errors detected 

by \f(CWLibdwarf\fP.  \f(CWerrarg\fP is the default error argument used 

by the function pointed to by \f(CWerrhand\fP.

.P

The \f(CWflags\fP

values are as follows:

.in +4

\f(CWDW_DLC_WRITE\fP 

is required.

The values

\f(CWDW_DLC_READ\fP  

\f(CWDW_DLC_RDWR\fP

are not supported by the producer and must not be passed.

If 

\f(CWDW_DLC_SIZE_64\fP

is not OR'd into \f(CWflags\fP

then

\f(CWDW_DLC_SIZE_32\fP

is assumed.

Oring in both is an error.

If

\f(CWDW_DLC_ISA_IA64\fP

is not OR'd into \f(CWflags\fP

then 

\f(CWDW_DLC_ISA_MIPS\fP

is assumed.

Oring in both is an error.

If

\f(CWDW_DLC_TARGET_BIGENDIAN\fP

is not OR'd into \f(CWflags\fP

then 

endianness the same as the host is assumed.

If

\f(CWDW_DLC_TARGET_LITTLEENDIAN\fP

is not OR'd into \f(CWflags\fP

then 

endianness the same as the host is assumed.

If both 

\f(CWDW_DLC_TARGET_LITTLEENDIAN\fP

and

\f(CWDW_DLC_TARGET_BIGENDIAN\fP

are or-d in it is an error.

Either one of two output forms is specifiable:

\f(CWDW_DLC_STREAM_RELOCATIONS\fP 

or

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP .

The default is

\f(CWDW_DLC_STREAM_RELOCATIONS\fP . 

The

\f(CWDW_DLC_STREAM_RELOCATIONS\fP

are relocations in a binary stream (as used

in a MIPS Elf object).

The

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP

are the same relocations but expressed in an

array of structures defined by libdwarf,

which the caller of the relevant function

(see below) must deal with appropriately.

This method of expressing relocations allows 

the producer-application to easily produce

assembler text output of debugging information.

If

\f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP

is OR'd into \f(CWflags\fP

then relocations are returned not as streams

but thru an array of structures.

.in -4

.P

The function \f(CWfunc\fP 

must be provided by the user of this library.