Getting Started with Debugging with Intel® Parallel Studio XE 2016

Prerequisites

Required Hardware

Two systems are required for debugging code running on the GPU. The main reason for this requirement is that video output from the GPU could be interrupted during debugging, which would make an IDE integrated debugger impossible to use on a single system.
The currently support target CPUs are Intel 4-th and 5-th Generation Core processors with integrated graphics. The detailed target system setup is detailed below.
The host system can be any stable, relatively recent Linux* distribution with no special requirements to host hardware. For this document, the host system is assumed to be CentOS* 7, but other systems work as well.
Both systems should be able to communicate freely with each other over TCP/IP networking, ideally within the same sub-net and a Domain Name Server. In addition, it is required to have the ability to elevate privileges using "sudo" or "su" commands for the purpose of installation of required packages.

Required Software Packages

• tool suite base installer
• Intel® Media Driver package consisting of RPM files and installation scripts.
• Eclipse* Luna CDT edition. Download it from

  https://www.eclipse.org/downloads/

Target System Setup

This target setup description uses CentOS* 7 as the base installation. Currently only 64-bit versions are supported.

1. Install CentOS* 7. Choose only to install the minimal system, without any X Server or GUI. During installation:
   • Use a Minimal Install under Software Selection.
   • Configure networking under Network & Hostname.
   • Create a user and add it to wheel group by selecting Make this user administrator on the Create User screen.
2. After installation, log in to the new system. Execute the following commands:

   Target:

   sudo yum -y update
   sudo yum -y group install "Development Tools"
   sudo yum -y install pciutils redhat-lsb nfs-utils mesa-dri-drivers rpm-build redhat-rpm-config \
   5
   asciidoc hmaccalc perl-ExtUtils-Embed pesign xmlto audit-libs-devel binutils-devel elfutils-devel \
   elfutils-libelf-devel newt-devel numactl-devel pciutils-devel python-devel zlib-devel net-tools \
   cmake ncurses-devel wget
   sudo usermod -a -G video $USER
   sudo reboot

3. After reboot, log in again. To make the workflow easier, it is recommended to share files between target and host system. Use the target system as host for sharing. This could be reversed, but for the purpose of getting started, it is not required to modify the host system. Skip this step, if your systems already have a common sharing mechanism.

   Note:
   This NFS sharing setup is not secure. Other systems may connect to the NFS server and access files. Please refer to external documentation for more information about how to secure an NFS server.

   Target:

   mkdir shared
   sudo mkdir -p /export/shared
   sudo chown $USER.$USER /export/shared
   sudo sh -c 'echo "/export *(rw,fsid=0,insecure,no_subtree_check,async)" >>/etc/exports'
   sudo sh -c 'echo "/export/shared *(rw,nohide,insecure,no_subtree_check,async)" >>/etc/exports'
   sudo sh -c 'echo `pwd`/shared /export/shared none rw,bind 0 0 >>/etc/fstab'
   sudo mount -a
   sudo firewall-cmd --permanent --add-port=2049/tcp
   sudo firewall-cmd --permanent --add-port=10000/tcp
   sudo firewall-cmd --permanent --add-port=61000-61100/tcp
   sudo systemctl enable rpcbind
   sudo systemctl enable nfs-server
   sudo systemctl enable nfs-lock
   sudo systemctl enable nfs-idmap
   sudo systemctl restart rpcbind
   sudo systemctl restart nfs-server
   sudo systemctl restart nfs-lock
   sudo systemctl restart nfs-idmap

4. Test the sharing setup by connecting from the host machine:

   Host:

   cd ~
   mkdir shared
   sudo mount -t nfs4 igfx-target:/shared ~/shared

5. Copy the driver installation files to the shared location and extract the files. This should be done from the host system:

   Host:

   mkdir -p ~/shared/drivers
   cd ~/shared/drivers
   cp <driver-file-location>/intel-linux-media_<distribution>.<version-number>_64bit.tar.gz ./

6. Next install the driver on the target system:

   Target:

   cd ~/shared/drivers
   tar xfz intel-linux-media_<distribution>.<version-number>_64bit.tar.gz
   sudo ./install_media.sh
   mkdir patches
   cd patches
   tar xfjv /opt/intel/mediasdk/opensource/patches/kmd/3.10.0/intel-kernel-patches.tar.bz2
   for PATCH_FILE in intel-kernel-patches/*.patch; do cat $PATCH_FILE >> ./intel-kernel.patch; done

7. The final step is to build the required Linux* kernel:

   Target:

   mkdir -p ~/rpmbuild/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
   echo '%_topdir %(echo $HOME)/rpmbuild' > ~/.rpmmacros
   KERNEL1=`uname -r`
   KERNEL2=${KERNEL1%.x86_64}
   rpm -i http://vault.centos.org/7.0.1406/updates/Source/SPackages/kernel-$KERNEL2.src.rpm
   cd ~/rpmbuild/SPECS
   rpmbuild -bp --target=$(uname -m) kernel.spec
   cd ~/rpmbuild/BUILD/kernel-$KERNEL2/linux-$KERNEL1
   patch -p 1 <~/shared/drivers/patches/intel-kernel.patch
   sed -i 's/CONFIG_STRICT_DEVMEM=y/# CONFIG_STRICT_DEVMEM is not set/g' .config
   sed -i 's/bool i915_enable_hangcheck __read_mostly = true;/bool i915_enable_hangcheck __read_mostly = false;/g' drivers/gpu/drm/i915/i915_drv.c
   sed -i 's/int i915_enable_ppgtt __read_mostly = -1;/int i915_enable_ppgtt __read_mostly = 1;/g' drivers/gpu/drm/i915/i915_drv.c
   sed -i 's/int i915_enable_cmd_parser __read_mostly = 1;/int i915_enable_cmd_parser __read_mostly = 0;/g' drivers/gpu/drm/i915/i915_drv.c
   make olddefconfig
   make -j16
   sudo make modules_install
   sudo make install
   sudo reboot

This completes the target setup. To run a sanity test after the reboot, execute:

Target:

vainfo

Host System Setup

For this setup, we assume a standard installation of CentOS* 7 as a desktop system with development tools present.

1. Extract Eclipse* Luna into the home directory.

   Host:

   cd ~
   tar xfz eclipse-cpp-luna-R-linux-gtk-x86_64.tar.gz

2. Install the tool suite containing the Intel® Debugger for Heterogeneous Compute by following the installation guidelines.
3. For this tutorial, we use the the shared directory on the target system. If necessary, execute the following lines in a terminal emulator.

   Host:

   cd ~
   mkdir shared
   sudo mount -t nfs4 igfx-target:/shared ~/shared

4. Extract the samples for Intel® Debugger for Heterogeneous Compute from ./samples_2016/en/compiler_c/psxe/gfx_samples.tar.gz and integrate them into Eclipse*. The code below also copies the necessary debugger files to the shared drive to make them accessible on the target system at the same time.

   Host:

   cd ~/shared
   INSTALLDIR=<install-dir>
   cp -r $INSTALLDIR/debugger_2016/targets/intel64_igfx .
   cp -r $INSTALLDIR/lib/* .
   tar xfz $INSTALLDIR/samples_2016/en/compiler_c/psxe/gfx_samples.tar.gz
   source $INSTALLDIR/bin/compilervars.sh intel64
   ~/eclipse/eclipse

5. Extract the samples for Intel® Debugger for Heterogeneous Compute and integrate them into Eclipse*.

   Host:

   Select New > Makefile Project with Existing Code. Set the project to, for example, Samples and browse for the location in ~/shared/gfx_samples.

   By default the projects are not built with debug information enabled, so open the ~/shared/ gfx_samples/Makefile and modify the line for CFLAGS to:

   Makefile:

   CFLAGS = -MMD -g -O0 -I_gfx_O0

6. Build the project.

The next step is to create a debug configuration:

1. Select Run > Debug Configurations and create a new C/C++ Remote Application.
   • Under the Main tab, select, for example, the "Matmult" application in the out directory.
   • As launcher, use the GDB (DSF) Manual Remote Debugging Launcher.
2. Still on the Debugger tab, browse for the start_mpm.sh script (located in the Intel® Parallel Studio XE 2016 installation) in the GDB debugger field.
3. Specify the connection to the target system on the Connection sub-tab.

The host system is now ready for debugging. Do not press the Debug button yet, since debugging needs to be started on the target system.

Debugging Example for CentOS* 7

The final step in the system setup is to start debugging on the target system. Since the project files are already shared, there is no need to transfer any files.
The debugger framework requires a system service daemon to run in the background for managing the access the GPU hardware registers. This service only needs to be started once and can continue to run indefinitely.

Target:

sudo ~/shared/intel64_igfx/bin/igfxdbgd

Note:
If you want to stop the service daemon after a debugging session, you can use the -t option.
Target:
sudo ~/shared/intel64_igfx/bin/igfxdbgd -t

Now the debugger server can be started, which launches the target program.

Target:

# Set up compiler runtime, if necessary
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/testuser/shared/system_studio_target/compiler/lib/intel64
~/shared/intel64_igfx/bin/gdbserver-ia.sh :10000~/shared/gfx_samples/out/Matmult

Now switch back to the host system and click Debug. The debugging session should start and execution will stop just inside the main() function.

At this point debugging should work as normal. To stop in any code on the GPU, insert a breakpoint at relevant code locations after pragma offload target(gfx) statements. In this example, one such location can be found in the In this example, one such location can be found in the Matmult.cpp source file from line 370 onward.

Once the host application starts offloading code, the GPU threads are automatically added to the debugging session and inserted breakpoints get triggered as the execution comes across them.

Note:
In some cases, and depending on network speeds, it might take 10-20 seconds for all debug information to get processed and loaded, due to the remote debugging configuration.