* 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.

1 files changed, 34 insertions, 7 deletions

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index 3c27769..a1bc3a5 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -397,6 +397,18 @@ single-step the program being debugged and test the value of the
 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 @@ defined.
 @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 @@ two macros can use them for their internal purposes.
 @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 @@ watchpoints before stepping the inferior.
 @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