Intel® VTune™ Profiler User Guide

User Guide

Contents

Android* Target Analysis from the Command Line

Use the
Intel® VTune™
Profiler
 to collect data on a remote Android application from the host system (remote usage mode) via command line interface (
vtune
) and view the analysis result locally from the command line or GUI.
You may run the following analysis types on Android systems:

Configure and Run Performance Analysis on Android System

Remote data collection using the
vtune
 command running on the host is very similar to the native collection on the target except that the option is added to the command line.
Prerequisites:
 Make sure to prepare a target Android* system and your application for analysis.
To run an analysis on an Android device:
  1. Launch your application on the target device.
  2. Find out
    <pid>
     or
    <name>
     of the application running on remote Android system. For example, you can use adb shell ps command for the purpose: 
    adb shell ps
...
root   2956 2   0      0     c1263c67 00000000 S kworker/u:3
u0_a34 8485 174 770232 54260 ffffffff 00000000 R com.intel.tbb.example.tachyon
shell  8502 235 2148   1028  00000000 b76bcf46 R ps
...
  3. Optional
    : If you have several Android devices, you may set the
    ANDROID_SERIAL
     environment variable to specify the device you plan to use for analysis. For example:
    export ANDROID_SERIAL= emulator-5554
     or
    export ANDROID_SERIAL=10.23.235.47:5555
  4. On the development host, run
    vtune
     to collect data.
    By default, the
    vtune
     utility is located in the following directory:
    Use the following syntax to run an analysis:
    host>./
    vtune
     -target-system=android:
    deviceName
     -<
    action
    > <
    analysis_type
    > [-duration <
    duration_value
    >][-r <
    result_path
    >] [-search-dir=<
    search_dir
    >] [-source-search-dir=<
    source_search_dir
    >] - <
    target_application
    >
    where:
    • deviceName
       is the name of your Android device, for example: Medfield2B3E703C . If you do not specify the name of the device, the
      VTune
      Profiler
       uses the default device specified with
      adb
      . You do not need to specify the device name if you set the
      ANDROID_SERIAL
       environment variable before the collection.
    • <action>
       is the action to perform the analysis (
      collect
       or
      collect-with
      )
    • <
      analysis_type
      >
       is a predefined analysis type, such as
      hotspots
      ,
      uarch-exploration
      , and so on
    • <
      duration_value
      >
       is the duration in seconds
    • <
      result_path
      >
       is a PATH/name of the directory where a result is stored
    • <
      search_dir
      >
       is a path to search for binary files used by your Android application
    • <
      source_search_dir
      >
       is a path to search for source files used by your Android application
    • <
      target_application
      >
       is an application to analyze. The command option depends on analysis target type:
      • To specify an application (a native Linux* application running on Android) or a script to analyze, enter the path to the application or the script on your host system.
        This target type is not supported for the Hotspots analysis of Android applications.
      • To specify an Android application package to analyze, enter the name of the Android package installed on a remote device.
      • To specify a particular process to attach to and analyze, use the
        -target-process
         command to specify application by process name or the
        -target-pid
         command to specify the application by process PID.
      • To profile your Android system, do not specify target application.
        System-wide analysis is possible on rooted devices only.
  5. Optional
    : You can send
    pause
     and
    resume
     commands during collection from another console window, for example: 
    host>./vtune -C pause -r tachyon_r001
    host>./vtune -C resume -r tachyon_r001
  6. If you do not specify analysis duration, you can stop analysis by pressing
    Ctrl-C
     or sending the
    stop
     command from another console on the host development system: 
    vtune -r tachyon_r001 -C stop
You may use the
Command Line...
 option in the
VTune
Profiler
 graphical interface to automatically generate a command line for an analysis configuration selected in the GUI.

Hotspots Analysis (User-Mode Sampling)

In this mode, you can:
  • Run analysis
    without
     root access (although, root access is required for Java* analysis)
  • Run the Hotspots analysis (if a target process or PID is specified) to identify functions that take the most time to execute (
    hotspots
    )
  • Explore call stacks
  • View C/C++ generated functions/source
  • (If installed) Automatically obtain Java function names for functions that have been JITed and drill down to either JIT assembly or Java source or DEX Byte Code
    Java analysis is not supported for the 4th Generation Intel® Core™ processors (based on Intel microarchitecture code name Haswell).
Example
This example runs Hotspots analysis on target Android system. 
host>./vtune -collect hotspots -target-system=android -r tachyon_r@@@ -- com.intel.tbb.example.tachyon

Event-Based Sampling Analysis

In this mode, you can:
  • Use hardware event-based sampling analysis types with event groups predefined by Intel architects
  • View C/C++ generated functions/source
  • Explore call stacks (if a target process or PID is specified)
  • Analyze performance system wide (if call stack analysis is disabled)
  • (If installed) Automatically obtain Java function names for functions that have been JITed and drill down to either JIT assembly or Java source or DEX Byte Code
    Java analysis is not supported for the 4th Generation Intel® Core™ processors (based on Intel microarchitecture code name Haswell) or systems using ART.
The following event-based sampling analysis types are supported by the
VTune
Profiler
 on Android systems:
To associate JITed Java functions to samples in the system-wide event-based sampling, you have the following two options:
  • Specify
    -target-process
    Proccess.Name
     for the process you are interested in similar to how you do this for the event-based call stack collection.
  • For any process you are interested in, copy the JIT files for the PID of that process into the
    data.0
     directory, and re-resolve the results in the
    VTune
    Profiler
     GUI:
    1. Collect results: 
      host>./vtune -collect <analysis_type> -duration=60 -target-system=android -r system_wide_r@@@
    2. Find PID of interesting processes: 
      adb shell ps | [grep MyApp]
u0_a79 1762 141 575912 75468 ffffffff 4006f2ef Scom.android.MyApp
    3. Copy all
      jit
       files for processes you are interested in to the
      data.0
      directory: 
      adb pull /data/vtune/results/localhost.1762*.jit system_wide_r000/data.0
Examples
Example 1: Microarchitecture Exploration Analysis
This example launches specified Android package and collects a complete list of events required to analyze typical client applications running on the 4th Generation Intel Core processor. 
host>./vtune -collect uarch-exploration -target-system=android -r tachyon_r@@@ -target-process com.intel.tbb.example.tachyon
Example 2: Call Stack Analysis
By default, the
VTune
Profiler
 does not collect stack data during hardware event-based sampling. To enable call stack analysis, use the
enable-stack-collection=true
 knob. For example: 
host>./vtune -collect hotspots -knob sampling-mode=hw -knob enable-stack-collection=true -target-system=android -r tachyon_r@@@ -target-process com.intel.tbb.example.tachyon
Example 3: System-wide Data Collection
To analyze performance of your target application and all other processes running on the Android system, use the
--duration
 option and do not specify an analysis target. 
host>./vtune -collect hotspots -knob sampling-mode=hw -target-system=android -duration=60 -r system_wide_r@@@
Example 4: Unplugged Mode Collection
This example configures the Hotspots analysis for the application on an Android system that will be launched after disconnecting the device from the USB cable or a network: 
host>./vtune --collect hotspots --target-system=android -unplugged-mode -r quadrant_r@@@ --target-process com.intel.fluid

Custom Analysis

Use the
-collect-with
 option to configure
VTune
Profiler
 to run a custom user-mode sampling and tracing (
runss
) or event-based sampling (
runsa
) analysis and take other than default configuration options. For example, to run a custom event-based sampling analysis, use the
-collect-with
 option and specify required event counters with the
-knob event-config
 option as follows: 
host>./vtune -collect-with runsa -target-process com.intel.tbb.example.tachyon -r system_wide_r001 -knob collection-detail=stack-sampling [-event-mux] -knob event-config=CPU_CLK_UNHALTED.REF_TSC:sa=1800000,CPU_CLK_UNHALTED
To display a list of events available on the target PMU, enter:
vtune
 -collect-with <
collector
> -target-system=android:
deviceName
 -knob event-config=? <
target_application
>
You can take any counter that the Performance Monitoring Unit (PMU) of that processor supports. Additionally, you can enable multiple counters at a time. Each processor supports only a specific number of counters that can be taken at a time. You can take more events than the processor supports by using the
-event-mux
 option, which will round robin the events you specified on the available counters in that processor.
Typically, you are recommended to use analysis types with the predefined sets of counters. Use of specific counters is targeted for advanced users. Please note that names of some counters may not exactly correspond to the analysis scope provided with these counters.
After collecting these counters, import the result to the
VTune
Profiler
 GUI and explore the Microarchitecture Explorationdata.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.