source: proiecte/hpl/openmpi_compiled/share/vampirtrace/doc/opari/Readme.html @ 97

Last change on this file since 97 was 97, checked in by (none), 14 years ago

Adding compiled files
File size: 11.6 KB
Line 
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">
19Version 1.1, October 2001
20<p>
21&copy; 2001 Forschungszentrum J&uuml;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
30which automatically adds all necessary calls to the
31<font color="#0000FF">pomp</font> runtime measurement library which
32allows to collect runtime performance data of Fortran, C, or C++ OpenMP
33applications. It is based on the idea of OpenMP pragma/directive
34rewriting which is described in detail in a paper
35(<a href="lacsi01.ps.gz">PostScript</a>,
36 <a href="lacsi01.pdf">PDF</a>)
37for <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
47This software is <b>free</B> but <b>copyright</B> &copy; 2001 by
48Forschungszentrum Juelich, ZAM, Germany. By downloading and using this
49software you automatically agree to comply with the regulations as
50described 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
77Before compiling the source files of an OpenMP application, each file
78needs to be transformed by a call to the <font color="#0000FF">OPARI</font>
79tool. 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
82be generated by using the <tt><b>-table</b></tt> option to
83<font color="#0000FF">OPARI</font> either together with the
84transformation of the <b>last</b> input source file or with a separate call
85to <font color="#0000FF">OPARI</font> after all transformations are done.
86A 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
96The 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]&nbsp;&nbsp;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]&nbsp;&nbsp;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]&nbsp;&nbsp;<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]&nbsp;&nbsp;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]&nbsp;&nbsp;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
161In addition to the modified output file, <font color="#0000FF">OPARI</font>
162also generates a file named <tt><b><i>infile</i>.opari.inc</b></tt>. It
163contains OpenMP region descriptors, one for each OpenMP region found in the
164input file. The meaning of the descriptor fields are described in the file
165<tt><b>pomp_lib.h</b></tt>.
166
167<p>
168
169In 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
207as well as the OpenMP extension <tt><b>INST</b></tt> directives/pragmas
208and 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
214Because <font color="#0000FF">OPARI</font> does not contain full parsers for
215the 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   
257We did not find these limitations overly restrictive during our tests and
258experiments. They rarely apply for well-written code. If they do, the
259original source code can easily be fixed.  Of course, it would be possible
260to remove these limitations by enhancing <font color="#0000FF">OPARI</font>`s
261parsing sophistication.
262
263<h3>Limitations due to source-to-source translation</h3>
264
265In addition, because of some subtleties in the OpenMP standard specifications,
266the transformations performed by <font color="#0000FF">OPARI</font> on the
267source code level can differ from the same instrumentation done by a real
268OpenMP 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
298Of course, an OpenMP compiler can insert the <font color="#0000FF">pomp</font>
299performance interface calls directly around the implicit barriers, thereby
300avoiding the described overheads and discrepancies.
301
302</div>
303</body>
304</html>
Note: See TracBrowser for help on using the repository browser.