This chapter presents a short tutorial for using the Debugger. The tutorial applies the Debugger to a program called jello, which provides a walk through some typical debugging situations. The tutorial is divided into four parts:
 | Note: WorkShop identifies files with the pathnames in which they were compiled. The pathnames in the tutorial may not match the ones on your system. |
In this part of the tutorial, you invoke the Debugger and start a typical process running. The jello program simulates an elastic polyhedron bouncing around inside of a revolving cube. The program's functionality is mainly contained in a single loop that calculates the acceleration, velocity, and position of the polyhedron's vertices.
Go to the directory /usr/demos/WorkShop/jello.
If the jello executable does not yet exist, type make jello
To invoke the Debugger, type cvd jello
The Main View window appears as shown in Figure 3-1. The display scrolls automatically to the main function.
Note: Main View brings up the source file in read-only mode to avoid inadvertent changes during debugging. You can change this mode by selecting "Make Editable" from the Source menu (provided you have the proper file access permissions). Click the Run button in the upper-right corner of the Main View to start the jello process.
The jello window opens on your display (see Figure 3-2). Enlarge this window to watch the program execute. The polyhedron is initially suspended in the center of the cube.
Click the left mouse button anywhere inside the jello window.
The polyhedron drops to the floor of the cube.
Hold down the right mouse button to display the pop-up menu and select "spin."
The cube now rotates and the polyhedron bounces. If you select "display" from the menu, you can change the appearance of the polyhedron: points only, lines only, full color, visible points only, or single color.
Note: You may encounter flashing colors inside windows while running jello. This is a normal side effect due to GL/X interaction.
This part of the tutorial covers the search facility in the Debugger. You will search through the jello source file for a function called spin. The spin function recalculates the position of the cube.
Choose "Search" from the Source menu.
The Search dialog box appears.
Type spin in the entry field in the Search dialog box, as shown in Figure 3-3.
Click the Apply button in the Search dialog box.
The search takes place. Each instance of "spin," the target string, is highlighted in the source code and flagged in the scroll bar to the right of the display area. Figure 3-4 shows typical search target indicators. The Next and Prev buttons let you move from one occurrence to the next in the order indicated. For more information on Search, see "Source Menu".
Click the Close button in the Search dialog box.
The dialog box disappears.
Click the middle mouse button on the last search target indicator.
This scrolls the source code down to the last occurrence, which is the location of the spin function.
Stop traps (also called breakpoints) stop the program's execution at a specified line in the code, allowing you to track the progress of your program and to check the values of variables at that point. Typically, you set breakpoints in your program prior to running it under the Debugger. For more information on traps, refer to Chapter 4, "Setting Traps."
In this part of the tutorial, you set a breakpoint at the spin function.
Click the left mouse button in the source code annotation column next to the line containing if ((a+=1)>3600) a -= 3600;.
A stop trap indicator appears in the annotation column as shown in Figure 3-5. This stop trap halts execution of jello at the beginning of the next call to the spin function. When the process stops, an icon indicating the current PC appears and the line becomes highlighted.
Click the Continue button at the upper-left corner of the Main View window repeatedly so that jello goes through several iterations.
The Continue button resumes execution until the next breakpoint (in this case, spin) is encountered. Stopping at the spin function allows you to view the jello image one frame at a time.
Select "Trap Manager" from the Views menu in Main View.
The Trap Manager window appears as shown in Figure 3-6.
Trap Manager lets you list, add, edit, disable, or remove traps in a process. You set one breakpoint in the spin function by clicking in the source code annotation column. This trap is displayed in the trap display area.
You can define other traps as well in the Trap Manager. You set conditional traps in the Condition field from the top. The count information lets you specify the number of times a trap should be encountered before it fires. The trap controls let you manipulate traps. All traps (active and inactive) are shown in the trap display area.
Click the button to the left of the stop trap in the trap display area.
The trap is temporarily disabled. Trap Manager lets you turn traps on and off by clicking them.
Click the Clear button, move the cursor to the Trap: field, type
watch display_mode
This sets a watchpoint for the variable display_mode. A watchpoint is a trap that fires when a specified variable or address is read, written, or executed.
After you continue the process, you can fire this watchpoint by holding down the right mouse button in the jello window and selecting "display" and a different display option. The variable display_mode is accessed and the watchpoint fires.
Click the Continue button to restart the process.
The process now runs somewhat slower but still at a reasonable speed for debugging.
Hold down the right mouse button in the jello window to display the popup menu, and select "display" and then the "conecs" option with the right button.
This triggers the watchpoint and stops the process. If you were tracking the effects of changing display modes, you could bring up other views now.
Go to the Trap Manager window and click the button next to the display_mode watchpoint to deactivate it. Click the button next to the spin stop trap to reactivate it.
This resets the traps for use in this tutorial.
Enter 100 in the Cycle Count field, press <Enter>, and click the Continue button in Main View.
This takes the process through the stop trap for the specified number of times, provided no other interruptions occur. The Current Count field keeps track of the actual number of iterations since the last stop, which is useful if an interrupt occurs. Note that it updates at interrupts only.
Select "Close" from the Admin menu in Trap Manager to close it.
This part of the tutorial describes how to examine data after the process stops.
Select "Call Stack" from the Views menu in Main View.
The Call Stack View window appears as in Figure 3-7. The Call Stack View window shows each frame in the call stack at the time of the breakpoint with the calling parameters and their values. You can also display the calling parameters' types, locations, and PC (program counter) through the Display menu. For more information, see "Tracing Through Call Stack View".
In this example, the spin and main stack frames are displayed in Call Stack View, and the spin stack frame is highlighted, indicating that it is the current stack frame.
Pull down the Admin menu and examine the "Active" selection.
By default, the "Active" toggle button in the Admin menu is turned on. Active views are those that have been specified to change their contents at stops or at call stack context changes. If the toggle is on, the call stack is updated automatically whenever the process stops.
Double-click the main stack frame.
This shifts the stack frame to the main function, scrolls the source code in Main View (or Source View) to the place in main where spin was called, and highlights the call in the designated context color. Any active views are updated according to the new stack frame.
Double-click the spin stack frame.
Select "Variable Browser" from the Views menu in Main View.
The Variable Browser window appears. This window shows you the value of local variables at the breakpoint. The variables appear in the left column (read-only), and the corresponding values appear in the right column (editable). Since the right column is editable, you can change the values of the variables if you want.
Your Variable Browser window should resemble the one in Figure 3-8, although you may need to enlarge the window to see all the variables (the values will be different).
The jello program uses variables a, b, and c as angles (in tenths); ca, cb, cc as their corresponding cosines; and sa, sb, sc as their sines. Whenever you stop at spin, these values change.
Double-click some different frames in Call Stack View and observe the changes to Variable Browser and Main View.
These views update appropriately whenever you change frames in Call Stack View. Notice also the change indicators in the upper right corners of the Result fields (see Figure 3-9). These appear if the value has changed. If you click the "folded" corner, the previous value displays (and the indicator appears "unfolded"). You can then toggle back to the current value.
Select "Close" from the Admin menu in Variable Browser and "Close" from the Admin menu in Call Stack View to close them.
Select "Expression View" from the Views menu in Main View.
The Expression View window appears. It lets you evaluate an expression involving data from the process. The expression can be typed in or more conveniently cut and pasted from your source code. You can view the value of variables (or expressions involving variables) any time the process stops. Enter the expression in the left column, and the corresponding value appears in the right column. For more information, see "Evaluating Expressions".
Hold down the right mouse button in the Expression column to bring up the Language menu. Then hold down the right mouse button in the Result column to display the Format menu.
The Language menu (shown on the left side of Figure 3-10) lets you apply the language semantics to the expression.
The Format menu (shown on the right side of Figure 3-10) lets you view the value, type, address, or size of the result. You can further specify the display format for the value and address.
Click on the first Expression field in the Expression View window. Then enter (a+1)>3600 in the field and press <Enter>.
This is a test performed in jello to ensure that the value of a is less than 3600. This uses the variable a that was displayed previously in Variable Browser. After you press <Enter>, the result is displayed in the right column; 0 signifies false.
Select "Close" from the Admin menu in Expression View to close it.
Select "Structure Browser" from the Views menu in Main View.
Enter jello_conec in the Expression field and press <Enter>.
The Structure Browser displays the structure for the given expression; field names are displayed in the left column, and values in the right column. If only pointers are available, Structure Browser will dereference the pointers automatically until actual values are encountered. You can then perform any further dereferencing by double-clicking pointer addresses in the right column of the data structure objects. A window similar to the one shown in Figure 3-11 now appears.
Click once to focus, then double-click the address of the next field (in the right column of the jello_conec structure).
Double-clicking the address corresponding to a pointer field dereferences it. Double-clicking the field name displays the complete name of the field in the Expression field at the top of the Structure Browser window. (See Figure 3-12.)
Select "Close" from the Admin menu in Structure Browser to close it.
Select "Array Browser" from the Views menu in Main View.
The Array Browser lets you see or change values in an array variable. It is particularly valuable for finding bad data in an array or for testing the effects of values you enter.
Type shadow in the Array field and press <Enter>.
You can now see the values of the shadow matrix, which displays the polyhedron's shadow on the cube. The Array Browser template should resemble Figure 3-13 but with different data values. If any fields are hidden, you can drag the sash buttons at the right of the window to expose them.
Select the Col button next to the $k index.
The Array Browser can handle matrices containing up to six dimensions but displays only two dimensions at a time. Selecting the Col button for $k has the effect of switching from a display of $i by $j to $i by $k.
Figure 3-14 shows a close-up view of the subscript control area.
The row/column toggles indicate whether a vector appears as a row, column, or not at all in the spreadsheet area. Although any number of vectors can reside in an array, you can view only two vectors at a time. The index values show the number of elements in a vector and are used to change the dimensions of the matrix. The index sliders let you move the focus cell along the particular vector. The index minimums and index maximums identify the beginning and ending elements, respectively, in the vectors. Use the horizontal and vertical scroll bars to expose hidden portions of the Array Browser window.
Select "Surface" from the Render menu.
The Render menu displays the data from the selected array variable graphically, in this case as a three-dimensional surface. The selected cell is highlighted by a rectangular prism. The selected subscripts correspond to the x- and y-axes in the rendering; the corresponding value is plotted on the z-axis. The data can be rendered as a surface, bar chart, multiple lines, or points.
Select "Exit" from the Admin menu in Main View to end this tutorial.
