* Support Libraries::
* Coding::
* Porting GDB::
+* Testsuite::
* Hints::
@end menu
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
+header. @code{find_sym_fns} then uses this identification to locate a
set of symbol-reading functions.
Symbol reading modules identify themselves to GDB by calling
@code{memcpy} and @code{memset}. Define this to avoid conflicts between
the native include files and the declarations in @file{defs.h}.
+@item NO_STD_REGS
+This macro is deprecated.
+
@item NO_SYS_FILE
Define this if your system does not have a @code{<sys/file.h>}.
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)}.
+If a raw machine instruction 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}. This is only used for
+addresses of instructions, and even then not in all contexts.
+
+For example, the two low-order bits of the PC on the Hewlett-Packard PA
+2.0 architecture contain the privilege level of the corresponding
+instruction. Since instructions must always be aligned on four-byte
+boundaries, the processor masks out these bits to generate the actual
+address of the instruction. ADDR_BITS_REMOVE should filter out these
+bits 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
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).
+When @var{EXTRACT_STRUCT_VALUE_ADDRESS_P} this is used to 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 EXTRACT_STRUCT_VALUE_ADDRESS_P
+Predicate for @var{EXTRACT_STRUCT_VALUE_ADDRESS}.
@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.
+If the virtual frame pointer is kept in a register, then define this
+macro to be the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_READ_FP} and
+@code{TARGET_WRITE_FP} are not defined.
-@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 FRAMELESS_FUNCTION_INVOCATION(fi)
+Define this to an expression that returns 1 if the function invocation
+represented by @var{fi} does not have a stack frame associated with it.
+Otherwise return 0.
@item FRAME_ARGS_ADDRESS_CORRECT
stack.c
@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_NUM_ARGS (fi)
+For the frame described by @var{fi} return the number of arguments that
+are being passed. If the number of arguments is not known, return
+@code{-1}.
@item FRAME_SAVED_PC(frame)
Given @var{frame}, return the pc saved there. That is, the return
@code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently
only defined for the Delta 68.)
+@item GDB_MULTI_ARCH
+If defined and non-zero, enables suport for multiple architectures
+within GDB.
+
+The support can be enabled at two levels. At level one, only
+definitions for previously undefined macros are provided; at level two,
+a multi-arch definition of all architecture dependant macros will be
+defined.
+
@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
@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.
+be the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_READ_PC} and
+@code{TARGET_WRITE_PC} are not defined.
@item NPC_REGNUM
The number of the ``next program counter'' register, if defined.
frame.
@item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)
-Define this to push arguments onto the stack for inferior function call.
+Define this to push arguments onto the stack for inferior function
+call. Return the updated stack pointer value.
@item PUSH_DUMMY_FRAME
Used in @samp{call_function_by_hand} to create an artificial stack frame.
Define this to return 1 if the given type will be passed by pointer
rather than directly.
+@item SAVE_DUMMY_FRAME_TOS (sp)
+Used in @samp{call_function_by_hand} to notify the target dependent code
+of the top-of-stack value that will be passed to the the inferior code.
+This is the value of the @var{SP} after both the dummy frame and space
+for parameters/results have been allocated on the stack.
+
@item SDB_REG_TO_REGNUM
Define this to convert sdb register numbers into GDB regnums. If not
defined, no conversion will be done.
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.
+If the stack-pointer is kept in a register, then define this macro to be
+the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_WRITE_SP} and
+@code{TARGET_WRITE_SP} are not defined.
@item STAB_REG_TO_REGNUM
Define this to convert stab register numbers (as gotten from `r'
@item TARGET_COMPLEX_BIT
Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
+At present this macro is not used.
+
@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}.
+At present this macro is not used.
+
@item TARGET_FLOAT_BIT
Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
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
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
@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
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}.
+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
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).
+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.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
+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, I have to write one. If you leave
-out the doc, I have to puzzle out what needs documenting. Etc.
+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 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
+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 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
+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 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).
+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@@cygnus.com}.
+@code{gdb-patches@@sourceware.cygnus.com}.
@section Obsolete Conditionals
projects / binutils-gdb.git / blobdiff