Contents|Previous|Next
Working with Cygnus Insight, the visual debugger

This documentation outlines the functions of the GNUPro visual debugger, Cygnus Insight, and its graphical user interface. 
When Insight first opens, it displays the Source Window. The other windows that are invoked from the Source Window, through View menu selections or tool bar buttons have documentation in the order that they appear in the Source Window’s View menu. The Help window, for instance, is invoked from the Source Window’s Help menu.
The documentation discusses what occurs during an actual debugging session, after running the executable up to a single breakpoint set in ’main.c’ of our example executable program.
 
Source Window
When Insight first opens, it displays the Source Window.
The following documentation describes the Source Window attributes and its correlating functionality.

Using the Source Window

When Insight first opens, it displays the Source Window.
Figure 1:  Source Window
Menu bar for the Source Window
There are six menu item selections: File, Run, View,Control, Preferences and Help.
The following documentation discusses the Source Window menus.
File
Figure 2:  File menu
Run
Figure 3:  Run menu
View
Figure 4:  View menu
Control
Figure 5:  Control menu
Preferences
Figure 6:  Preferences menu
Help 
Figure 7:  Help menu
Toolbar buttons
Figure 9:  Run button
Figure 10:  Stop button
Figure 11:  Step button
Figure 12:  Next button
Figure 13:  Finish button
Figure 14:  Continue button
Figure 15:  Step assembler instruction button
Figure 16:  Next assembler instruction button
Figure 17:  Registers button
Figure 18:  Memory button
Figure 19:  Stack button
Figure 20:  Watch Expressions button
Figure 21:  Local Variables button
Figure 22:  Breakpoints button
Figure 23:  Console button
Figure 24:  Program counter display frame and line number display frame
Figure 25:  Down stackframe button
Figure 26:  Up stackframe button
Figure 27:  Go to bottom of stackframe button
Special display pane features
The following discussion details some special features to the display panes.
Using the mouse in the display pane
There are various uses of the mouse within the main display pane of the Source Window. Divided into two columns (see Using the mouse in the window), the display pane’s left column extends from the left edge of the display pane to the last character of the line number, while the right column extends from the last character of the line number to the right edge of the display pane.
Figure 28:  Using the mouse in the window
         Left display column          |         Right display column

Within each column, the mouse has different effects.

The following functionality is for the right column.

Figure 29: Pop-up window for expressions
Add lis to Watch
Opens the Watch Expressions window and adds a variable expression (the ‘lis’ variable shows in the examples) to the list of expressions in the window.
Dump Memory at lis
Opens the Memory window, which displays a memory dump at an expression (in the example program, the ‘lis’ expression).
When the cursor is in the left column over an executable line (marked on the far left by a minus sign), it changes into a circle. When the cursor is in this state, the following functionality occurs.
Figure 30: Pop-up menu for setting breakpoints
Continue to here
Set breakpoint here
Set temporary breakpoint here
Set Breakpoint on Thread(s)... Figure 31: Thread-specific breakpoint

Figure 32: Pop-up menu for deleting breakpoints
Delete Breakpoint
Continue to Here
With the cursor over a line, a breakpoint opens a breakpoint information balloon (see example).

Below the horizontal scroll bar
 

There are four display and selection fields below the horizontal scroll bar: the status text box, the file drop-down list box, the function drop-down combo box and the code display drop-down list box
 
Figure 33: Status text box
At the top of horizontal scroll bar, a text box displays the current status of the debugger (in the status box for the window depicted in Figure 33: Status text box, the message reads "Program stopped at line 19" as current status for the example’s program.
Figure 34: File drop-down list box
The drop-down list box displays all the source (.c) and header (.h) files associated with the executable. Select files by clickingthe arrow to the right of the dialog box and selecting one of the files in the list box, or by typing the file’s name directly into the dialog box.

Figure 35: Function drop-down combo box

The function  drop-down list box displays all the functions in the currently selected source or header file. Select a function by clicking in the list box, or by typing into the text field above it.

 
Figure 36: Code display drop-down list box
Select how the code in the Source Window is displayed, as shown with the selectable formats in Figure 36: Code display drop-down list box.
Figure 37: Search text box
 
Dialog boxes for the Source Window
The following documentation describes the dialog boxes that are invoked from the Source Window, through the File and Preferences menu selections.
Load New Executable dialog box for the Source Window

 
The Load New Executable dialog box invokes by clicking the Open menu item in the file drop-down menu of the Source Window. This dialog box allows you to navigate through directories and select an executable file to be opened in the Source Window.
Figure 39: Load New Executable dialog box window

Choose GDB Command file dialog box

The Choose GDB Command file dialog box invokes by clicking the Source menu item in the File menu of the Source Window. This dialog box allows you to navigate through directories and select a text file containing a series of GDB commands, which will open for executing at the command prompt in the Console window.
Figure 40: Choose GDB Command file dialog box
     
Target selection from the Source Window
The Target Selection dialog box invokes by clicking the Target Settings menu item in the File menu of the Source Window. Allowing you to select the target for the executable files to which you want to debug, the Target Selection dialog box also helps in selecting or designating other target-specific settings.
 
Figure 41: Target Selection dialog box window

Global Preferences dialog box for the Source Window

The Global Preferences dialog box window invokes by clicking the Global menu item in the Preferences  menu of the Source Window. This dialog box allows you to select the font and the type size, for displaying text.
Figure 42: Global Preferences dialog box window

Source Preferences dialog box for the Source Window

The Source Preferences dialog box helps to specify preferences of how source code appears and to reflect changes of debug settings. Use the Source menu item in the Preferences menu of the Source Window to invoke the Source Preferences dialog box.
Figure 45: Source Preferences dialog box
    Colors
      Single left-clicking any of the colored squares opens the Choose color dialog box. The Choose color dialog box allows the display colors to be modified by the user.
    Debug Mode
      Unless GDB has been configured to enable the setting of tracepoints, this radio button has no effect.
    Variable Balloons
      If Variable Balloons is on, a balloon appears displaying the value of a variable, when the mouse is placed over the variable in the Source Window. On is the default selection.
    Tab Size
      Sets the number of spaces for a tab character in the Source Window.
    Line Numbers
      Enables (by default setting) the Source Window to display line numbers.
Page Setup dialog box for the Source Window

 
The Page Setup dialog box window invokes by clicking the Page Setup menu item in the File menu for the Source Window. This standard dialog box allows you to make page layout selections before printing a source file.
 
Figure 46: Page Setup dialog box window
Print dialog box for the Source Window
The Print dialog box window  invokes by clicking the Print Source menu item in the File drop-down menu of the Source Window. This dialog box allows you to select a printer and make other print specific selections, before printing a source file. 
 
Figure 47: Printdialog box window

Stack window

The Stack window displays the current state of the call Stack, where each line represents a stack frame.
Figure 48: Stack window
Clicking a frame selects that frame, indicated by the background of the frame turning yellow, as shown in Clicking a stack frame. The Source Window automatically updates to display the line, corresponding to the selected frame. If the frame points to an assembly instruction, the Source Window changes to display assembly code. The background of the corresponding line in the Source Window also changes to yellow.
Figure 49: Clicking a stack frame

Registers window

The Registers window dynamically displays the registers and their content. The documentation for Register menu for the Register window discusses changing the properties of registers.
Figure 50: Registers window
Hitting the escape key (Esc) will abort the editing.

Register menu for the Register window

Figure 51: Register menu
Figure 52: Register format menu
Hexadecimal (Hex) is the default display format.

Memory window

The Memory window dynamically displays the state of memory. 
Figure 53: Memory window
A memory location can be selected by double clicking the left mouse button with the cursor in the window. The contents of a selected memory location can be edited. See the Address menu for the Memory window.

Address menu for the Memory window

Figure 54: Address menu for the Memory window

Memory Preferences dialog box for the Memory window

The Memory Preferences dialog box for the Memory window makes it possible to set memory options. 
Figure 55: Memory Preferences dialog box for the Memory window

Watch Expressions window

The Watch Expressions window displays the name and current value of user-specified expressions.
Figure 56: Watch Expressions window
Figure 57: Watch menu in the Watch Expressions window
Figure 58: Watch menu for the Watch Expressions window
Figure 59: Value formats for the Watch Expressions window
By default, pointers are displayed in hexadecimal and all other expressions are displayed as decimal.

Add Watch button for the Watch Expressions window

An expression can be typed into the text edit field at the bottom of the dialog box, as shown in the screen on the left in Using the Add Watch button for the Watch Expressions window. By pressing the Add Watch button or hitting the Enter key, the expression is added to the list, as shown in the resulting addition to the window on the right in Using the Add Watch button for the Watch Expressions window. Invalid expressions are ignored. 
Figure 60 : Using the Add Watch button for the Watch Expressions window

Watching registers with the Watch Expressions window

GDB allows registers to be added to the Watch Expressions window, by typing register convenience variables into the text edit field. Every register has a corresponding convenience variable. The register convenience variables consist of a dollar sign followed by the register name. The convenience variable for the program counter is $pc, for example. The convenience variable for the frame pointer is $fp.

Casting pointers in the Watch Expressions window

Pointer values may be cast to other types and watched, represented as the type to which the pointer was cast. For example, by typing "(struct _foo *) bar" in the text edit field, the bar pointer is cast as a struct _foo pointer.

Local Variables window

The Local Variables window displays the current value of all local variables. 
Figure 61: Local Variables window
Figure 62: Displaying the elements of a variable structure

Variable menu for the Local Variables window

Figure 63: Variable menu for the Local Variables window
Figure 64: Variable format menu
By default, pointers are displayed in hexadecimal and all other expressions are displayed as decimal.

Breakpoints window

The Breakpoints window displays all breakpoints that are currently set. 
Warning!
When debugging C++ code, breakpoints and exceptions may not work and, so, the functionality of the Breakpoints window may be inoperable.
Figure 65: Breakpoints window

Breakpoint menu for the Breakpoints window

Figure 66: Breakpoint menu for the Breakpoints window
Figure 67: Results of setting breakpoints

Global menu for the Breakpoints window

Figure 68: Global menu for the Breakpoints window

Console window

The Console window  contains the command prompt for GDB, the GNUPro debugger, allowing access to the debugger through the command-line interface. (gdb) is the prompt for the debugger.
Figure 69: Console window

    Note: The Console window is different from the console window for the Windows operating system (which is known as the Command.com window).

Function Browser window

The Function Browser window invokes by clicking on the Function Browser menu selection in the View drop-down menu of the Source Window.
Figure 70: Function Browser window
Figure 71: Function Browser window with source browser

Threads window

The Threads window dynamically displays the state of threads running in the system.
Warning!
Threads support is not available for all systems.
The Threads window shows a system with two threads. See also Setting breakpoints and viewing local variables and Setting breakpoints on multiple threads.
Figure 72: Threads window
The Threads window displays a list of threads and/or processes. The exact contents are specific to each operating system. The Threads window consists of a list box that displays information on threads and/or processes that are part of the executable being debugged. The first column is the GDB thread number, used internally by GDB to track the thread. This number is also used by the command line interface (the Console window) when referring to threads. The rest of the columns are dependent on  information coming from the operating system.
The Source Window displays the current location and source for a current thread (or process). To change the current thread, click the left mouse button on the desired thread in the Threads window and the debugger will switch contexts, updating all windows. The current thread will highlight.
When a breakpoint is set on a line or function, every thread that hits that location will stop execution and return control to the debugger. To set a breakpoint on a specific thread or threads, you need to use the Source Window. See Setting breakpoints and viewing local variables and Setting breakpoints on multiple threads.

 

Help window

The Help window invokes by clicking the Help Topics menu selection in the Help drop-down menu of the Source Window. The Help window offers HTML based navigable help by topic.
Figure 73: Help window
See also the discussions for File menu for the Help window and Topics menu for the Help window.

File menu for the Help window

Figure 69: File menu for the Help window

Topics menu for the Help window

Selecting a menu item invokes the Help topic’s contents, as shown in Topics menu for the Help window.
Figure 70: Topics menu for the Help window
Each menu item represents a help topic. When a menu item is selected, the content of the Help window changes to reflect the listed topic. There is currently no Helptopic for the Function Browser window or the Threads window, since their implementation is new to Insight functionality.

Top|Contents|Previous|Next