1. Add probabilistic parsing, which contains 32-bit Linux, 64-bit Linux, and 32-bit...
[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
40 \begin{apient}
41 void parse(Address target,
42            bool recursive)
43 \end{apient}
44 \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.}
45
46 \begin{apient}
47 void parse(CodeRegion * cr,
48            Address target,
49            bool recursive)
50 \end{apient}
51 \apidesc{Parses the specified core region of the binary starting with the 
52 instruction at the provided target address. If \code{recursive} is 
53 {\scshape true}, recursive traversal parsing is used as in the default 
54 \code{parse()} method; otherwise only instructions reachable through 
55 intraprocedural control flow are visited.
56 }
57
58 \begin{apient}
59 struct NewEdgeToParse {
60     Block *source;
61     Address target;
62     EdgeTypeEnum type;
63 }
64 bool parseNewEdges( vector<NewEdgeToParse> & worklist )
65 \end{apient}
66 \apidesc{Parses a set of newly created edges specified in the worklist supplied 
67 that were not included when the function was originally parsed. 
68 }
69
70 ParseAPI is able to speculatively parse gaps 
71 (regions of binary that has not been identified as code or data yet)
72 to identify function entry points and
73 perform control flow traversal.
74
75 \begin{center}
76 \begin{tabular}{lp{10cm}}
77 \toprule
78 GapParsingType & Technique description \\
79 \midrule
80 PreambleMatching & If instruction patterns are matched at an adderss, the address is a function entry point  \\
81 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\\
82 \bottomrule
83 \end{tabular}
84 \end{center}
85
86 \begin{apient}
87 void parseGaps(CodeRegion *cr,
88                GapParsingType type=IdiomMatching)
89 \end{apient}
90 \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.}
91
92 \begin{apient}
93 Function * findFuncByEntry(CodeRegion * cr,
94                            Address entry)
95 \end{apient}
96 \apidesc{Find the function starting at address \code{entry} in the indicated CodeRegion. Returns {\scshape null} if no such function exists.}
97
98 \begin{apient}
99 int findFuncs(CodeRegion * cr,
100               Address addr,
101               std::set<Function*> & funcs)
102 \end{apient}
103 \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.}
104
105 \begin{apient}
106 int findFuncs(CodeRegion * cr,
107               Address start,
108               Address end,
109               std::set<Function*> & funcs)
110 \end{apient}
111 \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.}
112
113 \begin{apient}
114 funclist & funcs()
115 \end{apient}
116 \apidesc{Returns a reference to a container of all functions in the binary. Refer to Section \ref{sec:containers} for container access details.}
117
118 \begin{apient}
119 Block * findBlockByEntry(CodeRegion * cr,
120                          Address entry)
121 \end{apient}
122 \apidesc{Find the basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
123
124 \begin{apient}
125 int findBlocks(CodeRegion * cr,
126                Address addr,
127                std::set<Block*> & blocks)
128 \end{apient}
129 \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.}
130
131 \begin{apient}
132 Block * findNextBlock(CodeRegion * cr,
133                       Address addr)
134 \end{apient}
135 \apidesc{Find the next reachable basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
136
137 \begin{apient}
138 CodeSource * cs()
139 \end{apient}
140 \apidesc{Return a reference to the underlying CodeSource.}
141
142 \begin{apient}
143 CFGFactory * fact()
144 \end{apient}
145 \apidesc{Return a reference to the CFG object factory.}
146
147 \begin{apient}
148 bool defensiveMode()
149 \end{apient}
150 \apidesc{Return a boolean specifying whether or not defensive mode is enabled.}
151
152 \begin{apient}
153 bool isIATcall(Address insn,
154                std::string &calleeName)
155 \end{apient}
156 \apidesc{Returns a boolean specifying if the address at \code{addr} is located at the call named in \code{calleeName}. }
157
158 \begin{apient}
159 void startCallbackBatch()
160 \end{apient}
161 \apidesc{Starts a batch of callbacks that have been registered.}
162
163 \begin{apient}
164 void finishCallbackBatch()
165 \end{apient}
166 \apidesc{Completes all callbacks in the current batch.}
167
168 \begin{apient}
169 void finalize()
170 \end{apient}
171 \apidesc{Force complete parsing of the CodeObject; parsing operations are otherwise completed only as needed to answer queries.}
172
173 \begin{apient}
174 void destroy(Edge *)
175 \end{apient}
176 \apidesc{Destroy the edge listed.}
177
178 \begin{apient}
179 void destroy(Block *)
180 \end{apient}
181 \apidesc{Destroy the code block listed.}
182
183 \begin{apient}
184 void destroy(Function *)
185 \end{apient}
186 \apidesc{Destroy the function listed.}
187