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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdbint.info-3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
This is gdbint.info, produced by Makeinfo version 3.12f from
2
./gdbint.texinfo.
3
 
4
START-INFO-DIR-ENTRY
5
* Gdb-Internals: (gdbint).      The GNU debugger's internals.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the internals of the GNU debugger GDB.
9
 
10
   Copyright 1990-1999 Free Software Foundation, Inc.  Contributed by
11
Cygnus Solutions.  Written by John Gilmore.  Second Edition by Stan
12
Shebs.
13
 
14
   Permission is granted to make and distribute verbatim copies of this
15
manual provided the copyright notice and this permission notice are
16
preserved on all copies.
17
 
18
   Permission is granted to copy or distribute modified versions of this
19
manual under the terms of the GPL (for which purpose this text may be
20
regarded as a program in the language TeX).
21
 
22

23
File: gdbint.info,  Node: Support Libraries,  Next: Coding,  Prev: Native Debugging,  Up: Top
24
 
25
Support Libraries
26
*****************
27
 
28
BFD
29
===
30
 
31
   BFD provides support for GDB in several ways:
32
 
33
_identifying executable and core files_
34
     BFD will identify a variety of file types, including a.out, coff,
35
     and several variants thereof, as well as several kinds of core
36
     files.
37
 
38
_access to sections of files_
39
     BFD parses the file headers to determine the names, virtual
40
     addresses, sizes, and file locations of all the various named
41
     sections in files (such as the text section or the data section).
42
     GDB simply calls BFD to read or write section X at byte offset Y
43
     for length Z.
44
 
45
_specialized core file support_
46
     BFD provides routines to determine the failing command name stored
47
     in a core file, the signal with which the program failed, and
48
     whether a core file matches (i.e. could be a core dump of) a
49
     particular executable file.
50
 
51
_locating the symbol information_
52
     GDB uses an internal interface of BFD to determine where to find
53
     the symbol information in an executable file or symbol-file.  GDB
54
     itself handles the reading of symbols, since BFD does not
55
     "understand" debug symbols, but GDB uses BFD's cached information
56
     to find the symbols, string table, etc.
57
 
58
opcodes
59
=======
60
 
61
   The opcodes library provides GDB's disassembler.  (It's a separate
62
library because it's also used in binutils, for `objdump').
63
 
64
readline
65
========
66
 
67
mmalloc
68
=======
69
 
70
libiberty
71
=========
72
 
73
gnu-regex
74
=========
75
 
76
   Regex conditionals.
77
 
78
`C_ALLOCA'
79
 
80
`NFAILURES'
81
 
82
`RE_NREGS'
83
 
84
`SIGN_EXTEND_CHAR'
85
 
86
`SWITCH_ENUM_BUG'
87
 
88
`SYNTAX_TABLE'
89
 
90
`Sword'
91
 
92
`sparc'
93
include
94
=======
95
 
96

97
File: gdbint.info,  Node: Coding,  Next: Porting GDB,  Prev: Support Libraries,  Up: Top
98
 
99
Coding
100
******
101
 
102
   This chapter covers topics that are lower-level than the major
103
algorithms of GDB.
104
 
105
Cleanups
106
========
107
 
108
   Cleanups are a structured way to deal with things that need to be
109
done later.  When your code does something (like `malloc' some memory,
110
or open a file) that needs to be undone later (e.g. free the memory or
111
close the file), it can make a cleanup.  The cleanup will be done at
112
some future point: when the command is finished, when an error occurs,
113
or when your code decides it's time to do cleanups.
114
 
115
   You can also discard cleanups, that is, throw them away without doing
116
what they say.  This is only done if you ask that it be done.
117
 
118
   Syntax:
119
 
120
`struct cleanup *OLD_CHAIN;'
121
     Declare a variable which will hold a cleanup chain handle.
122
 
123
`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
124
     Make a cleanup which will cause FUNCTION to be called with ARG (a
125
     `char *') later.  The result, OLD_CHAIN, is a handle that can be
126
     passed to `do_cleanups' or `discard_cleanups' later.  Unless you
127
     are going to call `do_cleanups' or `discard_cleanups' yourself,
128
     you can ignore the result from `make_cleanup'.
129
 
130
`do_cleanups (OLD_CHAIN);'
131
     Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
132
     E.g.:
133
          make_cleanup (a, 0);
134
          old = make_cleanup (b, 0);
135
          do_cleanups (old);
136
 
137
     will call `b()' but will not call `a()'.  The cleanup that calls
138
     `a()' will remain in the cleanup chain, and will be done later
139
     unless otherwise discarded.
140
 
141
`discard_cleanups (OLD_CHAIN);'
142
     Same as `do_cleanups' except that it just removes the cleanups from
143
     the chain and does not call the specified functions.
144
 
145
   Some functions, e.g. `fputs_filtered()' or `error()', specify that
146
they "should not be called when cleanups are not in place".  This means
147
that any actions you need to reverse in the case of an error or
148
interruption must be on the cleanup chain before you call these
149
functions, since they might never return to your code (they `longjmp'
150
instead).
151
 
152
Wrapping Output Lines
153
=====================
154
 
155
   Output that goes through `printf_filtered' or `fputs_filtered' or
156
`fputs_demangled' needs only to have calls to `wrap_here' added in
157
places that would be good breaking points.  The utility routines will
158
take care of actually wrapping if the line width is exceeded.
159
 
160
   The argument to `wrap_here' is an indentation string which is
161
printed _only_ if the line breaks there.  This argument is saved away
162
and used later.  It must remain valid until the next call to
163
`wrap_here' or until a newline has been printed through the
164
`*_filtered' functions.  Don't pass in a local variable and then return!
165
 
166
   It is usually best to call `wrap_here()' after printing a comma or
167
space.  If you call it before printing a space, make sure that your
168
indentation properly accounts for the leading space that will print if
169
the line wraps there.
170
 
171
   Any function or set of functions that produce filtered output must
172
finish by printing a newline, to flush the wrap buffer, before switching
173
to unfiltered ("`printf'") output.  Symbol reading routines that print
174
warnings are a good example.
175
 
176
GDB Coding Standards
177
====================
178
 
179
   GDB follows the GNU coding standards, as described in
180
`etc/standards.texi'.  This file is also available for anonymous FTP
181
from GNU archive sites.  GDB takes a strict interpretation of the
182
standard; in general, when the GNU standard recommends a practice but
183
does not require it, GDB requires it.
184
 
185
   GDB follows an additional set of coding standards specific to GDB,
186
as described in the following sections.
187
 
188
   You can configure with `--enable-build-warnings' to get GCC to check
189
on a number of these rules.  GDB sources ought not to engender any
190
complaints, unless they are caused by bogus host systems.  (The exact
191
set of enabled warnings is currently `-Wall -Wpointer-arith
192
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
193
 
194
Formatting
195
----------
196
 
197
   The standard GNU recommendations for formatting must be followed
198
strictly.
199
 
200
   Note that while in a definition, the function's name must be in
201
column zero; in a function declaration, the name must be on the same
202
line as the return type.
203
 
204
   In addition, there must be a space between a function or macro name
205
and the opening parenthesis of its argument list (except for macro
206
definitions, as required by C).  There must not be a space after an open
207
paren/bracket or before a close paren/bracket.
208
 
209
   While additional whitespace is generally helpful for reading, do not
210
use more than one blank line to separate blocks, and avoid adding
211
whitespace after the end of a program line (as of 1/99, some 600 lines
212
had whitespace after the semicolon).  Excess whitespace causes
213
difficulties for diff and patch.
214
 
215
Comments
216
--------
217
 
218
   The standard GNU requirements on comments must be followed strictly.
219
 
220
   Block comments must appear in the following form, with no `/*'- or
221
'*/'-only lines, and no leading `*':
222
 
223
     /* Wait for control to return from inferior to debugger.  If inferior
224
        gets a signal, we may decide to start it up again instead of
225
        returning.  That is why there is a loop in this function.  When
226
        this function actually returns it means the inferior should be left
227
        stopped and GDB should read more commands.  */
228
 
229
   (Note that this format is encouraged by Emacs; tabbing for a
230
multi-line comment works correctly, and M-Q fills the block
231
consistently.)
232
 
233
   Put a blank line between the block comments preceding function or
234
variable definitions, and the definition itself.
235
 
236
   In general, put function-body comments on lines by themselves, rather
237
than trying to fit them into the 20 characters left at the end of a
238
line, since either the comment or the code will inevitably get longer
239
than will fit, and then somebody will have to move it anyhow.
240
 
241
C Usage
242
-------
243
 
244
   Code must not depend on the sizes of C data types, the format of the
245
host's floating point numbers, the alignment of anything, or the order
246
of evaluation of expressions.
247
 
248
   Use functions freely.  There are only a handful of compute-bound
249
areas in GDB that might be affected by the overhead of a function call,
250
mainly in symbol reading.  Most of GDB's performance is limited by the
251
target interface (whether serial line or system call).
252
 
253
   However, use functions with moderation.  A thousand one-line
254
functions are just as hard to understand as a single thousand-line
255
function.
256
 
257
Function Prototypes
258
-------------------
259
 
260
   Prototypes must be used to _declare_ functions, and may be used to
261
_define_ them.  Prototypes for GDB functions must include both the
262
argument type and name, with the name matching that used in the actual
263
function definition.
264
 
265
   All external functions should have a declaration in a header file
266
that callers include, except for `_initialize_*' functions, which must
267
be external so that `init.c' construction works, but shouldn't be
268
visible to random source files.
269
 
270
   All static functions must be declared in a block near the top of the
271
source file.
272
 
273
Clean Design
274
------------
275
 
276
   In addition to getting the syntax right, there's the little question
277
of semantics.  Some things are done in certain ways in GDB because long
278
experience has shown that the more obvious ways caused various kinds of
279
trouble.
280
 
281
   You can't assume the byte order of anything that comes from a target
282
(including VALUEs, object files, and instructions).  Such things must
283
be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
284
routines defined in `bfd.h', such as `bfd_get_32'.
285
 
286
   You can't assume that you know what interface is being used to talk
287
to the target system.  All references to the target must go through the
288
current `target_ops' vector.
289
 
290
   You can't assume that the host and target machines are the same
291
machine (except in the "native" support modules).  In particular, you
292
can't assume that the target machine's header files will be available
293
on the host machine.  Target code must bring along its own header files
294
- written from scratch or explicitly donated by their owner, to avoid
295
copyright problems.
296
 
297
   Insertion of new `#ifdef''s will be frowned upon.  It's much better
298
to write the code portably than to conditionalize it for various
299
systems.
300
 
301
   New `#ifdef''s which test for specific compilers or manufacturers or
302
operating systems are unacceptable.  All `#ifdef''s should test for
303
features.  The information about which configurations contain which
304
features should be segregated into the configuration files.  Experience
305
has proven far too often that a feature unique to one particular system
306
often creeps into other systems; and that a conditional based on some
307
predefined macro for your current system will become worthless over
308
time, as new versions of your system come out that behave differently
309
with regard to this feature.
310
 
311
   Adding code that handles specific architectures, operating systems,
312
target interfaces, or hosts, is not acceptable in generic code.  If a
313
hook is needed at that point, invent a generic hook and define it for
314
your configuration, with something like:
315
 
316
     #ifdef     WRANGLE_SIGNALS
317
        WRANGLE_SIGNALS (signo);
318
     #endif
319
 
320
   In your host, target, or native configuration file, as appropriate,
321
define `WRANGLE_SIGNALS' to do the machine-dependent thing.  Take a bit
322
of care in defining the hook, so that it can be used by other ports in
323
the future, if they need a hook in the same place.
324
 
325
   If the hook is not defined, the code should do whatever "most"
326
machines want.  Using `#ifdef', as above, is the preferred way to do
327
this, but sometimes that gets convoluted, in which case use
328
 
329
     #ifndef SPECIAL_FOO_HANDLING
330
     #define SPECIAL_FOO_HANDLING(pc, sp) (0)
331
     #endif
332
 
333
   where the macro is used or in an appropriate header file.
334
 
335
   Whether to include a "small" hook, a hook around the exact pieces of
336
code which are system-dependent, or whether to replace a whole function
337
with a hook depends on the case.  A good example of this dilemma can be
338
found in `get_saved_register'.  All machines that GDB 2.8 ran on just
339
needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
340
Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
341
`REGISTER_IN_WINDOW_P' were introduced.  Then the 29k and 88k required
342
the `GET_SAVED_REGISTER' hook.  The first three are examples of small
343
hooks; the latter replaces a whole function.  In this specific case, it
344
is useful to have both kinds; it would be a bad idea to replace all the
345
uses of the small hooks with `GET_SAVED_REGISTER', since that would
346
result in much duplicated code.  Other times, duplicating a few lines
347
of code here or there is much cleaner than introducing a large number
348
of small hooks.
349
 
350
   Another way to generalize GDB along a particular interface is with an
351
attribute struct.  For example, GDB has been generalized to handle
352
multiple kinds of remote interfaces - not by #ifdef's everywhere, but
353
by defining the "target_ops" structure and having a current target (as
354
well as a stack of targets below it, for memory references).  Whenever
355
something needs to be done that depends on which remote interface we are
356
using, a flag in the current target_ops structure is tested (e.g.
357
`target_has_stack'), or a function is called through a pointer in the
358
current target_ops structure.  In this way, when a new remote interface
359
is added, only one module needs to be touched - the one that actually
360
implements the new remote interface.  Other examples of
361
attribute-structs are BFD access to multiple kinds of object file
362
formats, or GDB's access to multiple source languages.
363
 
364
   Please avoid duplicating code.  For example, in GDB 3.x all the code
365
interfacing between `ptrace' and the rest of GDB was duplicated in
366
`*-dep.c', and so changing something was very painful.  In GDB 4.x,
367
these have all been consolidated into `infptrace.c'.  `infptrace.c' can
368
deal with variations between systems the same way any
369
system-independent file would (hooks, #if defined, etc.), and machines
370
which are radically different don't need to use infptrace.c at all.
371
 
372
   Don't put debugging printfs in the code.
373
 
374

375
File: gdbint.info,  Node: Porting GDB,  Next: Testsuite,  Prev: Coding,  Up: Top
376
 
377
Porting GDB
378
***********
379
 
380
   Most of the work in making GDB compile on a new machine is in
381
specifying the configuration of the machine.  This is done in a
382
dizzying variety of header files and configuration scripts, which we
383
hope to make more sensible soon.  Let's say your new host is called an
384
XYZ (e.g.  `sun4'), and its full three-part configuration name is
385
`ARCH-XVEND-XOS' (e.g.  `sparc-sun-sunos4').  In particular:
386
 
387
   In the top level directory, edit `config.sub' and add ARCH, XVEND,
388
and XOS to the lists of supported architectures, vendors, and operating
389
systems near the bottom of the file.  Also, add XYZ as an alias that
390
maps to `ARCH-XVEND-XOS'.  You can test your changes by running
391
 
392
     ./config.sub XYZ
393
 
394
and
395
     ./config.sub `ARCH-XVEND-XOS'
396
 
397
which should both respond with `ARCH-XVEND-XOS' and no error messages.
398
 
399
   You need to port BFD, if that hasn't been done already.  Porting BFD
400
is beyond the scope of this manual.
401
 
402
   To configure GDB itself, edit `gdb/configure.host' to recognize your
403
system and set `gdb_host' to XYZ, and (unless your desired target is
404
already available) also edit `gdb/configure.tgt', setting `gdb_target'
405
to something appropriate (for instance, XYZ).
406
 
407
   Finally, you'll need to specify and define GDB's host-, native-, and
408
target-dependent `.h' and `.c' files used for your configuration.
409
 
410
Configuring GDB for Release
411
===========================
412
 
413
   From the top level directory (containing `gdb', `bfd', `libiberty',
414
and so on):
415
     make -f Makefile.in gdb.tar.gz
416
 
417
   This will properly configure, clean, rebuild any files that are
418
distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will
419
then make a tarfile.  (If the top level directory has already been
420
configured, you can just do `make gdb.tar.gz' instead.)
421
 
422
   This procedure requires:
423
   * symbolic links
424
 
425
   * `makeinfo' (texinfo2 level)
426
 
427
   * TeX
428
 
429
   * `dvips'
430
 
431
   * `yacc' or `bison'
432
 
433
... and the usual slew of utilities (`sed', `tar', etc.).
434
 
435
TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
436
---------------------------------------------
437
 
438
   `gdb.texinfo' is currently marked up using the texinfo-2 macros,
439
which are not yet a default for anything (but we have to start using
440
them sometime).
441
 
442
   For making paper, the only thing this implies is the right
443
generation of `texinfo.tex' needs to be included in the distribution.
444
 
445
   For making info files, however, rather than duplicating the texinfo2
446
distribution, generate `gdb-all.texinfo' locally, and include the files
447
`gdb.info*' in the distribution.  Note the plural; `makeinfo' will
448
split the document into one overall file and five or so included files.
449
 
450

451
File: gdbint.info,  Node: Testsuite,  Next: Hints,  Prev: Porting GDB,  Up: Top
452
 
453
Testsuite
454
*********
455
 
456
   The testsuite is an important component of the GDB package.  While
457
it is always worthwhile to encourage user testing, in practice this is
458
rarely sufficient; users typically use only a small subset of the
459
available commands, and it has proven all too common for a change to
460
cause a significant regression that went unnoticed for some time.
461
 
462
   The GDB testsuite uses the DejaGNU testing framework.  DejaGNU is
463
built using tcl and expect.  The tests themselves are calls to various
464
tcl procs; the framework runs all the procs and summarizes the passes
465
and fails.
466
 
467
Using the Testsuite
468
===================
469
 
470
   To run the testsuite, simply go to the GDB object directory (or to
471
the testsuite's objdir) and type `make check'.  This just sets up some
472
environment variables and invokes DejaGNU's `runtest' script.  While
473
the testsuite is running, you'll get mentions of which test file is in
474
use, and a mention of any unexpected passes or fails.  When the
475
testsuite is finished, you'll get a summary that looks like this:
476
                     === gdb Summary ===
477
 
478
     # of expected passes            6016
479
     # of unexpected failures        58
480
     # of unexpected successes       5
481
     # of expected failures          183
482
     # of unresolved testcases       3
483
     # of untested testcases         5
484
   The ideal test run consists of expected passes only; however, reality
485
conspires to keep us from this ideal.  Unexpected failures indicate
486
real problems, whether in GDB or in the testsuite.  Expected failures
487
are still failures, but ones which have been decided are too hard to
488
deal with at the time; for instance, a test case might work everywhere
489
except on AIX, and there is no prospect of the AIX case being fixed in
490
the near future.  Expected failures should not be added lightly, since
491
you may be masking serious bugs in GDB.  Unexpected successes are
492
expected fails that are passing for some reason, while unresolved and
493
untested cases often indicate some minor catastrophe, such as the
494
compiler being unable to deal with a test program.
495
 
496
   When making any significant change to GDB, you should run the
497
testsuite before and after the change, to confirm that there are no
498
regressions.  Note that truly complete testing would require that you
499
run the testsuite with all supported configurations and a variety of
500
compilers; however this is more than really necessary.  In many cases
501
testing with a single configuration is sufficient.  Other useful
502
options are to test one big-endian (Sparc) and one little-endian (x86)
503
host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
504
or a 64-bit host (Alpha).
505
 
506
   If you add new functionality to GDB, please consider adding tests
507
for it as well; this way future GDB hackers can detect and fix their
508
changes that break the functionality you added.  Similarly, if you fix
509
a bug that was not previously reported as a test failure, please add a
510
test case for it.  Some cases are extremely difficult to test, such as
511
code that handles host OS failures or bugs in particular versions of
512
compilers, and it's OK not to try to write tests for all of those.
513
 
514
Testsuite Organization
515
======================
516
 
517
   The testsuite is entirely contained in `gdb/testsuite'.  While the
518
testsuite includes some makefiles and configury, these are very minimal,
519
and used for little besides cleaning up, since the tests themselves
520
handle the compilation of the programs that GDB will run.  The file
521
`testsuite/lib/gdb.exp' contains common utility procs useful for all
522
GDB tests, while the directory `testsuite/config' contains
523
configuration-specific files, typically used for special-purpose
524
definitions of procs like `gdb_load' and `gdb_start'.
525
 
526
   The tests themselves are to be found in `testsuite/gdb.*' and
527
subdirectories of those.  The names of the test files must always end
528
with `.exp'.  DejaGNU collects the test files by wildcarding in the
529
test directories, so both subdirectories and individual files get
530
chosen and run in alphabetical order.
531
 
532
   The following table lists the main types of subdirectories and what
533
they are for.  Since DejaGNU finds test files no matter where they are
534
located, and since each test file sets up its own compilation and
535
execution environment, this organization is simply for convenience and
536
intelligibility.
537
 
538
`gdb.base'
539
     This is the base testsuite.  The tests in it should apply to all
540
     configurations of GDB (but generic native-only tests may live
541
     here).  The test programs should be in the subset of C that is
542
     valid K&R, ANSI/ISO, and C++ (ifdefs are allowed if necessary, for
543
     instance for prototypes).
544
 
545
`gdb.LANG'
546
     Language-specific tests for all languages besides C.  Examples are
547
     `gdb.c++' and `gdb.java'.
548
 
549
`gdb.PLATFORM'
550
     Non-portable tests.  The tests are specific to a specific
551
     configuration (host or target), such as HP-UX or eCos.  Example is
552
     `gdb.hp', for HP-UX.
553
 
554
`gdb.COMPILER'
555
     Tests specific to a particular compiler.  As of this writing (June
556
     1999), there aren't currently any groups of tests in this category
557
     that couldn't just as sensibly be made platform-specific, but one
558
     could imagine a gdb.gcc, for tests of GDB's handling of GCC
559
     extensions.
560
 
561
`gdb.SUBSYSTEM'
562
     Tests that exercise a specific GDB subsystem in more depth.  For
563
     instance, `gdb.disasm' exercises various disassemblers, while
564
     `gdb.stabs' tests pathways through the stabs symbol reader.
565
 
566
Writing Tests
567
=============
568
 
569
   In many areas, the GDB tests are already quite comprehensive; you
570
should be able to copy existing tests to handle new cases.
571
 
572
   You should try to use `gdb_test' whenever possible, since it
573
includes cases to handle all the unexpected errors that might happen.
574
However, it doesn't cost anything to add new test procedures; for
575
instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
576
`gdb_test' multiple times.
577
 
578
   Only use `send_gdb' and `gdb_expect' when absolutely necessary, such
579
as when GDB has several valid responses to a command.
580
 
581
   The source language programs do _not_ need to be in a consistent
582
style.  Since GDB is used to debug programs written in many different
583
styles, it's worth having a mix of styles in the testsuite; for
584
instance, some GDB bugs involving the display of source lines would
585
never manifest themselves if the programs used GNU coding style
586
uniformly.
587
 
588

589
File: gdbint.info,  Node: Hints,  Prev: Testsuite,  Up: Top
590
 
591
Hints
592
*****
593
 
594
   Check the `README' file, it often has useful information that does
595
not appear anywhere else in the directory.
596
 
597
* Menu:
598
 
599
* Getting Started::             Getting started working on GDB
600
* Debugging GDB::               Debugging GDB with itself
601
 
602

603
File: gdbint.info,  Node: Getting Started,  Up: Hints
604
 
605
Getting Started
606
===============
607
 
608
   GDB is a large and complicated program, and if you first starting to
609
work on it, it can be hard to know where to start.  Fortunately, if you
610
know how to go about it, there are ways to figure out what is going on.
611
 
612
   This manual, the GDB Internals manual, has information which applies
613
generally to many parts of GDB.
614
 
615
   Information about particular functions or data structures are
616
located in comments with those functions or data structures.  If you
617
run across a function or a global variable which does not have a
618
comment correctly explaining what is does, this can be thought of as a
619
bug in GDB; feel free to submit a bug report, with a suggested comment
620
if you can figure out what the comment should say.  If you find a
621
comment which is actually wrong, be especially sure to report that.
622
 
623
   Comments explaining the function of macros defined in host, target,
624
or native dependent files can be in several places.  Sometimes they are
625
repeated every place the macro is defined.  Sometimes they are where the
626
macro is used.  Sometimes there is a header file which supplies a
627
default definition of the macro, and the comment is there.  This manual
628
also documents all the available macros.
629
 
630
   Start with the header files.  Once you have some idea of how GDB's
631
internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
632
will find it much easier to understand the code which uses and creates
633
those symbol tables.
634
 
635
   You may wish to process the information you are getting somehow, to
636
enhance your understanding of it.  Summarize it, translate it to another
637
language, add some (perhaps trivial or non-useful) feature to GDB, use
638
the code to predict what a test case would do and write the test case
639
and verify your prediction, etc.  If you are reading code and your eyes
640
are starting to glaze over, this is a sign you need to use a more active
641
approach.
642
 
643
   Once you have a part of GDB to start with, you can find more
644
specifically the part you are looking for by stepping through each
645
function with the `next' command.  Do not use `step' or you will
646
quickly get distracted; when the function you are stepping through
647
calls another function try only to get a big-picture understanding
648
(perhaps using the comment at the beginning of the function being
649
called) of what it does.  This way you can identify which of the
650
functions being called by the function you are stepping through is the
651
one which you are interested in.  You may need to examine the data
652
structures generated at each stage, with reference to the comments in
653
the header files explaining what the data structures are supposed to
654
look like.
655
 
656
   Of course, this same technique can be used if you are just reading
657
the code, rather than actually stepping through it.  The same general
658
principle applies--when the code you are looking at calls something
659
else, just try to understand generally what the code being called does,
660
rather than worrying about all its details.
661
 
662
   A good place to start when tracking down some particular area is
663
with a command which invokes that feature.  Suppose you want to know how
664
single-stepping works.  As a GDB user, you know that the `step' command
665
invokes single-stepping.  The command is invoked via command tables
666
(see `command.h'); by convention the function which actually performs
667
the command is formed by taking the name of the command and adding
668
`_command', or in the case of an `info' subcommand, `_info'.  For
669
example, the `step' command invokes the `step_command' function and the
670
`info display' command invokes `display_info'.  When this convention is
671
not followed, you might have to use `grep' or `M-x tags-search' in
672
emacs, or run GDB on itself and set a breakpoint in `execute_command'.
673
 
674
   If all of the above fail, it may be appropriate to ask for
675
information on `bug-gdb'.  But _never_ post a generic question like "I
676
was wondering if anyone could give me some tips about understanding
677
GDB"--if we had some magic secret we would put it in this manual.
678
Suggestions for improving the manual are always welcome, of course.
679
 
680

681
File: gdbint.info,  Node: Debugging GDB,  Up: Hints
682
 
683
Debugging GDB with itself
684
=========================
685
 
686
   If GDB is limping on your machine, this is the preferred way to get
687
it fully functional.  Be warned that in some ancient Unix systems, like
688
Ultrix 4.2, a program can't be running in one process while it is being
689
debugged in another.  Rather than typing the command `./gdb ./gdb',
690
which works on Suns and such, you can copy `gdb' to `gdb2' and then
691
type `./gdb ./gdb2'.
692
 
693
   When you run GDB in the GDB source directory, it will read a
694
`.gdbinit' file that sets up some simple things to make debugging gdb
695
easier.  The `info' command, when executed without a subcommand in a
696
GDB being debugged by gdb, will pop you back up to the top level gdb.
697
See `.gdbinit' for details.
698
 
699
   If you use emacs, you will probably want to do a `make TAGS' after
700
you configure your distribution; this will put the machine dependent
701
routines for your local machine where they will be accessed first by
702
`M-.'
703
 
704
   Also, make sure that you've either compiled GDB with your local cc,
705
or have run `fixincludes' if you are compiling with gcc.
706
 
707
Submitting Patches
708
==================
709
 
710
   Thanks for thinking of offering your changes back to the community of
711
GDB users.  In general we like to get well designed enhancements.
712
Thanks also for checking in advance about the best way to transfer the
713
changes.
714
 
715
   The GDB maintainers will only install "cleanly designed" patches.
716
This manual summarizes what we believe to be clean design for GDB.
717
 
718
   If the maintainers don't have time to put the patch in when it
719
arrives, or if there is any question about a patch, it goes into a
720
large queue with everyone else's patches and bug reports.
721
 
722
   The legal issue is that to incorporate substantial changes requires a
723
copyright assignment from you and/or your employer, granting ownership
724
of the changes to the Free Software Foundation.  You can get the
725
standard documents for doing this by sending mail to `gnu@gnu.org' and
726
asking for it.  We recommend that people write in "All programs owned
727
by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
728
in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
729
contributed with only one piece of legalese pushed through the
730
bureacracy and filed with the FSF.  We can't start merging changes until
731
this paperwork is received by the FSF (their rules, which we follow
732
since we maintain it for them).
733
 
734
   Technically, the easiest way to receive changes is to receive each
735
feature as a small context diff or unidiff, suitable for "patch".  Each
736
message sent to me should include the changes to C code and header files
737
for a single feature, plus ChangeLog entries for each directory where
738
files were modified, and diffs for any changes needed to the manuals
739
(gdb/doc/gdb.texinfo or gdb/doc/gdbint.texinfo).  If there are a lot of
740
changes for a single feature, they can be split down into multiple
741
messages.
742
 
743
   In this way, if we read and like the feature, we can add it to the
744
sources with a single patch command, do some testing, and check it in.
745
If you leave out the ChangeLog, we have to write one.  If you leave out
746
the doc, we have to puzzle out what needs documenting.  Etc.
747
 
748
   The reason to send each change in a separate message is that we will
749
not install some of the changes.  They'll be returned to you with
750
questions or comments.  If we're doing our job correctly, the message
751
back to you will say what you have to fix in order to make the change
752
acceptable.  The reason to have separate messages for separate features
753
is so that the acceptable changes can be installed while one or more
754
changes are being reworked.  If multiple features are sent in a single
755
message, we tend to not put in the effort to sort out the acceptable
756
changes from the unacceptable, so none of the features get installed
757
until all are acceptable.
758
 
759
   If this sounds painful or authoritarian, well, it is.  But we get a
760
lot of bug reports and a lot of patches, and many of them don't get
761
installed because we don't have the time to finish the job that the bug
762
reporter or the contributor could have done.  Patches that arrive
763
complete, working, and well designed, tend to get installed on the day
764
they arrive.  The others go into a queue and get installed as time
765
permits, which, since the maintainers have many demands to meet, may not
766
be for quite some time.
767
 
768
   Please send patches directly to the GDB maintainers at
769
`gdb-patches@sourceware.cygnus.com'.
770
 
771
Obsolete Conditionals
772
=====================
773
 
774
   Fragments of old code in GDB sometimes reference or set the following
775
configuration macros.  They should not be used by new code, and old uses
776
should be removed as those parts of the debugger are otherwise touched.
777
 
778
`STACK_END_ADDR'
779
     This macro used to define where the end of the stack appeared, for
780
     use in interpreting core file formats that don't record this
781
     address in the core file itself.  This information is now
782
     configured in BFD, and GDB gets the info portably from there.  The
783
     values in GDB's configuration files should be moved into BFD
784
     configuration files (if needed there), and deleted from all of
785
     GDB's config files.
786
 
787
     Any `FOO-xdep.c' file that references STACK_END_ADDR is so old
788
     that it has never been converted to use BFD.  Now that's old!
789
 
790
`PYRAMID_CONTROL_FRAME_DEBUGGING'
791
     pyr-xdep.c
792
 
793
`PYRAMID_CORE'
794
     pyr-xdep.c
795
 
796
`PYRAMID_PTRACE'
797
     pyr-xdep.c
798
 
799
`REG_STACK_SEGMENT'
800
     exec.c
801
 
802
 

powered by: WebSVN 2.1.0

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