#! /bin/sh
#
# Copyright 2003-2021 Intel Corporation.
#
# This software and the related documents are Intel copyrighted materials, and your use of
# them is governed by the express license under which they were provided to you (License).
# Unless the License provides otherwise, you may not use, modify, copy, publish, distribute,
# disclose or transmit this software or the related documents without Intel's prior written
# permission.
#
# This software and the related documents are provided as is, with no express or implied
# warranties, other than those that are expressly stated in the License.
#
# /**
#
# \page xstftool Expanded ASCII output of STF files
#
# \section synopsis Synopsis
#
# xstftool <STF file> [stftool options]
#
# Valid options are those that work together with
# "stftool --dump", the most important ones being:
# - --request: extract a subset of the data
# - --matched-vtf: put information about complex events
#                  like messages and collective operations
#                  into one line
#
# \section description Description 
#
# The xstftool is a simple wrapper around the stftool
# and the expandvtlog.pl Perl script which tells
# the stftool to dump a given Structured Trace Format
# (STF) file in ASCII format and uses the script as a
# filter to make the output more readable.
#
# It is intended to be used for doing custom analysis
# of trace data with scripts that parse the output
# to extract information not provided by the existing
# tools, or for situations where a few shell commands
# provide the desired information more quickly than
# a graphical analysis tool.
#
# \section output Output
#
# The output has the format of the ASCII Vampir Trace Format (VTF),
# but entities like function names are not represented by integer
# numbers that cannot be understood without remembering their
# definitions, but rather inserted into each record. The CPU
# numbers that encode process and thread ranks resp. groups are
# also expanded.
#
# \section examples Examples
#
# The following examples compare the output of "stftool --dump"
# with the expanded output of "xstftool":
#
# - definition of a group
#   \verbatim
#   DEFGROUP 2147942402 "All_Processes" NMEMBS 2 2147483649 2147483650
#   DEFGROUP All_Processes NMEMBS 2 "Process_0" "Process_2"
#   \endverbatim
# - a counter sample on thread 2 of the first process 
#   \verbatim
#   8629175798 SAMP CPU 131074 DEF 6 UINT 8 3897889661
#   8629175798 SAMP CPU 2:1 DEF "PERF_DATA:PAPI_TOT_INS" UINT 8 3897889661
#   \endverbatim
#
# */
#


absolutize_path() # <file> <parentDir>
{
    firstChar=`echo "$1" | cut -c1`
    if [ "$firstChar" = "/" ]; then
        echo "$1"
    else
        echo "$2/$1"
    fi
}


follow_link() # <file>
{
    file="$1"
    parentDir=`dirname "$file"`
    if [ ! -h "$file" ]; then
        echo "$file"
    else
        link=`ls -l "$file" | sed -e "s/.*->[ ]*//"`
        link=`absolutize_path "$link" "$parentDir"`
        follow_link "$link"
    fi
}


FILE="$1"
shift

if [ "$VT_ROOT" = "" ]; then
    VT_ROOT=`follow_link "$0"`
    VT_ROOT=`dirname "$VT_ROOT"`/..
    VT_ROOT=`( cd "$VT_ROOT"; pwd )` # guarantees an absolute path name
fi

"$VT_ROOT/bin/stftool" "$FILE" --extended-vtf --dump "$@" | $VT_ROOT/bin/expandvtlog.pl
