Initial revision

1 files changed, 242 insertions, 0 deletions

diff --git a/gdb/gdb-int.texinfo b/gdb/gdb-int.texinfo
new file mode 100755
index 0000000000..cc1b1880e2
--- /dev/null
+++ b/gdb/gdb-int.texinfo
@@ -0,0 +1,242 @@
+\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
+* Host versus Targt::		What features are in which files
+
+@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, Host versus Target, 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.
+
+@node Host versus Target, , README, Top
+@chapter What is considered ``host-dependent'' versus ``target-dependent''?
+
+The xconfig/*, xm-*.h and *-xdep.c files are for host support.  The
+question is, what features or aspects of a debugging or cross-debugging
+environment are considered to be ``host'' support.
+
+Defines and include files needed to build on the host are host support.
+Examples are tty support, system defined types, host byte order, host
+float format.
+
+Unix child process support is considered an aspect of the host.  Since
+when you fork on the host you are still on the host, the various macros
+needed for finding the registers in the upage, running ptrace, and such
+are all in the host-dependent files.
+
+This is still somewhat of a grey area; I (John Gilmore) didn't do the
+xm- and tm- split for gdb (it was done by Jim Kingdon) so I have had to
+figure out the grounds on which it was split, and make my own choices
+as I evolve it.  I have moved many things out of the xdep files
+actually, partly as a result of BFD and partly by removing duplicated
+code.
+
+@contents
+@bye
+