Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / FrameStepper.tex
1 \subsubsection{Class FrameStepper}
2 \definedin{framestepper.h}
3         
4 The \code{FrameStepper} class is an interface that tells StackwalkerAPI how to walk
5 through a specific type of stack frame. There may be many different ways of
6 walking through a stack frame on a platform, e.g, on Linux/x86 there are
7 different mechanisms for walking through system calls, signal handlers, regular
8 functions, and frameless functions. A single \code{FrameStepper} describes how to walk
9 through one of these types of stack frames.
10
11 A user can create their own \code{FrameStepper} classes that tell StackwalkerAPI how to
12 walk through new types of stack frames. A new \code{FrameStepper} object must be added
13 to a \code{StepperGroup} before it can be used. 
14
15 In addition to walking through individual stack frames, a \code{FrameStepper} tells its
16 \code{StepperGroup} when it can be used. The \code{FrameStepper} registers address ranges that
17 cover objects in the target process' code space (such as functions). These
18 address ranges should contain the objects that will create stack frames through
19 which the \code{FrameStepper} can walk. If multiple \code{FrameStepper} objects have
20 overlapping address ranges, then a priority value is used to determine which
21 \code{FrameStepper} should be attempted first.
22
23 \code{FrameStepper} is an interface class; it cannot be instantiated. Users who want to
24 develop new \code{FrameStepper} objects should inherit from this class and implement
25 the below virtual functions.
26
27 \begin{apient}
28 typedef enum { 
29     gcf_success,
30     gcf_stackbottom,
31     gcf_not_me, 
32     gcf_error 
33 } gcframe_ret_t
34 \end{apient}
35
36 \begin{apient}
37 virtual gcframe_ret_t getCallerFrame(const Frame &in, Frame &out) = 0
38 \end{apient}
39 \apidesc{
40 This method walks through a single stack frame and generates a Frame object that
41 represents the caller's stack frame. Parameter in will be a Frame object that
42 this FrameStepper is capable of walking through. Parameter out is an output
43 parameter that this method should set to the Frame object that called in.
44
45 There may be multiple ways of walking through a different types of stack frames.
46 Each \code{FrameStepper} class should be able to walk through a type of stack frame.
47 For example, on x86 one \code{FrameStepper} could be used to walk through stack frames
48 generated by ABI-compliant functions; out's FP and RA are found by reading from
49 in's FP, and out's SP is set to the word below in's FP. A different \code{FrameStepper}
50 might be used to walk through stack frames created by functions that have
51 optimized away their FP. In this case, in may have a FP that does not point
52 out's FP and RA. The \code{FrameStepper} will need to use other mechanisms to discover
53 out's FP or RA; perhaps the \code{FrameStepper} searches through the stack for the RA
54 or performs analysis on the function that created the stack frame.
55
56 If \code{getCallerFrame} successfully walks through in, it is required to set the
57 following parameters in out. See Section~\ref{subsec:frame} for more details on the values
58 that can be set in a Frame object:
59
60 \begin{description}
61     \item [Return Address (RA)] The RA should be set with the
62         \code{Frame::setRA} method.
63     \item [Stack Pointer (SP)] The SP should be set with the \code{Frame::setSP} method.
64     \item [Frame Pointer (FP)] The FP should be set with the \code{Frame::setFP} method
65 \end{description}
66
67 Optionally, getCallerFrame can also set any of following parameters in out:
68 \begin{description}
69     \item [Return Address Location (RALocation)] The RALocation should be set
70         with the \code{Frame::setRALocation()} method.
71     \item [Stack Pointer Location (SPLocation)] The SPLocation should be set
72         with the \code{Frame::setRALocation()} method.
73     \item [Frame Pointer Location (FPLocation)] The FPLocation should be set
74         with the \code{Frame::setFPLocation()} method.
75 \end{description}
76
77 If a location field in out is not set, then the appropriate
78 \code{Frame::getRALocation}, \code{Frame::getSPLocation} or
79 \code{Frame::getFPLocation} method will
80 return \code{loc\_unknown}.
81
82 \code{getCallerFrame} should return \code{gcf\_success} if it successfully walks
83 through in and creates an \code{out} \code{Frame} object. It should return
84 \code{gcf\_stackbottom} if in is the bottom of the stack and there are no stack
85 frames below it. It should return \code{gcf\_not\_me} if in is not the correct
86 type of stack frame for this \code{FrameStepper} to walk through. StackwalkerAPI
87 will then attempt to locate another \code{FrameStepper} to handle \code{in} or
88 abort the stackwalk. It should return \code{gcf\_error} if there was an error
89 and the stack walk should be aborted.
90 }
91
92 \begin{apient}
93 virtual void registerStepperGroup(StepperGroup &steppergroup)
94 \end{apient}
95 \apidesc{
96 This method is used to notify a \code{FrameStepper} when StackwalkerAPI adds it to a
97 \code{StepperGroup}. The \code{StepperGroup} to which this \code{FrameStepper} is being added is
98 passed in parameter steppergroup. This method can be used to initialize the
99 \code{FrameStepper} (in addition to any \code{FrameStepper} constructor).
100 }
101
102 \begin{apient}
103 virtual unsigned getPriority() = 0
104 \end{apient}
105 \apidesc{
106 This method is used by the \code{StepperGroup} to decide which \code{FrameStepper} to use if
107 multiple \code{FrameStepper} objects are registered over the same address range (see
108 addAddressRanges in Section~\ref{subsec:steppergroup} for more information about address ranges).
109 This method returns an integer representing a priority level, the lower the
110 number the higher the priority.
111
112 The default \code{FrameStepper} objects provided by StackwalkerAPI all return
113 priorities between \code{0x1000} and \code{0x2000}. If two \code{FrameStepper} objects have an
114 overlapping address range, and they have the same priority, then the order in
115 which they are used is undefined.
116 }