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

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

Adding compiled files
File size: 68.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4original version by:  Nikos Drakos, CBLU, University of Leeds
5* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>UserManual</TITLE>
11<META NAME="description" CONTENT="UserManual">
12<META NAME="keywords" CONTENT="UserManual">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
17<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
18
19<STYLE>
20/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
21.MATH    { font-family: "Century Schoolbook", serif; }
22.MATH I  { font-family: "Century Schoolbook", serif; font-style: italic }
23.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
24
25/* implement both fixed-size and relative sizes */
26SMALL.XTINY             { font-size : xx-small }
27SMALL.TINY              { font-size : x-small  }
28SMALL.SCRIPTSIZE        { font-size : smaller  }
29SMALL.FOOTNOTESIZE      { font-size : small    }
30SMALL.SMALL             {  }
31BIG.LARGE               {  }
32BIG.XLARGE              { font-size : large    }
33BIG.XXLARGE             { font-size : x-large  }
34BIG.HUGE                { font-size : larger   }
35BIG.XHUGE               { font-size : xx-large }
36
37/* heading styles */
38H1              {  }
39H2              {  }
40H3              {  }
41H4              {  }
42H5              {  }
43
44/* mathematics styles */
45DIV.displaymath         { }     /* math displays */
46TD.eqno                 { }     /* equation-number cells */
47
48
49/* document-specific styles come next */
50DIV.navigation          {   }
51PRE.preform             {   }
52SPAN.textit             { font-style: italic  }
53SPAN.arabic             {   }
54SPAN.textbf             { font-weight: bold  }
55
56BODY { font-family: sans-serif }
57</STYLE>
58
59</HEAD>
60
61<BODY >
62
63<P>
64
65<P>
66<B><BIG CLASS="XHUGE">VampirTrace 5.4.10 User Manual</BIG></B>
67<BR>
68<BR>
69<BR>
70TU Dresden
71<BR>
72Center for Information Services and
73<BR>
74High Performance Computing (ZIH)
75<BR>
7601062 Dresden
77<BR>
78Germany
79<BR>
80<BR><TT><A NAME="tex2html1"
81  HREF="http://www.tu-dresden.de/zih/">http://www.tu-dresden.de/zih/</A></TT>
82<BR><TT><A NAME="tex2html2"
83  HREF="http://www.tu-dresden.de/zih/vampirtrace/">http://www.tu-dresden.de/zih/vampirtrace/</A></TT>
84<BR>
85<BR>
86E-Mail: <TT><A NAME="tex2html3"
87  HREF="vampirsupport@zih.tu-dresden.de">vampirsupport@zih.tu-dresden.de</A></TT>
88<P>
89<BR>
90
91<H2><A NAME="SECTION00100000000000000000">
92Contents</A>
93</H2>
94<!--Table of Contents-->
95
96<UL CLASS="TofC">
97<LI><A NAME="tex2html54"
98  HREF="UserManual.html#SECTION00200000000000000000">Introduction</A>
99<LI><A NAME="tex2html55"
100  HREF="UserManual.html#SECTION00300000000000000000">Instrumentation</A>
101<UL>
102<LI><A NAME="tex2html56"
103  HREF="UserManual.html#SECTION00310000000000000000">The Compiler Wrappers</A>
104<LI><A NAME="tex2html57"
105  HREF="UserManual.html#SECTION00320000000000000000">Instrumentation Types</A>
106<LI><A NAME="tex2html58"
107  HREF="UserManual.html#SECTION00330000000000000000">Automatic Instrumentation</A>
108<UL>
109<LI><A NAME="tex2html59"
110  HREF="UserManual.html#SECTION00331000000000000000">Notes for Using the GNU, Intel, or Pathscale Compiler</A>
111<LI><A NAME="tex2html60"
112  HREF="UserManual.html#SECTION00332000000000000000">Known License Issues with BFD</A>
113<LI><A NAME="tex2html61"
114  HREF="UserManual.html#SECTION00333000000000000000">Notes on Instrumentation of Inline Functions</A>
115</UL>
116<LI><A NAME="tex2html62"
117  HREF="UserManual.html#SECTION00340000000000000000">Manual Instrumentation using the VampirTrace API</A>
118<LI><A NAME="tex2html63"
119  HREF="UserManual.html#SECTION00350000000000000000">Manual Instrumentation using POMP</A>
120<LI><A NAME="tex2html64"
121  HREF="UserManual.html#SECTION00360000000000000000">Binary instrumentation using Dyninst</A>
122</UL>
123<BR>
124<LI><A NAME="tex2html65"
125  HREF="UserManual.html#SECTION00400000000000000000">Runtime Measurement</A>
126<UL>
127<LI><A NAME="tex2html66"
128  HREF="UserManual.html#SECTION00410000000000000000">Environment Variables</A>
129<LI><A NAME="tex2html67"
130  HREF="UserManual.html#SECTION00420000000000000000">Influencing Trace File Size</A>
131<LI><A NAME="tex2html68"
132  HREF="UserManual.html#SECTION00430000000000000000">Unification of local Traces</A>
133</UL>
134<BR>
135<LI><A NAME="tex2html69"
136  HREF="UserManual.html#SECTION00500000000000000000">Recording additional Events and Counters</A>
137<UL>
138<LI><A NAME="tex2html70"
139  HREF="UserManual.html#SECTION00510000000000000000">PAPI Hardware Performance Counters</A>
140<LI><A NAME="tex2html71"
141  HREF="UserManual.html#SECTION00520000000000000000">Memory Allocation Counters</A>
142<LI><A NAME="tex2html72"
143  HREF="UserManual.html#SECTION00530000000000000000">Application I/O Calls</A>
144<LI><A NAME="tex2html73"
145  HREF="UserManual.html#SECTION00540000000000000000">User Defined Counters</A>
146</UL>
147<BR>
148<LI><A NAME="tex2html74"
149  HREF="UserManual.html#SECTION00600000000000000000">Filtering &amp; Grouping</A>
150<UL>
151<LI><A NAME="tex2html75"
152  HREF="UserManual.html#SECTION00610000000000000000">Function Filtering</A>
153<LI><A NAME="tex2html76"
154  HREF="UserManual.html#SECTION00620000000000000000">Function Grouping</A>
155</UL>
156<BR>
157<LI><A NAME="tex2html77"
158  HREF="UserManual.html#SECTION00700000000000000000">Command Reference</A>
159<UL>
160<LI><A NAME="tex2html78"
161  HREF="UserManual.html#SECTION00710000000000000000">Compiler Wrappers (vtcc,vtcxx,vtf77,vtf90)</A>
162<LI><A NAME="tex2html79"
163  HREF="UserManual.html#SECTION00720000000000000000">Local Trace Unifier (vtunify)</A>
164<LI><A NAME="tex2html80"
165  HREF="UserManual.html#SECTION00730000000000000000">Dyninst Mutator (vtdyn)</A>
166<LI><A NAME="tex2html81"
167  HREF="UserManual.html#SECTION00740000000000000000">Trace Filter Tool (vtfilter)</A>
168</UL>
169<BR>
170<LI><A NAME="tex2html82"
171  HREF="UserManual.html#SECTION00800000000000000000">PAPI Counter Specifications</A>
172<LI><A NAME="tex2html83"
173  HREF="UserManual.html#SECTION00900000000000000000">VampirTrace Installation</A>
174<UL>
175<LI><A NAME="tex2html84"
176  HREF="UserManual.html#SECTION00910000000000000000">Basics</A>
177<LI><A NAME="tex2html85"
178  HREF="UserManual.html#SECTION00920000000000000000">Configure Options</A>
179<LI><A NAME="tex2html86"
180  HREF="UserManual.html#SECTION00930000000000000000">Cross Compilation</A>
181<LI><A NAME="tex2html87"
182  HREF="UserManual.html#SECTION00940000000000000000">Environment Set-Up</A>
183<LI><A NAME="tex2html88"
184  HREF="UserManual.html#SECTION00950000000000000000">Notes for Developers</A>
185</UL></UL>
186<!--End of Table of Contents-->
187<P>
188This documentation describes how to prepare application programs in order
189to have traces generated, when executed. This step is called <SPAN  CLASS="textit">instrumentation</SPAN>.
190Furthermore, it explains how to control the run-time measurement system
191during execution (<SPAN  CLASS="textit">tracing</SPAN>).
192This also includes hardware performance counter sampling,
193as well as selective filtering and grouping of functions.
194
195<P>
196
197<P>
198
199<H1><A NAME="SECTION00200000000000000000">
200Introduction</A>
201</H1>
202
203<P>
204VampirTrace consists of a tool-set and a run-time library for instrumentation
205and tracing of software applications. It is particularly tailored towards 
206parallel and distributed High Performance Computing (HPC) applications.
207
208<P>
209The instrumentation part modifies a given application in order to inject
210additional measurement calls during run-time. The tracing part provides
211the current measurement functionality used by the instrumentation calls.
212By this means, a variety of detailed performance properties can be collected
213and recorded during run-time.
214This includes
215
216<P>
217
218<UL>
219<LI>Function call enter and leave events
220</LI>
221<LI>MPI communication events
222</LI>
223<LI>OpenMP events
224</LI>
225<LI>Hardware performance counters
226</LI>
227<LI>various special purpose events
228</LI>
229</UL>
230
231<P>
232After a successful trace run, VampirTrace writes all collected data to a 
233trace in the Open Trace Format (OTF), see <TT><A NAME="tex2html4"
234  HREF="http://www.tu-dresden.de/zih/otf">http://www.tu-dresden.de/zih/otf</A></TT>.
235
236<P>
237As a result the information is available for post-mortem analysis and
238visualization by various tools.
239Most notably, VampirTrace provides the input data for the Vampir analysis 
240and visualization tool, see <TT><A NAME="tex2html5"
241  HREF="http://www.vampir.eu">http://www.vampir.eu</A></TT>.
242
243<P>
244VampirTrace is included in OpenMPI&nbsp;1.3 and later.
245If not disabled explicitly, VampirTrace is built automatically when installing OpenMPI.
246Refer to <TT><A NAME="tex2html6"
247  HREF="http://www.open-mpi.org/faq/?category=vampirtrace">http://www.open-mpi.org/faq/?category=vampirtrace</A></TT> for more information.
248
249<P>
250Trace files can quickly become very large. With automatic instrumentation,
251even tracing applications that run only for a few seconds can result in
252trace files of several hundred megabytes. To protect users from
253creating trace files of several gigabytes, the default behavior of
254VampirTrace limits the internal buffer to 32 MB. This produces trace
255files that are not larger than 32 MB per process, typically a lot smaller.
256Please read Section <A HREF="#trace_file_size">3.2</A> on how to remove or change the limit.
257
258<P>
259VampirTrace supports various Unix and Linux platforms common in 
260HPC nowadays. It comes as open source software under a BSD License. 
261
262<P>
263
264<H1><A NAME="SECTION00300000000000000000">
265Instrumentation</A>
266</H1>
267
268<P>
269To make measurements with VampirTrace, the user's application program needs to
270be instrumented, i.e., at specific important points (called ``events'') VampirTrace
271measurement calls have to be activated.
272As an example, common events are entering and leaving
273of function calls, as well as sending and receiving of MPI messages.
274
275<P>
276By default, VampirTrace handles this automatically. In order to enable
277instrumentation of function calls, the user only needs to replace the compiler
278and linker commands with VampirTrace's wrappers,
279see Section <A HREF="#compiler_wrappers">2.1</A> below.
280VampirTrace supports different ways of instrumentation as described in
281Section <A HREF="#instrumentation_types">2.2</A>.
282
283<P>
284
285<H1><A NAME="SECTION00310000000000000000">&#160;</A>
286<A NAME="compiler_wrappers">&#160;</A>
287<BR>
288The Compiler Wrappers
289</H1>
290
291<P>
292All the necessary instrumentation of user functions as well as MPI and
293OpenMP events is handled by VampirTrace's compiler wrappers (vtcc, vtcxx, vtf77, and
294vtf90).
295In the script used to build the application (e.g. a makefile), all compile
296and link commands should be replaced by the VampirTrace compiler wrapper.
297The wrappers perform the necessary instrumentation of the program and link
298the suitable VampirTrace library.
299Note that the VampirTrace version included in OpenMPI 1.3
300has additional wrappers (mpicc-vt, mpicxx-vt, mpif77-vt, and mpif90-vt) which
301are like the ordinary MPI compiler wrappers (mpicc and friends) with the extension
302of automatic instrumentation.
303
304<P>
305The following list shows some examples depending on the parallelization
306type of the program:
307
308<P>
309
310<UL>
311<LI><SPAN  CLASS="textbf">Serial programs</SPAN>:
312Compiling serial code is the default behavior of the wrappers.
313Simply replace the compiler by VampirTrace's wrapper:
314
315<P>
316<BR>
317<TABLE CELLPADDING=3>
318<TR><TD ALIGN="LEFT">original:</TD>
319<TD ALIGN="LEFT"><TT>gfortran a.f90 b.f90 -o myprog  </TT></TD>
320</TR>
321<TR><TD ALIGN="LEFT">with instrumentation:</TD>
322<TD ALIGN="LEFT"><TT>vtf90 a.f90 b.f90 -o myprog     </TT></TD>
323</TR>
324</TABLE>
325<BR>
326
327<P>
328This will instrument user functions (if supported by compiler) and
329link the VampirTrace library.
330
331<P>
332</LI>
333<LI><SPAN  CLASS="textbf">MPI parallel programs</SPAN>:
334MPI instrumentation is always handled by means of the PMPI interface
335which is part of the MPI standard.
336This requires the compiler wrapper to link with an MPI-aware version of
337the VampirTrace library.
338If your MPI implementation uses MPI compilers (e.g. mpicc, mpxlf90),
339you need to tell VampirTrace's wrapper to use this compiler
340instead of the serial one:
341
342<P>
343<BR>
344<TABLE CELLPADDING=3>
345<TR><TD ALIGN="LEFT">original:</TD>
346<TD ALIGN="LEFT"><TT>mpicc hello.c -o hello  </TT></TD>
347</TR>
348<TR><TD ALIGN="LEFT">with instrumentation:</TD>
349<TD ALIGN="LEFT"><TT>vtcc -vt:cc mpicc hello.c -o hello    </TT></TD>
350</TR>
351</TABLE>
352<BR>
353
354<P>
355MPI implementations without own compilers require the user to link
356the MPI library manually. In this case, you simply replace the compiler
357by VampirTrace's compiler wrapper:
358
359<P>
360<BR>
361<TABLE CELLPADDING=3>
362<TR><TD ALIGN="LEFT">original:</TD>
363<TD ALIGN="LEFT"><TT>icc hello.c -o hello -lmpi </TT></TD>
364</TR>
365<TR><TD ALIGN="LEFT">with instrumentation:</TD>
366<TD ALIGN="LEFT"><TT>vtcc hello.c -o hello -lmpi  </TT></TD>
367</TR>
368</TABLE>
369<BR>
370
371<P>
372If you want to instrument MPI events only (creates smaller trace files and less overhead)
373use the option <TT>-vt:inst manual</TT> to disable automatic instrumentation
374of user functions (see also Section <A HREF="#A1">2.4</A>).
375
376<P>
377</LI>
378<LI><SPAN  CLASS="textbf">OpenMP parallel programs</SPAN>:
379When VampirTrace detects OpenMP flags on the command line,
380OPARI is invoked for automatic source code instrumentation of OpenMP events:
381
382<P>
383<BR>
384<TABLE CELLPADDING=3>
385<TR><TD ALIGN="LEFT">original:</TD>
386<TD ALIGN="LEFT"><TT>ifort -openmp pi.f -o pi </TT></TD>
387</TR>
388<TR><TD ALIGN="LEFT">with instrumentation:</TD>
389<TD ALIGN="LEFT"><TT>vtf77 -openmp pi.f -o pi </TT></TD>
390</TR>
391</TABLE>
392<BR>
393
394<P>
395For more information about OPARI refer to <TT>share/vampirtrace/doc/opari/Readme.html</TT> in
396VampirTrace's installation directory.
397
398<P>
399</LI>
400<LI><SPAN  CLASS="textbf">Hybrid MPI/OpenMP parallel programs</SPAN>:
401With a combination of the above mentioned approaches, hybrid applications can be instrumented:
402
403<P>
404<BR>
405<TABLE CELLPADDING=3>
406<TR><TD ALIGN="LEFT">original:</TD>
407<TD ALIGN="LEFT"><TT>mpif90 -openmp hybrid.F90 -o hybrid </TT></TD>
408</TR>
409<TR><TD ALIGN="LEFT">with instrumentation:</TD>
410<TD ALIGN="LEFT"><TT>vtf90 -vt:f90 mpif90 -openmp </TT></TD>
411</TR>
412<TR><TD ALIGN="LEFT">&nbsp;</TD>
413<TD ALIGN="LEFT"><TT>hybrid.F90 -o hybrid </TT></TD>
414</TR>
415</TABLE>
416<BR>
417
418<P>
419</LI>
420</UL>
421
422<P>
423The VampirTrace compiler wrappers try to detect automatically which parallelization
424method is used by means of the compiler flags (e.g. <TT>-openmp</TT> or <TT>-lmpi</TT>)
425and the compiler command (e.g. <TT>mpif90</TT>).
426If the compiler wrapper failed to detect this correctly,
427the instrumentation could be incomplete and an unsuitable
428VampirTrace library would be linked to the binary.
429In this case, you should tell the compiler wrapper which parallelization method
430your program uses by the switches
431<TT>-vt:mpi</TT>, <TT>-vt:omp</TT>, and <TT>-vt:hyb</TT> for MPI, OpenMP, and
432hybrid programs, respectively.
433Note that these switches do not change the underlying compiler or compiler flags.
434Use the option <TT>-vt:verbose</TT> to see the command line the compiler wrapper executes.
435Refer to Appendix <A HREF="#comm_wrappers">A.1</A> for a list of all compiler wrapper options.
436
437<P>
438The default settings of the compiler wrappers can be modified in the files
439<TT>share/vampirtrace/vtcc-wrapper-data.txt</TT> (and similar for the other languages)
440in the installation directory of VampirTrace.
441The settings include compilers, compiler flags, libraries, and instrumentation types.
442For example, you could modify the default C compiler
443from <TT>gcc</TT>
444to <TT>mpicc</TT> by changing the line <TT>compiler=gcc</TT> to <TT>compiler=mpicc</TT>.
445This may be convenient if you instrument MPI parallel programs only.
446
447<P>
448
449<H1><A NAME="SECTION00320000000000000000">&#160;</A>
450<A NAME="instrumentation_types">&#160;</A>
451<BR>
452Instrumentation Types
453</H1>
454
455<P>
456The wrapper's option <TT>-vt:inst &lt;insttype&gt;</TT> specifies the
457instrumentation type to use. Following values for <TT>&lt;insttype&gt;</TT> are possible:
458
459<P>
460
461<UL>
462<LI>fully-automatic instrumentation by the compiler (see Section <A HREF="#compiler_instrumentation">2.3</A>):
463
464<P>
465<TABLE CELLPADDING=3>
466<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">insttype</SPAN></TH>
467<TH ALIGN="LEFT"><SPAN  CLASS="textbf">Compilers</SPAN></TH>
468</TR>
469<TR><TD ALIGN="LEFT">gnu</TD>
470<TD ALIGN="LEFT">GNU (e.g., gcc, g++, gfortran, g95)</TD>
471</TR>
472<TR><TD ALIGN="LEFT">intel</TD>
473<TD ALIGN="LEFT">Intel version &ge;10.0 (e.g., icc, icpc, ifort)</TD>
474</TR>
475<TR><TD ALIGN="LEFT">pgi</TD>
476<TD ALIGN="LEFT">Portland Group (PGI) (e.g., pgcc, pgCC, pgf90, pgf77)</TD>
477</TR>
478<TR><TD ALIGN="LEFT">phat</TD>
479<TD ALIGN="LEFT">SUN Fortran 90 (e.g., cc, CC, f90)</TD>
480</TR>
481<TR><TD ALIGN="LEFT">xl</TD>
482<TD ALIGN="LEFT">IBM (e.g., xlcc, xlCC, xlf90)</TD>
483</TR>
484<TR><TD ALIGN="LEFT">ftrace</TD>
485<TD ALIGN="LEFT">NEC SX (e.g., sxcc, sxc++, sxf90)</TD>
486</TR>
487</TABLE>
488
489<P>
490</LI>
491<LI>manual instrumentation (needs source-code modifications):
492
493<P>
494<TABLE CELLPADDING=3>
495<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">insttype</SPAN></TH>
496<TH ALIGN="LEFT"><SPAN  CLASS="textbf">&nbsp;</SPAN></TH>
497</TR>
498<TR><TD ALIGN="LEFT">manual</TD>
499<TD ALIGN="LEFT">VampirTrace's API (see Section <A HREF="#A1">2.4</A>)</TD>
500</TR>
501<TR><TD ALIGN="LEFT">pomp</TD>
502<TD ALIGN="LEFT">POMP INST directives (see Section <A HREF="#A2">2.5</A>)</TD>
503</TR>
504</TABLE>
505
506<P>
507</LI>
508<LI>special instrumentation types (uses external tools):
509
510<P>
511<TABLE CELLPADDING=3>
512<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">insttype</SPAN></TH>
513<TH ALIGN="LEFT"><SPAN  CLASS="textbf">&nbsp;</SPAN></TH>
514</TR>
515<TR><TD ALIGN="LEFT">dyninst</TD>
516<TD ALIGN="LEFT">binary-instrumentation with Dyninst (Section <A HREF="#A3">2.6</A>)</TD>
517</TR>
518</TABLE>
519
520<P>
521</LI>
522</UL>
523
524<P>
525To determine which instrumentation type will be used by default and which other
526are available on your system take look at the entry <TT>inst_avail</TT> in the
527wrapper's configuration file (e.g. <TT>share/vampirtrace/vtcc-wrapper-data.txt</TT> in the
528installation directory of VampirTrace for the C compiler wrapper).
529
530<P>
531See Appendix <A HREF="#comm_wrappers">A.1</A> or type <TT>vtcc -vt:help</TT> for other
532options that can be passed through VampirTrace's compiler wrapper.
533
534<P>
535
536<H1><A NAME="SECTION00330000000000000000">&#160;</A>
537<A NAME="compiler_instrumentation">&#160;</A>
538<BR>
539Automatic Instrumentation
540</H1>
541
542<P>
543Automatic Instrumentation is the most convenient way to instrument your program.
544Simply use the compiler wrappers without any parameters, e.g.:
545
546<P>
547<BR>
548<BR>
549<code>   % vtf90 myprog1.f90 myprog2.f90 -o myprog</code>
550<BR>
551
552<P>
553
554<H2><A NAME="SECTION00331000000000000000">&#160;</A>
555<A NAME="bfdnotes">&#160;</A>
556<BR>
557Notes for Using the GNU, Intel, or Pathscale Compiler
558</H2>
559For these compilers the library <SPAN  CLASS="textit">BFD</SPAN> is required to get symbol information
560of the running application executable. This library is part of the <SPAN  CLASS="textit">GNU Binutils</SPAN>,
561which is downloadable from <TT><A NAME="tex2html7"
562  HREF="http://www.gnu.org/software/binutils">http://www.gnu.org/software/binutils</A></TT>.
563
564<P>
565To get the application executable for BFD during runtime, VampirTrace uses the <TT>/proc</TT> 
566file system. As <TT>/proc</TT> is not present on all operating systems, automatic symbol
567information might not be available. In this case, it is necessary to set the environment
568variable <TT>VT_APPPATH</TT> to the pathname of the application executable to get symbols
569resolved via BFD.
570
571<P>
572Should any problems emerge to get symbol information by using BFD, then the environment
573variable <TT>VT_GNU_NMFILE</TT> can be set to a symbol list file, which is created with the
574command <TT>nm</TT>, like:
575
576<P>
577<BR>
578<BR>
579<code>   % nm myprog &gt; myprog.nm</code>
580<BR>
581<BR>
582<BR>
583Note that the output format of <TT>nm</TT> must be written in BSD-style. See the manual-page
584of nm for getting help about the output format setting.
585
586<P>
587
588<H2><A NAME="SECTION00332000000000000000">
589Known License Issues with BFD</A>
590</H2>
591Please consider that BFD is deliviered under the GNU General Public License
592(GPL). So if you want to build binary packages including VampirTrace make sure
593to use the option <TT>-without-bfd</TT> to get a version without BFD. In this
594case you have to use <TT>nm</TT> to get symbol information from the running
595application executable (see Section&nbsp;<A HREF="#bfdnotes">2.3.1</A>).
596
597<P>
598
599<H2><A NAME="SECTION00333000000000000000">
600Notes on Instrumentation of Inline Functions</A>
601</H2>
602Compilers behave differently when they automatically instrument inlined functions.
603The GNU and Intel &ge;10.0 compilers instrument all functions by default when they
604are used with VampirTrace. They therefore switch off inlining completely, disregarding
605the optimization level chosen.
606One can prevent these particular functions from being instrumented by appending the
607following attribute to function declarations, hence
608making them able to be inlined (this works only for C/C++):
609
610<P>
611<BR>
612<BR>
613<code>      __attribute__ ((__no_instrument_function__))</code>
614<BR>
615<BR>
616
617<P>
618The PGI and IBM compilers prefer inlining over instrumentation when compiling
619with inlining enabled. Thus, one needs to disable inlining to enable instrumentation
620of inline functions and vice versa.
621
622<P>
623The bottom line is that you cannot inline and instrument a function at the same time.
624For more information on how to inline functions read your compiler's manual.
625
626<P>
627
628<H1><A NAME="SECTION00340000000000000000">&#160;</A>
629<A NAME="A1">&#160;</A>
630<BR>
631Manual Instrumentation using the VampirTrace API
632</H1>
633
634<P>
635The <TT>VT_USER_START</TT>, <TT>VT_USER_END</TT> instrumentation calls
636can be used to mark any user-defined sequence of statements.
637
638<P>
639<PRE>
640          Fortran:
641                   #include "vt_user.inc"
642                   VT_USER_START('name')
643                   ...
644                   VT_USER_END('name')
645</PRE> 
646
647<P>
648<PRE>
649          C:
650                   #include "vt_user.h"
651                   VT_USER_START("name");
652                   ...
653                   VT_USER_END("name");
654</PRE>
655If a block has several exit points (as it is often the case for
656functions), all exit points have to be instrumented by
657<TT>VT_USER_END</TT>, too.
658
659<P>
660For C++ it is simpler, as shown in the following example. Only entry points into a
661scope need to be marked. Exit points are detected automatically, when C++
662deletes scope-local variables.
663
664<P>
665<PRE>
666          C++:
667                   #include "vt_user.h"
668                   {
669                     VT_TRACER("name");
670                     ...
671                   }
672</PRE> 
673
674<P>
675For all three languages, the instrumented sources have to be compiled
676  with <TT>-DVTRACE</TT> otherwise the <TT>VT_*</TT> calls are ignored.
677  Note that Fortran source files instrumented this way have to be
678  preprocessed, too.
679
680<P>
681In addition, you can combine this instrumentation type with all other ones.
682  For example, all user functions can be instrumented by a compiler while
683  special source code regions (e.g. loops) can be instrumented by VT's API.
684
685<P>
686Use VT's compiler wrapper (described above) for compiling and linking the
687  instrumented source code, like:
688
689<UL>
690<LI>without other instrumentation (e.g., compiler):
691<BR>
692<BR><code>   % vtcc -vt:inst manual myprog1.c -DVTRACE -o myprog</code>
693<BR>
694<BR>
695</LI>
696<LI>combined with compiler-instrumentation:
697<BR>
698<BR><code>   % vtcc -vt:inst gnu myprog1.c -DVTRACE -o myprog</code>
699<BR>
700<BR>
701</LI>
702</UL>
703
704<P>
705Note that you can also use the option <TT>-vt:inst manual</TT>
706  with non-instrumented sources.
707  Binaries created this way only contain MPI and OpenMP instrumentation,
708  which might be desirable in some cases.
709
710<P>
711
712<H1><A NAME="SECTION00350000000000000000">&#160;</A>
713<A NAME="A2">&#160;</A>
714<BR>
715Manual Instrumentation using POMP
716</H1>
717
718<P>
719POMP (OpenMP Profiling Tool) instrumentation directives are supported for
720  Fortran and C/C++. The main advantage is that by using directives, the
721  instrumentation is ignored during normal compilation.
722
723<P>
724The <TT>INST BEGIN</TT> and <TT>INST END</TT> directives can be used to mark
725  any user-defined sequence of statements.
726  If this block has several exit points, all but the last exit
727  point have to be instrumented by <TT>INST ALTEND</TT>.
728
729<P>
730<PRE>
731          Fortran:
732                   !POMP$ INST BEGIN(name)
733                   ...
734                     [ !POMP$ INST ALTEND(name) ]
735                   ...
736                   !POMP$ INST END(name)
737</PRE> 
738
739<P>
740<PRE>
741          C/C++:   
742                   #pragma pomp inst begin(name)
743                   ...
744                     [ #pragma pomp inst altend(name) ]
745                   ...
746                   #pragma pomp inst end(name)
747</PRE> 
748  At least the main program function has to be instrumented in this way, and
749  additionally, the following must be inserted as the first executable
750  statement of the main program:
751
752<P>
753<PRE>
754          Fortran:
755                   !POMP$ INST INIT
756</PRE> 
757
758<P>
759<PRE>
760          C/C++:
761                   #pragma pomp inst init
762</PRE> 
763
764<P>
765
766<H1><A NAME="SECTION00360000000000000000">&#160;</A>
767<A NAME="A3">&#160;</A>
768<BR>
769Binary instrumentation using Dyninst
770</H1>
771
772<P>
773The option <TT>-vt:inst dyninst</TT> selects the compiler wrapper to
774instrument the application during run-time (binary instrumentation) by using
775Dyninst (<TT><A NAME="tex2html8"
776  HREF="http://www.dyninst.org">http://www.dyninst.org</A></TT>).
777Recompiling is not necessary for this way of instrumenting,
778but relinking, as shown:
779
780<P>
781<BR>
782<BR>
783<code>   % vtf90 -vt:inst dyninst myprog1.o myprog2.o -o myprog</code>
784<BR>
785<BR>
786<BR>
787The compiler wrapper dynamically links the library <TT>libvt.dynatt.so</TT>
788  to the  application. This library attaches the <SPAN  CLASS="textit">Mutator</SPAN>-program
789  <TT>vtdyn</TT> during run-time which invokes the instrumenting by using
790  the Dyninst-API.
791  Note that the application should have been compiled with the <TT>-g</TT>
792  switch in order to have symbol names visible.
793  After a trace-run by using this way of instrumenting, the <TT>vtunify</TT>
794  utility needs to be invoked manually (see Sections <A HREF="#unification">3.3</A> and <A HREF="#VTUNIFY">A.2</A>).
795
796<P>
797To prevent certain functions from being instrumented you can set
798  the environment variable <TT>VT_DYN_BLACKLIST</TT> to a file containing
799  a newline-separated list of function names. All additional overhead due to instrumentation
800  of these functions will be removed.
801
802<P>
803VampirTrace also allows binary instrumentation of functions located in shared libraries.
804  Ensure that the shared libraries have been compiled with <TT>-g</TT> and
805  assign a colon-separated list of their names to
806  the environment variable <TT>VT_DYN_SHLIBS</TT>, e.g.:
807
808<P>
809<BR>
810<BR>
811  <code>   VT_DYN_SHLIBS=libsupport.so:libmath.so</code>
812  <BR>
813<BR>
814
815<P>
816
817<H1><A NAME="SECTION00400000000000000000">
818Runtime Measurement</A>
819</H1>
820
821<P>
822By default, running a VampirTrace instrumented application should result in an
823OTF trace file in the current working directory where the application was
824executed. Use the environment variables <TT>VT_FILE_PREFIX</TT> and <TT>VT_PFORM_GDIR</TT>
825described below to change the name of the trace file and its final location.
826In case a problem occurs, set the environment variable <TT>VT_VERBOSE</TT> to <TT>yes</TT> before
827executing the instrumented application in order to see control messages of the
828VampirTrace run-time system which might help tracking down the problem.
829
830<P>
831The internal buffer of VampirTrace is limited to 32 MB. Use the environment
832variable <TT>VT_BUFFER_SIZE</TT> and <TT>VT_MAX_FLUSHES</TT> to increase
833this limit. Section <A HREF="#trace_file_size">3.2</A> contains further information on
834influencing trace file size.
835
836<P>
837
838<H1><A NAME="SECTION00410000000000000000">
839Environment Variables</A>
840</H1>
841
842<P>
843The following environment variables can be used to control the measurement
844of a VampirTrace instrumented executable:
845
846<P>
847
848<P>
849<TABLE CELLPADDING=3>
850<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">Variable</SPAN></TH>
851<TH ALIGN="LEFT"><SPAN  CLASS="textbf">Purpose</SPAN></TH>
852<TH ALIGN="LEFT"><SPAN  CLASS="textbf">Default</SPAN></TH>
853</TR>
854<TR><TD ALIGN="LEFT"><TT>VT_PFORM_GDIR</TT></TD>
855<TD ALIGN="LEFT">Name of global directory to store final trace file in</TD>
856<TD ALIGN="LEFT"><TT>./</TT></TD>
857</TR>
858<TR><TD ALIGN="LEFT"><TT>VT_PFORM_LDIR</TT></TD>
859<TD ALIGN="LEFT">Name of node-local directory that can be used to store temporary trace files</TD>
860<TD ALIGN="LEFT"><TT>/tmp/</TT></TD>
861</TR>
862<TR><TD ALIGN="LEFT"><TT>VT_FILE_PREFIX</TT></TD>
863<TD ALIGN="LEFT">Prefix used for trace filenames</TD>
864<TD ALIGN="LEFT"><TT>a</TT></TD>
865</TR>
866<TR><TD ALIGN="LEFT"><TT>VT_APPPATH</TT></TD>
867<TD ALIGN="LEFT">Path to the application executable</TD>
868<TD ALIGN="LEFT">-</TD>
869</TR>
870<TR><TD ALIGN="LEFT"><TT>VT_BUFFER_SIZE</TT></TD>
871<TD ALIGN="LEFT">Size of internal event trace buffer. This is the place where
872        event records are stored, before being written to a file.</TD>
873<TD ALIGN="LEFT">32M</TD>
874</TR>
875<TR><TD ALIGN="LEFT"><TT>VT_MAX_FLUSHES</TT></TD>
876<TD ALIGN="LEFT">Maximum number of buffer flushes</TD>
877<TD ALIGN="LEFT">1</TD>
878</TR>
879<TR><TD ALIGN="LEFT"><TT>VT_VERBOSE</TT></TD>
880<TD ALIGN="LEFT">Print VampirTrace related control information during measurement?</TD>
881<TD ALIGN="LEFT">no</TD>
882</TR>
883<TR><TD ALIGN="LEFT"><TT>VT_METRICS</TT></TD>
884<TD ALIGN="LEFT">Specify counter metrics to be recorded with trace events as a
885        colon-separated list of names. (for details see Appendix <A HREF="#papi">B</A>)</TD>
886<TD ALIGN="LEFT">-</TD>
887</TR>
888<TR><TD ALIGN="LEFT"><TT>VT_MEMTRACE</TT></TD>
889<TD ALIGN="LEFT">Enable memory allocation counters? (see Sec. <A HREF="#mem_alloc_counters">4.2</A>)</TD>
890<TD ALIGN="LEFT">no</TD>
891</TR>
892<TR><TD ALIGN="LEFT"><TT>VT_IOTRACE</TT></TD>
893<TD ALIGN="LEFT">Enable tracing of application I/O calls? (see Sec. <A HREF="#app_io_calls">4.3</A>)</TD>
894<TD ALIGN="LEFT">no</TD>
895</TR>
896<TR><TD ALIGN="LEFT"><TT>VT_MPITRACE</TT></TD>
897<TD ALIGN="LEFT">Enable tracing of MPI events?</TD>
898<TD ALIGN="LEFT">yes</TD>
899</TR>
900<TR><TD ALIGN="LEFT"><TT>VT_DYN_BLACKLIST</TT></TD>
901<TD ALIGN="LEFT">Name of blacklist file for Dyninst instrumentation (see Section <A HREF="#A3">2.6</A>)</TD>
902<TD ALIGN="LEFT">-</TD>
903</TR>
904<TR><TD ALIGN="LEFT"><TT>VT_DYN_SHLIBS</TT></TD>
905<TD ALIGN="LEFT">Colon-separated list of shared libraries for Dyninst instrumentation (see Section <A HREF="#A3">2.6</A>)</TD>
906<TD ALIGN="LEFT">-</TD>
907</TR>
908<TR><TD ALIGN="LEFT"><TT>VT_FILTER_SPEC</TT></TD>
909<TD ALIGN="LEFT">Name of function/region filter file (see Section <A HREF="#function_filter">5.1</A>)</TD>
910<TD ALIGN="LEFT">-</TD>
911</TR>
912<TR><TD ALIGN="LEFT"><TT>VT_GROUPS_SPEC</TT></TD>
913<TD ALIGN="LEFT">Name of function grouping file
914        (See Section <A HREF="#function_groups">5.2</A>)</TD>
915<TD ALIGN="LEFT">-</TD>
916</TR>
917<TR><TD ALIGN="LEFT"><TT>VT_UNIFY</TT></TD>
918<TD ALIGN="LEFT">Unify local trace files afterwards?</TD>
919<TD ALIGN="LEFT">yes</TD>
920</TR>
921<TR><TD ALIGN="LEFT"><TT>VT_COMPRESSION</TT></TD>
922<TD ALIGN="LEFT">Write compressed trace files?</TD>
923<TD ALIGN="LEFT">yes</TD>
924</TR>
925</TABLE>
926
927<P>
928The value for the first three variables can contain (sub)strings of the
929form <TT>$XYZ</TT> or <TT>${XYZ}</TT> where <TT>XYZ</TT> is the name of
930another environment variable.
931Evaluation of the environment variable is done at measurement run-time.
932
933<P>
934When you use these environment variables, make sure that they have the same
935value for all processes of your application on <SPAN  CLASS="textbf">all</SPAN> nodes of your cluster.
936Some cluster environments do not automatically transfer your environment
937when executing parts of your job on remote nodes of the cluster, and you
938may need to explicitly set and export them in batch job submission scripts.
939
940<P>
941
942<H1><A NAME="SECTION00420000000000000000">&#160;</A>
943<A NAME="trace_file_size">&#160;</A>
944<BR>
945Influencing Trace File Size
946</H1>
947
948<P>
949The default values of the environment variables <TT>VT_BUFFER_SIZE</TT> and <BR><TT>VT_MAX_FLUSHES</TT> limit the internal buffer of VampirTrace to
95032 MB and the number of times that the buffer is flushed to 1. Events that
951should be recorded after the limit has been reached are no longer written into
952the trace file. The environment variables apply to every process of a
953parallel application, meaning that applications with <SPAN  CLASS="textit">n</SPAN> processes
954will typically create trace files <SPAN  CLASS="textit">n</SPAN> times the size of a serial
955application.
956
957<P>
958To remove the limit and get a complete trace of an application, set <BR><TT>VT_MAX_FLUSHES</TT> to <TT>0</TT>. This causes VampirTrace to always
959write the buffer to disk when the buffer is full. To change the size of the
960buffer, use the variable <TT>VT_BUFFER_SIZE</TT>. The optimal value for
961this variable depends on the application that should be traced. Setting a
962small value will increase the memory that is available to the application but
963will trigger frequent buffer flushes by VampirTrace. These buffer flushes can
964significantly change the behavior of the application. On the other hand,
965setting a large value, like <TT>2G</TT>, will minimize buffer flushes by
966VampirTrace, but decrease the memory available to the application. If not
967enough memory is available to hold the VampirTrace buffer and the application
968data this may cause parts of the application to be swapped to disk leading
969also to a significant change in the behavior of the application.
970
971<P>
972
973<H1><A NAME="SECTION00430000000000000000">&#160;</A>
974<A NAME="unification">&#160;</A>
975<BR>
976Unification of local Traces
977</H1>
978
979<P>
980After a run of an instrumented application the traces of the single
981processes need to be <SPAN  CLASS="textit">unified</SPAN> in terms of timestamps and event IDs.
982In most cases, this happens automatically.
983But under certain circumstances it is necessary to perform unification of local
984traces manually. To do this, use the command:
985
986<P>
987<BR>
988<BR>
989<code>   % vtunify &lt;no-of-traces&gt; &lt;prefix&gt;</code>
990<BR>
991<BR>
992<BR>
993For example, this is required on the BlueGene/L platform or when using Dyninst
994instrumentation.
995
996<P>
997
998<H1><A NAME="SECTION00500000000000000000">
999Recording additional Events and Counters</A>
1000</H1>
1001
1002<P>
1003
1004<H1><A NAME="SECTION00510000000000000000">
1005PAPI Hardware Performance Counters</A>
1006</H1>
1007
1008<P>
1009If VampirTrace has been built with hardware-counter support enabled (see
1010  Section <A HREF="#install">C</A>), VampirTrace is capable of recording hardware counter
1011  information as part of the event records. To request the measurement of
1012  certain counters, the user must set the environment variable <TT>VT_METRICS</TT>.
1013  The variable should contain a colon-separated list of counter names,
1014  or a predefined platform-specific group.
1015  Metric names can be any PAPI preset names or PAPI native counter names.
1016  For example, set
1017
1018<P>
1019<BR>
1020<BR>
1021  <code>   VT_METRICS=PAPI_FP_OPS:PAPI_L2_TCM</code>
1022  <BR>
1023<BR>
1024<BR>
1025to record the number of floating point instructions and level 2 cache misses.
1026  See Appendix <A HREF="#papi">B</A> for a full list of PAPI preset counters.
1027
1028<P>
1029The user can leave the environment variable unset to indicate that no
1030  counters are requested. If any of the requested counters are not recognized
1031  or the full list of counters cannot be recorded due to hardware-resource
1032  limits, program execution will be aborted with an error message.
1033
1034<P>
1035
1036<H1><A NAME="SECTION00520000000000000000">&#160;</A>
1037<A NAME="mem_alloc_counters">&#160;</A>
1038<BR>
1039Memory Allocation Counters
1040</H1>
1041
1042<P>
1043The GNU glibc implementation provides a special hook mechanism that allows
1044  intercepting all calls to allocation and free functions
1045  (e.g. <TT>malloc</TT>, <TT>realloc</TT>, <TT>free</TT>).
1046  This is independent from compilation or source code access, but relies on the
1047  underlying system library.
1048
1049<P>
1050If VampirTrace has been built with memory-tracing support enabled (see
1051  Section <A HREF="#install">C</A>), VampirTrace is capable of recording memory allocation
1052  information as part of the event records. To request the measurement of
1053  the application's allocated memory, the user must set the environment variable
1054  <TT>VT_MEMTRACE</TT> to <TT>yes</TT>.
1055
1056<P>
1057
1058<H4><A NAME="SECTION00520010000000000000">
1059Note:</A>
1060</H4>
1061  This approach to get memory allocation information requires changing internal
1062  function pointers in a non-thread-safe way, so VampirTrace doesn't support
1063  memory tracing for OpenMP-parallelized programs!
1064
1065<P>
1066
1067<H1><A NAME="SECTION00530000000000000000">&#160;</A>
1068<A NAME="app_io_calls">&#160;</A>
1069<BR>
1070Application I/O Calls
1071</H1>
1072
1073<P>
1074Calls to functions which reside in external libraries can be intercepted by
1075  implementing identical functions and linking them before the external library.
1076  Such ``wrapper functions'' can record the parameters and return values of the
1077  library functions.
1078
1079<P>
1080If VampirTrace has been built with I/O tracing support, it uses this technique
1081  for recording calls to I/O functions of the standard C library which are
1082  executed by the application. Following functions
1083  are intercepted by VampirTrace:
1084
1085<P>
1086<TABLE CELLPADDING=3>
1087<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>open</TT></TD>
1088<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>read</TT></TD>
1089<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fdopen</TT></TD>
1090<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fread</TT></TD>
1091</TR>
1092<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>open64</TT></TD>
1093<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>write</TT></TD>
1094<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fopen</TT></TD>
1095<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fwrite</TT></TD>
1096</TR>
1097<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>creat</TT></TD>
1098<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>readv</TT></TD>
1099<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fopen64</TT></TD>
1100<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fgetc</TT></TD>
1101</TR>
1102<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>creat64</TT></TD>
1103<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>writev</TT></TD>
1104<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fclose</TT></TD>
1105<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>getc</TT></TD>
1106</TR>
1107<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>close</TT></TD>
1108<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>pread</TT></TD>
1109<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fseek</TT></TD>
1110<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fputc</TT></TD>
1111</TR>
1112<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>dup</TT></TD>
1113<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>pwrite</TT></TD>
1114<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fseeko</TT></TD>
1115<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>putc</TT></TD>
1116</TR>
1117<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>dup2</TT></TD>
1118<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>pread64</TT></TD>
1119<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fseeko64</TT></TD>
1120<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fgets</TT></TD>
1121</TR>
1122<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>lseek</TT></TD>
1123<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>pwrite64</TT></TD>
1124<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>rewind</TT></TD>
1125<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fputs</TT></TD>
1126</TR>
1127<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>lseek64</TT></TD>
1128<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110>&nbsp;</TD>
1129<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fsetpos</TT></TD>
1130<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fscanf</TT></TD>
1131</TR>
1132<TR><TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110>&nbsp;</TD>
1133<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110>&nbsp;</TD>
1134<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fsetpos64</TT></TD>
1135<TD ALIGN="LEFT" VALIGN="TOP" WIDTH=110><TT>fprintf</TT></TD>
1136</TR>
1137</TABLE>
1138
1139<P>
1140The gathered information will be saved
1141  as I/O event records in the trace file. This feature has to be activated for
1142  each tracing run by setting the environment variable <TT>VT_IOTRACE</TT> to
1143  <TT>yes</TT>.
1144
1145<P>
1146
1147<H1><A NAME="SECTION00540000000000000000">
1148User Defined Counters</A>
1149</H1>
1150
1151<P>
1152In addition to the manual instrumentation (see Section <A HREF="#A1">2.4</A>) the VampirTrace API
1153  provides instrumentation calls which allow recording of
1154  program variable values (e.g. iteration counts, calculation results, ...) or any other
1155  numerical quantity.
1156  A user defined counter is identified by its name, the counter group it belongs to,
1157  the type of its value (integer or floating-point), and the unit that the value is
1158  quoted (e.g. ``GFlop/sec'').
1159
1160<P>
1161The <TT>VT_COUNT_GROUP_DEF</TT> and <TT>VT_COUNT_DEF</TT> instrumentation
1162  calls can be used to define counter groups and counters:
1163
1164<P>
1165<PRE>
1166Fortran:
1167           #include "vt_user.inc"
1168           integer :: id, gid
1169           VT_COUNT_GROUP_DEF('name', gid)
1170           VT_COUNT_DEF('name', 'unit', type, gid, id)
1171</PRE> 
1172
1173<P>
1174<PRE>
1175C/C++:
1176           #include "vt_user.h"
1177           unsigned int id, gid;
1178           gid = VT_COUNT_GROUP_DEF('name');
1179           id = VT_COUNT_DEF("name", "unit", type, gid);
1180</PRE>
1181
1182<P>
1183The definition of a counter group is optionally. If no special counter group is desired
1184  the default group ``User'' can be used.
1185  In this case, set the parameter <TT>gid</TT> of <TT>VT_COUNT_DEF</TT> to
1186  <TT>VT_COUNT_DEFGROUP</TT>.
1187
1188<P>
1189The third parameter <TT>type</TT> of <TT>VT_COUNT_DEF</TT> specifies the data
1190  type of the counter value. To record a value for any of the defined counters the
1191  corresponding instrumentation call <TT>VT_COUNT_*_VAL</TT> must be invoked.
1192
1193<P>
1194
1195<P>
1196<TABLE CELLPADDING=3>
1197<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">Fortran:</SPAN></TH>
1198<TD ALIGN="LEFT">&nbsp;</TD>
1199<TD ALIGN="LEFT">&nbsp;</TD>
1200</TR>
1201<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">Type</SPAN></TH>
1202<TD ALIGN="LEFT"><SPAN  CLASS="textbf">Count call</SPAN></TD>
1203<TD ALIGN="LEFT"><SPAN  CLASS="textbf">Data type</SPAN></TD>
1204</TR>
1205<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_INTEGER</TT></TD>
1206<TD ALIGN="LEFT"><TT>VT_COUNT_INTEGER_VAL</TT></TD>
1207<TD ALIGN="LEFT">integer (4 byte)</TD>
1208</TR>
1209<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_INTEGER8</TT></TD>
1210<TD ALIGN="LEFT"><TT>VT_COUNT_INTEGER8_VAL</TT></TD>
1211<TD ALIGN="LEFT">integer (8 byte)</TD>
1212</TR>
1213<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_REAL</TT></TD>
1214<TD ALIGN="LEFT"><TT>VT_COUNT_REAL_VAL</TT></TD>
1215<TD ALIGN="LEFT">real</TD>
1216</TR>
1217<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_DOUBLE</TT></TD>
1218<TD ALIGN="LEFT"><TT>VT_COUNT_DOUBLE_VAL</TT></TD>
1219<TD ALIGN="LEFT">double precision</TD>
1220</TR>
1221</TABLE>
1222
1223<P>
1224<TABLE CELLPADDING=3>
1225<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">C/C++:</SPAN></TH>
1226<TD ALIGN="LEFT">&nbsp;</TD>
1227<TD ALIGN="LEFT">&nbsp;</TD>
1228</TR>
1229<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">Type</SPAN></TH>
1230<TD ALIGN="LEFT"><SPAN  CLASS="textbf">Count call</SPAN></TD>
1231<TD ALIGN="LEFT"><SPAN  CLASS="textbf">Data type</SPAN></TD>
1232</TR>
1233<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_SIGNED</TT></TD>
1234<TD ALIGN="LEFT"><TT>VT_COUNT_SIGNED_VAL</TT></TD>
1235<TD ALIGN="LEFT">signed int (max. 64-bit)</TD>
1236</TR>
1237<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_UNSIGNED</TT></TD>
1238<TD ALIGN="LEFT"><TT>VT_COUNT_UNSIGNED_VAL</TT></TD>
1239<TD ALIGN="LEFT">unsigned int (max. 64-bit)</TD>
1240</TR>
1241<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_FLOAT</TT></TD>
1242<TD ALIGN="LEFT"><TT>VT_COUNT_FLOAT_VAL</TT></TD>
1243<TD ALIGN="LEFT">float</TD>
1244</TR>
1245<TR><TD ALIGN="LEFT"><TT>VT_COUNT_TYPE_DOUBLE</TT></TD>
1246<TD ALIGN="LEFT"><TT>VT_COUNT_DOUBLE_VAL</TT></TD>
1247<TD ALIGN="LEFT">double</TD>
1248</TR>
1249</TABLE>
1250
1251<P>
1252The following example records the loop index <TT>i</TT>:
1253
1254<P>
1255<PRE>
1256Fortran:
1257
1258  #include "vt_user.inc"
1259
1260  program main
1261  integer :: i, cid, cgid
1262
1263  VT_COUNT_GROUP_DEF('loopindex', cgid)
1264  VT_COUNT_DEF('i', '#', VT_COUNT_TYPE_INTEGER, cgid, cid)
1265
1266  do i=1,100
1267    VT_COUNT_INTEGER_VAL(cid, i)
1268  end do
1269
1270  end program main
1271</PRE> 
1272
1273<P>
1274<PRE>
1275C/C++:
1276
1277  #include "vt_user.h"
1278
1279  int main() {
1280    unsigned int i, cid, cgid;
1281
1282    cgid = VT_COUNT_GROUP_DEF('loopindex');
1283    cid = VT_COUNT_DEF("i", "#", VT_COUNT_TYPE_UNSIGNED,
1284                       cgid);
1285
1286    for( i = 1; i &lt;= 100; i++ ) {
1287      VT_COUNT_UNSIGNED_VAL(cid, i);
1288    }
1289
1290    return 0;
1291  }
1292</PRE>
1293
1294<P>
1295For all three languages the instrumented sources have to be compiled
1296  with <TT>-DVTRACE</TT>. Otherwise the <TT>VT_*</TT> calls are ignored.
1297  If additionally any functions or regions are manually instrumented by VT's API
1298  (see Section <A HREF="#A1">2.4</A>) and only the instrumentation calls for user defined
1299  counter should be disabled, then the sources have to be compiled with
1300  <TT>-DVTRACE_NO_COUNT</TT>, too.
1301
1302<P>
1303
1304<H1><A NAME="SECTION00600000000000000000">
1305Filtering &amp; Grouping</A>
1306</H1>
1307
1308<P>
1309
1310<H1><A NAME="SECTION00610000000000000000">&#160;</A>
1311<A NAME="function_filter">&#160;</A>
1312<BR>
1313Function Filtering
1314</H1>
1315
1316<P>
1317By default, all calls of instrumented functions will be traced, so that the
1318  resulting trace files can easily become very large. In order to decrease the
1319  size of a trace, VampirTrace allows the specification of filter directives
1320  before running an instrumented application.
1321  The user can decide on how often an instrumented function/region is to be
1322  recorded to a trace file.
1323  To use a filter, the environment variable <TT>VT_FILTER_SPEC</TT> needs to be
1324  defined. It should contain the path and name of a file with filter directives.
1325
1326<P>
1327Below, there is an example of a file containing filter directives:
1328
1329<P>
1330<PRE>
1331  #    VampirTrace region filter specification
1332  #   
1333  #    call limit definitions and region assignments
1334  #   
1335  #    syntax: &lt;regions&gt; -- &lt;limit&gt;
1336  #   
1337  #      regions    semicolon-separated list of regions
1338  #                 (can be wildcards)
1339  #      limit      assigned call limit
1340  #                  0 = region(s) denied
1341  #                 -1 = unlimited
1342  #   
1343  add;sub;mul;div -- 1000
1344  * -- 3000000
1345</PRE> 
1346
1347<P>
1348These region filter directives cause that the functions <TT>add</TT>,
1349<TT>sub</TT>, <TT>mul</TT> and <TT>div</TT> to be recorded at most 1000 times.
1350The remaining functions <TT>*</TT> will be recorded at most 3000000 times.
1351
1352<P>
1353Besides creating filter files by hand, you can also use the <TT>vtfilter</TT>
1354tool to generate them automatically. This tool reads the provided trace
1355and decides whether a function should be filtered or not, based on the evaluation of
1356certain parameters. For more information see Section <A HREF="#VTFILTER">A.4</A>.
1357
1358<P>
1359
1360<H1><A NAME="SECTION00620000000000000000">&#160;</A>
1361<A NAME="function_groups">&#160;</A>
1362<BR>
1363Function Grouping
1364</H1>
1365
1366<P>
1367VampirTrace allows assigning functions/regions to a group.
1368  Groups can, for instance, be highlighted by different colors in Vampir displays.
1369  The following standard groups are created by VampirTrace:
1370
1371<P>
1372<TABLE CELLPADDING=3>
1373<TR><TH ALIGN="LEFT"><SPAN  CLASS="textbf">Group name</SPAN></TH>
1374<TH ALIGN="LEFT"><SPAN  CLASS="textbf">Contained functions/regions</SPAN></TH>
1375</TR>
1376<TR><TD ALIGN="LEFT"><TT>MPI</TT></TD>
1377<TD ALIGN="LEFT">MPI functions</TD>
1378</TR>
1379<TR><TD ALIGN="LEFT"><TT>OMP</TT></TD>
1380<TD ALIGN="LEFT">OpenMP constructs and functions</TD>
1381</TR>
1382<TR><TD ALIGN="LEFT"><TT>MEM</TT></TD>
1383<TD ALIGN="LEFT">Memory allocation functions (see <A HREF="#mem_alloc_counters">4.2</A>)</TD>
1384</TR>
1385<TR><TD ALIGN="LEFT"><TT>I/O</TT></TD>
1386<TD ALIGN="LEFT">I/O functions (see <A HREF="#app_io_calls">4.3</A>)</TD>
1387</TR>
1388<TR><TD ALIGN="LEFT"><TT>Application</TT></TD>
1389<TD ALIGN="LEFT">remaining instrumented functions and source code regions</TD>
1390</TR>
1391</TABLE>
1392
1393<P>
1394Additionally, you can create your own groups, e.g. to better distinguish
1395  different phases of an application.
1396  To use function/region grouping set the environment variable
1397  <TT>VT_GROUPS_SPEC</TT> to the path of a file which contains the group
1398  assignments.
1399  Below, there is an example of how to use group assignments:
1400
1401<P>
1402<PRE>
1403  #    VampirTrace region groups specification
1404  #
1405  #    group definitions and region assignments
1406  #
1407  #    syntax: &lt;group&gt;=&lt;regions&gt;
1408  #
1409  #      group      group name
1410  #      regions    semicolon-separated list of regions
1411  #                 (can be wildcards)
1412  #
1413  CALC=add;sub;mul;div
1414  USER=app_*
1415</PRE> 
1416
1417<P>
1418These group assignments make the functions <TT>add</TT>, <TT>sub</TT>,
1419<TT>mul</TT> and <TT>div</TT> associated with group ``CALC'' and all functions
1420with the prefix <TT>app_</TT> are associated with group ``USER''.
1421
1422<P>
1423
1424<P>
1425
1426<H1><A NAME="SECTION00700000000000000000">
1427Command Reference</A>
1428</H1>
1429
1430<H1><A NAME="SECTION00710000000000000000">&#160;</A>
1431<A NAME="comm_wrappers">&#160;</A>
1432<BR>
1433Compiler Wrappers (vtcc,vtcxx,vtf77,vtf90)
1434</H1>
1435
1436<P>
1437<PRE>
1438vtcc,vtcxx,vtf77,vtf90 - compiler wrappers for C, C++,
1439                         Fortran 77, Fortran 90
1440
1441Syntax: vt&lt;cc|cxx|f77|f90&gt; [-vt:&lt;cc|cxx|f77|f90&gt; &lt;cmd&gt;]
1442        [-vt:inst &lt;insttype&gt;] [-vt:&lt;seq|mpi|omp|hyb&gt;]
1443        [-vt:opari &lt;args&gt;] [-vt:verbose] [-vt:version]
1444        [-vt:showme] [-vt:showme_compile]
1445        [-vt:showme_link] ...
1446
1447options:
1448  -vt:help            Show this help message.
1449  -vt:&lt;cc|cxx|f77|f90&gt; &lt;cmd&gt;
1450                      Set the underlying compiler command.
1451
1452  -vt:inst &lt;insttype&gt; Set the instrumentation type.
1453
1454   possible values:
1455
1456    gnu               fully-automatic by GNU compiler
1457    intel             ... Intel (version &gt;= 10.x) ...
1458    pgi               ... Portland Group (PGI) ...
1459    phat              ... SUN Fortran 90 ...
1460    xl                ... IBM ...
1461    ftrace            ... NEC SX ...
1462    manual            manual by using VampirTrace's API
1463    pomp              manual by using using POMP INST directives
1464    dyninst           binary by using Dyninst (www.dyninst.org)
1465
1466  -vt:opari &lt;args&gt;    Set options for OPARI command. (see
1467                      share/vampirtrace/doc/opari/Readme.html)
1468
1469  -vt:&lt;seq|mpi|omp|hyb&gt;
1470                      Force application's parallelization type.
1471                      Necessary, if this cannot be determined
1472                      by underlying compiler and flags.
1473                      seq = sequential
1474                      mpi = parallel (uses MPI)
1475                      omp = parallel (uses OpenMP)
1476                      hyb = hybrid parallel (MPI + OpenMP)
1477                      (default: automatically determining by
1478                       underlying compiler and flags)
1479
1480  -vt:verbose         Enable verbose mode.
1481
1482  -vt:showme          Do not invoke the underlying compiler.
1483                      Instead, show the command line that
1484                      would be executed.
1485
1486  -vt:showme_compile  Do not invoke the underlying compiler.
1487                      Instead, show the compiler flags that
1488                      would be supplied to the compiler.
1489
1490  -vt:showme_link     Do not invoke the underlying compiler.
1491                      Instead, show the linker flags that
1492                      would be supplied to the compiler.
1493
1494  See the man page for your underlying compiler for other
1495  options that can be passed through 'vt&lt;cc|cxx|f77|f90&gt;'.
1496
1497Environment variables:
1498  VT_CC               Equivalent to '-vt:cc'
1499  VT_CXX              Equivalent to '-vt:cxx'
1500  VT_F77              Equivalent to '-vt:f77'
1501  VT_F90              Equivalent to '-vt:f90'
1502  VT_INST             Equivalent to '-vt:inst'
1503
1504  The corresponding command line options overwrite the
1505  environment variable settings.
1506
1507Examples:
1508  automatically instrumentation by using GNU compiler:
1509
1510     vtcc -vt:cc gcc -vt:inst gnu -c foo.c -o foo.o
1511     vtcc -vt:cc gcc -vt:inst gnu -c bar.c -o bar.o
1512     vtcc -vt:cc gcc -vt:inst gnu foo.o bar.o -o foo
1513
1514  manually instrumentation by using VT's API:
1515
1516     vtf90 -vt:inst manual foobar.F90 -o foobar -DVTRACE
1517
1518  IMPORTANT: Fortran source files instrumented by VT's API or
1519             POMP directives have to be preprocessed by CPP.
1520</PRE>
1521
1522<P>
1523
1524<H1><A NAME="SECTION00720000000000000000">&#160;</A>
1525<A NAME="VTUNIFY">&#160;</A>
1526<BR>
1527Local Trace Unifier (vtunify)
1528</H1>
1529
1530<P>
1531<PRE>
1532vtunify - local trace unifier for VampirTrace.
1533
1534Syntax: vtunify &lt;#files&gt; &lt;iprefix&gt; [-o &lt;oprefix&gt;]
1535        [-c|--compress &lt;on|off&gt;] [-k|--keeplocal]
1536        [-v|--verbose]
1537
1538Options:
1539  -h, --help          Show this help message.
1540
1541  #files              number of local trace files
1542                      (equal to # of '*.uctl' files)
1543
1544  iprefix             prefix of input trace filename.
1545
1546  -o &lt;oprefix&gt;        prefix of output trace filename.
1547
1548  -s &lt;statsofile&gt;     statistics output filename
1549                      default=&lt;oprefix&gt;.stats
1550
1551  -q, --noshowstats   Don't show statistics on stdout.
1552
1553  -c, --nocompress    Don't compress output trace files.
1554
1555  -k, --keeplocal     Don't remove input trace files.
1556
1557  -v, --verbose       Enable verbose mode.
1558</PRE>
1559
1560<P>
1561
1562<H1><A NAME="SECTION00730000000000000000">&#160;</A>
1563<A NAME="VTDYN">&#160;</A>
1564<BR>
1565Dyninst Mutator (vtdyn)
1566</H1>
1567
1568<P>
1569<PRE>
1570vtdyn - Dyninst Mutator for VampirTrace.
1571
1572Syntax: vtdyn [-v|--verbose] [-s|--shlib &lt;shlib&gt;[,...]]
1573              [-b|--blacklist &lt;bfile&gt; [-p|--pid &lt;pid&gt;]
1574              &lt;app&gt; [appargs ...]
1575
1576Options:
1577  -h, --help          Show this help message.
1578
1579  -v, --verbose       Enable verbose mode.
1580
1581  -s, --shlib         Comma-separated list of shared libraries
1582  &lt;shlib&gt;[,...]       which should also be instrumented.
1583
1584  -b, --blacklist     Set path of blacklist file containing
1585  &lt;bfile&gt;             a newline-separated list of functions
1586                      which should not be instrumented.
1587
1588  -p, --pid &lt;pid&gt;     application's process id
1589                      (attaches the mutator to a running process)
1590
1591  app                 path of application executable
1592
1593  appargs             application's arguments
1594</PRE>
1595
1596<P>
1597
1598<H1><A NAME="SECTION00740000000000000000">&#160;</A>
1599<A NAME="VTFILTER">&#160;</A>
1600<BR>
1601Trace Filter Tool (vtfilter)
1602</H1>
1603
1604<P>
1605<PRE>
1606vtfilter - filter generator for VampirTrace
1607
1608Syntax:
1609    Filter a trace file using an already existing filter file:
1610       vtfilter -filt [filt-options] &lt;input trace file&gt;
1611    Generate a filter:
1612       vtfilter -gen [gen-options] &lt;input trace file&gt;
1613
1614general options:
1615    -h, --help            show this help message
1616    -p                    show progress
1617
1618filt-options:
1619    -to &lt;file&gt;            output trace file name
1620   
1621    -fi &lt;file&gt;            input filter file name
1622   
1623    -z &lt;zlevel&gt;           Set the compression level. Level
1624                          reaches from 0 to 9 where 0 is no
1625                          compression and 9 is the highest
1626                          level. Standard is 4.
1627                         
1628    -f &lt;n&gt;                Set max number of file handles
1629                          available. Standard is 256.
1630
1631gen-options:
1632    -fo &lt;file&gt;            output filter file name
1633   
1634    -r &lt;n&gt;                Reduce the trace size to &lt;n&gt; percent
1635                          of the original size. The program
1636                          relies on the fact that the major
1637                          part of the trace are function calls.
1638                          The approximation of size will get
1639                          worse with a rising percentage of
1640                          communication and other non function
1641                          calling or performance counter
1642                          records.
1643                         
1644    -l &lt;n&gt;                Limit the number of accepted
1645                          function calls for filtered functions
1646                          to &lt;n&gt;. Standard is 0.
1647                         
1648    -ex &lt;f&gt;,&lt;f&gt;,...       Exclude certain symbols from
1649                          filtering. A symbol may contain
1650                          wildcards.
1651                         
1652    -in &lt;f&gt;,&lt;f&gt;,...       Force to include certain symbols
1653                          into the filter. A symbol may contain
1654                          wildcards.
1655                         
1656    -inc                  Automatically include children of
1657                          included functions as well into the
1658                          filter.
1659                         
1660    -stats                Prints out the desired and the
1661                          expected percentage of file size.
1662
1663
1664  environment variables:
1665    TRACEFILTER_EXCLUDEFILE  Specifies a file containing a list
1666                             of symbols not to be filtered. The
1667                             list of members can be seperated
1668                             by space, comma, tab, newline and
1669                             may contain wildcards.
1670                             
1671    TRACEFILTER_INCLUDEFILE  Specifies a file containing a list
1672                             of symbols  to be filtered.
1673</PRE>
1674
1675<P>
1676
1677<H1><A NAME="SECTION00800000000000000000">&#160;</A>
1678<A NAME="papi">&#160;</A>
1679<BR>
1680PAPI Counter Specifications
1681</H1>
1682
1683<P>
1684Available counter names can be queried with the PAPI commands
1685<TT>papi_avail</TT> and <TT>papi_native_avail</TT>.
1686There are limitations to the combinations of counters. To check
1687whether your choice works properly, use the command
1688<BR><TT>papi_event_chooser</TT>.
1689
1690<P>
1691<PRE>
1692PAPI_L[1|2|3]_[D|I|T]C[M|H|A|R|W]   
1693              Level 1/2/3 data/instruction/total cache
1694              misses/hits/accesses/reads/writes
1695
1696PAPI_L[1|2|3]_[LD|ST]M   
1697              Level 1/2/3 load/store misses                       
1698
1699PAPI_CA_SNP   Requests for a snoop                               
1700PAPI_CA_SHR   Requests for exclusive access to shared cache line 
1701PAPI_CA_CLN   Requests for exclusive access to clean cache line   
1702PAPI_CA_INV   Requests for cache line invalidation               
1703PAPI_CA_ITV   Requests for cache line intervention               
1704
1705PAPI_BRU_IDL  Cycles branch units are idle                       
1706PAPI_FXU_IDL  Cycles integer units are idle                       
1707PAPI_FPU_IDL  Cycles floating point units are idle               
1708PAPI_LSU_IDL  Cycles load/store units are idle                   
1709
1710PAPI_TLB_DM   Data translation lookaside buffer misses           
1711PAPI_TLB_IM   Instruction translation lookaside buffer misses     
1712PAPI_TLB_TL   Total translation lookaside buffer misses           
1713
1714PAPI_BTAC_M   Branch target address cache misses                 
1715PAPI_PRF_DM   Data prefetch cache misses                         
1716PAPI_TLB_SD   Translation lookaside buffer shootdowns             
1717
1718PAPI_CSR_FAL  Failed store conditional instructions               
1719PAPI_CSR_SUC  Successful store conditional instructions           
1720PAPI_CSR_TOT  Total store conditional instructions               
1721
1722PAPI_MEM_SCY  Cycles Stalled Waiting for memory accesses         
1723PAPI_MEM_RCY  Cycles Stalled Waiting for memory Reads             
1724PAPI_MEM_WCY  Cycles Stalled Waiting for memory writes           
1725
1726PAPI_STL_ICY  Cycles with no instruction issue                   
1727PAPI_FUL_ICY  Cycles with maximum instruction issue               
1728PAPI_STL_CCY  Cycles with no instructions completed               
1729PAPI_FUL_CCY  Cycles with maximum instructions completed         
1730
1731PAPI_BR_UCN   Unconditional branch instructions                   
1732PAPI_BR_CN    Conditional branch instructions                     
1733PAPI_BR_TKN   Conditional branch instructions taken               
1734PAPI_BR_NTK   Conditional branch instructions not taken           
1735PAPI_BR_MSP   Conditional branch instructions mispredicted       
1736PAPI_BR_PRC   Conditional branch instructions correctly predicted
1737
1738PAPI_FMA_INS  FMA instructions completed                         
1739PAPI_TOT_IIS  Instructions issued                                 
1740PAPI_TOT_INS  Instructions completed                             
1741PAPI_INT_INS  Integer instructions                               
1742PAPI_FP_INS   Floating point instructions                         
1743PAPI_LD_INS   Load instructions                                   
1744PAPI_SR_INS   Store instructions                                 
1745PAPI_BR_INS   Branch instructions                                 
1746PAPI_VEC_INS  Vector/SIMD instructions                           
1747PAPI_LST_INS  Load/store instructions completed                   
1748PAPI_SYC_INS  Synchronization instructions completed             
1749PAPI_FML_INS  Floating point multiply instructions               
1750PAPI_FAD_INS  Floating point add instructions                     
1751PAPI_FDV_INS  Floating point divide instructions                 
1752PAPI_FSQ_INS  Floating point square root instructions             
1753PAPI_FNV_INS  Floating point inverse instructions                 
1754
1755PAPI_RES_STL  Cycles stalled on any resource   
1756PAPI_FP_STAL  Cycles the FP unit(s) are stalled
1757
1758PAPI_FP_OPS   Floating point operations         
1759PAPI_TOT_CYC  Total cycles                     
1760PAPI_HW_INT   Hardware interrupts
1761</PRE> 
1762
1763<P>
1764
1765<H1><A NAME="SECTION00900000000000000000">&#160;</A>
1766<A NAME="install">&#160;</A>
1767<BR>
1768VampirTrace Installation
1769</H1>
1770
1771<P>
1772
1773<H1><A NAME="SECTION00910000000000000000">
1774Basics</A>
1775</H1>
1776
1777<P>
1778Building VampirTrace is typically a combination of running <TT>configure</TT>
1779    and
1780<BR><TT>make</TT>.  Execute the following commands to install VampirTrace from
1781    within the directory at the top of the tree:
1782
1783<P>
1784<PRE>
1785% ./configure --prefix=/where/to/install
1786[...lots of output...]
1787% make all install
1788</PRE> 
1789
1790<P>
1791If you need special access for installing, then you can execute
1792    <TT>make all</TT> as a user with write permissions in the build tree, and a
1793    separate <TT>make install</TT> as a user with write permissions to the
1794    install tree.
1795
1796<P>
1797However, for more details, also read the following instructions. Sometimes
1798    it might be necessary to provide <TT>./configure</TT> with options, e.g.
1799    specifications of paths or compilers. Please consult the CONFIG-EXAMPLES file to
1800    get an idea of how to configure VampirTrace for your platform.
1801
1802<P>
1803VampirTrace comes with example programs written in C, C++, and Fortran.
1804    They can be used to test different instrumentation types of the
1805    VampirTrace installation.
1806    You can find them in the directory <TT>examples</TT> of the VampirTrace package.
1807
1808<P>
1809
1810<H1><A NAME="SECTION00920000000000000000">
1811Configure Options</A>
1812</H1>
1813
1814<P>
1815
1816<H2><A NAME="SECTION00921000000000000000">
1817Compilers and Options</A>
1818</H2>
1819
1820<P>
1821Some systems require unusual options for compiling or linking that
1822      the
1823<BR><TT>configure</TT> script does not know about.  Run <TT>./configure -help</TT>
1824      for details on some of the pertinent environment variables.
1825
1826<P>
1827You can pass initial values for configuration parameters to <TT>configure</TT>
1828      by setting variables in the command line or in the environment.  Here
1829      is an example:
1830
1831<P>
1832<PRE>
1833% ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
1834</PRE> 
1835
1836<P>
1837
1838<H2><A NAME="SECTION00922000000000000000">
1839Installation Names</A>
1840</H2>
1841
1842<P>
1843By default, <TT>make install</TT> will install the package's files in
1844      <TT>/usr/local/bin</TT>, <TT>/usr/local/include</TT>, etc.  You can specify an
1845      installation prefix other than <TT>/usr/local</TT> by giving <TT>configure</TT> the
1846      option <TT>-prefix=PATH</TT>.
1847
1848<P>
1849
1850<H2><A NAME="SECTION00923000000000000000">
1851Optional Features</A>
1852</H2>
1853
1854<P>
1855<DL>
1856<DT><STRONG><TT>-enable-compinst=COMPINSTLIST</TT></STRONG></DT>
1857<DD>&nbsp;
1858<BR>
1859enable support for compiler instrumentation,
1860<BR>
1861e.g. (<TT>gnu,intel,pgi,phat,xl,ftrace</TT>),
1862<BR>
1863A VampirTrace installation can handle different compilers.
1864<BR>
1865The first item in the list is the run-time default.
1866<BR>
1867default: automatically by configure
1868
1869<P>
1870</DD>
1871<DT><STRONG><TT>-enable-mpi</TT></STRONG></DT>
1872<DD>&nbsp;
1873<BR>
1874enable MPI support, default: enable if
1875                              Open MPI found by configure
1876
1877<P>
1878</DD>
1879<DT><STRONG><TT>-enable-omp</TT></STRONG></DT>
1880<DD>&nbsp;
1881<BR>
1882enable OpenMP support, default: enable if
1883                              compiler supports OpenMP
1884
1885<P>
1886</DD>
1887<DT><STRONG><TT>-enable-hyb</TT></STRONG></DT>
1888<DD>&nbsp;
1889<BR>
1890enable Hybrid (MPI/OpenMP) support, default:
1891                              enable if MPI found and compiler supports OpenMP
1892
1893<P>
1894</DD>
1895<DT><STRONG><TT>-enable-memtrace</TT></STRONG></DT>
1896<DD>&nbsp;
1897<BR>
1898enable memory tracing support, default: enable if
1899                              found by configure
1900
1901<P>
1902</DD>
1903<DT><STRONG><TT>-enable-iotrace</TT></STRONG></DT>
1904<DD>&nbsp;
1905<BR>
1906enable libc's I/O tracing support, default: enable
1907                              if libdl found by configure
1908
1909<P>
1910</DD>
1911<DT><STRONG><TT>-enable-dyninst</TT></STRONG></DT>
1912<DD>&nbsp;
1913<BR>
1914enable support for Dyninst instrumentation,
1915<BR>
1916default: enable if found by configure
1917<BR>                              <SPAN  CLASS="textbf">Note:</SPAN> Requires Dyninst version 5.0.1 or higher!
1918<BR>                              (<TT><A NAME="tex2html9"
1919  HREF="http://www.dyninst.org">http://www.dyninst.org</A></TT>)
1920
1921<P>
1922</DD>
1923<DT><STRONG><TT>-enable-dyninst-attlib</TT></STRONG></DT>
1924<DD>&nbsp;
1925<BR>
1926build shared library which attaches dyninst to
1927                              the running application,
1928<BR>
1929default: enable if dyninst found
1930                              by configure and system supports shared libraries
1931
1932<P>
1933</DD>
1934<DT><STRONG><TT>-enable-papi</TT></STRONG></DT>
1935<DD>&nbsp;
1936<BR>
1937enable PAPI hardware counter support,
1938<BR>
1939default: enable if found by configure
1940</DD>
1941</DL>
1942
1943<P>
1944
1945<H2><A NAME="SECTION00924000000000000000">
1946Important Optional Packages</A>
1947</H2>
1948
1949<P>
1950<DL>
1951<DT><STRONG><TT>-with-local-tmp-dir=LTMPDIR</TT></STRONG></DT>
1952<DD>&nbsp;
1953<BR>
1954give the path for node-local temporary directory
1955                              to store local traces to, default: <TT>/tmp/</TT>
1956</DD>
1957</DL>
1958
1959<P>
1960If you would like to use an external version of OTF library, set:
1961<DL>
1962<DT><STRONG><TT>-with-extern-otf</TT></STRONG></DT>
1963<DD>&nbsp;
1964<BR>
1965use external OTF library, default: not set
1966</DD>
1967<DT><STRONG><TT>-with-extern-otf-dir=OTFDIR</TT></STRONG></DT>
1968<DD>&nbsp;
1969<BR>
1970give the path for OTF, default: <TT>/usr/local/</TT>
1971
1972<P>
1973</DD>
1974<DT><STRONG><TT>-with-otf-flags=FLAGS</TT></STRONG></DT>
1975<DD>&nbsp;
1976<BR>
1977pass FLAGS to the OTF distribution configuration
1978       (only for internal OTF version)
1979
1980<P>
1981</DD>
1982<DT><STRONG><TT>-with-otf-lib=OTFLIB</TT></STRONG></DT>
1983<DD>&nbsp;
1984<BR>
1985use given otf lib, default: <TT>-lotf -lz</TT>
1986
1987<P>
1988</DD>
1989</DL>
1990
1991<P>
1992If used OTF library was built without zlib support, then OTFLIB will
1993be set to <TT>-lotf</TT>.
1994
1995<P>
1996<DL>
1997<DT><STRONG><TT>-with-dyninst-dir=DYNIDIR</TT></STRONG></DT>
1998<DD>&nbsp;
1999<BR>
2000give the path for DYNINST, default: <TT>/usr/local/</TT>
2001
2002<P>
2003</DD>
2004<DT><STRONG><TT>-with-papi-dir=PAPIDIR</TT></STRONG></DT>
2005<DD>&nbsp;
2006<BR>
2007give the path for PAPI, default: <TT>/usr/</TT>
2008</DD>
2009</DL>
2010
2011<P>
2012If you have not specified the environment variable <TT>MPICC</TT>
2013(MPI compiler command), use the following options to set the location
2014of your MPI installation:
2015
2016<P>
2017<DL>
2018<DT><STRONG><TT>-with-mpi-dir=MPIDIR</TT></STRONG></DT>
2019<DD>&nbsp;
2020<BR>
2021give the path for MPI, default: <TT>/usr/</TT>
2022
2023<P>
2024</DD>
2025<DT><STRONG><TT>-with-mpi-inc-dir=MPIINCDIR</TT></STRONG></DT>
2026<DD>&nbsp;
2027<BR>
2028give the path for MPI include files,
2029<BR>
2030default: <TT>$MPIDIR/include/</TT>
2031
2032<P>
2033</DD>
2034<DT><STRONG><TT>-with-mpi-lib-dir=MPILIBDIR</TT></STRONG></DT>
2035<DD>&nbsp;
2036<BR>
2037give the path for MPI-libraries, default: <TT>$MPIDIR/lib/</TT>
2038
2039<P>
2040</DD>
2041<DT><STRONG><TT>-with-mpi-lib=MPILIB</TT></STRONG></DT>
2042<DD>&nbsp;
2043<BR>
2044use given mpi lib
2045
2046<P>
2047</DD>
2048<DT><STRONG><TT>-with-pmpi-lib=PMPILIB</TT></STRONG></DT>
2049<DD>&nbsp;
2050<BR>
2051use given pmpi lib, default: MPILIB
2052</DD>
2053</DL>
2054
2055<P>
2056
2057<H1><A NAME="SECTION00930000000000000000">
2058Cross Compilation</A>
2059</H1>
2060
2061<P>
2062Building VampirTrace on cross compilation platforms needs some special attention.
2063The compiler wrappers and OPARI are built for the front-end (build system) whereas
2064the VampirTrace libraries, vtdyn, vtunify, and vtfilter are built for the back-end
2065(host system). Some <TT>configure</TT> options which are of interest for cross compilation
2066are shown below:
2067
2068<UL>
2069<LI>Set <TT>CC</TT>, <TT>CXX</TT>, <TT>F77</TT>, and <TT>FC</TT> to the cross compilers installed on the front-end.
2070</LI>
2071<LI>Set <TT>CXX_FOR_BUILD</TT> to the native compiler of the front-end (used to compile compiler wrappers and OPARI only).
2072</LI>
2073<LI>Set <TT>-host=</TT> to the output of <TT>config.guess</TT> on the back-end.
2074</LI>
2075<LI>Maybe you also need to set additional commands and flags for the back-end (e.g. <TT>RANLIB</TT>, <TT>AR</TT>, <TT>MPICC</TT>, <TT>CXXFLAGS</TT>).
2076</LI>
2077</UL>
2078For example, this <TT>configure</TT> command line works for an NEC SX6 system with an X86_64 based front-end:
2079
2080<P>
2081<PRE>
2082% ./configure CC=sxcc CXX=sxc++ F77=sxf90 FC=sxf90
2083              AR=sxar RANLIB="sxar st" CXX_FOR_BUILD=c++
2084              --host=sx6-nec-superux14.1
2085              --with-otf-lib=-lotf
2086</PRE> 
2087
2088<P>
2089
2090<H1><A NAME="SECTION00940000000000000000">
2091Environment Set-Up</A>
2092</H1>
2093
2094<P>
2095Add the <TT>bin</TT> subdirectory of the installation directory to your
2096    <TT>$PATH</TT> environment variable. To use VampirTrace with Dyninst,
2097    you will also need to add the lib subdirectory to your
2098    <TT>LD_LIBRARY_PATH</TT> environment variable:
2099<BR>
2100<BR>
2101<BR>
2102for csh and tcsh:
2103<PRE>
2104&gt; setenv PATH &lt;vt-install&gt;/bin:$PATH
2105&gt; setenv LD_LIBRARY_PATH &lt;vt-install&gt;/lib:$LD_LIBRARY_PATH
2106</PRE> 
2107    for bash and sh:
2108<PRE>
2109% export PATH=&lt;vt-install&gt;/bin:$PATH
2110% export LD_LIBRARY_PATH=&lt;vt-install&gt;/lib:$LD_LIBRARY_PATH
2111</PRE> 
2112
2113<P>
2114
2115<H1><A NAME="SECTION00950000000000000000">
2116Notes for Developers</A>
2117</H1>
2118
2119<P>
2120
2121<H2><A NAME="SECTION00951000000000000000">
2122Build from CVS</A>
2123</H2>
2124
2125<P>
2126If you have checked out a <SPAN  CLASS="textit">developer's copy</SPAN> of VampirTrace (i.e.
2127      checked out from CVS), you should first run:
2128
2129<P>
2130<PRE>
2131% ./bootstrap
2132</PRE>
2133Note that GNU Autoconf &ge;2.60 and GNU Automake &ge;1.9.6 is required.
2134You can download them from <TT><A NAME="tex2html10"
2135  HREF="http://www.gnu.org/software/autoconf">http://www.gnu.org/software/autoconf</A></TT> 
2136and <TT><A NAME="tex2html11"
2137  HREF="http://www.gnu.org/software/automake">http://www.gnu.org/software/automake</A></TT>.
2138
2139<P>
2140
2141<H2><A NAME="SECTION00952000000000000000">
2142Creating a distribution tarball (VampirTrace-X.X.X.tar.gz)</A>
2143</H2>
2144
2145<P>
2146If you would like to create a new distribution tarball, run:
2147
2148<P>
2149<PRE>
2150% ./makedist -o &lt;otftarball&gt; &lt;major&gt; &lt;minor&gt; &lt;release&gt;
2151</PRE>
2152      instead of <TT>make dist</TT>.
2153      The script <TT>makedist</TT> adapts the version number <TT>&lt;major&gt;.&lt;minor&gt;.&lt;release&gt;</TT> in
2154      <TT>configure.in</TT> and extracts given OTF-tarball <TT>&lt;otftarball&gt;</TT> in
2155      <TT>./extlib/otf/</TT>.
2156
2157<P>
2158<BR><HR>
2159
2160</BODY>
2161</HTML>
Note: See TracBrowser for help on using the repository browser.