Merge branch 'master' into new-parallel-parsing
[dyninst.git] / stackwalk / doc / 1-Introduction.tex
1 \section{Introduction}
2 \label{sec:intro}
3 This document describes StackwalkerAPI, an API and library for walking a call
4 stack. The call stack (also known as the run-time stack) is a stack found in a
5 process that contains the currently active stack frames. Each stack frame is a
6 record of an executing function (or function-like object such as a signal
7 handler or system call). StackwalkerAPI provides an API that allows users to
8 collect a call stack (known as walking the call stack) and access information
9 about its stack frames. The current implementation supports Linux/x86,
10 Linux/x86-64, Linux/Power, Linux/Power-64, Windows/x86, BlueGene/L, and BlueGene/P.
11
12 StackwalkerAPI is designed to be both easy-to-use and easy-to-extend. Users can
13 easily use StackwalkerAPI to walk a call stack without needing to understand how
14 call stacks are laid out on their platform. Users can easily extend
15 StackwalkerAPI to work with new platforms and types of stack frames by
16 implementing a set of callbacks that can be plugged into StackwalkerAPI.
17
18 StackwalkerAPI's ease-of-use comes from it providing a platform independent
19 interface that allows users to access detailed information about the call stack.
20 For example, the following C++ code-snippet is all that is needed to walk and
21 print the call stack of the currently running thread.
22
23 \lstset{language=[GNU]C++,basicstyle=\ttfamily\selectfont\small}
24 \lstset{numbers=none}
25 \begin{lstlisting}
26 std::vector<Frame> stackwalk; 
27 string s;
28
29 Walker *walker = Walker::newWalker();
30 walker->walkStack(stackwalk);
31 for (unsigned i=0; i<stackwalk.size(); i++) {
32                 stackwalk[i].getName(s);
33                 cout << "Found function " << s << endl;
34 }       
35 \end{lstlisting}
36
37 StackwalkerAPI can walk a call stack in the same address space as where the
38 StackwalkerAPI library lives (known as a first party stackwalk), or it can walk
39 a call stack in another process (known as a third party stackwalk). To change
40 the above example to perform a third party stackwalk, we would only need to pass
41 a process identifier to newWalker, e.g: 
42 \begin{lstlisting}
43 Walker *walker = Walker::newWalker(pid);
44 \end{lstlisting}
45         
46 Our other design goal with StackwalkerAPI is to make it easy-to-extend. The
47 mechanics of how to walk through a stack frame can vary between different
48 platforms, and even between different types of stack frames on the same
49 platform. In addition, different platforms may have different mechanisms for
50 reading the data in a call stack or looking up symbolic names that go with a
51 stack frame. StackwalkerAPI provides a callback interface for plugging in
52 mechanisms for handling new systems and types of stack frames. The callback
53 interface can be used to port StackwalkerAPI to new platforms, extend
54 StackwalkerAPI support on existing systems, or more easily integrate
55 StackwalkerAPI into existing tools. There are callbacks for the following
56 StackwalkerAPI operations:
57
58 \begin{description}
59     \item[Walk through a stack frame] StackwalkerAPI will find different types
60         of stack frames on different platforms and even within the same
61         platform. For example, on Linux/x86 the stack frame generated by a
62         typical function looks different from the stack frame generated by a
63         signal handler. The callback interface can be used to register a handler
64         with StackwalkerAPI that knows how to walk through a new type of stack
65         frame. For example, the DyninstAPI tool registers an object with
66         StackwalkerAPI that describes how to walk through the stack frames
67         generated by its instrumentation.
68     
69     \item[Access process data] To walk a call stack, StackwalkerAPI needs to be
70         able to read a process' memory and registers. When doing a first party
71         stackwalk, this is done by directly reading them from the current
72         address space. When doing a third party stackwalk, this is done by
73         reading them using a debugger interface. The callback interface can be
74         used to register new objects for accessing process data. This can be
75         used, for example, to port StackwalkerAPI to a new operating system or
76         make it work with a new debugger interface.
77     
78     \item[Look up symbolic names] When StackwalkerAPI finds a stack frame, it
79         gets an address that points into the piece of code that created that
80         stack frame. This address is not necessarily meaningful to a user, so
81         StackwalkerAPI attempts to associate the address with a symbolic name.
82         The callback interface can be used to register an object with
83         StackwalkerAPI that performs an address to name mapping, allowing
84         StackwalkerAPI to associate names with stack frames.  
85 \end{description}