Experimental: support parsing of indirect tail calls when they appear as a function...
[dyninst.git] / parseAPI / doc / 5-Extending.tex
1 \section{Extending ParseAPI}
2 \label{sec:extend}
3
4 The ParseAPI is design to be a low level toolkit for binary analysis tools.
5 Users can extend the ParseAPI in two ways: by extending the control flow
6 structures (Functions, Blocks, and Edges) to incorporate additional data to
7 support various analysis applications, and by adding additional binary code
8 sources that are unsupported by the default SymtabAPI-based code source. For
9 example, a code source that represents a program image in memory could be
10 implemented by fulfilling the CodeSource and InstructionSource interfaces
11 described in Section \ref{sec:codesource} and below. Implementations that
12 extend the CFG structures need only provide a custom allocation factory in
13 order for these objects to be allocated during parsing.
14
15 \subsection{Instruction and Code Sources}
16
17 A CodeSource, as described above, exports its own and the InstructionSource interface for access to binary code and other details. In addition to implementing the virtual methods in the CodeSource base class (Section \ref{sec:codesource}), the methods in the pure-virtual InstructionSource class must be implemented:
18
19 \begin{apient}
20 virtual bool isValidAddress(const Address) 
21 \end{apient}
22 \apidesc{Returns {\scshape true} if the address is a valid code location.}
23
24 \begin{apient}
25 virtual void* getPtrToInstruction(const Address)
26 \end{apient}
27 \apidesc{Returns pointer to raw memory in the binary at the provided address.}
28
29 \begin{apient}
30 virtual void* getPtrToData(const Address)
31 \end{apient}
32 \apidesc{Returns pointer to raw memory in the binary at the provided address. The address need not correspond to an executable code region.}
33
34 \begin{apient}
35 virtual unsigned int getAddressWidth()
36 \end{apient}
37 \apidesc{Returns the address width (e.g. four or eight bytes) for the represented binary.}
38
39 \begin{apient}
40 virtual bool isCode(const Address)
41 \end{apient}
42 \apidesc{Indicates whether the location is in a code region.}
43
44 \begin{apient}
45 virtual bool isData(const Address)
46 \end{apient}
47 \apidesc{Indicates whether the location is in a data region.}
48
49 \begin{apient}
50 virtual Address offset()
51 \end{apient}
52 \apidesc{The start of the region covered by this instruction source.}
53
54 \begin{apient}
55 virtual Address length()
56 \end{apient}
57 \apidesc{The size of the region.}
58
59 \begin{apient}
60 virtual Architecture getArch()
61 \end{apient}
62 \apidesc{The architecture of the instruction source. See the Dyninst manual for details on architecture differences.}
63
64 \begin{apient}
65 virtual bool isAligned(const Address)
66 \end{apient}
67 \apidesc{For fixed-width instruction architectures, must return {\scshape true} if the address is a valid instruction boundary and {\scshape false} otherwise; otherwise returns {\scshape true}. This method has a default implementation that should be sufficient.}
68
69 CodeSource implementors need to fill in several data structures in the base CodeSource class:
70
71 \begin{apient}
72 std::map<Address, std::string> _linkage
73 \end{apient}
74 \apidesc{Entries in the linkage map represent external linkage, e.g. the PLT in ELF binaries. Filling in this map is optional.}
75
76 \begin{apient}
77 Address _table_of_contents
78 \end{apient}
79 \apidesc{Many binary format have ``table of contents'' structures for position
80 independant references. If such a structure exists, its address should be filled in.}
81
82 \begin{apient}
83 std::vector<CodeRegion *> _regions
84 Dyninst::IBSTree<CodeRegion> _region_tree
85 \end{apient}
86 \apidesc{One or more contiguous regions of code or data in the binary object must be registered with the base class. Keeping these structures in sync is the responsibility of the implementing class.}
87
88 \begin{apient}
89 std::vector<Hint> _hints
90 \end{apient}
91 \apidesc{CodeSource implementors can supply a set of Hint objects describing where functions are known to start in the binary. These hints are used to seed the parsing algorithm. Refer to the CodeSource header file for implementation details.}
92
93 \subsection{CFG Object Factories}
94 \label{sec:factories}
95
96 Users who which to incorporate the ParseAPI into large projects may need to store additional information about CFG objects like Functions, Blocks, and Edges. The simplest way to associate the ParseAPI-level CFG representation with higher-level implementation is to extend the CFG classes provided as part of the ParseAPI. Because the parser itself does not know how to construct such extended types, implementors must provide an implementation of the CFGFactory that is specialized for their CFG classes. The CFGFactory exports the following simple interface:
97
98 \begin{apient}
99 virtual Function * mkfunc(Address addr, 
100                           FuncSource src,
101                           std::string name, 
102                           CodeObject * obj, 
103                           CodeRegion * region,
104                           Dyninst::InstructionSource * isrc)
105 \end{apient}
106 \apidesc{Returns an object derived from Function as though the provided parameters had been passed to the Function constructor. The ParseAPI parser will never invoke \code{mkfunc()} twice with identical \code{addr}, and \code{region} parameters---that is, Functions are guaranteed to be unique by address within a region.}
107
108 \begin{apient}
109 virtual Block * mkblock(Function * func,
110                         CodeRegion * region,
111                         Address addr)
112 \end{apient}
113 \apidesc{Returns an object derived from Block as though the provided parameters had been passed to the Block constructor. The parser will never invoke \code{mkblock()} with identical \code{addr} and \code{region} parameters.}
114
115 \begin{apient}
116 virtual Edge * mkedge(Block * src,
117                       Block * trg,
118                       EdgeTypeEnum type)
119 \end{apient}
120 \apidesc{Returns an object derived from Edge as though the provided parameters had been passed to the Edge constructor. The parser \emph{may} invoke \code{mkedge()} multiple times with identical parameters.}
121
122 \begin{apient}
123 virtual Block * mksink(CodeObject *obj,
124                        CodeRegion *r)
125 \end{apient}
126 \apidesc{Returns a ``sink'' block derived from Block to which all unresolvable control flow instructions will be linked. Implementors may return a unique sink block per CodeObject or a single global sink.}
127
128 Implementors of extended CFG classes are required to override the default implementations of the \emph{mk*} functions to allocate and return the appropriate derived types statically cast to the base type. Implementors must also add all allocated objects to the following internal lists:
129
130 \begin{apient}
131 fact_list<Edge> edges_
132 fact_list<Block> blocks_
133 fact_list<Function> funcs_
134 \end{apient}
135 \apidesc{O(1) allocation lists for CFG types. See the CFG.h header file for list insertion and removal operations.}
136
137 Implementors \emph{may} but are \emph{not required to} override the
138 deallocation following deallocation routines. The primary reason to override
139 these routines is if additional action or cleanup is necessary upon CFG object
140 release; the default routines simply remove the objects from the allocation
141 list and invoke their destructors.
142
143 \begin{apient}
144 virtual void free_func(Function * f)
145 virtual void free_block(Block * b)
146 virtual void free_edge(Edge * e)
147 virtual void free_all()
148 \end{apient}
149 \apidesc{CFG objects should be freed using these functions, rather than delete, to avoid leaking memory.}