Home | History | Annotate | only in /external/libunwind
Up to higher level directory
NameDateSize
acinclude.m421-Aug-20181.6K
android/21-Aug-2018
Android.bp21-Aug-201815.5K
AUTHORS21-Aug-201839
aux/21-Aug-2018
ChangeLog21-Aug-20181.9K
configure.ac21-Aug-201812.2K
COPYING21-Aug-20181K
doc/21-Aug-2018
include/21-Aug-2018
LICENSE21-Aug-20181,023
Makefile.am21-Aug-20182.5K
MODULE_LICENSE_MIT21-Aug-20180
NEWS21-Aug-20188.2K
NOTICE21-Aug-20181,023
README21-Aug-20186.7K
scripts/21-Aug-2018
src/21-Aug-2018
tests/21-Aug-2018
TODO21-Aug-20185K

README

      1 -*- mode: Outline -*-
      2 
      3 This is version 1.0 of the unwind library.  This library supports
      4 several architecture/operating-system combinations:
      5 
      6  Linux/x86-64:	Works well.
      7  Linux/x86:	Works well.
      8  Linux/ARM:	Works well.
      9  Linux/IA-64:	Fully tested and supported.
     10  Linux/PARISC:	Works well, but C library missing unwind-info.
     11  HP-UX/IA-64:	Mostly works but known to have some serious limitations.
     12  Linux/AArch64:	Newly added.
     13  Linux/PPC64:	Newly added.
     14  Linux/SuperH:	Newly added.
     15  FreeBSD/i386:	Newly added.
     16  FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).
     17 
     18 
     19 * General Build Instructions
     20 
     21 In general, this library can be built and installed with the following
     22 commands:
     23 
     24 	$ autoreconf -i # Needed only for building from git. Depends on libtool.
     25 	$ ./configure
     26 	$ make
     27 	$ make install prefix=PREFIX
     28 
     29 where PREFIX is the installation prefix.  By default, a prefix of
     30 /usr/local is used, such that libunwind.a is installed in
     31 /usr/local/lib and unwind.h is installed in /usr/local/include.  For
     32 testing, you may want to use a prefix of /usr/local instead.
     33 
     34 
     35 * Building with Intel compiler
     36 
     37 ** Version 8 and later
     38 
     39 Starting with version 8, the preferred name for the IA-64 Intel
     40 compiler is "icc" (same name as on x86).  Thus, the configure-line
     41 should look like this:
     42 
     43     $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
     44 		LDFLAGS="-L$PWD/src/.libs"
     45 
     46 
     47 * Building on HP-UX
     48 
     49 For the time being, libunwind must be built with GCC on HP-UX.
     50 
     51 libunwind should be configured and installed on HP-UX like this:
     52 
     53     $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"
     54 
     55 Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
     56 	at the moment.
     57 
     58 ** Workaround for older versions of GCC
     59 
     60 GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h.  The
     61 workaround is to issue the following commands before running
     62 "configure":
     63 
     64     $ mkdir $top_dir/include/sys
     65     $ cp /usr/include/sys/types.h $top_dir/include/sys
     66 
     67 GCC v3.3.2 or later have been fixed and do not require this
     68 workaround.
     69 
     70 * Building for PowerPC64 / Linux
     71 
     72 For building for power64 you should use:
     73 
     74   $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
     75 
     76 If your power support altivec registers:
     77   $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
     78 
     79 To check if your processor has support for vector registers (altivec):
     80     cat /proc/cpuinfo | grep altivec
     81 and should have something like this:
     82     cpu             : PPC970, altivec supported
     83 
     84 If libunwind seems to not work (backtracing failing), try to compile
     85 it with -O0, without optimizations. There are some compiler problems
     86 depending on the version of your gcc.
     87 
     88 * Building on FreeBSD
     89 
     90 General building instructions apply. To build and execute several tests,
     91 you need libexecinfo library available in ports as devel/libexecinfo.
     92 
     93 Development of the port was done of FreeBSD 8.0-STABLE. The library
     94 was build with the system compiler that is modified version of gcc 4.2.1,
     95 as well as the gcc 4.4.3.
     96 
     97 * Regression Testing
     98 
     99 After building the library, you can run a set of regression tests with:
    100 
    101 	$ make check
    102 
    103 ** Expected results on IA-64 Linux
    104 
    105 Unless you have a very recent C library and compiler installed, it is
    106 currently expected to have the following tests fail on IA-64 Linux:
    107 
    108 	Gtest-init		(should pass starting with glibc-2.3.x/gcc-3.4)
    109 	Ltest-init		(should pass starting with glibc-2.3.x/gcc-3.4)
    110 	test-ptrace		(should pass starting with glibc-2.3.x/gcc-3.4)
    111 	run-ia64-test-dyn1	(should pass starting with glibc-2.3.x)
    112 
    113 This does not mean that libunwind cannot be used with older compilers
    114 or C libraries, it just means that for certain corner cases, unwinding
    115 will fail.  Since they're corner cases, it is not likely for
    116 applications to trigger them.
    117 
    118 Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's
    119       almost certainly a sign of an old assembler.  The GNU assembler used
    120       to encode previous-stack-pointer-relative offsets incorrectly.
    121       This bug was fixed on 21-Sep-2004 so any later assembler will be
    122       fine.
    123 
    124 ** Expected results on x86 Linux
    125 
    126 The following tests are expected to fail on x86 Linux:
    127 
    128 	Gtest-resume-sig	(fails to get SIGUSR2)
    129 	Ltest-resume-sig	(likewise)
    130 	Gtest-dyn1		(no dynamic unwind info support yet)
    131 	Ltest-dyn1		(no dynamic unwind info support yet)
    132 	test-setjmp		(longjmp() not implemented yet)
    133 	run-check-namespace	(no _Ux86_getcontext yet)
    134 	test-ptrace
    135 
    136 ** Expected results on x86-64 Linux
    137 
    138 The following tests are expected to fail on x86-64 Linux:
    139 
    140 	Gtest-dyn1		(no dynamic unwind info support yet)
    141 	Ltest-dyn1		(no dynamic unwind info support yet)
    142 	Gtest-init (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18743)
    143 	Ltest-init		(likewise)
    144 	test-async-sig		(crashes due to bad unwind-info?)
    145 	test-setjmp		(longjmp() not implemented yet)
    146 	run-check-namespace	(no _Ux86_64_getcontext yet)
    147 	run-ptrace-mapper	(??? investigate)
    148 	run-ptrace-misc	(see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748
    149 			 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749)
    150 
    151 ** Expected results on PARISC Linux
    152 
    153 Caveat: GCC v3.4 or newer is needed on PA-RISC Linux.  Earlier
    154 versions of the compiler failed to generate the exception-handling
    155 program header (GNU_EH_FRAME) needed for unwinding.
    156 
    157 The following tests are expected to fail on x86-64 Linux:
    158 
    159 	Gtest-bt   (backtrace truncated at kill() due to lack of unwind-info)
    160 	Ltest-bt   (likewise)
    161 	Gtest-resume-sig  (Gresume.c:my_rt_sigreturn() is wrong somehow)
    162 	Ltest-resume-sig  (likewise)
    163 	Gtest-init (likewise)
    164 	Ltest-init (likewise)
    165 	Gtest-dyn1 (no dynamic unwind info support yet)
    166 	Ltest-dyn1 (no dynamic unwind info support yet)
    167 	test-setjmp		(longjmp() not implemented yet)
    168 	run-check-namespace	(toolchain doesn't support HIDDEN yet)
    169 
    170 ** Expected results on HP-UX
    171 
    172 "make check" is currently unsupported for HP-UX.  You can try to run
    173 it, but most tests will fail (and some may fail to terminate).  The
    174 only test programs that are known to work at this time are:
    175 
    176      tests/bt
    177      tests/Gperf-simple
    178      tests/test-proc-info
    179      tests/test-static-link
    180      tests/Gtest-init
    181      tests/Ltest-init
    182      tests/Gtest-resume-sig
    183      tests/Ltest-resume-sig
    184 
    185 ** Expected results on PPC64 Linux
    186 
    187 "make check" should run with no more than 10 out of 24 tests failed.
    188 
    189 
    190 * Performance Testing
    191 
    192 This distribution includes a few simple performance tests which give
    193 some idea of the basic cost of various libunwind operations.  After
    194 building the library, you can run these tests with the following
    195 commands:
    196 
    197  $ cd tests
    198  $ make perf
    199 
    200 * Contacting the Developers
    201 
    202 Please direct all questions regarding this library to:
    203 
    204 	libunwind-devel (a] nongnu.org
    205 
    206 You can do this by sending a mail to libunwind-request (a] nongnu.org with
    207 a body of:
    208 
    209 	subscribe libunwind-devel
    210 
    211 or you can subscribe and manage your subscription via the
    212 web-interface at:
    213 
    214 	https://savannah.nongnu.org/mail/?group=libunwind
    215