+@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 PREPARE_TO_PROCEED @var{select_it}
+This (ugly) macro allows a native configuration to customize the way the
+@code{proceed} function in @file{infrun.c} deals with switching between
+threads.
+
+In a multi-threaded task we may select another thread and then continue
+or step. But if the old thread was stopped at a breakpoint, it will
+immediately cause another breakpoint stop without any execution (i.e. it
+will report a breakpoint hit incorrectly). So GDB must step over it
+first.
+
+If defined, @code{PREPARE_TO_PROCEED} should check the current thread
+against the thread that reported the most recent event. If a step-over
+is required, it returns TRUE. If @var{select_it} is non-zero, it should
+reselect the old thread.
+
+@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.
+
+Don't put debugging printfs in the code.
+
+@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 Testsuite
+
+@chapter Testsuite
+
+The testsuite is an important component of the GDB package. While it is
+always worthwhile to encourage user testing, in practice this is rarely
+sufficient; users typically use only a small subset of the available
+commands, and it has proven all too common for a change to cause a
+significant regression that went unnoticed for some time.
+
+The GDB testsuite uses the DejaGNU testing framework. DejaGNU is built
+using tcl and expect. The tests themselves are calls to various tcl
+procs; the framework runs all the procs and summarizes the passes and
+fails.
+
+@section Using the Testsuite
+
+To run the testsuite, simply go to the GDB object directory (or to the
+testsuite's objdir) and type @code{make check}. This just sets up some
+environment variables and invokes DejaGNU's @code{runtest} script. While
+the testsuite is running, you'll get mentions of which test file is in use,
+and a mention of any unexpected passes or fails. When the testsuite is
+finished, you'll get a summary that looks like this:
+@example
+ === gdb Summary ===
+
+# of expected passes 6016
+# of unexpected failures 58
+# of unexpected successes 5
+# of expected failures 183
+# of unresolved testcases 3
+# of untested testcases 5
+@end example
+The ideal test run consists of expected passes only; however, reality
+conspires to keep us from this ideal. Unexpected failures indicate
+real problems, whether in GDB or in the testsuite. Expected failures
+are still failures, but ones which have been decided are too hard to
+deal with at the time; for instance, a test case might work everywhere
+except on AIX, and there is no prospect of the AIX case being fixed in
+the near future. Expected failures should not be added lightly, since
+you may be masking serious bugs in GDB. Unexpected successes are expected
+fails that are passing for some reason, while unresolved and untested
+cases often indicate some minor catastrophe, such as the compiler being
+unable to deal with a test program.
+
+When making any significant change to GDB, you should run the testsuite
+before and after the change, to confirm that there are no regressions.
+Note that truly complete testing would require that you run the
+testsuite with all supported configurations and a variety of compilers;
+however this is more than really necessary. In many cases testing with
+a single configuration is sufficient. Other useful options are to test
+one big-endian (Sparc) and one little-endian (x86) host, a cross config
+with a builtin simulator (powerpc-eabi, mips-elf), or a 64-bit host
+(Alpha).
+
+If you add new functionality to GDB, please consider adding tests for it
+as well; this way future GDB hackers can detect and fix their changes
+that break the functionality you added. Similarly, if you fix a bug
+that was not previously reported as a test failure, please add a test
+case for it. Some cases are extremely difficult to test, such as code
+that handles host OS failures or bugs in particular versions of
+compilers, and it's OK not to try to write tests for all of those.
+
+@section Testsuite Organization
+
+The testsuite is entirely contained in @file{gdb/testsuite}. While the
+testsuite includes some makefiles and configury, these are very minimal,
+and used for little besides cleaning up, since the tests themselves
+handle the compilation of the programs that GDB will run. The file
+@file{testsuite/lib/gdb.exp} contains common utility procs useful for
+all GDB tests, while the directory @file{testsuite/config} contains
+configuration-specific files, typically used for special-purpose
+definitions of procs like @code{gdb_load} and @code{gdb_start}.
+
+The tests themselves are to be found in @file{testsuite/gdb.*} and
+subdirectories of those. The names of the test files must always end
+with @file{.exp}. DejaGNU collects the test files by wildcarding
+in the test directories, so both subdirectories and individual files
+get chosen and run in alphabetical order.
+
+The following table lists the main types of subdirectories and what they
+are for. Since DejaGNU finds test files no matter where they are
+located, and since each test file sets up its own compilation and
+execution environment, this organization is simply for convenience and
+intelligibility.
+
+@table @code
+
+@item gdb.base
+
+This is the base testsuite. The tests in it should apply to all
+configurations of GDB (but generic native-only tests may live here).
+The test programs should be in the subset of C that is valid K&R,
+ANSI/ISO, and C++ (ifdefs are allowed if necessary, for instance
+for prototypes).
+
+@item gdb.@var{lang}
+
+Language-specific tests for all languages besides C. Examples are
+@file{gdb.c++} and @file{gdb.java}.
+
+@item gdb.@var{platform}
+
+Non-portable tests. The tests are specific to a specific configuration
+(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
+HP-UX.
+
+@item gdb.@var{compiler}
+
+Tests specific to a particular compiler. As of this writing (June
+1999), there aren't currently any groups of tests in this category that
+couldn't just as sensibly be made platform-specific, but one could
+imagine a gdb.gcc, for tests of GDB's handling of GCC extensions.
+
+@item gdb.@var{subsystem}
+
+Tests that exercise a specific GDB subsystem in more depth. For
+instance, @file{gdb.disasm} exercises various disassemblers, while
+@file{gdb.stabs} tests pathways through the stabs symbol reader.
+
+@end table
+
+@section Writing Tests
+
+In many areas, the GDB tests are already quite comprehensive; you
+should be able to copy existing tests to handle new cases.
+
+You should try to use @code{gdb_test} whenever possible, since it
+includes cases to handle all the unexpected errors that might happen.
+However, it doesn't cost anything to add new test procedures; for
+instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
+calls @code{gdb_test} multiple times.
+
+Only use @code{send_gdb} and @code{gdb_expect} when absolutely
+necessary, such as when GDB has several valid responses to a command.
+
+The source language programs do @emph{not} need to be in a consistent
+style. Since GDB is used to debug programs written in many different
+styles, it's worth having a mix of styles in the testsuite; for
+instance, some GDB bugs involving the display of source lines would
+never manifest themselves if the programs used GNU coding style
+uniformly.
+
+@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.
+This manual summarizes what we believe to be clean design for GDB.
+
+If the maintainers don't have time to put the patch in when it 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 documents for doing this by sending mail to @code{gnu@@gnu.org}
+and asking for it. We 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. We can't start merging changes until
+this paperwork is received by the FSF (their rules, which we follow
+since we 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.texinfo or gdb/doc/gdbint.texinfo). If there are a lot of
+changes for a single feature, they can be split down into multiple
+messages.
+
+In this way, if we read and like the feature, we can add it to the
+sources with a single patch command, do some testing, and check it in.
+If you leave out the ChangeLog, we have to write one. If you leave
+out the doc, we have to puzzle out what needs documenting. Etc.
+
+The reason to send each change in a separate message is that we will not
+install some of the changes. They'll be returned to you with questions
+or comments. If we're doing our job correctly, the message back to you
+will say what you have to fix in order to make the change acceptable.
+The reason to have separate messages for separate features is so that
+the acceptable changes can be installed while one or more changes are
+being reworked. If multiple features are sent in a single message, we
+tend to not put in the effort to sort out the acceptable changes from
+the unacceptable, so none of the features get installed until all are
+acceptable.
+
+If this sounds painful or authoritarian, well, it is. But we get a lot
+of bug reports and a lot of patches, and many of them don't get
+installed because we don't have the time to finish the job that the bug
+reporter or the contributor could have done. Patches that arrive
+complete, working, and well designed, tend to get installed on the day
+they arrive. The others go into a queue and get installed as time
+permits, which, since the maintainers have many demands to meet, may not
+be for quite some time.
+
+Please send patches directly to the GDB maintainers at
+@code{gdb-patches@@sourceware.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
+
+