[97] | 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> |
---|