NetBSD/gnu/dist/toolchain/gdb/doc/gdbint.info-3

This is gdbint.info, produced by Makeinfo version 3.12f from
./gdbint.texinfo.

START-INFO-DIR-ENTRY
* Gdb-Internals: (gdbint).	The GNU debugger's internals.
END-INFO-DIR-ENTRY

   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.

   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).


File: gdbint.info,  Node: Support Libraries,  Next: Coding,  Prev: Native Debugging,  Up: Top

Support Libraries
*****************

BFD
===

   BFD provides support for GDB in several ways:

_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.

_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.

_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.

_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.

opcodes
=======

   The opcodes library provides GDB's disassembler.  (It's a separate
library because it's also used in binutils, for `objdump').

readline
========

mmalloc
=======

libiberty
=========

gnu-regex
=========

   Regex conditionals.

`C_ALLOCA'

`NFAILURES'

`RE_NREGS'

`SIGN_EXTEND_CHAR'

`SWITCH_ENUM_BUG'

`SYNTAX_TABLE'

`Sword'

`sparc'
include
=======


File: gdbint.info,  Node: Coding,  Next: Porting GDB,  Prev: Support Libraries,  Up: Top

Coding
******

   This chapter covers topics that are lower-level than the major
algorithms of GDB.

Cleanups
========

   Cleanups are a structured way to deal with things that need to be
done later.  When your code does something (like `malloc' some memory,
or open a file) that needs to be undone later (e.g. free the memory or
close the file), it can make a cleanup.  The cleanup will be done at
some future point: when the command is finished, when an error occurs,
or when your code decides it's time to do cleanups.

   You can also discard cleanups, that is, throw them away without doing
what they say.  This is only done if you ask that it be done.

   Syntax:

`struct cleanup *OLD_CHAIN;'
     Declare a variable which will hold a cleanup chain handle.

`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
     Make a cleanup which will cause FUNCTION to be called with ARG (a
     `char *') later.  The result, OLD_CHAIN, is a handle that can be
     passed to `do_cleanups' or `discard_cleanups' later.  Unless you
     are going to call `do_cleanups' or `discard_cleanups' yourself,
     you can ignore the result from `make_cleanup'.

`do_cleanups (OLD_CHAIN);'
     Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
     E.g.:
          make_cleanup (a, 0);
          old = make_cleanup (b, 0);
          do_cleanups (old);

     will call `b()' but will not call `a()'.  The cleanup that calls
     `a()' will remain in the cleanup chain, and will be done later
     unless otherwise discarded.

`discard_cleanups (OLD_CHAIN);'
     Same as `do_cleanups' except that it just removes the cleanups from
     the chain and does not call the specified functions.

   Some functions, e.g. `fputs_filtered()' or `error()', specify that
they "should not be called when cleanups are not in place".  This means
that any actions you need to reverse in the case of an error or
interruption must be on the cleanup chain before you call these
functions, since they might never return to your code (they `longjmp'
instead).

Wrapping Output Lines
=====================

   Output that goes through `printf_filtered' or `fputs_filtered' or
`fputs_demangled' needs only to have calls to `wrap_here' added in
places that would be good breaking points.  The utility routines will
take care of actually wrapping if the line width is exceeded.

   The argument to `wrap_here' is an indentation string which is
printed _only_ if the line breaks there.  This argument is saved away
and used later.  It must remain valid until the next call to
`wrap_here' or until a newline has been printed through the
`*_filtered' functions.  Don't pass in a local variable and then return!

   It is usually best to call `wrap_here()' after printing a comma or
space.  If you call it before printing a space, make sure that your
indentation properly accounts for the leading space that will print if
the line wraps there.

   Any function or set of functions that produce filtered output must
finish by printing a newline, to flush the wrap buffer, before switching
to unfiltered ("`printf'") output.  Symbol reading routines that print
warnings are a good example.

GDB Coding Standards
====================

   GDB follows the GNU coding standards, as described in
`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 `--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 `-Wall -Wpointer-arith
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.

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.

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 `*':

     /* 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.  */

   (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.

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.

Function Prototypes
-------------------

   Prototypes must be used to _declare_ functions, and may be used to
_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.

   All external functions should have a declaration in a header file
that callers include, except for `_initialize_*' functions, which must
be external so that `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.

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 VALUEs, object files, and instructions).  Such things must
be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
routines defined in `bfd.h', such as `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 `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 `#ifdef''s will be frowned upon.  It's much better
to write the code portably than to conditionalize it for various
systems.

   New `#ifdef''s which test for specific compilers or manufacturers or
operating systems are unacceptable.  All `#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:

     #ifdef	WRANGLE_SIGNALS
        WRANGLE_SIGNALS (signo);
     #endif

   In your host, target, or native configuration file, as appropriate,
define `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 `#ifdef', as above, is the preferred way to do
this, but sometimes that gets convoluted, in which case use

     #ifndef SPECIAL_FOO_HANDLING
     #define SPECIAL_FOO_HANDLING(pc, sp) (0)
     #endif

   where the macro is used or in an appropriate header file.

   Whether to include a "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 `get_saved_register'.  All machines that GDB 2.8 ran on just
needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
`REGISTER_IN_WINDOW_P' were introduced.  Then the 29k and 88k required
the `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 `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 `ptrace' and the rest of GDB was duplicated in
`*-dep.c', and so changing something was very painful.  In GDB 4.x,
these have all been consolidated into `infptrace.c'.  `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.


File: gdbint.info,  Node: Porting GDB,  Next: Testsuite,  Prev: Coding,  Up: Top

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
XYZ (e.g.  `sun4'), and its full three-part configuration name is
`ARCH-XVEND-XOS' (e.g.  `sparc-sun-sunos4').  In particular:

   In the top level directory, edit `config.sub' and add ARCH, XVEND,
and XOS to the lists of supported architectures, vendors, and operating
systems near the bottom of the file.  Also, add XYZ as an alias that
maps to `ARCH-XVEND-XOS'.  You can test your changes by running

     ./config.sub XYZ

and
     ./config.sub `ARCH-XVEND-XOS'

which should both respond with `ARCH-XVEND-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 `gdb/configure.host' to recognize your
system and set `gdb_host' to XYZ, and (unless your desired target is
already available) also edit `gdb/configure.tgt', setting `gdb_target'
to something appropriate (for instance, XYZ).

   Finally, you'll need to specify and define GDB's host-, native-, and
target-dependent `.h' and `.c' files used for your configuration.

Configuring GDB for Release
===========================

   From the top level directory (containing `gdb', `bfd', `libiberty',
and so on):
     make -f Makefile.in gdb.tar.gz

   This will properly configure, clean, rebuild any files that are
distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will
then make a tarfile.  (If the top level directory has already been
configured, you can just do `make gdb.tar.gz' instead.)

   This procedure requires:
   * symbolic links

   * `makeinfo' (texinfo2 level)

   * TeX

   * `dvips'

   * `yacc' or `bison'

... and the usual slew of utilities (`sed', `tar', etc.).

TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
---------------------------------------------

   `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 `texinfo.tex' needs to be included in the distribution.

   For making info files, however, rather than duplicating the texinfo2
distribution, generate `gdb-all.texinfo' locally, and include the files
`gdb.info*' in the distribution.  Note the plural; `makeinfo' will
split the document into one overall file and five or so included files.


File: gdbint.info,  Node: Testsuite,  Next: Hints,  Prev: Porting GDB,  Up: Top

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.

Using the Testsuite
===================

   To run the testsuite, simply go to the GDB object directory (or to
the testsuite's objdir) and type `make check'.  This just sets up some
environment variables and invokes DejaGNU's `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:
                     === 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
   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.

Testsuite Organization
======================

   The testsuite is entirely contained in `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
`testsuite/lib/gdb.exp' contains common utility procs useful for all
GDB tests, while the directory `testsuite/config' contains
configuration-specific files, typically used for special-purpose
definitions of procs like `gdb_load' and `gdb_start'.

   The tests themselves are to be found in `testsuite/gdb.*' and
subdirectories of those.  The names of the test files must always end
with `.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.

`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).

`gdb.LANG'
     Language-specific tests for all languages besides C.  Examples are
     `gdb.c++' and `gdb.java'.

`gdb.PLATFORM'
     Non-portable tests.  The tests are specific to a specific
     configuration (host or target), such as HP-UX or eCos.  Example is
     `gdb.hp', for HP-UX.

`gdb.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.

`gdb.SUBSYSTEM'
     Tests that exercise a specific GDB subsystem in more depth.  For
     instance, `gdb.disasm' exercises various disassemblers, while
     `gdb.stabs' tests pathways through the stabs symbol reader.

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 `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, `gdb.base/exprs.exp' defines a `test_expr' that calls
`gdb_test' multiple times.

   Only use `send_gdb' and `gdb_expect' when absolutely necessary, such
as when GDB has several valid responses to a command.

   The source language programs do _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.


File: gdbint.info,  Node: Hints,  Prev: Testsuite,  Up: Top

Hints
*****

   Check the `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


File: gdbint.info,  Node: Getting Started,  Up: Hints

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.

   Start with the header files.  Once you have some idea of how GDB's
internal symbol tables are stored (see `symtab.h', `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 `next' command.  Do not use `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 `step' command
invokes single-stepping.  The command is invoked via command tables
(see `command.h'); by convention the function which actually performs
the command is formed by taking the name of the command and adding
`_command', or in the case of an `info' subcommand, `_info'.  For
example, the `step' command invokes the `step_command' function and the
`info display' command invokes `display_info'.  When this convention is
not followed, you might have to use `grep' or `M-x tags-search' in
emacs, or run GDB on itself and set a breakpoint in `execute_command'.

   If all of the above fail, it may be appropriate to ask for
information on `bug-gdb'.  But _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.


File: gdbint.info,  Node: Debugging GDB,  Up: Hints

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 `./gdb ./gdb',
which works on Suns and such, you can copy `gdb' to `gdb2' and then
type `./gdb ./gdb2'.

   When you run GDB in the GDB source directory, it will read a
`.gdbinit' file that sets up some simple things to make debugging gdb
easier.  The `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 `.gdbinit' for details.

   If you use emacs, you will probably want to do a `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
`M-.'

   Also, make sure that you've either compiled GDB with your local cc,
or have run `fixincludes' if you are compiling with gcc.

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 `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
`gdb-patches@sourceware.cygnus.com'.

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.

`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 `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!

`PYRAMID_CONTROL_FRAME_DEBUGGING'
     pyr-xdep.c

`PYRAMID_CORE'
     pyr-xdep.c

`PYRAMID_PTRACE'
     pyr-xdep.c

`REG_STACK_SEGMENT'
     exec.c