libunwind.tex revision 3631469c786076a4dfc0659d405a683b31ec8095
1\documentclass{article} 2\usepackage[fancyhdr,pdf]{latex2man} 3 4\input{common.tex} 5 6\begin{document} 7 8\begin{Name}{3}{libunwind}{David Mosberger-Tang}{Programming Library}{Introduction to libunwind} 9 10 libunwind -- a (mostly) platform-independent unwind API 11\end{Name} 12 13\section{Synopsis} 14 15\File{\#include $<$libunwind.h$>$}\\ 16 17\noindent 18\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*});\\ 19\noindent 20\Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}, \Type{unw\_context\_t~*});\\ 21\noindent 22\Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}, \Type{unw\_addr\_space\_t}, \Type{void~*});\\ 23\noindent 24\Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*});\\ 25\noindent 26\Type{int} \Func{unw\_get\_reg}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_word\_t~*});\\ 27\noindent 28\Type{int} \Func{unw\_get\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_fpreg\_t~*});\\ 29\noindent 30\Type{int} \Func{unw\_set\_reg}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_word\_t});\\ 31\noindent 32\Type{int} \Func{unw\_set\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_fpreg\_t});\\ 33\noindent 34\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*});\\ 35 36\noindent 37\Type{unw\_addr\_space\_t} \Var{local\_addr\_space};\\ 38\noindent 39\Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t}, \Type{int});\\ 40\noindent 41\Type{void} \Func{unw\_destroy\_addr\_space}(\Type{unw\_addr\_space\_t});\\ 42\noindent 43\Type{unw\_accessors\_t} \Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t});\\ 44\noindent 45\Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t});\\ 46\noindent 47\Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t}, \Type{unw\_caching\_policy\_t});\\ 48 49\noindent 50\Type{const char *}\Func{unw\_regname}(\Type{int});\\ 51\noindent 52\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}, \Type{unw\_proc\_info\_t~*});\\ 53\noindent 54\Type{int} \Func{unw\_get\_save\_loc}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_save\_loc\_t~*});\\ 55\noindent 56\Type{int} \Func{unw\_is\_signal\_frame}(\Type{unw\_cursor\_t~*});\\ 57\noindent 58\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}, \Type{char~*}, \Type{size\_t});\\ 59 60\noindent 61\Type{void} \Func{\_U\_dyn\_register}(\Type{unw\_dyn\_info\_t~*});\\ 62\noindent 63\Type{void} \Func{\_U\_dyn\_cancel}(\Type{unw\_dyn\_info\_t~*});\\ 64 65\section{Local Unwinding} 66 67\Prog{Libunwind} is very easy to use when unwinding a stack from 68within a running program. This is called \emph{local} unwinding. Say 69you want to unwind the stack while executing in some function 70\Func{F}(). In this function, you would call \Func{unw\_getcontext}() 71to get a snapshot of the CPU registers (machine-state). Then you 72initialize an \emph{unwind~cursor} based on this snapshot. This is 73done with a call to \Func{unw\_init\_local}(). The cursor now points 74to the current frame, that is, the stack frame that corresponds to the 75current activation of function \Func{F}(). The unwind cursor can then 76be moved ``up'' (towards earlier stack frames) by calling 77\Func{unw\_step}(). By repeatedly calling this routine, you can 78uncover the entire call-chain that led to the activation of function 79\Func{F}(). A positive return value from \Func{unw\_step}() indicates 80that there are more frames in the chain, zero indicates that the end 81of the chain has been reached, and any negative value indicates that 82some sort of error has occurred. 83 84While it is not possible to directly move the unwind cursor in the 85``down'' direction (towards newer stack frames), this effect can be 86achieved by making copyies of an unwind cursor. For example, a 87program that sometimes has to move ``down'' by one stack frame could 88maintain two cursor variables: ``\Var{curr}'' and ``\Var{prev}''. The 89former would be used as the current cursor and \Var{prev} would be 90maintained as the ``previous frame'' cursor by copying the contents of 91\Var{curr} to \Var{prev} right before calling \Func{unw\_step}(). 92With this approach, the program could move one step ``down'' simply by 93copying back \Var{prev} to \Var{curr} whenever that is necessary. In 94the mosts extreme case, a program could maintain a separate cursor for 95each call frame and that way it could move up and down the call frame 96chain at will. 97 98Given an unwind cursor, it is possible to read and write the CPU 99registers that were preserved for the current stack frame identified 100by the cursor. \Prog{Libunwind} provides several routines for this 101purpose: \Func{unw\_get\_reg}() reads an integer (general) register, 102\Func{unw\_get\_fpreg}() reads a floating-point register, 103\Func{unw\_set\_reg}() writes an integer register, and 104\Func{unw\_set\_fpreg}() writes a floating-point register. Note that, 105by definition, only the \emph{preserved} machine state can be accessed 106during an unwind operation. Normally, this state consists of the 107\emph{callee-saved} (``preserved'') registers. However, in some 108special circumstances (e.g., in a signal handler trampoline), even the 109\emph{caller-saved} (``scratch'') registers are preserved in the stack 110frame and, in those cases, \Prog{libunwind} will grant access to them 111as well. The exact set of registers that can be accessed via the 112cursor depends, of course, on the platform. However, there are two 113registers that can be read on all platforms: the instruction pointer 114(IP), sometimes also known as the ``program counter'', and the stack 115pointer (SP). In \Prog{libunwind}, these registers are identified by 116the macros \Const{UNW\_REG\_IP} and \Const{UNW\_REG\_SP}, 117respectively. 118 119Besides just moving the unwind cursor and reading/writing saved 120registers, \Prog{libunwind} also provides the ability to resume 121execution at an arbitrary stack frame. As you might guess, this is 122useful for implementing non-local gotos and the exception handling 123needed by some high-level languages such as Java. Resuming execution 124with a particular stack frame simply requires calling 125\Func{unw\_resume}() and passing the cursor identifying the target 126frame as the only argument. 127 128Normally, \Prog{libunwind} supports both local and remote unwinding 129(the latter will be explained in the next section). However, if you 130tell libunwind that your program only needs local unwinding, then a 131special implementation can be selected which may run much faster than 132the generic implementation which supports both kinds of unwinding. To 133select this optimized version, simply define the macro 134\Const{UNW\_LOCAL\_ONLY} before including the headerfile 135\File{$<$libunwind.h$>$}. If is perfectly OK for a single program to 136employ both local-only and generic unwinding. That is, whether or not 137\Const{UNW\_LOCAL\_ONLY} is defined is a choice that each source-file 138(compilation-unit) can make on its own. Independent of the setting(s) 139of \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into 140the program (normally \Opt{-l}\File{unwind}). 141 142If we put all of the above together, here is how we could use 143\Prog{libunwind} write function \Func{show\_backtrace}() which prints 144a classic stack trace: 145 146\begin{verbatim} 147#define UNW_LOCAL_ONLY 148#include <libunwind.h> 149 150void show_backtrace (void) { 151 unw_cursor_t cursor; unw_context_t uc; 152 unw_word_t ip, sp; 153 154 unw_getcontext(&uc); 155 unw_init_local(&cursor, &uc); 156 while (unw_step(&cursor) > 0) { 157 unw_get_reg(&cursor, UNW_REG_IP, &ip); 158 unw_get_reg(&cursor, UNW_REG_SP, &sp); 159 printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp); 160 } 161} 162\end{verbatim} 163 164 165\section{Remote Unwinding} 166 167\Prog{Libunwind} can also be used to unwind a stack in a ``remote'' 168process. Here, ``remote'' may mean another process on the same 169machine or even a process on a completely different machine from the 170one that is running \Prog{libunwind}. Remote unwinding is typically 171used by debuggers and instruction-set simulators, for example. 172 173Before you can unwind a remote process, you need to create a new 174address-space object for that process. This is achieved with the 175\Func{unw\_create\_addr\_space} routine. The routine takes two 176arguments: a pointer to a set of \emph{accessor} routines and an 177integer that specifies the byte-order of the target process. The 178accessor routines provide \Func{libunwind} with the means to 179communicate with the remote process. In particular, there are 180callbacks to read and write the process's memory, its registers, and 181to access unwind information which may be needed by \Func{libunwind}. 182 183With the address space created, unwinding can be initiated by a call 184to \Func{unw\_init\_remote}(). This routine is very similar to 185\Func{unw\_init\_local}(), except that it takes an address-space 186object and an opaque pointer as arguments. The routine uses these 187arguments to fetch the initial machine state. \Prog{Libunwind} never 188uses the opaque pointer on its own, but instead justs passes it on to 189the accessor (callback) routines. Typically, this pointer is used to 190select, e.g., the thread within a process that is to be unwound. 191 192Once a cursor has been initialized with \Func{unw\_init\_remote}(), 193unwinding works exactly like in the local case. That is, you can use 194\Func{unw\_step} to move ``up'' in the call-chain, read and write 195registers, or resume execution at a particular stack frame by calling 196\Func{unw\_resume}. 197 198 199\section{Cross-platform and Multi-platform Unwinding} 200 201\Prog{Libunwind} has been designed to enable unwinding across 202platforms (architectures). Indeed, a single program can use 203\Prog{libunwind} to unwind an arbitrary number of target platforms, 204all at the same time! 205 206We call the machine that is running \Prog{libunwind} the \emph{host} 207and the machine that is running the process being unwound the 208\emph{target}. If the host and the target platform are the same, we 209call it \emph{native} unwinding. If they differ, we call it 210\emph{cross-platform} unwinding. 211 212The principle behind supporting native, cross-platform, and 213multi-platform unwinding are very simple: for native unwinding, a 214program includes \File{$<$libunwind.h$>$} and uses the linker switch 215\Opt{-l}\File{unwind}. For cross-platform unwinding, a program 216includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker 217switch \Opt{-l}\File{unwind-}\Var{PLAT}, where \Var{PLAT} is the name 218of the target platform (e.g., \File{ia64} for IA-64, \File{hppa-elf} 219for ELF-based HP PA-RISC, or \File{x86} for 80386). Multi-platform 220unwinding works exactly like cross-platform unwinding, the only 221limitation is that a single source file (compilation unit) can include 222at most one \Prog{libunwind} header file. In other words, the 223platform-specific support for each supported target needs to be 224isolated in separate source files---a limitation that shouldn't be an 225issue in practice. 226 227Note that, by definition, local unwinding is possible only for the 228native case. Attempting to call, e.g., \Func{unw\_local\_init}() when 229targeting a cross-platform will result in a link-time error 230(unresolved references). 231 232 233\section{Thread- and Signal-Safety} 234 235 236All \Prog{libunwind} routines are thread-safe. What this means is 237that multiple threads may use \Prog{libunwind} simulatenously. 238However, any given cursor may be accessed by only one thread at 239any given time. 240 241To ensure thread-safety, some \Prog{libunwind} routines may have to 242use locking. Such routines \emph{must~not} be called from signal 243handlers (directly or indirectly) and are therefore \emph{not} 244signal-safe. The manual page for each \Prog{libunwind} routine 245identifies whether or not it is signal-safe, but as a general rule, 246any routine that may be needed for \emph{local} unwinding is 247signal-safe (e.g., \Func{unw\_step}() for local unwinding is 248signal-safe). For remote-unwinding, \emph{none} of the 249\Prog{libunwind} routines are guaranteed to be signal-safe. 250 251 252\section{Unwinding Through Dynamically Generated Code} 253 254\Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and 255\Func{\_U\_dyn\_cancel} to register/cancel the information required to 256unwind through code that has been generated at runtime (e.g., by a 257just-in-time (JIT) compiler). It is important to register the 258information for \emph{all} dynamically generated code because 259otherwise, a debugger may not be able to function properly or 260high-level language exception handling may not work as expected. 261 262The interface for registering and canceling dynamic unwind info has 263been designed for maximum efficiency, so as to minimize the 264performance impact on JIT-compilers. In particular, both routines are 265guaranteed to execute in ``constant time'' (O(1)) and the 266data-structure encapsulating the dynamic unwind info has been designed 267to facilitate sharing, such that similar procedures can share much of 268the underlying information. 269 270 271\section{Caching of Unwind Info} 272 273To speed up execution, \Prog{libunwind} may aggressively cache the 274information it needs to perform unwinding. If a process changes 275during its lifetime, this creates a risk of \Prog{libunwind} using 276stale data. For example, this would happen if \Prog{libunwind} were 277to cache information about a shared library which later on gets 278unloaded (e.g., via \Cmd{dlclose}{3}). 279 280To prevent the risk of using stale data, \Prog{libunwind} provides two 281facilities: first, it is possible to flush the cached information 282associated with a specific address range in the target process (or the 283entire address space, if desired). This functionality is provided by 284\Func{unw\_flush\_cache}(). The second facility is provided by 285\Func{unw\_set\_caching\_policy}(), which lets a program 286select the exact caching policy in use for a given address-space 287object. In particular, by selecting the policy 288\Const{UNW\_CACHE\_NONE}, it is possible to turn off caching 289completely, therefore eliminating the risk of stale data alltogether 290(at the cost of slower execution). By default, caching is enabled for 291local unwinding only. 292 293 294\section{Files} 295 296\begin{Description} 297\item[\File{libunwind.h}] Headerfile to include for native (same 298 platform) unwinding. 299\item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when 300 unwind target runs on platform \Var{PLAT}. For example, to unwind 301 an IA-64 program, the header file \File{libunwind-ia64.h} should be 302 included. 303\item[\Opt{-l}\File{unwind}] Linker-switch to add when building a 304 program that does native (same platform) unwinding. 305\item[\Opt{-l}\File{unwind-}\Var{PLAT}] Linker-switch to add when 306 building a program that unwinds a program on platform \Var{PLAT}. 307 For example, to (cross-)unwind an IA-64 program, the linker switch 308 \File{-lunwind-ia64} should be added. Note: multiple such switches 309 may need to be specified for programs that can unwind programss on 310 multiple platforms. 311\end{Description} 312 313\section{See Also} 314 315libunwind-ia64(3), libunwind-hppa(3), libunwind-x86(3), 316unw\_init\_local(3), unw\_init\_remote(3), etc. 317 318\section{Author} 319 320\noindent 321David Mosberger-Tang\\ 322Hewlett-Packard Labs\\ 323Palo-Alto, CA 94304\\ 324Email: \Email{davidm@hpl.hp.com}\\ 325WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}. 326\LatexManEnd 327 328\end{document} 329