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