--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/elf4rom/libs/dwarf-20071209/libdwarf/README Fri Jan 15 09:07:44 2010 +0000
@@ -0,0 +1,136 @@
+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 $