Installing Performance Inspector ™ for Linux

• Supported systems
• Prerequisites
• Installation using the tarball
• Installation/uninstallation using rpm packages
• Environment setup and loading the driver
• A warning about ITrace
• Known problems

Supported systems

• Performance Inspector works with x86, x86_64, ppc64, and s390 architectures.
• This package has been tested with SLES 9 and 10, RHEL 4 and 5
• The lowest kernel version we tested with: 2.6.5
• The highest kernel version we tested with: 2.6.23
• Note that we did not test all possible OS/arch combinations, please let us know if something is not working on your system.
• On ppc64, there is no support for virtualized per thread metrics (ptt), except cycles (work in progress).
• On s390, there is no support for ptt.

Prerequisites

Performance Inspector is designed to work without the need to patch the kernel source code. Instead, it builds a kernel module compiled against the currently running kernel. This module takes advantage of the same system hooks used by OProfile, so we can be notified on timer ticks, task exit and memory unmap. For Dispatch hooks and ITrace, we use kprobes (ppc64) or run-time kernel patching (x86, x86_64).

You need the following prerequisites to compile and run Performance Inspector:

• Kernel source.
  • On many Linux systems it is not necessary to explicitly install the kernel source to build external kernel modules. Enough of the source is automatically included in /lib/modules/$(uname -r).
  • Some distributions separate the source, by making /lib/modules/$(uname -r)/source a symbolic link to /usr/src/linux, so you need to install the appropriate rpm with the kernel source if not already installed.
  • On RHEL4/RHEL5, you need kernel-devel-2.6.x.EL or kernel-smp-devel-2.6.x.EL (RHEL4, smp) rpm (where x matches your version number).
  • On SLES9, you need kernel-source-2.6.x rpm (where x matches your version number).
• binutils
  • We use libbfd.so during the trace post processing to get module information, and libopcodes.so to get assembly instructions.
  • Both libraries are components of the binutils package, which is usually included in Linux distrubutions.
  • On RHEL5, you also need to install the binutils-devel package, to get binutils header files.
• JDK
  • If you are building the tools using the tarball, you need Java and some JVMPI/JVMTI header files, usually part of JDK installation.
  • You can enter the name of the JDKDIR during installation, or add it to the path
  • Example: export PATH=${JAVAHOME}/bin:${JAVAHOME}/jre/bin:$PATH, where ${JAVAHOME} has an include directory
• kprobes
  • Needed for ptt and task dispatch tracing.
  • Not needed for x86, x86_64
  • Needed for ppc64 - if running on a system without kprobes and want ptt, you need to rebuild your kernel.
  • Not applicable for s390 (no ptt support).

1. Make sure you have a softlink (or directory) to /usr/src/linux that matches your kernel (See Prerequisites).
2. Make sure you have a libbfd.so (See Prerequisites).
3. Download the complete source tarball pi_linux_cross_src-20080731.tar.gz
4. Untar package:


tar -xzf pi_linux_cross_src-20080731.tar.gz
cd Dpiperf
 
5. From Dpiperf directory, run
   
   ./tinstall.appl
   
   This will build and install user space tools. You will be asked for JDK directory if not in the path.
6. Change to root (su) and from Dpiperf directory run
   
   ./tinstall.drv
   
   This will build, install, and load the kernel driver.

Installation using rpm packages

1. You may need to remove a previous package before installing a new one.
   The rpm packages may be removed using rpm -e package_name(s).
   Note that we changed the package name in this release,to remove the previous release run:
   rpm -e dpiperf_appl dpiperf_drv
   
   You need two rpm files: for the user-space applications and for the kernel module.
   The user-space applications are precompiled and the kernel module is automatically built after rpm installation.
2. Make sure you have a softlink (or directory) to /usr/src/linux that matches your kernel (See Prerequisites).


3. Make sure you have a libbfd.so (See Prerequisites).

For x86: pi_linux_appl-2008.07-31.i586.rpm
For x86_64: pi_linux_appl-2008.07-31.x86_64.rpm
For PPC64: pi_linux_appl-2008.07-31.ppc64.rpm
4. Install the rpm package for the user-space applications:
   
   rpm -ivh --prefix tools_dir pi_linux_appl-2008.07-31.arch.rpm
   
   tools_dir is the directory where you want the tools to be installed; if --prefix is ommited,
   the default directory is /opt directory.
   arch is the architecture for which you downloaded the rpm.
   Note: If binutil version on your system does not match the one that was on the system where the rpm package was built,
   the post-install rpm script will build liba2n and post on your system.
5. Download the kernel module rpm: pi_linux_drv-2008.07-31.noarch.rpm
6. Install the rpm package for the kernel module:
   
   rpm -ivh --prefix tools_dir pi_linux_drv-2008.07-31.noarch.rpm
   
   tools_dir is the directory where you want the driver source code to be installed; if --prefix is ommited,
   the default directory is /opt directory.
   The post-install rpm script will build and install the kernel module.

A warning about ITrace

DO NOT RUN ITRACE WITHOUT A BACKUP,
Since ITrace can hang your system. In the current package on x86 and x86_64 systems, ITrace run-time patches stay in the kernel until the computer is rebooted, so do not manually unload the driver after collecting an ITrace. On PPC64, ITrace support can be safely removed by unloading the driver.

Known Problems

• No tprof hooks with the first run.tprof after installation: reboot the machine and try again.
• No counter support for Xen.
• No graceful failure if two PttInit() calls follow one another, with different metrics
  (e.g., running two instances of Java with jprof at the same time, one with ptt_cycles and another with ptt_insts).