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