User Guide

Contents

Build and Install the Sampling Drivers for Linux* Targets

Prerequisites for remote Linux target systems
: You need root access to the target system.
Prerequisites for all Linux systems
: Sampling driver sources. You can find the sampling driver sources for the local system in the
<install_dir>/sepdk
folder of your
VTune
Profiler
installation. For remote targets, locate the target packages for the desired system in the
<install_dir>/target
folder of your installation, copy the package to the target system, extract it, and build the driver.

Install Drivers on Linux* Host Systems

During product installation on a host Linux OS, you may control the drivers installation options via the Advanced Options.
VTune
Profiler
provides the following options:
Use This Option
To Do This
Sampling driver install type [build driver (default) / driver kit files only ]
Choose the driver installation option. By default,
VTune
Profiler
uses the Sampling Driver Kit to build the driver for your kernel. You may change the option to
driver kit files only
if you want to build the driver manually after installation.
Driver access group [ vtune (default) ]
Set the driver access group ownership to determine which set of users can perform the collection on the system. By default, the group is
vtune
. Access to this group is not restricted. To restrict access, see the
Driver permissions
option below. You may set your own group during installation in the Advanced options or change it manually after installation by executing:
./boot-script -–group <
your_group
>
from the
<>/sepdk/src
directory.
Driver permissions [ 660 (default) ]
Change permissions for the driver. By default, only a
vtune
group user can access the driver. Using this access the user can profile the system, an application, or attach to a process.
Load driver [ yes (default) ]
Load the driver into the kernel.
Install boot script [ yes (default) ]
Use a boot script that loads the driver into the kernel each time the system is rebooted. The boot script can be disabled later by executing:
./boot-script --uninstall
from the
<
install-dir
>/sepdk/src
directory.
Enable per-user collection mode [no (default) / yes]
Install the hardware event-based collector driver with the per-user filtering on. When the filtering is on, the collector gathers data only for the processes spawned by the user who started the collection. When it is off (default), samples from all processes on the system are collected. Consider using the filtering to isolate the collection from other users on a cluster for security reasons. The administrator/root can change the filtering mode by rebuilding/restarting the driver at any time. A regular user cannot change the mode after the product is installed.
For MPI application analysis on a Linux* cluster, you may enable the
Per-user Hardware Event-based Sampling
mode when installing the Intel Parallel Studio XE Cluster Edition. This option ensures that during the collection the
VTune
Profiler
collects data only for the current user. Once enabled by the administrator during the installation, this mode cannot be turned off by a regular user, which is intentional to preclude individual users from observing the performance data over the whole node including activities of other users.
After installation, you can use the respective
vars.sh
files to set up the appropriate environment (PATH, MANPATH) in the current terminal session.
Driver build options …
Specify the location of the kernel header files on this system, the path and name of the C compiler to use for building the driver, the path and name of the make command to use for building the driver.

Check Sampling Driver Installation

To verify that the sampling driver is installed correctly on the host Linux system:
  1. Check whether the sampling drivers are installed:
    $ cd <>/sepdk/src
    $ ./insmod-sep -q
    This provides information on whether the drivers are currently loaded and, if so, what the group ownership and file permissions are on the driver devices.
  2. Check group permissions.
    If drivers are loaded, but you are not a member of the group listed in the
    query
    output, request your system administrator to add you to the group. By default, the driver access group is
    vtune
    . To check which groups you belong to, type
    groups
    at the command line. This is only required if the permissions are other than 666.
If there is no collection in progress, there is no execution time overhead of having the driver loaded and very little overhead for memory usage. You can let the system module be automatically loaded at boot time (for example, via the
install-boot-script
script, used by default). Unless the data is being collected by the
VTune
Profiler
, there will be no latency impact on the system performance.

Verify Kernel Configuration

To verify kernel configuration:
  1. Make sure that the kernel header sources are present on your host system. The kernel version should be 2.6.28 or later. To find the kernel version, explore
    kernel-src-dir/include/linux/utsrelease.h
    , or, depending on the kernel version:
    kernel-src-dir/include/generated/utsrelease.h
    . For more details, see the
    README.txt
    file in the
    sepdk/src
    directory.
  2. Make sure the following options are enabled in the kernel configuration for hardware event-based sampling (EBS) collection:
    • CONFIG_MODULES=y
    • CONFIG_MODULE_UNLOAD=y
    • CONFIG_PROFILING=y
    • CONFIG_SMP=y
    • CONFIG_TRACEPOINTS=y
      (optional but recommended)
  3. In addition to the options above, make sure the following options are enabled in the kernel configuration for EBS collection
    with stacks
    :
    • CONFIG_KPROBES=y
    • CONFIG_RING_BUFFER=y
    • CONFIG_FRAME_POINTER=y
      (optional but recommended for Call Stack Mode)
  4. For remote target systems, determine if signed kernel modules are required (
    CONFIG_MODULE_SIG_FORCE=y
    ). If they are, you must have the signed key that matches your target system.
    If you are building the sampling drivers from a fresh kernel source and want to use it for an existing target system, get the original key files and sign the sampling driver with the original key. Alternatively, build the new kernel and flash it to the target device so the target device uses your kernel build.

Build the Sampling Driver

Prerequisites
:
  • You need kernel header sources and other additional software to build and load the kernel drivers on Linux. Refer to the Verify kernel configuration section.
  • To cross-build drivers for a remote target Linux system, extract the package from the
    <install-dir>
    /target
    folder to
    <
    extract_dir
    >
    .
If the current version of the sampling driver that is shipped with the
VTune
Profiler
installation does not suit your needs, for example, due to a recent change in the Linux* kernel, you can find the latest version of the sampling driver on the Sampling Driver Downloads page.
To build the driver if it is missing:
  1. Change the directory to locate the build script:
    • To build drivers for a local system:
      $ cd <
      install-dir
      >/sepdk/src
    • To cross-build drivers for a remote target system:
      $ cd <
      extract-dir
      >/sepdk/src
  2. Use the
    build-driver
    script to build the drivers for your kernel. For example:
  • $ ./build-driver
    The script prompts the build option default for your local system.
  • $ ./build-driver -ni
    The script builds the driver for your local system with default options without prompting for your input.
  • $ ./build-driver -ni -pu
    The script builds the driver with the per-user event-based sampling collection on without prompting for your input.
  • $ ./build-driver -ni \
    --c-compiler=i586-i586-xxx-linux-gcc \
    --kernel-version="
    <kernel-version>
    " \
    --kernel-src-dir=
    <kernel-source-dir>
    \
    --make-args="PLATFORM=x32 ARITY=smp"
    --install-dir=
    <path>
    The script builds the drivers with a specified cross-compiler for a specific kernel version. This is usually used for the cross-build for a remote target system on the current host. This example uses the following options:
    • -ni
      disables the interactive during the build.
    • --c-compiler
      specifies the cross build compiler. The compiler should be available from the PATH environment. If the option is not specified, the host GCC compiler is used for the build.
    • --kernel-version
      specifies the kernel version of the target system. It should match the
      uname -r
      output of your target system and the UTS_RELEASE in
      kernel-src-dir/include/generated/utsrelease.h
      or
      kernel-src-dir/include/linux/utsrelease.h
      , depending on your kernel version.
    • --kernel-src-dir
      specifies the kernel source directory.
    • --make-args
      specifies the build arguments. For a 32-bit target system, use
      PLATFORM=x32
      . For a 64-bit target system, use
      PLATFORM=x32_64
    • --install-dir
      specifies the path to a writable directory where the drivers and scripts are copied after the build succeeds.
Use
./build-driver -h
to get the detailed help message on the script usage.
To build the sampling driver as RPM using build services such as Open Build Service (OBS):
Use the
sepdk.spec
file located at the
<
install-dir
>/sepdk/src
directory.

Install the Sampling Drivers

Prerequisites for remote target systems
: Copy the
sepdk/src
folder or the folder specified by the
--install-dir
option when building the driver to the target system using ssh, ftp, adb, sdb, or other supported means.
To install the drivers:
  1. If building the drivers succeeds, install them manually with the
    insmod-sep
    script:
    $ cd <
    install_dir
    >/sepdk/src
    $ ./insmod-sep -r -g <
    group
    >
    where
    <
    group
    >
    is the group of users that have access to the driver.
    To install the driver that is built with the per-user event-based sampling collection on, use the
    -pu (-per-user)
    option as follows:
    $ ./insmod-sep -g <
    group
    > -pu
    If you are running on a resource-restricted environment, add the
    -re
    option as follows:
    $ ./insmod-sep -re
  2. Enable the Linux system to automatically load the drivers at boot time:
    $ cd <
    install_dir
    >/sepdk/src
    $ ./boot-script --install -g <
    group
    >
    The
    -g
    <group>
    option is only required if you want to override the group specified when the driver was built.
To remove the driver on a Linux system, run:
./rmmod-sep -s

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804