ParseAPI documentation updates
[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, bool recursive)
42 \end{apient}
43 \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.}
44
45 \begin{apient}
46 void parse(CodeRegion * cr, Address target, bool recursive)
47 \end{apient}
48 \apidesc{Parses the specified core region of the binary starting with the 
49 instruction at the provided target address. If \code{recursive} is 
50 {\scshape true}, recursive traversal parsing is used as in the default 
51 \code{parse()} method; otherwise only instructions reachable through 
52 intraprocedural control flow are visited.
53 }
54
55 \begin{apient}
56 struct NewEdgeToParse {
57     Block *source;
58     Address target;
59     EdgeTypeEnum type;
60 };
61 bool parseNewEdges( vector<NewEdgeToParse> & worklist );
62 \end{apient}
63 \apidesc{Parses a set of newly created edges specified in the worklist supplied 
64 that were not included when the function was originally parsed. 
65 }
66
67 \begin{apient}
68 void parseGaps(CodeRegion *cr)
69 \end{apient}
70 \apidesc{Speculatively parse the indicated region of the binary using pattern matching to find likely function entry points. Only enabled on the x86 32-bit platform.}
71
72 \begin{apient}
73 Function * findFuncByEntry(CodeRegion * cr, Address entry)
74 \end{apient}
75 \apidesc{Find the function starting at address \code{entry} in the indicated CodeRegion. Returns {\scshape null} if no such function exists.}
76
77 \begin{apient}
78 int findFuncs(CodeRegion * cr, Address addr, std::set<Function*> & funcs)
79 \end{apient}
80 \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.}
81
82 \begin{apient}
83 int findFuncs(CodeRegion * cr, Address start, Address end, std::set<Function*> & funcs)
84 \end{apient}
85 \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.}
86
87 \begin{apient}
88 funclist & funcs()
89 \end{apient}
90 \apidesc{Returns a reference to a container of all functions in the binary. Refer to Section \ref{sec:containers} for container access details.}
91
92 \begin{apient}
93 Block * findBlockByEntry(CodeRegion * cr, Address entry)
94 \end{apient}
95 \apidesc{Find the basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
96
97 \begin{apient}
98 int findBlocks(CodeRegion * cr, Address addr, std::set<Block*> & blocks)
99 \end{apient}
100 \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.}
101
102 \begin{apient}
103 Block * findNextBlock(CodeRegion * cr, Address addr)
104 \end{apient}
105 \apidesc{Find the next reachable basic block starting at address \code{entry}. Returns {\scshape null} if no such block exists.}
106
107 \begin{apient}
108 CodeSource * cs()
109 \end{apient}
110 \apidesc{Return a reference to the underlying CodeSource.}
111
112 \begin{apient}
113 CFGFactory * fact()
114 \end{apient}
115 \apidesc{Return a reference to the CFG object factory.}
116
117 \begin{apient}
118 bool defensiveMode()
119 \end{apient}
120 \apidesc{Return a boolean specifying whether or not defensive mode is enabled.}
121
122 \begin{apient}
123 bool isIATcall(Address insn, std::string &calleeName)
124 \end{apient}
125 \apidesc{Returns a boolean specifying if the address at \code{addr} is located at the call named in \code{calleeName}. }
126
127 \begin{apient}
128 void startCallbackBatch()
129 \end{apient}
130 \apidesc{Starts a batch of callbacks that have been registered.}
131
132 \begin{apient}
133 void finishCallbackBatch()
134 \end{apient}
135 \apidesc{Completes all callbacks in the current batch.}
136
137 \begin{apient}
138 void finalize()
139 \end{apient}
140 \apidesc{Force complete parsing of the CodeObject; parsing operations are otherwise completed only as needed to answer queries.}
141
142 \begin{apient}
143 void destroy(Edge *)
144 \end{apient}
145 \apidesc{Destroy the edge listed.}
146
147 \begin{apient}
148 void destroy(Block *)
149 \end{apient}
150 \apidesc{Destroy the code block listed.}
151
152 \begin{apient}
153 void destroy(Function *)
154 \end{apient}
155 \apidesc{Destroy the function listed.}
156