/****************************************************************************
 * Copyright (c) 2005, 2008 Intel Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * $Id$
 ****************************************************************************/

Contributors:
Guru Nagarajan, Intel
    (JVMTI Agent)
Viacheslav G. Rybalov, Intel
    (JVMTI Agent, Agent Controller Integration and Data Collectors)
Ruslan Scherbakov, Intel
    (JVMTI Client, Launch Configuration and Analysis Views)
Vitaly Provodin, Intel
    (JVMTI Client, Launch Configuration and Analysis Views)
Asaf Yaffe, Intel
    (Martini SDK)
Alexander Alexeev, Intel
Stanislav V. Polevic, Intel
Vasily Levchenko, Intel

JVMTI Profiler in TPTP 4.5

1. Introduction
---------------
This package contains the JVMTI-based Data Collector for TPTP.
It includes call-graph, heap and thread data collectors built on top of a 
simplified interface for developing Java agents for JVMs that implement the Java 
Virtual Machine Tools Interface (JVMTI).
This file describes the dependencies, environments, and procedures necessary to 
compile and test the JVMTI Agent and SDK libraries on Windows and Linux 
platforms.

2. Installing the Package
-------------------------
The package is included with the New Technology Agent Controller installation.
The java Profiler runtime is contained in the 
(<AC_HOME>\plugins\org.eclipse.tptp.javaprofiler) directory.

3. Running the JVMTI Agent
--------------------------
* Running from the command line (Standalone Mode)
The Java Profiler can be used as a standalone application to collect 
profiling data info a file. The data emitted by the Profiler complies with the 
XML4Profiling Java Trace Model Specification. The output file can be imported to 
the Eclipse workbench using the import profiling file option available in TPTP.

The Java Profiler can be launched from the command line by typing the following
command at the prompt:

java -agentlib:JPIBootLoader=JPIAgent[:help|<global options>];
     <profiler>[:<profiler options>] <Java Class>

Where:
  help ? displays a brief usage message. For example,
  java -agentlib:JPIBootLoader=JPIAgent:help;CGProf

  <options> - comma-separated command line options, provided as name-value pairs.
              Both global and profiler-specific options are supported. 
   
  Supported global options:
    server=standalone|enabled|controlled ? specifies the profiler’s operation mode. 
                                           Refer to the online documentation
                                           for a detailed description of these
                                           operation modes.
    file=<file> - specifies the trace data output file name. If this option is 
                  omitted, the output will be written to a file named 
                  trace.trcxml in the current directory. Only applicable when 
                  server=standalone.
    filters=<file> - specifies the filters definition file. If this option is 
                     omitted, the profiler will look for filter definitions in 
                     a file named filters.txt in the current directory 
                     (if such file exists). 
                     Only applicable when server=standalone. 
    profiler=<file> - specifies the profiling options file. If this option is 
                      omitted, the profiler will look for profiling options in 
                      a file named jvmti.pro in the current directory 
                      (if such file exists). 
                      Only applicable when server=standalone.
    api=true|false - Whether to enable the Profiler API or not. Default is false.
                     The Profiler API feature is fully supported by the 
                     Heap and Thread profilers. The feature is partially 
                     supported by the Execution Time profiler (CGProf). See the
                     CGProf section below for more information.
    stackmap=true|false - Whether to recalculate the StackMapTable attribute of
                          instrumented methods. 
                          Use only when experiencing verification errors in 
						  Java 1.6+. Default is false.
    format=binary|xml - Output trace format. Default is xml.
    
  <profiler> - the profiler to launch:
    CGProf ? execution time analysis
    Supported options:
      execdetails=true|false - whether to collect execution flow information 
                               (true) or only method execution statistics (false).
                               Default is false
      * NOTES: 
      (1) The "execdetails=true" option is currently not supported when 
          running the profiler in "enabled" mode. To obtain execution flow 
          information for an application started from the command line, 
          use "controlled" mode with execdetails=true.
      (2) CGProf supports the Profiler API feature only when the 
          "execdetails=true" option is used. CGProf will ignore Profiler APIs 
          when "execdetails=false". Note that this also implies that 
          Profiler API is not supported when running CGProf in "enabled" mode 
          (as this mode implies using execdetails=false).
                               
    HeapProf ? memory analysis
    Supported options:
      allocsites=true|false - whether to collect information on the location
                              (method and line number) where objects were
                              allocated (true) or not (false).
                              Default it false
                              
    ThreadProf ? thread analysis
    Supported options:
      contanalysis=true|false - whether to collect lock usage information
                                for thread contention analysis.
      maxstackdepth=<number of frames> - limit the size of the stack trace
                                         reported by the profiler.

  <Java Class> - the Java class to execute


To run the Java Profiler according to whether environmental variable PATH(Windows)/
LD_LIBRARY_PATH(Linux) is available on your system:
(1) Avaliable
  (1.1) In standalone mode
   a) Add profilers path info into environmental variable:
     (Windows)Set PATH=<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler;%PATH%
     (Linux)export LD_LIBRARY_PATH=<<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler:$LD_LIBRARY_PATH
   b) Execute any of the following commands:
   On Windows:
   CPU Profiling (call-graph):
   java -agentlib:JPIBootLoader=JPIAgent:server=standalone;CGProf <<Your
   Application to profile>>

   Heap Profiling:
   java -agentlib:JPIBootLoader=JPIAgent:server=standalone;HeapProf <<Your
   Application to profile>>

   Thread Profiling:
   java -agentlib:JPIBootLoader=JPIAgent:server=standalone;ThreadProf <<Your
   Application to profile>>

   On Linux:
   CPU Profiling (call-graph):
   java '-agentlib:JPIBootLoader=JPIAgent:server=standalone;CGProf' <<Your
   Application to profile>>

  (1.2) In enabled or controlled mode
   a) Add profilers path and agent controller library info into environmental variable:
     (Windows)Set PATH=<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler;<<Agent Controller Home>>\bin;%PATH%
     (Linux)export LD_LIBRARY_PATH=<<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler:<<Agent Controller Home>>/lib:$LD_LIBRARY_PATH
   b) Execute any of the commands as in (1.1) just replace 'server=standalone' with 'server=enabled' or 'server=controlled'.
   
 

(2) Not avaliable
   Because profilers you use are agent controller contains, you should use -agentpath and environmental variable setting is not needed.

   On Windows:
   CPU Profiling (call-graph):
   java -agentpath:<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler\JPIBootLoader=JPIAgent:server=standalone;CGProf <<Your
   Application to profile>>

   Heap Profiling:
   java -agentlib:<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler\JPIBootLoader=JPIAgent:server=standalone;HeapProf <<Your
   Application to profile>>

   Thread Profiling:
   java -agentlib:<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler\JPIBootLoader=JPIAgent:server=standalone;ThreadProf <<Your
   Application to profile>>

   On Linux:
   CPU Profiling (call-graph):
   java '-agentpath:<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler\libJPIBootLoader.so=JPIAgent:server=standalone;CGProf' <<Your
   Application to profile>>

 

In all of the examples above, the profiling output will be written to a file 
named trace.trcxml in the current directory.

NOTE: On Linux, make sure to surround the entire –agentlib argument with single 
quotes (as shown above). Otherwise, the Linux shell may interpret the ; 
preceding CGProf as a command terminator and the Java application will not be 
executed.

* Running from the command line, to be discovered by the Eclipse Workbench 
(Enabled or Controlled modes)

Repeat the steps for running the Profiler in standalone mode and change the 
command line as shown below:

java -agentlib:JPIBootLoader=JPIAgent:server=enabled;CGProf <<Your 
Application to profile>>

or 

java -agentlib:JPIBootLoader=JPIAgent:server=controlled;CGProf <<Your 
Application to profile>>

* Running from the Workbench (Controlled Mode)
This mode is used by the Eclipse Client to launch an Application under the 
profiler.
java.exe -agentlib:JPIBootLoader=JPIAgent:server=controlled;CGProf <<Your 
Application to profile>>

4. Available Packages
---------------------
The Runtime package is available in TPTP 4.4. The SDK package can be built using 
the build scripts. 

5. Building the JVMTI Agent and its Components from Source
----------------------------------------------------------
The JVMTI Agent code is located in the
dev.eclipse.org/cvsroot/tptp/platform/org.eclipse.tptp.platform.jvmti.runtime 
TPTP CVS module.

The src-native directory contains the top level make files which will build all 
of the component parts. The build directory contains make files and scripts for 
specific components:

tptp_profiler.dsw
    Windows workspace file for the JVMTI Agent and the Call-graph Profiler.
tptp_martini.dsw
    Windows workspace file for the Martini SDK libraries. Specifying the
    BuildMartini32 project results in a complete build of all Martini libraries.
build_tptp_profiler.bat
    Windows build script for the JVMTI Agent and Call-graph Profiler.
build_tptp_profiler.script
    Linux build script for the JVMTI Agent and Call-graph Profiler.
build_tptp_martini.bat
    Windows build script for the Martini SDK libraries.
build_tptp_martini.script
    Linux build script for the Martini SDK libraries.
build_tptp_all.script
    Linux build script for all JVMTI Agent libraries.

A. Dependencies

1) Compilers:

 - Windows/IA32: Microsoft Visual C++ v6.0 Service Pack 6
 - Windows/EM64T: Microsoft C/C++ Compiler Version 14.0 for EM64T/AMD64
   (Microsoft Platform SDK Windows 2003 Server SP1 ? R1)
 - Windows/IPF: Microsoft C/C++ Compiler Version 14.0 for IA-64
   (Microsoft Platform SDK Windows 2003 Server SP1 ? R1)

 - Linux-IA32 - GCC version 2.96, binutils - 2.14.90
 - Linux-IPF (Itanium) - GCC version 3.2.3, binutils - 2.14.90
 - Linux-EM64T (Intel64 or AMD64) - GCC version 3.4.4, 
   binutils 2.14.90 (or higher)
 
2) Software:
 - Java, J2SE 5.0 (1.5.0) JDK or above (http://java.sun.com/j2se/index.jsp)

 - TPTP 4.4 New Technology Agent Controller SDK
   (http://www.eclipse.org/tptp/home/downloads/downloads.html)

B. Windows Build Instructions

1) Install Java J2SE 5.0 JDK, and set the environment variable JAVA_HOME
to point to the directory containing the JDK 'include' directory.

2) Install the TPTP New Technology Agent Controller SDK and set the environment 
variable TPTP_ACSDK_HOME to point to the directory containing the SDK 'include' 
and 'lib' directories.

3) Execute the build_tptp_martini.bat script with the arguments that match your
build platform (execute the script without arguments to see usage information).
Example: to build for IA-32, use the following command:
    build_tptp_martini.bat ia32 release

NOTE: when building for IA-32, you can also use the tptp_martini.dsw workspace 
to build from the Visual Studio 6 IDE.

4) Execute the build_tptp_profiler.bat script with the arguments that match your
build platform (execute the script without arguments to see usage information).
Example: to build for IA-32, use the following command:
    build_tptp_profiler.bat ia32 release

NOTE: when building for IA-32, you can also use the tptp_profiler.dsw workspace 
to build from the Visual Studio 6 IDE.

5) When the build completes, all binaries are created under the following 
directory:
    src-native\bin\windows\<build_type>\<architecture>
Example: all binaries for an IA-32 release build will be created under
    src-native\bin\windows\release\IA-32


C. Linux Build Instructions

1) Follow the Windows Build Steps 1 and 2.

2) Execute the build_tptp_all.script script, specifying the build type in the 
first argument (see examples below).

NOTE: the build scripts use the gcc, g++ and binutils executables that appear on 
the system path. Make sure to configure your environment to use the correct tool 
versions, as specified in section 5.A.1 of this document.

NOTE: to clean the results of a previous build, add the word “clean? to the 
script argument.

Examples:
  - To create a "release" build, use the following command:
        bash build_tptp_all.script "RELEASE=1"
  - To create a "debug" build, use the following command:
        bash build_tptp_all.script "DEBUG=1"
  - To clean up a "release" build, use the following command:
        bash build_tptp_all.script "RELEASE=1 clean"
  - To clean up a "debug" build, use the following command:
        bash build_tptp_all.script "DEBUG=1 clean"

