This is gdbint.info, produced by Makeinfo version 3.12f from
|
This is gdbint.info, produced by Makeinfo version 3.12f from
|
./gdbint.texinfo.
|
./gdbint.texinfo.
|
|
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb-Internals: (gdbint). The GNU debugger's internals.
|
* Gdb-Internals: (gdbint). The GNU debugger's internals.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the internals of the GNU debugger GDB.
|
This file documents the internals of the GNU debugger GDB.
|
|
|
Copyright 1990-1999 Free Software Foundation, Inc. Contributed by
|
Copyright 1990-1999 Free Software Foundation, Inc. Contributed by
|
Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
|
Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
|
Shebs.
|
Shebs.
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
Permission is granted to make and distribute verbatim copies of this
|
manual provided the copyright notice and this permission notice are
|
manual provided the copyright notice and this permission notice are
|
preserved on all copies.
|
preserved on all copies.
|
|
|
Permission is granted to copy or distribute modified versions of this
|
Permission is granted to copy or distribute modified versions of this
|
manual under the terms of the GPL (for which purpose this text may be
|
manual under the terms of the GPL (for which purpose this text may be
|
regarded as a program in the language TeX).
|
regarded as a program in the language TeX).
|
|
|
|
|
File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
|
File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
|
|
|
Support Libraries
|
Support Libraries
|
*****************
|
*****************
|
|
|
BFD
|
BFD
|
===
|
===
|
|
|
BFD provides support for GDB in several ways:
|
BFD provides support for GDB in several ways:
|
|
|
_identifying executable and core files_
|
_identifying executable and core files_
|
BFD will identify a variety of file types, including a.out, coff,
|
BFD will identify a variety of file types, including a.out, coff,
|
and several variants thereof, as well as several kinds of core
|
and several variants thereof, as well as several kinds of core
|
files.
|
files.
|
|
|
_access to sections of files_
|
_access to sections of files_
|
BFD parses the file headers to determine the names, virtual
|
BFD parses the file headers to determine the names, virtual
|
addresses, sizes, and file locations of all the various named
|
addresses, sizes, and file locations of all the various named
|
sections in files (such as the text section or the data section).
|
sections in files (such as the text section or the data section).
|
GDB simply calls BFD to read or write section X at byte offset Y
|
GDB simply calls BFD to read or write section X at byte offset Y
|
for length Z.
|
for length Z.
|
|
|
_specialized core file support_
|
_specialized core file support_
|
BFD provides routines to determine the failing command name stored
|
BFD provides routines to determine the failing command name stored
|
in a core file, the signal with which the program failed, and
|
in a core file, the signal with which the program failed, and
|
whether a core file matches (i.e. could be a core dump of) a
|
whether a core file matches (i.e. could be a core dump of) a
|
particular executable file.
|
particular executable file.
|
|
|
_locating the symbol information_
|
_locating the symbol information_
|
GDB uses an internal interface of BFD to determine where to find
|
GDB uses an internal interface of BFD to determine where to find
|
the symbol information in an executable file or symbol-file. GDB
|
the symbol information in an executable file or symbol-file. GDB
|
itself handles the reading of symbols, since BFD does not
|
itself handles the reading of symbols, since BFD does not
|
"understand" debug symbols, but GDB uses BFD's cached information
|
"understand" debug symbols, but GDB uses BFD's cached information
|
to find the symbols, string table, etc.
|
to find the symbols, string table, etc.
|
|
|
opcodes
|
opcodes
|
=======
|
=======
|
|
|
The opcodes library provides GDB's disassembler. (It's a separate
|
The opcodes library provides GDB's disassembler. (It's a separate
|
library because it's also used in binutils, for `objdump').
|
library because it's also used in binutils, for `objdump').
|
|
|
readline
|
readline
|
========
|
========
|
|
|
mmalloc
|
mmalloc
|
=======
|
=======
|
|
|
libiberty
|
libiberty
|
=========
|
=========
|
|
|
gnu-regex
|
gnu-regex
|
=========
|
=========
|
|
|
Regex conditionals.
|
Regex conditionals.
|
|
|
`C_ALLOCA'
|
`C_ALLOCA'
|
|
|
`NFAILURES'
|
`NFAILURES'
|
|
|
`RE_NREGS'
|
`RE_NREGS'
|
|
|
`SIGN_EXTEND_CHAR'
|
`SIGN_EXTEND_CHAR'
|
|
|
`SWITCH_ENUM_BUG'
|
`SWITCH_ENUM_BUG'
|
|
|
`SYNTAX_TABLE'
|
`SYNTAX_TABLE'
|
|
|
`Sword'
|
`Sword'
|
|
|
`sparc'
|
`sparc'
|
include
|
include
|
=======
|
=======
|
|
|
|
|
File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
|
File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
|
|
|
Coding
|
Coding
|
******
|
******
|
|
|
This chapter covers topics that are lower-level than the major
|
This chapter covers topics that are lower-level than the major
|
algorithms of GDB.
|
algorithms of GDB.
|
|
|
Cleanups
|
Cleanups
|
========
|
========
|
|
|
Cleanups are a structured way to deal with things that need to be
|
Cleanups are a structured way to deal with things that need to be
|
done later. When your code does something (like `malloc' some memory,
|
done later. When your code does something (like `malloc' some memory,
|
or open a file) that needs to be undone later (e.g. free the memory or
|
or open a file) that needs to be undone later (e.g. free the memory or
|
close the file), it can make a cleanup. The cleanup will be done at
|
close the file), it can make a cleanup. The cleanup will be done at
|
some future point: when the command is finished, when an error occurs,
|
some future point: when the command is finished, when an error occurs,
|
or when your code decides it's time to do cleanups.
|
or when your code decides it's time to do cleanups.
|
|
|
You can also discard cleanups, that is, throw them away without doing
|
You can also discard cleanups, that is, throw them away without doing
|
what they say. This is only done if you ask that it be done.
|
what they say. This is only done if you ask that it be done.
|
|
|
Syntax:
|
Syntax:
|
|
|
`struct cleanup *OLD_CHAIN;'
|
`struct cleanup *OLD_CHAIN;'
|
Declare a variable which will hold a cleanup chain handle.
|
Declare a variable which will hold a cleanup chain handle.
|
|
|
`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
|
`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
|
Make a cleanup which will cause FUNCTION to be called with ARG (a
|
Make a cleanup which will cause FUNCTION to be called with ARG (a
|
`char *') later. The result, OLD_CHAIN, is a handle that can be
|
`char *') later. The result, OLD_CHAIN, is a handle that can be
|
passed to `do_cleanups' or `discard_cleanups' later. Unless you
|
passed to `do_cleanups' or `discard_cleanups' later. Unless you
|
are going to call `do_cleanups' or `discard_cleanups' yourself,
|
are going to call `do_cleanups' or `discard_cleanups' yourself,
|
you can ignore the result from `make_cleanup'.
|
you can ignore the result from `make_cleanup'.
|
|
|
`do_cleanups (OLD_CHAIN);'
|
`do_cleanups (OLD_CHAIN);'
|
Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
|
Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
|
E.g.:
|
E.g.:
|
make_cleanup (a, 0);
|
make_cleanup (a, 0);
|
old = make_cleanup (b, 0);
|
old = make_cleanup (b, 0);
|
do_cleanups (old);
|
do_cleanups (old);
|
|
|
will call `b()' but will not call `a()'. The cleanup that calls
|
will call `b()' but will not call `a()'. The cleanup that calls
|
`a()' will remain in the cleanup chain, and will be done later
|
`a()' will remain in the cleanup chain, and will be done later
|
unless otherwise discarded.
|
unless otherwise discarded.
|
|
|
`discard_cleanups (OLD_CHAIN);'
|
`discard_cleanups (OLD_CHAIN);'
|
Same as `do_cleanups' except that it just removes the cleanups from
|
Same as `do_cleanups' except that it just removes the cleanups from
|
the chain and does not call the specified functions.
|
the chain and does not call the specified functions.
|
|
|
Some functions, e.g. `fputs_filtered()' or `error()', specify that
|
Some functions, e.g. `fputs_filtered()' or `error()', specify that
|
they "should not be called when cleanups are not in place". This means
|
they "should not be called when cleanups are not in place". This means
|
that any actions you need to reverse in the case of an error or
|
that any actions you need to reverse in the case of an error or
|
interruption must be on the cleanup chain before you call these
|
interruption must be on the cleanup chain before you call these
|
functions, since they might never return to your code (they `longjmp'
|
functions, since they might never return to your code (they `longjmp'
|
instead).
|
instead).
|
|
|
Wrapping Output Lines
|
Wrapping Output Lines
|
=====================
|
=====================
|
|
|
Output that goes through `printf_filtered' or `fputs_filtered' or
|
Output that goes through `printf_filtered' or `fputs_filtered' or
|
`fputs_demangled' needs only to have calls to `wrap_here' added in
|
`fputs_demangled' needs only to have calls to `wrap_here' added in
|
places that would be good breaking points. The utility routines will
|
places that would be good breaking points. The utility routines will
|
take care of actually wrapping if the line width is exceeded.
|
take care of actually wrapping if the line width is exceeded.
|
|
|
The argument to `wrap_here' is an indentation string which is
|
The argument to `wrap_here' is an indentation string which is
|
printed _only_ if the line breaks there. This argument is saved away
|
printed _only_ if the line breaks there. This argument is saved away
|
and used later. It must remain valid until the next call to
|
and used later. It must remain valid until the next call to
|
`wrap_here' or until a newline has been printed through the
|
`wrap_here' or until a newline has been printed through the
|
`*_filtered' functions. Don't pass in a local variable and then return!
|
`*_filtered' functions. Don't pass in a local variable and then return!
|
|
|
It is usually best to call `wrap_here()' after printing a comma or
|
It is usually best to call `wrap_here()' after printing a comma or
|
space. If you call it before printing a space, make sure that your
|
space. If you call it before printing a space, make sure that your
|
indentation properly accounts for the leading space that will print if
|
indentation properly accounts for the leading space that will print if
|
the line wraps there.
|
the line wraps there.
|
|
|
Any function or set of functions that produce filtered output must
|
Any function or set of functions that produce filtered output must
|
finish by printing a newline, to flush the wrap buffer, before switching
|
finish by printing a newline, to flush the wrap buffer, before switching
|
to unfiltered ("`printf'") output. Symbol reading routines that print
|
to unfiltered ("`printf'") output. Symbol reading routines that print
|
warnings are a good example.
|
warnings are a good example.
|
|
|
GDB Coding Standards
|
GDB Coding Standards
|
====================
|
====================
|
|
|
GDB follows the GNU coding standards, as described in
|
GDB follows the GNU coding standards, as described in
|
`etc/standards.texi'. This file is also available for anonymous FTP
|
`etc/standards.texi'. This file is also available for anonymous FTP
|
from GNU archive sites. GDB takes a strict interpretation of the
|
from GNU archive sites. GDB takes a strict interpretation of the
|
standard; in general, when the GNU standard recommends a practice but
|
standard; in general, when the GNU standard recommends a practice but
|
does not require it, GDB requires it.
|
does not require it, GDB requires it.
|
|
|
GDB follows an additional set of coding standards specific to GDB,
|
GDB follows an additional set of coding standards specific to GDB,
|
as described in the following sections.
|
as described in the following sections.
|
|
|
You can configure with `--enable-build-warnings' to get GCC to check
|
You can configure with `--enable-build-warnings' to get GCC to check
|
on a number of these rules. GDB sources ought not to engender any
|
on a number of these rules. GDB sources ought not to engender any
|
complaints, unless they are caused by bogus host systems. (The exact
|
complaints, unless they are caused by bogus host systems. (The exact
|
set of enabled warnings is currently `-Wall -Wpointer-arith
|
set of enabled warnings is currently `-Wall -Wpointer-arith
|
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
|
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
|
|
|
Formatting
|
Formatting
|
----------
|
----------
|
|
|
The standard GNU recommendations for formatting must be followed
|
The standard GNU recommendations for formatting must be followed
|
strictly.
|
strictly.
|
|
|
Note that while in a definition, the function's name must be in
|
Note that while in a definition, the function's name must be in
|
column zero; in a function declaration, the name must be on the same
|
column zero; in a function declaration, the name must be on the same
|
line as the return type.
|
line as the return type.
|
|
|
In addition, there must be a space between a function or macro name
|
In addition, there must be a space between a function or macro name
|
and the opening parenthesis of its argument list (except for macro
|
and the opening parenthesis of its argument list (except for macro
|
definitions, as required by C). There must not be a space after an open
|
definitions, as required by C). There must not be a space after an open
|
paren/bracket or before a close paren/bracket.
|
paren/bracket or before a close paren/bracket.
|
|
|
While additional whitespace is generally helpful for reading, do not
|
While additional whitespace is generally helpful for reading, do not
|
use more than one blank line to separate blocks, and avoid adding
|
use more than one blank line to separate blocks, and avoid adding
|
whitespace after the end of a program line (as of 1/99, some 600 lines
|
whitespace after the end of a program line (as of 1/99, some 600 lines
|
had whitespace after the semicolon). Excess whitespace causes
|
had whitespace after the semicolon). Excess whitespace causes
|
difficulties for diff and patch.
|
difficulties for diff and patch.
|
|
|
Comments
|
Comments
|
--------
|
--------
|
|
|
The standard GNU requirements on comments must be followed strictly.
|
The standard GNU requirements on comments must be followed strictly.
|
|
|
Block comments must appear in the following form, with no `/*'- or
|
Block comments must appear in the following form, with no `/*'- or
|
'*/'-only lines, and no leading `*':
|
'*/'-only lines, and no leading `*':
|
|
|
/* Wait for control to return from inferior to debugger. If inferior
|
/* Wait for control to return from inferior to debugger. If inferior
|
gets a signal, we may decide to start it up again instead of
|
gets a signal, we may decide to start it up again instead of
|
returning. That is why there is a loop in this function. When
|
returning. That is why there is a loop in this function. When
|
this function actually returns it means the inferior should be left
|
this function actually returns it means the inferior should be left
|
stopped and GDB should read more commands. */
|
stopped and GDB should read more commands. */
|
|
|
(Note that this format is encouraged by Emacs; tabbing for a
|
(Note that this format is encouraged by Emacs; tabbing for a
|
multi-line comment works correctly, and M-Q fills the block
|
multi-line comment works correctly, and M-Q fills the block
|
consistently.)
|
consistently.)
|
|
|
Put a blank line between the block comments preceding function or
|
Put a blank line between the block comments preceding function or
|
variable definitions, and the definition itself.
|
variable definitions, and the definition itself.
|
|
|
In general, put function-body comments on lines by themselves, rather
|
In general, put function-body comments on lines by themselves, rather
|
than trying to fit them into the 20 characters left at the end of a
|
than trying to fit them into the 20 characters left at the end of a
|
line, since either the comment or the code will inevitably get longer
|
line, since either the comment or the code will inevitably get longer
|
than will fit, and then somebody will have to move it anyhow.
|
than will fit, and then somebody will have to move it anyhow.
|
|
|
C Usage
|
C Usage
|
-------
|
-------
|
|
|
Code must not depend on the sizes of C data types, the format of the
|
Code must not depend on the sizes of C data types, the format of the
|
host's floating point numbers, the alignment of anything, or the order
|
host's floating point numbers, the alignment of anything, or the order
|
of evaluation of expressions.
|
of evaluation of expressions.
|
|
|
Use functions freely. There are only a handful of compute-bound
|
Use functions freely. There are only a handful of compute-bound
|
areas in GDB that might be affected by the overhead of a function call,
|
areas in GDB that might be affected by the overhead of a function call,
|
mainly in symbol reading. Most of GDB's performance is limited by the
|
mainly in symbol reading. Most of GDB's performance is limited by the
|
target interface (whether serial line or system call).
|
target interface (whether serial line or system call).
|
|
|
However, use functions with moderation. A thousand one-line
|
However, use functions with moderation. A thousand one-line
|
functions are just as hard to understand as a single thousand-line
|
functions are just as hard to understand as a single thousand-line
|
function.
|
function.
|
|
|
Function Prototypes
|
Function Prototypes
|
-------------------
|
-------------------
|
|
|
Prototypes must be used to _declare_ functions, and may be used to
|
Prototypes must be used to _declare_ functions, and may be used to
|
_define_ them. Prototypes for GDB functions must include both the
|
_define_ them. Prototypes for GDB functions must include both the
|
argument type and name, with the name matching that used in the actual
|
argument type and name, with the name matching that used in the actual
|
function definition.
|
function definition.
|
|
|
All external functions should have a declaration in a header file
|
All external functions should have a declaration in a header file
|
that callers include, except for `_initialize_*' functions, which must
|
that callers include, except for `_initialize_*' functions, which must
|
be external so that `init.c' construction works, but shouldn't be
|
be external so that `init.c' construction works, but shouldn't be
|
visible to random source files.
|
visible to random source files.
|
|
|
All static functions must be declared in a block near the top of the
|
All static functions must be declared in a block near the top of the
|
source file.
|
source file.
|
|
|
Clean Design
|
Clean Design
|
------------
|
------------
|
|
|
In addition to getting the syntax right, there's the little question
|
In addition to getting the syntax right, there's the little question
|
of semantics. Some things are done in certain ways in GDB because long
|
of semantics. Some things are done in certain ways in GDB because long
|
experience has shown that the more obvious ways caused various kinds of
|
experience has shown that the more obvious ways caused various kinds of
|
trouble.
|
trouble.
|
|
|
You can't assume the byte order of anything that comes from a target
|
You can't assume the byte order of anything that comes from a target
|
(including VALUEs, object files, and instructions). Such things must
|
(including VALUEs, object files, and instructions). Such things must
|
be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
|
be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
|
routines defined in `bfd.h', such as `bfd_get_32'.
|
routines defined in `bfd.h', such as `bfd_get_32'.
|
|
|
You can't assume that you know what interface is being used to talk
|
You can't assume that you know what interface is being used to talk
|
to the target system. All references to the target must go through the
|
to the target system. All references to the target must go through the
|
current `target_ops' vector.
|
current `target_ops' vector.
|
|
|
You can't assume that the host and target machines are the same
|
You can't assume that the host and target machines are the same
|
machine (except in the "native" support modules). In particular, you
|
machine (except in the "native" support modules). In particular, you
|
can't assume that the target machine's header files will be available
|
can't assume that the target machine's header files will be available
|
on the host machine. Target code must bring along its own header files
|
on the host machine. Target code must bring along its own header files
|
- written from scratch or explicitly donated by their owner, to avoid
|
- written from scratch or explicitly donated by their owner, to avoid
|
copyright problems.
|
copyright problems.
|
|
|
Insertion of new `#ifdef''s will be frowned upon. It's much better
|
Insertion of new `#ifdef''s will be frowned upon. It's much better
|
to write the code portably than to conditionalize it for various
|
to write the code portably than to conditionalize it for various
|
systems.
|
systems.
|
|
|
New `#ifdef''s which test for specific compilers or manufacturers or
|
New `#ifdef''s which test for specific compilers or manufacturers or
|
operating systems are unacceptable. All `#ifdef''s should test for
|
operating systems are unacceptable. All `#ifdef''s should test for
|
features. The information about which configurations contain which
|
features. The information about which configurations contain which
|
features should be segregated into the configuration files. Experience
|
features should be segregated into the configuration files. Experience
|
has proven far too often that a feature unique to one particular system
|
has proven far too often that a feature unique to one particular system
|
often creeps into other systems; and that a conditional based on some
|
often creeps into other systems; and that a conditional based on some
|
predefined macro for your current system will become worthless over
|
predefined macro for your current system will become worthless over
|
time, as new versions of your system come out that behave differently
|
time, as new versions of your system come out that behave differently
|
with regard to this feature.
|
with regard to this feature.
|
|
|
Adding code that handles specific architectures, operating systems,
|
Adding code that handles specific architectures, operating systems,
|
target interfaces, or hosts, is not acceptable in generic code. If a
|
target interfaces, or hosts, is not acceptable in generic code. If a
|
hook is needed at that point, invent a generic hook and define it for
|
hook is needed at that point, invent a generic hook and define it for
|
your configuration, with something like:
|
your configuration, with something like:
|
|
|
#ifdef WRANGLE_SIGNALS
|
#ifdef WRANGLE_SIGNALS
|
WRANGLE_SIGNALS (signo);
|
WRANGLE_SIGNALS (signo);
|
#endif
|
#endif
|
|
|
In your host, target, or native configuration file, as appropriate,
|
In your host, target, or native configuration file, as appropriate,
|
define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit
|
define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit
|
of care in defining the hook, so that it can be used by other ports in
|
of care in defining the hook, so that it can be used by other ports in
|
the future, if they need a hook in the same place.
|
the future, if they need a hook in the same place.
|
|
|
If the hook is not defined, the code should do whatever "most"
|
If the hook is not defined, the code should do whatever "most"
|
machines want. Using `#ifdef', as above, is the preferred way to do
|
machines want. Using `#ifdef', as above, is the preferred way to do
|
this, but sometimes that gets convoluted, in which case use
|
this, but sometimes that gets convoluted, in which case use
|
|
|
#ifndef SPECIAL_FOO_HANDLING
|
#ifndef SPECIAL_FOO_HANDLING
|
#define SPECIAL_FOO_HANDLING(pc, sp) (0)
|
#define SPECIAL_FOO_HANDLING(pc, sp) (0)
|
#endif
|
#endif
|
|
|
where the macro is used or in an appropriate header file.
|
where the macro is used or in an appropriate header file.
|
|
|
Whether to include a "small" hook, a hook around the exact pieces of
|
Whether to include a "small" hook, a hook around the exact pieces of
|
code which are system-dependent, or whether to replace a whole function
|
code which are system-dependent, or whether to replace a whole function
|
with a hook depends on the case. A good example of this dilemma can be
|
with a hook depends on the case. A good example of this dilemma can be
|
found in `get_saved_register'. All machines that GDB 2.8 ran on just
|
found in `get_saved_register'. All machines that GDB 2.8 ran on just
|
needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
|
needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
|
Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
|
Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
|
`REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required
|
`REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required
|
the `GET_SAVED_REGISTER' hook. The first three are examples of small
|
the `GET_SAVED_REGISTER' hook. The first three are examples of small
|
hooks; the latter replaces a whole function. In this specific case, it
|
hooks; the latter replaces a whole function. In this specific case, it
|
is useful to have both kinds; it would be a bad idea to replace all the
|
is useful to have both kinds; it would be a bad idea to replace all the
|
uses of the small hooks with `GET_SAVED_REGISTER', since that would
|
uses of the small hooks with `GET_SAVED_REGISTER', since that would
|
result in much duplicated code. Other times, duplicating a few lines
|
result in much duplicated code. Other times, duplicating a few lines
|
of code here or there is much cleaner than introducing a large number
|
of code here or there is much cleaner than introducing a large number
|
of small hooks.
|
of small hooks.
|
|
|
Another way to generalize GDB along a particular interface is with an
|
Another way to generalize GDB along a particular interface is with an
|
attribute struct. For example, GDB has been generalized to handle
|
attribute struct. For example, GDB has been generalized to handle
|
multiple kinds of remote interfaces - not by #ifdef's everywhere, but
|
multiple kinds of remote interfaces - not by #ifdef's everywhere, but
|
by defining the "target_ops" structure and having a current target (as
|
by defining the "target_ops" structure and having a current target (as
|
well as a stack of targets below it, for memory references). Whenever
|
well as a stack of targets below it, for memory references). Whenever
|
something needs to be done that depends on which remote interface we are
|
something needs to be done that depends on which remote interface we are
|
using, a flag in the current target_ops structure is tested (e.g.
|
using, a flag in the current target_ops structure is tested (e.g.
|
`target_has_stack'), or a function is called through a pointer in the
|
`target_has_stack'), or a function is called through a pointer in the
|
current target_ops structure. In this way, when a new remote interface
|
current target_ops structure. In this way, when a new remote interface
|
is added, only one module needs to be touched - the one that actually
|
is added, only one module needs to be touched - the one that actually
|
implements the new remote interface. Other examples of
|
implements the new remote interface. Other examples of
|
attribute-structs are BFD access to multiple kinds of object file
|
attribute-structs are BFD access to multiple kinds of object file
|
formats, or GDB's access to multiple source languages.
|
formats, or GDB's access to multiple source languages.
|
|
|
Please avoid duplicating code. For example, in GDB 3.x all the code
|
Please avoid duplicating code. For example, in GDB 3.x all the code
|
interfacing between `ptrace' and the rest of GDB was duplicated in
|
interfacing between `ptrace' and the rest of GDB was duplicated in
|
`*-dep.c', and so changing something was very painful. In GDB 4.x,
|
`*-dep.c', and so changing something was very painful. In GDB 4.x,
|
these have all been consolidated into `infptrace.c'. `infptrace.c' can
|
these have all been consolidated into `infptrace.c'. `infptrace.c' can
|
deal with variations between systems the same way any
|
deal with variations between systems the same way any
|
system-independent file would (hooks, #if defined, etc.), and machines
|
system-independent file would (hooks, #if defined, etc.), and machines
|
which are radically different don't need to use infptrace.c at all.
|
which are radically different don't need to use infptrace.c at all.
|
|
|
Don't put debugging printfs in the code.
|
Don't put debugging printfs in the code.
|
|
|
|
|
File: gdbint.info, Node: Porting GDB, Next: Testsuite, Prev: Coding, Up: Top
|
File: gdbint.info, Node: Porting GDB, Next: Testsuite, Prev: Coding, Up: Top
|
|
|
Porting GDB
|
Porting GDB
|
***********
|
***********
|
|
|
Most of the work in making GDB compile on a new machine is in
|
Most of the work in making GDB compile on a new machine is in
|
specifying the configuration of the machine. This is done in a
|
specifying the configuration of the machine. This is done in a
|
dizzying variety of header files and configuration scripts, which we
|
dizzying variety of header files and configuration scripts, which we
|
hope to make more sensible soon. Let's say your new host is called an
|
hope to make more sensible soon. Let's say your new host is called an
|
XYZ (e.g. `sun4'), and its full three-part configuration name is
|
XYZ (e.g. `sun4'), and its full three-part configuration name is
|
`ARCH-XVEND-XOS' (e.g. `sparc-sun-sunos4'). In particular:
|
`ARCH-XVEND-XOS' (e.g. `sparc-sun-sunos4'). In particular:
|
|
|
In the top level directory, edit `config.sub' and add ARCH, XVEND,
|
In the top level directory, edit `config.sub' and add ARCH, XVEND,
|
and XOS to the lists of supported architectures, vendors, and operating
|
and XOS to the lists of supported architectures, vendors, and operating
|
systems near the bottom of the file. Also, add XYZ as an alias that
|
systems near the bottom of the file. Also, add XYZ as an alias that
|
maps to `ARCH-XVEND-XOS'. You can test your changes by running
|
maps to `ARCH-XVEND-XOS'. You can test your changes by running
|
|
|
./config.sub XYZ
|
./config.sub XYZ
|
|
|
and
|
and
|
./config.sub `ARCH-XVEND-XOS'
|
./config.sub `ARCH-XVEND-XOS'
|
|
|
which should both respond with `ARCH-XVEND-XOS' and no error messages.
|
which should both respond with `ARCH-XVEND-XOS' and no error messages.
|
|
|
You need to port BFD, if that hasn't been done already. Porting BFD
|
You need to port BFD, if that hasn't been done already. Porting BFD
|
is beyond the scope of this manual.
|
is beyond the scope of this manual.
|
|
|
To configure GDB itself, edit `gdb/configure.host' to recognize your
|
To configure GDB itself, edit `gdb/configure.host' to recognize your
|
system and set `gdb_host' to XYZ, and (unless your desired target is
|
system and set `gdb_host' to XYZ, and (unless your desired target is
|
already available) also edit `gdb/configure.tgt', setting `gdb_target'
|
already available) also edit `gdb/configure.tgt', setting `gdb_target'
|
to something appropriate (for instance, XYZ).
|
to something appropriate (for instance, XYZ).
|
|
|
Finally, you'll need to specify and define GDB's host-, native-, and
|
Finally, you'll need to specify and define GDB's host-, native-, and
|
target-dependent `.h' and `.c' files used for your configuration.
|
target-dependent `.h' and `.c' files used for your configuration.
|
|
|
Configuring GDB for Release
|
Configuring GDB for Release
|
===========================
|
===========================
|
|
|
From the top level directory (containing `gdb', `bfd', `libiberty',
|
From the top level directory (containing `gdb', `bfd', `libiberty',
|
and so on):
|
and so on):
|
make -f Makefile.in gdb.tar.gz
|
make -f Makefile.in gdb.tar.gz
|
|
|
This will properly configure, clean, rebuild any files that are
|
This will properly configure, clean, rebuild any files that are
|
distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will
|
distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will
|
then make a tarfile. (If the top level directory has already been
|
then make a tarfile. (If the top level directory has already been
|
configured, you can just do `make gdb.tar.gz' instead.)
|
configured, you can just do `make gdb.tar.gz' instead.)
|
|
|
This procedure requires:
|
This procedure requires:
|
* symbolic links
|
* symbolic links
|
|
|
* `makeinfo' (texinfo2 level)
|
* `makeinfo' (texinfo2 level)
|
|
|
* TeX
|
* TeX
|
|
|
* `dvips'
|
* `dvips'
|
|
|
* `yacc' or `bison'
|
* `yacc' or `bison'
|
|
|
... and the usual slew of utilities (`sed', `tar', etc.).
|
... and the usual slew of utilities (`sed', `tar', etc.).
|
|
|
TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
|
TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
|
---------------------------------------------
|
---------------------------------------------
|
|
|
`gdb.texinfo' is currently marked up using the texinfo-2 macros,
|
`gdb.texinfo' is currently marked up using the texinfo-2 macros,
|
which are not yet a default for anything (but we have to start using
|
which are not yet a default for anything (but we have to start using
|
them sometime).
|
them sometime).
|
|
|
For making paper, the only thing this implies is the right
|
For making paper, the only thing this implies is the right
|
generation of `texinfo.tex' needs to be included in the distribution.
|
generation of `texinfo.tex' needs to be included in the distribution.
|
|
|
For making info files, however, rather than duplicating the texinfo2
|
For making info files, however, rather than duplicating the texinfo2
|
distribution, generate `gdb-all.texinfo' locally, and include the files
|
distribution, generate `gdb-all.texinfo' locally, and include the files
|
`gdb.info*' in the distribution. Note the plural; `makeinfo' will
|
`gdb.info*' in the distribution. Note the plural; `makeinfo' will
|
split the document into one overall file and five or so included files.
|
split the document into one overall file and five or so included files.
|
|
|
|
|
File: gdbint.info, Node: Testsuite, Next: Hints, Prev: Porting GDB, Up: Top
|
File: gdbint.info, Node: Testsuite, Next: Hints, Prev: Porting GDB, Up: Top
|
|
|
Testsuite
|
Testsuite
|
*********
|
*********
|
|
|
The testsuite is an important component of the GDB package. While
|
The testsuite is an important component of the GDB package. While
|
it is always worthwhile to encourage user testing, in practice this is
|
it is always worthwhile to encourage user testing, in practice this is
|
rarely sufficient; users typically use only a small subset of the
|
rarely sufficient; users typically use only a small subset of the
|
available commands, and it has proven all too common for a change to
|
available commands, and it has proven all too common for a change to
|
cause a significant regression that went unnoticed for some time.
|
cause a significant regression that went unnoticed for some time.
|
|
|
The GDB testsuite uses the DejaGNU testing framework. DejaGNU is
|
The GDB testsuite uses the DejaGNU testing framework. DejaGNU is
|
built using tcl and expect. The tests themselves are calls to various
|
built using tcl and expect. The tests themselves are calls to various
|
tcl procs; the framework runs all the procs and summarizes the passes
|
tcl procs; the framework runs all the procs and summarizes the passes
|
and fails.
|
and fails.
|
|
|
Using the Testsuite
|
Using the Testsuite
|
===================
|
===================
|
|
|
To run the testsuite, simply go to the GDB object directory (or to
|
To run the testsuite, simply go to the GDB object directory (or to
|
the testsuite's objdir) and type `make check'. This just sets up some
|
the testsuite's objdir) and type `make check'. This just sets up some
|
environment variables and invokes DejaGNU's `runtest' script. While
|
environment variables and invokes DejaGNU's `runtest' script. While
|
the testsuite is running, you'll get mentions of which test file is in
|
the testsuite is running, you'll get mentions of which test file is in
|
use, and a mention of any unexpected passes or fails. When the
|
use, and a mention of any unexpected passes or fails. When the
|
testsuite is finished, you'll get a summary that looks like this:
|
testsuite is finished, you'll get a summary that looks like this:
|
=== gdb Summary ===
|
=== gdb Summary ===
|
|
|
# of expected passes 6016
|
# of expected passes 6016
|
# of unexpected failures 58
|
# of unexpected failures 58
|
# of unexpected successes 5
|
# of unexpected successes 5
|
# of expected failures 183
|
# of expected failures 183
|
# of unresolved testcases 3
|
# of unresolved testcases 3
|
# of untested testcases 5
|
# of untested testcases 5
|
The ideal test run consists of expected passes only; however, reality
|
The ideal test run consists of expected passes only; however, reality
|
conspires to keep us from this ideal. Unexpected failures indicate
|
conspires to keep us from this ideal. Unexpected failures indicate
|
real problems, whether in GDB or in the testsuite. Expected failures
|
real problems, whether in GDB or in the testsuite. Expected failures
|
are still failures, but ones which have been decided are too hard to
|
are still failures, but ones which have been decided are too hard to
|
deal with at the time; for instance, a test case might work everywhere
|
deal with at the time; for instance, a test case might work everywhere
|
except on AIX, and there is no prospect of the AIX case being fixed in
|
except on AIX, and there is no prospect of the AIX case being fixed in
|
the near future. Expected failures should not be added lightly, since
|
the near future. Expected failures should not be added lightly, since
|
you may be masking serious bugs in GDB. Unexpected successes are
|
you may be masking serious bugs in GDB. Unexpected successes are
|
expected fails that are passing for some reason, while unresolved and
|
expected fails that are passing for some reason, while unresolved and
|
untested cases often indicate some minor catastrophe, such as the
|
untested cases often indicate some minor catastrophe, such as the
|
compiler being unable to deal with a test program.
|
compiler being unable to deal with a test program.
|
|
|
When making any significant change to GDB, you should run the
|
When making any significant change to GDB, you should run the
|
testsuite before and after the change, to confirm that there are no
|
testsuite before and after the change, to confirm that there are no
|
regressions. Note that truly complete testing would require that you
|
regressions. Note that truly complete testing would require that you
|
run the testsuite with all supported configurations and a variety of
|
run the testsuite with all supported configurations and a variety of
|
compilers; however this is more than really necessary. In many cases
|
compilers; however this is more than really necessary. In many cases
|
testing with a single configuration is sufficient. Other useful
|
testing with a single configuration is sufficient. Other useful
|
options are to test one big-endian (Sparc) and one little-endian (x86)
|
options are to test one big-endian (Sparc) and one little-endian (x86)
|
host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
|
host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
|
or a 64-bit host (Alpha).
|
or a 64-bit host (Alpha).
|
|
|
If you add new functionality to GDB, please consider adding tests
|
If you add new functionality to GDB, please consider adding tests
|
for it as well; this way future GDB hackers can detect and fix their
|
for it as well; this way future GDB hackers can detect and fix their
|
changes that break the functionality you added. Similarly, if you fix
|
changes that break the functionality you added. Similarly, if you fix
|
a bug that was not previously reported as a test failure, please add a
|
a bug that was not previously reported as a test failure, please add a
|
test case for it. Some cases are extremely difficult to test, such as
|
test case for it. Some cases are extremely difficult to test, such as
|
code that handles host OS failures or bugs in particular versions of
|
code that handles host OS failures or bugs in particular versions of
|
compilers, and it's OK not to try to write tests for all of those.
|
compilers, and it's OK not to try to write tests for all of those.
|
|
|
Testsuite Organization
|
Testsuite Organization
|
======================
|
======================
|
|
|
The testsuite is entirely contained in `gdb/testsuite'. While the
|
The testsuite is entirely contained in `gdb/testsuite'. While the
|
testsuite includes some makefiles and configury, these are very minimal,
|
testsuite includes some makefiles and configury, these are very minimal,
|
and used for little besides cleaning up, since the tests themselves
|
and used for little besides cleaning up, since the tests themselves
|
handle the compilation of the programs that GDB will run. The file
|
handle the compilation of the programs that GDB will run. The file
|
`testsuite/lib/gdb.exp' contains common utility procs useful for all
|
`testsuite/lib/gdb.exp' contains common utility procs useful for all
|
GDB tests, while the directory `testsuite/config' contains
|
GDB tests, while the directory `testsuite/config' contains
|
configuration-specific files, typically used for special-purpose
|
configuration-specific files, typically used for special-purpose
|
definitions of procs like `gdb_load' and `gdb_start'.
|
definitions of procs like `gdb_load' and `gdb_start'.
|
|
|
The tests themselves are to be found in `testsuite/gdb.*' and
|
The tests themselves are to be found in `testsuite/gdb.*' and
|
subdirectories of those. The names of the test files must always end
|
subdirectories of those. The names of the test files must always end
|
with `.exp'. DejaGNU collects the test files by wildcarding in the
|
with `.exp'. DejaGNU collects the test files by wildcarding in the
|
test directories, so both subdirectories and individual files get
|
test directories, so both subdirectories and individual files get
|
chosen and run in alphabetical order.
|
chosen and run in alphabetical order.
|
|
|
The following table lists the main types of subdirectories and what
|
The following table lists the main types of subdirectories and what
|
they are for. Since DejaGNU finds test files no matter where they are
|
they are for. Since DejaGNU finds test files no matter where they are
|
located, and since each test file sets up its own compilation and
|
located, and since each test file sets up its own compilation and
|
execution environment, this organization is simply for convenience and
|
execution environment, this organization is simply for convenience and
|
intelligibility.
|
intelligibility.
|
|
|
`gdb.base'
|
`gdb.base'
|
This is the base testsuite. The tests in it should apply to all
|
This is the base testsuite. The tests in it should apply to all
|
configurations of GDB (but generic native-only tests may live
|
configurations of GDB (but generic native-only tests may live
|
here). The test programs should be in the subset of C that is
|
here). The test programs should be in the subset of C that is
|
valid K&R, ANSI/ISO, and C++ (ifdefs are allowed if necessary, for
|
valid K&R, ANSI/ISO, and C++ (ifdefs are allowed if necessary, for
|
instance for prototypes).
|
instance for prototypes).
|
|
|
`gdb.LANG'
|
`gdb.LANG'
|
Language-specific tests for all languages besides C. Examples are
|
Language-specific tests for all languages besides C. Examples are
|
`gdb.c++' and `gdb.java'.
|
`gdb.c++' and `gdb.java'.
|
|
|
`gdb.PLATFORM'
|
`gdb.PLATFORM'
|
Non-portable tests. The tests are specific to a specific
|
Non-portable tests. The tests are specific to a specific
|
configuration (host or target), such as HP-UX or eCos. Example is
|
configuration (host or target), such as HP-UX or eCos. Example is
|
`gdb.hp', for HP-UX.
|
`gdb.hp', for HP-UX.
|
|
|
`gdb.COMPILER'
|
`gdb.COMPILER'
|
Tests specific to a particular compiler. As of this writing (June
|
Tests specific to a particular compiler. As of this writing (June
|
1999), there aren't currently any groups of tests in this category
|
1999), there aren't currently any groups of tests in this category
|
that couldn't just as sensibly be made platform-specific, but one
|
that couldn't just as sensibly be made platform-specific, but one
|
could imagine a gdb.gcc, for tests of GDB's handling of GCC
|
could imagine a gdb.gcc, for tests of GDB's handling of GCC
|
extensions.
|
extensions.
|
|
|
`gdb.SUBSYSTEM'
|
`gdb.SUBSYSTEM'
|
Tests that exercise a specific GDB subsystem in more depth. For
|
Tests that exercise a specific GDB subsystem in more depth. For
|
instance, `gdb.disasm' exercises various disassemblers, while
|
instance, `gdb.disasm' exercises various disassemblers, while
|
`gdb.stabs' tests pathways through the stabs symbol reader.
|
`gdb.stabs' tests pathways through the stabs symbol reader.
|
|
|
Writing Tests
|
Writing Tests
|
=============
|
=============
|
|
|
In many areas, the GDB tests are already quite comprehensive; you
|
In many areas, the GDB tests are already quite comprehensive; you
|
should be able to copy existing tests to handle new cases.
|
should be able to copy existing tests to handle new cases.
|
|
|
You should try to use `gdb_test' whenever possible, since it
|
You should try to use `gdb_test' whenever possible, since it
|
includes cases to handle all the unexpected errors that might happen.
|
includes cases to handle all the unexpected errors that might happen.
|
However, it doesn't cost anything to add new test procedures; for
|
However, it doesn't cost anything to add new test procedures; for
|
instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
|
instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
|
`gdb_test' multiple times.
|
`gdb_test' multiple times.
|
|
|
Only use `send_gdb' and `gdb_expect' when absolutely necessary, such
|
Only use `send_gdb' and `gdb_expect' when absolutely necessary, such
|
as when GDB has several valid responses to a command.
|
as when GDB has several valid responses to a command.
|
|
|
The source language programs do _not_ need to be in a consistent
|
The source language programs do _not_ need to be in a consistent
|
style. Since GDB is used to debug programs written in many different
|
style. Since GDB is used to debug programs written in many different
|
styles, it's worth having a mix of styles in the testsuite; for
|
styles, it's worth having a mix of styles in the testsuite; for
|
instance, some GDB bugs involving the display of source lines would
|
instance, some GDB bugs involving the display of source lines would
|
never manifest themselves if the programs used GNU coding style
|
never manifest themselves if the programs used GNU coding style
|
uniformly.
|
uniformly.
|
|
|
|
|
File: gdbint.info, Node: Hints, Prev: Testsuite, Up: Top
|
File: gdbint.info, Node: Hints, Prev: Testsuite, Up: Top
|
|
|
Hints
|
Hints
|
*****
|
*****
|
|
|
Check the `README' file, it often has useful information that does
|
Check the `README' file, it often has useful information that does
|
not appear anywhere else in the directory.
|
not appear anywhere else in the directory.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Getting Started:: Getting started working on GDB
|
* Getting Started:: Getting started working on GDB
|
* Debugging GDB:: Debugging GDB with itself
|
* Debugging GDB:: Debugging GDB with itself
|
|
|
|
|
File: gdbint.info, Node: Getting Started, Up: Hints
|
File: gdbint.info, Node: Getting Started, Up: Hints
|
|
|
Getting Started
|
Getting Started
|
===============
|
===============
|
|
|
GDB is a large and complicated program, and if you first starting to
|
GDB is a large and complicated program, and if you first starting to
|
work on it, it can be hard to know where to start. Fortunately, if you
|
work on it, it can be hard to know where to start. Fortunately, if you
|
know how to go about it, there are ways to figure out what is going on.
|
know how to go about it, there are ways to figure out what is going on.
|
|
|
This manual, the GDB Internals manual, has information which applies
|
This manual, the GDB Internals manual, has information which applies
|
generally to many parts of GDB.
|
generally to many parts of GDB.
|
|
|
Information about particular functions or data structures are
|
Information about particular functions or data structures are
|
located in comments with those functions or data structures. If you
|
located in comments with those functions or data structures. If you
|
run across a function or a global variable which does not have a
|
run across a function or a global variable which does not have a
|
comment correctly explaining what is does, this can be thought of as a
|
comment correctly explaining what is does, this can be thought of as a
|
bug in GDB; feel free to submit a bug report, with a suggested comment
|
bug in GDB; feel free to submit a bug report, with a suggested comment
|
if you can figure out what the comment should say. If you find a
|
if you can figure out what the comment should say. If you find a
|
comment which is actually wrong, be especially sure to report that.
|
comment which is actually wrong, be especially sure to report that.
|
|
|
Comments explaining the function of macros defined in host, target,
|
Comments explaining the function of macros defined in host, target,
|
or native dependent files can be in several places. Sometimes they are
|
or native dependent files can be in several places. Sometimes they are
|
repeated every place the macro is defined. Sometimes they are where the
|
repeated every place the macro is defined. Sometimes they are where the
|
macro is used. Sometimes there is a header file which supplies a
|
macro is used. Sometimes there is a header file which supplies a
|
default definition of the macro, and the comment is there. This manual
|
default definition of the macro, and the comment is there. This manual
|
also documents all the available macros.
|
also documents all the available macros.
|
|
|
Start with the header files. Once you have some idea of how GDB's
|
Start with the header files. Once you have some idea of how GDB's
|
internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
|
internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
|
will find it much easier to understand the code which uses and creates
|
will find it much easier to understand the code which uses and creates
|
those symbol tables.
|
those symbol tables.
|
|
|
You may wish to process the information you are getting somehow, to
|
You may wish to process the information you are getting somehow, to
|
enhance your understanding of it. Summarize it, translate it to another
|
enhance your understanding of it. Summarize it, translate it to another
|
language, add some (perhaps trivial or non-useful) feature to GDB, use
|
language, add some (perhaps trivial or non-useful) feature to GDB, use
|
the code to predict what a test case would do and write the test case
|
the code to predict what a test case would do and write the test case
|
and verify your prediction, etc. If you are reading code and your eyes
|
and verify your prediction, etc. If you are reading code and your eyes
|
are starting to glaze over, this is a sign you need to use a more active
|
are starting to glaze over, this is a sign you need to use a more active
|
approach.
|
approach.
|
|
|
Once you have a part of GDB to start with, you can find more
|
Once you have a part of GDB to start with, you can find more
|
specifically the part you are looking for by stepping through each
|
specifically the part you are looking for by stepping through each
|
function with the `next' command. Do not use `step' or you will
|
function with the `next' command. Do not use `step' or you will
|
quickly get distracted; when the function you are stepping through
|
quickly get distracted; when the function you are stepping through
|
calls another function try only to get a big-picture understanding
|
calls another function try only to get a big-picture understanding
|
(perhaps using the comment at the beginning of the function being
|
(perhaps using the comment at the beginning of the function being
|
called) of what it does. This way you can identify which of the
|
called) of what it does. This way you can identify which of the
|
functions being called by the function you are stepping through is the
|
functions being called by the function you are stepping through is the
|
one which you are interested in. You may need to examine the data
|
one which you are interested in. You may need to examine the data
|
structures generated at each stage, with reference to the comments in
|
structures generated at each stage, with reference to the comments in
|
the header files explaining what the data structures are supposed to
|
the header files explaining what the data structures are supposed to
|
look like.
|
look like.
|
|
|
Of course, this same technique can be used if you are just reading
|
Of course, this same technique can be used if you are just reading
|
the code, rather than actually stepping through it. The same general
|
the code, rather than actually stepping through it. The same general
|
principle applies--when the code you are looking at calls something
|
principle applies--when the code you are looking at calls something
|
else, just try to understand generally what the code being called does,
|
else, just try to understand generally what the code being called does,
|
rather than worrying about all its details.
|
rather than worrying about all its details.
|
|
|
A good place to start when tracking down some particular area is
|
A good place to start when tracking down some particular area is
|
with a command which invokes that feature. Suppose you want to know how
|
with a command which invokes that feature. Suppose you want to know how
|
single-stepping works. As a GDB user, you know that the `step' command
|
single-stepping works. As a GDB user, you know that the `step' command
|
invokes single-stepping. The command is invoked via command tables
|
invokes single-stepping. The command is invoked via command tables
|
(see `command.h'); by convention the function which actually performs
|
(see `command.h'); by convention the function which actually performs
|
the command is formed by taking the name of the command and adding
|
the command is formed by taking the name of the command and adding
|
`_command', or in the case of an `info' subcommand, `_info'. For
|
`_command', or in the case of an `info' subcommand, `_info'. For
|
example, the `step' command invokes the `step_command' function and the
|
example, the `step' command invokes the `step_command' function and the
|
`info display' command invokes `display_info'. When this convention is
|
`info display' command invokes `display_info'. When this convention is
|
not followed, you might have to use `grep' or `M-x tags-search' in
|
not followed, you might have to use `grep' or `M-x tags-search' in
|
emacs, or run GDB on itself and set a breakpoint in `execute_command'.
|
emacs, or run GDB on itself and set a breakpoint in `execute_command'.
|
|
|
If all of the above fail, it may be appropriate to ask for
|
If all of the above fail, it may be appropriate to ask for
|
information on `bug-gdb'. But _never_ post a generic question like "I
|
information on `bug-gdb'. But _never_ post a generic question like "I
|
was wondering if anyone could give me some tips about understanding
|
was wondering if anyone could give me some tips about understanding
|
GDB"--if we had some magic secret we would put it in this manual.
|
GDB"--if we had some magic secret we would put it in this manual.
|
Suggestions for improving the manual are always welcome, of course.
|
Suggestions for improving the manual are always welcome, of course.
|
|
|
|
|
File: gdbint.info, Node: Debugging GDB, Up: Hints
|
File: gdbint.info, Node: Debugging GDB, Up: Hints
|
|
|
Debugging GDB with itself
|
Debugging GDB with itself
|
=========================
|
=========================
|
|
|
If GDB is limping on your machine, this is the preferred way to get
|
If GDB is limping on your machine, this is the preferred way to get
|
it fully functional. Be warned that in some ancient Unix systems, like
|
it fully functional. Be warned that in some ancient Unix systems, like
|
Ultrix 4.2, a program can't be running in one process while it is being
|
Ultrix 4.2, a program can't be running in one process while it is being
|
debugged in another. Rather than typing the command `./gdb ./gdb',
|
debugged in another. Rather than typing the command `./gdb ./gdb',
|
which works on Suns and such, you can copy `gdb' to `gdb2' and then
|
which works on Suns and such, you can copy `gdb' to `gdb2' and then
|
type `./gdb ./gdb2'.
|
type `./gdb ./gdb2'.
|
|
|
When you run GDB in the GDB source directory, it will read a
|
When you run GDB in the GDB source directory, it will read a
|
`.gdbinit' file that sets up some simple things to make debugging gdb
|
`.gdbinit' file that sets up some simple things to make debugging gdb
|
easier. The `info' command, when executed without a subcommand in a
|
easier. The `info' command, when executed without a subcommand in a
|
GDB being debugged by gdb, will pop you back up to the top level gdb.
|
GDB being debugged by gdb, will pop you back up to the top level gdb.
|
See `.gdbinit' for details.
|
See `.gdbinit' for details.
|
|
|
If you use emacs, you will probably want to do a `make TAGS' after
|
If you use emacs, you will probably want to do a `make TAGS' after
|
you configure your distribution; this will put the machine dependent
|
you configure your distribution; this will put the machine dependent
|
routines for your local machine where they will be accessed first by
|
routines for your local machine where they will be accessed first by
|
`M-.'
|
`M-.'
|
|
|
Also, make sure that you've either compiled GDB with your local cc,
|
Also, make sure that you've either compiled GDB with your local cc,
|
or have run `fixincludes' if you are compiling with gcc.
|
or have run `fixincludes' if you are compiling with gcc.
|
|
|
Submitting Patches
|
Submitting Patches
|
==================
|
==================
|
|
|
Thanks for thinking of offering your changes back to the community of
|
Thanks for thinking of offering your changes back to the community of
|
GDB users. In general we like to get well designed enhancements.
|
GDB users. In general we like to get well designed enhancements.
|
Thanks also for checking in advance about the best way to transfer the
|
Thanks also for checking in advance about the best way to transfer the
|
changes.
|
changes.
|
|
|
The GDB maintainers will only install "cleanly designed" patches.
|
The GDB maintainers will only install "cleanly designed" patches.
|
This manual summarizes what we believe to be clean design for GDB.
|
This manual summarizes what we believe to be clean design for GDB.
|
|
|
If the maintainers don't have time to put the patch in when it
|
If the maintainers don't have time to put the patch in when it
|
arrives, or if there is any question about a patch, it goes into a
|
arrives, or if there is any question about a patch, it goes into a
|
large queue with everyone else's patches and bug reports.
|
large queue with everyone else's patches and bug reports.
|
|
|
The legal issue is that to incorporate substantial changes requires a
|
The legal issue is that to incorporate substantial changes requires a
|
copyright assignment from you and/or your employer, granting ownership
|
copyright assignment from you and/or your employer, granting ownership
|
of the changes to the Free Software Foundation. You can get the
|
of the changes to the Free Software Foundation. You can get the
|
standard documents for doing this by sending mail to `gnu@gnu.org' and
|
standard documents for doing this by sending mail to `gnu@gnu.org' and
|
asking for it. We recommend that people write in "All programs owned
|
asking for it. We recommend that people write in "All programs owned
|
by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
|
by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
|
in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
|
in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
|
contributed with only one piece of legalese pushed through the
|
contributed with only one piece of legalese pushed through the
|
bureacracy and filed with the FSF. We can't start merging changes until
|
bureacracy and filed with the FSF. We can't start merging changes until
|
this paperwork is received by the FSF (their rules, which we follow
|
this paperwork is received by the FSF (their rules, which we follow
|
since we maintain it for them).
|
since we maintain it for them).
|
|
|
Technically, the easiest way to receive changes is to receive each
|
Technically, the easiest way to receive changes is to receive each
|
feature as a small context diff or unidiff, suitable for "patch". Each
|
feature as a small context diff or unidiff, suitable for "patch". Each
|
message sent to me should include the changes to C code and header files
|
message sent to me should include the changes to C code and header files
|
for a single feature, plus ChangeLog entries for each directory where
|
for a single feature, plus ChangeLog entries for each directory where
|
files were modified, and diffs for any changes needed to the manuals
|
files were modified, and diffs for any changes needed to the manuals
|
(gdb/doc/gdb.texinfo or gdb/doc/gdbint.texinfo). If there are a lot of
|
(gdb/doc/gdb.texinfo or gdb/doc/gdbint.texinfo). If there are a lot of
|
changes for a single feature, they can be split down into multiple
|
changes for a single feature, they can be split down into multiple
|
messages.
|
messages.
|
|
|
In this way, if we read and like the feature, we can add it to the
|
In this way, if we read and like the feature, we can add it to the
|
sources with a single patch command, do some testing, and check it in.
|
sources with a single patch command, do some testing, and check it in.
|
If you leave out the ChangeLog, we have to write one. If you leave out
|
If you leave out the ChangeLog, we have to write one. If you leave out
|
the doc, we have to puzzle out what needs documenting. Etc.
|
the doc, we have to puzzle out what needs documenting. Etc.
|
|
|
The reason to send each change in a separate message is that we will
|
The reason to send each change in a separate message is that we will
|
not install some of the changes. They'll be returned to you with
|
not install some of the changes. They'll be returned to you with
|
questions or comments. If we're doing our job correctly, the message
|
questions or comments. If we're doing our job correctly, the message
|
back to you will say what you have to fix in order to make the change
|
back to you will say what you have to fix in order to make the change
|
acceptable. The reason to have separate messages for separate features
|
acceptable. The reason to have separate messages for separate features
|
is so that the acceptable changes can be installed while one or more
|
is so that the acceptable changes can be installed while one or more
|
changes are being reworked. If multiple features are sent in a single
|
changes are being reworked. If multiple features are sent in a single
|
message, we tend to not put in the effort to sort out the acceptable
|
message, we tend to not put in the effort to sort out the acceptable
|
changes from the unacceptable, so none of the features get installed
|
changes from the unacceptable, so none of the features get installed
|
until all are acceptable.
|
until all are acceptable.
|
|
|
If this sounds painful or authoritarian, well, it is. But we get a
|
If this sounds painful or authoritarian, well, it is. But we get a
|
lot of bug reports and a lot of patches, and many of them don't get
|
lot of bug reports and a lot of patches, and many of them don't get
|
installed because we don't have the time to finish the job that the bug
|
installed because we don't have the time to finish the job that the bug
|
reporter or the contributor could have done. Patches that arrive
|
reporter or the contributor could have done. Patches that arrive
|
complete, working, and well designed, tend to get installed on the day
|
complete, working, and well designed, tend to get installed on the day
|
they arrive. The others go into a queue and get installed as time
|
they arrive. The others go into a queue and get installed as time
|
permits, which, since the maintainers have many demands to meet, may not
|
permits, which, since the maintainers have many demands to meet, may not
|
be for quite some time.
|
be for quite some time.
|
|
|
Please send patches directly to the GDB maintainers at
|
Please send patches directly to the GDB maintainers at
|
`gdb-patches@sourceware.cygnus.com'.
|
`gdb-patches@sourceware.cygnus.com'.
|
|
|
Obsolete Conditionals
|
Obsolete Conditionals
|
=====================
|
=====================
|
|
|
Fragments of old code in GDB sometimes reference or set the following
|
Fragments of old code in GDB sometimes reference or set the following
|
configuration macros. They should not be used by new code, and old uses
|
configuration macros. They should not be used by new code, and old uses
|
should be removed as those parts of the debugger are otherwise touched.
|
should be removed as those parts of the debugger are otherwise touched.
|
|
|
`STACK_END_ADDR'
|
`STACK_END_ADDR'
|
This macro used to define where the end of the stack appeared, for
|
This macro used to define where the end of the stack appeared, for
|
use in interpreting core file formats that don't record this
|
use in interpreting core file formats that don't record this
|
address in the core file itself. This information is now
|
address in the core file itself. This information is now
|
configured in BFD, and GDB gets the info portably from there. The
|
configured in BFD, and GDB gets the info portably from there. The
|
values in GDB's configuration files should be moved into BFD
|
values in GDB's configuration files should be moved into BFD
|
configuration files (if needed there), and deleted from all of
|
configuration files (if needed there), and deleted from all of
|
GDB's config files.
|
GDB's config files.
|
|
|
Any `FOO-xdep.c' file that references STACK_END_ADDR is so old
|
Any `FOO-xdep.c' file that references STACK_END_ADDR is so old
|
that it has never been converted to use BFD. Now that's old!
|
that it has never been converted to use BFD. Now that's old!
|
|
|
`PYRAMID_CONTROL_FRAME_DEBUGGING'
|
`PYRAMID_CONTROL_FRAME_DEBUGGING'
|
pyr-xdep.c
|
pyr-xdep.c
|
|
|
`PYRAMID_CORE'
|
`PYRAMID_CORE'
|
pyr-xdep.c
|
pyr-xdep.c
|
|
|
`PYRAMID_PTRACE'
|
`PYRAMID_PTRACE'
|
pyr-xdep.c
|
pyr-xdep.c
|
|
|
`REG_STACK_SEGMENT'
|
`REG_STACK_SEGMENT'
|
exec.c
|
exec.c
|
|
|
|
|
|
|