Rebuilt manual PDFs.
[dyninst.git] / stackwalk / doc / 3-API.tex
1 \section{API Reference}
2 \label{sec:api}
3
4 This section describes the StackwalkerAPI interface. It is divided into three
5 sub-sections: a description of the definitions and basic types used by this API,
6 a description of the interface for collecting stackwalks, and a description of
7 the callback interface.
8
9 \subsection{Definitions and Basic Types}
10 The following definitions and basic types are referenced throughout the rest of
11 this manual.
12
13 \subsubsection{Definitions}
14 \label{subsec:definitions}
15 \begin{description}
16
17 \item [Stack Frame] A stack frame is a record of a function (or function-like
18     object) invocation. When a function is executed, it may create a frame on
19     the call stack. StackwalkerAPI finds stack frames and returns a description
20     of them when it walks a call stack.  The following three definitions deal
21     with stack frames.
22
23 \item [Bottom of the Stack] The bottom of the stack is the earliest stack frame
24     in a call stack, usually a thread's initial function. The stack grows from
25     bottom to the top.
26
27 \item [Top of the Stack] The top of the stack is the most recent stack frame in
28     a call stack. The stack frame at the top of the stack is for the currently
29     executing function.
30
31 \item [Frame Object] A Frame object is StackwalkerAPI's representation of a
32     stack frame. A Frame object is a snapshot of a stack frame at a specific
33     point in time. Even if a stack frame changes as a process executes, a Frame
34     object will remain the same. Each Frame object is represented by an instance
35     of the Frame class.
36
37 \end{description}
38
39 The following three definitions deal with fields in a Frame object. 
40 \begin{description}
41
42 \item [SP (Stack Pointer)] A Frame object's SP member points to the top of its
43     stack frame (a stack frame grows from bottom to top, similar to a call
44     stack). The Frame object for the top of the stack has a SP that is equal to
45     the value in the stack pointer register at the time the Frame object was
46     created. The Frame object for any other stack frame has a SP that is equal
47     to the top address in the stack frame. 
48
49 \item [FP (Frame Pointer)] A Frame object's FP member points to the beginning
50     (or bottom) of its stack frame. The Frame object for the top of the stack
51     has a FP that is equal to the value in the frame pointer register at the
52     time the Frame object was created. The Frame object for any other stack
53     frame has a FP that is equal to the beginning of the stack frame.
54     
55 \item [RA (Return Address)] A Frame object's RA member points to the location in
56     the code space where control will resume when the function that created the
57     stack frame resumes. The Frame object for the top of the stack has a RA that
58     is equal to the value in the program counter register at the time the Frame
59     object was created.  The Frame object for any other stack frame has a RA
60     that is found when walking a call stack.
61
62 \end{description}
63
64 \input{fig/layout}
65 \input{fig/layout-armv8}
66
67 Figure~\ref{fig:layout} shows the relationship between application code, stack
68 frames, and Frame objects. In the figure, the source code on the left has run
69 through the main and foo functions, and into the bar function. It has created
70 the call stack in the center, which is shown as a sequence of words growing
71 down. The current values of the processor registers, while executing in bar, are
72 shown below the call stack. When StackwalkerAPI walks the call stack, it creates
73 the Frame objects shown on the right. Each Frame object corresponds to one of
74 the stack frames found in the call stack or application registers.  
75
76 The call stack in Figure~\ref{fig:layout} is similar to one that would be found
77 on the x86 architecture. Details about how the call stack is laid out may be
78 different on other architectures, but the meanings of the FP, SP, and RA fields
79 in the Frame objects will remain the same. The layout of the ARM64 stack may be found in Figure~\ref{fig:layout-armv8} as an example of the scope of architectural variations.
80
81
82 The following four definitions deal with processes involved in StackwalkerAPI.
83 \begin{description}
84
85 \item [Target Process] The process from which StackwalkerAPI is collecting
86     stackwalks.
87
88 \item [Host Process] The process in which StackwalkerAPI code is currently
89     running.
90
91 \item [First Party Stackwalk] StackwalkerAPI collects first party stackwalk when
92     it walks a call stack in the same address space it is running in, i.e. the
93     target process is the same as the host process.
94
95 \item [Third Party Stackwalk] StackwalkerAPI collects third party stackwalk when
96     it walks the call stack in a different address space from the one it is
97     running in, i.e. the target process is different from the host process. A
98     third party stackwalk is usually done through a debugger interface.
99
100 \end{description}
101
102 \subsubsection{Basic Types}
103
104 \begin{apient}
105 typedef unsigned long Address
106 \end{apient}
107 \apidesc{
108     An integer value capable of holding an address in the target process.
109     Address variables should not, and in many cases cannot, be used directly as
110     a pointer. It may refer to an address in a different process, and it may not
111     directly match the target process' pointer representation. Address is
112     guaranteed to be at least large enough to hold an address in a target
113     process, but may be larger.
114 }
115 \begin{apient}
116 typedef ... Dyninst::PID
117 \end{apient}
118 \apidesc{
119         A handle for identifying a process. On UNIX systems this will be an integer representing a PID. On Windows this will be a HANDLE object.
120 }
121 \begin{apient}
122 typedef ... Dyninst::THR_ID
123 \end{apient}
124 \apidesc{
125         A handle for identifying a thread. On Linux and BlueGene platforms this is an integer referring to a TID (Thread Identifier). On Windows it is a HANDLE object.
126 }
127
128 \begin{apient}
129 class Dyninst::MachRegister
130 \end{apient}
131 \apidesc{
132         A value that names a machine register.
133 }
134
135 \begin{apient}
136 typedef unsigned long Dyninst::MachRegisterVal
137 \end{apient}
138 \apidesc{
139         A value that holds the contents of a register. A Dyninst::MachRegister names a specific register, while a Dyninst::MachRegisterVal represents the value that may be in that register.
140 }    
141     
142 \subsection{Namespace StackwalkerAPI}
143 The classes in Section~\ref{sec:stackwalking-interface} and
144 Section~\ref{sec:callback-interface} fall under the C++ namespace
145 Dyninst::Stackwalker. To access them, a user should refer to them using the
146 Dyninst::Stackwalker:: prefix, e.g. Dyninst::Stackwalker::Walker. Alternatively,
147 a user can add the C++ using keyword above any references to StackwalkerAPI
148 objects, e.g, using namespace Dyninst and using namespace Stackwalker.
149     
150 \subsection{Stackwalking Interface}
151 \label{sec:stackwalking-interface}
152
153 This section describes StackwalkerAPI's interface for walking a call stack. This
154 interface is sufficient for walking call stacks on all the systems and
155 variations covered by our default callbacks. 
156
157 To collect a stackwalk, first create new Walker object associated with the target process via
158
159 \begin{lstlisting}
160     Walker::newWalker()
161 \end{lstlisting}
162         or 
163 \begin{lstlisting}
164     Walker::newWalker(Dyninst::PID pid)
165 \end{lstlisting}
166
167 Once a Walker object has been created, a call stack can be walked with the
168 \begin{lstlisting}
169 Walker::walkStack
170 \end{lstlisting}
171 method. The new stack walk is returned as a vector of Frame objects.
172     
173 \input{API/Walker}
174 \input{API/Frame}
175
176 \subsection{Accessing Local Variables}
177 \definedin{local\_var.h}
178         
179 StackwalkerAPI can be used to access local variables found in the frames of a
180 call stack. The StackwalkerAPI interface for accessing the values of local
181 variables is closely tied to the SymtabAPI interface for collecting information
182 about local variables--SymtabAPI handles for functions, local variables, and
183 types are part of this interface. 
184
185 Given an initial handle to a SymtabAPI Function object, SymtabAPI can look up
186 local variables contained in that function and the types of those local
187 variables. See the SymtabAPI Programmer's Guide for more information.
188
189 \begin{apient}
190 static Dyninst::SymtabAPI::Function *getFunctionForFrame(Frame f)
191 \end{apient}
192 \apidesc{
193 This method returns a SymtabAPI function handle for the function that created the call stack frame, f. 
194 }
195
196 \begin{apient}
197 static int glvv_Success = 0;
198 static int glvv_EParam = -1;
199 static int glvv_EOutOfScope = -2;
200 static int glvv_EBufferSize = -3;
201 static int glvv_EUnknown = -4;
202 \end{apient}
203
204 \begin{apient}
205 static int getLocalVariableValue(Dyninst::SymtabAPI::localVar *var,
206                                  std::vector<Frame> &swalk,
207                                  unsigned frame,
208                                  void *out_buffer,
209                                  unsigned out_buffer_size)
210 \end{apient}
211 \apidesc{
212     Given a local variable and a stack frame from a call stack, this function
213     returns the value of the variable in that frame. The local variable is
214     specified by the SymtabAPI variable object, \code{var}. \code{swalk} is a
215     call stack that was collected via StackwalkerAPI, and \code{frame} specifies
216     an index into that call stack that contains the local variable. The value of
217     the variable is stored in \code{out\_buffer} and the size of
218     \code{out\_buffer} should be specified in \code{out\_buffer\_size}.
219         
220     A local variable only has a limited scope with-in a target process'
221     execution. StackwalkerAPI cannot guarantee that it can collect the correct
222     return value of a local variable from a call stack if the target process is
223     continued after the call stack is collected.
224         
225     Finding and collecting the values of local variables is dependent on
226     debugging information being present in a target process' binary. Not all
227     binaries contain debugging information, and in some cases, such as for
228     binaries built with high compiler optimization levels, that debugging
229     information may be incorrect.
230
231     \code{getLocalVariableValue} will return on of the following values:
232     \begin{description}
233     
234         \item [glvv\_Success] getLocalVariableValue was able to correctly read
235             the value of the given variable.
236    
237         \item [glvv\_EParam] An error occurred, an incorrect parameter was
238             specified (frame was larger than \code{swalk.size()}, or var was not a
239             variable in the function specified by frame).
240     
241         \item [glvv\_EOutOfScope] An error occurred, the specified variable
242             exists in the function but isn't live at the current execution
243             point.
244     
245         \item [glvv\_EBufferSize] An error occurred, the variable's value does
246             not fit inside \code{out\_buffer}. 
247     
248         \item [glvv\_EUnknown] An unknown error occurred. It is most likely that
249             the local variable was optimized away or debugging information about
250             the variable was incorrect.
251     
252     \end{description} 
253 }
254
255 \subsection{Callback Interface}
256 \label{sec:callback-interface}
257 This subsection describes the Callback Interface for StackwalkerAPI. The
258 Callback Interface is primarily used to port StackwalkerAPI to new platforms,
259 extend support for new types of stack frames, or integrate StackwalkerAPI into
260 existing tools.
261
262 The classes in this subsection are interfaces, they cannot be instantiated.  To
263 create a new implementation of one of these interfaces, create a new class that
264 inherits from the callback class and implement the necessary methods. To use a
265 new ProcessState, StepperGroup, or SymbolLookup class with StackwalkerAPI,
266 create a new instance of the class and register it with a new Walker object
267 using the
268 \begin{lstlisting}
269 Walker::newWalker(ProcessState *, StepperGroup *, SymbolLookup *)
270 \end{lstlisting}        
271 factory method (see Section~\ref{subsec:walker}). To use a new FrameStepper class with
272 StackwalkerAPI, create a new instance of the class and register it with a
273 StepperGroup using the
274 \begin{lstlisting}
275 StepperGroup::addStepper(FrameStepper *)
276 \end{lstlisting}
277 method (see Section~\ref{subsec:steppergroup}).
278
279 Some of the classes in the Callback Interface have methods with default
280 implementations. A new class that inherits from a Callback Interface can
281 optionally implement these methods, but it is not required. If a method requires
282 implementation, it is written as a C++ pure virtual method (\code{virtual funcName() =
283 0}). A method with a default implementation is written as a C++ virtual method
284 (\code{virtual funcName()}).
285
286 \subsubsection{Default Implementations}
287 \label{subsec:defaults}
288
289 The classes described in the Callback Interface are C++ abstract classes, or
290 interfaces. They cannot be instantiated. For each of these classes
291 StackwalkerAPI provides one or more default implementations on each platform.
292 These default implementations are classes that inherit from the abstract classes
293 described in the Callback Interface. If a user creates a Walker object without
294 providing their own \code{FrameStepper}, \code{ProcessState}, and
295 \code{SymbolLookup} objects, then StackwalkerAPI will use the default
296 implementations listed in Table~\ref{table:defaults}. These
297 implementations are described in Section \ref{sec:framesteppers}.
298
299 \begin{table}
300 \begin{tabular}{| l | l | l | l | l |}
301     \hline
302                     &   StepperGroup    & ProcessState      &   SymbolLookup    &   FrameStepper\\
303     \hline
304     Linux/x86       &   1. AddrRange    &   1. ProcSelf     &   1. SwkSymtab    &   1. FrameFuncStepper\\
305     Linux/x86-64    &                   &   2. ProcDebug    &                   &   2. SigHandlerStepper\\
306                     &                   &                   &                   &   3. DebugStepper\\
307                     &                   &                   &                   &   4. AnalysisStepper\\ 
308                     &                   &                   &                   &   5. StepperWanderer\\
309                     &                   &                   &                   &   6. BottomOfStackStepper\\
310    \hline
311     Linux/PPC       &   1. AddrRange    &   1. ProcSelf     &   1. SwkSymtab    & 1. FrameFuncStepper\\
312     Linux/PPC-64    &                   &   2. ProcDebug    &                   & 2. SigHandlerStepper\\
313                     &                   &                   &                   & 3. AnalysisStepper\\
314     \hline
315     Windows/x86     &   1. AddrRange    &   1. ProcSelf     &   1. SwkSymtab    & 1. FrameFuncStepper\\
316                     &                   &   2. ProcDebug    &                   & 2. AnalysisStepper \\
317                     &                   &                   &                   & 3. StepperWanderer\\
318                     &                   &                   &                   & 4. BottomOfStackStepper\\
319     \hline  
320     BlueGene        &   1. AddrRange    &   1. ProcDebug    &   1. SwkSymtab    & 1. FrameFuncStepper\\
321     \hline
322 \end{tabular}
323 \caption{Callback Interface Defaults}
324 \label{table:defaults}
325 \end{table}
326
327 \input{API/FrameStepper}
328 \input{API/StepperGroup}
329 \input{API/ProcessState}
330 \input{API/SymbolLookup}
331