Merge branch 'master' into new-parallel-parsing
[dyninst.git] / stackwalk / doc / 4-Callbacks.tex
1 \section{Callback Interface Default Implementations}
2
3 StackwalkerAPI provides one or more default implementations of each of the
4 callback classes described in Section 3.5. These implementations are used by a
5 default configuration of StackwalkerAPI. 
6
7 \subsection{Debugger Interface}
8 \label{subsec:debugger}
9
10 This section describes how to use StackwalkerAPI for collecting 3rd party stack
11 walks. In 3rd party mode StackwalkerAPI uses the OS's debugger interface to
12 connect to another process and walk its call stacks. As part of being a debugger
13 StackwalkerAPI receives and needs to handle debug events. When a debugger event
14 occurs, StackwalkerAPI must get control of the host process in order to receive
15 the debugger event and continue the target process. 
16
17 To illustrate the complexities with running in 3rd party mode, consider the
18 follow code snippet that uses StackwalkerAPI to collect a stack walk every five
19 seconds. 
20
21 \begin{lstlisting}
22 Walker *walker = Walker::newWalker(pid);
23 std::vector<Frame> swalk;
24 for (;;) {
25                 walker->walkStack(swalk);
26                 sleep(5);
27 }
28 \end{lstlisting}
29
30 StackwalkerAPI is running in 3rd party mode, since it attached to the target
31 process, \code{pid}. As the target process runs it may be generating debug events such
32 a thread creation and destruction, library loads and unloads, signals,
33 forking/execing, etc. When one of these debugger events is generated the OS will
34 pause the target process and send a notice to the host process. The target
35 process will remain paused until the host process handles the debug event and
36 resumes the target process.
37
38 In the above example the host process is spending almost all of its time in the
39 sleep call. If a debugger event happens during the sleep, then StackwalkerAPI
40 will not be able to get control of the host process and handle the event for up
41 to five seconds. This will cause long pauses in the target process and lead to a
42 potentially very large slowdown.
43
44 To work around this problem StackwalkerAPI provides a notification file
45 descriptor. This file descriptor represents a connection between the
46 StackwalkerAPI library and user code. StackwalkerAPI will write a single byte to
47 this file descriptor when a debug event occurs, thus notifying the user code
48 that it needs to let StackwalkerAPI receive and handle debug events. The user
49 code can use system calls such as select to watch for events on the notification
50 file descriptor.
51
52 The following example illustrates how to properly use StackwalkerAPI to collect
53 a stack walk from another process at a five second interval. Details on the
54 \code{ProcDebug} class, \code{getNotificationFD} method, and
55 \code{handleDebugEvent} method can be
56 found in Section~\ref{subsubsec:procdebug}. See the UNIX man pages for more information on the
57 \code{select} system call. Note that this example does not include all of the proper
58 error handling and includes that should be present when using \code{select}.
59
60 \begin{lstlisting}
61 Walker *walker = Walker::newWalker(pid);
62 ProcDebug *debugger = (ProcDebug *) walker->getProcessState();
63 std::vector<Frame> swalk;
64 for (;;) {
65     walker->walkStack(swalk);           
66     struct timeval timeout;
67     timeout.tv_sec = 5;
68     timeout.tv_usec = 0;
69     int max = 1;
70     fd_set readfds, writefds, exceptfds;
71     FD_ZERO(&readfds); FD_ZERO(&writefds); FD_ZERO(&exceptfds);
72     FD_SET(ProcDebug::getNotificationFD(), &readfds);
73     for (;;) {
74         int result = select(max, &readfds, &writefds, &exceptfds, &timeout);
75         if (FD_ISSET(ProcDebug::getNotificationFD(), readfds)) {
76             //Debug event
77             ProcDebug::handleDebugEvent();
78         }
79         if (result == 0) {
80             //Timeout
81             break;
82         }
83     }
84 }
85 \end{lstlisting}
86
87
88 \subsubsection{Class ProcDebug}
89 \label{subsubsec:procdebug}
90 \definedin{procstate.h}
91
92 Access to StackwalkerAPI's debugger is through the \code{ProcDebug} class, which
93 inherits from the \code{ProcessState} interface. The easiest way to get at a
94 \code{ProcDebug} object is to cast the return value of
95 \code{Walker::getProcessState} into a \code{ProcDebug}. C++'s
96 \code{dynamic\_cast} operation can be used to test if a \code{Walker} uses the
97 \code{ProcDebug} interface:
98
99 \begin{lstlisting}
100 ProcDebug *debugger;
101 debugger = dynamic_cast<ProcDebug*>(walker->getProcessState());
102 if (debugger != NULL) {
103     //3rd party
104     ...
105 } else {
106     //1st party
107     ...
108 }
109 \end{lstlisting}
110
111 In addition to the handling of debug events, described in
112 Section~\ref{subsec:debugger}, the \code{ProcDebug} class provides a process
113 control interface; users can pause and resume process or threads, detach from a
114 process, and test for events such as process death. As an implementation of the
115 \code{ProcessState} class, \code{ProcDebug} also provides all of the
116 functionality described in Section~\ref{subsec:processstate}.
117
118 \begin{apient}
119 virtual bool pause(Dyninst::THR_ID tid = NULL_THR_ID)
120 \end{apient}
121 \apidesc{
122     This method pauses a process or thread. The paused object will not resume
123     execution until \code{ProcDebug::resume} is called. If the \code{tid} parameter is not
124     \code{NULL\_THR\_ID} then StackwalkerAPI will pause the thread specified by
125     \code{tid}. If
126     \code{tid} is \code{NULL\_THR\_ID} then StackwalkerAPI will pause every thread in the
127     process.
128
129     When StackwalkerAPI collects a call stack from a running thread it first
130     pauses the thread, collects the stack walk, and then resumes the thread.
131     When collecting a call stack from a paused thread StackwalkerAPI will
132     collect the stack walk and leave the thread paused. This method is thus
133     useful for pausing threads before stack walks if the user needs to keep the
134     returned stack walk synchronized with the current state of the thread.
135
136     This method returns \code{true} if successful and \code{false} on error.
137 }
138
139 \begin{apient}
140 virtual bool resume(Dyninst::THR_ID tid = NULL_THR_ID)
141 \end{apient}
142 \apidesc{
143     This method resumes execution on a paused process or thread. This method
144     only resumes threads that were paused by the \code{ProcDebug::pause} call, using it
145     on other threads is an error. If the \code{tid} parameter is not
146     \code{NULL\_THR\_ID} then
147     StackwalkerAPI will resume the thread specified by \code{tid}. If \code{tid} is
148     \code{NULL\_THR\_ID} then StackwalkerAPI will resume all paused threads in the
149     process.
150
151     This method returns \code{true} if successful and \code{false} on error.
152 }
153
154 \begin{apient}
155 virtual bool detach(bool leave_stopped = false)
156 \end{apient}
157 \apidesc{
158     This method detaches StackwalkerAPI from the target process. StackwalkerAPI
159     will no longer receive debug events on this target process and will no
160     longer be able to collect call stacks from it. This method invalidates the
161     associated \code{Walker} and \code{ProcState} objects, they should be cleaned using C++'s
162     \code{delete} operator after making this call. It is an error to attempt to do
163     operations on these objects after a detach, and undefined behavior may
164     result.
165
166     If the \code{leave\_stopped} parameter is \code{true} StackwalkerAPI will detach from the
167     process but leave it in a paused state so that it does resume progress. This
168     is useful for attaching another debugger back to the process for further
169     analysis. The \code{leave\_stopped} parameter is not supported on the Linux platform
170     and its value will have no affect on the detach call.
171
172     This method returns \code{true} if successful and \code{false} on error.
173 }
174
175 \begin{apient}
176 virtual bool isTerminated()
177 \end{apient}
178 \apidesc{
179     This method returns \code{true} if the associated target process has
180     terminated and \code{false} otherwise. A target process may terminate itself by
181     calling exit, returning from main, or receiving an unhandled signal.
182     Attempting to collect stack walks or perform other operations on a
183     terminated process is illegal an will lead to undefined behavior.
184         
185     A process termination will also be signaled through the notification FD.
186 Users should check processes for the isTerminated state after returning from
187 handleDebugEvent.  
188 }
189
190 \begin{apient}
191 static int getNotificationFD()
192 \end{apient}
193 \apidesc{
194     This method returns StackwalkerAPI's notification FD. The notification FD is
195     a file descriptor that StackwalkerAPI will write a byte to whenever a debug
196     event occurs that need. If the user code sees a byte on this file descriptor
197     it should call \code{handleDebugEvent} to let StackwalkerAPI handle the debug
198     event. Example code using \code{getNotificationFD} can be found in
199     Section~\ref{subsec:debugger}. 
200
201         StackwalkerAPI will only create one notification FD, even if it is attached to multiple 3rd party target processes.
202 }
203
204 \begin{apient}
205 static bool handleDebugEvent(bool block = false)
206 \end{apient}
207 \apidesc{
208     When this method is called StackwalkerAPI will receive and handle all
209     pending debug events from each 3rd party target process to which it is
210     attached. After handling debug events each target process will be continued
211     (unless it was explicitly stopped by the ProcDebug::pause method) and any
212     bytes on the notification FD will be cleared. It is generally expected that
213     users will call this method when a event is sent to the notification FD,
214     although it can be legally called at any time.
215
216     If the \code{block} parameter is \code{true}, then \code{handleDebugEvents}
217     will block until it has handled at least one debug event. If the block
218     parameter is \code{false}, then handleDebugEvents will handle any currently pending
219     debug events or immediately return if none are available. 
220
221     StackwalkerAPI may receive process exit events for target processes while
222     handling debug events. The user should check for any exited processes by
223     calling \code{ProcDebug::isTerminated} after handling debug events.
224
225     This method returns \code{true} if successful and \code{false} on error.
226 }
227     
228 \subsection{FrameSteppers}\label{sec:framesteppers} 
229 \definedin{framestepper.h}
230
231 StackwalkerAPI ships with numerous default implementations of the
232 \code{FrameStepper}
233 class. Each of these \code{FrameStepper} implementations allow StackwalkerAPI to walk a
234 type of call frames. Section~\ref{subsec:defaults} describes which
235 \code{FrameStepper} implementations
236 are available on which platforms. This sections gives a brief description of
237 what each \code{FrameStepper} implementation does. Each of the following classes
238 implements the \code{FrameStepper} interface described in
239 Section~\ref{subsec:framestepper}, so we do not
240 repeat the API description for the classes here.
241
242 Several of the \code{FrameStepper}s use helper classes (see
243 \code{FrameFuncStepper} as an
244 example). Users can further customize the behavior of a \code{FrameStepper} by
245 providing their own implementation of these helper classes.
246
247 \subsubsection{Class FrameFuncStepper}
248 This class implements stack walking through a call frame that is setup with the
249 architectures standard stack frame. For example, on x86 this \code{FrameStepper} will
250 be used to walk through stack frames that are setup with a \code{push \%ebp/mov
251 \%esp,\%ebp} prologue. 
252
253 \paragraph{Class FrameFuncHelper}
254
255 \code{FrameFuncStepper} uses a helper class, \code{FrameFuncHelper}, to get information on
256 what kind of stack frame it's walking through. The \code{FrameFuncHelper} will
257 generally use techniques such as binary analysis to determine what type of stack
258 frame the \code{FrameFuncStepper} is walking through. Users can have StackwalkerAPI use
259 their own binary analysis mechanisms by providing an implementation of this
260 \code{FrameFuncHelper}.
261
262 There are two important types used by \code{FrameFuncHelper} and one important function:
263 \begin{apient}
264 typedef enum {
265     unknown_t=0,
266     no_frame,
267     standard_frame,
268     savefp_only_frame,
269 } frame_type;
270 \end{apient}
271 \apidesc{
272     The \code{frame\_type} describes what kind of stack frame a function uses. If it
273     does not set up a stack frame then \code{frame\_type} should be
274     \code{no\_frame}. If it sets
275     up a standard frame then \code{frame\_type} should be \code{standard\_frame}. The
276     \code{savefp\_only\_frame} value currently only has meaning on the x86 family of
277     systems, and means that a function saves the old frame pointer, but does not
278     setup a new frame pointer (it has a \code{push \%ebp} instruction, but no \code{mov
279     \%esp,\%ebp}). If the \code{FrameFuncHelper} cannot determine the
280     \code{frame\_type}, then it should be assigned the value \code{unknown\_t}. 
281 }
282
283 \begin{apient}
284 typedef enum {
285     unknown_s=0,
286     unset_frame,
287     halfset_frame,
288     set_frame
289 } frame_state;
290 \end{apient}
291 \apidesc{
292     The \code{frame\_state} type determines the current state of function with a stack
293     frame at some point of execution. For example, a function may set up a
294     standard stack frame and have a \code{frame\_type} of \code{standard\_frame}, but execution
295     may be at the first instruction in the function and the frame is not yet
296     setup, in which case the \code{frame\_state} will be \code{unset\_frame}. 
297
298     If the function sets up a standard stack frame and the execution point is
299     someplace where the frame is completely setup, then the \code{frame\_state} should be
300     \code{set\_frame}. If the function sets up a standard frame and the execution point is
301 at a point where the frame does not yet exist or has been torn down, then
302 \code{frame\_state} should be \code{unset\_frame}. The \code{halfset\_frame}
303 value of \code{frame\_state} is
304 currently only meaningful on the x86 family of architecture, and should if the
305 function has saved the old frame pointer, but not yet set up a new frame
306 pointer.        
307 }
308
309 \begin{apient}
310 typedef std::pair<frame_type, frame_state> alloc_frame_t;               
311 virtual alloc_frame_t allocatesFrame(Address addr) = 0;
312 \end{apient}
313 \apidesc{
314     The \code{allocatesFrame} function of \code{FrameFuncHelper} returns a
315     \code{alloc\_frame\_t} that
316     describes the frame\_type of the function at \code{addr} and the
317     \code{frame\_state} of the
318     function when execution reached \code{addr}.
319         
320     If \code{addr} is invalid or an error occurs, allocatedFrame should return
321     \code{alloc\_frame\_t(unknown\_t, unknown\_s)}.  
322 }
323
324 \subsubsection{Class SigHandlerStepper}
325
326 The \code{SigHandlerStepper} is used to walk through UNIX signal handlers as found on
327 the call stack. On some systems a signal handler generates a special kind of
328 stack frame that cannot be walked through using normal stack walking techniques.
329
330
331 \subsubsection{Class DebugStepper}
332
333 This class uses debug information found in a binary to walk through a stack
334 frame. It depends on SymtabAPI to read debug information from a binary, then
335 uses that debug information to walk through a call frame. 
336
337 Most binaries must be built with debug information (\code{-g} with \code{gcc}) in order to
338 include debug information that this \code{FrameStepper} uses. Some languages, such as
339 C++, automatically include stackwalking debug information for use by exceptions.
340 The \code{DebugStepper} class will also make use of this kind of exception
341 information if it is available.
342
343 \subsubsection{Class AnalysisStepper}
344
345 This class uses dataflow analysis to determine possible stack sizes at
346 all locations in a function as well as the location of the frame
347 pointer. It is able to handle optimized code with omitted frame
348 pointers and overlapping code sequences. 
349
350 \subsubsection{Class StepperWanderer}
351
352 This class uses a heuristic approach to find possible return addresses
353 in the stack frame. If a return address is found that matches a valid
354 caller of the current function, we conclude it is the actual return
355 address and construct a matching stack frame. Since this approach is
356 heuristic it can make mistakes leading to incorrect stack
357 information. It has primarily been replaced by the
358 \code{AnalysisStepper} described above. 
359
360 \subsubsection{Class BottomOfStackStepper}
361
362 The \code{BottomOfStackStepper} doesn't actually walk through any type of call frame.
363 Instead it attempts to detect whether the bottom of the call stack has been
364 reached. If so, \code{BottomOfStackStepper} will report \code{gcf\_stackbottom} from its
365 \code{getCallerFrame} method. Otherwise it will report \code{gcf\_not\_me}.
366 \code{BottomOfStackStepper}
367 runs with a higher priority than any other \code{FrameStepper} class.
368