[commit] gdbint.texinfo: Improve description of watchpoint support

Eli Zaretskii eliz@gnu.org
Sat Dec 4 14:38:00 GMT 2004


As mentioned in another thread, I realized that the descriptions of
target_stopped_data_address and STOPPED_BY_WATCHPOINT in
gdbint.texinfo are somewhat misleading, so I fixed them.  While at
that, I also added a paragraph with a general description of the
procedure used by breakpoint.c to find out whether the inferior
stopped due to a watchpoint, and if so, which one.

Committed.


2004-12-04  Eli Zaretskii  <eliz@gnu.org>

	* gdbint.texinfo (Algorithms): More accurate description of
	STOPPED_BY_WATCHPOINT.  Point out that target_stopped_data_address
	is not needed unless data-read and data-access watchpoints are
	supported.  Add a description of how GDB checks whether the
	inferior stopped because a watchpoint was hit.

Index: gdb/doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.226
diff -u -r1.226 gdbint.texinfo
--- gdb/doc/gdbint.texinfo	12 Oct 2004 19:14:31 -0000	1.226
+++ gdb/doc/gdbint.texinfo	4 Dec 2004 13:59:50 -0000
@@ -397,6 +397,18 @@
 watched expression(s) after each instruction.  The rest of this
 section is mostly irrelevant for software watchpoints.
 
+When the inferior stops, @value{GDBN} tries to establish, among other
+possible reasons, whether it stopped due to a watchpoint being hit.
+For a data-write watchpoint, it does so by evaluating, for each
+watchpoint, the expression whose value is being watched, and testing
+whether the watched value has changed.  For data-read and data-access
+watchpoints, @value{GDBN} needs the target to supply a primitive that
+returns the address of the data that was accessed or read (see the
+description of @code{target_stopped_data_address} below): if this
+primitive returns a valid address, @value{GDBN} infers that a
+watchpoint triggered if it watches an expression whose evaluation uses
+that address.
+
 @value{GDBN} uses several macros and primitives to support hardware
 watchpoints:
 
@@ -431,17 +443,18 @@
 @findex TARGET_DISABLE_HW_WATCHPOINTS
 @item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid})
 Disables watchpoints in the process identified by @var{pid}.  This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
+used, e.g., on HPPA-RISC machines running HP-UX, which provide
+operations to disable and enable the page-level memory protection that
+implements hardware watchpoints on that platform.
 
 @findex TARGET_ENABLE_HW_WATCHPOINTS
 @item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid})
 Enables watchpoints in the process identified by @var{pid}.  This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
+used, e.g., on HPPA-RISC machines running HP-UX, which provide
+operations to disable and enable the page-level memory protection that
+implements hardware watchpoints on that platform.
 
+@cindex insert or remove hardware watchpoint
 @findex target_insert_watchpoint
 @findex target_remove_watchpoint
 @item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
@@ -480,7 +493,11 @@
 @item target_stopped_data_address (@var{addr_p})
 If the inferior has some watchpoint that triggered, place the address
 associated with the watchpoint at the location pointed to by
-@var{addr_p} and return non-zero.  Otherwise, return zero.
+@var{addr_p} and return non-zero.  Otherwise, return zero.  Note that
+this primitive is used by @value{GDBN} only on targets that support
+data-read or data-access type watchpoints, so targets that have
+support only for data-write watchpoints need not implement these
+primitives.
 
 @findex HAVE_STEPPABLE_WATCHPOINT
 @item HAVE_STEPPABLE_WATCHPOINT
@@ -506,6 +523,16 @@
 @item STOPPED_BY_WATCHPOINT (@var{wait_status})
 Return non-zero if stopped by a watchpoint.  @var{wait_status} is of
 the type @code{struct target_waitstatus}, defined by @file{target.h}.
+Normally, this macro is defined to invoke the function pointed to by
+the @code{to_stopped_by_watchpoint} member of the structure (of the
+type @code{target_ops}, defined on @file{target.h}) that describes the
+target-specific operations; @code{to_stopped_by_watchpoint} ignores
+the @var{wait_status} argument.
+
+@value{GDBN} does not require the non-zero value returned by
+@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot
+determine for sure whether the inferior stopped due to a watchpoint,
+it could return non-zero ``just in case''.
 @end table
 
 @subsection x86 Watchpoints



More information about the Gdb-patches mailing list