The Source Window

Overview

The Source Window is the primary interface between the user and the debugger; it is automatically opened when the debugger starts. The Source Window displays the status of the trace experiment, controls navigation of the trace buffer, and allows visualization of the program execution.

Source Window topics:

- Variable Balloons
- Source Pop-up Mens
- Program Status Bar
- Source Display Status Bar
Search Entry

Menus

File Menu

The File menu contains the following items:

Open: Opens a file selection dialog to select the executable to debug
Target Settings...: Opens the Target Selection Dialog to edit target settings
Page Setup: (Windows only) Opens the Windows Page Setup dialog to configure printing
Print: (Windows only) Print the contents of the Source Window Display
Exit: Exits the debugger

Run Menu

The Run menu contains the following items:

Connect to target: Establish a connection to a target. This option will open the Target Selection Dialog if no previous connection has been established in the current session.
Begin Collection: Start collecting trace data on the target
End Collection: Stop collecting trace data on the target
Disconnect: Disconnect the debugger from the target

View Menu

The View menu contains the following items:

Stack: Open a Stack Window
Registers: Open a Register Window
Memory: Open a Memory Window
Watch Expressions: Open a Watch Window
Local Variables: Open a Locals Window
Tracepoints: Open a Tracepoint Window
Tdump: Open a Tracepoint Dump Window
Console: Open a Console Window

Trace Menu

The Trace Menu contains the following items:

Next Hit: Update all displays with the next tracepoint in the tracepoint buffer
Previous Hit: Go to the previous tracepoint in the buffer
First Hit: View the first tracepoint in the buffer
Next Line Hit: Go to the next tracepoint in the buffer in the same frame as the current tracepoint
Next Hit Here: Jump to the next reference of the current tracepoint in the buffer
Tfind Line...: Opens a dialog allowing the user to specify which source line to inpect in the tracepoint buffer
Tfind PC...: Opens a dialog allowing the user to specify the PC of the tracepoint to view
Tfind Tracepoint...: Opens a dialog allowing the user to specify which tracepoint to view (by number). This option is most commonly used in conjunction with the Console Window.

Preferences Menu

The Preferences menu contains the following items:

Global: Opens the Global Preferences Dialog and allows editing of global settings
Source: Opens the Source Preferences Dialog and allows editing of Source Window settings
Register: Opens the Register Preferences Dialog and allows editing of Register Window settings

Toolbar

The Source Window toolbar consists of three functional sections: trace control buttons, debugger window buttons, and stack frame control buttons.

Tracing Control Buttons

These convenience buttons provide on-screen access to the most important debugger tracing control functions:

TStart or TStop: The TStart Button causes the target to start collecting trace data; The TStop Button causes the target to stop collecting trace data
Next Hit: Update all displays with the next tracepoint in the tracepoint buffer
Previous Hit: Go to the previous tracepoint in the buffer
First Hit: View the first tracepoint in the buffer
Next Line Hit: Go to the next tracepoint in the buffer in the same frame as the current tracepoint
Next Hit Here: Jump to the next reference of the current tracepoint in the buffer

Window Buttons

The Debugger Window buttons give instant access to the Debugger's auxillary windows:

Registers: Open a Register Window
Memory: Open a Memory Window
Stack: Open a Stack Window
Watch Expressions: Open a Watch Window
Local Variables: Open a Locals Window
Tracepoints: Open a Tracepoint Window
Tracepoint Dump Window: Open a Tdump Window
Console: Open a Console Window

Frame Control

The Frame Control area of the toolbar displays information about the PC of the current frame, and the frame control buttons may be used to navigate through the call stack. Whenever any of these buttons are used, both the Source Window Display and the Stack Window will show the selected frame. In order to use the Stack Window in tracing mode, the stack pointer must be collected.

Frame Information Display: The left half of the frame information display shows the value of the PC in the current frame. The right half shows the line number of the PC in the source file, if available.
Up: Select and view the stack frame that called this one
Down: Select and view the stack frame called by this one
Bottom: Select and view the bottom-most stack frame

Source Display

The Source Display is used for many things: browsing source code, setting, editing, and deleting tracepoints, and a few other special functions. Executable lines (those for which executable code was generated by the compiler) are denoted with a marker (a dash, "-") in the first column of the display.

The debugger highlights the PC in the current frame in either green, indicating that the PC is in the current tracepoint, or gold, indicating that the PC is contained in a frame that is not the current tracepoint, i.e., as part of a stack backtrace. A blue highlight is used by the debugger to indicate a browsing position. All highlight colors are user-selectable in the Source Preferences.

Setting a Tracepoint

Moving the mouse pointer over the "hot spot" of an executable line will change the mouse cursor to a large dot. Clicking the left mouse button will then allow tracepoint to be inserted at this line. If no tracepoint exists, the Add Tracepoint Dialog will appear. If a tracepoint is installed, the dash in the left margin will change into a magenta breakdot. If a tracepoint exists, the Edit Tracepoint Dialog appears, allowing either modification of the tracepoint or deletion of the tracepoint. If the tracepoint is deleted, the breakdot will revert to a dash.

The executable line marker shows the status of each line: an empty marker (the dash) indicates that no tracepoint is set at the line. A colored breakdot indicates that a tracepoint exists at the line.

The display will attempt to show the value of variables in variable balloons. To activate a variable balloon, simply hold the mouse cursor over the name of a variable in the Source Display for a second or two: the debugger displays the name of the variable, its type, and its value in a pop-up balloon. If the variable was not collected, the Variable Balloon will show a memory-access error.

Source Pop-up Menus

The Source Display has two pop-up menus. One is activated by clicking the right mouse button when the mouse cursor is over an executable line marker's hot spot. This pop-up menu provides access to:

Set Tracepoint: Opens the Add/Edit Tracepoint Dialog, which allows new tracepoints to be set and modification and deletion of existing tracepoints.

The other pop-up menu is activated by clicking the right mouse button anywhere else in the Source Display. It is only available when a variable or number in the display lies below the mouse cursor or is selected (by clicking the left mouse button and dragging the mouse to highlight the variable/number). The pop-up menu allows users to:

Add expr to Watch: Adds the selected expression to the Watch Window, opening it, if necessary.
Dump Memory at expr: Opens a new Memory Window at the selected expression. If the expression is a variable, then the Memory Window is opened with memory addresses starting at the value of the variable.
Set Tracepoint Range: This option is only available when a range of lines is highlighted in the Source Display. It allows tracepoints with the same properties to be set at every executable line in the range. If any tracepoints exist in the range already, the debugger will ask if the properties of the existing tracepoint should be replaced with the properties of the range.

Source Window Status Bars

The Source Window has two status bars which inform the user of the status of the program (the "status bar") and the status of the Source Window.

The Program Status Bar (or simply "Status Bar") displays the status of the program. Common messages seen here include:

No program loaded.: No program has been loaded into target memory.
Inspecting trace at line/address: The debugger is inspecting the tracepoint at line line or address address. Use the Tracing Control Buttons to navigate through the trace buffer.

The Status Bar also displays some help information. For instance, the Status Bar will show the function of a button on the toolbar or the Source Display Status Bar as well as any keyboard shortcut for this button.

Source Display Status Bar

current state of the Source Window: the name of the file displayed in the Display, the name of the function in the Display which contains the PC for the current frame (if any), and the display mode.

The Source File Selector is a dropdown menu which contains the names of all the files that were compiled into the program being debugged.

Normally, the File Selector displays the name of the file currently being viewed, but any file from the dropdown menu may be selected for browsing. Simply select the file to view from the available choices (or type it directly into the File Selector) and the Source Window will load that file into the Display. To return to the current tracepoint, simply press the Bottom Frame Control Button.

The Source Function Selector displays the name of the function containing the Source Window's PC, if one exists, but it may be used to browse any function in the current file. Simply type the name of the desired function into the Function Selector or select it from the dropdown menu. The Source Window's PC is updated to point at this function. To return to the current tracepoint, simply press the Bottom Frame Control Button.

The Source Display Mode Selector displays the viewing mode of the current file/function shown in the Source Window Display.

The Display Mode Selector may be used to change the view of the current source file. The available display modes are

SOURCE: The contents of the Display are shown as source code. If source code is not available (either because no debugging information is available or the source file is not found), the Source Window will revert the Display Mode to "ASSEMBLY".
ASSEMBLY: A disassembly of the target's memory is shown in the Display. Even assembly source files show a disassembly of target memory; to see the assembly source code, use the SOURCE mode. Note that the debugger can only display assmebly code on a function-by-function basis. It cannot display all the instructions generated from a single source file.
MIXED: The Display shows source code mixed with the assembler instructions which were generated for those lines by the compiler for the current funtion. Note that the addresses of the assembly lines is not necessarily monotonically increasing. If the source file associated with the function cannot be found, the Source Window will revert to ASSEMBLY mode.
SRC+ASM: The Source Window Display is divided into two panes: an assembly pane and a source pane. Tracepoints may be set/cleared in either pane.

Search Entry

The Search Entry facilitates searching for text in the Source Window Display. Simply enter the text to be found into the Search Entry and press the Enter key on the keyboard to search forwards in the Source Window Display (hold down ths Shift key to search backwards). If a match is found, it is highlighted in the Source Window and the Program Status Bar displays information about where the match was found.

The Search Entry can also jump the Source Window to a specific line. Enter the line number preceeded by an at-sign (@) into the Search Entry and press enter. If entered line number is greater than the total number of lines in the Source Window Display, the Display will jump to the end of the current file.