Getting Started with the Intel® Debugger for Heterogenous Compute 2018 for Linux* OS

The Intel® Debugger for Heterogeneous Compute is a tool to 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

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 for Linux* Host GNU* Project Debugger (GDB).

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 SelectionConfigure networking under Network & HostnameCreate 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_2018/gdb/targets/idhc/install to shared directory.

    Host:

    cp /opt/intel/debugger_2018/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

Assumed for this setup is a standard installation of CentOS* 7.1 as a desktop system with development tools installed.

  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, the shared directory on the target system is used. 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: /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 preceding 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: /home/user/shared/workspace/matmult/a.out.
  4. Select Disable auto build. 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.

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.

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 usual. To stop in any code on the GPU, insert a breakpoint inside the code for the GPU and continue the application, this means, 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.

Troubleshooting

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.

Documentation and Resources

Document Description
GDB Manual

Contains descriptions of the GNU* Debugger (GDB) functions and interfaces including Intel-extended features for the Intel® Debugger for Heterogeneous Compute

Release Notes for Linux* Host GNU* Project Debugger (GDB)

Contains the most up-to-date information about the product, including:

  • Overview information (including new features and product contents)
  • System requirements (hardware and software requirements for installing and using the product)
  • Known limitations
  • Technical support (links to contacts for reporting problems and getting support)

Intel® System Studio product page Intel® System Studio product page. See this page for support and online documentation.

Legal Information

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest forecast, schedule, specifications and roadmaps. The products and services described may contain defects or errors known as errata which may cause deviations from published specifications. Current characterized errata are available on request.

Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

© Intel Corporation

Para obtener información más completa sobre las optimizaciones del compilador, consulte nuestro Aviso de optimización.