Merge branch 'master' of git.nic.uoregon.edu:/gitroot/tau2

README.sampling

@@ -1,71 +1,114 @@
 ************************************************************************
-** TAU EBS Sampling
+*****                       TAU EBS Sampling                       *****
 ************************************************************************
 
+***********************
+*** DATA GENERATION ***
+***********************
 TAU has a prototype sampling infrastructure.  It can be used to generated
 sampling based traces from the TAU measurement library.  These traces can be
 processed and read into ParaProf to augment profile data collected via standard
-measurement probes.
+measurement probes or viewed as traces in OTF format.
 
-To use:
+** Typical use:
 
 1) Enabled sampling by setting the environment variable TAU_SAMPLING=1.
 
-2) Set a sample source and frequency (default: itimer, 1000 samples per second)
-with TAU_EBS_SOURCE.  When choosing a PAPI metric, the frequency variable is
-used as the overflow sample point.  E.g.
+2) Set a sample source and sampling period (default: "itimer", 
+1,000 microseconds between samples) with TAU_EBS_SOURCE and TAU_EBS_PERIOD.  
+When choosing a PAPI metric, the period variable is used as the overflow 
+sample point.  E.g.
 
    export TAU_EBS_SOURCE=PAPI_TOT_CYC
-   export TAU_EBS_FREQUENCY=3000000
+   export TAU_EBS_PERIOD=3000000
 
-will sample about every 1000 ms on a 3.0Ghz CPU.
+will sample about every 1000 ms on a 3.0Ghz CPU as PAPI will trigger an
+overflow event every 3,000,000 CPU cycles.
 
-3) Sampled traces are output in the current working directory, three for each thread:
+** TAU EBS Sampling through tau_exec:
+
+On machines that support dynamic shared libraries, we offer support
+for sampling through the tau_exec mechanism. Please refer to
+documentation on tau_exec for more details:
+
+Eg. mpirun -n 8 tau_exec -ebs -ebs_source=PAPI_TOT_CYC 
+	-ebs_period=3000000 <exe> <exe options>
+
+**************
+*** OUTPUT ***
+**************
+Sampled traces are output in the current working directory, up to three 
+for each thread. Raw and definition files are written on all platforms:
 
-   ebstrace.raw.<pid>.<nid><cid><tid>
-   ebstrace.map.<pid>.<nid><cid><tid>
-   ebstrace.def.<pid>.<nid><cid><tid>
+   ebstrace.raw.<pid>.<nid>.<cid>.<tid>
+   ebstrace.def.<pid>.<nid>.<cid>.<tid>
 
-4) Process the traces with tau2/tools/src/tausamp_process2.pl to generate processed traces for paraprof
+   Map files are written only on supported platforms. For platforms like 
+   the Bluegene/P which does not support the generation of map files, EBS 
+   sampling has to be performed on single static execution binaries:
 
-5) View in paraprof
+   ebstrace.map.<pid>.<nid>.<cid>.<tid>
 
-************************************************************************
+***********************
+*** POST-PROCESSING *** 
+***********************
 
-More advanced usage:
+*** Enhanced ParaProf Profiles ***
 
-************************************************************************
-*** Converting to OTF
-************************************************************************
+1) Process the traces with tau2/<arch>/bin/tau_ebs_process.pl to generate 
+processed traces for paraprof. Some platforms will require the environment 
+variable TAU_EBS_EXE to be set to the full path of the executable. These
+include:
 
-1) Build ebs2otf shared library
+   a. Bluegene/P - no map file support.
+   b. Cray XT5 - executable path at runtime is different from 
+        real executable path and is transient.
 
-   cd tau2/utils/ebs2otf
-   cp </path/to/otf>/include/*.h .
-   ./reswig.sh
-
-2) Generate EBS traces as above
+   The processed trace files are of the form:
+
+   ebstrace.processed.<pid>.<nid>.<cid>.<tid>
+
+2) View in paraprof. ParaProf will read the processed trace files above 
+along with the standard profile.<pid>.<nid>.<cid>.<tid> files to present
+visualization of the combined information.
+
+*** Converting to OTF (Open Trace Format) for third party tools like Vampir ***
+
+1) Please make sure the version of TAU was built with ebs2otf support. 
+As of this release, we support only OTF 1.8 (sturgeon):
 
-3) Set PERL5LIB and LD_LIBRARY_PATH:
+   ./configure -ebs2otf -otfinc=<dir> -otflib=<dir> [other options]
+
+   It is also possible to use the -otf=<dir> option. However that option
+has the side-effect of turning on TAU tracing as a default. EBS traces
+currently work only with TAU profiles.
+
+2) Generate EBS traces as above.
+
+3) Make sure the environment variables PERL5LIB and LD_LIBRARY_PATH are
+   correctly set:
 
-   export PERL5LIB=$HOME/tau2/utils/ebs2otf
-   export LD_LIBRARY_PATH=/usr/local/packages/otf-1.6.4/lib:$LD_LIBRARY_PATH
+   export PERL5LIB=$TAUROOT/tau2/<arch>/lib
+   export LD_LIBRARY_PATH=<OTF installed library>:$LD_LIBRARY_PATH
 
 4) Run converter:
 
-   $HOME/tau2/utils/ebs2otf/tausamp_process_otf.pl
+   $HOME/tau2/<arch>/bin/tau_ebs2otf.pl
 
 5) View in vampir: 
 
    vampir ebstrace.otf
 
-************************************************************************
-*** Collecting EBS callstack traces
-************************************************************************
+***********************
+*** Advanced Topics ***
+***********************
+
+*** Collecting EBS callstack traces ***
 
 To collect EBS callstack traces, you must download and build HPCToolkit
 (http://hpctoolkit.org) 4.9.2, r2138 for which we supply a patch to enable TAU
-integration.
+integration. This feature is currently beta and will be more fully 
+supported in later versions.
 
 1) Download, patch and build HPCToolkit 4.9.2 r2138
 
@@ -95,7 +138,3 @@ integration.
 
    hpcrun -e PAPI_TOT_CYC@100000 ./simple
 
-
-
-
-

configure

@@ -100,6 +100,9 @@ for arg in "$@"; do
     echo "-jdk=<dir>  Build a library for profiling Java code with specified jdk."
     echo "-vtf=<dir> ......... Specify location of VTF3 Trace Generation Package."
     echo "-otf=<dir> ....... Specify location of Open Trace Format (OTF) Package."
+    echo "-otfinc=<dir> ....... Specify location of stand-alone OTF header files."
+    echo "-otflib=<dir> ...... Specify location of stand-alone OTF library files."
+    echo "-ebs2otf ............... Enable conversion of EBS traces to OTF format."
     echo "-nocomm  ........ Disable tracking communication events in MPI library."
     echo "-hpctoolkit-src-dir=<dir> .......... Specify patched HPCToolkit source."
     echo "-hpctoolkit-install-dir=<dir> . Specify patched HPCToolkit Install dir."
@@ -193,6 +196,9 @@ for arg in "$@"; do
     echo "-bfd=<dir | download> ............ Specify a BFD directory or download."
     echo "-vtf=<dir> ......... Specify location of VTF3 Trace Generation Package."
     echo "-otf=<dir> ....... Specify location of Open Trace Format (OTF) Package."
+    echo "-otfinc=<dir> ....... Specify location of stand-alone OTF header files."
+    echo "-otflib=<dir> ...... Specify location of stand-alone OTF library files."
+    echo "-ebs2otf ............... Enable conversion of EBS traces to OTF format."
     echo "-mpi .......................... Specify use of TAU MPI wrapper library."
     echo "-mpiinc=<dir> ............. Specify location of MPI include dir and use"
     echo "                           the TAU MPI Profiling and Tracing Interface."
@@ -425,6 +431,10 @@ pdt=no
 armci=no
 vtf=no
 otf=no
+otfdir=
+otfinc=
+otflib=
+ebs2otf=no
 opari=no
 epilog=no
 hpctoolkit=no
@@ -955,6 +965,31 @@ for arg in "$@"; do
     shift
     ;;
 
+  -otfinc=*)
+      otfinc=`echo $arg | sed -e 's/-otfinc=//'`
+      if [ ! -d $otfinc ]
+      then
+        echo "Error: Cannot access OTF include directory $otfinc"
+        exit 1
+      fi
+      shift
+      ;;
+
+  -otflib=*)
+      otflib=`echo $arg | sed -e 's/-otflib=//'`
+      if [ ! -d $otflib ]
+      then
+        echo "Error: Cannot access OTF library directory $otflib"
+        exit 1
+      fi
+      shift
+      ;;
+
+  -ebs2otf)
+      ebs2otf=yes
+      shift
+      ;;
+
   -dyninst=*)
       dyninst=yes
       dyninstdir=`echo $arg | sed -e 's/-dyninst=//'`
@@ -1567,8 +1602,9 @@ cp ${tauroot}/tools/src/contrib/postgresql.jar $JARTARGET
 cp ${tauroot}/tools/src/contrib/xerces.jar $JARTARGET
 cp ${tauroot}/tools/src/common/resources/tau16x16.gif $JARTARGET
 
-# install the perl script for ebs post-processing in the bin dir
+# install the perl scripts for ebs post-processing in the bin dir
 cp ${tauroot}/tools/src/tau_ebs_process.pl $BINTARGET
+cp ${tauroot}/utils/ebs2otf/tau_ebs2otf.pl $BINTARGET
 
 case $machine in
 
@@ -5217,6 +5253,41 @@ if [ $otf = yes ] ; then
   fi  
 fi
 
+if [ $ebs2otf = yes ] ; then
+  if [ -f utils/ebs2otf/ebs2otf.so ] ; then
+      touch utils/ebs2otf/ebs2otf.so
+  fi
+  if [ $otf = yes ] ; then
+      echo "Warning: -otf option enables TAU Tracing as a default. EBS will only work with TAU profiles. Please make sure Profiles are enabled before use."
+      if [ "$otflib" = "" ] ; then
+	  otflib="$otfdir/${architecture}/lib"
+	  echo "OTF Library implicitly set to $otflib"
+      fi
+      if [ "$otfinc" = "" ] ; then
+	  otfinc="$otfdir/include"
+	  echo "OTF Header directory implicitly set to $otfinc"
+      fi
+  fi 
+  if [ ! -d $otflib ]
+      then
+      echo "Error: No available OTF support. Library not found at $otflib."
+      exit 1
+  fi
+  if [ ! -d $otfinc ]
+      then
+      echo "Error: No available OTF support. Headers not found at $otfinc."
+      exit 1
+  fi
+  if [ ! -f $otfinc/OTF_Version.h ] ; then
+      echo "Error: OTF_Version.h cannot be found. EBS will not support this version of OTF."
+      exit 1
+      # *CWL* Need version control code here. Still trying to decide the
+      #    best way about it. The above conditional will at least trim away
+      #    ancient versions of OTF.
+  fi
+
+  fixmakeargs="$fixmakeargs EBS2OTF otflib=$otflib otfinc=$otfinc"
+fi
 
 if [ $pdt_cxx_compiler != default ] ; then
 # Check if they specified -pdt_c++=/usr/bin/g++ instead of just g++ 

src/Profile/TauMetaData.cpp

@@ -267,7 +267,7 @@ int Tau_metadata_fillMetaData() {
   if (Kernel_ProcessCount() > 1) {
     Tau_metadata_register("BGP Node Mode", "Virtual");
   } else {
-    sprintf(bgpbuffer, "Coprocessor (%d)", Kernel_ProcessCount);
+    sprintf(bgpbuffer, "Coprocessor (%d)", Kernel_ProcessCount());
     Tau_metadata_register("BGP Node Mode", bgpbuffer);
   }