Building and Managing the Sampling Drivers

Managing the Sampling Driver for Linux Targets

Prerequisites for remote target systems: You need root access to the target system.

To verify that the sampling driver is installed correctly (host only):

1. Check whether the sampling drivers are installed:

   > cd <install-dir>/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 660 or 666.

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 files in the sepdk/src and powerdk/src directories.

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.

To build the driver if it is missing:

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>.

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.

Please use ./build-driver -h to get the detailed help message on the script usage.

To install the 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.

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. If the -g option is not specified, the group vtune will be used by default.

   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

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 (socperf2_0.ko, pax.ko , sep4_0.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 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 as root or under sudo:

For Intel® Xeon Phi™ coprocessor code named Knights Corner:

1. Copy the install files to a system location:

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

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):

   > service mpss restart

   > micctrl -w

For Intel® Xeon Phi™ coprocessor code named Knights Landing (Linux only): Copy the install files to a system location and load drivers:

> <host_install_dir>/bin64/knl-lb/mic_install.sh

To uninstall the sampling server and drivers, run the following commands as root or under sudo:

For Intel® Xeon Phi™ coprocessor code named Knights Corner:

> service mpss stop

> <host_install_dir>/bin64/k1om/micboot_uninstall.sh

> service mpss restart

> micctrl -w

For Intel® Xeon Phi™ coprocessor code named Knights Landing:

> <host_install_dir>/bin64/knl-lb/mic_uninstall.sh