\input texinfo @c -*- texinfo -*-
@setfilename gdbint.info
@include gdb-cfg.texi
+@settitle @value{GDBN} Internals
+@setchapternewpage off
@dircategory Software development
@direntry
* Gdb-Internals: (gdbint). The GNU debugger's internals.
@copying
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010
Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
@insertcopying
@end ifnottex
-@setchapternewpage off
-@settitle @value{GDBN} Internals
@syncodeindex fn cp
@syncodeindex vr cp
watchpoints:
@table @code
-@findex TARGET_HAS_HARDWARE_WATCHPOINTS
-@item TARGET_HAS_HARDWARE_WATCHPOINTS
-If defined, the target supports hardware watchpoints.
-(Currently only used for several native configs.)
-
@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
Return the number of hardware watchpoints of type @var{type} that are
hardware-assisted breakpoint always requires exactly one debug
register.
-@findex i386_stopped_by_hwbp
-@item i386_stopped_by_hwbp (void)
-This function returns non-zero if the inferior has some watchpoint or
-hardware breakpoint that triggered. It works like
-@code{i386_stopped_data_address}, except that it doesn't record the
-address whose watchpoint triggered.
-
@findex i386_cleanup_dregs
@item i386_cleanup_dregs (void)
This function clears all the reference counts, addresses, and control
the name of the field.
@end deftypefun
-@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
-This function outputs an address.
+@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address})
+This function outputs an address as appropriate for @var{gdbarch}.
@end deftypefun
@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
@{
if (nr_printable_breakpoints > 0)
annotate_field (4);
- if (gdbarch_addr_bit (current_gdbarch) <= 32)
+ if (print_address_bits <= 32)
ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
else
ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
the ID to further disambiguate frames---for instance, on IA-64
the separate register stack address is included in the ID.
-An invalid frame ID (@code{null_frame_id}) returned from the
+An invalid frame ID (@code{outer_frame_id}) returned from the
@code{this_id} method means to stop unwinding after this frame.
+@code{null_frame_id} is another invalid frame ID which should be used
+when there is no frame. For instance, certain breakpoints are attached
+to a specific frame, and that frame is identified through its frame ID
+(we use this to implement the "finish" command). Using
+@code{null_frame_id} as the frame ID for a given breakpoint means
+that the breakpoint is not specific to any frame. The @code{this_id}
+method should never return @code{null_frame_id}.
+
@section Unwinding Registers
Each unwinder includes a @code{prev_register} method. This method
* Register Representation::
* Frame Interpretation::
* Inferior Call Setup::
+* Adding support for debugging core files::
* Defining Other Architecture Features::
* Adding a New Target::
@end menu
definitions, appropriate for architectures on which all pointers are
simple unsigned byte addresses.
-@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf})
+@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf})
Assume that @var{buf} holds a pointer of type @var{type}, in the
appropriate format for the current architecture. Return the byte
address the pointer refers to.
C@t{++} reference type.
@end deftypefun
-@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{current_gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
+@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
Store in @var{buf} a pointer of type @var{type} representing the address
@var{addr}, in the appropriate format for the current architecture.
types within @value{GDBN} as well as provide the added information to
a @value{GDBN} user when printing type expressions.
-@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})
+@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})
Returns the type flags needed to construct a pointer type whose size
is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
This function is normally called from within a symbol reader. See
@file{dwarf2read.c}.
@end deftypefun
-@deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{current_gdbarch}, int @var{type_flags})
+@deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{gdbarch}, int @var{type_flags})
Given the type flags representing an address class qualifier, return
its name.
@end deftypefun
-@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{name}, int *@var{type_flags_ptr})
+@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{gdbarch}, int @var{name}, int *@var{type_flags_ptr})
Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
for that address class qualifier.
@end deftypefun
@end deftypefn
+@node Adding support for debugging core files
+@section Adding support for debugging core files
+@cindex core files
+
+The prerequisite for adding core file support in @value{GDBN} is to have
+core file support in BFD.
+
+Once BFD support is available, writing the apropriate
+@code{regset_from_core_section} architecture function should be all
+that is needed in order to add support for core files in @value{GDBN}.
+
@node Defining Other Architecture Features
@section Defining Other Architecture Features
nonzero if a function argument of type @var{type} is passed by reference
instead of value.
-@item PROCESS_LINENUMBER_HOOK
-@findex PROCESS_LINENUMBER_HOOK
-A hook defined for XCOFF reading.
-
@item CORE_ADDR gdbarch_push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{bp_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
@findex gdbarch_push_dummy_call
@anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to
the Unix @code{ptrace} call in a vanilla way.
@end table
-@section Native core file Support
-@cindex native core files
-
-@table @file
-@findex fetch_core_registers
-@item core-aout.c::fetch_core_registers()
-Support for reading registers out of a core file. This routine calls
-@code{register_addr()}, see below. Now that BFD is used to read core
-files, virtually all machines should use @code{core-aout.c}, and should
-just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
-@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
-
-@item core-aout.c::register_addr()
-If your @code{nm-@var{xyz}.h} file defines the macro
-@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
-set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
-register number @code{regno}. @code{blockend} is the offset within the
-``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
-@file{core-aout.c} will define the @code{register_addr()} function and
-use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
-you are using the standard @code{fetch_core_registers()}, you will need
-to define your own version of @code{register_addr()}, put it into your
-@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
-the @code{NATDEPFILES} list. If you have your own
-@code{fetch_core_registers()}, you may not need a separate
-@code{register_addr()}. Many custom @code{fetch_core_registers()}
-implementations simply locate the registers themselves.@refill
-@end table
-
-When making @value{GDBN} run native on a new operating system, to make it
-possible to debug core files, you will need to either write specific
-code for parsing your OS's core files, or customize
-@file{bfd/trad-core.c}. First, use whatever @code{#include} files your
-machine uses to define the struct of registers that is accessible
-(possibly in the u-area) in a core file (rather than
-@file{machine/reg.h}), and an include file that defines whatever header
-exists on a core file (e.g., the u-area or a @code{struct core}). Then
-modify @code{trad_unix_core_file_p} to use these values to set up the
-section information for the data segment, stack segment, any other
-segments in the core file (perhaps shared library contents or control
-information), ``registers'' segment, and if there are two discontiguous
-sets of registers (e.g., integer and float), the ``reg2'' segment. This
-section information basically delimits areas in the core file in a
-standard way, which the section-reading routines in BFD know how to seek
-around in.
-
-Then back in @value{GDBN}, you need a matching routine called
-@code{fetch_core_registers}. If you can use the generic one, it's in
-@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
-It will be passed a char pointer to the entire ``registers'' segment,
-its length, and a zero; or a char pointer to the entire ``regs2''
-segment, its length, and a 2. The routine should suck out the supplied
-register values and install them into @value{GDBN}'s ``registers'' array.
-
-If your system uses @file{/proc} to control processes, and uses ELF
-format core files, then you may be able to use the same routines for
-reading the registers out of processes and out of core files.
-
@section ptrace
@section /proc
An x86-based machine can define this to use the generic x86 watchpoint
support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
-@item PROC_NAME_FMT
-@findex PROC_NAME_FMT
-Defines the format for the name of a @file{/proc} device. Should be
-defined in @file{nm.h} @emph{only} in order to override the default
-definition in @file{procfs.c}.
-
@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
@findex SOLIB_ADD
Define this to expand into an expression that will cause the symbols in
Update the copyright year in:
@itemize @bullet
-@item file @file{top.c}, function @code{print_gdb_version}
-@item file @file{gdbserver/server.c}, function @code{gdbserver_version}
-@item file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version}
+ @item
+ file @file{top.c}, function @code{print_gdb_version}
+ @item
+ file @file{gdbserver/server.c}, function @code{gdbserver_version}
+ @item
+ file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version}
@end itemize
@item
-Add the new year in the copyright notices of all source and documentation
-files. This can be done semi-automatically by running the @code{copyright.sh}
-script. This script requires Emacs 22 or later to be installed.
+Run the @file{copyright.sh} script to add the new year in the copyright
+notices of most source files. This script requires Emacs 22 or later to
+be installed.
+
+@item
+The new year also needs to be added manually in all other files that
+are not already taken care of by the @file{copyright.sh} script:
+@itemize @bullet
+ @item
+ @file{*.s}
+ @item
+ @file{*.f}
+ @item
+ @file{*.f90}
+ @item
+ @file{*.igen}
+ @item
+ @file{*.ac}
+ @item
+ @file{*.texi}
+ @item
+ @file{*.texinfo}
+ @item
+ @file{*.tex}
+ @item
+ @file{*.defs}
+ @item
+ @file{*.1}
+@end itemize
@end itemize
@itemize @bullet
@item
Check the @code{autoconf} version carefully. You want to be using the
-version taken from the @file{binutils} snapshot directory, which can be
-found at @uref{ftp://sourceware.org/pub/binutils/}. It is very
-unlikely that a system installed version of @code{autoconf} (e.g.,
-@file{/usr/bin/autoconf}) is correct.
+version documented in the toplevel @file{README-maintainer-mode} file.
+It is very unlikely that the version of @code{autoconf} installed in
+system directories (e.g., @file{/usr/bin/autoconf}) is correct.
@end itemize
@subsubheading Check out the relevant modules:
where @var{tests} is a list of test script file names, separated by
spaces.
+If you use GNU make, you can use its @option{-j} option to run the
+testsuite in parallel. This can greatly reduce the amount of time it
+takes for the testsuite to run. In this case, if you set
+@code{RUNTESTFLAGS} then, by default, the tests will be run serially
+even under @option{-j}. You can override this and force a parallel run
+by setting the @code{make} variable @code{FORCE_PARALLEL} to any
+non-empty value. Note that the parallel @kbd{make check} assumes
+that you want to run the entire testsuite, so it is not compatible
+with some dejagnu options, like @option{--directory}.
+
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 @value{GDBN} or in the testsuite. Expected
UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
@end smallexample
+@section Testsuite Parameters
+
+Several variables exist to modify the behavior of the testsuite.
+
+@itemize @bullet
+
+@item @code{TRANSCRIPT}
+
+Sometimes it is convenient to get a transcript of the commands which
+the testsuite sends to @value{GDBN}. For example, if @value{GDBN}
+crashes during testing, a transcript can be used to more easily
+reconstruct the failure when running @value{GDBN} under @value{GDBN}.
+
+You can instruct the @value{GDBN} testsuite to write transcripts by
+setting the DejaGNU variable @code{TRANSCRIPT} (to any value)
+before invoking @code{runtest} or @kbd{make check}. The transcripts
+will be written into DejaGNU's output directory. One transcript will
+be made for each invocation of @value{GDBN}; they will be named
+@file{transcript.@var{n}}, where @var{n} is an integer. The first
+line of the transcript file will show how @value{GDBN} was invoked;
+each subsequent line is a command sent as input to @value{GDBN}.
+
+@smallexample
+make check RUNTESTFLAGS=TRANSCRIPT=y
+@end smallexample
+
+Note that the transcript is not always complete. In particular, tests
+of completion can yield partial command lines.
+
+@item @code{GDB}
+
+Sometimes one wishes to test a different @value{GDBN} than the one in the build
+directory. For example, one may wish to run the testsuite on
+@file{/usr/bin/gdb}.
+
+@smallexample
+make check RUNTESTFLAGS=GDB=/usr/bin/gdb
+@end smallexample
+
+@item @code{GDBSERVER}
+
+When testing a different @value{GDBN}, it is often useful to also test a
+different gdbserver.
+
+@smallexample
+make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
+@end smallexample
+
+@item @code{INTERNAL_GDBFLAGS}
+
+When running the testsuite normally one doesn't want whatever is in
+@file{~/.gdbinit} to interfere with the tests, therefore the test harness
+passes @option{-nx} to @value{GDBN}. One also doesn't want any windowed
+version of @value{GDBN}, e.g., @command{gdbtui}, to run.
+This is achieved via @code{INTERNAL_GDBFLAGS}.
+
+@smallexample
+set INTERNAL_GDBFLAGS "-nw -nx"
+@end smallexample
+
+This is all well and good, except when testing an installed @value{GDBN}
+that has been configured with @option{--with-system-gdbinit}. Here one
+does not want @file{~/.gdbinit} loaded but one may want the system
+@file{.gdbinit} file loaded. This can be achieved by pointing @code{$HOME}
+at a directory without a @file{.gdbinit} and by overriding
+@code{INTERNAL_GDBFLAGS} and removing @option{-nx}.
+
+@smallexample
+cd testsuite
+HOME=`pwd` runtest \
+ GDB=/usr/bin/gdb \
+ GDBSERVER=/usr/bin/gdbserver \
+ INTERNAL_GDBFLAGS=-nw
+@end smallexample
+
+@end itemize
+
+There are two ways to run the testsuite and pass additional parameters
+to DejaGnu. The first is with @kbd{make check} and specifying the
+makefile variable @samp{RUNTESTFLAGS}.
+
+@smallexample
+make check RUNTESTFLAGS=TRANSCRIPT=y
+@end smallexample
+
+The second is to cd to the @file{testsuite} directory and invoke the DejaGnu
+@command{runtest} command directly.
+
+@smallexample
+cd testsuite
+make site.exp
+runtest TRANSCRIPT=y
+@end smallexample
+
@section Testsuite Organization
@cindex test suite organization
projects / deliverable / binutils-gdb.git / blobdiff