Debugging Intel® Xeon Phi™ Applications on Linux* Host

Contents

• Introduction
• Debug Solution for Intel® MIC
  • How to get it?
  • Why use GNU* GDB provided by Intel?
  • Why is Intel providing a Command Line and Eclipse* IDE Integration?
  • Deprecation Notice
• Features
  • Register and Instruction Set Support
  • Data Race Detection
• Debugging on Command Line
  • Debugging Natively
  • Debugging Remotely
  • Debugging Remotely with PDBX
• Debugging with Eclipse* IDE
  • Pre-requisites
  • Install Plug-in for Offload Debugging
  • Configure Offload Debugging
  • Start Offload Debugging
  • Additional Requirements for Offload Debugging
  • Configure Native Debugging
  • Build Native Application for the Coprocessor
  • Start Native Debugging
• Documentation
• Errata

Introduction

Intel® Xeon Phi™ coprocessor is a product based on the Intel® Many Integrated Core Architecture (Intel® MIC). Intel® offers a debug solution for this architecture that can debug applications running on an Intel® Xeon Phi™ coprocessor.

There are many reasons for the need of a debug solution for Intel^® MIC. Some of the most important ones are the following:

• Developing native Intel^® MIC applications is as easy as for IA-32 or Intel^® 64 hosts. In most cases they just need to be cross-compiled (-mmic).
  Yet, Intel^® MIC Architecture is different to host architecture. Those differences could unveil existing issues. Also, incorrect tuning for Intel^® MIC could introduce new issues (e.g. alignment of data, can an application handle more than hundreds of threads?, efficient memory consumption?, etc.)
• Developing offload enabled applications induces more complexity as host and coprocessor share workload.
• General lower level analysis, tracing execution paths, learning the instruction set of Intel^® MIC Architecture, …

Debug Solution for Intel® MIC

For Linux* host, Intel offers a debug solution for Intel® MIC which is based on GNU* GDB. It can be used on the command line for both host and coprocessor. There is also an Eclipse* IDE integration that eases debugging of applications with hundreds of threads thanks to its user interface. It also supports debugging offload enabled applications.

How to get it?

There are currently two ways to obtain Intel’s debug solution for Intel® MIC Architecture on Linux* host:

• Intel^® Manycore Platform Software Stack (MPSS):
  http://software.intel.com/en-us/articles/intel-manycore-platform-software-stack-mpss
  (currently MPSS 3.2.3 for Linux*)
  First version became available with MPSS 2.1.
• Intel^® Composer XE (for C/C++ or Fortran):
  http://software.intel.com/en-us/intel-composer-xe
  It requires at least Intel^® Composer XE 2013 SP1 or later.

Both packages contain the same debug solutions for Intel® MIC Architecture!

Why use GNU* GDB provided by Intel?

• Capabilities are released back to GNU* community
• Latest GNU* GDB versions in future releases
• Improved C/C++ & Fortran support thanks to Project Archer and contribution through Intel
• Increased support for Intel^® architecture (esp. Intel^® MIC)
• Eclipse* IDE integration for C/C++ and Fortran
• Additional debugging capabilities – more later

Why is Intel providing a Command Line and Eclipse* IDE Integration?

The command line with GNU* GDB has the following advantages:

• Well known syntax
• Lightweight: no dependencies
• Easy setup: no project needs to be created
• Fast for debugging hundreds of threads
• Can be automatized/scripted

Using the Eclipse* IDE provides more features:

• Comfortable user interface
• Most known IDE in the Linux* space
• Use existing Eclipse* projects
• Simple integration of the Intel enhanced GNU* GDB
• Works also with Photran* plug-in to support Fortran
• Supports debugging of offload enabled applications
  (not supported by command line)

Deprecation Notice

Intel® Debugger is deprecated (incl. Intel® MIC Architecture support):

• Intel® Debugger for Intel® MIC Architecture was only available in Composer XE 2013 & 2013 SP1
• Intel® Debugger is not part of Intel® Composer XE 2015 anymore

Users are advised to use GNU* GDB that comes with Intel® Composer XE 2013 SP1 and later!

You can provide feedback via either your Intel® Premier account (http://premier.intel.com) or via the Debug Solutions User Forum (http://software.intel.com/en-us/forums/debug-solutions/).

Features

Intel’s GNU* GDB, starting with version 7.5, provides additional extensions that are available on the command line:

• Support for Intel^® Many Integrated Core Architecture (Intel^® MIC Architecture):
  Displays registers (zmmX & kX) and disassembles the instruction set
• Support for Intel^® Transactional Synchronization Extensions (Intel^® TSX):
  Helpers for Restricted Transactional Memory (RTM) model
  (only for host)
• Data Race Detection (pdbx):
  Detect and locate data races for applications threaded using POSIX* thread (pthread) or OpenMP* models
• Branch Trace Store (btrace):
  Record branches taken in the execution flow to backtrack easily after events like crashes, signals, exceptions, etc.
  (only for host)
• Pointer Checker:
  Assist in finding pointer issues if compiled with Intel^® C++ Compiler and having Pointer Checker feature enabled
  (only for host)
• Register support for Intel^® Memory Protection Extensions (Intel^® MPX) and Intel^® Advanced Vector Extensions 512 (Intel^® AVX-512):
  Debugger is already prepared for future generations

The features for Intel® MIC highlighted above are described in the following.

Register and Instruction Set Support

Compared to Intel® architecture on host systems, Intel® MIC Architecture comes with a different instruction and register set. Intel’s GNU* GDB comes with transparently integrated support for those.  Use is no different than with host systems, e.g.:

• Disassembling of instructions:
  

  
  		(gdb) disassemble $pc, +10
  
  		Dump of assembler code from 0x11 to 0x24:
  
  		0x0000000000000011 <foobar+17>: vpackstorelps %zmm0,-0x10(%rbp){%k1}
  
  		0x0000000000000018 <foobar+24>: vbroadcastss -0x10(%rbp),%zmm0
  
  		⁞
  
  		

  
  
  In the above example the first ten instructions are disassembled beginning at the instruction pointer ($pc). Only first two lines are shown for brevity. The first two instructions are Intel® MIC specific and their mnemonic is correctly shown.
   
• Listing of mask (kX) and vector (zmmX) registers:
  

  
  		(gdb) info registers zmm
  
  		k0   0x0  0
  
  		     ⁞
  
  		zmm31 {v16_float = {0x0 <repeats 16 times>},
  
  		      v8_double = {0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0},
  
  		      v64_int8 = {0x0 <repeats 64 times>},
  
  		      v32_int16 = {0x0 <repeats 32 times>},
  
  		      v16_int32 = {0x0 <repeats 16 times>},
  
  		      v8_int64 = {0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0},
  
  		      v4_uint128 = {0x0, 0x0, 0x0, 0x0}}
  
  		

  
  
  Also registers have been extended by kX (mask) and zmmX (vector) register sets that come with Intel® MIC.

If you use the Eclipse* IDE integration you’ll get the same information in dedicated windows:

• Disassembling of instructions:
  
• Listing of mask (kX) and vector (zmmX) registers:
  

Data Race Detection

A quick excursion about what data races are:

• A data race happens…
  If at least two threads/tasks access the same memory location w/o synchronization and at least one thread/task is writing.
• Example:
  Imaging the two functions thread1()& thread2() are executed concurrently by different threads.
  
  

  
  		int a = 1;
  
  		int b = 2;
  
  		                                         | t
  
  		int thread1() {      int thread2() {     | i
  
  		  return a + b;        b = 42;           | m
  
  		}                    }                   | e
  
  		                                         v
  
  		

  
  
  Return value of thread1() depends on timing: 3 vs. 43!
  This is one (trivial) example of a data race.

What are typical symptoms of data races?

• Data race symptoms:
  • Corrupted results
  • Run-to-run variations
  • Corrupted data ending in a crash
  • Non-deterministic behavior
• Solution is to synchronize concurrent accesses, e.g.:
  • Thread-level ordering (global synchronization)
  • Instruction level ordering/visibility (atomics)
    Note:
    Race free but still not necessarily run-to-run reproducible results!
  • No synchronization: data races might be acceptable

Intel’s GNU* GDB data race detection can help to analyze correctness.

How to detect data races?

• Prepare to detect data races:
  • Only supported with Intel^® C++/Fortran Compiler (part of Intel^® Composer XE):
    Compile with -debug parallel (icc, icpc or ifort)
    Only objects compiled with-debug parallel are analyzed!
  • Optionally, add debug information via –g
• Enable data race detection (PDBX) in debugger:
  

  
  		(gdb) pdbx enable
  
  		(gdb) c
  
  		data race detected
  
  		1: write shared, 4 bytes from foo.c:36
  
  		3: read shared, 4 bytes from foo.c:40
  
  		Breakpoint -11, 0x401515 in L_test_..._21 () at foo.c:36
  
  		*var = 42; /* bp.write */
  
  		

Data race detection requires an additional library libpdbx.so.5:

• Keeps track of the synchronizations
• Part of Intel® C++ & Fortran Compiler
• Copy to coprocessor if missing
  (found at <composer_xe_root>/compiler/lib/mic/libpdbx.so)

Supported parallel programming models:

• OpenMP*
• POSIX* threads

Data race detection can be enabled/disabled at any time

• Only memory access are analyzed within a certain period
• Keeps memory footprint and run-time overhead minimal

There is finer grained control for minimizing overhead and selecting code sections to analyze by using filter sets.

More control about what to analyze with filters:

• Add filter to selected filter set, e.g.:
  

  
  		(gdb) pdbx filter line foo.c:36
  
  		(gdb) pdbx filter code 0x40518..0x40524
  
  		(gdb) pdbx filter var shared
  
  		(gdb) pdbx filter data 0x60f48..0x60f50
  
  		(gdb) pdbx filter reads # read accesses
  
  		

  
  Those define various filter on either instructions by specifying source file and line or the addresses (range), or variables using symbol names or addresses (range) respectively. There is also a filter to only report accesses that use (read) data in case of a data race.
   
• There are two basic configurations, that are exclusive:
   
  • Ignore events specified by filters (default behavior)
    

    
    				(gdb) pdbx fset suppress
    
    				

  • Ignore events not specified by filters
    

    
    				(gdb) pdbx fset focus
    
    				

    
    The first one defines a white list, whilst the latter one blacklists code or data sections that should not be analyzed.
     
• Get debug command help
  

  
  		(gdb) help pdbx
  
  		

  
  This command will provide additional help on the commands.

Use cases for filters:

• Focused debugging, e.g. debug a single source file or only focus on one specific memory location.
• Limit overhead and control false positives. Detection involves some runtime and memory overhead at runtime. The more filters narrow down the scope of analysis, the more the overhead will be reduced. This can also be used to exclude false positives. Those can occur if real data races are detected, but without any impact on application’s correctness by design (e.g. results of multiple threads don’t need to be globally stored in strict order).
• Exclude 3rd party code for analysis

Some additional hints using PDBX:

• Optimized code (symptom):
  

  
  		(gdb) run
  
  		data race detected
  
  		1: write question, 4 bytes from foo.c:36
  
  		3: read question, 4 bytes from foo.c:40
  
  		Breakpoint -11, 0x401515 in foo () at foo.c:36
  
  		*answer = 42;
  
  		(gdb)
  
  		

  
   
• Incident has to be analyzed further:
  • Remember: data races are reported on memory objects
  • If symbol name cannot be resolved: only address is printed
     
• Recommendation:
  Unoptimized code (-O0) makes it easier to understand due to removed/optimized away temporaries, etc.
   
• Reported data races appear to be false positives:
  • Not all data races are bad… user intended?
  • OpenMP*: Distinct parallel sections using the same variable (same stack frame) can result in false positives

Note:
PDBX is not available for Eclipse* IDE and will only work for remote debugging of native coprocessor applications. See section Debugging Remotely with PDBX for more information on how to use it.

Debugging on Command Line

There are multiple versions available:

• Debug natively on Intel^® Xeon Phi™ coprocessor
• Execute GNU* GDB on host and debug remotely

Debug natively on Intel® Xeon Phi™ coprocessor
This version of Intel’s GNU* GDB runs natively on the coprocessor. It is included in Intel® MPSS only and needs to be made available on the coprocessor first in order to run it. Depending on the MPSS version it can be found at the provided location:

• MPSS 2.1: /usr/linux-k1om-4.7/linux-k1om/usr/bin/gdb
• MPSS 3.[1|2]: included in gdb-7.5+mpss3.*.k1om.rpm as part of package mpss-3.*-k1om.tar
  (for MPSS 3.1.2, please see Errata, for MPSS 3.1.4 use mpss-3.1.4-k1om-gdb.tar)
  
  For MPSS 3.[1|2] the coprocessor native GNU* GDB requires debug information from some system libraries for proper operation. Please see Errata for more information.

Execute GNU* GDB on host and debug remotely
There are two ways to start GNU* GDB on the host and debug remotely using GDBServer on the coprocessor:

• Intel^® MPSS:
  • MPSS 2.1: /usr/linux-k1om-4.7/bin/x86_64-k1om-linux-gdb
  • MPSS 3.[1|2]: <mpss_root>/sysroots/x86_64-mpsssdk-linux/usr/bin/k1om-mpss-linux/k1om-mpss-linux-gdb
  • GDBServer:
    /usr/linux-k1om-4.7/linux-k1om/usr/bin/gdbserver
    (same path for MPSS 2.1 & 3.[1|2])
• Intel^® Composer XE:
  • Source environment to start GNU* GDB:
    

    
    				$ source debuggervars.[sh|csh]
    
    				$ gdb-mic
    
    				

  • GDBServer:
    <composer_xe_root>/debugger/gdb/target/mic/bin/gdbserver

The sourcing of the debugger environment is only needed once. If you already sourced the according compilervars.[sh|csh] script you can omit this step and gdb-mic should already be in your default search paths.

Attention: Do not mix GNU* GDB & GDBServer from different packages! Always use both from either Intel® MPSS or Intel® Composer XE!

Debugging Natively

1. Make sure GNU* GDB is already on the target by:

• Copy manually, e.g.:
  

  
  		$ scp /usr/linux-k1om-4.7/linux-k1om/usr/bin/gdb mic0:/tmp
  
  		

• Add to the coprocessor image (see Intel® MPSS documentation)
   

1. Run GNU* GDB on the Intel® Xeon Phi™ coprocessor, e.g.:
   

   
   		$ ssh –t mic0 /tmp/gdb
   
   		

   
    
2. Initiate debug session, e.g.:

• Attach:
  

  
  		(gdb) attach <pid>

  
  <pid> is PID on the coprocessor
• Load & execute:
  

  
  		(gdb) file <path_to_application>

  
  <path_to_application> is path on coprocessor

Some additional hints:

• If native application needs additional libraries:
  Set $LD_LIBRARY_PATH, e.g. via:
  

  
  		(gdb) set env LD_LIBRARY_PATH=/tmp/
  
  		

  
  …or set the variable before starting GDB
   
• If source code is relocated, help the debugger to find it:
  

  
  		(gdb) set substitute-path <from> <to>

  
  Change paths from <from> to<to>. You can relocate a whole source (sub-)tree with that.

Debugging is no different than on host thanks to a real Linux* environment on the coprocessor!

Debugging Remotely

1. Copy GDBServer to coprocessor, e.g.:
   

   
   		$ scp <composer_xe_root>/debugger/gdb/target/mic/bin/gdbserver mic0:/tmp

   
   During development you can also add GDBServer to your coprocessor image!
    
2. Start GDB on host, e.g.:
   

   
   		$ source debuggervars.[sh|csh]
   
   		$ gdb-mic
   
   		

   
   
   Note:
   There is also a version named gdb-ia which is for IA-32/Intel® 64 only!
    
3. Connect:
   

   
   		(gdb) target extended-remote | ssh -T mic0 /tmp/gdbserver --multi –
   
   		

   
    
4. Set sysroot from MPSS installation, e.g.:
   

   
   		(gdb) set sysroot /opt/mpss/3.1.4/sysroots/k1om-mpss-linux/
   
   		

   
   If you do not specify this you won't get debugger support for system libraries.
    
5. Debug:

• Attach:
  

  
  		(gdb) file <path_to_application>
  
  		(gdb) attach <pid>

  
  <path_to_application> is path on host, <pid> is PID on the coprocessor
• Load & execute:
  

  
  		(gdb) file <path_to_application>
  
  		(gdb) set remote exec-file <remote_path_to_application>

  
  <path_to_application> is path on host, <remote_path_to_application> is path on the coprocessor

Some additional hints:

• If remote application needs additional libraries:
  Set $LD_LIBRARY_PATH, e.g. via:
  

  
  		(gdb) target extended-remote | ssh mic0 LD_LIBRARY_PATH=/tmp/ /tmp/gdbserver --multi -
  
  		

• If source code is relocated, help the debugger to find it:
  

  
  		(gdb) set substitute-path <from> <to>

  
  Change paths from <from> to <to>. You can relocate a whole source (sub-)tree with that.
   
• If libraries have different paths on host & target, help the debugger to find them:
  

  
  		(gdb) set solib-search-path <lib_paths>

  
  <lib_paths> is a colon separated list of paths to look for libraries on the host

Debugging is no different than on host thanks to a real Linux* environment on the coprocessor!

Debugging Remotely with PDBX

PDBX has some pre-requisites that must be fulfilled for proper operation. Use pdbx check command to see whether PDBX is working:

1. First step:
   

   
   		(gdb) pdbx check
   
   		checking inferior...failed.
   
   		

   
   
   Solution:
   Start a remote application (inferior) and hit some breakpoint (e.g. b main& run)
    
2. Second step:
   

   
   		(gdb) pdbx check
   
   		checking inferior...passed.
   
   		checking libpdbx...failed.
   
   		

   
   
   Solution:
   Use set solib-search-path <lib_paths> to provide the path of libpdbx.so.5 on the host.
    
3. Third step:
   

   
   		(gdb) pdbx check
   
   		checking inferior...passed.
   
   		checking libpdbx...passed.
   
   		checking environment...failed.
   
   		

   
   
   Solution:
   Set additional environment variables on the target for OpenMP*. Those need to be set with starting GDBServer (similar to setting $LD_LIBRARY_PATH).

• $INTEL_LIBITTNOTIFY32=""
• $INTEL_LIBITTNOTIFY64=""
• $INTEL_ITTNOTIFY_GROUPS=sync

Debugging with Eclipse* IDE

Intel offers an Eclipse* IDE debugger plug-in for Intel® MIC that has the following features:

• Seamless debugging of host and coprocessor
• Simultaneous view of host and coprocessor threads
• Supports multiple coprocessor cards
• Supports both C/C++ and Fortran
• Support of offload extensions (auto-attach to offloaded code)
• Support for Intel^® Many Integrated Core Architecture (Intel^® MIC Architecture): Registers & Disassembly

The plug-in is part of both Intel® MPSS and Intel® Composer XE.

Pre-requisites

In order to use the provided plug-in the following pre-requisites have to be met:

• Supported Eclipse* IDE version:
  • 4.2 with Eclipse C/C++ Development Tools (CDT) 8.1 or later
  • 3.8 with Eclipse C/C++ Development Tools (CDT) 8.1 or later
  • 3.7 with Eclipse C/C++ Development Tools (CDT) 8.0 or later

We recommend: Eclipse* IDE for C/C++ Developers (4.2)

• Java* Runtime Environment (JRE) 6.0 or later
• For Fortran optionally Photran* plug-in
• Remote System Explorer (aka. Target Management) to debug native coprocessor applications
• Only for plug-in from Intel^® Composer XE, source debuggervars.[sh|csh] for Eclipse* IDE environment!

Install Intel® C++ Compiler plug-in (optional):
Add plug-in via “Install New Software…”:

This Plug-in is part of Intel^® Composer XE (<composer_xe_root>/eclipse_support/cdt8.0/). It adds Intel® C++ Compiler support which is not mandatory for debugging. For Fortran the counterpart is the Photran* plug-in. These plug-ins are recommended for the best experience.

Note:
Uncheck “Group items by category”, as the list will be empty otherwise!

Install Plug-in for Offload Debugging

Add plug-in via “Install New Software…”:

Plug-in is part of:

• Intel^® MPSS:
  • MPSS 2.1: <mpss_root>/eclipse_support/
  • MPSS 3.[1|2]: /usr/share/eclipse/mic_plugin/
• Intel^® Composer XE:<composer_xe_root>/debugger/cdt/

Configure Offload Debugging

• Create a new debug configuration for “C/C++ Application”
• Click on “Select other…” and select MPM (DSF) Create Process Launcher:
  The “MPM (DSF) Create Process Launcher” needs to be used for our plug-in. Please note that this instruction is for both C/C++ and Fortran applications! Even though Photran* is installed and a “Fortran Local Application” entry is visible (not in the screenshot above!) don’t use it. It is not capable of using MPM.
   
• In “Debugger” tab specify MPM script of Intel’s GNU* GDB:
  • Intel^® MPSS:
    • MPSS 2.1: <mpss_root>/mpm/bin/start_mpm.sh
    • MPSS 3.[1|2]: /usr/bin/start_mpm.sh
      (for MPSS 3.1.1, 3.1.2 or 3.1.4, please see Errata)
  • Intel^® Composer XE:
    <composer_xe_root>/debugger/mpm/bin/start_mpm.sh
    
    Here, you finally add Intel’s GNU* GDB for offload debugging (using MPM (DSF)). It is a script that takes care of setting up the full environment needed. No further configuration is required (e.g. which coprocessor cards, GDBServer & ports, IP addresses, etc.); it works fully automatic and transparent.

Start Offload Debugging

Debugging offload enabled applications is not much different than applications native for the host:

• Create & build an executable with offload extensions (C/C++ or Fortran)
  • Use offload pragmas/directives or OpenMP* 4.0
  • Use MYO (_Cilk_shared, _Cilk_spawn, …)
    
    For getting started examples, please see:
    • <composer_xe_root>/Samples/en_US/[C++|Fortran]/mic_samples
    • http://software.intel.com/en-us/articles/offload-programming-fortran-and-c-code-examples
    • Or search via Intel® Developer Zone’s Content Library:
      http://software.intel.com/en-us/search/site
       
• Don’t forget to add debug information (-g) and reduce optimization level if possible (-O0)
• Start debug session:
  • Host & target debugger will work together seamlessly
  • All threads from host & target are shown and described
  • Debugging is same as used from Eclipse* IDE

This is an example (Fortran) of what offload debugging looks like. On the left side we see host & mic0 threads running. One thread (11) from the coprocessor has hit the breakpoint we set inside the loop of the offloaded code. Run control (stepping, continuing, etc.), setting breakpoints, evaluating variables/memory, … work as they used to.

Additional Requirements for Offload Debugging

For debugging offload enabled applications additional environment variables need to be set:

• Intel® MPSS 3.[1|2]:
  AMPLXE_COI_DEBUG_SUPPORT=TRUE
  MYO_WATCHDOG_MONITOR=-1
   
• Intel® MPSS 2.1:
  COI_SEP_DISABLE=FALSE
  MYO_WATCHDOG_MONITOR=-1

Set those variables before starting Eclipse* IDE!

Those are currently needed but might become obsolete in the future. Please be aware that the debugger cannot and should not be used in combination with Intel® VTune™ Amplifier XE. Hence disabling SEP (as part of Intel® VTune™ Amplifier XE) is valid. The watchdog monitor must be disabled because a debugger can stop execution for an unspecified amount of time. Hence the system watchdog might assume that a debugged application, if not reacting anymore, is dead and will terminate it. For debugging we do not want that.

Note:
Do not set those variables for a production system!

For Intel® MPSS 3.2 and later:
MYO debug libraries are no longer installed with Intel MPSS 3.2 by default. This is a change from earlier Intel MPSS versions. Users must install the MYO debug libraries manually in order to debug MYO enabled applications using the Eclipse plug-in for offload debugging. For Intel MPSS 3.2 (and later) the MYO debug libraries can be found in the package mpss-myo-dbg-* which is included in the mpss-*.tar file.

MPSS 3.2 and later does not support offload debugging with Intel® Composer XE 2013 SP1, please see Errata for more information!

Configure Native Debugging

Configure Remote System Explorer
To debug native coprocessor applications we need to configure the Remote System Explorer (RSE).

Note:
Before you continue, make sure SSH works (e.g. via command line). You can also specify different credentials (user account) via RSE and save the password.

The basic steps are quite simple:

1. Show the Remote System window:
   Menu Window->Show View->Other…
   Select: Remote Systems->Remote Systems
    
2. Add a new system node for each coprocessor:
   
   Context menu in window Remote Systems: New Connection…

• Select Linux, press Next>
• Specify hostname of the coprocessor (e.g. mic0), press Next>
• In the following dialogs select:
  • ssh.files
  • processes.shell.linux
  • ssh.shells
  • ssh.terminals

Repeat this step for each coprocessor!

Transfer GDBServer
Transfer of the GDBServer to the coprocessor is required for remote debugging. We choose /tmp/gdberver as target on the coprocessor here (important for the following sections).

Transfer the GDBServer to the coprocessor target, e.g.:

	$ scp <composer_xe_root>/debugger/gdb/target/mic/bin/gdbserver mic0:/tmp

During development you can also add GDBServer to your coprocessor image!

Note:
See section Debugging on Command Line above for the correct path of GDBServer, depending on the chosen package (Intel^® MPSS or Intel^® Composer XE)!

Debug Configuration

To create a new debug configuration for a native coprocessor application (here: native_c++) create a new one for C/C++ Remote Application.

Set Connection to the coprocessor target configured with RSE before (here: mic0).

Specify the remote path of the application, wherever it was copied to (here: /tmp/native_c++). We’ll address how to manually transfer files later.

Set the flag for “Skip download to target path.” if you don’t want the debugger to upload the executable to the specified path. This can be meaningful if you have complex projects with external dependencies (e.g. libraries) and don’t want to manually transfer the binaries.
(for MPSS 3.1.2 or 3.1.4, please see Errata)

Note that we use C/C++ Remote Application here. This is also true for Fortran applications because there’s no remote debug configuration section provided by the Photran* plug-in!

In Debugger tab, specify the provided Intel GNU* GDB for Intel® MIC (here: gdb-mic).

In the above example, set sysroot from MPSS installation in .gdbinit, e.g.:

	set sysroot /opt/mpss/3.1.4/sysroots/k1om-mpss-linux/

	

You can use .gdbinit or any other command file that should be loaded before starting the debugging session. If you do not specify this you won't get debugger support for system libraries.

Note:
See section Debugging on Command Line above for the correct path of GDBServer, depending on the chosen package (Intel^® MPSS or Intel^® Composer XE)!

In Debugger/Gdbserver Settings tab, specify the uploaded GDBServer (here: /tmp/gdbserver).

Build Native Application for the Coprocessor

Configuration depends on the installed plug-ins. For C/C++ applications we recommend to install the Intel® C++ Compiler XE plug-in that comes with Composer XE. For Fortran, install Photran* (3^rd party) and select the Intel® Fortran Compiler manually.

Make sure to use the debug configuration and provide options as if debugging on the host (-g). Optionally, disabling optimizations by –O0 can make the instruction flow comprehendible when debugging.

The only difference compared to host builds is that you need to cross-compile for the coprocessor: Use the –mmic option, e.g.:

After configuration, clean your build. This is needed because Eclipse* IDE might not notice all dependencies. And finally, build.

Note:
That the configuration dialog shown only exists for the Intel® C++ Compiler plug-in. For Fortran, users need to install the Photran* plug-in and switch the compiler/linker to ifort by hand plus adding -mmic manually. This has to be done for both the compiler & linker!

Start Native Debugging

Transfer the executable to the coprocessor, e.g.:

• Copy manually  (e.g. via script on the terminal)
• Use the Remote Systems window (RSE) to copy files from host and paste to coprocessor target (e.g. mic0):
  
  Select the files from the tree (Local Files) and paste them to where you want them on the target to be (e.g. mic0)
   
• Use NFS to mirror builds to coprocessor (no need for update)
• Use debugger to transfer (see earlier)

Note:
It is crucial that the executable can be executed on the coprocessor. In some cases the execution bits might not be set after copying.

Start debugging using the C/C++ Remote Application created in the earlier steps. It should connect to the coprocessor target and launch the specified application via the GDBServer. Debugging is the same as for local/host applications.

Note:
This works for coprocessor native Fortran applications the exact same way!

Documentation

More information can be found in the official documentation:

• Intel^® MPSS:
  • MPSS 2.1:
    <mpss_root>/docs/gdb/gdb.pdf
    <mpss_root>/eclipse_support/README-INTEL
  • MPSS 3.[1|2]:
    not available yet (please see Errata)
• Intel^® Composer XE:
  <composer_xe_root>/Documentation/[en_US|ja_JP]/debugger/gdb/gdb.pdf
  <composer_xe_root>/Documentation/[en_US|ja_JP]/debugger/gdb/eclmigdb_config_guide.pdf

The PDF gdb.pdf is the original GNU* GDB manual for the base version Intel ships, extended by all features added. So, this is the place to get help for new commands, behavior, etc.
README-INTEL from Intel® MPSS contains a short guide how to install and configure the Eclipse* IDE plug-in.
PDF eclmigdb_config_guide.pdf provides an overall step-by-step guide how to debug with the command line and with Eclipse* IDE.

Using Intel^® C++ Compiler with the Eclipse* IDE on Linux*:
http://software.intel.com/en-us/articles/intel-c-compiler-for-linux-using-intel-compilers-with-the-eclipse-ide-pdf/
The knowledgebase article (Using Intel® C++ Compiler with the Eclipse* IDE on Linux*) is a step-by step guide how to install, configure and use the Intel® C++ Compiler with Eclipse* IDE.

Errata

• With the recent switch from MPSS 2.1 to 3.1 some packages might be incomplete or missing. Future updates will add improvements. Currently, documentation for GNU* GDB is missing.
   
• For MPSS 3.1.2 and 3.1.4 the respective package mpss-3.1.[2|4]-k1om.tar is missing. It contains binaries for the coprocessor, like the native GNU* GDB for the coprocessor. It also contains /usr/libexec/sftp-server which is needed if you want to debug native applications on the coprocessor and require Eclipse* IDE to transfer the binary automatically. As this is missing you need to transfer the files manually (select “Skip download to target path.” in this case).
  As a workaround, you can use mpss-3.1.1-k1om.tar from MPSS 3.1.1 and install the binaries from there. If you use MPSS 3.1.4, the native GNU* GDB is available separately via mpss-3.1.4-k1om-gdb.tar.
   
• With MPSS 3.1.1, 3.1.2 or 3.1.4 the script <mpss_root>/mpm/bin/start_mpm.sh uses an incorrect path to the MPSS root directory. Hence offload debugging is not working. You can fix this by creating a symlink for your MPSS root, e.g. for MPSS 3.1.2:
  
  $ ln -s /opt/mpss/3.1.2 /opt/mpss/3.1
  
  Future versions of MPSS will correct this. This workaround is not required if you use the start_mpm.sh script from the Intel(R) Composer XE package.
   
• For MPSS 3.[1|2] the coprocessor native GNU* GDB requires debug information from some system libraries for proper opteration.
  Beginning with MPSS 3.1, debug information for system libraries is not installed on the coprocessor anymore. If the coprocessor native GNU* GDB is executed, it will fail when loading/continuing with a signal (SIGTRAP).
  Current workaround is to copy the .debug folders for the system libraries to the coprocessor, e.g.:
  
  $ scp -r /opt/mpss/3.1.2/sysroots/k1om-mpss-linux/lib64/.debug root@mic0:/lib64/
   
• MPSS 3.2 and 3.2.1 do not support offload debugging with Intel® Composer XE 2013 SP1.
  Offload debugging with the Eclipse plug-in from Intel® Composer XE 2013 SP1 does not work with Intel MPSS 3.2 and 3.2.1. A configuration file which is required for operation by the Intel Composer XE 2013 SP1 package has been removed with Intel MPSS 3.2 and 3.2.1. Previous Intel MPSS versions are not affected. Intel MPSS 3.2.3 fixes this problem (there is no version Intel MPSS 3.2.2!).