The Tornado debugger (CrossWind) combines the best features of graphical and command-line debugging interfaces.

The most common debugging activities, such as setting breakpoints and controlling program execution, are available through convenient point-and-click interfaces. Similarly, program listings and data-inspection windows provide an immediate visual context for the crucial portions of your application.

For complex or unpredictable debugging needs, the command-line interface gives you full access to a wealth of specialized debugging commands.You can extend or automate command-line debugger interactions by using the Tcl scripting interface that allows you to develop custom debugger commands (see 10.1 Introduction).

The underlying debugging engine is an enhanced version of GDB, the portable symbolic debugger from the Free Software Foundation (FSF). For full documentation of the GDB commands, see GDB User's Guide.

Figure 10-1 illustrates the GUI elements you can use to interact with the debugger.

The Debug menu provides the complete list of Tornado GUI debugger commands, as well as their keyboard shortcuts (10.2.1 Debugger Toolbar, Buttons, and Menu Commands).

The Debug toolbar provides buttons for the most common debugger commands, as well as for opening and closing windows that display data, memory, and stack information (see 10.2.1 Debugger Toolbar, Buttons, and Menu Commands).

You use the editor window to keep track of the code you are debugging. You can click in this window to specify information for debugger commands (such as symbol names, or lines of code). The debugger in turn uses the attribute panel, in the left margin of the editor window, to show breakpoints and the execution context. (See 10.3 Using the Debugger.)

The debugger command line window for CrossWind provides a command-line interface to the debugger (see 10.5 Using the Debugger Command Line). The window is not needed for standard debugger operations; the graphical interface provide simpler controls.

The Debug toolbar has buttons for the most common debugging commands, as well as for displaying auxiliary debugger windows. The toolbar shown as a floating palette in Figure 10-2.

The commands in the Debug menu include alternatives to the buttons in the Debug toolbar, as well as additional debugger functions. Keyboard shortcuts are also available for all graphical debugger commands

The debugger buttons and menu commands are described in Table 10-1.

The debugger allows you to download object modules, to start routines under debugger control, and to take over existing tasks in the target. Tasks under debugger control execute normally until they terminate, unless they encounter a breakpoint, or you interrupt them, or some other event sends them an interrupt or a signal.

There are two ways to start a debugging session:

• From the Tornado Launch toolbar: Press the button. This starts a debugging session for the currently selected target server (see Tornado Launch Toolbar, p.98).

• From the Tools menu: Click on Debugger. The dialog box shown in Figure 10-3 appears, to allow you to select a target server from the Targets drop-down list.

When the debugger is running, you can interact with it through the editor window, through the debugger command line window, and through the Debug menu and toolbar. (See 10.2 Debugger GUI.)

You can end the debugging session in any of the following ways:

• In the debug toolbar, press the button.

• Click on the Stop Debugging command in the Debug menu.

The debugger maintains a list of directories where it searches for source code, and for the host-resident image of the VxWorks run-time (the debugger uses the latter to load debugging symbol information). This list is called the source search path.

Normally you will not need to set the source search path because the debugger can derive the path from the object file. If GDB finds the object but cannot find the source, the GUI prompts you for the source file location and remembers it.

If necessary, click on Source Search Path to add directories to, remove directories from, or change the order of this list. Figure 10-4 illustrates the Debugger Source Search Path dialog box.

Normally you will not need to unload a module. If you update and download a module with the same name, it replaces the module loaded earlier. In the unusual case where you need to unload a module without replacing it, use the unload option from the context menu in the project Workspace window (see 4.3.5 Downloading an Application).

You can also use the debugger command line to remove any dynamically-linked module from the target. Open the debug command-line window and use the GDB unload command. See 10.5 Using the Debugger Command Line for more information about command line usage.

To run a subroutine under debugger control, use the Run command. The Run Task dialog box appears; use it to specify which routine to run, with what arguments. Click OK to start the task on the target.

Specify the argument list after the routine name, with the arguments separated by spaces. The argument list must contain integers or addresses only; it may not contain floating-point or double-precision values, function calls, or user-defined C++ operations. (See GDB User's Guide for other commands which allow arbitrary arguments to be passed.)

Figure 10-5 shows the Run Task dialog box with a routine name (required) and an argument list (optional). The default for required arguments that you do not supply is zero. To set a temporary breakpoint where the routine begins execution, check the Break at Entrypoint box.

Once a task stops under debugger control (most often, at a breakpoint), you can single-step through the code, jump over subroutine calls, or resume execution. Figure 10-10 shows the debugger stopped at the entry point of the routine BigBang( ). The context pointer þ indicates what statement will execute if you allow the program to resume.

You can interrupt execution with Interrupt Debugger in the Debug menu, by pressing the button, or by using the keyboard shortcut ALT+SHIFT+F5.

To set multiple breakpoints, select Breakpoints in either the Debug or the pop-up menu (right-click in the editor window). The Breakpoints dialog box appears. (See Figure 10-7.) Enter a file name and line number in the Location box, select a scope (local task or all tasks), and click Add. The new breakpoint appears in the Breakpoints list. If Externally managed is checked, it indicates that the breakpoint was set by means other than the debugger (by the Tornado shell, for example).

dialog lets you attach conditions to the break point as well as deleting or disabling it instead of keeping it when it is hit. Enter a file name and line number in the Location box. A conditional expression of type int can be used, which will be evaluated as true or false (all non-zero values being true), or to check if a value in memory has changed. The On Break options have the following meanings with regard to handling a breakpoint:

Defines the breakpoint as persistent. It remains active until disabled or deleted.

Defines the breakpoint as temporary. The breakpoint is deleted after it is hit.

Defines the breakpoint as temporary. The breakpoint is disabled after it is hit (not deleted), and can be manually enabled.

To set a breakpoint on an individual line of code, place the text cursor in the line where you want the program to stop. Then click the button, select Toggle Breakpoint from the Debug menu, or right-click on the line of code and select Toggle Breakpoint from the pop-up menu. The symbol appears in the left margin of the editor window to indicate the breakpoint location, when the attribute pane is turned on for the editor (12.3.2 Editor Preferences). Otherwise, the entire line is highlighted to indicate the breakpoint location.

If you click Toggle Breakpoint on a line that produces no object code (such as a comment line or a declaration), the breakpoint appears on the next line that does produce object code.

You can also set temporary breakpoints by using Toggle Temp. Breakpoint from the Debug menu. A temporary breakpoint stops the program only once. The debugger deletes it automatically as soon as the program stops there. A hollow breakpoint symbol ( ) marks temporary breakpoints in the editor's left margin, so that you can readily distinguish the two kinds of breakpoints there.

To remove either kind of breakpoint, click either of these commands with a line selected that already has a breakpoint or use the Breakpoints dialog box.

Once a task has been stopped under debugger control (most often, at a breakpoint), you can single-step through the code, jump over subroutine calls, or resume execution. Figure 10-10 shows the debugger stopped at the entry point of the routine graphInit( ). The context pointer þ indicates what statement will execute if you allow the program to resume.

When the program is stopped, you can resume operation with the Continue command from the Debug menu. If there are no remaining breakpoints, interrupts, or signals, the task runs to completion. A common example of using Continue is to set a breakpoint at the end of a loop, then use Continue repeatedly to stop once in each iteration through the loop, while monitoring a variable used within that loop.

To step through the code one line at a time, click Step Into. If you have auxiliary debugger windows open (10.3.11 Examining Data, Memory, and the Stack), they are updated with current values as you step through the code. If there is a subroutine call in the current line, Step Into takes you to the first line of that subroutine, not to the next line currently displayed on your screen. The only exception is for calls to system subroutines and application subroutines that are compiled without debugging information; Step Into cannot step into these.

The effect of Step Into is somewhat different if the current view in the editor shows assembly instructions (when either Disassembly or Mixed is selected from the View menu, or the current routine has no debugging symbols). In this case, Step Into advances execution to the next instruction rather than to the next line of source.

To single-step without going into other subroutines, click Step Over instead of Step Into. The Step Over command is almost the same as Step Into, but instead of stepping to the very next statement executed (which, in the case of a subroutine call, is typically not the next statement displayed), Step Over steps to the next line on the screen. If there is no intervening subroutine call, this is the same thing as Step Into. But if there is an intervening subroutine call, Step Over executes that subroutine in its entirety, then stops at the line after the subroutine call.

The display style has the same effect on Step Over as on Step Into. Step Over steps to either the next machine instruction or the next source statement, and if necessary completes a subroutine call first.

While stepping through a program, you may conclude that the problem you are interested in lies in the current subroutine's caller, rather than at the stack level where your task is suspended. Use the Step Out command from the Debug menu in that situation: execution continues until the current subroutine completes, then the debugger regains control in the calling statement.

To continue a stopped task to a specific point without setting a breakpoint, place the cursor on the desired line of code, right-click to open the pop-up menu, and select Run to Cursor.

Click Attach to attach the debugging session to a task that is already running. If you were already debugging another task, the previous task is released from debugger control, remaining in its current state (running or stopped). Attach displays a scrolling list of the tasks running on the target (Figure 10-11). You can either select a task in the list, or type the name (or task ID) of a task in the Attach to: box. By default, the debugger attaches without stopping the task. The task will stop when it hits a breakpoint.

Usually, a newly-attached task stops in a system routine; thus, the debugger displays an assembly listing in the editor window. Open the backtrace window using the button. Change the frame by double-clicking on the frame you want to jump to.

The first entry in the Attach dialog box is always System. Select this entry to enter system mode, as described in 10.6 System-Mode Debugging. An error display appears if your BSP is not configured to support system mode.

By default, the debugger always attaches to the next task to register an exception. Thus your debugger is always attached to the task that needs debugging.

This default behavior can be changed by selecting Tools>Options>Debugger. The following options can be selected:

never	do not auto-attach at all
safely	only auto-attach if we are not attached to any task
always	always attach to the next task that gets an exception

Click Detach and Resume to release the current task from debugger control (and allow it to continue running). This allows you to exit the debugger, or switch to system mode, without killing the task you were debugging.

When a program stops under debugger control, you can use auxiliary windows to examine local and global program variables, arguments, registers, target memory, and the execution stack. The windows can be displayed docked or free-floating (Figure 10-12). When they are docked (the default), the split bars at their edges can be used to change their size.

Buttons for the auxiliary debugger windows are on the debugger toolbar, and provide a simple means for opening and closing the windows. They are also accessible from Debug>Debug Windows.

The Watch window displays the current values of symbols, throughout the execution of the program. The Watch window has four pages, which allows you to group and display sets of symbols in any manner you find useful.

To select a symbol for display in the watch window, click on or highlight the symbol name in the editor, display the pop-up menu (with the right-mouse button), and select Add to Watch. If you highlighted the symbols name, the Watch window opens, and lists the symbol and its current value. If you simply clicked on the symbol, the Add to Watch dialog box opens (Figure 10-13).

Enter the name of the symbol and click OK to display the symbol and its current value in the Watch window (Figure 10-14). Use the pop-up menu or the Delete key to remove symbols from the window.

Click the Variables command in the Debug Windows sub-menu to open a window that shows the values of local variables. Figure 10-15 shows an example of the Variables window.

The contents of the Variables window always reflect the routine that is currently executing; when you step into a different routine, the new routine's local variables replace those in the previous display.

Click the Registers command in the Debug menu to open a window that shows the values in the target registers. Figure 10-16 illustrates the Registers window. The contents of the window depend on the architecture of the target, and the title displayed when the window is not docked includes information about machine architecture.

To inspect the calling sequence leading to the current routine, click Back Trace in the Debug Windows sub-menu. The Back Trace window allows you to monitor the stack. You can double-click on any routine in the window to move the context pointer to that stack level in the editor window (Figure 10-17).

Click the Memory command to open a window that displays a range of target memory starting at the address specified in the Start Address control field. The debugger saves each address you type in the field; you can select a previously displayed address from the drop-down list associated with this box. To update the memory display, press the button. Figure 10-18 shows the window docked and maximized.

The display of data in the Memory window is controlled by the Debugger page of the Options property sheet, which is accessible from Tools>Options>Debugger.

See the description of the x ("examine") command in GDB User's Guide: Examining Data for a discussion of the memory-display formats.

While the debugger is running, you can display your program code in the editor as source code, as symbolic disassembly of object code, and as mixed source and disassembly.

The Source, Disassembly, and Mixed Source and Disassembly commands in the View menu control the display of code in the editor:

Displays the original high-level language source code (usually C or C++). This is the default style of program display.

Displays a symbolic disassembly of your program's object code. This style of display is the default for routines compiled without debugging information (such as VxWorks system routines supplied as object code only).

Displays both high-level source and a symbolic disassembly, with the assembly-level code shown as close as possible to the source code that generates the corresponding object code.

Figure 10-19 shows a mixed-mode code display.

Source display (in either the Source or the Mixed Source and Disassembly view) requires that your application modules be compiled with debugging information which is the default for compilations with the Tornado project facility (see 4Projects).

The Tornado graphical interface is usually the most convenient way to run the debugger. However, you can also use the GDB command-line interface, which in some cases is the best way to perform a particular action (see Figure 10-1). The debugger command-line window provides full access to GDB commands, as well as to Tornado extensions to those commands. The command line can be displayed with Debug>Debug Windows>Debug Command Line.

One use of the debugger window is to experiment with text-based commands for actions that you might want to perform automatically each time you start debugging.

When the debugger first executes GDB, it looks for a file named .gdbinit. It first looks in the directory named by the environment variable HOME (if it is defined), then in your current working directory.¹ If it finds the file in either directory, the debugger commands in it are executed; if it finds the file in both directories, the commands in both are executed.

A related initialization file, called gdb.tcl, is specifically intended for Tcl code to customize GDB with your own extensions. The Tcl code in this file executes before .gdbinit. The debugger searches for gdb.tcl in two places: first in installDir\.wind, then (if the environment variable HOME is defined) in homeDir\.wind. See 10.7 Tcl: Debugger Automation for a discussion of extending GDB through Tcl. See also 10.8.1 Tcl: Debugger Initialization Files for a discussion of how the Tornado debugger initialization files interact.

You can use the following commands to establish the debugging context:

Specifies an object file on the host for the debugging session.

When the module you want to debug is already on the target (whether linked there statically, or downloaded by another Tornado tool), the debugger attempts to locate the corresponding object code on the host by querying the target server for the original file name and location. However, many factors often make it necessary to specify the object file explicitly. These factors include differing mount points on host and target, symbolic links, virtual file systems, or simply moving a file after downloading it.

The debugger recognizes the abbreviation add for this command.

Downloads an object file to the target.

This command is equivalent to the Download command in the Debug menu. You may sometimes find it preferable to invoke the command from the command panel--for example, when you can paste a complex path name from the clipboard instead of spending time in a file-browser interaction.

Reads debugging information from filename while downloading serverFilename to the target.

Use this version of the load command when the target server you are using is on a host with a different view of the file system from your debugging session. For example, in some complex networks different hosts may mount the same file at different points: you may want to download a file c:\fred\applic.o which your target server on another host sees as \\fredshost\fred\applic.o.²

Use the serverFilename argument to specify what file to download from the server's point of view. (You must also specify the filename argument from the local point of view for the benefit of the debugger itself.)

See 7.6 Object Module Load Path for a more extended discussion of the same problem in the context of the shell.

Undoes the effect of load: removes a dynamically linked file from the target, deletes its symbols from the debugger, and closes the file.

The load and unload commands both request confirmation if the debugger is attached to an active task. You can disable this confirmation request, as well as all other debugger confirmation requests, with set confirm. See GDB User's Guide: Controlling GDB.

Just as with the Tornado shell, you can execute any subroutine in your application from the debugger. Use the following commands:

This is the principal command to begin execution under debugger control. Execution begins at routine; you can specify an argument list after the routine name, with the arguments separated by spaces. The argument list may not contain floating-point or double-precision values. (This command is not available in system mode; use the shell to get tasks started in that mode. See 7.2.7 Using the Shell for System Mode Debugging.)

If a task is already running (and suspended, so that the debugger has control), you can evaluate any source-language expression (including subroutine calls) with the call command. This provides a way of exploring the effects of other subroutines without abandoning the suspended call. Subroutine arguments in the expression expr may be of any type, including floating-point or double precision.

When you run a routine from the debugger using one of these commands, the routine runs until it encounters a breakpoint or a signal, or until it completes execution. The normal practice is to set one or more breakpoints in contexts of interest before starting a routine. However, you can interrupt the running task by clicking Interrupt Debugger in the Debug menu or by pressing CTRL+BREAK from the Debugger window.

By default, any tasks you start with the run command use the standard I/O channels assigned globally in VxWorks. However, the debugger has the following mechanisms to specify input and output channels:

• Redirection with < and >

Each time you use the run command, you can redirect I/O explicitly for that particular task by using < to redirect input and > to redirect output. For output, ordinary path names refer to files on the host where the debugger is running, and path names preceded by an @ character refer to files or devices on the target. Input cannot be redirected to host files, but input redirection to target files or devices is supported with the same @ convention for consistency. For example, the following command starts the routine appMain( ) in a task that gets input from target device /tyCo/0 and writes output to host file grab.it:

(gdb) run appMain > grab.it < @/tyCo/0

• New Default I/O with tty Command

The debugger command tty sets a new default input and output device for all future run commands in the debugging session. The same convention used with explicit redirection on the run line allow you to specify target files or devices for I/O. For example, the following command sets the default input and output channels to target device /tyCo/0:

(gdb) tty @/tyCo/0

• Tcl: Redirection of Global or Task-Specific I/O

Tcl extensions are available within the debugger's Tcl interpreter to redirect either all target I/O, or the I/O channels of any running task. See 10.7.3 Tcl: Invoking GDB Facilities for details.

The GDB frame command has a Tornado graphical extension, even when used at the command line.

Displays a summary of a stack frame, in the Debugger window. But it also has a useful side effect: it re-displays the code in the editor window, centered around the line of code corresponding to that stack frame.

Used without any arguments, this command provides a quick way of restoring the editor-window context for the current stack frame, after you scroll to inspect some other region of code. Used with an argument n (a stack-frame number, or a stack-frame address), this command provides a quick way of looking at the source-code context elsewhere in the calling stack. For more information about stack frames in GDB and about the GDB frame command, see GDB User's Guide: Examining the Stack.

Instead of using the target server list in the Tornado Launch toolbar, you can select a target from the Debugger window with the target wtx command. The two methods of selecting a target are interchangeable. However, it may sometimes be more convenient to use the GDB command language--for example, you might specify a target this way in your .gdbinit initialization file or in other debugger scripts.

Connects to a target managed by the target server registered as servername in the Tornado registry, using the WTX protocol. Use this command regardless of whether your target is attached through a serial line or through an Ethernet connection; the target server subsumes such communication details. To identify the target server, any unique abbreviation will do as servername; there is no need to specify the full name known to the Tornado registry.

The debugger also provides two kinds of extended commands:

• Server Protocol Requests

The Tornado tools use a protocol called WTX to communicate with the target server. You can send WTX protocol requests directly from the GDB command area as well, by using a family of commands beginning with the prefix "wtx". See Tornado API Programmer's Guide: WTX Protocol for descriptions of WTX protocol requests. Convert protocol message names to lower case, and use hyphens in place of underbars. For example, issue the message WTX_CONSOLE_CREATE as the command wtx-console-create.

• Shell Commands

You can run any of the Tornado shell's primitive facilities described in 7.2.4 Invoking Built-In Shell Routines in the Debugger window, by inserting the prefix "wind-" before the shell command name. For example, to run the shell td( ) command from the debugger, enter wind-td in the Debugger window.³ Because of GDB naming conventions, mixed-case command names cannot be used; if the shell command you need has upper-case characters, use lower case and insert a hyphen before the upper-case letter. For example, to run the semShow( ) command, enter wind-sem-show.

You can change many details of the debugger's behavior by using the set command to establish alternative values for internal parameters. (The show command displays these values; you can list the full set interactively with help set.)

The following additional set/show parameters are available in the Tornado debugger (CrossWind) in addition to those described in GDB User's Guide:

Specifies whether or not to read the GDB-language initialization files (discussed in 10.8.1 Tcl: Debugger Initialization Files). Default: no (that is, read initialization files).

Specifies whether or not to report the explicit exit status of a routine under debugger control. When this parameter is on, the debugger always reports completion of a routine with the message "Program terminated normally." If your application's routines use the exit status to convey information, set this parameter to off to see the explicit exit status as part of the termination message. Default: on.

Specifies the option flags for the dynamic loader (Download in the Debug menu, or load in the Debugger window). These flags are described in the discussion of ld( ) in VxWorks Programmer's Guide: Configuration and Build. Default: LOAD_GLOBAL_SYMBOLS (4).

Specifies whether the debugger translates a relative path specified in the load argument to an absolute path when instructing the target server to download a file. Setting this value to yes instructs the debugger to perform this translation, so that the target server can locate the file even if the server and the debugger have different working directories.

However, in some networks where the debugger and target server have different views of the file system, a relative path name can be interpreted correctly by both programs even though the absolute path name is different for the two. In this case, set wtx-load-path-qualify to no.

Default: yes.

Specifies how long to wait for the target to respond during a download. If a download does no complete in less time than is specified here (in seconds), the debugger reports an error. Default: 30 seconds. To reset this parameter to 120 seconds, use:

(gdb) set wtx-load-timeout 120

wtx-task-priority

Specifies the priority for transient VxWorks tasks spawned by the run command. Default: 100.

Specifies the stack size for transient tasks spawned by the run command. Default: 20,000.

Specifies the name supplied for the debugger session to the target server. This is the name reported in the launcher's list of tools attached to a target. If you often run multiple debugger sessions, you can use this parameter to give each session a distinct name. Default: crosswind.

By default, in Tornado you debug only one task at a time. The task is selected either by using the run dialog box to create a new task, or by using the Attach dialog box (10.3.8 Attaching to a Running Task) to debug an existing task. When the debugger is attached to a task, debugger commands affect only that particular task. For example, breakpoints apply only to that task. When the task reaches a breakpoint, only that task stops, not the entire system. This form of debugging is called task mode debugging. (All the material in 10.3 Using the Debugger applies to task mode debugging).

Tornado also supports an alternate form of debugging, where you can switch among multiple tasks (also called threads) and even examine execution in system routines such as ISRs. This alternative mode is called system mode debugging; it is also sometimes called external mode. In system mode, you can use global breakpoints to stop the entire system whenever any task hits the breakpoint.

Most of the debugger features described elsewhere in this manual, and the debugging commands described in GDB User's Guide, are available regardless of which debugging mode you select. However, certain debugging commands (discussed below in 10.6.3 Thread Facilities in System Mode) are useful only in system mode.

In order for system mode debugging to work properly, the following items must be set correctly.

To debug in system mode, click on the System entry displayed in the Attach dialog box (use the Attach command in the Debug menu to display the dialog box).

You can also switch to system mode from the debugger window or an initialization file, but first make sure your debugger session is not attached to any task (type detach). Then issue the following command:

Switches the target connection into system mode (if supported by the target agent) and stops the entire target system.

The response to a successful attach system is output similar to the following:

(gdb) attach system 
Attaching to system. 
0x5b58 in wdbSuspendSystemHere ()

Once in system mode, the entire target system stops. In the example above, the system stopped in wdbSuspendSystemHere( ), the normal suspension point after attach system.

In system mode, the GDB thread-debugging facilities become useful. Thread is the general term for processes with some independent context, but a shared address space. In VxWorks, each task is a thread. The system context (including ISRs and drivers) is also a thread. GDB identifies each thread with a thread ID, a single arbitrary number internal to the debugger.

You can use the following GDB commands to manage threads:

Displays summary information (including thread ID) for every thread in the target system.

Selects the specified thread as the current thread.

Sets a breakpoint affecting only the specified thread.

For a general description of these commands, see GDB User's Guide: Debugging Programs with Multiple Threads. The sections below discuss the thread commands in the context of debugging a VxWorks target in system mode.

The command info threads shows what thread ID corresponds to which VxWorks task. For example, immediately after attaching to the system, the info threads display resembles the following:

(gdb) info threads 
  4 task 0x4fc868   tExcTask    0x444f58 in ?? () 
  3 task 0x4f9f40   tLogTask    0x444f58 in ?? () 
  2 task 0x4c7380 + tNetTask    0x4151e0 in ?? () 
  1 task 0x4b0a24   tWdbTask    0x4184fe in ?? () 
(gdb)

In the info threads output, the left-most number on each line is the debugger's thread ID. The single asterisk (*) at the left margin indicates which thread is the current thread. The current thread identifies the "most local" perspective: debugger commands that report task-specific information, such as bt and info regs (as well as the corresponding debugger displays) apply only to the current thread.

The next two columns in the thread list show the VxWorks task ID and the task name. If the system context is shown, the single word system replaces both of these columns. The thread (either a task, or the system context) currently scheduled by the kernel is marked with a + to the right of the task identification.

To switch to a different thread (making that thread the current one for debugging, but without affecting kernel task scheduling), use the thread command. For example:

(gdb) thread 2 
[Switching to task 0x3a4bd8   tShell    ] 
#0  0x66454 in semBTake () 
(gdb) bt 
#0  0x66454 in semBTake () 
#1  0x66980 in semTake () 
#2  0x63a50 in tyRead () 
#3  0x5b07c in iosRead () 
#4  0x5a050 in read () 
#5  0x997a8 in ledRead () 
#6  0x4a144 in execShell () 
#7  0x49fe4 in shell () 
(gdb) thread 3 
[Switching to task 0x3aa9d8   tFtpdTask ] 
#0  0x66454 in semBTake () 
(gdb) print/x $i0 
$3 = 0x3bdb50

As in the display shown above, each time you switch threads the debugger exhibits the newly current thread's task ID and task name.

In system mode, unqualified breakpoints (set with graphical controls on the editor window, or in the Debugger window with the break command and a single argument) apply globally: any thread stops when it reaches such a breakpoint. You can also set thread-specific breakpoints, so that only one thread stops there.

To set a thread-specific breakpoint, append the word thread followed by a thread ID to the break command. For example:

(gdb) break printf thread 2 
Breakpoint 1 at 0x568b8 
(gdb) cont 
Continuing. 
[Switching to task 0x3a4bd8 + tShell    ] 
 
Breakpoint 1, 0x568b8 in printf ()

(gdb) i th 
  8 task 0x3b8ef0   tExcTask    0x9bfd0 in qJobGet () 
  7 task 0x3b6580   tLogTask    0x9bfd0 in qJobGet () 
  6 task 0x3b15b8   tNetTask    0x66454 in semBTake () 
  5 task 0x3ade80   tRlogind    0x66454 in semBTake () 
  4 task 0x3abf60   tTelnetd    0x66454 in semBTake () 
  3 task 0x3aa9d8   tFtpdTask   0x66454 in semBTake () 
* 2 task 0x3a4bd8 + tShell      0x568b8 in printf () 
  1 task 0x398688   tWdbTask    0x66454 in semBTake () 
(gdb) bt 
#0  0x568b8 in printf () 
#1  0x4a108 in execShell () 
#2  0x49fe4 in shell ()

Internally, the debugger still gets control every time any thread encounters the breakpoint; but if the thread ID is not the one you specified with the break command, the debugger silently continues program execution without prompting you.

Your program may not always suspend in the thread you expect. If any breakpoint or other event (such as an exception) occurs while in system mode, in any thread, the debugger gets control. Whenever the target system is stopped, the debugger switches to the thread that was executing. If the new current thread is different from the previous value, a message beginning with "Switching to" shows which thread is suspended:

(gdb) thread 2 
(gdb) cont 
Continuing. 
Interrupt... 
Program received signal SIGINT, Interrupt. 
[Switching to system +] 
 
0x5b58 in wdbSuspendSystemHere () 

Whenever the debugger does not have control, you can interrupt the target system by clicking Interrupt Debugger in the Debug menu, or by keying CTRL+BREAK. This usually suspends the target in the system thread rather than in any task.

When you step program execution (with any of the commands step, stepi, next, or nexti, or the equivalent buttons or ), the target resumes execution where it left off, which is in the thread marked + in the info threads display. However, in the course of stepping that thread, other threads may begin executing. The debugger may stop in another thread before the stepping command completes, due to an event in that other thread.

The debugger exploits Tcl at two levels: like other Tornado tools, it uses Tcl to build the graphical interface, but it also includes a Tcl interpreter at the GDB command level. This section discusses using the Tcl interpreter inside the Tornado enhanced GDB, at the command level.

To submit commands to the Tcl interpreter within GDB from the Tornado Debugger window, use the tcl command. For example:

(gdb) tcl info tclversion

This command reports which version of Tcl is integrated with GDB. All the text passed as arguments to the tcl command (in this example, info tclversion) is provided to the Tcl interpreter exactly as typed. Convenience variables (described in GDB User's Guide: Convenience Variables) are not expanded by GDB. However, Tcl scripts can force GDB to evaluate their arguments; see 10.7.3 Tcl: Invoking GDB Facilities.

You can also define Tcl procedures from the GDB command line. The following example procedure, mload, calls the load command for each file in a list:

(gdb) tcl proc mload args {foreach obj $args {gdb load $obj}}

You can run the new procedure from the GDB command line; for example:

(gdb) tcl mload vxColor.o priTst.o

To avoid typing tcl every time, use the tclproc command to assign a new GDB command name to the Tcl procedure. For example:

(gdb) tclproc mld mload

This command creates a new GDB command, mld. Now, instead of typing tcl mload, you can run mld as follows:

(gdb) mld vxColor.o priTst.o

You can collect Tcl procedures in a file, and load them into the GDB Tcl interpreter with this command:

(gdb) tcl source tclFile

If you develop a collection of Tcl procedures that you want to make available automatically in all your debugging sessions, write them in the file gdb.tcl. The GDB Tcl interpreter reads this file when it begins executing. (See 10.8.1 Tcl: Debugger Initialization Files for a discussion of where you can put this file, and of how all the Tornado debugger and GDB initialization files interact.)

The Tornado debugger (CrossWind) includes four commands to help you use Tcl. The first two were discussed in the previous section. The commands are:

Passes the remainder of the command line to the Tcl interpreter, without attempting to evaluate any of the text as a GDB command.

Creates a GDB command gdbName for a Tcl procedure named TclName. GDB does not evaluate the arguments when gdbName is invoked; it passes them to the Tcl procedure just as they were entered.

You can access GDB facilities from Tcl scripts with the following Tcl extensions:

Executes a GDB command (the converse of the GDB tcl command). Tcl evaluates the arguments, performing all applicable substitutions, then combines them (separated by spaces) into one string, which is passed to GDB's internal command interpreter for execution.

If the GDB command produces output, it is shown in the Debugger window.

If Tcl debugging is enabled (with tcldebug), the following message is printed:

    execute: command 

If the GDB command causes an error, the Tcl procedure gdb signals a Tcl error, which causes unwinding if not caught (for information about unwinding, see C.2.9 Tcl Error Handling).

Evaluates a list of expressions exprlist and returns a list of single integer values (in hexadecimal), one for each element of exprlist.⁴ If an expression represents a scalar value (such as int, long, or char), that value is returned. If an expression represents a float or double, the fractional part is truncated. If an expression represents an aggregate type, such as a structure or array, the address of the indicated object is returned. Standard rules for Tcl argument evaluation apply.

If Tcl debugging is enabled, the following message is printed for each expression:

    evaluate: expression 

If an expression does not evaluate to an object that can be cast to pointer type, an error message is printed, and gdbEvalScalar signals a Tcl error, which unwinds the Tcl stack if not caught (see C.2.9 Tcl Error Handling for information about unwinding).

Returns a Tcl list with four elements: the first source line number of fileName that corresponds to generated object code, the last such line number, the lowest object-code address from fileName in the target, and the highest object-code address from fileName in the target. The argument fileName must be the source file (.c, not .o) corresponding to code loaded in the target and in the debugger.

For example:

    (gdb) tcl gdbFileAddrInfo vxColor.c 
    {239 1058 0x39e2d0 0x39fbfc}

Returns a Tcl list with as many elements as there are source lines of fileName that correspond to generated object code. Each element of the list is itself a list with three elements: the source-file line number, the beginning address of object code for that line, and the ending address of object code for that line. The argument fileName must be the source file (.c, not .o) of a file corresponding to code loaded in the target and in the debugger.

For example:

    (gdb) tcl gdbFileLineInfo vxColor.c  
    {239 0x39e2d0 0x39e2d4} {244 0x39e2d4 0x39e2ec} ...

Redirects target input to file or device inFile, and target output and error streams to file or device outFile. If taskId is specified, redirect input and output only for that task; otherwise, redirect global input and output. To leave either input or output unchanged, specify the corresponding argument as a dash (-). Input may only be redirected to target files or devices; output may be redirected either to host files or to target files or devices. Ordinary path names indicate host files; arguments with an @ prefix indicate target files or devices. For target files, you may specify either a path name or a numeric file descriptor.

For example, the following command redirects all target output (including stderr) to host file grab.it:

    (gdb) tcl gdbIORedirect - grab.it

Closes all file descriptors opened on the host by the most recent gdbIoRedirect call.

Returns a list of names of local symbols for the current stack frame.

Returns a list of names of the routines currently on the stack.

Translates integer, interpreted as a target address, into an offset from the nearest target symbol. The display has the following format:

    symbolName [ + Offset ]

Offset is a decimal integer. If Offset is zero, it is not printed. For example:

    (gdb) tcl puts stdout [gdbSymbol 0x20000] 
    floatInit+2276

If Tcl debugging is on, gdbSymbol prints the following message:

    symbol: value 

Returns 1 if the specified symbol exists in any loaded symbol table, or 0 if not. You can use this command to test for the presence of a symbol without generating error messages from GDB if the symbol does not exist. This procedure cannot signal a Tcl error.

When Tcl debugging is on, gdbSymbolExists prints a message like the following:

    symbol exists: symbolName 

This section shows a Tcl procedure to traverse a linked list, printing information about each node.⁵ The example is tailored to a list where each node has the following structure:

A common method of list traversal in C is a for loop like the following:

We imitate this code in Tcl, with the important difference that all Tcl data is in strings, not pointers.

The argument to the Tcl procedure will be an expression (called head in our procedure) representing the first node of the list.

Use gdbEvalScalar to convert the GDB expression for a pointer into a Tcl string:

To get the pointer to the next element in the list:

Putting these lines together into a Tcl for loop, the procedure (in a form suitable for a Tcl script file) looks like the following:

In the body of the loop, the Tcl command puts prints the address of the node.

To type the procedure directly into the Debugger window would require prefacing the text above with the tcl command, and would require a backslash at the end of every line.

If pList is a variable of type (struct *node), you can execute:

(gdb) tcl traverse pList

The procedure displays the address of each node in the list. For a list with two elements, the output would look something like the following:

0xffeb00 
0xffea2c

It might be more useful to redefine the procedure body to print out the integer member data, instead. For example, replace the last line with the following:

You can bind a new GDB command to this Tcl procedure by using tclproc (typically, in the same Tcl script file as the procedure definition):

The traverse command can be abbreviated, like any GDB command. With these definitions, you can type the following command:

(gdb) trav pList

The output now exhibits the contents of each node in the list:

data = 1 
data = 2

Like every other Tornado tool, the debugger's graphical user interface is "soft" (amenable to customizing) because it is written in Tcl, which is an interpreted language. The Tornado API Reference describes the graphical building blocks available. You can also study the Tcl implementation of the debugger graphical interface itself, in host\resource\tcl\CrossWind.win32.tcl.

You can write Tcl code to customize the debugger's graphical presentation in a file called crosswind.tcl. The debugger looks for this file in two places: first under c:\tornado (or whatever directory you specify with the environment variable WIND_BASE), and then in the directory specified by the HOME environment variable (if that environment variable is defined). Use this file to collect your custom modifications, or to incorporate shared modifications from a central repository of Tcl extensions at your site.

Recall that the debugger uses two separate Tcl interpreters. Previous sections described the .gdbinit and gdb.tcl initialization files for the debugger command language (see 10.7 Tcl: Debugger Automation). The following outline summarizes the role of all the Tornado debugger customization files. The files are listed in the order in which they execute:

Use this file to customize the Tcl interpreter built into GDB itself (for example, to define Tcl procedures for new GDB commands). This file is unique to the Tornado debugger (that is, it is not shared by any other GDB configuration you might install). When issuing commands intended for GDB, you must prepend them with gdb.

The version of this file under installDir (for example, in installDir\.wind) is shared by everyone who uses Tornado on the same PC.

If more than one developer uses the same PC as a Tornado host, you can use this file just like the shared version of gdb.tcl described above, but for user-specific customizations; each user can specify a different directory in the HOME environment variable.

Use this file for any initialization you want to perform in GDB's command language rather than in Tcl. This file is not unique to the Tornado debugger; it is shared by any other GDB configuration you may install.

Akin to the .gdbinit in your home directory, the version of this file in the current working directory also contains commands in GDB's command language, and is not unique to the Tornado configuration of GDB. However, this file is specific to a particular working directory; thus it may be an appropriate place to record application-specific debugger settings.

Use this file to customize the debugger's graphical presentation, using Tcl--for example, to define new buttons or menu commands. This file is unique to the Tornado debugger (that is, it is not shared by any other GDB configuration you might install).

The version of this file under %WIND_BASE% is shared by everyone who uses Tornado on the same PC.

If other developers use the same PC as a Tornado host, you can use this file in the same way as the shared version of crosswind.tcl described above, but for user-specific customizations; each user can specify a different directory in the HOME environment variable.

You can prevent the Tornado debugger from looking for the two .gdbinit files, if you choose, by setting the internal GDB parameter inhibit-gdbinit to yes. Because the initialization files execute in the order they are listed above, you have the opportunity to set this parameter before the debugger reads either .gdbinit file. To do this, insert the following in gdb.tcl:

gdb set inhibit-gdbinit yes 

You can use the following specialized Tcl commands to pass control between the two Tornado debugger (CrossWind) Tcl interpreters:

From the Tcl interpreter integrated with the GDB command parser, uptcl executes the remainder of the line in the Tornado debugger graphical-interface Tcl interpreter. uptcl does not return a result.

From the graphical-interface layer, downtcl executes the remainder of the line in the Tcl interpreter integrated with GDB. The result of downtcl is whatever GDB output the command generates. Use downtcl rather than writeDebugInput if your goal is to capture the result for presentation in the graphical layer.

From the graphical-interface layer, writeDebugInput passes its string argument to GDB, exactly as if you had typed the argument in the command panel. A newline is not assumed; if you are writing a command and want it to be executed, include the newline character (\n) at the end of the string. Use writeDebugInput rather than downtcl if your goal is to make information appear in the command panel (this can be useful for providing information to other GDB prompts besides the command prompt).

The major use of uptcl is to experiment with customizing or extending the graphical interface. For example, if you have a file myXWind containing experimental Tcl code for extending the interface, you can try it out by entering the following in the Debugger window:

(gdb) tcl upctl source myXWind

By contrast, downtcl and writeDebugInput are likely to be embedded in Tcl procedures, because (in conjunction with the commands discussed in 10.7.3 Tcl: Invoking GDB Facilities) they are the path to debugger functionality from the graphical front end.

Most of the examples in 10.8.3 Tcl: Experimenting with Tornado Debugger Extensions, below, center around calls to downtcl.

The examples in this section use the Tcl extensions summarized in Table 10-3. For detailed descriptions of these and other Tornado graphical building blocks in Tcl, see Tornado API Programmer's Guide or the online Tornado API Reference.

As explained in 10.5.2 Selecting Modules to Debug, you sometimes need to tell the debugger explicitly to load symbols for modules that were downloaded to the target using other programs (such as the shell).

Example 10-1 illustrates a Debug menu command Add Symbols to handle this through the graphical user interface, instead of typing the add-symbol-file command.

In C++ programs, one particular named value has special interest: this, which is a pointer to the object where the currently executing routine is a member.

Example 10-2 defines a Debug menu command to launch an inspection window for the value where this points. The Tcl primitive catch is used in the definition in order to avoid propagating error conditions (for instance, if the buttons are pressed with no code loaded) from GDB back to the controlling Tornado debugger session.