1 | <html> |
---|
2 | |
---|
3 | <head> |
---|
4 | <title>OPARI: OpenMP Pragma And Region Instrumentor</title> |
---|
5 | </head> |
---|
6 | |
---|
7 | <body bgcolor="#FFFFFF"> |
---|
8 | |
---|
9 | <div align="center"> |
---|
10 | <img src="opari-logo-100.gif"> |
---|
11 | </div> |
---|
12 | |
---|
13 | <h1 align="center"><font color="#FF0000">O</font>penMP |
---|
14 | <font color="#FF0000">P</font>ragma |
---|
15 | <font color="#FF0000">A</font>nd |
---|
16 | <font color="#FF0000">R</font>egion |
---|
17 | <font color="#FF0000">I</font>nstrumentor - </h1> |
---|
18 | <div align="center"> |
---|
19 | Version 1.1, October 2001 |
---|
20 | <p> |
---|
21 | © 2001 Forschungszentrum Jülich, ZAM, Germany |
---|
22 | <br>Bernd Mohr |
---|
23 | </div> |
---|
24 | |
---|
25 | <p> |
---|
26 | |
---|
27 | <div align="justify"> |
---|
28 | |
---|
29 | <font color="#0000FF">OPARI</font> is a source-to-source translation tool |
---|
30 | which automatically adds all necessary calls to the |
---|
31 | <font color="#0000FF">pomp</font> runtime measurement library which |
---|
32 | allows to collect runtime performance data of Fortran, C, or C++ OpenMP |
---|
33 | applications. It is based on the idea of OpenMP pragma/directive |
---|
34 | rewriting which is described in detail in a paper |
---|
35 | (<a href="lacsi01.ps.gz">PostScript</a>, |
---|
36 | <a href="lacsi01.pdf">PDF</a>) |
---|
37 | for <a href="http://lacsi.lanl.gov/symposium/">LACSI'01</a>. |
---|
38 | |
---|
39 | <p> |
---|
40 | |
---|
41 | <font color="#0000FF">OPARI</font> was developed as part of the |
---|
42 | <a href="http://www.fz-juelich.de/zam/kojak/">KOJAK</a> and |
---|
43 | <a href="http://www.acl.lanl.gov/tau/">TAU</a> projects. |
---|
44 | |
---|
45 | <h2><hr>DOWNLOAD<hr></h2> |
---|
46 | |
---|
47 | This software is <b>free</B> but <b>copyright</B> © 2001 by |
---|
48 | Forschungszentrum Juelich, ZAM, Germany. By downloading and using this |
---|
49 | software you automatically agree to comply with the regulations as |
---|
50 | described in the <a href="LICENSE">license agreement</a>. |
---|
51 | |
---|
52 | <p> |
---|
53 | <table border=1> |
---|
54 | <tr> |
---|
55 | <th colspan=3>Sources in gzipped tar format |
---|
56 | </tr> |
---|
57 | <tr> |
---|
58 | <th>Version |
---|
59 | <th>Date |
---|
60 | <th>Description |
---|
61 | </tr> |
---|
62 | <tr> |
---|
63 | <td>1.1 |
---|
64 | <td>17-Oct-2001 |
---|
65 | <td><a href="ChangeLog">Changes</a> |
---|
66 | </tr> |
---|
67 | <tr> |
---|
68 | <td>1.0 |
---|
69 | <td>28-Aug-2001 |
---|
70 | <td>Initial version |
---|
71 | </tr> |
---|
72 | </table> |
---|
73 | <p> |
---|
74 | |
---|
75 | <h2><hr>USAGE<hr></h2> |
---|
76 | |
---|
77 | Before compiling the source files of an OpenMP application, each file |
---|
78 | needs to be transformed by a call to the <font color="#0000FF">OPARI</font> |
---|
79 | tool. In addition, the application has to be linked against the |
---|
80 | <font color="#0000FF">pomp</font> runtime measurement library and the |
---|
81 | <font color="#0000FF">OPARI</font> runtime table file. The latter has to |
---|
82 | be generated by using the <tt><b>-table</b></tt> option to |
---|
83 | <font color="#0000FF">OPARI</font> either together with the |
---|
84 | transformation of the <b>last</b> input source file or with a separate call |
---|
85 | to <font color="#0000FF">OPARI</font> after all transformations are done. |
---|
86 | A call to <font color="#0000FF">OPARI</font> has the following syntax: |
---|
87 | </div> |
---|
88 | <pre><b> |
---|
89 | opari [-f77|-f90|-c|-c++] [-nosrc] [-disable <i>constructs</i>] |
---|
90 | [-rcfile <i>file</i>] [-table <i>tabfile</i>] <i>infile</i> [outfile] |
---|
91 | </b>or:<b> |
---|
92 | opari [-rcfile <i>file</i>] -table <i>tabfile</i> |
---|
93 | </b></pre> |
---|
94 | <div align="justify"> |
---|
95 | |
---|
96 | The options and parameters have the following meaning: |
---|
97 | |
---|
98 | <table cellspacing=10> |
---|
99 | <tr> |
---|
100 | <td valign="top"><tt><b>[-f77|-f90|-c|-c++]</b></tt> |
---|
101 | <td valign="top">[OPTIONAL] Specifies the programming language |
---|
102 | of the input source file. This option is only |
---|
103 | necessary if the automatic language detection |
---|
104 | based on the input file suffix fails. |
---|
105 | </tr> |
---|
106 | <tr> |
---|
107 | <td valign="top"><tt><b>[-nosrc]</b></tt> |
---|
108 | <td valign="top">[OPTIONAL] If specified, |
---|
109 | <font color="#0000FF">OPARI</font> does not generate |
---|
110 | <tt><b>#line</b></tt> constructs in the transformation process |
---|
111 | which allow to preserve the original source file |
---|
112 | and line number information. This option might |
---|
113 | be necessary if the OpenMP compiler does not |
---|
114 | understand <tt><b>#line</b></tt> constructs. The default is to |
---|
115 | generate <tt><b>#line</b></tt> constructs. |
---|
116 | </tr> |
---|
117 | <tr> |
---|
118 | <td valign="top"><tt><b>[-rcfile <i>file</i>]</b></tt> |
---|
119 | <td valign="top">[OPTIONAL] <font color="#0000FF">OPARI</font> |
---|
120 | uses the file <tt><b>./opari.rc</b></tt> to preserve state information |
---|
121 | between calls to <font color="#0000FF">OPARI</font> if the OpenMP |
---|
122 | application consists of more than one source file. With the |
---|
123 | <tt><b>-rcfile</b></tt> option the file <tt><b><i>file</i></b></tt> is |
---|
124 | used instead. This can be useful if more than one application is |
---|
125 | stored in the same directory or if the source files of an application |
---|
126 | are stored in more than one directory. |
---|
127 | </tr> |
---|
128 | <tr> |
---|
129 | <td valign="top"><tt><b>-table <i>tabfile</i></b></tt> |
---|
130 | <td valign="top">Generate the <font color="#0000FF">OPARI</font> runtime |
---|
131 | table in file <tt><b><i>tabfile</i></b></tt>. |
---|
132 | This option has to be used either together with the |
---|
133 | call to <font color="#0000FF">OPARI</font> for the transformation of |
---|
134 | the <b>last</b> input source file or with a separate call to |
---|
135 | <font color="#0000FF">OPARI</font> after all transformations are done. |
---|
136 | </tr> |
---|
137 | <tr> |
---|
138 | <td valign="top"><tt><b>-disable <i>constructs</i></b></tt> |
---|
139 | <td valign="top">[OPTIONAL] Disable the instrumentation of |
---|
140 | the more fine-grained OpenMP constructs such as <tt><b>!$OMP</b></tt> |
---|
141 | <tt><b>ATOMIC</b></tt>. <tt><b><i>constructs</i></b></tt> |
---|
142 | is a comma separated list of the constructs for which the |
---|
143 | instrumentation should be disabled. Accepted tokens are |
---|
144 | <tt><b>atomic</b></tt>, <tt><b>critical</b></tt>, <tt><b>master</b></tt>, |
---|
145 | <tt><b>flush</b></tt>, <tt><b>single</b></tt>, or <tt><b>locks</b></tt> |
---|
146 | as well as <tt><b>sync</b></tt> to disable all of them. |
---|
147 | </tr> |
---|
148 | <tr> |
---|
149 | <td valign="top"><tt><b><i>infile</i></b></tt> |
---|
150 | <td valign="top">Input file name. |
---|
151 | </tr> |
---|
152 | <tr> |
---|
153 | <td valign="top"><tt><b>[<i>outfile</i>]</b></tt> |
---|
154 | <td valign="top">[OPTIONAL] Output file name. If not specified, |
---|
155 | <font color="#0000FF">OPARI</font> uses the name |
---|
156 | <tt><b><i>infile</i>.mod.<i>suffix</i></b></tt> if |
---|
157 | the input file is called <tt><b><i>infile</i>.<i>suffix</i></b></tt>. |
---|
158 | </tr> |
---|
159 | </table> |
---|
160 | |
---|
161 | In addition to the modified output file, <font color="#0000FF">OPARI</font> |
---|
162 | also generates a file named <tt><b><i>infile</i>.opari.inc</b></tt>. It |
---|
163 | contains OpenMP region descriptors, one for each OpenMP region found in the |
---|
164 | input file. The meaning of the descriptor fields are described in the file |
---|
165 | <tt><b>pomp_lib.h</b></tt>. |
---|
166 | |
---|
167 | <p> |
---|
168 | |
---|
169 | In summary, the typical usage of <font color="#0000FF">OPARI</font> consists of the following steps: |
---|
170 | |
---|
171 | <ol> |
---|
172 | <li>Reset <font color="#0000FF">OPARI</font> state information by removing |
---|
173 | the state information file if it exists. |
---|
174 | <pre><b> |
---|
175 | % rm -f opari.rc |
---|
176 | </b></pre> |
---|
177 | |
---|
178 | <li>Call <font color="#0000FF">OPARI</font> for each input source file |
---|
179 | <pre><b> |
---|
180 | % opari file1.f90 |
---|
181 | ... |
---|
182 | % opari fileN.f90 |
---|
183 | </b></pre> |
---|
184 | |
---|
185 | <li>Generate the <font color="#0000FF">OPARI</font> runtime table and |
---|
186 | compile it using a ANSI C compiler |
---|
187 | <pre><b> |
---|
188 | % opari -table opari.tab.c |
---|
189 | % cc -c opari.tab.c |
---|
190 | </b></pre> |
---|
191 | |
---|
192 | <li>Compile all modified output files <tt><b>*.mod.*</b></tt> using the OpenMP |
---|
193 | compiler |
---|
194 | <p> |
---|
195 | |
---|
196 | <li>Link the resulting object files against the |
---|
197 | <font color="#0000FF">OPARI</font> runtime table |
---|
198 | <tt><b>opari.tab.o</b></tt> and the <font color="#0000FF">pomp</font> |
---|
199 | runtime measurement library. |
---|
200 | </ol> |
---|
201 | |
---|
202 | <h2><hr>LIMITATIONS<hr></h2> |
---|
203 | |
---|
204 | <font color="#0000FF">OPARI</font> understands all OpenMP constructs by the |
---|
205 | <a href="http://www.openmp.org/specs/">Fortran 77/90 OpenMP 2.0</a> and |
---|
206 | <a href="http://www.openmp.org/specs/">C/C++ OpenMP 1.0</a> specifications |
---|
207 | as well as the OpenMP extension <tt><b>INST</b></tt> directives/pragmas |
---|
208 | and the alternative <tt><b>POMP</b></tt> sentinel proposed in |
---|
209 | <a href="lacsi01.ps.gz">lacsi01.ps.gz</a> / |
---|
210 | <a href="lacsi01.pdf">lacsi01.pdf</a>. |
---|
211 | |
---|
212 | <h3>Limitations due to fuzzy parsing</h3> |
---|
213 | |
---|
214 | Because <font color="#0000FF">OPARI</font> does not contain full parsers for |
---|
215 | the supported programming languages the following restrictions apply: |
---|
216 | |
---|
217 | <h4>Fortran 77/90:</h4> |
---|
218 | |
---|
219 | <ol> |
---|
220 | <li> The <tt><b>!$OMP</b></tt> <tt><b>END</b></tt> <tt><b>DO</b></tt> and |
---|
221 | <tt><b>!$OMP</b></tt> <tt><b>END</b></tt> <tt><b>PARALLEL</b></tt> |
---|
222 | <tt><b>DO</b></tt> directives |
---|
223 | are required (and not optional as described in the OpenMP specification) |
---|
224 | <p> |
---|
225 | <li> The <i>atomic expression</i> controlled by a |
---|
226 | <tt><b>!$OMP</b></tt> <tt><b>ATOMIC</b></tt> |
---|
227 | directive has to be on a line all by itself. |
---|
228 | <p> |
---|
229 | <li> If the measurement environment does not support the automatic |
---|
230 | recording of user function entries and exits, the |
---|
231 | <font color="#0000FF">OPARI</font> runtime |
---|
232 | measurement library has to be initialized by a |
---|
233 | <tt><b>!$OMP</b></tt> <tt><b>INST</b></tt> <tt><b>INIT</b></tt> |
---|
234 | directive prior to any other OpenMP directive. |
---|
235 | </ol> |
---|
236 | |
---|
237 | <h4>C/C++:</h4> |
---|
238 | |
---|
239 | <ol> |
---|
240 | <li> <i>structured blocks</i> describing the extend of an OpenMP pragma |
---|
241 | need to be either compound statements <tt><b>{....}</b></tt>, |
---|
242 | <tt><b>while</b></tt> loops, or simple statements. In addition, |
---|
243 | <tt><b>for</b></tt> loops are supported after |
---|
244 | <tt><b>omp</b></tt> <tt><b>for</b></tt> and <tt><b>omp</b></tt> |
---|
245 | <tt><b>parallel</b></tt> <tt><b>for</b></tt> pragmas. |
---|
246 | Complex statements like |
---|
247 | <tt><b>if-then-else</b></tt> or <tt><b>do-while</b></tt> need to |
---|
248 | be enclosed in a block ( <tt><b>{....}</b></tt> ). |
---|
249 | <p> |
---|
250 | <li> If the measurement environment does not support the automatic |
---|
251 | recording of user function entries and exits, the |
---|
252 | <font color="#0000FF">OPARI</font> runtime measurement library has to |
---|
253 | be initialized by a <tt><b>omp</b></tt> <tt><b>inst</b></tt> |
---|
254 | <tt><b>init</b></tt> pragma prior to any other OpenMP pragma. |
---|
255 | </ol> |
---|
256 | |
---|
257 | We did not find these limitations overly restrictive during our tests and |
---|
258 | experiments. They rarely apply for well-written code. If they do, the |
---|
259 | original source code can easily be fixed. Of course, it would be possible |
---|
260 | to remove these limitations by enhancing <font color="#0000FF">OPARI</font>`s |
---|
261 | parsing sophistication. |
---|
262 | |
---|
263 | <h3>Limitations due to source-to-source translation</h3> |
---|
264 | |
---|
265 | In addition, because of some subtleties in the OpenMP standard specifications, |
---|
266 | the transformations performed by <font color="#0000FF">OPARI</font> on the |
---|
267 | source code level can differ from the same instrumentation done by a real |
---|
268 | OpenMP compiler. Here is the list of limitations we currently know about: |
---|
269 | <ul> |
---|
270 | <li><font color="#0000FF">OPARI</font> makes implicit barriers explicit. |
---|
271 | Unfortunately, this method cannot be used for measuring the barrier waiting |
---|
272 | time at the end of <tt><b>PARALLEL</tt></b> directives because they do not |
---|
273 | allow a <tt><b>NOWAIT</tt></b> clause. Therefore, we add an explicit |
---|
274 | barrier with corresponding performance interface calls here. For <font |
---|
275 | color="#0000FF">OPARI</font>, this means that actually two barriers get |
---|
276 | called. But the second (implicit) barrier should execute and succeed |
---|
277 | immediately because the threads of the OpenMP team are already synchronized |
---|
278 | by the first barrier. |
---|
279 | <p> |
---|
280 | <li>The OpenMP standard (unfortunately) allows compilers to ignore |
---|
281 | <tt><b>NOWAIT</tt></b>s, which means that in this case <font |
---|
282 | color="#0000FF">OPARI</font> inserts an extra barrier and the |
---|
283 | <font color="#0000FF">pomp</font> functions get invoked on this extra |
---|
284 | (and not the real) barrier. |
---|
285 | <p> |
---|
286 | <li><font color="#0000FF">OPARI</font> cannot instrument the (required) |
---|
287 | internal synchronization inside <tt><b>!$OMP</tt></b> |
---|
288 | <tt><b>WORKSHARE</tt></b>. |
---|
289 | <p> |
---|
290 | <li>Mark Bull's <a |
---|
291 | href="http://www.epcc.ed.ac.uk/research/openmpbench/">Microbenchmarks</a> |
---|
292 | show that some compiler use different implementations (with different |
---|
293 | characteristics) for implicit and explicit barriers. If <font |
---|
294 | color="#0000FF">OPARI</font> changes implicit to explicit barriers, we |
---|
295 | measure the wrong behavior on these compilers. |
---|
296 | </ul> |
---|
297 | |
---|
298 | Of course, an OpenMP compiler can insert the <font color="#0000FF">pomp</font> |
---|
299 | performance interface calls directly around the implicit barriers, thereby |
---|
300 | avoiding the described overheads and discrepancies. |
---|
301 | |
---|
302 | </div> |
---|
303 | </body> |
---|
304 | </html> |
---|