@ifinfo
This file documents the internals of the GNU debugger GDB.
-Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+Copyright 1990-1999 Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1990-1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
* 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
The @file{a.out} format is so simple that it doesn't have any reserved
place for debugging information. (Hey, the original Unix hackers used
@file{adb}, which is a machine-language debugger.) The only debugging
-format for @file{a.out} is stabs, which for this format are encoded as
-symbols with distinctive properties.
+format for @file{a.out} is stabs, which is encoded as a set of normal
+symbols with distinctive attributes.
+
+The basic @file{a.out} reader is in @file{dbxread.c}.
@subsection COFF
instance, it was not possible to represent code that came from an
included file.
+The COFF reader is in @file{coffread.c}.
+
@subsection ECOFF
+ECOFF is an extended COFF originally introduced for Mips and Alpha
+workstations.
+
+The basic ECOFF reader is in @file{mipsread.c}.
+
@subsection XCOFF
The IBM RS/6000 running AIX uses an object file format called XCOFF.
@samp{.debug} section (rather than the string table). For more
information, see @xref{Top,,,stabs,The Stabs Debugging Format}.
-The shared library scheme has a nice clean interface for figuring out
-what shared libraries are in use, but the catch is that everything which
+The shared library scheme has a clean interface for figuring out what
+shared libraries are in use, but the catch is that everything which
refers to addresses (symbol tables and breakpoints at least) needs to be
relocated for both shared libraries and the main executable. At least
using the standard mechanism this can only be done once the program has
@subsection PE
Windows 95 and NT use the PE (Portable Executable) format for their
-executables. PE is basically COFF with an additional header or two.
+executables. PE is basically COFF with additional headers.
+
+While BFD includes special PE support, GDB needs only the basic
+COFF reader.
@subsection ELF
to COFF in being organized into a number of sections, but it removes
many of COFF's limitations.
+The basic ELF reader is in @file{elfread.c}.
+
@subsection SOM
+SOM is HP's object file and debug format (not to be confused with IBM's
+SOM, which is a cross-language ABI).
+
+The SOM reader is in @file{hpread.c}.
+
+@subsection Other File Formats
+
+Other file formats that have been supported by GDB include Netware
+Loadable Modules (@file{nlmread.c}.
+
@section Debugging File Formats
+This section describes characteristics of debugging information that
+are independent of the object file format.
+
@subsection stabs
+@code{stabs} started out as special symbols within the @code{a.out}
+format. Since then, it has been encapsulated into other file
+formats, such as COFF and ELF.
+
+While @file{dbxread.c} does some of the basic stab processing,
+including for encapsulated versions, @file{stabsread.c} does
+the real work.
+
@subsection COFF
+The basic COFF definition includes debugging information. The level
+of support is minimal and non-extensible, and is not often used.
+
+@subsection Mips debug (Third Eye)
+
+ECOFF includes a definition of a special debug format.
+
+The file @file{mdebugread.c} implements reading for this format.
+
@subsection DWARF 1
+DWARF 1 is a debugging format that was originally designed to be
+used with ELF in SVR4 systems.
+
+@c CHILL_PRODUCER
+@c GCC_PRODUCER
+@c GPLUS_PRODUCER
+@c LCC_PRODUCER
+@c If defined, these are the producer strings in a DWARF 1 file. All of
+@c these have reasonable defaults already.
+
+The DWARF 1 reader is in @file{dwarfread.c}.
+
@subsection DWARF 2
+DWARF 2 is an improved but incompatible version of DWARF 1.
+
+The DWARF 2 reader is in @file{dwarf2read.c}.
+
@subsection SOM
+Like COFF, the SOM definition includes debugging information.
+
@section Adding a New Symbol Reader to GDB
If you are using an existing object file format (a.out, COFF, ELF, etc),
@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>}.
bfd_seek). FIXME, should be replaced by SEEK_SET instead, which is the
POSIX equivalent.
-@item MAINTENANCE_CMDS
-If the value of this is 1, then a number of optional maintenance
-commands are compiled in.
-
@item MALLOC_INCOMPATIBLE
Define this if the system's prototype for @code{malloc} differs from the
@sc{ANSI} definition.
set correctly if compiling with GCC. This will almost never need to be
defined.
+@item USE_GENERIC_DUMMY_FRAMES
+Define this to 1 if the target is using the generic inferior function
+call code. See @code{blockframe.c} for more information.
+
@item USE_MMALLOC
GDB will use the @code{mmalloc} library for memory allocation for symbol
reading if this symbol is defined. Be careful defining it since there
which registers are which; however, it is critical that they do match up
accurately. The only way to make this work is to get accurate
information about the order that the compiler uses, and to reflect that
-in the @code{REGISTER_NAMES} and related macros.
+in the @code{REGISTER_NAME} and related macros.
GDB can handle big-endian, little-endian, and bi-endian architectures.
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
pattern could be an invalid instruction. The breakpoint must be no
longer than the shortest instruction of the architecture.
+@var{BREAKPOINT} has been deprecated in favour of
+@var{BREAKPOINT_FROM_PC}.
+
@item BIG_BREAKPOINT
@item LITTLE_BREAKPOINT
Similar to BREAKPOINT, but used for bi-endian targets.
+@var{BIG_BREAKPOINT} and @var{LITTLE_BREAKPOINT} have been deprecated in
+favour of @var{BREAKPOINT_FROM_PC}.
+
+@item REMOTE_BREAKPOINT
+@item LITTLE_REMOTE_BREAKPOINT
+@item BIG_REMOTE_BREAKPOINT
+Similar to BREAKPOINT, but used for remote targets.
+
+@var{BIG_REMOTE_BREAKPOINT} and @var{LITTLE_REMOTE_BREAKPOINT} have been
+deprecated in favour of @var{BREAKPOINT_FROM_PC}.
+
+@item BREAKPOINT_FROM_PC (pcptr, lenptr)
+
+Use the program counter to determine the contents and size of a
+breakpoint instruction. It returns a pointer to a string of bytes that
+encode a breakpoint instruction, stores the length of the string to
+*lenptr, and adjusts pc (if necessary) to point to the actual memory
+location where the breakpoint should be inserted.
+
+Although it is common to use a trap instruction for a breakpoint, it's
+not required; for instance, the bit pattern could be an invalid
+instruction. The breakpoint must be no longer than the shortest
+instruction of the architecture.
+
+Replaces all the other @var{BREAKPOINT} macros.
+
+@item CALL_DUMMY_P
+A C expresson that is non-zero when the target suports inferior function
+calls.
+
+@item CALL_DUMMY_WORDS
+Pointer to an array of @var{LONGEST} words of data containing
+host-byte-ordered @var{REGISTER_BYTES} sized values that partially
+specify the sequence of instructions needed for an inferior function
+call.
+
+Should be deprecated in favour of a macro that uses target-byte-ordered
+data.
+
+@item SIZEOF_CALL_DUMMY_WORDS
+The size of @var{CALL_DUMMY_WORDS}. When @var{CALL_DUMMY_P} this must
+return a positive value. See also @var{CALL_DUMMY_LENGTH}.
+
@item CALL_DUMMY
-valops.c
+A static initializer for @var{CALL_DUMMY_WORDS}. Deprecated.
+
@item CALL_DUMMY_LOCATION
inferior.h
+
@item CALL_DUMMY_STACK_ADJUST
-valops.c
+Stack adjustment needed when performing an inferior function call.
+
+Should be deprecated in favor of something like @var{STACK_ALIGN}.
+
+@item CALL_DUMMY_STACK_ADJUST_P
+Predicate for use of @var{CALL_DUMMY_STACK_ADJUST}.
+
+Should be deprecated in favor of something like @var{STACK_ALIGN}.
@item CANNOT_FETCH_REGISTER (regno)
A C expression that should be nonzero if @var{regno} cannot be fetched
status words, and other special registers. If this is not defined, GDB
will assume that all registers may be written.
-@item CHILL_PRODUCER
-@item GCC_PRODUCER
-@item GPLUS_PRODUCER
-@item LCC_PRODUCER
-If defined, these are the producer strings in a DWARF 1 file. All of
-these have reasonable defaults already.
-
@item DO_DEFERRED_STORES
@item CLEAR_DEFERRED_STORES
Define this to execute any deferred stores of registers into the inferior,
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 EXTRA_FRAME_INFO
-If defined, this must be a list of slots that may be inserted into the
-@code{frame_info} structure defined in @code{frame.h}.
+@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
Presently only defined for HP PA.
@item FRAME_CHAIN_VALID(chain,thisframe)
+
Define this to be an expression that returns zero if the given frame is
-an outermost frame, with no caller, and nonzero otherwise. The default
-definition is nonzero if the chain pointer is nonzero and given frame's
-PC is not inside the startup file (such as @file{crt0.o}). The
-alternate default definition (which is used if
-FRAME_CHAIN_VALID_ALTERNATE is defined) is nonzero if the chain pointer
-is nonzero and the given frame's PC is not in @code{main()} or a known
+an outermost frame, with no caller, and nonzero otherwise. Three common
+definitions are available. @code{default_frame_chain_valid} (the
+default) is nonzero if the chain pointer is nonzero and given frame's PC
+is not inside the startup file (such as @file{crt0.o}).
+@code{alternate_frame_chain_valid} is nonzero if the chain pointer is
+nonzero and the given frame's PC is not in @code{main()} or a known
entry point function (such as @code{_start()}).
-@item FRAME_CHAIN_VALID_ALTERNATE
-Define this in order to use the alternate default definition of
-@code{FRAME_CHAIN_VALID}.
+@item FRAME_INIT_SAVED_REGS(frame)
+See @file{frame.h}. Determines the address of all registers in the
+current stack frame storing each in @code{frame->saved_regs}. Space for
+@code{frame->saved_regs} shall be allocated by
+@code{FRAME_INIT_SAVED_REGS} using either
+@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
-@item FRAME_FIND_SAVED_REGS
-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 GET_SAVED_REGISTER
Define this if you need to supply your own definition for the function
-@code{get_saved_register}. Currently this is only done for the a29k.
+@code{get_saved_register}.
@item HAVE_REGISTER_WINDOWS
Define this if the target has register windows.
@item IEEE_FLOAT
Define this if the target system uses IEEE-format floating point numbers.
-@item INIT_EXTRA_FRAME_INFO (fromleaf, fci)
-If defined, this should be a C expression or statement that fills in the
-@code{EXTRA_FRAME_INFO} slots of the given frame @var{fci}.
+@item INIT_EXTRA_FRAME_INFO (fromleaf, frame)
+If additional information about the frame is required this should be
+stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
+is allocated using @code{frame_obstack_alloc}.
@item INIT_FRAME_PC (fromleaf, prev)
This is a C statement that sets the pc of the frame pointed to by
@var{prev}. [By default...]
-@item INNER_THAN
-Define this to be either @code{<} if the target's stack grows downward
-in memory, or @code{>} is the stack grows upwards.
+@item INNER_THAN (lhs,rhs)
+Returns non-zero if stack address @var{lhs} is inner than (nearer to the
+stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
+the target's stack grows downward in memory, or @code{lhs > rsh} if the
+stack grows upward.
@item IN_SIGTRAMP (pc, name)
Define this to return true if the given @var{pc} and/or @var{name}
constant, the macro expansion will typically just ignore the supplied
@var{pc}.
-@item IN_SOLIB_TRAMPOLINE pc name
+@item IN_SOLIB_CALL_TRAMPOLINE pc name
Define this to evaluate to nonzero if the program is stopped in the
trampoline that connects to a shared library.
+@item IN_SOLIB_RETURN_TRAMPOLINE pc name
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that returns from a shared library.
+
@item IS_TRAPPED_INTERNALVAR (name)
This is an ugly hook to allow the specification of special actions that
should occur as a side-effect of setting the value of a variable
internal to GDB. Currently only used by the h8500. Note that this
could be either a host or target conditional.
-@item KERNEL_DEBUGGING
-tm-ultra3.h
-
-@item MIPSEL
-mips-tdep.c
-
@item NEED_TEXT_START_END
Define this if GDB should determine the start and end addresses of the
text section. (Seems dubious.)
@item NO_HIF_SUPPORT
(Specific to the a29k.)
-@item NO_SINGLE_STEP
-Define this if the target does not support single-stepping. If this is
-defined, you must supply, in @code{*-tdep.c}, the function
-@code{single_step}, which takes a target_signal as argument and returns
-nothing. It must insert breakpoints at each possible destinations of
-the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
+@item SOFTWARE_SINGLE_STEP_P
+Define this as 1 if the target does not have a hardware single-step
+mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
+
+@item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)
+A function that inserts or removes (dependant on
+@var{insert_breapoints_p}) breakpoints at each possible destinations of
+the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
for examples.
@item PCC_SOL_BROKEN
@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.
The total amount of space needed to store GDB's copy of the machine's
register state.
+@item REGISTER_NAME(i)
+Return the name of register @var{i} as a string. May return @var{NULL}
+or @var{NUL} to indicate that register @var{i} is not valid.
+
@item REGISTER_NAMES
-Define this to expand into an initializer of an array of strings. Each
-string is the name of a register.
+Deprecated in favor of @var{REGISTER_NAME}.
@item REG_STRUCT_HAS_ADDR (gcc_p, type)
Define this to return 1 if the given type will be passed by pointer
rather than directly.
+@item 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.
(Only used for m88k targets.)
@item SKIP_PROLOGUE (pc)
-A C statement that advances the @var{pc} across any function entry
-prologue instructions so as to reach ``real'' code.
+A C expression that returns the address of the ``real'' code beyond the
+function entry prologue found at @var{pc}.
@item SKIP_PROLOGUE_FRAMELESS_P
-A C statement that should behave similarly, but that can stop as soon as
-the function is known to have a frame. If not defined,
+A C expression that should behave similarly, but that can stop as soon
+as the function is known to have a frame. If not defined,
@code{SKIP_PROLOGUE} will be used instead.
@item SKIP_TRAMPOLINE_CODE (pc)
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'
The default value of the `symbol-reloading' variable. (Never defined in
current sources.)
-@item TARGET_BYTE_ORDER
-The ordering of bytes in the target. This must be defined to be either
-@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
+@item TARGET_BYTE_ORDER_DEFAULT
+The ordering of bytes in the target. This must be either
+@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
+@var{TARGET_BYTE_ORDER} which is deprecated.
+
+@item TARGET_BYTE_ORDER_SELECTABLE_P
+Non-zero if the target has both @code{BIG_ENDIAN} and
+@code{LITTLE_ENDIAN} variants. This macro replaces
+@var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
@item TARGET_CHAR_BIT
Number of bits in a char; defaults to 8.
@item TARGET_COMPLEX_BIT
Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
+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}.
hard to get at place; for example, part in a segment register and part
in an ordinary register.
+@item TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)
+Returns a @code{(register, offset)} pair representing the virtual
+frame pointer in use at the code address @code{"pc"}. If virtual
+frame pointers are not used, a default definition simply returns
+@code{FP_REGNUM}, with an offset of zero.
+
@item USE_STRUCT_CONVENTION (gcc_p, type)
If defined, this must be an expression that is nonzero if a value of the
given @var{type} being returned from a function must have space
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
to unfiltered (``@code{printf}'') output. Symbol reading routines that
print warnings are a good example.
-@section Coding Style
+@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. There are some additional considerations
-for GDB maintainers that reflect the unique environment and style of GDB
-maintenance. If you follow these guidelines, GDB will be more
-consistent and easier to maintain.
+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
-GDB's policy on the use of prototypes is that prototypes are used to
-@emph{declare} functions but never to @emph{define} them. Simple macros
-are used in the declarations, so that a non-ANSI compiler can compile
-GDB without trouble. The simple macro calls are used like this:
+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, char *));
+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
described like:
@example @code
-void noprocess PARAMS ((void));
+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. All static functions should have such
-a declaration near the top of their source file.
+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.
-We don't have a gcc option that will properly check that these rules
-have been followed, but it's GDB policy, and we periodically check it
-using the tools available (plus manual labor), and clean up any
-remnants.
+All static functions must be declared in a block near the top of the
+source file.
-@section Clean Design
+@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
machines which are radically different don't need to use infptrace.c at
all.
-@emph{Do} write code that doesn't 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. In short, follow good
-programming practices for writing portable C code.
-
+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