Add initial support for analyzing AMDGPU binaries (#900)
[dyninst.git] / stackwalk / doc / API / FrameStepper.tex
1 \subsubsection{Class FrameStepper}\label{subsec: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 the desired virtual functions. The \code{getCallerFrame,
26   getPriority}, and \code{getName} functions must be implemented; all
27 others may be overridden if desired. 
28
29 \begin{apient}
30 typedef enum { 
31     gcf_success,
32     gcf_stackbottom,
33     gcf_not_me, 
34     gcf_error 
35 } gcframe_ret_t
36 \end{apient}
37
38 \begin{apient}
39 virtual gcframe_ret_t getCallerFrame(const Frame &in, Frame &out) = 0
40 \end{apient}
41 \apidesc{
42 This method walks through a single stack frame and generates a Frame object that
43 represents the caller's stack frame. Parameter in will be a Frame object that
44 this FrameStepper is capable of walking through. Parameter out is an output
45 parameter that this method should set to the Frame object that called in.
46
47 There may be multiple ways of walking through a different types of stack frames.
48 Each \code{FrameStepper} class should be able to walk through a type of stack frame.
49 For example, on x86 one \code{FrameStepper} could be used to walk through stack frames
50 generated by ABI-compliant functions; out's FP and RA are found by reading from
51 in's FP, and out's SP is set to the word below in's FP. A different \code{FrameStepper}
52 might be used to walk through stack frames created by functions that have
53 optimized away their FP. In this case, in may have a FP that does not point
54 out's FP and RA. The \code{FrameStepper} will need to use other mechanisms to discover
55 out's FP or RA; perhaps the \code{FrameStepper} searches through the stack for the RA
56 or performs analysis on the function that created the stack frame.
57
58 If \code{getCallerFrame} successfully walks through in, it is required to set the
59 following parameters in out. See Section~\ref{subsec:frame} for more details on the values
60 that can be set in a Frame object:
61
62 \begin{description}
63     \item [Return Address (RA)] The RA should be set with the
64         \code{Frame::setRA} method.
65     \item [Stack Pointer (SP)] The SP should be set with the \code{Frame::setSP} method.
66     \item [Frame Pointer (FP)] The FP should be set with the \code{Frame::setFP} method
67 \end{description}
68
69 Optionally, getCallerFrame can also set any of following parameters in out:
70 \begin{description}
71     \item [Return Address Location (RALocation)] The RALocation should be set
72         with the \code{Frame::setRALocation()} method.
73     \item [Stack Pointer Location (SPLocation)] The SPLocation should be set
74         with the \code{Frame::setRALocation()} method.
75     \item [Frame Pointer Location (FPLocation)] The FPLocation should be set
76         with the \code{Frame::setFPLocation()} method.
77 \end{description}
78
79 If a location field in out is not set, then the appropriate
80 \code{Frame::getRALocation}, \code{Frame::getSPLocation} or
81 \code{Frame::getFPLocation} method will
82 return \code{loc\_unknown}.
83
84 \code{getCallerFrame} should return \code{gcf\_success} if it successfully walks
85 through in and creates an \code{out} \code{Frame} object. It should return
86 \code{gcf\_stackbottom} if in is the bottom of the stack and there are no stack
87 frames below it. It should return \code{gcf\_not\_me} if in is not the correct
88 type of stack frame for this \code{FrameStepper} to walk through. StackwalkerAPI
89 will then attempt to locate another \code{FrameStepper} to handle \code{in} or
90 abort the stackwalk. It should return \code{gcf\_error} if there was an error
91 and the stack walk should be aborted.
92 }
93
94 \begin{apient}
95 virtual void registerStepperGroup(StepperGroup *steppergroup)
96 \end{apient}
97 \apidesc{
98 This method is used to notify a \code{FrameStepper} when StackwalkerAPI adds it to a
99 \code{StepperGroup}. The \code{StepperGroup} to which this \code{FrameStepper} is being added is
100 passed in parameter steppergroup. This method can be used to initialize the
101 \code{FrameStepper} (in addition to any \code{FrameStepper} constructor).
102 }
103
104 \begin{apient}
105 virtual unsigned getPriority() const = 0
106 \end{apient}
107 \apidesc{
108 This method is used by the \code{StepperGroup} to decide which \code{FrameStepper} to use if
109 multiple \code{FrameStepper} objects are registered over the same address range (see
110 addAddressRanges in Section~\ref{subsec:steppergroup} for more information about address ranges).
111 This method returns an integer representing a priority level, the lower the
112 number the higher the priority.
113
114 The default \code{FrameStepper} objects provided by StackwalkerAPI all return
115 priorities between \code{0x1000} and \code{0x2000}. If two \code{FrameStepper} objects have an
116 overlapping address range, and they have the same priority, then the order in
117 which they are used is undefined.
118 }
119
120 \begin{apient}
121 FrameStepper(Walker *w);
122 \end{apient}
123 \apidesc{Constructor definition for all \code{FrameStepper}
124   instances.}
125
126 \begin{apient}
127 virtual ProcessState *getProcessState();
128 \end{apient}
129 \apidesc{Return the \code{ProcessState} used by the
130   \code{FrameStepper}. Can be overridden if the user desires.}
131
132 \begin{apient}
133 virtual Walker *getWalker();
134 \end{apient}
135
136 \apidesc{Return the \code{Walker} associated with the
137   \code{FrameStepper}. Can be overridden if the user desires.}
138
139 \begin{apient}
140 typedef std::pair<std::string, Address> LibAddrPair;
141 typedef enum { library_load, library_unload } lib_change_t;
142 virtual void newLibraryNotification(LibAddrPair *libAddr, 
143                                     lib_change_t change);
144 \end{apient}
145
146 \apidesc{This function is called when a new library is loaded by the
147 process; it should be implemented if the \code{FrameStepper} requires
148 such information.}
149
150 \begin{apient}
151 virtual const char *getName() const = 0;
152 \end{apient}
153
154 \apidesc{Returns a name for the \code{FrameStepper}; must be
155   implemented by the user.}