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