Imported Upstream version 20120410upstream/20120410upstream

1 files changed, 199 insertions, 0 deletions

diff --git a/libdwarf/README b/libdwarf/README
new file mode 100644
index 0000000..bf96a58
--- /dev/null
+++ b/libdwarf/README
@@ -0,0 +1,199 @@
+To build libdwarf.a, type
+        ./configure
+        make
+To build libdwarf.so, type
+        ./configure --enable-shared --disable-nonshared
+        make
+To build  both, type
+        ./configure --enable-shared 
+        make
+
+No real install target is provided here, so 'make install' does
+not do much. One can copy either or both of libdwarf.a libdwarf.so 
+to somewhere fairly standard (but intended for software you build)  
+like '/usr/local/lib'.  Or anywhere else you want to copy it.
+
+To use dwarf or libdwarf, you may want to copy dwarf.h and
+libdwarf.h somewhere convenient (possibly /usr/local/include), 
+and you may need to copy the libdwarf to a convenient spot 
+(/usr/local/lib is a traditional place for libraries one builds
+oneself on Unix and Linux).
+This copying is not needed to build dwarfdump.
+
+
+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 make command line to add flags and include directories.
+For example
+  ./configure  
+  PREINCS="-I /usr/local/share/include" POSTINCS="-I /home/x/include"  make
+PREINCS content is inserted before CFLAGS as make(1) is running.
+POSTINCS content is added after the CFLAGS value.
+
+To set LDFLAGS (which is used when building a .so and
+in building gennames to create some source here), 
+do so at configure time, for example:
+  ./configure LDFLAGS="-L /var/tmp"
+Or use PRELIBS and/or POSTLIBS at 'make' time similar to the use
+of PREINCS and POSTINCS.
+
+If you are using the old frame interfaces and depend on
+the use of DW_FRAME_CFA_COL you must add  --enable-oldframecol
+to the ./configure options to configure libdwarf.
+See NEWS and libdwarf2.1.mm/pdf .
+
+To generate SGI IRIX 64 bit offsets (in the producer code)
+configure with   --enable-dwarf-format-sgi-irix.
+To configure with only 32bit offsets (aka DWARF2) configure
+with --enable-dwarf-format-strict-32bit.
+By default the producer now generates 32bit offsets by default
+but one can turn on DWARF3 64bit offset generation at runtime by ORing
+DW_DLC_OFFSET_SIZE_64 onto the flags in the call to 
+dwarf_producer_init() (or dwarf_producer_init_b) [when the
+address size is specified as 64 bit].
+
+Mac OSX (June 2010): Since MacOSX does not use elf, there is no elf.h
+header in the headers provided on MacOSX.
+Use a search engine (like google) to find an elf.h you can use.
+http://www.rockbox.org/tracker/9006?getfile=16683 
+might be useful.
+In addition, the archive (ar) program on MacOSX does not
+automatically generate some data so modify the generated
+Makefile to add -s to the options to ar.
+
+To enable dection of Windows pathnames as full paths
+add --enable-windowspath.  Doing this does mean things like
+A:foo and \anything are treated as full paths (these are
+unlikely path names on a POSIX system but are legal 
+POSIX partial paths).
+
+It is possible to request a shared library (libdwarf.so) build with
+	--enable-shared
+To turn off the build of the archive library (libdwarf.a) specify
+        --disable-nonshared
+but in this case you must specify --enable-shared or nothing will
+build!
+
+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 appropriate to your architecture. 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).
+
+If your printf does not support C standard %llx etc,
+(such as MSWindows with long long), configure
+option --enable-nonstandardprintf
+and defines like DW_PR_DUx etc in libdwarf.h
+provide a way to configure for that relatively easily.
+
+
+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 architecture.
+
+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.pdf documents a way for a debugger to read dwarf information.
+libdwarf2p.1.pdf documents a way for a compiler to generate dwarf information.
+dwarf.v2.pdf documents Dwarf Version 2.
+index.v2.pdf 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.
+
+See the Makefile for the commands used to build pdf files
+libdwarf.2.1.pdf and libdwarf1p.1.pdf.
+
+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 (GNU groff works fine).
+
+The index.v2.mm was generated by the dwarf-document writer
+using some local ATT/USL tools (which neither SGI 
+nor the open-source community generally has, 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
+and from the normal Linux repositories for Linux releases.
+On Ubuntu 20/04 for example:
+	sudo apt-get install libelf-dev libelf1 
+
+$Source: /home/davea/dwarf/dwarf-working/trunk/libdwarf/README,v $
+$Revision: 1.1 $
+$Date: 2009/11/23 17:15:37 $