\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
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 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
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
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
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