Add compiler-specific search directories in getResolvedLibraryPath (#732)
[dyninst.git] / parseAPI / doc / API / CodeObject.tex
1 \subsection{Class CodeObject}
2
3 \definedin{CodeObject.h}
4
5 The CodeObject class describes an individual binary code object, such as an
6 executable or library. It is the top-level container for parsing the object as
7 well as accessing that parse data. The following API routines and data types
8 are provided to support parsing and retrieving parsing products.
9
10 \begin{apient}
11
12 typedef std::set<Function *, Function::less> funclist
13 \end{apient}
14 \apidesc{Container for access to functions. Refer to Section \ref{sec:containers} for details. Library users \emph{must not} rely on the underlying container type of std::set, as it is subject to change.}
15
16 \begin{apient}
17 CodeObject(CodeSource * cs,
18            CFGFactory * fact = NULL,
19            ParseCallback * cb = NULL,
20            bool defensiveMode = false)
21 \end{apient}
22 \apidesc{Constructs a new CodeObject from the provided CodeSource and
23 optional object factory and callback handlers. Any parsing hints provided
24 by the CodeSource are processed, but the binary is not parsed when this
25 constructor returns.
26
27 \medskip\noindent The \code{defensiveMode}
28 parameter optionally trades off coverage for safety; this mode is not
29 recommended for most applications as it makes very conservative assumptions
30 about control flow transfer instructions (see Section \ref{sec:defmode}).}
31
32 \begin{apient}
33 void parse()
34 \end{apient}
35 \apidesc{Recursively parses the binary represented by this CodeObject from all
36 known function entry points (i.e., the hints provided by the CodeSource). This
37 method and the following parsing methods may safely be invoked repeatedly if
38 new information about function locations is provided through the CodeSource.
39 Note that these parsing methods do not automatically perform speculative gap parsing.
40 parseGaps should be used for this purpose.}
41
42 \begin{apient}
43 void parse(Address target,
44            bool recursive)
45 \end{apient}
46 \apidesc{Parses the binary starting with the instruction at the provided target address. If \code{recursive} is {\scshape true}, recursive traversal parsing is used as in the default \code{parse()} method; otherwise only instructions reachable through intraprocedural control flow are visited.}
47
48 \begin{apient}
49 void parse(CodeRegion * cr,
50            Address target,
51            bool recursive)
52 \end{apient}
53 \apidesc{Parses the specified core region of the binary starting with the 
54 instruction at the provided target address. If \code{recursive} is 
55 {\scshape true}, recursive traversal parsing is used as in the default 
56 \code{parse()} method; otherwise only instructions reachable through 
57 intraprocedural control flow are visited.
58 }
59
60 \begin{apient}
61 struct NewEdgeToParse {
62     Block *source;
63     Address target;
64     EdgeTypeEnum type;
65 }
66 bool parseNewEdges( vector<NewEdgeToParse> & worklist )
67 \end{apient}
68 \apidesc{Parses a set of newly created edges specified in the worklist supplied 
69 that were not included when the function was originally parsed. 
70 }
71
72 ParseAPI is able to speculatively parse gaps 
73 (regions of binary that has not been identified as code or data yet)
74 to identify function entry points and
75 perform control flow traversal.
76
77 \begin{center}
78 \begin{tabular}{lp{10cm}}
79 \toprule
80 GapParsingType & Technique description \\
81 \midrule
82 PreambleMatching & If instruction patterns are matched at an adderss, the address is a function entry point  \\
83 IdiomMatching & Based on a pre-trained model, this technique calculates the probability of an address to be a function entry point and predicts whether which addresses are function entry points\\
84 \bottomrule
85 \end{tabular}
86 \end{center}
87
88 \begin{apient}
89 void parseGaps(CodeRegion *cr,
90                GapParsingType type=IdiomMatching)
91 \end{apient}
92 \apidesc{Speculatively parse the indicated region of the binary using the specified technique to find likely function entry points, enabled on the x86 and x86-64 platforms.}
93
94 \begin{apient}
95 Function * findFuncByEntry(CodeRegion * cr,
96                            Address entry)
97 \end{apient}
98 \apidesc{Find the function starting at address \code{entry} in the indicated CodeRegion. Returns {\scshape null} if no such function exists.}
99
100 \begin{apient}
101 int findFuncs(CodeRegion * cr,
102               Address addr,
103               std::set<Function*> & funcs)
104 \end{apient}
105 \apidesc{Finds all functions spanning \code{addr} in the code region, adding each to \code{funcs}. The number of results of this stabbing query are returned.}
106
107 \begin{apient}
108 int findFuncs(CodeRegion * cr,
109               Address start,
110               Address end,
111               std::set<Function*> & funcs)
112 \end{apient}
113 \apidesc{Finds all functions overlapping the range \code{[start,end)} in the code region, adding each to \code{funcs}. The number of results of this stabbing query are returned.}
114
115 \begin{apient}
116 const funclist & funcs()
117 \end{apient}
118 \apidesc{Returns a const reference to a container of all functions in the binary. Refer to Section \ref{sec:containers} for container access details.}
119
120 \begin{apient}
121 Block * findBlockByEntry(CodeRegion * cr,
122                          Address entry)
123 \end{apient}
124 \apidesc{Find the basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
125
126 \begin{apient}
127 int findBlocks(CodeRegion * cr,
128                Address addr,
129                std::set<Block*> & blocks)
130 \end{apient}
131 \apidesc{Finds all blocks spanning \code{addr} in the code region, adding each to \code{blocks}. Multiple blocks can be returned only on platforms with variable-length instruction sets (such as IA32) for which overlapping instructions are possible; at most one block will be returned on all other platforms.}
132
133 \begin{apient}
134 Block * findNextBlock(CodeRegion * cr,
135                       Address addr)
136 \end{apient}
137 \apidesc{Find the next reachable basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
138
139 \begin{apient}
140 CodeSource * cs()
141 \end{apient}
142 \apidesc{Return a reference to the underlying CodeSource.}
143
144 \begin{apient}
145 CFGFactory * fact()
146 \end{apient}
147 \apidesc{Return a reference to the CFG object factory.}
148
149 \begin{apient}
150 bool defensiveMode()
151 \end{apient}
152 \apidesc{Return a boolean specifying whether or not defensive mode is enabled.}
153
154 \begin{apient}
155 bool isIATcall(Address insn,
156                std::string &calleeName)
157 \end{apient}
158 \apidesc{Returns a boolean specifying if the address at \code{addr} is located at the call named in \code{calleeName}. }
159
160 \begin{apient}
161 void startCallbackBatch()
162 \end{apient}
163 \apidesc{Starts a batch of callbacks that have been registered.}
164
165 \begin{apient}
166 void finishCallbackBatch()
167 \end{apient}
168 \apidesc{Completes all callbacks in the current batch.}
169
170 \begin{apient}
171 void registerCallback(ParseCallback *cb);
172 \end{apient}
173 \apidesc{Register a callback \code{cb}}
174
175 \begin{apient}
176 void unregisterCallback(ParseCallback *cb);
177 \end{apient}
178 \apidesc{Unregister an existing callback \code{cb}}
179
180
181 \begin{apient}
182 void finalize()
183 \end{apient}
184 \apidesc{Force complete parsing of the CodeObject; parsing operations are otherwise completed only as needed to answer queries.}
185
186 \begin{apient}
187 void destroy(Edge *)
188 \end{apient}
189 \apidesc{Destroy the edge listed.}
190
191 \begin{apient}
192 void destroy(Block *)
193 \end{apient}
194 \apidesc{Destroy the code block listed.}
195
196 \begin{apient}
197 void destroy(Function *)
198 \end{apient}
199 \apidesc{Destroy the function listed.}
200