Update manual version numbers and minor fixes
[dyninst.git] / symtabAPI / doc / 2-Abstractions.tex
1 \section{Abstractions}
2 \label{sec:abstractions}
3
4 \begin{figure}
5     \centering
6     \tikzstyle{symbol} = [rectangle, draw, fill=green!25]
7     \tikzstyle{type} = [rectangle, draw, rounded corners, fill=yellow!25]
8     \tikzstyle{local} = [ellipse, draw, fill=red!25]
9     \tikzstyle{line} = [trapezium, trapezium left angle=70, trapezium right angle=70, draw, fill=cyan!25]
10     \tikzstyle{annotation} = []
11     \begin{tikzpicture}[
12             level distance=1cm,
13             level 3/.style={level distance=1cm}, 
14             growth parent anchor=south,
15             sibling distance=2.2cm,
16             child anchor=north,
17         ]
18
19         \node [symbol] (Archive) {Archive} [->]
20         child {
21             node [symbol] (Symtab) {Symtab}
22             child {
23                 node [symbol] (Module) {Module}
24                 child  {
25                     node [symbol] (ExceptionBlock) {ExceptionBlock}
26 %                    edge from parent node[sloped, above, draw=none] {N:1}
27                 }
28                 child [xshift=.5cm]{
29                     node [symbol] (Function) {Function}
30 %                    edge from parent node[sloped, above, draw=none] {N:1}
31                 }
32                 child [yshift=-1cm-1em] {
33                     node [symbol] (Symbol) {Symbol}
34                     child {
35                         node [local] (localVar) {localVar}
36 %                        edge from parent node[left, draw=none] {1:N}
37                     }
38 %                    edge from parent node[sloped, above, draw=none] {N:1}
39                 }
40                 child [xshift=-.25cm] {
41                     node [symbol] (Variable) {Variable}
42 %                    edge from parent node[sloped, above, draw=none] {N:1}
43                 }
44                 child [xshift=-.5cm] {
45                     node [type] (Type) {Type}
46 %                    edge from parent node[sloped, above, draw=none] {1:N}
47                 }
48                 child {
49                     node [line] (LineInformation) {LineInformation}
50                     child {
51                         node [line] (Statement) {Statement}
52 %                        edge from parent node[left, draw=none] {1:N}
53                     }
54 %                    edge from parent node[sloped, above, draw=none] {1:1}
55                 }
56 %                edge from parent node[left, draw=none] {1:N}
57             }
58 %            edge from parent node[left, draw=none] {1:N}
59         }
60         ;
61
62 %        \draw [->] (Function) edge node[sloped, below] {1:N} (Symbol);
63 %        \draw [->] (Variable) edge node[sloped, below] {N:1} (Symbol);
64         \draw [->] (Function) -- (Symbol);
65         \draw [->] (Variable) -- (Symbol);
66
67     \end{tikzpicture}
68     
69     \vspace{1cm}
70
71     % legend
72     \begin{tikzpicture}
73     \node [symbol, minimum width=1.5cm, minimum height=1em] (symbol) {A};
74     \node [annotation, right=.25cm of symbol] (classSymbol) {Class A belongs to the};
75     \node [annotation, below=0cm of classSymbol] (classSymbol2) {symbol table interface};
76
77     \node [type, minimum width=1.5cm, minimum height=1em, below=1cm of symbol] (type) {A};
78     \node [annotation, right=.25cm of type] (classType) {Class A belongs to the};
79     \node [annotation, below=0cm of classType] (classType2) {Type interface};
80
81     \node [local, minimum width=1.5cm, minimum height=1em, right=5cm of symbol] (local) {A};
82     \node [annotation, right=.25cm of local] (classLocal) {Class A belongs to the};
83     \node [annotation, below=0cm of classLocal] (classLocal2) {Local Variable interface};
84
85     \node [line, below=1cm of local] (line) {~~A~~};
86     \node [annotation, right=.25cm of line] (classLine) {Class A belongs to the};
87     \node [annotation, below=0cm of classLine] (classLine2) {Line Number interface};
88
89 %    \node [annotation, below=1cm of type] (ownA) {A};
90 %    \node [annotation, right=1cm of ownA] (ownB) {B};
91 %    \draw [->] (ownA) edge node[above] {1:1} (ownB);
92 %    \node [annotation, right=.25cm of ownB] (own) {Each instance of class A owns
93 %    one instance of class B};
94 %
95 %    \node [annotation, below=.5cm of ownA] (ownmultA) {A};
96 %    \node [annotation, right=1cm of ownmultA] (ownmultB) {B};
97 %    \draw [->] (ownmultA) edge node[above] {1:N} (ownmultB);
98 %    \node [annotation, right=.25cm of ownmultB] (ownmult) {Each instance of class A owns
99 %    multiple instances of class B};
100 %
101     \node [rectangle, draw,
102     fit=(symbol)(classSymbol)(classSymbol2)(type)(classType)(classType2)(local)(classLocal)(classLocal2)(line)(classLine)(classLine2)]
103     (legendBox) {};
104     \node [rectangle, label=left: \rotatebox{90}{LEGEND}, fit=(legendBox)] {};
105
106     \end{tikzpicture}
107     
108     \caption{SymtabAPI Object Ownership Diagram}
109     \label{fig:object-ownership}
110 \end{figure}
111
112 SymtabAPI provides a simple set of abstractions over complicated data structures
113 which makes it straight-forward to use. The SymtabAPI consists of five classes of
114 interfaces: the symbol table interface, the type interface, the line map
115 interface, the local variable interface, and the address translation interface. 
116
117 Figure~\ref{fig:object-ownership} shows the ownership hierarchy for the
118 SymtabAPI classes. Ownership here is a ``contains'' relationship; if one
119 class owns another, then instances of the owner class maintain an exclusive
120 instance of the other. For example, each Symtab class instance contains multiple
121 instances of class Symbol and each Symbol class instance belongs to one Symtab
122 class instance. Each of four interfaces and the classes belonging to these
123 interfaces are described in the rest of this section. The API functions in each
124 of the classes are described in detail in Section \ref{sec:symtabAPI}.
125
126 \subsection{Symbol Table Interface}
127
128 The symbol table interface is responsible for parsing the object file and
129 handling the look-up and addition of new symbols. It is also responsible for the
130 emit functionality that SymtabAPI supports. The Symtab and the Module classes
131 inherit from the LookupInterface class, an abstract class, ensuring the same
132 lookup function signatures for both Module and Symtab classes. 
133
134 \begin{description}
135 \item[Symtab] A Symtab class object represents either an object file on-disk or in-memory that the SymtabAPI library operates on.
136 \item[Symbol] A Symbol class object represents an entry in the symbol table.
137 \item[Module] A Module class object represents a particular source file in cases where multiple files were compiled into a single binary object; if this information is not present, we use a single default module.
138 \item[Archive] An Archive class object represents a collection of binary objects stored in a single file (e.g., a static archive). 
139 \item[ExceptionBlock] An ExceptionBlock class object represents an exception block which contains the information necessary for run-time exception handling.
140 \end{description}
141
142 In addition, we define two symbol aggregates, Function and Variable. These classes collect multiple symbols with the same address and type but different names; for example, weak and strong symbols for a single function. 
143
144 \subsection{Type Interface}
145 \label{subsec:typeInterface}
146  The Type interface is responsible for parsing type information from the object file and handling the look-up and addition of new type information. Figure \ref{fig:class-inherit} shows the class inheritance diagram for the type interface. Class Type is the base class for all of the classes that are part of the interface. This class provides the basic common functionality for all the types, such as querying the name and size of a type. The rest of the classes represent specific types and provide more functionality based on the type. 
147
148  \begin{figure}
149     \centering
150     \tikzstyle{class} = [rectangle, draw, rounded corners, fill=yellow!100]
151     \tikzstyle{class2} = [rectangle, draw, rounded corners, fill=yellow!100,
152 node distance=.65cm]
153     \tikzstyle{abstract} = [rectangle, draw, rounded corners,
154 pattern=north west lines, pattern color=yellow]
155     \tikzstyle{annotation} = []
156     \begin{tikzpicture}[
157         level distance=1cm, 
158         growth parent anchor=south,
159         level 1/.style={sibling distance=3cm},
160     ]
161
162     \node [class] (type) {Type} [<-]
163     child [level distance=1.95cm+1em] {
164         node [class2] (typeEnum) {typeEnum}
165         node [class2, below of=typeEnum] (typeFunction) {typeFunction}
166         node [class2, below of=typeFunction] (typeScalar) {typeScalar}
167     }
168     child [xshift=1cm] {
169         node [abstract] (derivedType) {derivedType}
170         child {
171             node [class2] (typeRef) {typeRef}
172             node [class2, below of=typeRef] (typePointer) {typePointer}
173             node [class2, below of=typePointer] (typeTypedef) {typeTypedef}
174         }
175     }
176     child [xshift=1cm] {
177         node [abstract] (filedListType) {fieldListType}
178         child {
179             node [class2] (typeStruct) {typeStruct}
180             node [class2, below of=typeStruct] (typeUnion) {typeUnion}
181             node [class2, below of=typeUnion] (typeCommon) {typeCommon}
182         }
183     }
184     child [xshift=1cm] {
185         node [abstract] (rangedType) {rangedType}
186         child {
187             node [class2] (typeArray) {typeArray}
188             node [class2, below of=typeArray] (typeSubrange) {typeSubrange}
189         }
190     }
191     ;
192
193     \node [class, above=1cm-1em of typeEnum] (CBlock) {CBlock};
194
195     \end{tikzpicture}
196
197     \vspace{1cm}
198
199     \begin{tikzpicture}[]
200     % legend
201     \node [class, minimum width=2cm, minimum height=1em] (A) {A};
202     \node [annotation, right=.25cm of A] (classA) {Class A belongs to the};
203     \node [annotation, below=0cm of classA] (classA2) {Type interface};
204
205     \node [annotation, right=1.5cm of classA] (littleA) {A};
206     \node [annotation, right of=littleA] (littleB) {B};
207     \draw [->] (littleA) -- (littleB);
208     \node [annotation, right=.25cm of littleB] (inherits) {A inherits from B};
209
210     \node [abstract, below=.5cm of littleA, minimum width=2cm, minimum
211 height=1.25em] (abstract) {};
212     \node [annotation, right=.25cm of abstract] (abstractClass) {Represents an abstract class};
213
214     \node [rectangle, draw, fit=(A)(classA)(classA2)(littleA)(littleB)(inherits)(abstract)(abstractClass)]
215 (legendBox) {};   
216     \node [rectangle, label=left: \rotatebox{90}{LEGEND}, fit=(legendBox)] {};
217
218     \end{tikzpicture}
219      \caption{SymtabAPI Type Interface - Class Inheritance Diagram}
220      \label{fig:class-inherit}
221  \end{figure}
222
223 Some of the types inherit from a second level of type classes, each representing a separate category of types. 
224 \begin{description}
225 \item[fieldListType] - This category of types represent the container types that contain a list of fields. Examples of this category include structure and the union types. 
226 \item[derivedType] - This category of types represent types derived from a base type. Examples of this category include typedef, pointer and reference types. 
227 \item[rangedType] - This category represents range types. Examples of this category include the array and the sub-range types. 
228 \end{description}
229 The enum, function, common block and scalar types do not fall under any of the above category of types. Each of the specific types is derived from Type.
230
231 \subsection{Line Number Interface}
232
233 The Line Number interface is responsible for parsing line number information from the object file debug information and handling the look-up and addition of new line information. The main classes for this interface are LineInformation and LineNoTuple. 
234
235 \begin{description}
236 \item[LineInformation] - A LineInformation class object represents a mapping of line numbers to address range within a module (source file). 
237 \item[Statement/LineNoTuple] - A Statement class object represents a location in source code with a source file, line number in that source file and start column in that line. For backwards compatibility, Statements may also be referred to as LineNoTuples. 
238 \end{description}
239
240 \subsection{Local Variable Interface}
241 The Local Variable Interface is responsible for parsing local variable and parameter information of functions from the object file debug information and handling the look-up and addition of new add new local variables. All the local variables within a function are tied to the Symbol class object representing that function.
242 \begin{description}
243 \item[localVar] - A localVar class object represents a local variable or a parameter belonging to a function.
244 \end{description}
245
246 \subsection{Dynamic Address Translation}
247 The AddressLookup class is a component for mapping between absolute addresses found in a running process and SymtabAPI objects. This is useful because libraries can load at different addresses in different processes. Each AddressLookup instance is associated with, and provides mapping for, one process.
248