Added interface to query whether a module already has address range information,...
[dyninst.git] / dynC_API / doc / 2-Language.tex
1 \section{DynC Language Description}
2 The DynC language is a subset of C with a \textbf{domain} specification for selecting the location of a resource.
3
4 \subsection{Domains}
5 Domains are special keywords that allow the programmer to precisely indicate
6 which resource to use.  DynC domains follow the form of
7 \code{<domain>`<identifier>}, with a back-tick separating the domain and the
8 identifier. The DynC domains are as follows:
9
10 \begin{table}[!th]
11 \begin{tabular}{ | l | p{12cm} |}
12 \hline
13 Domain & Description\\
14 \hline
15 \code{inf} & The inferior process (the program being instrumented). Allows access to functions of the mutatee and it's loaded libraries.\\
16 \hline
17 \code{dyninst} & Dyninst utility functions. Allows access to context information as well as the \code{break()} function. See Appendix \ref{sec:dyninstdomain}.\\
18 \hline
19 \code{local} & A mutatee variable local to function in which the snippet is inserted. \\
20 \hline
21 \code{global} & A global mutatee variable. \\
22 \hline
23 \code{param} & A parameter of the mutatee function in which the snippet is inserted. \\
24 \hline
25 \textit{default} & The default domain (domain not specified) is the domain of snippet variables. \\
26 \hline
27
28 \end{tabular}
29 \caption{DynC API Domains}
30 \end{table}
31
32 \noindent Example:
33 \begin{lstlisting}
34    inf`printf("n is equal to %d.\n", ++global`n);
35 \end{lstlisting}
36 This would increment and print the value of the mutatee global variable n.
37
38 \subsection{Control Flow}
39
40 \subsubsection{Comments}
41 Block and line comments work as they do in C or C++.
42
43 \noindent Example:
44 \begin{lstlisting}
45    /*
46     * This is a comment.
47     */
48    int i; // So is this.
49 \end{lstlisting}
50
51 \subsubsection{Conditionals}
52 Use \code{if} to conditionally execute code. 
53 \noindent Example:
54 \begin{lstlisting}
55    if(x == 0){
56       inf`printf("x == 0.\n");
57    }
58 \end{lstlisting}
59 The \code{else} command can be used to specify code executed if a condition is not true.
60 \noindent Example:
61 \begin{lstlisting}
62    if(x == 0){
63       inf`printf("x == 0.\n");
64    }else if(x > 3){
65       inf`printf("x > 3.\n");
66    }else{
67       inf`printf("x < 3 but x }= 0.\n");
68    }
69 \end{lstlisting}
70
71 \subsubsection{First-Only Code Block}
72 \label{sec:firstOnly}
73 Code enclosed by a pair of \code{{\% <code> \%}} is executed only once by a
74 snippet. First-only code blocks can be useful for declaring and initilizing
75 variables, or for any task that needs to be executed only once. Any number of
76 first-only code blocks can be used in a dynC code snippet.
77
78 \noindent A first-only code block is equivalent to the following:
79 \begin{lstlisting}
80    static int firstTime = 0;
81    if(firstTime == 0){
82      <code>
83      firstTime = 1;
84    }
85 \end{lstlisting}
86
87 DynC will only execute the code in a first-only section the first time a snippet
88 is executed. If \code{createSnippet(...)} is called multiple times and is passed
89 the same name, then the first-only code will be executed only once: the first
90 time that any of those snippets \underline{with the same name} is executed. In
91 contrast, if a snippet is created by calling \code{createSnippet(...)} with a
92 unique snippet name (or if a name is unspecified), the first-only code will be
93 executed only once upon reaching the first point encountered in the execution of
94 the mutatee where the returned \code{BPatch\_Snippet} is inserted. 
95
96 \noindent Example Touch:
97 \begin{lstlisting}
98    {%
99       inf`printf("Function %s has been touched.\n", dyninst`function_name);
100    %}
101 \end{lstlisting}
102
103 If \code{createSnippet(...)} is passed the code in Example Touch and the name
104 \code{"fooTouchSnip"} and the returned \code{BPatch\_snippet} is inserted at the entry to function \code{foo}, the output would be:
105 \begin{lstlisting}
106    Function foo has been touched.
107    (mutatee exit)
108 \end{lstlisting}
109
110 If the dynC code in Example Touch is passed to \code{createSnippet(...)} multiple times and each snippet is given the same name, but is inserted at the entries of the functions \code{foo}, \code{bar}, and \code{run} respectively, the output would be:
111
112 \begin{lstlisting}
113    Function foo has been touched.
114    (mutatee exit)
115 \end{lstlisting}
116
117 Creating the snippets with distinct names (e.g. \code{createSnippet(...)} is called with the dynC code in Example Touch multiple times and the snippets are named \code{"fooTouchSnip"}, \code{"barTouchSnip"}, \code{"runTouchSnip"}) would produce an output like:
118
119 \begin{lstlisting}
120    Function foo has been touched.
121    Function bar has been touched.
122    Function run has been touched.
123    (mutatee exit)
124 \end{lstlisting}
125
126 A cautionary note: the use of first-only blocks can be expensive, as a
127 conditional must be evaluated each time the snippet is executed. If the option
128 is available, one may opt to insert a dynC snippet initializing all global
129 variables at the entry point of \code{main}.
130
131 \subsection{Variables}
132
133 DynC allows for the creation of \textit{snippet local} variables. These
134 variables are in scope only within the snippet in which they are created.
135
136 \noindent For example,
137
138 \begin{lstlisting}
139    int i;
140    i = 5;
141 \end{lstlisting}
142
143 \noindent would create an uninitialized variable named \code{i} of type integer.
144 The value of \code{i} is then set to 5.  This is equivalent to:
145
146 \begin{lstlisting}
147    int i = 5;
148 \end{lstlisting}
149
150 \subsubsection{Static Variables}
151
152 Every time a snippet is executed, non-static variables are reinitialized. To create a variable with value that persists across executions of snippets, declare the variable as static. 
153
154 \noindent Example: 
155 \begin{lstlisting}
156    int i = 10;
157    inf`printf("i is %d.\n", i++);
158 \end{lstlisting}
159
160 \noindent If the above is inserted at the entrance to a function that is called four times, the output would be:
161
162 \begin{lstlisting}
163 i is 10.
164 i is 10.
165 i is 10.
166 i is 10.
167 \end{lstlisting}
168
169 \noindent Adding \code{static} to the variable declaration would make the value of \code{i} persist across executions:
170 \begin{lstlisting}
171    static int i = 10;
172    inf`printf("i is %d.\n", i++);
173 \end{lstlisting}
174 \noindent Produces:
175 \begin{lstlisting}
176 i is 10.
177 i is 11.
178 i is 12.
179 i is 13.
180 \end{lstlisting}
181
182 \noindent A variable declared in a first-only section will also behave statically, as the initialization occurs only once.
183
184 \begin{lstlisting}
185    {%
186       int i = 10;
187    %}
188 \end{lstlisting}
189
190 \subsubsection{An Explanation of the Internal Workings of DynC Variable Creation}
191 \label{sec:varExplain}
192
193 DynC uses the DyninstAPI function \code{malloc(...)} to allocate dynC declared
194 variables when \code{createSnippet(...)} is called. The variable name is mangled
195 with the name of the snippet passed to createSnippet. Thus, variables declared
196 in dynC snippets are accessible only to those snippets created by calling
197 \code{createSnippet(...)} with the same name. 
198
199 If the variables are explicitly initialized, dynC sets the value of the variable
200 with a \code{BPatch\_arithExpr(BPatch\_assign...)} snippet. Because of this, each
201 time the snippet is executed, the value is reset to the initialized value. If,
202 however the variables are not explicitly initialized, they are automatically set
203 to a type-specific zero-value. Scalar variables are set to 0, and c-strings are
204 set to empty, null-terminated strings (i.e. \code{""}).
205
206 If a variable is declared with the \code{static} keyword, then the
207 initialization is performed as if in a first-only block (see section
208 \ref{sec:firstOnly}). Thus, a variable is initialized only the first time that
209 snippet is executed, and subsequent executions of the variable initialization
210 are ignored. 
211
212 \subsubsection{Creating Global Variables That Work With DynC}
213
214 To declare a global variable that is accessible to all snippets inserted into a
215 mutatee, one must use the DyninstAPI \hspace{1pt}
216 \code{BPatch\_addressSpace::malloc(...)} method (see \underline{Dyninst
217 Programmer's Guide}). This code is located in mutator code (\emph{not} in dynC
218 code).
219
220
221 \noindent \textbf{myMutator.C:}
222 \begin{lstlisting}
223    ...
224    // Creates a global variable of type in named globalIntN
225    myAddressSpace->malloc(myImage->getType("int"), "globalIntN"); 
226    
227    // file1 and file2 are FILE *, entryPoint and exitPoint are BPatch_point 
228    BPatch_snippet *snippet1 = dynC::createSnippet(file1, &entryPoint, "mySnippet1"); 
229    BPatch_snippet *snippet2 = dynC::createSnippet(file2, &exitPoint, "mySnippet2");
230    
231    assert(snippet1);
232    assert(snippet2);
233    
234    myAdressSpace->insertSnippet(snippet1, &entryPoint);
235    myAdressSpace->insertSnippet(snippet2, &exitPoint);
236    
237    // run the mutatee
238    ((BPatch_process *)myAdressSpace)->continueExecution();
239    ...
240 \end{lstlisting}
241 \noindent \textbf{file1:}
242 \begin{lstlisting}
243    {%
244       global`globalIntN = 0; // initialize global variable in first-only section
245    %}
246    inf`printf("Welcome to function %s. Global variable globalIntN = %d.\n", 
247         dyninst`function_name, global`globalIntN++);
248 \end{lstlisting}
249
250 \noindent \textbf{file2:}
251 \begin{lstlisting}
252    inf`printf("Goodbye from function %s. Global variable globalIntN = %d.\n", 
253         dyninst`function_name, global`globalIntN++);
254 \end{lstlisting}
255
256 \noindent When run, the output from the instrumentation would be:
257 \begin{lstlisting}
258    Welcome to function foo. Global variable globalIntN = 0.
259    Goodbye from function foo. Global variable globalIntN = 1.
260    Welcome to function foo. Global variable globalIntN = 2.
261    Goodbye from function foo. Global variable globalIntN = 3.
262    Welcome to function foo. Global variable globalIntN = 4.
263    Goodbye from function foo. Global variable globalIntN = 5.
264 \end{lstlisting}
265
266 \subsubsection{Data Types}
267 \label{dataTypes}
268 DynC supported data types are restricted by those supported by Dyninst: \code{int}, \code{long}, \code{char *}, and \code{void *}. Integer and c-string primitives are also recognized:\\
269
270 \noindent Example:
271 \begin{lstlisting}
272    int i = 12;
273    char *s = "hello";
274 \end{lstlisting}
275
276 \subsubsection{Pointers}
277 Pointers are dereferenced with the prefix \code{*<variable>} and the address of
278 variable is specified by \code{\&<variable>}.
279 For example, in reference to the previous example from section \ref{dataTypes}, the statement \code{*s} would evaluate to the character \code{h}.
280
281 \subsubsection{Arrays}
282 Arrays in DynC behave much the same way they do in C. 
283
284 \noindent Example:
285 \begin{lstlisting}
286    int array[3] = {1, 2, 3};
287    char *names[] = {"Mark", "Phil", "Deb", "Tracy"};
288    names[2] = "Gwen" // change Deb to Gwen
289    inf`printf("The seventh element of mutArray is %d.\n", global`mutArray[6]); //Mutatee array 
290    if(inf`strcmp(*names, "Mark") == 0){} // This will evaluate to true. 
291 \end{lstlisting}
292
293 \subsection{DynC Limitations}
294 The DynC, while quite expressive, is limited to those actions supported by the DyninstAPI. As such, it lacks certain abilities that many programmers have come to expect. These differences will be discussed in an exploration of those C abilities that dynC lacks.
295  
296 \subsubsection{Loops}
297 There are no looping structures in DynC.
298
299 \subsubsection{Enums, Unions, Structures}
300 These features present a unique implementation challenge and are in development. Look to future revisions for full support for enums, unions, and structures.
301
302 \subsubsection{Preprocessing}
303 DynC does not allow C-style preprocessing macros or importation. Rather than
304 \code{\#define} statements, constant variables are recommended.
305
306 \subsubsection{Functions}
307 Specifying functions is beyond the scope of the DynC language. DyninstAPI has methods for dynamically loading code into a mutatee, and these loaded functions can be used in DynC snippets.
308
309