To build libdwarf.a, type

        ./configure

        make

To use dwarf or libdwarf, you may want to install dwarf.h and

libdwarf.h somewhere convenient, and you may need the libdwarf

in the accompanying libdwarf directory

Multi Threading, or using threads with libdwarf (Thread Safety):

  Nothing in libdwarf does any locking.  Every Dwarf_Debug

  (such as returned by dwarf_init()) is fully independent

  of all other Dwarf_Debug-s.  However, calls to libdwarf can

  change a Dwarf_Debug. So it is unsafe to have two different

  threads accessing a single Dwarf_Debug simultaneously.

  It is therefore sufficient to ensure than any one Dwarf_Debug

  is only accessed from a single thread.

Warnings like

 "warning: cast from pointer to integer of different size"

at compile time are to be expected in dwarf_frame.c and

dwarf_frame2.c.   Do not be alarmed.

If your headers are not in the expected places,

use the configure script to access them (and to add other ld

or C flags).

For example

        ./configure  CPPFLAGS="-I/home/davea/inc" CFLAGS="-I/home/davea/inc"

Set both CFLAGS and CPPFLAGS so that configure works properly.

It is now possible to request shared library build with

	--enable-shared

(--enable-nonshared is on by default).

TARGET DEPENDENCIES of .debug_frame:

dwarf.h

  These should be revised if you have more than the defined

  63 'normal' registers.  It's not harmful to have these too large!

  Too small will lead to errors reading .debug_frame and .eh_frame.

  DW_FRAME_HIGHEST_NORMAL_REGISTER

  DW_FRAME_LAST_REG_NUM

  These you might revise, but can safely ignore if simply

  using dwarfdump.  If using the producer code you will want

  to get these exactly right for your architecture.

  DW_FRAME_RA_COL

  DW_FRAME_STATIC_LINK

  DW_FRAME_CFA_COL

libdwarf.h

  The DW_FRAME_REG_INITIAL_VALUE #define should be set to

  the value approprate to your archtecture. See libdwarf.h

  for details.

  If DW_REG_TABLE_SIZE is not set large enough attempts to 

  fill in the .debug_frame tables will get an error. 

  Should be at least as large as DW_FRAME_LAST_REG_NUM.

  If it's too large nothing is harmed (but some extra space taken

  at run time).

The .debug_frame is so very architecture dependent

and because the host (where libdwarf/dwarfdump are executed)

and target (the objects read) could be different.

It's currently not supported to have dwarfdump/libdwarf determine

the architecture on-the-fly and do-the-right-thing.

Just setting DW_FRAME_LAST_REG_NUM and DW_FRAME_HIGHEST_NORMAL_REGISTER

and DW_REG_TABLE_SIZE high enough will likely suffice for most

purposes and most compilers/architectures..

See comments in dwarf.h/libdwarf.h.

It's perfectly safe to ignore the above suggestions as long

as libdwarf does not get a DW_DLE_DF_REG_NUM_TOO_HIGH error.

(which would only happen on reading .debug_frame or .eh_frame data).

If you intend to use the libdwarf dwarf-producer code

for .debug_frame information

you must do a thorough analysys and revise dwarf.h

substantially to match the output target archtecture.

In general, in the producer code, numbers are copied from and

to integers with memcpy().  In case of endianness problems,

constants set in dwarf_producer_init() can fix the problems.

If one wants to produce a *different-endian* output the best

solution is to change the integer memcpy calls to call thru a

new dbg-based function pointer and have it 'do the right thing'

to adjust endianness.  Set the function pointer correctly in

dwarf_producer_init() and the rest of the code will just call

thru the function pointer.  Tedious work to find and change the

memcpy calls to be dbg->de_memcpy(), but once done the code is

no longer endian dependent (right now there is no way to ask

for cross-endian: a new flag needed or ?).

leb128 numbers are endian-independent, so nothing need be

done with those for cross-endian support (the storage

of leb128 on disk is always little-endian).

The .ps files are postscript. So those who cannot deal with mm

format files but do have a postscript printer (or have

ghostscript) can print the documents.  

This form was chosen before pdf format existed...

libdwarf2.1.ps documents a way for a debugger to read dwarf information.

libdwarf2p.1.ps documents a way for a compiler to generate dwarf information.

dwarf.v2.ps documents Dwarf Version 2.

index.v2.ps is an index to dwarf.v2.ps.

indexDW.v2  is a plain text index of dwarf #defines to dwarf.v2.ps

mips_extensions.ps documents the mips/sgi extensions to dwarf.

The commands used to generate the postscript were:

 pr -t -e libdwarf2.1.mm | tbl | psroff -t -mm >libdwarf2.1.ps

 pr -t -e  libdwarf2p.1.mm | tbl | psroff -t -mm >libdwarf2p.1.ps

 pic dwarf.v2.mm | tbl | psroff -t -mm >dwarf.v2.ps 2> newIndex

 pic index.v2.mm | tbl | psroff -t -mm >index.v2.ps

pic is a picture processing tool (ATT command).

tbl is a table-processing tool.

(part of Documentor's Work Bench on ATT-like systems).

tbl and pic are available on linux.

psroff is a name for a troff-like processor, part of

Documentor's Work Bench on IRIX. Substitute a

troff-like or nroff-like processor.

The index.v2.mm was generated by the dwarf-document writer

using some local ATT/USL tools (which SGI does not have, so

there is no way I know of to regenerate this).

To use dwarf or libdwarf, you may want to install dwarf.h and

libdwarf.h somewhere convenient.

You will also need libelf (libelf.a and/or libelf.so) and

libelf.h installed. These are available from GNU repositories.

$Source: /plroot/cmplrs.src/v7.4.5m/.RCS/PL/libdwarf/RCS/README,v $

$Revision: 1.10 $

$Date: 2006/03/30 18:04:52 $