Build and Install the Sampling Drivers for Linux* Targets
Install Drivers on Linux* Host Systems
Use This Option
To Do This
Sampling driver install type [build driver (default) / driver kit files only ]
Choose the driver installation option. By default,
VTuneuses the Sampling Driver Kit to build the driver for your kernel. You may change the option to
driver kit files onlyif 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 permissionsoption below. You may set your own group during installation in the Advanced options or change it manually after installation by executing:
./boot-script -–group <from the
Driver permissions [ 660 (default) ]
Change permissions for the driver. By default, only a
vtunegroup 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 --uninstallfrom the
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 Samplingmode when installing the Intel Parallel Studio XE Cluster Edition. This option ensures that during the collection the
VTunecollects 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.shfiles 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
- Check whether the sampling drivers are installed:$ ./insmod-sep -qThis provides information on whether the drivers are currently loaded and, if so, what the group ownership and file permissions are on the driver devices.
- Check group permissions.If drivers are loaded, but you are not a member of the group listed in thequeryoutput, request your system administrator to add you to the group. By default, the driver access group isvtune. To check which groups you belong to, typegroupsat the command line. This is only required if the permissions are other than 666.
Verify Kernel Configuration
- 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, explorekernel-src-dir/include/linux/utsrelease.h, or, depending on the kernel version:kernel-src-dir/include/generated/utsrelease.h. For more details, see theREADME.txtfile in thesepdk/srcdirectory.
- Make sure the following options are enabled in the kernel configuration for hardware event-based sampling (EBS) collection:
- CONFIG_PROFILING=y(kernel versions 5.16 or older)
- CONFIG_TRACEPOINTS=y(required for kernel versions 5.17 and newer; recommended for all other versions)
- CONFIG_KPROBES=y(kernel versions 5.17 and newer)
- In addition to the options above, make sure the following options are enabled in the kernel configuration for EBS collectionwith stacks:
- 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
- To cross-build drivers for a remote target Linux system, extract the package from thefolder to<install-dir>/target<.extract_dir>
- 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
- Use thebuild-driverscript to build the drivers for your kernel. For example:
- $ ./build-driverThe script prompts the build option default for your local system.
- $ ./build-driver -niThe script builds the driver for your local system with default options without prompting for your input.
- $ ./build-driver -ni -puThe script builds the driver with the per-user event-based sampling collection enabled, 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:
- -nidisables the interactive during the build.
- --c-compilerspecifies 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-versionspecifies the kernel version of the target system. It should match theuname -routput of your target system and the UTS_RELEASE inkernel-src-dir/include/generated/utsrelease.horkernel-src-dir/include/linux/utsrelease.h, depending on your kernel version.
- --kernel-src-dirspecifies the kernel source directory.
- --make-argsspecifies the build arguments. For a 32-bit target system, usePLATFORM=x32. For a 64-bit target system, usePLATFORM=x32_64
- --install-dirspecifies the path to a writable directory where the drivers and scripts are copied after the build succeeds.
Install the Sampling Drivers
- If building the drivers succeeds, install them manually with theinsmod-sepscript:$ cd <install_dir>/sepdk/src$ ./insmod-sep -r -g <group>where<is the group of users that have access to the driver.group>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> -puIf you are running on a resource-restricted environment, add the-reoption as follows:$ ./insmod-sep -re
- Enable the Linux system to automatically load the drivers at boot time:$ cd <install_dir>/sepdk/src$ ./boot-script --install -g <group>The-goption is only required if you want to override the group specified when the driver was built.<group>