Debugging Intel® Xeon Phi™ Applications on Linux* Host

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® Parallel Studio XE 2016 (for C/C++ or Fortran):
https://software.intel.com/en-us/intel-parallel-studio-xe
Intel^® Manycore Platform Software Stack (MPSS):
http://software.intel.com/en-us/articles/intel-manycore-platform-software-stack-mpss
(currently MPSS 3.5.2 for Linux* [3.4.5 for long term support])
First version became available with MPSS 2.1.

Both packages contain debug solutions for Intel® MIC Architecture!

Attention:
Never mix debugging tools from Intel® Parallel Studio XE with the ones from Intel® Manycore Platform Software Stack! Use all tools from the very same package. Different packages might have different debugger versions with different feature sets.

Note:
Intel® Composer XE 2013 SP1 contains GNU* GDB 7.5. With Intel® Parallel Studio XE 2015 GNU* GDB 7.7, and with Intel® Parallel Studio XE 2015 Update 2 GNU* GDB 7.8 (host only; 7.7 for coprocessor) is available. Intel® Parallel Studio XE 2016 contains GNU* GDB 7.8 for both host & coprocessor.
MPSS versions have different versions of GNU* GDB – please check the Release Notes of the individual MPPS releases.
There has been a change in product naming: Intel® Parallel Studio XE Composer Edition is the successor of Intel® Composer XE, starting with 2015.

Why use GNU* GDB provided by Intel?

New features/improvements offered 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)
Additional debugging capabilities – more later

Latest Intel related HW support and features are provided in the debug solution from Intel!

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)

Features

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

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
And more...

The features for Intel® MIC Architecture highlighted above are described in the following.
Note that newer GNU* GDB versions with more features are already available, but those do not add anything in addition for Intel® MIC Architecture.

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

GDB data race detection points out unsynchronized data accesses. Not all of them might incur data races. It is the responsibility of the user to decide which ones are not expected and filter them (see next).
Due to technical limitations not all unsynchronized data accesses can be found, e.g.: 3rd party libraries or any object code not compiled with –debug parallel (see next).

How to detect data races?

Prepare to detect data races:
- Only supported with Intel^® C++/Fortran Compiler:
  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 <install-dir>/compilers_and_libraries/linux/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.*: included in gdb-7.*+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.* 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.*: <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.*)
Intel® Parallel Studio XE Composer Edition:
- Source environment to start GNU* GDB:
```
				$ source compilervars.[sh|csh] [ia32|intel64]

				$ gdb-mic

				
```
- GDBServer:
  <install-dir>/debugger_2016/gdb/targets/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® Parallel Studio XE Composer Edition!

Debugging Natively

Make sure GNU* GDB is already on the target by:
- Copy manually, e.g.:
  - MPSS 2.1:
```
						$ scp /usr/linux-k1om-4.7/linux-k1om/usr/bin/gdb mic0:/tmp

						
```
  - MPSS 3.*: Install gdb-7.*+mpss3.*.k1om.rpm
- Add to the coprocessor image (see Intel® MPSS documentation)

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

MPSS 2.1:
```
				$ ssh –t mic0 /tmp/gdb

				
```
MPSS 3.*:
```
				$ ssh –t mic0 /usr/bin/gdb

				
```

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

Copy GDBServer to coprocessor, e.g.:

Intel® MPSS:


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

Intel® Parallel Studio XE Composer Edition:
```
				$ scp <install-dir>/debugger_2016/gdb/targets/mic/bin/gdbserver mic0:/tmp
```
During development you can also add GDBServer to your coprocessor image!

Start GDB on host, e.g.:
```
		$ source compilervars.[sh|csh] [ia32|intel64]

		$ gdb-mic

		
```
Note:
There are also versions named gdb-ia and gdb-ia-mic which are for IA-32/Intel® 64 only!
(Only for Intel® Parallel Studio XE 2015 Update 2 Composer Edition: gdb-ia is 7.8, gdb-ia-mic is 7.7)

Connect:


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

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

First step:
```
		(gdb) pdbx check

		checking inferior...failed.

		
```
Solution:
Start a remote application (inferior) and hit some breakpoint (e.g. b main& run)
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.
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® Parallel Studio XE Composer Edition.

Pre-requisites

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

Supported Eclipse* IDE version:
- 4.5 with Eclipse C/C++ Development Tools (CDT) 8.7 or later
- 4.4 with Eclipse C/C++ Development Tools (CDT) 8.3 or later
- 4.2 & 4.3 with Eclipse C/C++ Development Tools (CDT) 8.1 or later

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

Java* Runtime Environment (JRE) 6.0 or later (7.0 for Eclipse* 4.4)
For Fortran optionally Photran* plug-in
Remote System Explorer (aka. Target Management) to debug native coprocessor applications
Only for plug-in from Intel® Parallel Studio XE Composer Edition, source compilervars.[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® Parallel Studio XE Composer Edition (<install-dir>/ide_support_2016/eclipse/compiler_xe/). 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!
In addition, it is recommended to disable checking for latest versions. If not done, installation could take unnecessarily long and newer components might be installed that did not come with the vanilla Eclipse package. Those could cause problems.

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.*: /usr/share/eclipse/mic_plugin/
Intel® Parallel Studio XE Composer Edition:<install-dir>/ide_support_2016/eclipse/gdb_xe/

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.*: /usr/bin/start_mpm.sh
    (for MPSS 3.1.1, 3.1.2 or 3.1.4, please see Errata)
- Intel® Parallel Studio XE Composer Edition:
  <install-dir>/debugger_2016/mpm/mic/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:
  - <install-dir>/compilers_and_libraries/linux/samples/en/compiler_[c|f]/psxe/mic_samples.tar.gz
  - 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 2.1:
COI_SEP_DISABLE=FALSE
MYO_WATCHDOG_MONITOR=-1
Intel® MPSS 3.*:
AMPLXE_COI_DEBUG_SUPPORT=TRUE
MYO_WATCHDOG_MONITOR=-1

Set those variables before starting Eclipse* IDE!

Those are currently needed but might become obsolete in the future.

For MPSS 2.1, please be aware that the debugger cannot and should not be used in combination with Intel® VTune™ Amplifier XE (COI_SEP_DISABLE=FALSE). Hence, disabling SEP (as part of Intel® VTune™ Amplifier XE) is valid.

For MPSS 3.*, AMPLXE_COI_DEBUG_SUPPORT=TRUE extracts K1OM object code map files from fat SOs (with host & K1OM object code) and places it under /tmp/coi_procs/<card #>/<process ID>/load_lib/ on the coprocessor. This is not only required for Intel® VTune™ Amplifier XE but also for the debugger. Additionally, use the mic_extract tool to extract K1OM object code from fat SOs on the host (where Eclipse IDE* runs on). Otherwise the current debugger won’t find the K1OM object code on the host, e.g.:


	$ mic_extract libx.so

If libx.so contains K1OM object code as well, another file is created aside libx.so, like libxMIC.so. The latter contains the K1OM object code. See https://software.intel.com/en-us/node/524818 for more information.

In addition, 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 3.2.1 do 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:

Show the Remote System window:
Menu Window->Show View->Other…
Select: Remote Systems->Remote Systems
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).

Copy GDBServer to coprocessor, e.g.:

Intel® MPSS:


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

Intel® Parallel Studio XE Composer Edition:
```
		$ scp <install-dir>/debugger_2016/gdb/targets/mic/bin/gdbserver mic0:/tmp
```
During development you can also add GDBServer to your coprocessor image!

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® Parallel Studio XE Composer Edition)!

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 Intel® Parallel Studio XE Composer Edition. 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.*:
  <mpss_root>/sysroots/x86_64-mpsssdk-linux/usr/share/doc/gdb-<version>/GDB.pdf
  (not available for all; please see Errata)
Intel® Parallel Studio XE Composer Edition:
<install-dir>/documentation_2016/en/debugger/gdb-mic/gdb.pdf
<install-dir>/documentation_2016/en/debugger/ps2016/get_started.htm

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. Documentation for GNU* GDB is missing up to 3.2 (3.3 and later contain it).
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

Newer versions of MPSS correct this. This workaround is not required if you use the start_mpm.sh script from the Intel® Parallel Studio XE Composer Edition package.
For MPSS 3.* the coprocessor native GNU* GDB requires debug information from some system libraries for proper operation.
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 of Intel MPSS 3.2.2!).

Contents

Trending Articles