Add texinfo wrappers
This commit is contained in:
Roland Pesch
parent
0245d1cd26
commit
ca714d0352
|
|
@ -1,10 +1,67 @@
|
|||
GDB Internals documentation
|
||||
Copyright 1990, 1991 Free Software Foundation, Inc.
|
||||
\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.
|
||||
|
||||
This needs to be wrapped in texinfo stuff...
|
||||
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.
|
||||
|
||||
Cleanups
|
||||
@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
|
||||
|
|
@ -18,36 +75,36 @@ what they say. This is only done if you ask that it be done.
|
|||
|
||||
Syntax:
|
||||
|
||||
old_chain = make_cleanup (function, arg);
|
||||
|
||||
@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.
|
||||
|
||||
do_cleanups (old_chain);
|
||||
|
||||
@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.
|
||||
|
||||
discard_cleanups (old_chain);
|
||||
|
||||
@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. fputs_filtered() or error(), specify that they
|
||||
"should not be called when cleanups are not in place". This means
|
||||
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 "longjmp" instead).
|
||||
since they might never return to your code (they @samp{longjmp} instead).
|
||||
|
||||
|
||||
|
||||
Wrapping output lines
|
||||
@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
|
||||
|
|
@ -71,25 +128,25 @@ unfiltered ("printf") output. Symbol reading routines that print
|
|||
warnings are a good example.
|
||||
|
||||
|
||||
|
||||
Configuring GDB for release
|
||||
@node Releases, README, Wrapping, Top
|
||||
@chapter Configuring GDB for release
|
||||
|
||||
|
||||
GDB should be released after doing "config.gdb none" in the top level
|
||||
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 "make gdb.tar.Z"... If you
|
||||
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.
|
||||
|
||||
"config.gdb none" is also a good way to rebuild the top level Makefile
|
||||
@samp{config.gdb none} is also a good way to rebuild the top level Makefile
|
||||
after changing Makefile.dist, alldeps.mak, etc.
|
||||
|
||||
|
||||
|
||||
|
||||
The README file
|
||||
@node README, New Architectures, Releases, Top
|
||||
@chapter The README file
|
||||
|
||||
|
||||
Check the README file, it often has useful information that does not
|
||||
|
|
@ -97,55 +154,65 @@ appear anywhere else in the directory.
|
|||
|
||||
|
||||
|
||||
|
||||
Defining a new host or target architecture
|
||||
@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. ARCH stands for the
|
||||
organize where to put the various parts. @var{ARCH} stands for the
|
||||
architecture involved.
|
||||
|
||||
Object files needed when the host system is an ARCH are listed in the file
|
||||
xconfig/ARCH, in the Makefile macro "XDEPFILES = ...". You can also
|
||||
define XXXXXX in there.
|
||||
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 ARCH host, you
|
||||
can just include the generic file's name (with .o, not .c) in
|
||||
XDEPFILES. Otherwise, you will need to write routines that perform the
|
||||
same functions as the generic file, put them into ARCH-xdep.c, and put
|
||||
ARCH-xdep.o into XDEPFILES. These generic host support files include:
|
||||
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
|
||||
|
||||
fetch_core_registers():
|
||||
@table @code
|
||||
@item fetch_core_registers()
|
||||
Support for reading registers out of a core file. This routine calls
|
||||
register_addr(), see below.
|
||||
@code{register_addr(}), see below.
|
||||
|
||||
register_addr():
|
||||
If your xm-ARCH.h file defines the macro REGISTER_U_ADDR(reg) to be the
|
||||
offset within the "user" struct of a register (represented as a GDB
|
||||
register number), coredep.c will define the register_addr() function
|
||||
and use the macro in it. If you do not define REGISTER_U_ADDR, but
|
||||
you are using the standard fetch_core_registers, you
|
||||
will need to define your own version of register_addr, put it into
|
||||
your ARCH-xdep.c file, and be sure ARCH-xdep.o is in the XDEPFILES list.
|
||||
If you have your own fetch_core_registers, you only need to define
|
||||
register_addr if your fetch_core_registers calls it. Many custom
|
||||
fetch_core_registers implementations simply locate the registers
|
||||
@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 ARCH are listed in the file
|
||||
tconfig/ARCH, in the Makefile macro "TDEPFILES = ...". You can also
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue