How to build and Install Vtune™ Amplifier Sampling Driver for Embedded/Mobile system

Intel® Developer Zone offers tools and how-to information for cross-platform app development, platform and technology information, code samples, and peer expertise to help developers innovate and succeed. Join our communities for Android, Internet of Things, Intel® RealSense™ Technology, and Windows to download tools, access dev kits, share ideas with like-minded developers, and participate in hackathon’s, contests, roadshows, and local events.

Intel® VTune™ Amplifier uses a sampling driver to enable the hardware Event-Based Sampling (EBS) analysis. During Intel System Studio production installation, the sampling driver can be installed for host system so that we can collect the performance data for applications that running on host system. However the sampling driver should also be installed on the target system if we want to collect the event-based sampling data for the application that running on target system. In this case, we may need to build the sampling driver manually to match the kernel requirement for the target system, and install the sampling driver on target system.

This article describes how to build and install the sampling driver for an embedded Linux system. The sampling drivers will be built as the kernel modules. Enable the sampling driver on target system will require root access of the target system. Make sure you have the root access on target before working on the sampling driver.

This article covers the following topics:
Prepare your Kernel Build Environment
Kernel Configuration Requirements
Signed Kernel Module Support
Build the VTune Amplifier Sampling Driver
Load the Sampling Drivers on Target Device

Prepare your Kernel Build Environment

To build the sampling driver for your target system, you should have the kernel build environment which exactly matching your target kernel version.

If you are building the target kernel on your local host and flash the kernel to the target device, you should already have the kernel source and the prepared kernel build environment for VTune amplifier sampling driver. In this case, the kernel source directory which will be used later for building sampling driver, is exactly the directory where you build your target kernel on the host system.

If you don’t have a build environment for your target kernel, you can config the kernel based on the kernel sources which used to build the target system. In this case, you should have the kernel sources which exactly match your target kernel version. In your kernel source directory, copy the configuration files of your target system to host system and rename it to .config in the kernel source directory. The target system configuration file is normally in the /boot/ folder with name config-`uname -r`. In your kernel source directory on host, try to prepare the build using the following command:
$ make oldconfig
$ make prepare
$ make modules_prepare

Once the configuration completes, you need to make sure that UTS_RELEASE in kernel-src-dir/include/generated/utsrelease.h, or depending on the kernel version kernel-src-dir/include/linux/utsrelease.h, matches `uname -r` output on your target system. Try to adjust your kernel Makefile in the kernel source directory if the version does not match.

Kernel Configuration Requirements for Sampling Driver

To use VTune Amplifier sampling driver for target system, your kernel version should be 2.6.28 or later. Some kernel options must be enabled to make sure the sampling driver can work smoothly. These kernel options are listed below. You need to make sure these options are enabled in the kernel configuration:

CONFIG_OPROFILE=m   (or CONFIG_OPROFILE=y)
CONFIG_MODULES=y
CONFIG_SMP=y
CONFIG_MODULE_UNLOAD=y
CONFIG_KPROBES=y         (must for sampling with stack)
CONFIG_RING_BUFFER=y (must for sampling with stack)
CONFIG_TRACEPOINTS=y (optional but recommended for sampling with stack)
CONFIG_FRAME_POINTER=y (optional but recommended for kernel stack analysis)

For most of embedded Linux system, these configurations are enabled by default. If you are working on a customized Linux configuration, check these options to make sure the VTune Amplifier sampling driver can work.

Signed Kernel Module Support

Since Linux kernel version 3.7 onwards, support has been added for signed kernel modules. When enabled, the Linux kernel will only load kernel modules that are digitally signed with the proper key. This allows further hardening of the system by disallowing unsigned kernel modules, or kernel modules signed with the wrong key, to be loaded.

You can check the configuration option CONFIG_MODULE_SIG_FORCE to see if the signed kernel modules are required. If it is enabled as "CONFIG_MODULE_SIG_FORCE=y", all the kernel modules should be signed with a valid key, so as for VTune Amplifier sampling drivers.

If signed kernel modules are required, such as most modern mobile OS like Android*, Tizen* etc, you must have the signed key which matching your target system. If you are building the kernel on your local host and flash it to your target device, these key files are available on the kernel source folder. In this case, you can build the sampling driver as usual. If you are building the sampling drivers from a fresh kernel source and want to use it for an existing target system, you may get a different key which may result in the error when loading the drivers on target system, for example, you may get error message "ERROR: could not insert module pax.ko: Required key not available". In this case, you should get the original key files and sign the sampling driver with right key. Alternatively you can build the new kernel and flash it to your device with your own build. For more information on signed kernel module, you may refer to Cryptographically-signed kernel modules.

Build the VTune Amplifier Sampling Driver

With the kernel source environment prepared, we can now build the sampling drivers. You can get the sampling driver sources from Intel system studio installation folder, for example, in folder /opt/intel/system_studio_2015.x.y/vtune_amplifier_for_systems/target where you can find the proper VTune Amplifier packages for the target system including the sources for sampling drivers. For example, in target/linux32, you can find everything required from a .tgz file for 32bit linux target. In target/linux64 folder, you can find the packages for 64bit target Linux system. In general, there are two packages available, the VTune Amplifier target package and the VTune Amplifier target "sep" package. The VTune Amplifier target package can be used for remote data collection from host to target. The "sep" package is only for the native performance collection on target system. Both packages contain the proper sampling driver sources. Extract the package, go to the sepdk/src folder and build drivers, for example:

$ cd sepdk/src
    $./build-driver -ni \
         --c-compiler=i586-xxx-linux-gcc \
         --kernel-version="3.4.34-25.1-clovertrail" \
         --kernel-src-dir=/kernel-src-dir/ \
         --make-args="PLATFORM=x32 ARITY=smp"

In the above sample, "--c-compiler" option is used to specify the cross build compiler. Make sure the compiler is available from PATH environment. If this option is not specified, it will use the host gcc compiler for sampling driver build.
"--kernel-version" option is used to specify 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 the kernel version.
"--kernel-src-dir" option is used to specify the kernel source directory, which we have prepared as described in the above sessions of this article.
"--make-args" option is used to specify the build arguments. For 32bit target system, use "PLATFORM=x32". For 64bit target system, use "PLATFORM=x32_64".
"-ni" option will disable the interactive during build.

Please use build-driver -h option to check details of all available options. By default, if all these options are not specified, the build-driver script will built the sampling drivers for your host system using the default gcc compiler.
Once the build finished, you will find the following .ko files in the sepdk/src folder:
pax/pax.ko
sep3_10.ko,
vtsspp/vtsspp.ko.

These .ko files are also copied to a new name which can reflect the target kernel version, e.g. the file sep3_10.ko may be copied to sep3_10-x32-3.4.34-27.2-clovertrailsmp.ko.
To verify if the driver is built with right vermagic, here is a simple way you can check. In the command line, run the command:
$modinfo ./sep3_10.ko |grep vermagic

It will give a vermagic string something like below for example:
vermagic: 3.4.34-27.2-clovertrail SMP preempt mod_unload ATOM

On your target shell, run lsmod and find a loaded kernel model, use modinfo to get the vermagic for that module. Make sure the sample driver vermagic is exactly same as the existing kernel module on target device.

Load the Sampling Drivers on Target Device

Copy the sepdk/src folder of the sampling driver to your target system by using ssh, ftp, adb, sdb etc anyways that supported by your system. Make sure you have root access of your target system, go to sepdk/src folder on the target shell, load the driver by executing the following command:
$./insmod-sep3

The scripts will load the sampling drives automatically. If you are running on a resource restricted environment, try to add the "-re" option as following:
$ ./insmod-sep3 -re

In the case that you may have to load the drivers manually, using the following command to load the sample drivers:
$insmod pax/pax.ko
$insmod sep3_10.ko
$insmod vtsspp/vtsspp.ko

You may try lsmod to see if pax, sep3_10 and vtsspp kernel modules are loaded successfully in kernel. Once the sampling drivers are loaded in your target kernel, you are ready to collect the event based performance data for your target system.
You need to disable the nmi_watchdog in the kernel before you start the performance collection. You may simply make it by the following command:
$echo 0 >/proc/sys/kernel/nmi_watchdog

Note:
If you are working on the Yocto* Project, or the Wind River* Linux, there are more easier way to build the sampling drivers for your target system. The sampling drivers, and the target collection packages can be built into your target system automatically. You can refer to the following articles for more details.

Using Intel(R) System Studio with Wind River Linux Build Environment

Using Intel(R) System Studio with the Yocto* Project