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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [gdbtk/] [README.GDBTK] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
                                 README.GDBTK
2
                           Written by Stu Grossman
3
              Updated 9/26/95 by Fred Fish for gdb 4.15 release
4
              Updated 4/18/97 by Martin Hunt
5
 
6
This file describes how to build, install, use and hack on GDBtk, a TK based
7
GUI for GDB, the GNU debugger.
8
 
9
Introduction
10
============
11
 
12
GDBtk is a version of GDB that uses Tcl/Tk to implement a graphical
13
user inter-face.  It is a fully integrated GUI, not a separate
14
front-end program.  The interface consists of several separate
15
windows, which use standard elements like buttons, scrollbars, entry
16
boxes and such to create a fairly easy to use interface.  Each window
17
has a distinct content and purpose, and can be enabled or disabled
18
individually.  The windows contain things like the current source
19
file, a disassembly of the current function, text commands (for things
20
that aren't accessible via a button), and so forth.
21
 
22
Building and installing
23
=======================
24
 
25
Building GDBtk is very straightforward.  The main difference is that you will
26
need to use the `--enable-gdbtk' option when you run configure in the top level
27
directory.  You will also need to install Tcl version 7.6 and Tk version 4.2.
28
 
29
On Unix machines, you will also need to have X11 (R4/R5/R6) installed
30
(this is a prerequisite to installing Tk).
31
 
32
For Windows, you can obtain Tcl/Tk from ftp://ftp.smli.com:/pub/tcl/win76p2.exe.
33
There is a bug in this version of Tcl/tk that requires you to set the
34
environmental variable TK_LIBRARY to where the tk library directory is installed.
35
There is also a problem with the colors in images on 16-bit displays under
36
Windows, so some icons may look strange.
37
 
38
[See the GDB README file for more details on configure options and such.]
39
 
40
For example:
41
 
42
        host> cd gdbtk
43
        host> ./configure --enable-gdbtk
44
        host> make
45
        host> make install
46
 
47
Using GDBtk
48
===========
49
 
50
Just run it like you would a normal GDB (in fact, it's actually called `gdb').
51
If everything goes well, you should have several windows pop up.  To get going,
52
hit the start button, and go exploring.
53
 
54
If you want to use GDB in command line mode, just use the -nw option.  Or, you
55
can undefine the DISPLAY environment variable.
56
 
57
In the current version, you can have up to 6 windows active at once.  They are:
58
 
59
        1) Command
60
        2) Source
61
        3) Assembly
62
        4) Register
63
        5) Auto Command
64
        6) Expression
65
 
66
Most windows have a similar layout consisting of a menubar, display area,
67
scrollbar, status box and window-specific buttons.
68
 
69
The menubar contains the following items:
70
 
71
        File    - General file control.  Also has window close and quit buttons.
72
        Options - Window specific options.
73
        Window  - A menu of other windows that can be popped up or created.
74
        Help    - Mostly unimplemented.
75
 
76
The status box indicates things like the current file and function, or the
77
current PC and function depending upon the window.
78
 
79
Command window:
80
 
81
        This can be used to type commands at GDB (useful for when there isn't a
82
        button for what you want to do).
83
 
84
Source window:
85
 
86
        This contains the current source file.  The margin displays line
87
        numbers, and has an indicator for lines that actually contain code (and
88
        therefore can have breakpoints as well).  When a breakpoint is set at
89
        that line, the indicator is replaced with a stop sign icon.
90
 
91
        The buttons are:
92
 
93
        Start - Put a breakpoint at main, and then run.
94
        Stop - Stop the program (only active when program is running).
95
        Step, Next, Cont[inue], Finish, Up, Down - Same as the corresponding
96
              GDB command.  (Finish runs the current subroutine until it's done.)
97
        Bottom - Does a `frame 0' to put you at the innermost call frame.
98
 
99
        There are also accelerators for various buttons (just type the letter
100
        without any control/meta/alt/shift in the text frame):
101
 
102
        s - Step
103
        n - Next
104
        c - Continue
105
        f - Finish
106
        u - Up
107
        d - Down
108
 
109
        The mouse can also be used to set and clear breakpoints when clicked
110
        in the margin (on a breakpoint indicator).
111
 
112
Assembly window:
113
 
114
        This displays a disassembly of the current function.  It's buttons are
115
        similar to those of the source window, except that it uses Stepi and
116
        Nexti to run one instruction at a time instead of one statement at a
117
        time.  The accelerators and mouse actions are also similar.
118
 
119
        Additionally, there is an option to enable mixed source and assembly.
120
 
121
Register window:
122
 
123
        This displays the registers.  It may have to be resized to properly
124
        display all the registers.  The displayed registers can be selected
125
        via the Options|Config menu item.
126
 
127
Auto Command window:
128
 
129
        Using this window, you can specify a command to be executed frequently.
130
        The output will be automatically updated.  Options|Accumulate-output
131
        can be used to avoid clearing the window each time so that you can
132
        accumulate a history.
133
 
134
Expressions:
135
 
136
        The expression window can be used to just calculate an expression, or
137
        to watch the value of an expression (ala the `display' command), using
138
        the Update button.  The expression window will also pop up
139
        automatically when an expression is double-clicked in the source window.
140
 
141
Customizing GDBtk
142
=================
143
 
144
There are three primary ways to customize GDBtk.  One is to modify the
145
appropriate X resources.  Another is to hack a ~/.gdbtkinit file.  The last
146
is to change the files in gdbtcl, which defines the most basic interface
147
elements.
148
 
149
X resources give you control over things like the choice of fonts, color
150
schemes and some geometry info.
151
 
152
For more serious customizations, you will probably need to hack your
153
~/.gdbtkinit or gdbtcl files.
154
 
155
X Resources
156
===========
157
 
158
        The class name for GDBtk is `Gdb', and it's appname is `gdb'.  The top-
159
level windows have instance names of `src', 'asm', 'reg', and 'cmd'.  The main
160
display area in each has the class `Text'.  So, to change the font in all the
161
main display areas, something like the following will do:
162
 
163
        Gdb*Text*font:          fixed
164
 
165
To change the font in only the source window:
166
 
167
        Gdb*src*Text*font:              fixed
168
 
169
To find out the names of the widgets do the following (in the command window):
170
 
171
        tk info comm .*
172
 
173
To get the list of resources (and their classes) for a given widget, do some-
174
thing like:
175
 
176
        tk .asm.text config
177
 
178
This will return a list of lists, where each sublist looks something like this:
179
 
180
        {-height height Height 24 25}
181
 
182
The first item is the name of the config option used when creating the widget.
183
The second item is the instance name of this resource, the third is the class
184
name.  The fourth item is the default value, and the last item is the current
185
value.
186
 
187
To get info about a single resource, add the config option name to the end of
188
the previous command.  I.e.:
189
 
190
        tk .asm.text config -font
191
 
192
will return just the info about the font.
193
 
194
To find out the class of a window, just do:
195
 
196
        tk winfo class .asm.text
197
 
198
Note that some things may be explicitly overridden by gdbtk.tcl.  In
199
particular, the `tk colormodel . monochrome' command should probably be
200
disabled if you want to use color.
201
 
202
Hacking ~/.gdbtkinit and gdbtcl
203
===============================
204
~/.gdbtkinit is sourced at the end of gdbtk.tcl.  Currently there is no good
205
doc on this.  See gdbtcl/main.tcl to see what you can change.
206
 
207
The GUI is primarily implemented by Tcl/Tk code which lives in gdbtcl and a
208
C file called gdbtk.c.  The Tcl/Tk code determines the look and feel, the
209
layout, and the functions associated with all of the interface elements.  The C
210
code is mostly just glue between GDB internals and Tclland.  In essence, all of
211
the policy is implemented in Tcl/Tk, and is easily changed without recompiling.
212
 
213
To make more serious changes to the interface, such as adding a new window or
214
changing the framework, you will have to hack the tcl code.  This directory is
215
installed in $(libdir) (probably /usr/local/lib/).  But, you will probably want
216
to hack on your own private copy before putting it up for the rest of the
217
users.  To find the GDB tcl code, GDB first checks for the environment variable
218
GDBTK_LIBRARY.  This can be a directory name or a list of directories separated
219
by colons (semicolons on Windows). GDB will check each directory in order until
220
it finds "main.tcl".  If GDBTK_LIBRARY is not set, GDB will look for
221
"gdbtcl/main.tcl" in the current directory, and finally, it will try to find
222
the tcl directory in the sources.
223
 
224
Note that the old GDBTK_FILENAME environment variable is no longer used.
225
 
226
Internally, GDBtk is basically GDB, linked with Tcl/Tk, and some glue code that
227
interfaces GDB internals to Tclland.  This means that GDBtk operates as a
228
single program, not a front-end to GDB.  All GDB commands, and a great deal of
229
the target program state are accessible to the Tcl programmer.  In addition,
230
there are many callbacks from GDB to notify Tclland of important events.
231
 
232
Here is a brief rundown of the GDB<=>Tcl interfaces:
233
 
234
Tcl->GDB calls:
235
        gdb_cmd - sends a text command to gdb.  Returns the result
236
        gdb_loc - takes PC, and returns a list consisting of a short file name,
237
                  the function name, a long file name, the line number and the
238
                  PC (in case you didn't supply it).
239
        gdb_sourcelines - Takes a filename, and returns a list of lines that
240
                  contain code.
241
        gdb_listfiles - Returns a list of all of the source files.
242
        gdb_stop - Stops the target process.
243
        gdb_regnames - Returns a list of all of the register names.
244
        gdb_fetch_registers - Returns the contents of the specified registers.
245
        gdb_changed_register_list - Returns a list of registers that have
246
                  changed since the last call.
247
        gdb_disassemble - Takes a function or PC.  Returns the text of a dis-
248
                  assembly of the entire function.
249
        gdb_eval - Takes an expression.  Returns it's value.
250
        gdb_get_breakpoint_list - Does the obvious.
251
        gdb_get_breakpoint_info - Takes a breakpoint number.  Returns a list of
252
                  info about that breakpoint.
253
 
254
GDB->Tcl callbacks:
255
        gdb_tcl_fputs - Sends output into Tcl for the command window.
256
        gdb_tcl_query - Pops up a query window.
257
        gdbtk_tcl_breakpoint - Notifies Tcl of changes to a breakpoint.
258
        gdbtk_tcl_idle - Notifies Tcl that debugged process is now idle.
259
        gdbtk_tcl_busy - Notifies Tcl that debugged process is now running.
260
 
261
For details, see the usage in gdbtk.tcl, or the definitions in gdbtk.c.
262
 
263
Additionally, there is a new GDB command `tk', which can be used to poke at
264
Tk/Tcl from the command window.
265
 
266
Problems
267
========
268
 
269
During building, you may run into problems with finding Tcl, Tk or X11.  Look
270
in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as
271
appropriate.
272
 
273
If you one of the following messages when you run gdb:
274
 
275
        Tcl_Init failed: can't find init.tcl; perhaps you need to
276
        install Tcl or set your TCL_LIBRARY environment variable?
277
or
278
        Tk_Init failed: can't find tk.tcl; perhaps you need to
279
        install Tk or set your TK_LIBRARY environment variable?
280
 
281
then you haven't installed Tcl or TK properly.  Fix the appropriate environment
282
variable to point at the {tcl tk}/library directory, and restart gdb.
283
 
284
If you get the following:
285
 
286
        /usr/local/lib/gdbtk.tcl:1: couldn't read file "/usr/local/lib/gdbtk.tcl": No such file or directory
287
        Stack trace:
288
        can't unset "auto_index": no such variable
289
            while executing
290
        "unset auto_index"
291
 
292
then GDBtk wasn't installed properly.  You can set the GDBTK_FILENAME
293
environment variable to point at the gdbtk.tcl in your source directory.  Note
294
that the stack trace displayed here is not valid.  If you actually get an error
295
in gdbtk.tcl, the stack trace is useful to pinpoint the location.
296
 
297
Known Bugs
298
==========
299
 
300
generic problems
301
 
302
    o   If you open an Assembly window before you have run the program, gdbtk
303
        pops up a dialog box titled "Error in Tcl Script" with the contents
304
        "Error: No function contains the specified address".  Trying to then
305
        do other things brings up a dialog box with the contents "Error:
306
        can't read 'current_asm_label': no such variable.
307
 
308
        Solution:  Close Assembly window when there is no program running.
309
 
310
    o   If you open Registers window before you have run the program, gdbtk
311
        pops up a dialog box titled "Error in Tcl Script" with the contents
312
        "Error: No registers".  Trying to then do other things, like use the
313
        Start button to run the program, repeatedly produce the same dialog
314
        box and the action is not performed.
315
 
316
        Solution:  Close Registers window when there is no program running.
317
 
318
    o   Expressions are sometimes not displayed correctly in the Expression
319
        window.  I.E. "argc" works, as does "*(argv+argc)" but not "argv[argc]".
320
 
321
        Solution:  None
322
        [ I believe this problem is fixed, but I have not tested it ]
323
 
324
    o   The Breakpoint window does not get automatically updated and changes
325
        made in the window are not reflected back in the results from "info br".
326
        I.E. the breakpoint count in the window is not updated at each hit and
327
        enabling/disabling the breakpoint from the Breakpoint window has no effect.
328
 
329
        Solution:  Use the command interface to control breakpoints and don't
330
        open a Breakpoint window.
331
 
332
    o   Sometimes while an expression window is active you get a dialog box
333
        that complains "Error: invalid command name ".expr.e5.expr" for
334
        example.  The Tcl stack trace looks something like:
335
 
336
                invalid command name ".expr.e5.expr"
337
                    while executing
338
                "$e.expr get 0.0 end"
339
                    invoked from within
340
                "set expr [$e.expr get 0.0 end]..."
341
                    (procedure "update_expr" line 17)
342
                    invoked from within
343
                "update_expr $expr_num"
344
                    invoked from within
345
                "if $expr_update_list($expr_num) {
346
                    update_expr $expr_num
347
                        .
348
                        .
349
                        .
350
 
351
        Solution:  None except close expression window and reopen it.
352
 
353
    o   If you select the "Down" button in either the Source or Assembly
354
        window while in the bottom (innermost) frame, the error message that
355
        results goes just to the command window and may be missed if the
356
        command window is not open.  This may also apply to other messages
357
        as well.  It should probably put up a notification box instead.
358
 
359
        Solution:  Keep Command window open to see error messages.
360
 
361
    o   Not really a problem, but it would be nice to have a backtrace
362
        window.
363
 
364
        Solution:  Do bt in command window?
365
 
366
    o   Also not really a problem, but it might be nice to have a frame/stack
367
        window that displays the last N words on the stack, along with
368
        indications about which function owns a particular frame, how the
369
        frame pointers are chained, and possibly the names of variables
370
        alongside their frame slots.
371
 
372
m68k-hp-hpux9.00:
373
 
374
    o   Attempting to use a Register window results in a Tcl Script Error
375
        "Error: Erroneous arithmetic operation".  The Tcl stack trace is:
376
 
377
            while executing
378
        "gdb_fetch_registers $reg_format $regnum"
379
            invoked from within
380
        "set regval [gdb_fetch_registers $reg_format $regnum]..."
381
            ("foreach" body line 2)
382
            invoked from within
383
        "foreach regnum $reg_display_list {
384
                                set regval [gdb_fetch_registers $reg_format $regnum]
385
                                set regval [format "%-*s" $valwidth $regval]
386
                                $win del ..."
387
            invoked from within
388
        "if {$which == "all"} {
389
                        set lineindex 1
390
                        foreach regnum $reg_display_list {
391
                                set regval [gdb_fetch_registers $reg_format $regnum]
392
                                set regval [f ..."
393
            (procedure "update_registers" line 16)
394
            invoked from within
395
        "update_registers all"
396
                .
397
                .
398
                .
399
 
400
 

powered by: WebSVN 2.1.0

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