set software breakpoints.
Software breakpoints require GDB to do somewhat more work. The basic
-theory is that GDB will replace a program instruction a trap, illegal
-divide, or some other instruction that will cause an exception, and then
-when it's encountered, GDB will take the exception and stop the program.
-When the user says to continue, GDB will restore the original
+theory is that GDB will replace a program instruction with a trap,
+illegal divide, or some other instruction that will cause an exception,
+and then when it's encountered, GDB will take the exception and stop the
+program. When the user says to continue, GDB will restore the original
instruction, single-step, re-insert the trap, and continue on.
Since it literally overwrites the program being tested, the program area
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
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
HPPA's. This should all be ripped out, and a scheme like elfread.c
used.
-@item GDB_TARGET_IS_MACH386
-@item GDB_TARGET_IS_SUN3
-@item GDB_TARGET_IS_SUN386
-Kludges that should go away.
-
@item GET_LONGJMP_TARGET
For most machines, this is a target-dependent parameter. On the
DECstation and the Iris, this is a native-dependent parameter, since
feature-specific macros. It was introduced in haste and we are
repenting at leisure.
+@item SYMBOLS_CAN_START_WITH_DOLLAR
+Some systems have routines whose names start with @samp{$}. Giving this
+macro a non-zero value tells GDB's expression parser to check for such
+routines when parsing tokens that begin with @samp{$}.
+
+On HP-UX, certain system routines (millicode) have names beginning with
+@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
+routine that handles inter-space procedure calls on PA-RISC.
+
@item IEEE_FLOAT
Define this if the target system uses IEEE-format floating point numbers.
Define this to evaluate to nonzero if the program is stopped in the
trampoline that returns from a shared library.
+@item IN_SOLIB_DYNSYM_RESOLVE_CODE pc
+Define this to evaluate to nonzero if the program is stopped in the
+dynamic linker.
+
+@item SKIP_SOLIB_RESOLVER pc
+Define this to evaluate to the (nonzero) address at which execution
+should continue to get past the dynamic linker's symbol resolution
+function. A zero value indicates that it is not important or necessary
+to set a breakpoint to get through the dynamic linker and that single
+stepping will suffice.
+
@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
The number of the ``next next program counter'' register, if defined.
Currently, this is only defined for the Motorola 88K.
+@item PARM_BOUNDARY
+If non-zero, round arguments to a boundary of this many bits before
+pushing them on the stack.
+
@item PRINT_REGISTER_HOOK (regno)
If defined, this must be a function that prints the contents of the
given register to standard output.
@item SHIFT_INST_REGS
(Only used for m88k targets.)
+@item SKIP_PERMANENT_BREAKPOINT
+Advance the inferior's PC past a permanent breakpoint. GDB normally
+steps over a breakpoint by removing it, stepping one instruction, and
+re-inserting the breakpoint. However, permanent breakpoints are
+hardwired into the inferior, and can't be removed, so this strategy
+doesn't work. Calling SKIP_PERMANENT_BREAKPOINT adjusts the processor's
+state so that execution will resume just after the breakpoint. This
+macro does the right thing even when the breakpoint is in the delay slot
+of a branch or jump.
+
@item SKIP_PROLOGUE (pc)
A C expression that returns the address of the ``real'' code beyond the
function entry prologue found at @var{pc}.
@item gdb/config/@var{arch}/@var{ttt}.mt
Contains a Makefile fragment specific to this target. Specifies what
object files are needed for target @var{ttt}, by defining
-@samp{TDEPFILES=@dots{}}. Also specifies the header file which
-describes @var{ttt}, by defining @samp{TM_FILE= tm-@var{ttt}.h}. You
-can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, but
-these are now deprecated and may go away in future versions of GDB.
+@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
+the header file which describes @var{ttt}, by defining @samp{TM_FILE=
+tm-@var{ttt}.h}.
+
+You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
+but these are now deprecated, replaced by autoconf, and may go away in
+future versions of GDB.
@item gdb/config/@var{arch}/tm-@var{ttt}.h
(@file{tm.h} is a link to this file, created by configure). Contains
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
@subsection Function Prototypes
-Prototypes must be used to @emph{declare} functions but never to
+Prototypes must be used to @emph{declare} functions, and may be used to
@emph{define} them. Prototypes for GDB functions must include both the
argument type and name, with the name matching that used in the actual
function definition.
-For the sake of compatibility with pre-ANSI compilers, define prototypes
-with the @code{PARAMS} macro:
-
-@example @code
-extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
- char *contents_cache));
-@end example
-
-Note the double parentheses around the parameter types. This allows an
-arbitrary number of parameters to be described, without freaking out the
-C preprocessor. When the function has no parameters, it should be
-described like:
-
-@example @code
-extern void noprocess PARAMS ((void));
-@end example
-
-The @code{PARAMS} macro expands to its argument in ANSI C, or to a
-simple @code{()} in traditional C.
-
-All external functions should have a @code{PARAMS} declaration in a
-header file that callers include, except for @code{_initialize_*}
-functions, which must be external so that @file{init.c} construction
-works, but shouldn't be visible to random source files.
+All external functions should have a declaration in a header file that
+callers include, except for @code{_initialize_*} functions, which must
+be external so that @file{init.c} construction works, but shouldn't be
+visible to random source files.
All static functions must be declared in a block near the top of the
source file.
@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
@c Conditionals})
-Start with the header files. Once you some idea of how GDB's internal
+Start with the header files. Once you have some idea of how GDB's internal
symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
will find it much easier to understand the code which uses and creates
those symbol tables.