OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [gdbtcl/] [help/] [trace/] [source.html] - Blame information for rev 1767

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
<HTML>
2
<HEAD>
3
<TITLE>Source Window Help</TITLE>
4
</HEAD>
5
<BODY>
6
<CENTER><H1>The Source Window</H1></CENTER>
7
<H3>Overview</H3>
8
<BR>
9
The Source Window is the primary interface between the user and the
10
debugger; it is automatically opened when the debugger starts.
11
The Source Window displays the status of the trace experiment, controls
12
navigation of the trace buffer, and allows visualization of the program
13
execution.
14
 
15
<P>Source Window topics:
16
<UL>
17
    <LI><UL><A HREF="#menus">Menus</A>
18
            <LI><A HREF="#menus_file">File Menu</A>
19
            <LI><A HREF="#menus_run">Run Menu</A>
20
            <LI><A HREF="#menus_view">View Menu</A>
21
            <LI><A HREF="#menus_trace">Trace Menu</A>
22
            <LI><A HREF="#menus_prefs">Preferences Menu</A>
23
        </UL>
24
    <LI><UL><A HREF="#toolbar">Toolbar</A>
25
            <LI><A HREF="#toolbar_exec">Trace Control Buttons</A>
26
            <LI><A HREF="#toolbar_window">Window Buttons</A>
27
            <LI><A HREF="#toolbar_frame">Frame Control</A>
28
        </UL>
29
    <LI><UL><A HREF="#display">Source Window Display</A>
30
            <LI><A HREF="#display_balloon">Variable Balloons</A>
31
            <LI><A HREF="#display_popup">Source Pop-up Mens</A>
32
        </UL>
33
    <LI><UL><A HREF="#status">Source Window Status Bars</A>
34
            <LI><A HREF="#status_bar">Program Status Bar</A>
35
            <LI><A HREF="#status_mode">Source Display Status Bar</A>
36
        </UL>
37
    <LI><A HREF="#search">Search Entry</A>
38
</UL></P>
39
 
40
<H3><A NAME="menus">Menus</A></H3>
41
<H4><A NAME="menus_file">File Menu</A></H4>
42
The File menu contains the following items:
43
<DL>
44
    <DT>Open
45
        <DD>Opens a file selection dialog to select the executable to debug
46
    <DT>Target Settings...
47
        <DD>Opens the <A HREF="target.html">Target Selection Dialog</A>
48
            to edit target settings
49
    <DT>Page Setup
50
        <DD>(Windows only) Opens the Windows Page Setup dialog to
51
            configure printing
52
    <DT>Print
53
        <DD>(Windows only) Print the contents of the Source Window Display
54
    <DT>Exit
55
        <DD>Exits the debugger
56
</DL>
57
 
58
<H4><A NAME="menus_run">Run Menu</A></H4>
59
The Run menu contains the following items:
60
<DL>
61
    <DT>Connect to target
62
        <DD>Establish a connection to a target. This option will open
63
            the <A HREF="target.html">Target Selection Dialog</A> if no
64
            previous connection has been established in the current
65
            session.
66
    <DT>Begin Collection
67
        <DD>Start collecting trace data on the target
68
    <DT>End Collection
69
        <DD>Stop collecting trace data on the target
70
    <DT>Disconnect
71
        <DD>Disconnect the debugger from the target
72
</DL>
73
 
74
<H4><A NAME="menus_view">View Menu</A></H4>
75
The View menu contains the following items:
76
<DL>
77
    <DT>Stack
78
        <DD>Open a <A HREF="stack.html">Stack Window</A>
79
    <DT>Registers
80
        <DD>Open a <A HREF="register.html">Register Window</A>
81
    <DT>Memory
82
        <DD>Open a <A HREF="memory.html">Memory Window</A>
83
    <DT>Watch Expressions
84
        <DD>Open a <A HREF="watch.html">Watch Window</A>
85
    <DT>Local Variables
86
        <DD>Open a <A HREF="locals.html">Locals Window</A>
87
    <DT>Tracepoints
88
        <DD>Open a <A HREF="tp.html">Tracepoint Window</A>
89
    <DT>Tdump
90
        <DD>Open a <A HREF="tdump.html">Tracepoint Dump Window</A>
91
    <DT>Console
92
        <DD>Open a <A HREF="console.html">Console Window</A>
93
</DL>
94
 
95
<H4><A NAME="menus_trace">Trace Menu</A></H4>
96
The Trace Menu contains the following items:
97
<DL>
98
    <DT>Next Hit
99
        <DD>Update all displays with the next tracepoint in the
100
            tracepoint buffer
101
    <DT>Previous Hit
102
        <DD>Go to the previous tracepoint in the buffer
103
    <DT>First Hit
104
        <DD>View the first tracepoint in the buffer
105
    <DT>Next Line Hit
106
        <DD>Go to the next tracepoint in the buffer in the same
107
            frame as the current tracepoint
108
    <DT>Next Hit Here
109
        <DD>Jump to the next reference of the current tracepoint
110
            in the buffer
111
    <DT>Tfind Line...
112
        <DD>Opens a dialog allowing the user to specify which source
113
            line to inpect in the tracepoint buffer
114
    <DT>Tfind PC...
115
        <DD>Opens a dialog allowing the user to specify the PC of the
116
            tracepoint to view
117
    <DT>Tfind Tracepoint...
118
        <DD>Opens a dialog allowing the user to specify which tracepoint
119
            to view (by number). This option is most commonly used in
120
            conjunction with the <A HREF="console.html">Console Window</A>.
121
</DL>
122
 
123
<H4><A NAME="menus_prefs">Preferences Menu</A></H4>
124
The Preferences menu contains the following items:
125
<DL>
126
    <DT>Global
127
        <DD>Opens the <A HREF="gbl_pref.html">Global Preferences Dialog</A>
128
            and allows editing of global settings
129
    <DT>Source
130
        <DD>Opens the <A HREF="src_pref.html">Source Preferences Dialog</A>
131
            and allows editing of Source Window settings
132
    <DT>Register
133
        <DD>Opens the <A HREF="reg_pref.html">Register Preferences Dialog</A>
134
            and allows editing of Register Window settings
135
</DL>
136
 
137
<H3><A NAME="toolbar">Toolbar</A></H3>
138
The Source Window toolbar consists of three functional sections: trace
139
control buttons, debugger window buttons, and stack frame control buttons.
140
<BR>
141
 
142
<H4><A NAME="toolbar_exec">Tracing Control Buttons</A></H4>
143
These convenience buttons provide on-screen access to the most important
144
debugger tracing control functions:
145
<DL>
146
    <DT><A NAME="run_button"><IMG SRC="%run"> TStart</A> or
147
        <A NAME="stop_button"><IMG SRC="%stop"></A> TStop
148
         <DD>The TStart Button causes the target to start collecting trace data
149
         <DD>The TStop Button causes the target to stop collecting trace data
150
    <DT>Next Hit
151
        <DD>Update all displays with the next tracepoint in the
152
            tracepoint buffer
153
    <DT>Previous Hit
154
        <DD>Go to the previous tracepoint in the buffer
155
    <DT>First Hit
156
        <DD>View the first tracepoint in the buffer
157
    <DT>Next Line Hit
158
        <DD>Go to the next tracepoint in the buffer in the same
159
            frame as the current tracepoint
160
    <DT>Next Hit Here
161
        <DD>Jump to the next reference of the current tracepoint
162
            in the buffer
163
</DL>
164
 
165
<H4><A NAME="toolbar_window">Window Buttons</A></H4>
166
The Debugger Window buttons give instant access to the Debugger's
167
auxillary windows:
168
<DL>
169
    <DT><A NAME="register_button"><IMG SRC="%register"></A> Registers
170
        <DD>Open a <A HREF="register.html">Register Window</A>
171
    <DT><A NAME="memory_button"><IMG SRC="%memory"></A> Memory
172
        <DD>Open a <A HREF="memory.html">Memory Window</A>
173
    <DT><A NAME="stack_button"><IMG SRC="%stack"></A> Stack
174
        <DD>Open a <A HREF="stack.html">Stack Window</A>
175
    <DT><A NAME="watch_button"><IMG SRC="%watch"></A> Watch Expressions
176
        <DD>Open a <A HREF="watch.html">Watch Window</A>
177
    <DT><A NAME="locals_button"><IMG SRC="%locals"></A> Local Variables
178
        <DD>Open a <A HREF="locals.html">Locals Window</A>
179
    <DT><A NAME="tracepoints_button">Tracepoints</A>
180
        <DD>Open a <A HREF="tp.html">Tracepoint Window</A>
181
    <DT>Tracepoint Dump Window
182
        <DD>Open a <A HREF="tdump.html">Tdump Window</A>
183
    <DT><A NAME="console_button"><IMG SRC="%console"></A> Console
184
        <DD>Open a <A HREF="console.html">Console Window</A>
185
</DL>
186
 
187
<H4><A NAME="toolbar_frame">Frame Control</A></H4>
188
The Frame Control area of the toolbar displays information about the PC of
189
the current frame, and the frame control buttons may be used to navigate
190
through the call stack. Whenever any of these buttons are used, both the
191
Source Window Display and the <A HREF="stack.html">Stack Window</A> will
192
show the selected frame. In order to use the Stack Window in tracing mode,
193
the stack pointer must be collected.
194
<DL>
195
    <!-- is this a problem for windows? no file join? -->
196
    <DT><IMG SRC="images/frame_info.gif"> Frame Information Display
197
        <DD>The left half of the frame information display shows the
198
            value of the PC in the current frame. The right half shows
199
            the line number of the PC in the source file, if available.
200
    <DT><A NAME="up_button"><IMG SRC="%up"></A> Up
201
        <DD>Select and view the stack frame that called this one
202
    <DT><A NAME="down_button"><IMG SRC="%down"></A> Down
203
        <DD>Select and view the stack frame called by this one
204
    <DT><A NAME="bottom_button"><IMG SRC="%bottom"></A> Bottom
205
        <DD>Select and view the bottom-most stack frame
206
</DL>
207
 
208
<H3><A NAME="display">Source Display</A></H3>
209
The Source Display is used for many things: browsing source code, setting,
210
editing, and deleting tracepoints, and a few other special functions.
211
Executable lines (those for which executable code was generated by the
212
compiler) are denoted with a marker (a dash, "-") in the first column of
213
the display.
214
 
215
<P>The debugger highlights the PC in the current frame in either green,
216
indicating that the PC is in the current tracepoint, or gold, indicating
217
that the PC is contained in a frame that is not the current tracepoint, i.e.,
218
as part of a stack backtrace. A blue highlight is used by the debugger to
219
indicate a browsing position. All highlight colors
220
are user-selectable in the <A HREF="src_pref.html">Source Preferences</A>.</P>
221
<BR>
222
 
223
<H4><A NAME="setting_a_tracepoint">Setting a Tracepoint</A></H4>
224
Moving the mouse pointer over the "hot spot" of an executable line will change
225
the mouse cursor to a large dot. Clicking the left mouse button will then allow
226
tracepoint to be inserted at this line. If no tracepoint exists, the
227
<A HREF="tracedlg.html">Add Tracepoint Dialog</A> will appear. If a tracepoint
228
is installed, the dash in the left margin will change into a magenta breakdot.
229
If a tracepoint exists, the <A HREF="tracedlg.html">Edit Tracepoint Dialog</A>
230
appears, allowing either modification of the tracepoint or deletion of the
231
tracepoint. If the tracepoint is deleted, the breakdot will revert to a dash.</P>
232
 
233
<P>The executable line marker shows the status of each line: an empty marker
234
(the dash) indicates that no tracepoint is set at the line. A colored breakdot
235
indicates that a tracepoint exists at the line.</P>
236
 
237
<P>The display will attempt to show the value of variables in
238
<A NAME="display_balloon">variable balloons</A>. To activate a
239
variable balloon, simply hold the mouse cursor over the name of
240
a variable in the Source Display for a second or two: the debugger displays the
241
name of the variable, its type, and its value in a pop-up balloon. If the
242
variable was not collected, the Variable Balloon will show a memory-access error.</P>
243
<BR>
244
 
245
<H4><A NAME="display_popup">Source Pop-up Menus</A></H4>
246
The Source Display has two pop-up menus. One is activated by clicking the
247
right mouse button when the mouse cursor is over an executable line marker's
248
hot spot. This pop-up menu provides access to:
249
<DL>
250
    <DT>Set Tracepoint
251
        <DD>Opens the <A HREF="#tracedlg">Add/Edit Tracepoint Dialog</A>,
252
            which allows new tracepoints to be set and modification and
253
            deletion of existing tracepoints.
254
</DL>
255
 
256
<P>The other pop-up menu is activated by clicking the right mouse button
257
anywhere else in the Source Display. It is only available when a variable
258
or number in the display lies below the mouse cursor or is selected
259
(by clicking the left mouse button and dragging the mouse to highlight
260
the variable/number). The pop-up menu allows users to:
261
<DL>
262
    <DT><A NAME="add_to_watch">Add <I>expr</I> to Watch</A>
263
        <DD>Adds the selected expression to the <A HREF="watch.html">Watch
264
            Window</A>, opening it, if necessary.
265
    <DT>Dump Memory at <I>expr</I>
266
        <DD>Opens a new <A HREF="memory.html">Memory Window</A> at the
267
            selected expression. If the expression is a variable, then
268
            the Memory Window is opened with memory addresses starting
269
            at the value of the variable.
270
    <DT>Set Tracepoint Range
271
        <DD>This option is only available when a range of lines is highlighted
272
            in the Source Display. It allows tracepoints with the same
273
            properties to be set at every executable line in the range. If
274
            any tracepoints exist in the range already, the debugger will
275
            ask if the properties of the existing tracepoint should be
276
            replaced with the properties of the range.
277
</DL>
278
</P>
279
 
280
<H4><A NAME="status">Source Window Status Bars</A></H4>
281
The Source Window has two status bars which inform the user of the
282
status of the program (the "status bar") and the status of the Source
283
Window.
284
 
285
<P>The <A NAME="status_bar">Program Status Bar</A> (or simply "Status Bar")
286
displays the status of the program. Common messages seen here include:
287
<DL>
288
    <DT>No program loaded.
289
        <DD>No program has been loaded into target memory.
290
    <DT>Inspecting trace at <I>line/address</I>
291
        <DD>The debugger is inspecting the tracepoint at line
292
            <I>line</I> or address <I>address</I>. Use the
293
            <A HREF="#toolbar_exec">Tracing Control Buttons</A>
294
            to navigate through the trace buffer.
295
</DL>
296
<P>The Status Bar also displays some help information. For instance,
297
the Status Bar will show the function of a button on the toolbar or
298
the Source Display Status Bar as well as any keyboard shortcut for this
299
button.</P>
300
<BR>
301
 
302
<H4><A NAME="status_mode">Source Display Status Bar</A></H4>
303
current state of the Source Window: the name of the file displayed in
304
the Display, the name of the function in the Display which contains
305
the PC for the current frame (if any), and the display mode.
306
 
307
<P>The <A NAME="file_selector">Source File Selector</A> is a dropdown
308
menu which contains the names of all the files that were compiled into
309
the program being debugged.</P>
310
 
311
<P>Normally, the File Selector displays the name of the file currently being
312
viewed, but any file from the dropdown menu may be selected for browsing.
313
Simply select the file to view from the available choices (or type it directly
314
into the File Selector) and the Source Window will load that file into
315
the Display. To return to the current tracepoint, simply press the
316
<A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>
317
 
318
<P>The <A NAME="function_selector">Source Function Selector</A> displays the
319
name of the function containing the Source Window's PC, if one exists, but it
320
may be used to browse any function in the current file. Simply type the name
321
of the desired function into the Function Selector or select it from the
322
dropdown menu. The Source Window's PC is updated to point at this function.
323
To return to the current tracepoint, simply press the
324
<A HREF="#bottom_button">Bottom Frame Control Button</A>.</P>
325
 
326
<P>The <A NAME="mode_selector">Source Display Mode Selector</A> displays
327
the viewing mode of the current file/function shown in the Source
328
Window Display.</P>
329
 
330
<P>The Display Mode Selector may be used to change the view of the current
331
source file. The available display modes are
332
<DL>
333
    <DT>SOURCE
334
        <DD>The contents of the Display are shown as source code.
335
            If source code is not available (either because no debugging
336
            information is available or the source file is not found),
337
            the Source Window will revert the Display Mode to "ASSEMBLY".
338
    <DT>ASSEMBLY
339
        <DD>A disassembly of the target's memory is shown in the Display.
340
            Even assembly source files show a disassembly of target memory;
341
            to see the assembly source code, use the SOURCE mode. Note that the
342
            debugger can only display assmebly code on a function-by-function
343
            basis. It cannot display all the instructions generated from a single
344
            source file.
345
    <DT>MIXED
346
        <DD>The Display shows source code mixed with the assembler
347
            instructions which were generated for those lines by the
348
            compiler for the current funtion. Note that the addresses
349
            of the assembly lines is not necessarily monotonically
350
            increasing. If the source file associated with the function
351
            cannot be found, the Source Window will revert to ASSEMBLY mode.
352
    <DT>SRC+ASM
353
        <DD>The Source Window Display is divided into two panes: an
354
            assembly pane and a source pane. Tracepoints may be set/cleared
355
            in either pane.
356
</DL>
357
<BR>
358
 
359
<H3><A NAME="search">Search Entry</A></H3>
360
The Search Entry facilitates searching for text in the Source Window Display. Simply enter the
361
text to be found into the Search Entry and press the Enter key on the keyboard to search
362
forwards in the Source Window Display (hold down ths Shift key to search backwards). If
363
a match is found, it is highlighted in the Source Window and the Program Status Bar
364
displays information about where the match was found.
365
 
366
<P>The Search Entry can also jump the Source Window to a specific line. Enter the line
367
number preceeded by an at-sign (@) into the Search Entry and press enter. If entered
368
line number is greater than the total number of lines in the Source Window Display,
369
the Display will jump to the end of the current file.</P>
370
</BODY>
371
</HTML>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.