Initial creation of sourceware repositorygdb-4_18-branchpoint

1 files changed, 2711 insertions, 0 deletions

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
new file mode 100644
index 00000000000..99f081dcda4
--- /dev/null
+++ b/gdb/doc/gdbint.texinfo
@@ -0,0 +1,2711 @@
+\input texinfo
+@setfilename gdbint.info
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Gdb-Internals: (gdbint).	The GNU debugger's internals.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This file documents the internals of the GNU debugger GDB.
+
+Copyright 1990-1999 Free Software Foundation, Inc.
+Contributed by Cygnus Solutions.  Written by John Gilmore.
+Second Edition by Stan Shebs.
+
+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 off
+@settitle GDB Internals
+
+@titlepage
+@title{GDB Internals}
+@subtitle{A guide to the internals of the GNU debugger}
+@author John Gilmore
+@author Cygnus Solutions
+@author Second Edition:
+@author Stan Shebs
+@author Cygnus Solutions
+@page
+@tex
+\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$}  % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Solutions\par
+\hfill \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+}
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1990-1999 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
+@c Perhaps this should be the title of the document (but only for info,
+@c not for TeX).  Existing GNU manuals seem inconsistent on this point.
+@top Scope of this Document
+
+This document documents the internals of the GNU debugger, GDB.  It
+includes description of GDB's key algorithms and operations, as well
+as the mechanisms that adapt GDB to specific hosts and targets.
+
+@menu
+* Requirements::
+* Overall Structure::
+* Algorithms::
+* User Interface::
+* Symbol Handling::
+* Language Support::
+* Host Definition::
+* Target Architecture Definition::
+* Target Vector Definition::
+* Native Debugging::
+* Support Libraries::
+* Coding::
+* Porting GDB::
+* Hints::
+@end menu
+
+@node Requirements
+
+@chapter Requirements
+
+Before diving into the internals, you should understand the formal
+requirements and other expectations for GDB.  Although some of these may
+seem obvious, there have been proposals for GDB that have run counter to
+these requirements.
+
+First of all, GDB is a debugger.  It's not designed to be a front panel
+for embedded systems.  It's not a text editor.  It's not a shell.  It's
+not a programming environment.
+
+GDB is an interactive tool.  Although a batch mode is available, GDB's
+primary role is to interact with a human programmer.
+
+GDB should be responsive to the user.  A programmer hot on the trail of
+a nasty bug, and operating under a looming deadline, is going to be very
+impatient of everything, including the response time to debugger
+commands.
+
+GDB should be relatively permissive, such as for expressions.  While the
+compiler should be picky (or have the option to be made picky), since
+source code lives for a long time usually, the programmer doing
+debugging shouldn't be spending time figuring out to mollify the
+debugger.
+
+GDB will be called upon to deal with really large programs.  Executable
+sizes of 50 to 100 megabytes occur regularly, and we've heard reports of
+programs approaching 1 gigabyte in size.
+
+GDB should be able to run everywhere.  No other debugger is available
+for even half as many configurations as GDB supports.
+
+
+@node Overall Structure
+
+@chapter Overall Structure
+
+GDB consists of three major subsystems: user interface, symbol handling
+(the ``symbol side''), and target system handling (the ``target side'').
+
+Ther user interface consists of several actual interfaces, plus
+supporting code.
+
+The symbol side consists of object file readers, debugging info
+interpreters, symbol table management, source language expression
+parsing, type and value printing.
+
+The target side consists of execution control, stack frame analysis, and
+physical target manipulation.
+
+The target side/symbol side division is not formal, and there are a
+number of exceptions.  For instance, core file support involves symbolic
+elements (the basic core file reader is in BFD) and target elements (it
+supplies the contents of memory and the values of registers).  Instead,
+this division is useful for understanding how the minor subsystems
+should fit together.
+
+@section The Symbol Side
+
+The symbolic side of GDB can be thought of as ``everything you can do in
+GDB without having a live program running''.  For instance, you can look
+at the types of variables, and evaluate many kinds of expressions.
+
+@section The Target Side
+
+The target side of GDB is the ``bits and bytes manipulator''.  Although
+it may make reference to symbolic info here and there, most of the
+target side will run with only a stripped executable available -- or
+even no executable at all, in remote debugging cases.
+
+Operations such as disassembly, stack frame crawls, and register
+display, are able to work with no symbolic info at all.  In some cases,
+such as disassembly, GDB will use symbolic info to present addresses
+relative to symbols rather than as raw numbers, but it will work either
+way.
+
+@section Configurations
+
+@dfn{Host} refers to attributes of the system where GDB runs.
+@dfn{Target} refers to the system where the program being debugged
+executes.  In most cases they are the same machine, in which case a
+third type of @dfn{Native} attributes come into play.
+
+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.
+
+Defines and information needed to handle the target format are target
+dependent.  Examples are the stack frame format, instruction set,
+breakpoint instruction, registers, and how to set up and tear down the stack
+to call a function.
+
+Information that is only needed when the host and target are the same,
+is native dependent.  One example is Unix child process support; if the
+host and target are not the same, doing a fork to start the target
+process is a bad idea.  The various macros needed for finding the
+registers in the @code{upage}, running @code{ptrace}, and such are all
+in the native-dependent files.
+
+Another example of native-dependent code is support for features that
+are really part of the target environment, but which require
+@code{#include} files that are only available on the host system.  Core
+file handling and @code{setjmp} handling are two common cases.
+
+When you want to make GDB work ``native'' on a particular machine, you
+have to include all three kinds of information.
+
+
+@node Algorithms
+
+@chapter Algorithms
+
+GDB uses a number of debugging-specific algorithms.  They are often not
+very complicated, but get lost in the thicket of special cases and
+real-world issues.  This chapter describes the basic algorithms and
+mentions some of the specific target definitions that they use.
+
+@section Frames
+
+A frame is a construct that GDB uses to keep track of calling and called
+functions.
+
+@code{FRAME_FP} in the machine description has no meaning to the
+machine-independent part of GDB, except that it is used when setting up
+a new frame from scratch, as follows:
+
+@example
+      create_new_frame (read_register (FP_REGNUM), read_pc ()));
+@end example
+
+Other than that, all the meaning imparted to @code{FP_REGNUM} is
+imparted by the machine-dependent code.  So, @code{FP_REGNUM} can have
+any value that is convenient for the code that creates new frames.
+(@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
+defined; that is where you should use the @code{FP_REGNUM} value, if
+your frames are nonstandard.)
+
+Given a GDB frame, define @code{FRAME_CHAIN} to determine the address of
+the calling function's frame.  This will be used to create a new GDB
+frame struct, and then @code{INIT_EXTRA_FRAME_INFO} and
+@code{INIT_FRAME_PC} will be called for the new frame.
+
+@section Breakpoint Handling
+
+In general, a breakpoint is a user-designated location in the program
+where the user wants to regain control if program execution ever reaches
+that location.
+
+There are two main ways to implement breakpoints; either as ``hardware''
+breakpoints or as ``software'' breakpoints.
+
+Hardware breakpoints are sometimes available as a builtin debugging
+features with some chips.  Typically these work by having dedicated
+register into which the breakpoint address may be stored.  If the PC
+ever matches a value in a breakpoint registers, the CPU raises an
+exception and reports it to GDB.  Another possibility is when an
+emulator is in use; many emulators include circuitry that watches the
+address lines coming out from the processor, and force it to stop if the
+address matches a breakpoint's address.  A third possibility is that the
+target already has the ability to do breakpoints somehow; for instance,
+a ROM monitor may do its own software breakpoints.  So although these
+are not literally ``hardware breakpoints'', from GDB's point of view
+they work the same; GDB need not do nothing more than set the breakpoint
+and wait for something to happen.
+
+Since they depend on hardware resources, hardware breakpoints may be
+limited in number; when the user asks for more, GDB will start trying to
+set software breakpoints.
+
+Software breakpoints require GDB to do somewhat more work.  The basic
+theory is that GDB will replace a program instruction a trap, illegal
+divide, or some other instruction that will cause an exception, and then
+when it's encountered, GDB will take the exception and stop the program.
+When the user says to continue, GDB will restore the original
+instruction, single-step, re-insert the trap, and continue on.
+
+Since it literally overwrites the program being tested, the program area
+must be writeable, so this technique won't work on programs in ROM.  It
+can also distort the behavior of programs that examine themselves,
+although the situation would be highly unusual.
+
+Also, the software breakpoint instruction should be the smallest size of
+instruction, so it doesn't overwrite an instruction that might be a jump
+target, and cause disaster when the program jumps into the middle of the
+breakpoint instruction.  (Strictly speaking, the breakpoint must be no
+larger than the smallest interval between instructions that may be jump
+targets; perhaps there is an architecture where only even-numbered
+instructions may jumped to.)  Note that it's possible for an instruction
+set not to have any instructions usable for a software breakpoint,
+although in practice only the ARC has failed to define such an
+instruction.
+
+The basic definition of the software breakpoint is the macro
+@code{BREAKPOINT}.
+
+Basic breakpoint object handling is in @file{breakpoint.c}.  However,
+much of the interesting breakpoint action is in @file{infrun.c}.
+
+@section Single Stepping
+
+@section Signal Handling
+
+@section Thread Handling
+
+@section Inferior Function Calls
+
+@section Longjmp Support
+
+GDB has support for figuring out that the target is doing a
+@code{longjmp} and for stopping at the target of the jump, if we are
+stepping.  This is done with a few specialized internal breakpoints,
+which are visible in the @code{maint info breakpoint} command.
+
+To make this work, you need to define a macro called
+@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
+structure and extract the longjmp target address.  Since @code{jmp_buf}
+is target specific, you will need to define it in the appropriate
+@file{tm-@var{xyz}.h} file.  Look in @file{tm-sun4os4.h} and
+@file{sparc-tdep.c} for examples of how to do this.
+
+@node User Interface
+
+@chapter User Interface
+
+GDB has several user interfaces.  Although the command-line interface
+is the most common and most familiar, there are others.
+
+@section Command Interpreter
+
+The command interpreter in GDB is fairly simple.  It is designed to
+allow for the set of commands to be augmented dynamically, and also
+has a recursive subcommand capability, where the first argument to
+a command may itself direct a lookup on a different command list.
+
+For instance, the @code{set} command just starts a lookup on the
+@code{setlist} command list, while @code{set thread} recurses
+to the @code{set_thread_cmd_list}.
+
+To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
+the main command list, and should be used for those commands.  The usual
+place to add commands is in the @code{_initialize_@var{xyz}} routines at the
+ends of most source files.
+
+@section Console Printing
+
+@section TUI
+
+@section libgdb
+
+@code{libgdb} was an abortive project of years ago.  The theory was to
+provide an API to GDB's functionality.
+
+@node Symbol Handling
+
+@chapter Symbol Handling
+
+Symbols are a key part of GDB's operation.  Symbols include variables,
+functions, and types.
+
+@section Symbol Reading
+
+GDB reads symbols from ``symbol files''.  The usual symbol file is the
+file containing the program which GDB is debugging.  GDB can be directed
+to use a different file for symbols (with the @code{symbol-file}
+command), and it can also read more symbols via the ``add-file'' and
+``load'' commands, or while reading symbols from shared libraries.
+
+Symbol files are initially opened by code in @file{symfile.c} using the
+BFD library.  BFD identifies the type of the file by examining its
+header.  @code{symfile_init} then uses this identification to locate a
+set of symbol-reading functions.
+
+Symbol reading modules identify themselves to GDB by calling
+@code{add_symtab_fns} during their module initialization.  The argument
+to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
+name (or name prefix) of the symbol format, the length of the prefix,
+and pointers to four functions.  These functions are called at various
+times to process symbol-files whose identification matches the specified
+prefix.
+
+The functions supplied by each module are:
+
+@table @code
+@item @var{xyz}_symfile_init(struct sym_fns *sf)
+
+Called from @code{symbol_file_add} when we are about to read a new
+symbol file.  This function should clean up any internal state (possibly
+resulting from half-read previous files, for example) and prepare to
+read a new symbol file. Note that the symbol file which we are reading
+might be a new "main" symbol file, or might be a secondary symbol file
+whose symbols are being added to the existing symbol table.
+
+The argument to @code{@var{xyz}_symfile_init} is a newly allocated
+@code{struct sym_fns} whose @code{bfd} field contains the BFD for the
+new symbol file being read.  Its @code{private} field has been zeroed,
+and can be modified as desired.  Typically, a struct of private
+information will be @code{malloc}'d, and a pointer to it will be placed
+in the @code{private} field.
+
+There is no result from @code{@var{xyz}_symfile_init}, but it can call
+@code{error} if it detects an unavoidable problem.
+
+@item @var{xyz}_new_init()
+
+Called from @code{symbol_file_add} when discarding existing symbols.
+This function need only handle the symbol-reading module's internal
+state; the symbol table data structures visible to the rest of GDB will
+be discarded by @code{symbol_file_add}.  It has no arguments and no
+result.  It may be called after @code{@var{xyz}_symfile_init}, if a new
+symbol table is being read, or may be called alone if all symbols are
+simply being discarded.
+
+@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
+
+Called from @code{symbol_file_add} to actually read the symbols from a
+symbol-file into a set of psymtabs or symtabs.
+
+@code{sf} points to the struct sym_fns originally passed to
+@code{@var{xyz}_sym_init} for possible initialization.  @code{addr} is
+the offset between the file's specified start address and its true
+address in memory.  @code{mainline} is 1 if this is the main symbol
+table being read, and 0 if a secondary symbol file (e.g. shared library
+or dynamically loaded file) is being read.@refill
+@end table
+
+In addition, if a symbol-reading module creates psymtabs when
+@var{xyz}_symfile_read is called, these psymtabs will contain a pointer
+to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
+from any point in the GDB symbol-handling code.
+
+@table @code
+@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
+
+Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if
+the psymtab has not already been read in and had its @code{pst->symtab}
+pointer set.  The argument is the psymtab to be fleshed-out into a
+symtab.  Upon return, pst->readin should have been set to 1, and
+pst->symtab should contain a pointer to the new corresponding symtab, or
+zero if there were no symbols in that part of the symbol file.
+@end table
+
+@section Partial Symbol Tables
+
+GDB has three types of symbol tables.
+
+@itemize @bullet
+
+@item full symbol tables (symtabs).  These contain the main information
+about symbols and addresses.
+
+@item partial symbol tables (psymtabs).  These contain enough
+information to know when to read the corresponding part of the full
+symbol table.
+
+@item minimal symbol tables (msymtabs).  These contain information
+gleaned from non-debugging symbols.
+
+@end itemize
+
+This section describes partial symbol tables.
+
+A psymtab is constructed by doing a very quick pass over an executable
+file's debugging information.  Small amounts of information are
+extracted -- enough to identify which parts of the symbol table will
+need to be re-read and fully digested later, when the user needs the
+information.  The speed of this pass causes GDB to start up very
+quickly.  Later, as the detailed rereading occurs, it occurs in small
+pieces, at various times, and the delay therefrom is mostly invisible to
+the user.
+@c (@xref{Symbol Reading}.)
+
+The symbols that show up in a file's psymtab should be, roughly, those
+visible to the debugger's user when the program is not running code from
+that file.  These include external symbols and types, static symbols and
+types, and enum values declared at file scope.
+
+The psymtab also contains the range of instruction addresses that the
+full symbol table would represent.
+
+The idea is that there are only two ways for the user (or much of the
+code in the debugger) to reference a symbol:
+
+@itemize @bullet
+
+@item by its address
+(e.g. execution stops at some address which is inside a function in this
+file).  The address will be noticed to be in the range of this psymtab,
+and the full symtab will be read in.  @code{find_pc_function},
+@code{find_pc_line}, and other @code{find_pc_@dots{}} functions handle
+this.
+
+@item by its name
+(e.g. the user asks to print a variable, or set a breakpoint on a
+function).  Global names and file-scope names will be found in the
+psymtab, which will cause the symtab to be pulled in.  Local names will
+have to be qualified by a global name, or a file-scope name, in which
+case we will have already read in the symtab as we evaluated the
+qualifier.  Or, a local symbol can be referenced when we are "in" a
+local scope, in which case the first case applies.  @code{lookup_symbol}
+does most of the work here.
+
+@end itemize
+
+The only reason that psymtabs exist is to cause a symtab to be read in
+at the right moment.  Any symbol that can be elided from a psymtab,
+while still causing that to happen, should not appear in it.  Since
+psymtabs don't have the idea of scope, you can't put local symbols in
+them anyway.  Psymtabs don't have the idea of the type of a symbol,
+either, so types need not appear, unless they will be referenced by
+name.
+
+It is a bug for GDB to behave one way when only a psymtab has been read,
+and another way if the corresponding symtab has been read in.  Such bugs
+are typically caused by a psymtab that does not contain all the visible
+symbols, or which has the wrong instruction address ranges.
+
+The psymtab for a particular section of a symbol-file (objfile) could be
+thrown away after the symtab has been read in.  The symtab should always
+be searched before the psymtab, so the psymtab will never be used (in a
+bug-free environment).  Currently, psymtabs are allocated on an obstack,
+and all the psymbols themselves are allocated in a pair of large arrays
+on an obstack, so there is little to be gained by trying to free them
+unless you want to do a lot more work.
+
+@section Types
+
+Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
+
+These are the fundamental types that GDB uses internally.  Fundamental
+types from the various debugging formats (stabs, ELF, etc) are mapped
+into one of these.  They are basically a union of all fundamental types
+that gdb knows about for all the languages that GDB knows about.
+
+Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
+
+Each time GDB builds an internal type, it marks it with one of these
+types.  The type may be a fundamental type, such as TYPE_CODE_INT, or a
+derived type, such as TYPE_CODE_PTR which is a pointer to another type.
+Typically, several FT_* types map to one TYPE_CODE_* type, and are
+distinguished by other members of the type struct, such as whether the
+type is signed or unsigned, and how many bits it uses.
+
+Builtin Types (e.g., builtin_type_void, builtin_type_char).
+
+These are instances of type structs that roughly correspond to
+fundamental types and are created as global types for GDB to use for
+various ugly historical reasons.  We eventually want to eliminate these.
+Note for example that builtin_type_int initialized in gdbtypes.c is
+basically the same as a TYPE_CODE_INT type that is initialized in
+c-lang.c for an FT_INTEGER fundamental type.  The difference is that the
+builtin_type is not associated with any particular objfile, and only one
+instance exists, while c-lang.c builds as many TYPE_CODE_INT types as
+needed, with each one associated with some particular objfile.
+
+@section Object File Formats
+
+@subsection a.out
+
+The @file{a.out} format is the original file format for Unix.  It
+consists of three sections: text, data, and bss, which are for program
+code, initialized data, and uninitialized data, respectively.
+
+The @file{a.out} format is so simple that it doesn't have any reserved
+place for debugging information.  (Hey, the original Unix hackers used
+@file{adb}, which is a machine-language debugger.)  The only debugging
+format for @file{a.out} is stabs, which is encoded as a set of normal
+symbols with distinctive attributes.
+
+The basic @file{a.out} reader is in @file{dbxread.c}.
+
+@subsection COFF
+
+The COFF format was introduced with System V Release 3 (SVR3) Unix.
+COFF files may have multiple sections, each prefixed by a header.  The
+number of sections is limited.
+
+The COFF specification includes support for debugging.  Although this
+was a step forward, the debugging information was woefully limited.  For
+instance, it was not possible to represent code that came from an
+included file.
+
+The COFF reader is in @file{coffread.c}.
+
+@subsection ECOFF
+
+ECOFF is an extended COFF originally introduced for Mips and Alpha
+workstations.
+
+The basic ECOFF reader is in @file{mipsread.c}.
+
+@subsection XCOFF
+
+The IBM RS/6000 running AIX uses an object file format called XCOFF.
+The COFF sections, symbols, and line numbers are used, but debugging
+symbols are dbx-style stabs whose strings are located in the
+@samp{.debug} section (rather than the string table).  For more
+information, see @xref{Top,,,stabs,The Stabs Debugging Format}.
+
+The shared library scheme has a clean interface for figuring out what
+shared libraries are in use, but the catch is that everything which
+refers to addresses (symbol tables and breakpoints at least) needs to be
+relocated for both shared libraries and the main executable.  At least
+using the standard mechanism this can only be done once the program has
+been run (or the core file has been read).
+
+@subsection PE
+
+Windows 95 and NT use the PE (Portable Executable) format for their
+executables.  PE is basically COFF with additional headers.
+
+While BFD includes special PE support, GDB needs only the basic
+COFF reader.
+
+@subsection ELF
+
+The ELF format came with System V Release 4 (SVR4) Unix.  ELF is similar
+to COFF in being organized into a number of sections, but it removes
+many of COFF's limitations.
+
+The basic ELF reader is in @file{elfread.c}.
+
+@subsection SOM
+
+SOM is HP's object file and debug format (not to be confused with IBM's
+SOM, which is a cross-language ABI).
+
+The SOM reader is in @file{hpread.c}.
+
+@subsection Other File Formats
+
+Other file formats that have been supported by GDB include Netware
+Loadable Modules (@file{nlmread.c}.
+
+@section Debugging File Formats
+
+This section describes characteristics of debugging information that
+are independent of the object file format.
+
+@subsection stabs
+
+@code{stabs} started out as special symbols within the @code{a.out}
+format.  Since then, it has been encapsulated into other file
+formats, such as COFF and ELF.
+
+While @file{dbxread.c} does some of the basic stab processing,
+including for encapsulated versions, @file{stabsread.c} does
+the real work.
+
+@subsection COFF
+
+The basic COFF definition includes debugging information.  The level
+of support is minimal and non-extensible, and is not often used.
+
+@subsection Mips debug (Third Eye)
+
+ECOFF includes a definition of a special debug format.
+
+The file @file{mdebugread.c} implements reading for this format.
+
+@subsection DWARF 1
+
+DWARF 1 is a debugging format that was originally designed to be
+used with ELF in SVR4 systems.
+
+@c CHILL_PRODUCER
+@c GCC_PRODUCER
+@c GPLUS_PRODUCER
+@c LCC_PRODUCER
+@c If defined, these are the producer strings in a DWARF 1 file.  All of
+@c these have reasonable defaults already.
+
+The DWARF 1 reader is in @file{dwarfread.c}.
+
+@subsection DWARF 2
+
+DWARF 2 is an improved but incompatible version of DWARF 1.
+
+The DWARF 2 reader is in @file{dwarf2read.c}.
+
+@subsection SOM
+
+Like COFF, the SOM definition includes debugging information.
+
+@section Adding a New Symbol Reader to GDB
+
+If you are using an existing object file format (a.out, COFF, ELF, etc),
+there is probably little to be done.
+
+If you need to add a new object file format, you must first add it to
+BFD.  This is beyond the scope of this document.
+
+You must then arrange for the BFD code to provide access to the
+debugging symbols.  Generally GDB will have to call swapping routines
+from BFD and a few other BFD internal routines to locate the debugging
+information.  As much as possible, GDB should not depend on the BFD
+internal data structures.
+
+For some targets (e.g., COFF), there is a special transfer vector used
+to call swapping routines, since the external data structures on various
+platforms have different sizes and layouts.  Specialized routines that
+will only ever be implemented by one object file format may be called
+directly.  This interface should be described in a file
+@file{bfd/libxyz.h}, which is included by GDB.
+
+
+@node Language Support
+
+@chapter Language Support
+
+GDB's language support is mainly driven by the symbol reader, although
+it is possible for the user to set the source language manually.
+
+GDB chooses the source language by looking at the extension of the file
+recorded in the debug info; @code{.c} means C, @code{.f} means Fortran,
+etc.  It may also use a special-purpose language identifier if the debug
+format supports it, such as DWARF.
+
+@section Adding a Source Language to GDB
+
+To add other languages to GDB's expression parser, follow the following
+steps:
+
+@table @emph
+@item Create the expression parser.
+
+This should reside in a file @file{@var{lang}-exp.y}.  Routines for
+building parsed expressions into a @samp{union exp_element} list are in
+@file{parse.c}.
+
+Since we can't depend upon everyone having Bison, and YACC produces
+parsers that define a bunch of global names, the following lines
+@emph{must} be included at the top of the YACC parser, to prevent the
+various parsers from defining the same global names:
+
+@example
+#define yyparse 	@var{lang}_parse
+#define yylex 	@var{lang}_lex
+#define yyerror 	@var{lang}_error
+#define yylval 	@var{lang}_lval
+#define yychar 	@var{lang}_char
+#define yydebug 	@var{lang}_debug
+#define yypact  	@var{lang}_pact 
+#define yyr1		@var{lang}_r1   
+#define yyr2		@var{lang}_r2   
+#define yydef		@var{lang}_def  
+#define yychk		@var{lang}_chk  
+#define yypgo		@var{lang}_pgo  
+#define yyact  	@var{lang}_act  
+#define yyexca  	@var{lang}_exca
+#define yyerrflag  	@var{lang}_errflag
+#define yynerrs  	@var{lang}_nerrs
+@end example
+
+At the bottom of your parser, define a @code{struct language_defn} and
+initialize it with the right values for your language.  Define an
+@code{initialize_@var{lang}} routine and have it call
+@samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
+that your language exists.  You'll need some other supporting variables
+and functions, which will be used via pointers from your
+@code{@var{lang}_language_defn}.  See the declaration of @code{struct
+language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
+for more information.
+
+@item Add any evaluation routines, if necessary
+
+If you need new opcodes (that represent the operations of the language),
+add them to the enumerated type in @file{expression.h}.  Add support
+code for these operations in @code{eval.c:evaluate_subexp()}.  Add cases
+for new opcodes in two functions from @file{parse.c}:
+@code{prefixify_subexp()} and @code{length_of_subexp()}.  These compute
+the number of @code{exp_element}s that a given operation takes up.
+
+@item Update some existing code
+
+Add an enumerated identifier for your language to the enumerated type
+@code{enum language} in @file{defs.h}.
+
+Update the routines in @file{language.c} so your language is included.
+These routines include type predicates and such, which (in some cases)
+are language dependent.  If your language does not appear in the switch
+statement, an error is reported.
+
+Also included in @file{language.c} is the code that updates the variable
+@code{current_language}, and the routines that translate the
+@code{language_@var{lang}} enumerated identifier into a printable
+string.
+
+Update the function @code{_initialize_language} to include your
+language.  This function picks the default language upon startup, so is
+dependent upon which languages that GDB is built for.
+
+Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
+code so that the language of each symtab (source file) is set properly.
+This is used to determine the language to use at each stack frame level.
+Currently, the language is set based upon the extension of the source
+file.  If the language can be better inferred from the symbol
+information, please set the language of the symtab in the symbol-reading
+code.
+
+Add helper code to @code{expprint.c:print_subexp()} to handle any new
+expression opcodes you have added to @file{expression.h}.  Also, add the
+printed representations of your operators to @code{op_print_tab}.
+
+@item Add a place of call
+
+Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
+@code{parse.c:parse_exp_1()}.
+
+@item Use macros to trim code
+
+The user has the option of building GDB for some or all of the
+languages.  If the user decides to build GDB for the language
+@var{lang}, then every file dependent on @file{language.h} will have the
+macro @code{_LANG_@var{lang}} defined in it.  Use @code{#ifdef}s to
+leave out large routines that the user won't need if he or she is not
+using your language.
+
+Note that you do not need to do this in your YACC parser, since if GDB
+is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
+compiled form of your parser) is not linked into GDB at all.
+
+See the file @file{configure.in} for how GDB is configured for different
+languages.
+
+@item Edit @file{Makefile.in}
+
+Add dependencies in @file{Makefile.in}.  Make sure you update the macro
+variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
+not get linked in, or, worse yet, it may not get @code{tar}red into the
+distribution!
+
+@end table
+
+
+@node Host Definition
+
+@chapter Host Definition
+
+With the advent of autoconf, it's rarely necessary to have host
+definition machinery anymore.
+
+@section Adding a New Host
+
+Most of GDB's host configuration support happens via autoconf.  It
+should be rare to need new host-specific definitions.  GDB still uses
+the host-specific definitions and files listed below, but these mostly
+exist for historical reasons, and should eventually disappear.
+
+Several files control GDB's configuration for host systems:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed when hosting on machine @var{xyz}.
+In particular, this lists the required machine-dependent object files,
+by defining @samp{XDEPFILES=@dots{}}.  Also specifies the header file
+which describes host @var{xyz}, by defining @code{XM_FILE=
+xm-@var{xyz}.h}.  You can also define @code{CC}, @code{SYSV_DEFINE},
+@code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
+etc.; see @file{Makefile.in}.
+
+@item gdb/config/@var{arch}/xm-@var{xyz}.h
+(@file{xm.h} is a link to this file, created by configure).  Contains C
+macro definitions describing the host system environment, such as byte
+order, host C compiler and library.
+
+@item gdb/@var{xyz}-xdep.c
+Contains any miscellaneous C code required for this machine as a host.
+On most machines it doesn't exist at all.  If it does exist, put
+@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
+@file{gdb/config/@var{arch}/@var{xyz}.mh}.
+
+@end table
+
+@subheading Generic Host Support Files
+
+There are some ``generic'' versions of routines that can be used by
+various systems.  These can be customized in various ways by macros
+defined in your @file{xm-@var{xyz}.h} file.  If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
+
+Otherwise, if your machine needs custom support routines, you will need
+to write routines that perform the same functions as the generic file.
+Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
+into @code{XDEPFILES}.
+
+@table @file
+
+@item ser-unix.c
+This contains serial line support for Unix systems.  This is always
+included, via the makefile variable @code{SER_HARDWIRE}; override this
+variable in the @file{.mh} file to avoid it.
+
+@item ser-go32.c
+This contains serial line support for 32-bit programs running under DOS,
+using the GO32 execution environment.
+
+@item ser-tcp.c
+This contains generic TCP support using sockets.
+
+@end table
+
+@section Host Conditionals
+
+When GDB is configured and compiled, various macros are defined or left
+undefined, to control compilation based on the attributes of the host
+system.  These macros and their meanings (or if the meaning is not
+documented here, then one of the source files where they are used is
+indicated) are:
+
+@table @code
+
+@item GDBINIT_FILENAME
+The default name of GDB's initialization file (normally @file{.gdbinit}).
+
+@item MEM_FNS_DECLARED
+Your host config file defines this if it includes declarations of
+@code{memcpy} and @code{memset}.  Define this to avoid conflicts between
+the native include files and the declarations in @file{defs.h}.
+
+@item NO_SYS_FILE
+Define this if your system does not have a @code{<sys/file.h>}.
+
+@item SIGWINCH_HANDLER
+If your host defines @code{SIGWINCH}, you can define this to be the name
+of a function to be called if @code{SIGWINCH} is received.
+
+@item SIGWINCH_HANDLER_BODY
+Define this to expand into code that will define the function named by
+the expansion of @code{SIGWINCH_HANDLER}.
+
+@item ALIGN_STACK_ON_STARTUP
+Define this if your system is of a sort that will crash in
+@code{tgetent} if the stack happens not to be longword-aligned when
+@code{main} is called.  This is a rare situation, but is known to occur
+on several different types of systems.
+
+@item CRLF_SOURCE_FILES
+Define this if host files use @code{\r\n} rather than @code{\n} as a
+line terminator.  This will cause source file listings to omit @code{\r}
+characters when printing and it will allow \r\n line endings of files
+which are "sourced" by gdb.  It must be possible to open files in binary
+mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
+
+@item DEFAULT_PROMPT
+The default value of the prompt string (normally @code{"(gdb) "}).
+
+@item DEV_TTY
+The name of the generic TTY device, defaults to @code{"/dev/tty"}.
+
+@item FCLOSE_PROVIDED
+Define this if the system declares @code{fclose} in the headers included
+in @code{defs.h}.  This isn't needed unless your compiler is unusually
+anal.
+
+@item FOPEN_RB
+Define this if binary files are opened the same way as text files.
+
+@item GETENV_PROVIDED
+Define this if the system declares @code{getenv} in its headers included
+in @code{defs.h}. This isn't needed unless your compiler is unusually
+anal.
+
+@item HAVE_MMAP
+In some cases, use the system call @code{mmap} for reading symbol
+tables.  For some machines this allows for sharing and quick updates.
+
+@item HAVE_SIGSETMASK
+Define this if the host system has job control, but does not define
+@code{sigsetmask()}.  Currently, this is only true of the RS/6000.
+
+@item HAVE_TERMIO
+Define this if the host system has @code{termio.h}.
+
+@item HOST_BYTE_ORDER
+The ordering of bytes in the host.  This must be defined to be either
+@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
+
+@item INT_MAX
+@item INT_MIN
+@item LONG_MAX
+@item UINT_MAX
+@item ULONG_MAX
+Values for host-side constants.
+
+@item ISATTY
+Substitute for isatty, if not available.
+
+@item LONGEST
+This is the longest integer type available on the host.  If not defined,
+it will default to @code{long long} or @code{long}, depending on
+@code{CC_HAS_LONG_LONG}.
+
+@item CC_HAS_LONG_LONG
+Define this if the host C compiler supports ``long long''.  This is set
+by the configure script.
+
+@item PRINTF_HAS_LONG_LONG
+Define this if the host can handle printing of long long integers via
+the printf format directive ``ll''. This is set by the configure script.
+
+@item HAVE_LONG_DOUBLE
+Define this if the host C compiler supports ``long double''.  This is
+set by the configure script.
+
+@item PRINTF_HAS_LONG_DOUBLE
+Define this if the host can handle printing of long double float-point
+numbers via the printf format directive ``Lg''. This is set by the
+configure script.
+
+@item SCANF_HAS_LONG_DOUBLE
+Define this if the host can handle the parsing of long double
+float-point numbers via the scanf format directive directive
+``Lg''. This is set by the configure script.
+
+@item LSEEK_NOT_LINEAR
+Define this if @code{lseek (n)} does not necessarily move to byte number
+@code{n} in the file.  This is only used when reading source files.  It
+is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
+
+@item L_SET
+This macro is used as the argument to lseek (or, most commonly,
+bfd_seek).  FIXME, should be replaced by SEEK_SET instead, which is the
+POSIX equivalent.
+
+@item MAINTENANCE_CMDS
+If the value of this is 1, then a number of optional maintenance
+commands are compiled in.
+
+@item MALLOC_INCOMPATIBLE
+Define this if the system's prototype for @code{malloc} differs from the
+@sc{ANSI} definition.
+
+@item MMAP_BASE_ADDRESS
+When using HAVE_MMAP, the first mapping should go at this address.
+
+@item MMAP_INCREMENT
+when using HAVE_MMAP, this is the increment between mappings.
+
+@item NEED_POSIX_SETPGID
+Define this to use the POSIX version of @code{setpgid} to determine
+whether job control is available.
+
+@item NORETURN
+If defined, this should be one or more tokens, such as @code{volatile},
+that can be used in both the declaration and definition of functions to
+indicate that they never return.  The default is already set correctly
+if compiling with GCC.  This will almost never need to be defined.
+
+@item ATTR_NORETURN
+If defined, this should be one or more tokens, such as
+@code{__attribute__ ((noreturn))}, that can be used in the declarations
+of functions to indicate that they never return.  The default is already
+set correctly if compiling with GCC.  This will almost never need to be
+defined.
+
+@item USE_MMALLOC
+GDB will use the @code{mmalloc} library for memory allocation for symbol
+reading if this symbol is defined.  Be careful defining it since there
+are systems on which @code{mmalloc} does not work for some reason.  One
+example is the DECstation, where its RPC library can't cope with our
+redefinition of @code{malloc} to call @code{mmalloc}.  When defining
+@code{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the
+Makefile, to point to the mmalloc library.  This define is set when you
+configure with --with-mmalloc.
+
+@item NO_MMCHECK
+Define this if you are using @code{mmalloc}, but don't want the overhead
+of checking the heap with @code{mmcheck}.  Note that on some systems,
+the C runtime makes calls to malloc prior to calling @code{main}, and if
+@code{free} is ever called with these pointers after calling
+@code{mmcheck} to enable checking, a memory corruption abort is certain
+to occur.  These systems can still use mmalloc, but must define
+NO_MMCHECK.
+
+@item MMCHECK_FORCE
+Define this to 1 if the C runtime allocates memory prior to
+@code{mmcheck} being called, but that memory is never freed so we don't
+have to worry about it triggering a memory corruption abort.  The
+default is 0, which means that @code{mmcheck} will only install the heap
+checking functions if there has not yet been any memory allocation
+calls, and if it fails to install the functions, gdb will issue a
+warning.  This is currently defined if you configure using
+--with-mmalloc.
+
+@item NO_SIGINTERRUPT
+Define this to indicate that siginterrupt() is not available.
+
+@item R_OK
+Define if this is not in a system .h file.
+
+@item SEEK_CUR
+@item SEEK_SET
+Define these to appropriate value for the system lseek(), if not already
+defined.
+
+@item STOP_SIGNAL
+This is the signal for stopping GDB.  Defaults to SIGTSTP.  (Only
+redefined for the Convex.)
+
+@item USE_O_NOCTTY
+Define this if the interior's tty should be opened with the O_NOCTTY
+flag.  (FIXME: This should be a native-only flag, but @file{inflow.c} is
+always linked in.)
+
+@item USG
+Means that System V (prior to SVR4) include files are in use.  (FIXME:
+This symbol is abused in @file{infrun.c}, @file{regex.c},
+@file{remote-nindy.c}, and @file{utils.c} for other things, at the
+moment.)
+
+@item lint
+Define this to help placate lint in some situations.
+
+@item volatile
+Define this to override the defaults of @code{__volatile__} or
+@code{/**/}.
+
+@end table
+
+
+@node Target Architecture Definition
+
+@chapter Target Architecture Definition
+
+GDB's target architecture defines what sort of machine-language programs
+GDB can work with, and how it works with them.
+
+At present, the target architecture definition consists of a number of C
+macros.
+
+@section Registers and Memory
+
+GDB's model of the target machine is rather simple.  GDB assumes the
+machine includes a bank of registers and a block of memory.  Each
+register may have a different size.
+
+GDB does not have a magical way to match up with the compiler's idea of
+which registers are which; however, it is critical that they do match up
+accurately.  The only way to make this work is to get accurate
+information about the order that the compiler uses, and to reflect that
+in the @code{REGISTER_NAME} and related macros.
+
+GDB can handle big-endian, little-endian, and bi-endian architectures.
+
+@section Frame Interpretation
+
+@section Inferior Call Setup
+
+@section Compiler Characteristics
+
+@section Target Conditionals
+
+This section describes the macros that you can use to define the target
+machine.
+
+@table @code
+
+@item ADDITIONAL_OPTIONS
+@item ADDITIONAL_OPTION_CASES
+@item ADDITIONAL_OPTION_HANDLER
+@item ADDITIONAL_OPTION_HELP
+These are a set of macros that allow the addition of additional command
+line options to GDB.  They are currently used only for the unsupported
+i960 Nindy target, and should not be used in any other configuration.
+
+@item ADDR_BITS_REMOVE (addr)
+If a raw machine address includes any bits that are not really part of
+the address, then define this macro to expand into an expression that
+zeros those bits in @var{addr}.  For example, the two low-order bits of
+a Motorola 88K address may be used by some kernels for their own
+purposes, since addresses must always be 4-byte aligned, and so are of
+no use for addressing.  Those bits should be filtered out with an
+expression such as @code{((addr) & ~3)}.
+
+@item BEFORE_MAIN_LOOP_HOOK
+Define this to expand into any code that you want to execute before the
+main loop starts.  Although this is not, strictly speaking, a target
+conditional, that is how it is currently being used.  Note that if a
+configuration were to define it one way for a host and a different way
+for the target, GDB will probably not compile, let alone run correctly.
+This is currently used only for the unsupported i960 Nindy target, and
+should not be used in any other configuration.
+
+@item BELIEVE_PCC_PROMOTION
+Define if the compiler promotes a short or char parameter to an int, but
+still reports the parameter as its original type, rather than the
+promoted type.
+
+@item BELIEVE_PCC_PROMOTION_TYPE
+Define this if GDB should believe the type of a short argument when
+compiled by pcc, but look within a full int space to get its value.
+Only defined for Sun-3 at present.
+
+@item BITS_BIG_ENDIAN
+Define this if the numbering of bits in the targets does *not* match the
+endianness of the target byte order.  A value of 1 means that the bits
+are numbered in a big-endian order, 0 means little-endian.
+
+@item BREAKPOINT
+This is the character array initializer for the bit pattern to put into
+memory where a breakpoint is set.  Although it's common to use a trap
+instruction for a breakpoint, it's not required; for instance, the bit
+pattern could be an invalid instruction.  The breakpoint must be no
+longer than the shortest instruction of the architecture.
+
+@item BIG_BREAKPOINT
+@item LITTLE_BREAKPOINT
+Similar to BREAKPOINT, but used for bi-endian targets.
+
+@item REMOTE_BREAKPOINT
+@item LITTLE_REMOTE_BREAKPOINT
+@item BIG_REMOTE_BREAKPOINT
+Similar to BREAKPOINT, but used for remote targets.
+
+@item BREAKPOINT_FROM_PC (pcptr, lenptr)
+
+Use the program counter to determine the contents and size of a
+breakpoint instruction.  It returns a pointer to a string of bytes that
+encode a breakpoint instruction, stores the length of the string to
+*lenptr, and adjusts pc (if necessary) to point to the actual memory
+location where the breakpoint should be inserted.
+
+Although it is common to use a trap instruction for a breakpoint, it's
+not required; for instance, the bit pattern could be an invalid
+instruction.  The breakpoint must be no longer than the shortest
+instruction of the architecture.
+
+Replaces all the other BREAKPOINTs.
+
+@item CALL_DUMMY
+valops.c
+@item CALL_DUMMY_LOCATION
+inferior.h
+@item CALL_DUMMY_STACK_ADJUST
+valops.c
+
+@item CANNOT_FETCH_REGISTER (regno)
+A C expression that should be nonzero if @var{regno} cannot be fetched
+from an inferior process.  This is only relevant if
+@code{FETCH_INFERIOR_REGISTERS} is not defined.
+
+@item CANNOT_STORE_REGISTER (regno)
+A C expression that should be nonzero if @var{regno} should not be
+written to the target.  This is often the case for program counters,
+status words, and other special registers.  If this is not defined, GDB
+will assume that all registers may be written.
+
+@item DO_DEFERRED_STORES
+@item CLEAR_DEFERRED_STORES
+Define this to execute any deferred stores of registers into the inferior,
+and to cancel any deferred stores.
+
+Currently only implemented correctly for native Sparc configurations?
+
+@item CPLUS_MARKER
+Define this to expand into the character that G++ uses to distinguish
+compiler-generated identifiers from programmer-specified identifiers.
+By default, this expands into @code{'$'}.  Most System V targets should
+define this to @code{'.'}.
+
+@item DBX_PARM_SYMBOL_CLASS
+Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
+information.  In the i960, parameters can be stored as locals or as
+args, depending on the type of the debug record.
+
+@item DECR_PC_AFTER_BREAK
+Define this to be the amount by which to decrement the PC after the
+program encounters a breakpoint.  This is often the number of bytes in
+BREAKPOINT, though not always.  For most targets this value will be 0.
+
+@item DECR_PC_AFTER_HW_BREAK
+Similarly, for hardware breakpoints.
+
+@item DISABLE_UNSETTABLE_BREAK addr
+If defined, this should evaluate to 1 if @var{addr} is in a shared
+library in which breakpoints cannot be set and so should be disabled.
+
+@item DO_REGISTERS_INFO
+If defined, use this to print the value of a register or all registers.
+
+@item END_OF_TEXT_DEFAULT
+This is an expression that should designate the end of the text section
+(? FIXME ?)
+
+@item EXTRACT_RETURN_VALUE(type,regbuf,valbuf)
+Define this to extract a function's return value of type @var{type} from
+the raw register state @var{regbuf} and copy that, in virtual format,
+into @var{valbuf}.
+ 
+@item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)
+Define this to extract from an array @var{regbuf} containing the (raw)
+register state, the address in which a function should return its
+structure value, as a CORE_ADDR (or an expression that can be used as
+one).
+
+@item FLOAT_INFO
+If defined, then the `info float' command will print information about
+the processor's floating point unit.
+
+@item FP_REGNUM
+The number of the frame pointer register.
+
+@item FRAMELESS_FUNCTION_INVOCATION(fi, frameless)
+Define this to set the variable @var{frameless} to 1 if the function
+invocation represented by @var{fi} does not have a stack frame
+associated with it.  Otherwise set it to 0.
+
+@item FRAME_ARGS_ADDRESS_CORRECT
+stack.c
+
+@item FRAME_CHAIN(frame)
+Given @var{frame}, return a pointer to the calling frame.
+
+@item FRAME_CHAIN_COMBINE(chain,frame)
+Define this to take the frame chain pointer and the frame's nominal
+address and produce the nominal address of the caller's frame.
+Presently only defined for HP PA.
+
+@item FRAME_CHAIN_VALID(chain,thisframe)
+
+Define this to be an expression that returns zero if the given frame is
+an outermost frame, with no caller, and nonzero otherwise.  Three common
+definitions are available. @code{default_frame_chain_valid} (the
+default) is nonzero if the chain pointer is nonzero and given frame's PC
+is not inside the startup file (such as @file{crt0.o}).
+@code{alternate_frame_chain_valid} is nonzero if the chain pointer is
+nonzero and the given frame's PC is not in @code{main()} or a known
+entry point function (such as @code{_start()}).
+
+@item FRAME_INIT_SAVED_REGS(frame)
+See @file{frame.h}.  Determines the address of all registers in the
+current stack frame storing each in @code{frame->saved_regs}.  Space for
+@code{frame->saved_regs} shall be allocated by
+@code{FRAME_INIT_SAVED_REGS} using either
+@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
+
+@var{FRAME_FIND_SAVED_REGS} and @var{EXTRA_FRAME_INFO} are deprecated.
+
+@item FRAME_NUM_ARGS (val, fi)
+For the frame described by @var{fi}, set @var{val} to the number of arguments
+that are being passed.
+
+@item FRAME_SAVED_PC(frame)
+Given @var{frame}, return the pc saved there.  That is, the return
+address.
+
+@item FUNCTION_EPILOGUE_SIZE
+For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
+function end symbol is 0.  For such targets, you must define
+@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
+function's epilogue.
+
+@item GCC_COMPILED_FLAG_SYMBOL
+@item GCC2_COMPILED_FLAG_SYMBOL
+If defined, these are the names of the symbols that GDB will look for to
+detect that GCC compiled the file.  The default symbols are
+@code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently
+only defined for the Delta 68.)
+
+@item GDB_TARGET_IS_HPPA
+This determines whether horrible kludge code in dbxread.c and
+partial-stab.h is used to mangle multiple-symbol-table files from
+HPPA's.  This should all be ripped out, and a scheme like elfread.c
+used.
+
+@item GDB_TARGET_IS_MACH386
+@item GDB_TARGET_IS_SUN3
+@item GDB_TARGET_IS_SUN386
+Kludges that should go away.
+
+@item GET_LONGJMP_TARGET
+For most machines, this is a target-dependent parameter.  On the
+DECstation and the Iris, this is a native-dependent parameter, since
+<setjmp.h> is needed to define it.
+
+This macro determines the target PC address that longjmp() will jump to,
+assuming that we have just stopped at a longjmp breakpoint.  It takes a
+CORE_ADDR * as argument, and stores the target PC value through this
+pointer.  It examines the current state of the machine as needed.
+
+@item GET_SAVED_REGISTER
+Define this if you need to supply your own definition for the function
+@code{get_saved_register}.  Currently this is only done for the a29k.
+
+@item HAVE_REGISTER_WINDOWS
+Define this if the target has register windows.
+@item REGISTER_IN_WINDOW_P (regnum)
+Define this to be an expression that is 1 if the given register is in
+the window.
+
+@item IBM6000_TARGET
+Shows that we are configured for an IBM RS/6000 target.  This
+conditional should be eliminated (FIXME) and replaced by
+feature-specific macros.  It was introduced in haste and we are
+repenting at leisure.
+
+@item IEEE_FLOAT
+Define this if the target system uses IEEE-format floating point numbers.
+
+@item INIT_EXTRA_FRAME_INFO (fromleaf, frame)
+If additional information about the frame is required this should be
+stored in @code{frame->extra_info}.  Space for @code{frame->extra_info}
+is allocated using @code{frame_obstack_alloc}.
+
+@item INIT_FRAME_PC (fromleaf, prev)
+This is a C statement that sets the pc of the frame pointed to by
+@var{prev}.  [By default...]
+
+@item INNER_THAN (lhs,rhs)
+Returns non-zero if stack address @var{lhs} is inner than (nearer to the
+stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
+the target's stack grows downward in memory, or @code{lhs > rsh} if the
+stack grows upward.
+
+@item IN_SIGTRAMP (pc, name)
+Define this to return true if the given @var{pc} and/or @var{name}
+indicates that the current function is a sigtramp.
+
+@item SIGTRAMP_START (pc)
+@item SIGTRAMP_END (pc)
+Define these to be the start and end address of the sigtramp for the
+given @var{pc}.  On machines where the address is just a compile time
+constant, the macro expansion will typically just ignore the supplied
+@var{pc}.
+
+@item IN_SOLIB_CALL_TRAMPOLINE pc name
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that connects to a shared library.
+
+@item IN_SOLIB_RETURN_TRAMPOLINE pc name
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that returns from a shared library.
+
+@item IS_TRAPPED_INTERNALVAR (name)
+This is an ugly hook to allow the specification of special actions that
+should occur as a side-effect of setting the value of a variable
+internal to GDB.  Currently only used by the h8500.  Note that this
+could be either a host or target conditional.
+
+@item NEED_TEXT_START_END
+Define this if GDB should determine the start and end addresses of the
+text section.  (Seems dubious.)
+
+@item NO_HIF_SUPPORT
+(Specific to the a29k.)
+
+@item SOFTWARE_SINGLE_STEP_P
+Define this as 1 if the target does not have a hardware single-step
+mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
+
+@item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)
+A function that inserts or removes (dependant on
+@var{insert_breapoints_p}) breakpoints at each possible destinations of
+the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
+for examples.
+
+@item PCC_SOL_BROKEN
+(Used only in the Convex target.)
+
+@item PC_IN_CALL_DUMMY
+inferior.h
+
+@item PC_LOAD_SEGMENT
+If defined, print information about the load segment for the program
+counter.  (Defined only for the RS/6000.)
+
+@item PC_REGNUM
+If the program counter is kept in a register, then define this macro to
+be the number of that register.  This need be defined only if
+@code{TARGET_WRITE_PC} is not defined.
+
+@item NPC_REGNUM
+The number of the ``next program counter'' register, if defined.
+
+@item NNPC_REGNUM
+The number of the ``next next program counter'' register, if defined.
+Currently, this is only defined for the Motorola 88K.
+
+@item PRINT_REGISTER_HOOK (regno)
+If defined, this must be a function that prints the contents of the
+given register to standard output.
+
+@item PRINT_TYPELESS_INTEGER
+This is an obscure substitute for @code{print_longest} that seems to
+have been defined for the Convex target.
+
+@item PROCESS_LINENUMBER_HOOK
+A hook defined for XCOFF reading.
+
+@item PROLOGUE_FIRSTLINE_OVERLAP
+(Only used in unsupported Convex configuration.)
+
+@item PS_REGNUM
+If defined, this is the number of the processor status register.  (This
+definition is only used in generic code when parsing "$ps".)
+
+@item POP_FRAME
+Used in @samp{call_function_by_hand} to remove an artificial stack
+frame.
+
+@item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)
+Define this to push arguments onto the stack for inferior function call.
+
+@item PUSH_DUMMY_FRAME
+Used in @samp{call_function_by_hand} to create an artificial stack frame.
+
+@item REGISTER_BYTES
+The total amount of space needed to store GDB's copy of the machine's
+register state.
+
+@item REGISTER_NAME(i)
+Return the name of register @var{i} as a string.  May return @var{NULL}
+or @var{NUL} to indicate that register @var{i} is not valid.
+
+@item REG_STRUCT_HAS_ADDR (gcc_p, type)
+Define this to return 1 if the given type will be passed by pointer
+rather than directly.
+
+@item SDB_REG_TO_REGNUM
+Define this to convert sdb register numbers into GDB regnums.  If not
+defined, no conversion will be done.
+
+@item SHIFT_INST_REGS
+(Only used for m88k targets.)
+
+@item SKIP_PROLOGUE (pc)
+A C statement that advances the @var{pc} across any function entry
+prologue instructions so as to reach ``real'' code.
+
+@item SKIP_PROLOGUE_FRAMELESS_P
+A C statement that should behave similarly, but that can stop as soon as
+the function is known to have a frame.  If not defined,
+@code{SKIP_PROLOGUE} will be used instead.
+
+@item SKIP_TRAMPOLINE_CODE (pc)
+If the target machine has trampoline code that sits between callers and
+the functions being called, then define this macro to return a new PC
+that is at the start of the real function.
+
+@item SP_REGNUM
+Define this to be the number of the register that serves as the stack
+pointer.
+
+@item STAB_REG_TO_REGNUM
+Define this to convert stab register numbers (as gotten from `r'
+declarations) into GDB regnums.  If not defined, no conversion will be
+done.
+
+@item STACK_ALIGN (addr)
+Define this to adjust the address to the alignment required for the
+processor's stack.
+
+@item STEP_SKIPS_DELAY (addr)
+Define this to return true if the address is of an instruction with a
+delay slot.  If a breakpoint has been placed in the instruction's delay
+slot, GDB will single-step over that instruction before resuming
+normally.  Currently only defined for the Mips.
+
+@item STORE_RETURN_VALUE (type, valbuf)
+A C expression that stores a function return value of type @var{type},
+where @var{valbuf} is the address of the value to be stored.
+
+@item SUN_FIXED_LBRAC_BUG
+(Used only for Sun-3 and Sun-4 targets.)
+
+@item SYMBOL_RELOADING_DEFAULT
+The default value of the `symbol-reloading' variable.  (Never defined in
+current sources.)
+
+@item TARGET_BYTE_ORDER_DEFAULT
+The ordering of bytes in the target.  This must be either
+@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.  This macro replaces
+@var{TARGET_BYTE_ORDER} which is deprecated.
+
+@item TARGET_BYTE_ORDER_SELECTABLE_P
+Non-zero if the target has both @code{BIG_ENDIAN} and
+@code{LITTLE_ENDIAN} variants.  This macro replaces
+@var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
+
+@item TARGET_CHAR_BIT
+Number of bits in a char; defaults to 8.
+
+@item TARGET_COMPLEX_BIT
+Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
+
+@item TARGET_DOUBLE_BIT
+Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
+
+@item TARGET_DOUBLE_COMPLEX_BIT
+Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+@item TARGET_FLOAT_BIT
+Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_INT_BIT
+Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_BIT
+Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_DOUBLE_BIT
+Number of bits in a long double float;
+defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+@item TARGET_LONG_LONG_BIT
+Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
+
+@item TARGET_PTR_BIT
+Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
+
+@item TARGET_SHORT_BIT
+Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
+
+@item TARGET_READ_PC
+@item TARGET_WRITE_PC (val, pid)
+@item TARGET_READ_SP
+@item TARGET_WRITE_SP
+@item TARGET_READ_FP
+@item TARGET_WRITE_FP
+These change the behavior of @code{read_pc}, @code{write_pc},
+@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
+For most targets, these may be left undefined.  GDB will call the read
+and write register functions with the relevant @code{_REGNUM} argument.
+
+These macros are useful when a target keeps one of these registers in a
+hard to get at place; for example, part in a segment register and part
+in an ordinary register.
+
+@item TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)
+Returns a @code{(register, offset)} pair representing the virtual 
+frame pointer in use at the code address @code{"pc"}.  If virtual 
+frame pointers are not used, a default definition simply returns 
+@code{FP_REGNUM}, with an offset of zero.
+
+@item USE_STRUCT_CONVENTION (gcc_p, type)
+If defined, this must be an expression that is nonzero if a value of the
+given @var{type} being returned from a function must have space
+allocated for it on the stack.  @var{gcc_p} is true if the function
+being considered is known to have been compiled by GCC; this is helpful
+for systems where GCC is known to use different calling convention than
+other compilers.
+
+@item VARIABLES_INSIDE_BLOCK (desc, gcc_p)
+For dbx-style debugging information, if the compiler puts variable
+declarations inside LBRAC/RBRAC blocks, this should be defined to be
+nonzero.  @var{desc} is the value of @code{n_desc} from the
+@code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed the
+presence of either the @code{GCC_COMPILED_SYMBOL} or the
+@code{GCC2_COMPILED_SYMBOL}.  By default, this is 0.
+
+@item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)
+Similarly, for OS/9000.  Defaults to 1.
+
+@end table
+
+Motorola M68K target conditionals.
+
+@table @code
+
+@item BPT_VECTOR
+Define this to be the 4-bit location of the breakpoint trap vector.  If
+not defined, it will default to @code{0xf}.
+
+@item REMOTE_BPT_VECTOR
+Defaults to @code{1}.
+
+@end table
+
+@section Adding a New Target
+
+The following files define a target to GDB:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{ttt}.mt
+Contains a Makefile fragment specific to this target.  Specifies what
+object files are needed for target @var{ttt}, by defining
+@samp{TDEPFILES=@dots{}}.  Also specifies the header file which
+describes @var{ttt}, by defining @samp{TM_FILE= tm-@var{ttt}.h}.  You
+can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, but
+these are now deprecated and may go away in future versions of GDB.
+
+@item gdb/config/@var{arch}/tm-@var{ttt}.h
+(@file{tm.h} is a link to this file, created by configure).  Contains
+macro definitions about the target machine's registers, stack frame
+format and instructions.
+
+@item gdb/@var{ttt}-tdep.c
+Contains any miscellaneous code required for this target machine.  On
+some machines it doesn't exist at all.  Sometimes the macros in
+@file{tm-@var{ttt}.h} become very complicated, so they are implemented
+as functions here instead, and the macro is simply defined to call the
+function.  This is vastly preferable, since it is easier to understand
+and debug.
+
+@item gdb/config/@var{arch}/tm-@var{arch}.h
+This often exists to describe the basic layout of the target machine's
+processor chip (registers, stack, etc).  If used, it is included by
+@file{tm-@var{ttt}.h}.  It can be shared among many targets that use the
+same processor.
+
+@item gdb/@var{arch}-tdep.c
+Similarly, there are often common subroutines that are shared by all
+target machines that use this particular architecture.
+
+@end table
+
+If you are adding a new operating system for an existing CPU chip, add a
+@file{config/tm-@var{os}.h} file that describes the operating system
+facilities that are unusual (extra symbol table info; the breakpoint
+instruction needed; etc).  Then write a @file{@var{arch}/tm-@var{os}.h}
+that just @code{#include}s @file{tm-@var{arch}.h} and
+@file{config/tm-@var{os}.h}.
+
+
+@node Target Vector Definition
+
+@chapter Target Vector Definition
+
+The target vector defines the interface between GDB's abstract handling
+of target systems, and the nitty-gritty code that actually exercises
+control over a process or a serial port.  GDB includes some 30-40
+different target vectors; however, each configuration of GDB includes
+only a few of them.
+
+@section File Targets
+
+Both executables and core files have target vectors.
+
+@section Standard Protocol and Remote Stubs
+
+GDB's file @file{remote.c} talks a serial protocol to code that runs in
+the target system.  GDB provides several sample ``stubs'' that can be
+integrated into target programs or operating systems for this purpose;
+they are named @file{*-stub.c}.
+
+The GDB user's manual describes how to put such a stub into your target
+code.  What follows is a discussion of integrating the SPARC stub into a
+complicated operating system (rather than a simple program), by Stu
+Grossman, the author of this stub.
+
+The trap handling code in the stub assumes the following upon entry to
+trap_low:
+
+@enumerate
+
+@item %l1 and %l2 contain pc and npc respectively at the time of the trap
+
+@item traps are disabled
+
+@item you are in the correct trap window
+
+@end enumerate
+
+As long as your trap handler can guarantee those conditions, then there
+is no reason why you shouldn't be able to `share' traps with the stub.
+The stub has no requirement that it be jumped to directly from the
+hardware trap vector.  That is why it calls @code{exceptionHandler()},
+which is provided by the external environment.  For instance, this could
+setup the hardware traps to actually execute code which calls the stub
+first, and then transfers to its own trap handler.
+
+For the most point, there probably won't be much of an issue with
+`sharing' traps, as the traps we use are usually not used by the kernel,
+and often indicate unrecoverable error conditions.  Anyway, this is all
+controlled by a table, and is trivial to modify.  The most important
+trap for us is for @code{ta 1}.  Without that, we can't single step or
+do breakpoints.  Everything else is unnecessary for the proper operation
+of the debugger/stub.
+
+From reading the stub, it's probably not obvious how breakpoints work.
+They are simply done by deposit/examine operations from GDB.
+
+@section ROM Monitor Interface
+
+@section Custom Protocols
+
+@section Transport Layer
+
+@section Builtin Simulator
+
+
+@node Native Debugging
+
+@chapter Native Debugging
+
+Several files control GDB's configuration for native support:
+
+@table @file
+
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed when hosting @emph{or native} on
+machine @var{xyz}.  In particular, this lists the required
+native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
+Also specifies the header file which describes native support on
+@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}.  You can also
+define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
+@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+
+@item gdb/config/@var{arch}/nm-@var{xyz}.h
+(@file{nm.h} is a link to this file, created by configure).  Contains C
+macro definitions describing the native system environment, such as
+child process control and core file support.
+
+@item gdb/@var{xyz}-nat.c
+Contains any miscellaneous C code required for this native support of
+this machine.  On some machines it doesn't exist at all.
+
+@end table
+
+There are some ``generic'' versions of routines that can be used by
+various systems.  These can be customized in various ways by macros
+defined in your @file{nm-@var{xyz}.h} file.  If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
+
+Otherwise, if your machine needs custom support routines, you will need
+to write routines that perform the same functions as the generic file.
+Put them into @code{@var{xyz}-nat.c}, and put @code{@var{xyz}-nat.o}
+into @code{NATDEPFILES}.
+
+@table @file
+
+@item inftarg.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use ptrace and wait to control the child.
+
+@item procfs.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use /proc to control the child.
+
+@item fork-child.c
+This does the low-level grunge that uses Unix system calls to do a "fork
+and exec" to start up a child process.
+
+@item infptrace.c
+This is the low level interface to inferior processes for systems using
+the Unix @code{ptrace} call in a vanilla way.
+
+@end table
+
+@section Native core file Support
+
+@table @file
+
+@item core-aout.c::fetch_core_registers()
+Support for reading registers out of a core file.  This routine calls
+@code{register_addr()}, see below.  Now that BFD is used to read core
+files, virtually all machines should use @code{core-aout.c}, and should
+just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
+@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
+
+@item core-aout.c::register_addr()
+If your @code{nm-@var{xyz}.h} file defines the macro
+@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
+set @code{addr} to the offset within the @samp{user} struct of GDB
+register number @code{regno}.  @code{blockend} is the offset within the
+``upage'' of @code{u.u_ar0}.  If @code{REGISTER_U_ADDR} is defined,
+@file{core-aout.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{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
+the @code{NATDEPFILES} list.  If you have your own
+@code{fetch_core_registers()}, you may not need a separate
+@code{register_addr()}.  Many custom @code{fetch_core_registers()}
+implementations simply locate the registers themselves.@refill
+
+@end table
+
+When making GDB run native on a new operating system, to make it
+possible to debug core files, you will need to either write specific
+code for parsing your OS's core files, or customize
+@file{bfd/trad-core.c}.  First, use whatever @code{#include} files your
+machine uses to define the struct of registers that is accessible
+(possibly in the u-area) in a core file (rather than
+@file{machine/reg.h}), and an include file that defines whatever header
+exists on a core file (e.g. the u-area or a @samp{struct core}).  Then
+modify @code{trad_unix_core_file_p()} to use these values to set up the
+section information for the data segment, stack segment, any other
+segments in the core file (perhaps shared library contents or control
+information), ``registers'' segment, and if there are two discontiguous
+sets of registers (e.g.  integer and float), the ``reg2'' segment.  This
+section information basically delimits areas in the core file in a
+standard way, which the section-reading routines in BFD know how to seek
+around in.
+
+Then back in GDB, you need a matching routine called
+@code{fetch_core_registers()}.  If you can use the generic one, it's in
+@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
+It will be passed a char pointer to the entire ``registers'' segment,
+its length, and a zero; or a char pointer to the entire ``regs2''
+segment, its length, and a 2.  The routine should suck out the supplied
+register values and install them into GDB's ``registers'' array.
+
+If your system uses @file{/proc} to control processes, and uses ELF
+format core files, then you may be able to use the same routines for
+reading the registers out of processes and out of core files.
+
+@section ptrace
+
+@section /proc
+
+@section win32
+
+@section shared libraries
+
+@section Native Conditionals
+
+When GDB is configured and compiled, various macros are defined or left
+undefined, to control compilation when the host and target systems are
+the same.  These macros should be defined (or left undefined) in
+@file{nm-@var{system}.h}.
+
+@table @code
+
+@item ATTACH_DETACH
+If defined, then GDB will include support for the @code{attach} and
+@code{detach} commands.
+
+@item CHILD_PREPARE_TO_STORE
+If the machine stores all registers at once in the child process, then
+define this to ensure that all values are correct.  This usually entails
+a read from the child.
+
+[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
+currently.]
+
+@item FETCH_INFERIOR_REGISTERS
+Define this if the native-dependent code will provide its own routines
+@code{fetch_inferior_registers} and @code{store_inferior_registers} in
+@file{@var{HOST}-nat.c}.  If this symbol is @emph{not} defined, and
+@file{infptrace.c} is included in this configuration, the default
+routines in @file{infptrace.c} are used for these functions.
+
+@item FILES_INFO_HOOK
+(Only defined for Convex.)
+
+@item FP0_REGNUM
+This macro is normally defined to be the number of the first floating
+point register, if the machine has such registers.  As such, it would
+appear only in target-specific code.  However, /proc support uses this
+to decide whether floats are in use on this target.
+
+@item GET_LONGJMP_TARGET
+For most machines, this is a target-dependent parameter.  On the
+DECstation and the Iris, this is a native-dependent parameter, since
+<setjmp.h> is needed to define it.
+
+This macro determines the target PC address that longjmp() will jump to,
+assuming that we have just stopped at a longjmp breakpoint.  It takes a
+CORE_ADDR * as argument, and stores the target PC value through this
+pointer.  It examines the current state of the machine as needed.
+
+@item KERNEL_U_ADDR
+Define this to the address of the @code{u} structure (the ``user
+struct'', also known as the ``u-page'') in kernel virtual memory.  GDB
+needs to know this so that it can subtract this address from absolute
+addresses in the upage, that are obtained via ptrace or from core files.
+On systems that don't need this value, set it to zero.
+
+@item KERNEL_U_ADDR_BSD
+Define this to cause GDB to determine the address of @code{u} at
+runtime, by using Berkeley-style @code{nlist} on the kernel's image in
+the root directory.
+
+@item KERNEL_U_ADDR_HPUX
+Define this to cause GDB to determine the address of @code{u} at
+runtime, by using HP-style @code{nlist} on the kernel's image in the
+root directory.
+
+@item ONE_PROCESS_WRITETEXT
+Define this to be able to, when a breakpoint insertion fails, warn the
+user that another process may be running with the same executable.
+
+@item PROC_NAME_FMT
+Defines the format for the name of a @file{/proc} device.  Should be
+defined in @file{nm.h} @emph{only} in order to override the default
+definition in @file{procfs.c}.
+
+@item PTRACE_FP_BUG
+mach386-xdep.c
+
+@item PTRACE_ARG3_TYPE
+The type of the third argument to the @code{ptrace} system call, if it
+exists and is different from @code{int}.
+
+@item REGISTER_U_ADDR
+Defines the offset of the registers in the ``u area''.
+
+@item SHELL_COMMAND_CONCAT
+If defined, is a string to prefix on the shell command used to start the
+inferior.
+
+@item SHELL_FILE
+If defined, this is the name of the shell to use to run the inferior.
+Defaults to @code{"/bin/sh"}.
+
+@item SOLIB_ADD (filename, from_tty, targ)
+Define this to expand into an expression that will cause the symbols in
+@var{filename} to be added to GDB's symbol table.
+
+@item SOLIB_CREATE_INFERIOR_HOOK
+Define this to expand into any shared-library-relocation code that you
+want to be run just after the child process has been forked.
+
+@item START_INFERIOR_TRAPS_EXPECTED
+When starting an inferior, GDB normally expects to trap twice; once when
+the shell execs, and once when the program itself execs.  If the actual
+number of traps is something other than 2, then define this macro to
+expand into the number expected.
+
+@item SVR4_SHARED_LIBS
+Define this to indicate that SVR4-style shared libraries are in use.
+
+@item USE_PROC_FS
+This determines whether small routines in @file{*-tdep.c}, which
+translate register values between GDB's internal representation and the
+/proc representation, are compiled.
+
+@item U_REGS_OFFSET
+This is the offset of the registers in the upage.  It need only be
+defined if the generic ptrace register access routines in
+@file{infptrace.c} are being used (that is, @file{infptrace.c} is
+configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined).  If
+the default value from @file{infptrace.c} is good enough, leave it
+undefined.
+
+The default value means that u.u_ar0 @emph{points to} the location of
+the registers.  I'm guessing that @code{#define U_REGS_OFFSET 0} means
+that u.u_ar0 @emph{is} the location of the registers.
+
+@item CLEAR_SOLIB
+objfiles.c
+
+@item DEBUG_PTRACE
+Define this to debug ptrace calls.
+
+@end table
+
+
+@node Support Libraries
+
+@chapter Support Libraries
+
+@section BFD
+
+BFD provides support for GDB in several ways:
+
+@table @emph
+
+@item identifying executable and core files
+BFD will identify a variety of file types, including a.out, coff, and
+several variants thereof, as well as several kinds of core files.
+
+@item access to sections of files
+BFD parses the file headers to determine the names, virtual addresses,
+sizes, and file locations of all the various named 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 for length Z.
+
+@item specialized core file support
+BFD provides routines to determine the failing command name stored 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 particular executable
+file.
+
+@item locating the symbol information
+GDB uses an internal interface of BFD to determine where to find the
+symbol information in an executable file or symbol-file.  GDB itself
+handles the reading of symbols, since BFD does not ``understand'' debug
+symbols, but GDB uses BFD's cached information to find the symbols,
+string table, etc.
+
+@end table
+
+@section opcodes
+
+The opcodes library provides GDB's disassembler.  (It's a separate
+library because it's also used in binutils, for @file{objdump}).
+
+@section readline
+
+@section mmalloc
+
+@section libiberty
+
+@section gnu-regex
+
+Regex conditionals.
+
+@table @code
+
+@item C_ALLOCA
+
+@item NFAILURES
+
+@item RE_NREGS
+
+@item SIGN_EXTEND_CHAR
+
+@item SWITCH_ENUM_BUG
+
+@item SYNTAX_TABLE
+
+@item Sword
+
+@item sparc
+
+@end table
+
+@section include
+
+@node Coding
+
+@chapter Coding
+
+This chapter covers topics that are lower-level than the major
+algorithms of GDB.
+
+@section Cleanups
+
+Cleanups are a structured way to deal with things that need to be done
+later.  When your code does something (like @code{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 struct cleanup *@var{old_chain};
+Declare a variable which will hold a cleanup chain handle.
+
+@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
+Make a cleanup which will cause @var{function} to be called with
+@var{arg} (a @code{char *}) later.  The result, @var{old_chain}, is a
+handle that can be passed to @code{do_cleanups} or
+@code{discard_cleanups} later.  Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
+the result from @code{make_cleanup}.
+
+@item do_cleanups (@var{old_chain});
+Perform all cleanups done since @code{make_cleanup} returned
+@var{old_chain}.  E.g.:
+@example
+make_cleanup (a, 0); 
+old = make_cleanup (b, 0); 
+do_cleanups (old);
+@end example
+@noindent
+will call @code{b()} but will not call @code{a()}.  The cleanup that
+calls @code{a()} will remain in the cleanup chain, and will be done
+later unless otherwise discarded.@refill
+
+@item discard_cleanups (@var{old_chain});
+Same as @code{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).
+
+@section Wrapping Output Lines
+
+Output that goes through @code{printf_filtered} or @code{fputs_filtered}
+or @code{fputs_demangled} needs only to have calls to @code{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 @code{wrap_here} is an indentation string which is
+printed @emph{only} if the line breaks there.  This argument is saved
+away and used later.  It must remain valid until the next call to
+@code{wrap_here} or until a newline has been printed through the
+@code{*_filtered} functions.  Don't pass in a local variable and then
+return!
+
+It is usually best to call @code{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 (``@code{printf}'') output.  Symbol reading routines that
+print warnings are a good example.
+
+@section GDB Coding Standards
+
+GDB follows the GNU coding standards, as described in
+@file{etc/standards.texi}.  This file is also available for anonymous
+FTP from GNU archive sites.  GDB takes a strict interpretation of the
+standard; in general, when the GNU standard recommends a practice but
+does not require it, GDB requires it.
+
+GDB follows an additional set of coding standards specific to GDB,
+as described in the following sections.
+
+You can configure with @samp{--enable-build-warnings} to get GCC to
+check on a number of these rules.  GDB sources ought not to engender any
+complaints, unless they are caused by bogus host systems.  (The exact
+set of enabled warnings is currently @samp{-Wall -Wpointer-arith
+-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations}.
+
+@subsection Formatting
+
+The standard GNU recommendations for formatting must be followed
+strictly.
+
+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 line as
+the return type.
+
+In addition, there must be a space between a function or macro name 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
+paren/bracket or before a close paren/bracket.
+
+While additional whitespace is generally helpful for reading, do not 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 had whitespace
+after the semicolon).  Excess whitespace causes difficulties for diff and
+patch.
+
+@subsection Comments
+
+The standard GNU requirements on comments must be followed strictly.
+
+Block comments must appear in the following form, with no `/*'- or
+'*/'-only lines, and no leading `*':
+
+@example @code
+/* Wait for control to return from inferior to debugger.  If inferior
+   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
+   this function actually returns it means the inferior should be left
+   stopped and GDB should read more commands.  */
+@end example
+
+(Note that this format is encouraged by Emacs; tabbing for a multi-line
+comment works correctly, and M-Q fills the block consistently.)
+
+Put a blank line between the block comments preceding function or
+variable definitions, and the definition itself.
+
+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
+line, since either the comment or the code will inevitably get longer
+than will fit, and then somebody will have to move it anyhow.
+
+@subsection C Usage
+
+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
+of evaluation of expressions.
+
+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, mainly
+in symbol reading.  Most of GDB's performance is limited by the target
+interface (whether serial line or system call).
+
+However, use functions with moderation.  A thousand one-line functions
+are just as hard to understand as a single thousand-line function.
+
+@subsection Function Prototypes
+
+Prototypes must be used to @emph{declare} functions but never to
+@emph{define} them.  Prototypes for GDB functions must include both the
+argument type and name, with the name matching that used in the actual
+function definition.
+
+For the sake of compatibility with pre-ANSI compilers, define prototypes
+with the @code{PARAMS} macro:
+
+@example @code
+extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
+                                             char *contents_cache));
+@end example
+
+Note the double parentheses around the parameter types.  This allows an
+arbitrary number of parameters to be described, without freaking out the
+C preprocessor.  When the function has no parameters, it should be
+described like:
+
+@example @code
+extern void noprocess PARAMS ((void));
+@end example
+
+The @code{PARAMS} macro expands to its argument in ANSI C, or to a
+simple @code{()} in traditional C.
+
+All external functions should have a @code{PARAMS} declaration in a
+header file that callers include, except for @code{_initialize_*}
+functions, which must be external so that @file{init.c} construction
+works, but shouldn't be visible to random source files.
+
+All static functions must be declared in a block near the top of the
+source file.
+
+@subsection Clean Design
+
+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
+experience has shown that the more obvious ways caused various kinds of
+trouble.
+
+You can't assume the byte order of anything that comes from a target
+(including @var{value}s, object files, and instructions).  Such things
+must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, or one of
+the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
+
+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
+current @code{target_ops} vector.
+
+You can't assume that the host and target machines are the same machine
+(except in the ``native'' support modules).  In particular, you 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 --
+written from scratch or explicitly donated by their owner, to avoid
+copyright problems.
+
+Insertion of new @code{#ifdef}'s will be frowned upon.  It's much better
+to write the code portably than to conditionalize it for various
+systems.
+
+New @code{#ifdef}'s which test for specific compilers or manufacturers
+or operating systems are unacceptable.  All @code{#ifdef}'s should test
+for features.  The information about which configurations contain which
+features should be segregated into the configuration files.  Experience
+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
+predefined macro for your current system will become worthless over
+time, as new versions of your system come out that behave differently
+with regard to this feature.
+
+Adding code that handles specific architectures, operating systems,
+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
+your configuration, with something like:
+
+@example
+#ifdef	WRANGLE_SIGNALS
+   WRANGLE_SIGNALS (signo);
+#endif
+@end example
+
+In your host, target, or native configuration file, as appropriate,
+define @code{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 the future, if they need a hook in the same place.
+
+If the hook is not defined, the code should do whatever "most" machines
+want.  Using @code{#ifdef}, as above, is the preferred way to do this,
+but sometimes that gets convoluted, in which case use
+
+@example
+#ifndef SPECIAL_FOO_HANDLING
+#define SPECIAL_FOO_HANDLING(pc, sp) (0)
+#endif
+@end example
+
+where the macro is used or in an appropriate header file.
+
+Whether to include a @dfn{small} hook, a hook around the exact pieces of
+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
+found in @code{get_saved_register}.  All machines that GDB 2.8 ran on
+just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
+registers.  Then the SPARC and Pyramid came along, and
+@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
+introduced.  Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
+hook.  The first three are examples of small 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 uses of the small hooks
+with @code{GET_SAVED_REGISTER}, since that would 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 small hooks.
+
+Another way to generalize GDB along a particular interface is with an
+attribute struct.  For example, GDB has been generalized to handle
+multiple kinds of remote interfaces -- not by #ifdef's everywhere, but
+by defining the "target_ops" structure and having a current target (as
+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
+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
+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
+implements the new remote interface.  Other examples of
+attribute-structs are BFD access to multiple kinds of object file
+formats, or GDB's access to multiple source languages.
+
+Please avoid duplicating code.  For example, in GDB 3.x all the code
+interfacing between @code{ptrace} and the rest of GDB was duplicated in
+@file{*-dep.c}, and so changing something was very painful.  In GDB 4.x,
+these have all been consolidated into @file{infptrace.c}.
+@file{infptrace.c} can deal with variations between systems the same way
+any system-independent file would (hooks, #if defined, etc.), and
+machines which are radically different don't need to use infptrace.c at
+all.
+
+
+@node Porting GDB
+
+@chapter Porting GDB
+
+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 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 @var{xyz} (e.g.
+@samp{sun4}), and its full three-part configuration name is
+@code{@var{arch}-@var{xvend}-@var{xos}} (e.g.  @samp{sparc-sun-sunos4}).
+In particular:
+
+In the top level directory, edit @file{config.sub} and add @var{arch},
+@var{xvend}, and @var{xos} to the lists of supported architectures,
+vendors, and operating systems near the bottom of the file.  Also, add
+@var{xyz} as an alias that maps to
+@code{@var{arch}-@var{xvend}-@var{xos}}.  You can test your changes by
+running
+
+@example
+./config.sub @var{xyz}
+@end example
+@noindent
+and
+@example
+./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
+@end example
+@noindent
+which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
+and no error messages.
+
+You need to port BFD, if that hasn't been done already.  Porting BFD is
+beyond the scope of this manual.
+
+To configure GDB itself, edit @file{gdb/configure.host} to recognize
+your system and set @code{gdb_host} to @var{xyz}, and (unless your
+desired target is already available) also edit @file{gdb/configure.tgt},
+setting @code{gdb_target} to something appropriate (for instance,
+@var{xyz}).
+
+Finally, you'll need to specify and define GDB's host-, native-, and
+target-dependent @file{.h} and @file{.c} files used for your
+configuration.
+
+@section Configuring GDB for Release
+
+From the top level directory (containing @file{gdb}, @file{bfd},
+@file{libiberty}, and so on):
+@example
+make -f Makefile.in gdb.tar.gz
+@end example
+
+This will properly configure, clean, rebuild any files that are
+distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
+and will then make a tarfile.  (If the top level directory has already
+been configured, you can just do @code{make gdb.tar.gz} instead.)
+
+This procedure requires:
+@itemize @bullet
+@item symbolic links
+@item @code{makeinfo} (texinfo2 level)
+@item @TeX{}
+@item @code{dvips}
+@item @code{yacc} or @code{bison}
+@end itemize
+@noindent
+@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
+
+@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
+
+@file{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
+them sometime).
+
+For making paper, the only thing this implies is the right generation of
+@file{texinfo.tex} needs to be included in the distribution.
+
+For making info files, however, rather than duplicating the texinfo2
+distribution, generate @file{gdb-all.texinfo} locally, and include the
+files @file{gdb.info*} in the distribution.  Note the plural;
+@code{makeinfo} will split the document into one overall file and five
+or so included files.
+
+@node Hints
+
+@chapter Hints
+
+Check the @file{README} file, it often has useful information that does not
+appear anywhere else in the directory.
+
+@menu
+* Getting Started::		Getting started working on GDB
+* Debugging GDB::		Debugging GDB with itself
+@end menu
+
+@node Getting Started,,, Hints
+
+@section Getting Started
+
+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
+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
+generally to many parts of GDB.
+
+Information about particular functions or data structures are located in
+comments with those functions or data structures.  If you 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 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 comment which is
+actually wrong, be especially sure to report that.
+
+Comments explaining the function of macros defined in host, target, or
+native dependent files can be in several places.  Sometimes they are
+repeated every place the macro is defined.  Sometimes they are where the
+macro is used.  Sometimes there is a header file which supplies a
+default definition of the macro, and the comment is there.  This manual
+also documents all the available macros.
+@c (@pxref{Host Conditionals}, @pxref{Target
+@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
+@c Conditionals})
+
+Start with the header files.  Once you some idea of how GDB's internal
+symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
+will find it much easier to understand the code which uses and creates
+those symbol tables.
+
+You may wish to process the information you are getting somehow, to
+enhance your understanding of it.  Summarize it, translate it to another
+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
+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
+approach.
+
+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
+function with the @code{next} command.  Do not use @code{step} or you
+will quickly get distracted; when the function you are stepping through
+calls another function try only to get a big-picture understanding
+(perhaps using the comment at the beginning of the function being
+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
+one which you are interested in.  You may need to examine the data
+structures generated at each stage, with reference to the comments in
+the header files explaining what the data structures are supposed to
+look like.
+
+Of course, this same technique can be used if you are just reading the
+code, rather than actually stepping through it.  The same general
+principle applies---when the code you are looking at calls something
+else, just try to understand generally what the code being called does,
+rather than worrying about all its details.
+
+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
+single-stepping works.  As a GDB user, you know that the @code{step}
+command invokes single-stepping.  The command is invoked via command
+tables (see @file{command.h}); by convention the function which actually
+performs the command is formed by taking the name of the command and
+adding @samp{_command}, or in the case of an @code{info} subcommand,
+@samp{_info}.  For example, the @code{step} command invokes the
+@code{step_command} function and the @code{info display} command invokes
+@code{display_info}.  When this convention is not followed, you might
+have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on
+itself and set a breakpoint in @code{execute_command}.
+
+If all of the above fail, it may be appropriate to ask for information
+on @code{bug-gdb}.  But @emph{never} post a generic question like ``I 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.
+Suggestions for improving the manual are always welcome, of course.
+
+@node Debugging GDB,,,Hints
+
+@section Debugging GDB with itself
+
+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
+Ultrix 4.2, a program can't be running in one process while it is being
+debugged in another.  Rather than typing the command @code{@w{./gdb
+./gdb}}, which works on Suns and such, you can copy @file{gdb} to
+@file{gdb2} and then type @code{@w{./gdb ./gdb2}}.
+
+When you run GDB in the GDB source directory, it will read a
+@file{.gdbinit} file that sets up some simple things to make debugging
+gdb easier.  The @code{info} command, when executed without a subcommand
+in a GDB being debugged by gdb, will pop you back up to the top level
+gdb.  See @file{.gdbinit} for details.
+
+If you use emacs, you will probably want to do a @code{make TAGS} after
+you configure your distribution; this will put the machine dependent
+routines for your local machine where they will be accessed first by
+@kbd{M-.}
+
+Also, make sure that you've either compiled GDB with your local cc, or
+have run @code{fixincludes} if you are compiling with gcc.
+
+@section Submitting Patches
+
+Thanks for thinking of offering your changes back to the community of
+GDB users.  In general we like to get well designed enhancements.
+Thanks also for checking in advance about the best way to transfer the
+changes.
+
+The GDB maintainers will only install ``cleanly designed'' patches.  You
+may not always agree on what is clean design.
+@c @pxref{Coding Style}, @pxref{Clean Design}.
+
+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 large queue
+with everyone else's patches and bug reports.
+
+The legal issue is that to incorporate substantial changes requires a
+copyright assignment from you and/or your employer, granting ownership
+of the changes to the Free Software Foundation.  You can get the
+standard document for doing this by sending mail to
+@code{gnu@@prep.ai.mit.edu} and asking for it.  I recommend that people
+write in "All programs owned 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 contributed with only one piece of legalese
+pushed through the bureacracy and filed with the FSF.  I can't start
+merging changes until this paperwork is received by the FSF (their
+rules, which I follow since I maintain it for them).
+
+Technically, the easiest way to receive changes is to receive 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 for a single feature, plus ChangeLog entries for each
+directory where files were modified, and diffs for any changes needed
+to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi).  If there
+are a lot of changes for a single feature, they can be split down
+into multiple messages.
+
+In this way, if I read and like the feature, I can add it to the
+sources with a single patch command, do some testing, and check it in.
+If you leave out the ChangeLog, I have to write one.  If you leave
+out the doc, I have to puzzle out what needs documenting.  Etc.
+
+The reason to send each change in a separate message is that I will
+not install some of the changes.  They'll be returned to you with
+questions or comments.  If I'm doing my job, my message 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 is so
+that other changes (which I @emph{am} willing to accept) can be installed
+while one or more changes are being reworked.  If multiple features
+are sent in a single message, I tend to not put in the effort to sort
+out the acceptable changes from the unacceptable, so none of the
+features get installed until all are acceptable.
+
+If this sounds painful or authoritarian, well, it is.  But I get a lot
+of bug reports and a lot of patches, and most of them don't get
+installed because I don't have the time to finish the job that the bug
+reporter or the contributor could have done.  Patches that arrive
+complete, working, and well designed, tend to get installed on the day
+they arrive.  The others go into a queue and get installed if and when
+I scan back over the queue -- which can literally take months
+sometimes.  It's in both our interests to make patch installation easy
+-- you get your changes installed, and I make some forward progress on
+GDB in a normal 12-hour day (instead of them having to wait until I
+have a 14-hour or 16-hour day to spend cleaning up patches before I
+can install them).
+
+Please send patches directly to the GDB maintainers at
+@code{gdb-patches@@cygnus.com}.
+
+@section Obsolete Conditionals
+
+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
+should be removed as those parts of the debugger are otherwise touched.
+
+@table @code
+
+@item STACK_END_ADDR
+This macro used to define where the end of the stack appeared, for use
+in interpreting core file formats that don't record this address in the
+core file itself.  This information is now configured in BFD, and GDB
+gets the info portably from there.  The values in GDB's configuration
+files should be moved into BFD configuration files (if needed there),
+and deleted from all of GDB's config files.
+
+Any @file{@var{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!
+
+@item PYRAMID_CONTROL_FRAME_DEBUGGING
+pyr-xdep.c
+@item PYRAMID_CORE
+pyr-xdep.c
+@item PYRAMID_PTRACE
+pyr-xdep.c
+
+@item REG_STACK_SEGMENT
+exec.c
+
+@end table
+
+
+@contents
+@bye