Building and Managing the Sampling Drivers

Managing the Sampling Driver for Windows Targets

To verify the sampling driver is installed correctly on a Microsoft Windows* OS, open the command prompt as an administrator and run the amplxe-sepreg.exe utility located at <install-dir>\bin32.

To make sure your system meets all the requirements necessary for the hardware event-based sampling collection, enter:

> amplxe-sepreg.exe -c

This command performs the following dependency checks required to install the sampling driver:

• platform, architecture, and OS environment

• availability of the sampling driver binaries: sep3drv.sys and sepdal.sys

• administrative privileges

• 32/64-bit installation

To check whether the sampling driver is loaded, enter:

> amplxe-sepreg.exe -s

If the sampling driver is not installed but the system is supported by the VTune Amplifier, execute the following command with the administrative privileges to install the driver:

> amplxe-sepreg.exe -i

Managing the Sampling Driver for Linux Targets

To verify that the sampling driver is installed correctly:

1. Check whether the sampling drivers are installed:

   > cd <install-dir>/sepdk/src

   > ./insmod-sep3 -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. To check which groups you belong to, type groups at the command line. This is only required if the permissions are other than 660 or 666.

To build the driver:

Prerequisites: You need kernel header sources and other additional software to build and load the kernel drivers on Linux. 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 files in the sepdk/src and powerdk/src directories.

If the drivers are missing, build them for your kernel:

> cd <install_dir>/sepdk/src

> ./build-driver -ni

If you are building a driver for an embedded platform, for example, with Yocto* 1.2 build of the fri2-noemgd board support package, your build command may look like the following:

> ./build-driver -ni --c-compiler=i586-poky-linux-gcc \
--kernel-src-dir=~/yocto/poky-denzil-7.0/build/tmp/work/fri2_noemgd-poky-linux/linux-yocto-3.2.11+git1+5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b_1+76dc683eccc46804729a76b9d2fd425ba540a483-r1/linux-fri2-noemgd-standard-build \
--kernel-version=3.2.18-yocto-standard \
--make-args="PLATFORM=x32 ARITY=smp" \
--install-dir=../src

To build the driver with the per-user event-based sampling collection on, use the -pu (-per-user) option as follows:

> ./build-driver -ni -pu

To install the drivers:

1. If building the drivers succeeds, install them manually with the insmod-sep3 script:

   > cd <install_dir>/sepdk/src

   > ./insmod-sep3 -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-sep3 -g <group> -pu

   Note

   If scripts do not work due to absence of standard Linux commands, you may install the driver manually using the Linux OS insmod command directly.

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 verify the driver configuration:

1. Make sure the kernel version is 2.6.28 or later.

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_OPROFILE=m (or CONFIG_OPROFILE=y)

   • CONFIG_HAVE_OPROFILE=y

3. Make sure that following options are enabled in the kernel configuration for EBS collection with stacks:

   • CONFIG_MODULES=y

   • CONFIG_SMP=y

   • CONFIG_MODULE_UNLOAD=y

   • CONFIG_KPROBES=y

   • CONFIG_RING_BUFFER=y

   • CONFIG_TRACEPOINTS=y (optional but recommended)

   • CONFIG_FRAME_POINTER=y (optional but recommended for kernel stack analysis)

./rmmod-sep3 -s

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.

Managing the Sampling Driver for Android Targets (VTune Amplifier for Systems only)

On some versions of Android systems, including most of the Intel supplied reference builds for SDVs, the required drivers are pre-installed in /lib/modules or /system/lib/modules. If the drivers are not pre-installed in any of these directories, you need to build them manually from the command line. Optionally, you can get the drivers integrated into the Android build so that they are built and installed when the operating system is built.

Android requires signed drivers. Every time the Android kernel is built, a random private/public key is generated. Drivers must be signed with the random private key to be loaded. The drivers (pax.ko , sep3_10.ko , and vtsspp.ko) must be signed with the same key and be compiled against the same kernel headers/sources as what is installed on the Android target system.

VTune Amplifier has options for building a new driver on the Linux host system and installing it on a target Android system. This is not the default and will only work if you provide the proper kernel headers/sources and a signing key. For example, the VTune Amplifier uses the --with-drivers option for building PMU drivers and --kernel-src-dir option for providing the configured kernel headers/sources tree path.

To build the sampling drivers on the host Linux system, enter:

<install-dir>/bin{32,64}/amplxe-androidreg.sh --package-command=build --with-drivers --kernel-src-dir=/ path /to/configured/kernel/sources [--jitvtuneinfo=jit|src|dex|none]

To install the sampling drivers from the Linux host, enter:

<install-dir>/bin{32,64}/amplxe-androidreg.sh --package-command=install --with-drivers --kernel-src-dir=/ path/to/configured/kernel/sources [--jitvtuneinfo=jit|src|dex|none]

To sign the drivers after the drivers are built:

Typically the VTune Amplifier for Systems automatically signs drivers if kernel sources with the keys are available when it builds the drivers. Otherwise, to manually sign the drivers, use the following command:

$KERNEL_SRC/source/scripts/sign-file CONFIG_MODULE_SIG_HASH $KERNEL_SRC/signing_key.priv $KERNEL_SRC/signing_key.x509 driver.ko

where the CONFIG_MODULE_SIG_HASH value is extracted from the $KERNEL_SRC/.config file.

Managing the Sampling Driver for the Intel Xeon Phi™ Coprocessor (VTune Amplifier XE only)

For hardware event-based sampling analysis on an Intel Xeon Phi coprocessor based on Intel Many Integrated Core (Intel MIC) architecture, sampling drivers should be installed on the coprocessor cards to be sampled. Typically, the VTune Amplifier installs the drivers by default during product installation. If for some reasons the sampling driver was not properly installed on the Intel Xeon Phi coprocessor card(s) or needs to be reinstalled, follow the instructions below.

To install the sampling drivers manually, run the following command lines:

1. Copy the install files to a system location:

   > <host_install_dir>/bin64/k1om/micboot_install.cmd

2. Start (or restart) the Intel Xeon Phi coprocessor service (this also restarts the sampling drivers once the files are copied in the previous step):

   > net start mpss

   > micctrl -w

To uninstall the sampling server and drivers, run the following commands:

> net stop mpss> <host_install_dir>/bin64/k1om/micboot_uninstall.cmd> net start mpss> micctrl –w