219 lines
8.0 KiB
Plaintext
219 lines
8.0 KiB
Plaintext
\input texinfo
|
|
@setfilename gdb-internals
|
|
@ifinfo
|
|
This file documents the internals of the GNU debugger GDB.
|
|
|
|
Copyright (C) 1990, 1991 Free Software Foundation, Inc.
|
|
Contributed by Cygnus Support. Written by John Gilmore.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through Tex and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
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
|
|
regarded as a program in the language TeX).
|
|
@end ifinfo
|
|
|
|
@setchapternewpage odd
|
|
@settitle GDB Internals
|
|
@titlepage
|
|
@title{Working in GDB}
|
|
@subtitle{A guide to the internals of the GNU debugger}
|
|
@author John Gilmore
|
|
@author Cygnus Support
|
|
@page
|
|
@tex
|
|
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
|
|
\xdef\manvers{\$Revision$} % For use in headers, footers too
|
|
{\parskip=0pt
|
|
\hfill Cygnus Support\par
|
|
\hfill \manvers\par
|
|
\hfill \TeX{}info \texinfoversion\par
|
|
}
|
|
@end tex
|
|
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1990, 1991 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
@end titlepage
|
|
|
|
@node Top, Cleanups, (dir), (dir)
|
|
|
|
@menu
|
|
* Cleanups:: Cleanups
|
|
* Wrapping:: Wrapping output lines
|
|
* Releases:: Configuring GDB for release
|
|
* README:: The README file
|
|
* New Architectures:: Defining a new host or target architecture
|
|
|
|
@end menu
|
|
|
|
@node Cleanups, Wrapping, Top, Top
|
|
@chapter Cleanups
|
|
|
|
Cleanups are a structured way to deal with things that need to be 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 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, or
|
|
when your code decides it's time to do cleanups.
|
|
|
|
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.
|
|
|
|
Syntax:
|
|
|
|
@table @code
|
|
@item old_chain = make_cleanup (function, arg);
|
|
This makes a cleanup which will cause FUNCTION to be called with ARG
|
|
(a char *) later. The result, OLD_CHAIN, is a handle that can be
|
|
passed to do_cleanups or discard_cleanups later. Unless you are
|
|
going to call do_cleanups or discard_cleanups yourself,
|
|
you can ignore the result from make_cleanup.
|
|
|
|
|
|
@item do_cleanups (old_chain);
|
|
Performs all cleanups done since make_cleanup returned OLD_CHAIN.
|
|
E.g.: make_cleanup (a, 0); old = make_cleanup (b, 0); do_cleanups (old);
|
|
will call b() but will not call a(). The cleanup that calls a() will remain
|
|
in the cleanup chain, and will be done later unless otherwise discarded.
|
|
|
|
@item discard_cleanups (old_chain);
|
|
Same as do_cleanups except that it just removes the cleanups from the
|
|
chain and does not call the specified functions.
|
|
|
|
@end table
|
|
|
|
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that 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
|
|
interruption must be on the cleanup chain before you call these functions,
|
|
since they might never return to your code (they @samp{longjmp} instead).
|
|
|
|
|
|
@node Wrapping, Releases, Cleanups, Top
|
|
@chapter Wrapping output lines
|
|
|
|
Output that goes through printf_filtered or fputs_filtered or
|
|
fputs_demangled needs only to have calls to wrap_here() added
|
|
in places that would be good breaking points. The utility routines
|
|
will take care of actually wrapping if the line width is exceeded.
|
|
|
|
The argument to wrap_here() is an indentation string which is printed
|
|
ONLY if the line breaks there. This argument is saved away and used
|
|
later. It must remain valid until the next call to wrap_here() or
|
|
until a newline has been printed through the *_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 space.
|
|
If you call it before printing a space, make sure that your indentation
|
|
properly accounts for the leading space that will print if the line wraps
|
|
there.
|
|
|
|
Any function or set of functions that produce filtered output must finish
|
|
by printing a newline, to flush the wrap buffer, before switching to
|
|
unfiltered ("printf") output. Symbol reading routines that print
|
|
warnings are a good example.
|
|
|
|
|
|
@node Releases, README, Wrapping, Top
|
|
@chapter Configuring GDB for release
|
|
|
|
|
|
GDB should be released after doing @samp{config.gdb none} in the top level
|
|
directory. This will leave a makefile there, but no tm- or xm- files.
|
|
The makefile is needed, for example, for @samp{make gdb.tar.Z}@dots{} If you
|
|
have tm- or xm-files in the main source directory, C's include rules
|
|
cause them to be used in preference to tm- and xm-files in the
|
|
subdirectories where the user will actually configure and build the
|
|
binaries.
|
|
|
|
@samp{config.gdb none} is also a good way to rebuild the top level Makefile
|
|
after changing Makefile.dist, alldeps.mak, etc.
|
|
|
|
|
|
|
|
@node README, New Architectures, Releases, Top
|
|
@chapter The README file
|
|
|
|
|
|
Check the README file, it often has useful information that does not
|
|
appear anywhere else in the directory.
|
|
|
|
|
|
|
|
@node New Architectures, , README, Top
|
|
@chapter Defining a new host or target architecture
|
|
|
|
|
|
When building support for a new host and/or target, this will help you
|
|
organize where to put the various parts. @var{ARCH} stands for the
|
|
architecture involved.
|
|
|
|
Object files needed when the host system is an @var{ARCH} are listed in
|
|
the file @file{xconfig/@var{ARCH}}, in the Makefile macro @samp{XDEPFILES
|
|
= }@dots{}. You can also define XXXXXX in there.
|
|
|
|
There are some ``generic'' versions of routines that can be used by
|
|
various host systems. If these routines work for the @var{ARCH} host,
|
|
you can just include the generic file's name (with .o, not .c) in
|
|
@code{XDEPFILES}. Otherwise, you will need to write routines that
|
|
perform the same functions as the generic file, put them into
|
|
@code{@var{ARCH}-xdep.c}, and put @code{@var{ARCH}-xdep.o} into
|
|
@code{XDEPFILES}. These generic host support files include:
|
|
|
|
@example
|
|
coredep.c, coredep.o
|
|
@end example
|
|
|
|
@table @code
|
|
@item fetch_core_registers()
|
|
Support for reading registers out of a core file. This routine calls
|
|
@code{register_addr(}), see below.
|
|
|
|
@item register_addr()
|
|
If your @code{xm-@var{ARCH}.h} file defines the macro @code{REGISTER_U_ADDR(reg)} to be the
|
|
offset within the @samp{user} struct of a register (represented as a GDB
|
|
register number), @file{coredep.c} will define the @code{register_addr()} function
|
|
and use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
|
|
you are using the standard @code{fetch_core_registers}, you
|
|
will need to define your own version of @code{register_addr}, put it into
|
|
your @code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is in the @code{XDEPFILES} list.
|
|
If you have your own @code{fetch_core_registers}, you only need to define
|
|
@code{register_addr} if your @code{fetch_core_registers} calls it. Many custom
|
|
@code{fetch_core_registers} implementations simply locate the registers
|
|
themselves.
|
|
@end table
|
|
|
|
Files needed when the target system is an @var{ARCH} are listed in the file
|
|
@file{tconfig/@var{ARCH}}, in the @code{Makefile} macro @samp{TDEPFILES = }@dots{}. You can also
|
|
define XXXXXX in there.
|
|
|
|
Similar generic support files for target systems are:
|
|
|
|
@example
|
|
exec.c, exec.o:
|
|
@end example
|
|
|
|
This file defines functions for accessing files that are executable
|
|
on the target system. These functions open and examine an exec file,
|
|
extract data from one, write data to one, print information about one,
|
|
etc. Now that executable files are handled with BFD, every architecture
|
|
should be able to use the generic exec.c rather than its own custom code.
|
|
|
|
@contents
|
|
@bye
|
|
|