Getting Started with the Intel® Debugger for Heterogeneous Compute

This document provides startup and usage information for the Intel® Debugger for Heterogeneous Compute (Windows* targets only).

In case you need assistance installing or running this product, please visit our Get Help page at http://software.intel.com/en-us/support for support options.

For discussions, user-to-user help and general debugging information, please also join our online community at http://software.intel.com/en-us/forums/debug-solutions.

Prerequisites

Required Hardware

Two systems are required for debugging code on Intel® Processor Graphics. 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 supported target CPUs are Intel 5-th and 6-th Generation Core processors with integrated graphics. The target system setup is detailed below.

For the the host (development) side you can use a system running Windows* 7, Windows* 8.1 or Windows* 10. Windows* 10 is the recommended version for best compatibility. It is fully supported to have the host inside a virtual machine, as long as the virtual machine host is not the target system or shares physical hardware with the target system.

Both systems should be able to communicate freely with each other over TCP/IP networking, ideally within the same sub-net and same Domain Name Server.

Required Software

Both the host and the target must be running 64-bit operating systems. 32-bit versions of Windows* are not supported.

The host system requires an installation of Microsoft Visual Studio* 2015 with all the latest updates installed.

The target system should be using Windows* 10 for best results and driver compatibility. Previous versions of Windows* may run older Intel graphics drivers, which could impact functionality.

Host System Setup

The host system installation should follow the normal installation procedure of the tool suite. Unless the feature selection is customized, all required parts are installed by default.

Target System Setup

Installation on the target system requires running an additional installation package. During the installation on the host system, the target installer has been placed in the targets directory of the installation. The installer file's location is:

<install_dir>\debugger_2018\gdb\targets\idhc\install\idhc_install.msi,

where <install_dir> is the install location of Intel® System Studio.

Copy the above file to the target system and run it to start the installation. The installer will setup the debug driver, applications and libraries needed for the debugger.

It is required to restart the target system after the installation completes.

Example Project

With the setup of the systems complete, the next step is to create an example project in Microsoft Visual Studio* 2015 on the host system.

To facilitate sharing of the project between host and target system, create a shared directory:

  1. On the host system, right-click the Windows* Start button and select Command Prompt (Admin).

    An administrative command prompt is opened.

  2. In the command prompt, type the following commands to create a shared folder:
    cd \
    mkdir shared
    net share shared=c:\shared /GRANT:<your-username-here>,CHANGE
  3. On the target system, open an administrative command prompt and type:
    cd \
    mklink /D shared \\<your-host-system-name-here>\shared

    The same folder contents should appear similarly on both systems.

  4. Start Microsoft Visual Studio* 2015.
  5. Create a new project:

  6. Edit the project settings to use the shared folder:

    Leave the project settings to their defaults.

  7. Once the project is created, open the main source file, and replace the entire code with:
    /* 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 "stdafx.h"
    #include <Windows.h>
    #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[])
    {
    // For local debugging and domain users, comment out the line below.
    SetEnvironmentVariableA("IGFXDBG_OVERRIDE_CLIENT_PID", "111");
    matmult();
    return 0;
    }
  8. You now need to convert the project to using the Intel® C++ compiler and ensuring that 64-bit code is generated:

    To link and compile the project, select Build Solution from the Build menu.

    This should produce the following build output:

    1>------ Build started: Project: ConsoleApplication1, Configuration: Debug x64 ------
    1> stdafx.cpp
    1> ConsoleApplication1.cpp
    1> ConsoleApplication1.cpp
    ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

    Make sure that a "Debug x64" version is produced, since 32-bit applications are not supported, and "Release" builds will not produce debug information needed for debugging.

Debugging the Example

Configuration

By default, debugging code on Intel® Processor Graphics is disabled. Open the Options dialog in Microsoft Visual Studio* and locate the settings for Intel Compilers and Tools > Debugger > Heterogeneous Compute.

Under Enable Debugging select True. Under Auto-launch Server select False, and under Local Debugging select False.

This primes the system for the most generic use case. Refer to the following subsections for a more detailed discussion on these options.

For the Server entry, type in your target system DNS/WINS name or TCP/IP address.

Leave the TCP/IP port setting as it is for now.

Local Debugging

The term "Local Debugging" refers to a configuration where host and target system are the same. This configuration only works, if the desktop rendering is done through an additional, discrete graphics card. If you have such a system, then you should set Auto-launch Server to True and Local Debugging to True. The Server field should be localhost in this case.

Remote Debugging for Domain Users

If both the host and target system are within the Windows* Domain, it is possible to start the remote debug server automatically. This requires active sessions on both system with the same domain user account.

If this matches your environment, then you should set Auto-launch Server to True and Local Debugging to False. The Server field should be the DNS/WINS name of the target system.

Generic Remote Debugging

The most generic case requires that the debug server gets launched manually on the target system. This works in all configurations, regardless of same system debugging or domain users.

Set Auto-launch Server to False. The Server field should be the DNS/WINS name of the target system.

The important step for this configuration is to start the debug server manually on the target system.

On the target system, press Windows-Key+R to open the Run dialog. Enter the following command:

"C:\Program Files\Intel\Debugger for Heterogeneous Compute\target\bin\launch_gdbserver.bat" 2530 111

A new console application is started, displaying:

Note: make sure to set the following env var _before_ launching your host application:
set IGFXDBG_OVERRIDE_CLIENT_PID=111
Executing: C:\Program Files\Intel\Debugger for Heterogeneous Compute\target\bin\gdbserver.exe :2530 --attach 111
Started gdbserver, listening on localhost:2530

Note

  • The 2530 must match the TCP/IP port number from the options page.
  • The 111 must match the value set by the call to
    SetEnvironmentVariableA("IGFXDBG_OVERRIDE_CLIENT_PID", "111");

    in the example project.

These numbers can be changed, but need to match.

Start Debugging

Once the configuration is complete, the final step is to configure the project for remote debugging and set up the Microsoft Visual Studio* remote monitor.

You can skip this step if local debugging is possible through another discrete graphics card.

  1. Follow the instructions to set up remote debugging for Microsoft Visual Studio* 2015 on the target system: https://msdn.microsoft.com/en-us/library/y7f5zaaa.aspx
  2. Ensure that you use the x64 version of msvsmon.exe.
  3. On the host system, within Microsoft Visual Studio*, open the project properties and select Debugging under Configuration Properties.
  4. Under Debugger to launch: select the Remote Windows Debugger.
  5. Under Remote Command, enter $(TargetPath).
  6. Fill in the Remote Server Name with the target's DNS/WINS name.

You can now start debugging:

  1. Set a breakpoint within the main() function on the call to matmult() to stop there, prior to any offloaded code being executed.
  2. Set a breakpoint on line 40, c[i][j] += a[i][k] * b[k][j]; (the innermost calculation of the nested loops). Once this breakpoint is hit, you are debugging code on the graphics unit.
  3. Continue to step around, exploring other threads running the same code.
  4. Finally, remove all breakpoints and set a new breakpoint in the code marked as CPU code on any of the printf statements. Once this breakpoint is hit, the execution is back on the CPU.
  5. Remove all breakpoints and exit the debugger.

Documentation and Resources

Document Description

Release Notes for Windows* 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

有关编译器优化的更完整信息,请参阅优化通知