Getting Started with Debugging with Intel® Parallel Studio XE 2017

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 4th, 5th and 6th 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 description 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.

For other prerequisites, new debugger features, hardware and software requirements, and known issues refer to the release notes.. 

Required Software Packages

• Intel® System Studio 2017
• Intel® Media Driver package consisting of a compressed tar archive.
• Eclipse* Luna or Mars CDT edition. Download it from

  http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/1/eclipse-cpp-mars-1-linux-gtk-x86_64.tar.gz

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.1. 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 install epel-release
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 \
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 dkms
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/tcpsudo 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. Install the Intel HD Graphics Driver for Linux on the target system. The driver package and documentation is located at: https://registrationcenter.intel.com/download.aspx?ProductID=2112&pass=yes

   Host:

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

   Note: If the latest packages installed on the target system have higher version numbers than the files provided with the driver package, edit the file install_sdk_UMD_CentOS.sh by adding --oldpackage to the parameters for rpm. So the line should read rpm -Uvh --oldpackage \.

   There can be a similar problem with the kernel rpm that gets created by the build_kernel_rpm_CentOS.sh script, if a newer kernel version already exists on the target system. In that case install the kernel rpm packages on the target using:

   Target:

   sudo rpm -i --oldpackage rpmbuild/RPMS/x86_64/kernel-3.10.0-229.1.2.47109.MSSr6.el7.centos.x86_64.rpm rpmbuild/RPMS/x86_64/kernel-devel-3.10.0-229.1.2.47109.MSSr6.el7.centos.x86_64.rpm

6. For the debugger to operate correctly, some ports need to be allowed through the firewall:

   Target:

   sudo firewall-cmd --permanent --add-port=10000/tcp
sudo firewall-cmd --permanent --add-port=61000-61100/tcp
sudo firewall-cmd --permanent --add-port=10001/tcp


7. The final step is to install the debugger target packages: Copy the RPM files from /opt/intel/debugger_2017/gdb/targets/idhc/install to shared directory.

   Host:

   cp /opt/intel/debugger_2017/gdb/targets/idhc/install/*.rpm ~/shared

8. Then install them on the target.

   Target:

   cd ~/shared
sudo rpm -i gdbserver-igfx-7.6.1-1.x86_64.rpm libelfdwarf-1.0-1.x86_64.rpm libigfxdbg-1.0-1.x86_64.rpm gdbserver-ia-7.6.1-1.x86_64.rpm
igfxdcd-dkms-1.0-1.x86_64.rpm
sudo dkms add -m igfxdcd -v 1.0
sudo dkms build -m igfxdcd -v 1.0
sudo dkms install -m igfxdcd -v 1.0
sudo modprobe igfxdcd

Host System Setup

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

1. Extract Eclipse* Mars into the home directory.

   Host:

   cd ~
tar xfz eclipse-cpp-mars-1-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. Copy the runtime libraries onto the share, so they can be used on the target system.

   Host:

   mkdir -p ~/shared/lib
cd ~/shared/lib
cp /opt/intel/compilers_and_libraries/linux/lib/intel64/* .


The next step is to start Eclipse*.

1. Host:

   cd ~/shared
source /opt/intel/bin/compilervars.sh intel64
~/eclipse/eclipse

   At startup enter the workspace path that points into the shared directory, i.e., /home/$USER/shared/workspace.

2. Select New > C+ Project  to create a new project.
3. As project name, enter a convenient name, such as "matmult".
4. As project type, select Makefile Project > Empty Project.

You now need to add a C++ source file and a Makefile for the project.

1. Create the source file using File > New > Source File. Enter matmult.cpp as the name and accept with OK.
2. Copy and paste the following code into the new C++ source file:

   /* Copyright 2016 Intel Corporation. All Rights Reserved.
* The source code contained or described herein and all
* documents related to the source code ("Material") are owned by
* Intel Corporation or its suppliers or licensors. Title to the
* Material remains with Intel Corporation or its suppliers and
* licensors. The Material is protected by worldwide copyright
* laws and treaty provisions. No part of the Material may be
* used, copied, reproduced, modified, published, uploaded,
* posted, transmitted, distributed, or disclosed in any way
* except as expressly provided in the license provided with the
* Materials. No license under any patent, copyright, trade
* secret or other intellectual property right is granted to or
* conferred upon you by disclosure or delivery of the Materials,
* either expressly, by implication, inducement, estoppel or
* otherwise, except as expressly provided in the license
* provided with the Materials.
*/
#include <stdio.h>

void matmult()
{
// Sample data
int a[3][2] = { { 1, 2 },{ 3, 4 },{ 5, 6 } };
int b[2][3] = { { 6, 5, 4 },{ 3, 2, 1 } };
int c[3][3] = { { 0, 0, 0 },{ 0, 0, 0 },{ 0, 0, 0 } };
// Offloaded code
#pragma offload target(gfx) pin(a) pin(b) pin(c)
_Cilk_for(int i = 0; i < 3; i++)
{
_Cilk_for(int j = 0; j < 3; j++)
{
for (int k = 0; k < 2; k++)
{
c[i][j] += a[i][k] * b[k][j];
}
}
}
// CPU code
for (int i = 0; i < 3; i++)
{
for (int j = 0; j < 3; j++)
{
printf("%2d ", c[i][j]);
}
printf("\n");
}
}
int main(int argc, char *argv[])
{
matmult();
return 0;
}


3. To create the Makefile for the project, select File > New > Other, then General > File. As the file name, enter Makefile.
4. Copy and paste the following code:

   all: matmult.cpp
icpc -gdwarf-3 -qoffload-arch=haswell:visa3.1 -O0 matmult.cpp

   Note:There needs to be a TAB character in front icpc, otherwise make will not be functional.

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

   Change the default launcher by clicking Select other....

   

2. In the next dialog box, change the configuration to a manual launcher:

   

3. Going back to the Debug Configuration, enter the output name of the project, i.e., /home/user/shared/workspace/matmult/a.out.
4. Select Disable auto build, since the application gets started on the target system before debugging start, so a rebuild would cause inconsistencies.

   

5. On the Debugger tab, browse for the start_mpm.sh script to be entered in the GDB debugger field:

   

6. Specify the connection to the target system on the Connection sub-tab:

   

The host system is now ready for debugging. Do not click the Debug button yet, since debugging need 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 server can be started, which launches the target program.

Target:

# Set up compiler runtime, if necessary
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/shared/lib
gdbserver-ia :10000 ~/shared/workspace/matmult/a.out

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 inside the code for the GPU and continue the application, i.e., the line containing the matrix multiplication's inner loop body: c[i][j] += a[i][k] * b[k][j];

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.