share/insight1.0/help/trace/source.html - toolchains/skids - Git at Google

 <HTML>
 <HEAD>
 <TITLE>Source Window Help</TITLE>
 </HEAD>
 <BODY>
 <CENTER><H1>The Source Window</H1></CENTER>
 <H3>Overview</H3>
 <BR>
 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.

 <P>Source Window topics:
 <UL>
     <LI><UL><A HREF="#menus">Menus</A>
             <LI><A HREF="#menus_file">File Menu</A>
             <LI><A HREF="#menus_run">Run Menu</A>
             <LI><A HREF="#menus_view">View Menu</A>
             <LI><A HREF="#menus_trace">Trace Menu</A>
             <LI><A HREF="#menus_prefs">Preferences Menu</A>
         </UL>
     <LI><UL><A HREF="#toolbar">Toolbar</A>
             <LI><A HREF="#toolbar_exec">Trace Control Buttons</A>
             <LI><A HREF="#toolbar_window">Window Buttons</A>
             <LI><A HREF="#toolbar_frame">Frame Control</A>
         </UL>
     <LI><UL><A HREF="#display">Source Window Display</A>
             <LI><A HREF="#display_balloon">Variable Balloons</A>
             <LI><A HREF="#display_popup">Source Pop-up Mens</A>
         </UL>
     <LI><UL><A HREF="#status">Source Window Status Bars</A>
             <LI><A HREF="#status_bar">Program Status Bar</A>
             <LI><A HREF="#status_mode">Source Display Status Bar</A>
         </UL>
     <LI><A HREF="#search">Search Entry</A>
 </UL></P>

 <H3><A NAME="menus">Menus</A></H3>
 <H4><A NAME="menus_file">File Menu</A></H4>
 The File menu contains the following items:
 <DL>
     <DT>Open
         <DD>Opens a file selection dialog to select the executable to debug
     <DT>Target Settings...
         <DD>Opens the <A HREF="target.html">Target Selection Dialog</A>
             to edit target settings
     <DT>Page Setup
         <DD>(Windows only) Opens the Windows Page Setup dialog to
             configure printing
     <DT>Print
         <DD>(Windows only) Print the contents of the Source Window Display
     <DT>Exit
         <DD>Exits the debugger
 </DL>

 <H4><A NAME="menus_run">Run Menu</A></H4>
 The Run menu contains the following items:
 <DL>
     <DT>Connect to target
         <DD>Establish a connection to a target. This option will open
             the <A HREF="target.html">Target Selection Dialog</A> if no
             previous connection has been established in the current
             session.
     <DT>Begin Collection
         <DD>Start collecting trace data on the target
     <DT>End Collection
         <DD>Stop collecting trace data on the target
     <DT>Disconnect
         <DD>Disconnect the debugger from the target
 </DL>

 <H4><A NAME="menus_view">View Menu</A></H4>
 The View menu contains the following items:
 <DL>
     <DT>Stack
         <DD>Open a <A HREF="stack.html">Stack Window</A>
     <DT>Registers
         <DD>Open a <A HREF="register.html">Register Window</A>
     <DT>Memory
         <DD>Open a <A HREF="memory.html">Memory Window</A>
     <DT>Watch Expressions
         <DD>Open a <A HREF="watch.html">Watch Window</A>
     <DT>Local Variables
         <DD>Open a <A HREF="locals.html">Locals Window</A>
     <DT>Tracepoints
         <DD>Open a <A HREF="tp.html">Tracepoint Window</A>
     <DT>Tdump
         <DD>Open a <A HREF="tdump.html">Tracepoint Dump Window</A>
     <DT>Console
         <DD>Open a <A HREF="console.html">Console Window</A>
 </DL>

 <H4><A NAME="menus_trace">Trace Menu</A></H4>
 The Trace Menu contains the following items:
 <DL>
     <DT>Next Hit
         <DD>Update all displays with the next tracepoint in the
             tracepoint buffer
     <DT>Previous Hit
         <DD>Go to the previous tracepoint in the buffer
     <DT>First Hit
         <DD>View the first tracepoint in the buffer
     <DT>Next Line Hit
         <DD>Go to the next tracepoint in the buffer in the same
             frame as the current tracepoint
     <DT>Next Hit Here
         <DD>Jump to the next reference of the current tracepoint
             in the buffer
     <DT>Tfind Line...
         <DD>Opens a dialog allowing the user to specify which source
             line to inpect in the tracepoint buffer
     <DT>Tfind PC...
         <DD>Opens a dialog allowing the user to specify the PC of the
             tracepoint to view
     <DT>Tfind Tracepoint...
         <DD>Opens a dialog allowing the user to specify which tracepoint
             to view (by number). This option is most commonly used in
             conjunction with the <A HREF="console.html">Console Window</A>.
 </DL>

 <H4><A NAME="menus_prefs">Preferences Menu</A></H4>
 The Preferences menu contains the following items:
 <DL>
     <DT>Global
         <DD>Opens the <A HREF="gbl_pref.html">Global Preferences Dialog</A>
             and allows editing of global settings
     <DT>Source
         <DD>Opens the <A HREF="src_pref.html">Source Preferences Dialog</A>
             and allows editing of Source Window settings
     <DT>Register
         <DD>Opens the <A HREF="reg_pref.html">Register Preferences Dialog</A>
             and allows editing of Register Window settings
 </DL>

 <H3><A NAME="toolbar">Toolbar</A></H3>
 The Source Window toolbar consists of three functional sections: trace
 control buttons, debugger window buttons, and stack frame control buttons.
 <BR>

 <H4><A NAME="toolbar_exec">Tracing Control Buttons</A></H4>
 These convenience buttons provide on-screen access to the most important
 debugger tracing control functions:
 <DL>
     <DT><A NAME="run_button"><IMG SRC="%run"> TStart</A> or
         <A NAME="stop_button"><IMG SRC="%stop"></A> TStop
          <DD>The TStart Button causes the target to start collecting trace data
          <DD>The TStop Button causes the target to stop collecting trace data
     <DT>Next Hit
         <DD>Update all displays with the next tracepoint in the
             tracepoint buffer
     <DT>Previous Hit
         <DD>Go to the previous tracepoint in the buffer
     <DT>First Hit
         <DD>View the first tracepoint in the buffer
     <DT>Next Line Hit
         <DD>Go to the next tracepoint in the buffer in the same
             frame as the current tracepoint
     <DT>Next Hit Here
         <DD>Jump to the next reference of the current tracepoint
             in the buffer
 </DL>

 <H4><A NAME="toolbar_window">Window Buttons</A></H4>
 The Debugger Window buttons give instant access to the Debugger's
 auxillary windows:
 <DL>
     <DT><A NAME="register_button"><IMG SRC="%register"></A> Registers
         <DD>Open a <A HREF="register.html">Register Window</A>
     <DT><A NAME="memory_button"><IMG SRC="%memory"></A> Memory
         <DD>Open a <A HREF="memory.html">Memory Window</A>
     <DT><A NAME="stack_button"><IMG SRC="%stack"></A> Stack
         <DD>Open a <A HREF="stack.html">Stack Window</A>
     <DT><A NAME="watch_button"><IMG SRC="%watch"></A> Watch Expressions
         <DD>Open a <A HREF="watch.html">Watch Window</A>
     <DT><A NAME="locals_button"><IMG SRC="%locals"></A> Local Variables
         <DD>Open a <A HREF="locals.html">Locals Window</A>
     <DT><A NAME="tracepoints_button">Tracepoints</A>
         <DD>Open a <A HREF="tp.html">Tracepoint Window</A>
     <DT>Tracepoint Dump Window
         <DD>Open a <A HREF="tdump.html">Tdump Window</A>
     <DT><A NAME="console_button"><IMG SRC="%console"></A> Console
         <DD>Open a <A HREF="console.html">Console Window</A>
 </DL>

 <H4><A NAME="toolbar_frame">Frame Control</A></H4>
 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 <A HREF="stack.html">Stack Window</A> will
 show the selected frame. In order to use the Stack Window in tracing mode,
 the stack pointer must be collected.
 <DL>
     <!-- is this a problem for windows? no file join? -->
     <DT><IMG SRC="images/frame_info.gif"> Frame Information Display
         <DD>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.
     <DT><A NAME="up_button"><IMG SRC="%up"></A> Up
         <DD>Select and view the stack frame that called this one
     <DT><A NAME="down_button"><IMG SRC="%down"></A> Down
         <DD>Select and view the stack frame called by this one
     <DT><A NAME="bottom_button"><IMG SRC="%bottom"></A> Bottom
         <DD>Select and view the bottom-most stack frame
 </DL>

 <H3><A NAME="display">Source Display</A></H3>
 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.

 <P>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 <A HREF="src_pref.html">Source Preferences</A>.</P>
 <BR>

 <H4><A NAME="setting_a_tracepoint">Setting a Tracepoint</A></H4>
 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
 <A HREF="tracedlg.html">Add Tracepoint Dialog</A> will appear. If a tracepoint
 is installed, the dash in the left margin will change into a magenta breakdot.
 If a tracepoint exists, the <A HREF="tracedlg.html">Edit Tracepoint Dialog</A>
 appears, allowing either modification of the tracepoint or deletion of the
 tracepoint. If the tracepoint is deleted, the breakdot will revert to a dash.</P>

 <P>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.</P>

 <P>The display will attempt to show the value of variables in
 <A NAME="display_balloon">variable balloons</A>. 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.</P>
 <BR>

 <H4><A NAME="display_popup">Source Pop-up Menus</A></H4>
 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:
 <DL>
     <DT>Set Tracepoint
         <DD>Opens the <A HREF="#tracedlg">Add/Edit Tracepoint Dialog</A>,
             which allows new tracepoints to be set and modification and
             deletion of existing tracepoints.
 </DL>

 <P>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:
 <DL>
     <DT><A NAME="add_to_watch">Add <I>expr</I> to Watch</A>
         <DD>Adds the selected expression to the <A HREF="watch.html">Watch
             Window</A>, opening it, if necessary.
     <DT>Dump Memory at <I>expr</I>
         <DD>Opens a new <A HREF="memory.html">Memory Window</A> 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.
     <DT>Set Tracepoint Range
         <DD>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.
 </DL>
 </P>

 <H4><A NAME="status">Source Window Status Bars</A></H4>
 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.

 <P>The <A NAME="status_bar">Program Status Bar</A> (or simply "Status Bar")
 displays the status of the program. Common messages seen here include:
 <DL>
     <DT>No program loaded.
         <DD>No program has been loaded into target memory.
     <DT>Inspecting trace at <I>line/address</I>
         <DD>The debugger is inspecting the tracepoint at line
             <I>line</I> or address <I>address</I>. Use the
             <A HREF="#toolbar_exec">Tracing Control Buttons</A>
             to navigate through the trace buffer.
 </DL>
 <P>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.</P>
 <BR>

 <H4><A NAME="status_mode">Source Display Status Bar</A></H4>
 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.

 <P>The <A NAME="file_selector">Source File Selector</A> is a dropdown
 menu which contains the names of all the files that were compiled into
 the program being debugged.</P>

 <P>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
 <A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>

 <P>The <A NAME="function_selector">Source Function Selector</A> 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
 <A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>

 <P>The <A NAME="mode_selector">Source Display Mode Selector</A> displays
 the viewing mode of the current file/function shown in the Source
 Window Display.</P>

 <P>The Display Mode Selector may be used to change the view of the current
 source file. The available display modes are
 <DL>
     <DT>SOURCE
         <DD>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".
     <DT>ASSEMBLY
         <DD>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.
     <DT>MIXED
         <DD>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.
     <DT>SRC+ASM
         <DD>The Source Window Display is divided into two panes: an
             assembly pane and a source pane. Tracepoints may be set/cleared
             in either pane.
 </DL>
 <BR>

 <H3><A NAME="search">Search Entry</A></H3>
 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.

 <P>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.</P>
 </BODY>
 </HTML>
	<HTML>
	<HEAD>
	<TITLE>Source Window Help</TITLE>
	</HEAD>
	<BODY>
	<CENTER><H1>The Source Window</H1></CENTER>
	<H3>Overview</H3>
	<BR>
	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.

	<P>Source Window topics:
	<UL>
	<LI><UL><A HREF="#menus">Menus</A>
	<LI><A HREF="#menus_file">File Menu</A>
	<LI><A HREF="#menus_run">Run Menu</A>
	<LI><A HREF="#menus_view">View Menu</A>
	<LI><A HREF="#menus_trace">Trace Menu</A>
	<LI><A HREF="#menus_prefs">Preferences Menu</A>
	</UL>
	<LI><UL><A HREF="#toolbar">Toolbar</A>
	<LI><A HREF="#toolbar_exec">Trace Control Buttons</A>
	<LI><A HREF="#toolbar_window">Window Buttons</A>
	<LI><A HREF="#toolbar_frame">Frame Control</A>
	</UL>
	<LI><UL><A HREF="#display">Source Window Display</A>
	<LI><A HREF="#display_balloon">Variable Balloons</A>
	<LI><A HREF="#display_popup">Source Pop-up Mens</A>
	</UL>
	<LI><UL><A HREF="#status">Source Window Status Bars</A>
	<LI><A HREF="#status_bar">Program Status Bar</A>
	<LI><A HREF="#status_mode">Source Display Status Bar</A>
	</UL>
	<LI><A HREF="#search">Search Entry</A>
	</UL></P>

	<H3><A NAME="menus">Menus</A></H3>
	<H4><A NAME="menus_file">File Menu</A></H4>
	The File menu contains the following items:
	<DL>
	<DT>Open
	<DD>Opens a file selection dialog to select the executable to debug
	<DT>Target Settings...
	<DD>Opens the <A HREF="target.html">Target Selection Dialog</A>
	to edit target settings
	<DT>Page Setup
	<DD>(Windows only) Opens the Windows Page Setup dialog to
	configure printing
	<DT>Print
	<DD>(Windows only) Print the contents of the Source Window Display
	<DT>Exit
	<DD>Exits the debugger
	</DL>

	<H4><A NAME="menus_run">Run Menu</A></H4>
	The Run menu contains the following items:
	<DL>
	<DT>Connect to target
	<DD>Establish a connection to a target. This option will open
	the <A HREF="target.html">Target Selection Dialog</A> if no
	previous connection has been established in the current
	session.
	<DT>Begin Collection
	<DD>Start collecting trace data on the target
	<DT>End Collection
	<DD>Stop collecting trace data on the target
	<DT>Disconnect
	<DD>Disconnect the debugger from the target
	</DL>

	<H4><A NAME="menus_view">View Menu</A></H4>
	The View menu contains the following items:
	<DL>
	<DT>Stack
	<DD>Open a <A HREF="stack.html">Stack Window</A>
	<DT>Registers
	<DD>Open a <A HREF="register.html">Register Window</A>
	<DT>Memory
	<DD>Open a <A HREF="memory.html">Memory Window</A>
	<DT>Watch Expressions
	<DD>Open a <A HREF="watch.html">Watch Window</A>
	<DT>Local Variables
	<DD>Open a <A HREF="locals.html">Locals Window</A>
	<DT>Tracepoints
	<DD>Open a <A HREF="tp.html">Tracepoint Window</A>
	<DT>Tdump
	<DD>Open a <A HREF="tdump.html">Tracepoint Dump Window</A>
	<DT>Console
	<DD>Open a <A HREF="console.html">Console Window</A>
	</DL>

	<H4><A NAME="menus_trace">Trace Menu</A></H4>
	The Trace Menu contains the following items:
	<DL>
	<DT>Next Hit
	<DD>Update all displays with the next tracepoint in the
	tracepoint buffer
	<DT>Previous Hit
	<DD>Go to the previous tracepoint in the buffer
	<DT>First Hit
	<DD>View the first tracepoint in the buffer
	<DT>Next Line Hit
	<DD>Go to the next tracepoint in the buffer in the same
	frame as the current tracepoint
	<DT>Next Hit Here
	<DD>Jump to the next reference of the current tracepoint
	in the buffer
	<DT>Tfind Line...
	<DD>Opens a dialog allowing the user to specify which source
	line to inpect in the tracepoint buffer
	<DT>Tfind PC...
	<DD>Opens a dialog allowing the user to specify the PC of the
	tracepoint to view
	<DT>Tfind Tracepoint...
	<DD>Opens a dialog allowing the user to specify which tracepoint
	to view (by number). This option is most commonly used in
	conjunction with the <A HREF="console.html">Console Window</A>.
	</DL>

	<H4><A NAME="menus_prefs">Preferences Menu</A></H4>
	The Preferences menu contains the following items:
	<DL>
	<DT>Global
	<DD>Opens the <A HREF="gbl_pref.html">Global Preferences Dialog</A>
	and allows editing of global settings
	<DT>Source
	<DD>Opens the <A HREF="src_pref.html">Source Preferences Dialog</A>
	and allows editing of Source Window settings
	<DT>Register
	<DD>Opens the <A HREF="reg_pref.html">Register Preferences Dialog</A>
	and allows editing of Register Window settings
	</DL>

	<H3><A NAME="toolbar">Toolbar</A></H3>
	The Source Window toolbar consists of three functional sections: trace
	control buttons, debugger window buttons, and stack frame control buttons.
	<BR>

	<H4><A NAME="toolbar_exec">Tracing Control Buttons</A></H4>
	These convenience buttons provide on-screen access to the most important
	debugger tracing control functions:
	<DL>
	<DT><A NAME="run_button"><IMG SRC="%run"> TStart</A> or
	<A NAME="stop_button"><IMG SRC="%stop"></A> TStop
	<DD>The TStart Button causes the target to start collecting trace data
	<DD>The TStop Button causes the target to stop collecting trace data
	<DT>Next Hit
	<DD>Update all displays with the next tracepoint in the
	tracepoint buffer
	<DT>Previous Hit
	<DD>Go to the previous tracepoint in the buffer
	<DT>First Hit
	<DD>View the first tracepoint in the buffer
	<DT>Next Line Hit
	<DD>Go to the next tracepoint in the buffer in the same
	frame as the current tracepoint
	<DT>Next Hit Here
	<DD>Jump to the next reference of the current tracepoint
	in the buffer
	</DL>

	<H4><A NAME="toolbar_window">Window Buttons</A></H4>
	The Debugger Window buttons give instant access to the Debugger's
	auxillary windows:
	<DL>
	<DT><A NAME="register_button"><IMG SRC="%register"></A> Registers
	<DD>Open a <A HREF="register.html">Register Window</A>
	<DT><A NAME="memory_button"><IMG SRC="%memory"></A> Memory
	<DD>Open a <A HREF="memory.html">Memory Window</A>
	<DT><A NAME="stack_button"><IMG SRC="%stack"></A> Stack
	<DD>Open a <A HREF="stack.html">Stack Window</A>
	<DT><A NAME="watch_button"><IMG SRC="%watch"></A> Watch Expressions
	<DD>Open a <A HREF="watch.html">Watch Window</A>
	<DT><A NAME="locals_button"><IMG SRC="%locals"></A> Local Variables
	<DD>Open a <A HREF="locals.html">Locals Window</A>
	<DT><A NAME="tracepoints_button">Tracepoints</A>
	<DD>Open a <A HREF="tp.html">Tracepoint Window</A>
	<DT>Tracepoint Dump Window
	<DD>Open a <A HREF="tdump.html">Tdump Window</A>
	<DT><A NAME="console_button"><IMG SRC="%console"></A> Console
	<DD>Open a <A HREF="console.html">Console Window</A>
	</DL>

	<H4><A NAME="toolbar_frame">Frame Control</A></H4>
	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 <A HREF="stack.html">Stack Window</A> will
	show the selected frame. In order to use the Stack Window in tracing mode,
	the stack pointer must be collected.
	<DL>
	<!-- is this a problem for windows? no file join? -->
	<DT><IMG SRC="images/frame_info.gif"> Frame Information Display
	<DD>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.
	<DT><A NAME="up_button"><IMG SRC="%up"></A> Up
	<DD>Select and view the stack frame that called this one
	<DT><A NAME="down_button"><IMG SRC="%down"></A> Down
	<DD>Select and view the stack frame called by this one
	<DT><A NAME="bottom_button"><IMG SRC="%bottom"></A> Bottom
	<DD>Select and view the bottom-most stack frame
	</DL>

	<H3><A NAME="display">Source Display</A></H3>
	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.

	<P>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 <A HREF="src_pref.html">Source Preferences</A>.</P>
	<BR>

	<H4><A NAME="setting_a_tracepoint">Setting a Tracepoint</A></H4>
	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
	<A HREF="tracedlg.html">Add Tracepoint Dialog</A> will appear. If a tracepoint
	is installed, the dash in the left margin will change into a magenta breakdot.
	If a tracepoint exists, the <A HREF="tracedlg.html">Edit Tracepoint Dialog</A>
	appears, allowing either modification of the tracepoint or deletion of the
	tracepoint. If the tracepoint is deleted, the breakdot will revert to a dash.</P>

	<P>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.</P>

	<P>The display will attempt to show the value of variables in
	<A NAME="display_balloon">variable balloons</A>. 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.</P>
	<BR>

	<H4><A NAME="display_popup">Source Pop-up Menus</A></H4>
	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:
	<DL>
	<DT>Set Tracepoint
	<DD>Opens the <A HREF="#tracedlg">Add/Edit Tracepoint Dialog</A>,
	which allows new tracepoints to be set and modification and
	deletion of existing tracepoints.
	</DL>

	<P>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:
	<DL>
	<DT><A NAME="add_to_watch">Add <I>expr</I> to Watch</A>
	<DD>Adds the selected expression to the <A HREF="watch.html">Watch
	Window</A>, opening it, if necessary.
	<DT>Dump Memory at <I>expr</I>
	<DD>Opens a new <A HREF="memory.html">Memory Window</A> 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.
	<DT>Set Tracepoint Range
	<DD>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.
	</DL>
	</P>

	<H4><A NAME="status">Source Window Status Bars</A></H4>
	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.

	<P>The <A NAME="status_bar">Program Status Bar</A> (or simply "Status Bar")
	displays the status of the program. Common messages seen here include:
	<DL>
	<DT>No program loaded.
	<DD>No program has been loaded into target memory.
	<DT>Inspecting trace at <I>line/address</I>
	<DD>The debugger is inspecting the tracepoint at line
	<I>line</I> or address <I>address</I>. Use the
	<A HREF="#toolbar_exec">Tracing Control Buttons</A>
	to navigate through the trace buffer.
	</DL>
	<P>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.</P>
	<BR>

	<H4><A NAME="status_mode">Source Display Status Bar</A></H4>
	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.

	<P>The <A NAME="file_selector">Source File Selector</A> is a dropdown
	menu which contains the names of all the files that were compiled into
	the program being debugged.</P>

	<P>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
	<A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>

	<P>The <A NAME="function_selector">Source Function Selector</A> 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
	<A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>

	<P>The <A NAME="mode_selector">Source Display Mode Selector</A> displays
	the viewing mode of the current file/function shown in the Source
	Window Display.</P>

	<P>The Display Mode Selector may be used to change the view of the current
	source file. The available display modes are
	<DL>
	<DT>SOURCE
	<DD>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".
	<DT>ASSEMBLY
	<DD>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.
	<DT>MIXED
	<DD>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.
	<DT>SRC+ASM
	<DD>The Source Window Display is divided into two panes: an
	assembly pane and a source pane. Tracepoints may be set/cleared
	in either pane.
	</DL>
	<BR>

	<H3><A NAME="search">Search Entry</A></H3>
	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.

	<P>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.</P>
	</BODY>
	</HTML>