Debug parts of the code that gets executed on an Intel® integrated GPU applications remotely. The debugger runs on a host system and a debug agent (gdbserver-igfx) runs on the target system.

There are two options:

  • Use the command line version of the debugger. Start the debugger with the command gdb-igfx.
  • Use the Eclipse* IDE plugin. This works only for offload enabled applications.

Setup for CentOS* 7


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

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:


    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.

    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.


    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:


    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:


    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 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 script, if a newer kernel version already exists on the target system. In that case install the kernel rpm packages on the target using:


    sudo rpm -i --oldpackage rpmbuild/RPMS/x86_64/kernel-3.10.0- rpmbuild/RPMS/x86_64/kernel-devel-3.10.0-

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


    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.


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

  8. Then install them on the 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
    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.


    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.


    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.


    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/ intel64

    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]);
    int main(int argc, char *argv[])
    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 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.

Using the Debugger

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.


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


CentOS* 7 has a firewall enabled by default. If there is any problem with connections between the debugger and the debug server (from host to target) ensure the ports are opened in the firewall. Alternatively, disable the firewall.

Training and Documentation



GDB Manual

Contains descriptions of the GNU* Debugger (GDB) functions and interfaces including Intel-extended features for the Intel® Debugger for Heterogeneous Compute
Intel® Parallel Studio XE 2017 Composer Edition C++ - Debug Solutions Release Notes Release Notes for debugging with the Intel® Parallel Studio XE.

Intel® Parallel Studio XE

Intel® Parallel Studio XE product page. See this page for support and online documentation.
Para obter informações mais completas sobre otimizações do compilador, consulte nosso aviso de otimização.