This document provides startup and usage information for the GNU* Project Debugger (GDB) shipped with Intel® System Studio (Linux* and Android* targets only).

Refer to the Intel® System Studio release notes for an introduction to the entire suite.

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

Always call the compiler environment setup script:

$ call <install-dir>\compilers_and_libraries_<version>\linux\bin\compilervars.bat <target-arch> <platform>

<install-dir> is the installation directory, by default, it is:

C:\IntelSWTools\<suitename>

<target-arch> must be one of:

  • ia32 (for IA-32 host and target)
  • intel64 (for Intel® 64 host and target)

<platform> must be one of

  • linux (for Linux* target)
  • android (for Android* target)

For other prerequisites, new debugger features, hardware and software requirements, and known issues refer to the Release Notes for Windows* Host GNU* Project Debugger (GDB).

Using GDB

  1. Depending on the target system, there are different gdbserver executables provided. Select an appropriate one under

    <install-dir>\debugger_<version>\gdb\targets\<target-arch>\<target>\bin\gdbserver

    and copy it to the target system.

    <install-dir> is the installation directory, by default, it is:

    C:\IntelSWTools\<suitename>

    <target-arch> is ia32, intel64, or Quark, identifying the architecture of the target system.

    <target> is the target system type.

    Note

    Not all combinations of host/target systems are supported. Refer to the Intel® System Studio release notes for more information.

  2. Start the gdbserver on the target system by either loading an application to debug or attaching to it:

    • Loading an application called my_application:

      $ gdbserver localhost:2000 my_application
      Process program created; pid = ...
      Listening on port 2000

    • Attaching to a running application with PID my_pid:

      $ gdbserver localhost:2000 --attach my_pid
      Process program created; pid =  ...
      Listening on port 2000 
                                      

    Note

    This requires that the application has been launched externally before. To ensure that it does not run away, you can add the following code snippet:

    volatile int lock_loop = 1;
    while(lock_loop) { lock_loop = 1; } // or: sleep(1)

    An application will be locked to that loop until attached and lock_loop manually being set to 0.

  3. Start GDB on the host, connect to the gdbserver on the target system called my_target and debug the remote application my_remote_application>:

    gdb-ia.bat
    (gdb) target remote my_target:2000
    Remote debugging using my_target:2000

    The port number must match the one specified during launch of gdbserver on the target called my_target.

    Make sure the connection is not blocked by a firewall.

    Note

    Do not use gdb-ia.exe directly. Use gdb-ia.bat instead.

    Alternatively, you can use multi-mode which allows reuse of the gdbserver across different debug sessions (this means, it does not terminate):

    1. Start gdbserver on the target system in multi-mode (no application or PID is required):

      $gdbserver --multi localhost:2000
      Listening on port 2000 
                                      

    2. Start GDB on host and connect with the following command:

      $ gdb-ia.bat
      (gdb) target extended-remote my_target:2000
      Remote debugging using my_target:2000

      Refer to the GDB documentation for more information.

    Note

    For remote debugging it is important to set the sysroot (set sysroot <path> command). Optionally, you can specify additional target libraries (set solib-search-path <path> command) and/or map source paths (set substitute-path <from> <to> command). Refer to the GDB documentation for more information.

Using Debug Configurations in the Intel System Studio IDE

The Intel System Studio Integrated Development Environment (IDE) features built-in debug configuration templates preconfigured for use with GNU GDB with Intel's modifications. Follow these instructions to use GDB from within the Intel System Studio IDE.

Launch the Intel System Studio IDE

Launch the Intel® System Studio IDE by running <install-dir>\iss_ide_eclipse-launcher.bat, where <install-dir> is the root directory of your Intel® System Studio installation. By default, <install-dir> isC:\IntelSWTools\system_studio_<version>\.

Create a New Debug Configuration

  1. In the top menu bar, choose Run > Debug Configurations…
  2. Double-click an entry beginning with gdb-ia, for example, gdb-ia C/C++ Application.
  3. Configure the debug target:
    1. In the Main tab, click the Browse… button next to the Project input field and select the project you wish to debug.
    2. Click the Search Project… button or the Browse… button next to the C/C++ Application input field to select the target executable.
  4. Configure the debugger:
    1. In the Debugger tab, verify that the GDB debugger input field contains the path to GDB with Intel's modifications. If the field is empty, click the Browse… button and select the GDB executable manually. By default, it is located in <install-dir>\debugger_<version>\gdb\intel64\bin\gdb-ia.bat.
    2. If debugging a remote application, switch to the Main tab and do one of the following:
      • Select an existing connection in the Connection drop-down list.
      • Create and configure a new connection by clicking the New button next to the Connection drop-down list.

(Optional) Copy gdbserver to Remote Target

Depending on the target system, there are differentgdbserverexecutables provided. Select an appropriate one under

<install-dir>\debugger_<version>\gdb\targets\<target-arch>\<target>\bin\gdbserver

and copy it to the target system.

<target-arch> is ia32, intel64 or Quark, identifying the architecture of the target system.

<target> is the target system type.

On the target system, add gdbserver to the PATH environment variable for the user selected with the remote configuration in RSE.

Note

Not all combinations of host/target systems are supported. Refer to the Intel® System Studio release notes for more information.

Debug Your Application

Choose Run > Debug in the top menu bar to start debugging.

By default, execution breaks at the start of the main() function. You can double-click the left margin of the source code view to add breakpoints manually. The breakpoint mark shows the location of your breakpoint.

You can use the console to pass input to your application during execution. To pass commands directly to GDB, open the Debugger Console by selecting Windows > Show View > Debugger Console.

Note

For remote debugging it is required to set the sysroot (set sysroot <path> command). Optionally, you can specify additional target libraries (set solib-search-path <path> command) and/or map source paths (set substitute-path <from> <to> command). Some of those settings are directly supported by the Eclipse* IDE. In case this is not possible, the .gdbinit file can be used to host those commands.

Refer to the GDB documentation for more information.

Hardware-supported Instruction Recording with the Intel System Studio IDE

The provided GDB can be used for hardware-supported instruction recording as described in chapter "Recording Inferior's Execution and Replaying It" in the GDB Manual.

To enable the feature with Intel System Studio IDE and view the function call history of executed branches, perform the following steps:

  1. Select Run > Debug Configurations....
  2. Expand gdb-ia C/C++ Remote Application.
  3. Create a new configuration or select an existing one.
  4. Go to the Debugger tab.
  5. Under Debugger Options check Enable Reverse Debugger at startup.
  6. Select a recording method from the pulldown menu. The methods you can use depend on the used hardware. See the Release Notes for more information.
  7. Click Apply.

    The recording is now enabled. For more information see the GDB Manual.

  8. To display the Function Call History window, select Window > Show View > Function Call History.
  9. To enable reverse debugging, select Window > Customize Perspective... and check Reverse Debugging.
  10. Run or step into your application. The Function Call History window displays the function calls of each executed branch.
  11. To stop recording, selectRun > Toggle Reverse Debugging. You can also change the branch trace recording method by using the Set Reverse Debugging Trace Method pulldown menu in the toolbar.

Cross-Development Use Cases

Debugging on a Remote Target System with GDB

For cross-development, GDB comes with a remote debug agent called gdbserver . This debug agent can be installed on the debug target to launch a debuggee and attach to it remotely from the development host. This can be useful in situations where the program needs to be run on a target host that is different from the host used for development, particularly when the target has a limited amount of resources (either CPU and/or memory).

To do so, start your program using gdbserver on the target machine (see above). The gdbserver then automatically suspends the execution of your program at its entry point, waiting for a debugger to connect to it. The following commands start an application called "my_program" and tell gdbserver to wait for a connection with the debugger on local host port 2000.

$ gdbserver localhost:2000 my_program
Process program created; pid = 5685
Listening on port 2000

Once gdbserver has started listening, tell the debugger to establish a connection with this gdbserver, and start the same debugging session as if the program was being debugged on the same host, directly under the control of GDB.

$ gdb-ia.bat my_program
(gdb) target remote my_target:2000
Remote debugging using my_target:2000
0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
(gdb) b foo.adb:3
Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
(gdb) continue
Continuing.
Breakpoint 1, foo () at foo.adb:4
4 end foo;

It is also possible to use gdbserver to attach to an already running program, in which case the execution of that program is suspended until the connection between the debugger and gdbserver is established.

To tell gdbserver to wait for GDB to attempt a debug connection to the running process with process ID 5685, use the following syntax:

$ gdbserver localhost:2000 --attach 5685

Refer to "GDB: The GNU* Project Debugger" (http://www.gnu.org/software/gdb/) for details.

Using GDB to Debug Applications Running Inside a Virtual Machine

Using GDB for remotely debugging an application running inside a virtual machine follows the same principles as remote debugging using the gdbserver debug agent.

The only additional step is to ensure TCP/IP communication forwarding from inside the virtual machine and making the IP address of the virtual machine along with the port used for debug communication visible to the network as a whole.

Details on how to do this setup can be found on Wikibooks* (http://en.wikibooks.org/wiki/QEMU/Networking).

  1. To install QEMU, enter:
    $ su -
    $ yum install qemu bridge-utils
  2. For best performance, install your guest OS to an image file. To create one, type:
    $ qemu-img create <filename> <size>[ M | G ]
    $ qemu-img create Linux.img 10G

    where <filename> is name of your image, and <size> is the size of your image with the suffix M (MB) or G (GB) right after the number, no spaces.

  3. To configure the network for your guest OS, enter the following contents into /etc/qemu-ifup:
    #!/bin/sh
    #
    # Script to bring up the device in QEMU in bridged mode
    #
    # This script bridges eth0 and tap0. First take eth0 down, then
    # bring it up with IP 0.0.0.0
    #
    /sbin/ifdown eth0
    /sbin/ifconfig eth0 0.0.0.0 up
    #
    # Bring up tap0 with IP 0.0.0.0, create bridge br0 and add
    # interfaces eth0 and tap0
    #
    /sbin/ifconfig tap0 0.0.0.0 promisc up
    /usr/sbin/brctl addbr br0 /usr/sbin/brctl addif br0 eth0
    /usr/sbin/brctl addif br0 tap0
    #
    # As we have only a single bridge and loops are not possible,
    # turn spanning tree protocol off
    #
    /usr/sbin/brctl stp br0 off
    #
    # Bring up the bridge with IP 192.168.1.2
    # and add the default route
    #
    /sbin/ifconfig br0 192.168.1.2 up
    /sbin/route add default gw 192.168.1.1
    #
    # Stop firewall
    #
    /sbin/service firestarter stop
    /sbin/service iptables stop

    Change the IP addresses (boldface) according to your setup. The first and the second occurrence of the IP is the IP address assigned to your computer. Note that to predict your IP, you need static IP addresses. The third IP represents your gateway.

  4. Enter the following contents into /etc/qemu-ifdown:
    #!/bin/sh
    #
    # Script to bring down and delete bridge br0 when QEMU exits
    #
    # Bring down eth0 and br0
    #
    /sbin/ifdown eth0
    /sbin/ifdown br0
    /sbin/ifconfig br0 down
    #
    # Delete the bridge
    #
    /usr/sbin/brctl delbr br0
    #
    # Bring up eth0 in "normal" mode
    #
    /sbin/ifup eth0
    #
    # Start firewall again
    #
    /sbin/service firestarter start
    /sbin/service iptables start
  5. Make the scripts executable so QEMU can use them:
    $ su -
    $ chmod +x /etc/qemu-if*
    $ exit
  6. To start installing the guest OS, type:
    $ su
    $ /sbin/modprobe tun
    $ qemu -boot d -hda <image>.img -localtime -net nic -net tap -m 192 -usb -soundhw sb16 -cdrom /dev/hdc;/etc/qemu-ifdown

    where image is the name of your image. If /dev/cdrom is not your CD drive, change it to the correct device. After the install is complete, proceed to the next step.

  7. To run your guest OS, create a QEMU start script called qemustart in the same directory as your image:
    #!/bin/sh
    su -c "/sbin/modprobe tun;qemu -boot c -hda <image>.img -localtime -net nic -net tap -m 192 -usb -soundhw sb16; /etc/qemu-ifdown"
  8. To make the startup script executable, enter:
    $ chmod +x qemustart

Training and Documentation

Document Description
GDB Manual Only available for Linux*/Android* target! Contains descriptions of the GNU* Debugger (GDB) functions and interfaces including Intel-extended features
Release Notes for Windows* Host GNU* Project Debugger (GDB) This document 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.

Copyright 2015-2019 Intel Corporation.

This software and the related documents are Intel copyrighted materials, and your use of them is governed by the express license under which they were provided to you (License). Unless the License provides otherwise, you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related documents without Intel's prior written permission.

This software and the related documents are provided as is, with no express or implied warranties, other than those that are expressly stated in the License.

For more complete information about compiler optimizations, see our Optimization Notice.