From b6b8ece66c352e998c7258b40747a8d1b7701cdf Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 4 Dec 2004 14:02:44 +0000 Subject: * 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. --- gdb/doc/ChangeLog | 8 ++++++++ gdb/doc/gdbint.texinfo | 41 ++++++++++++++++++++++++++++++++++------- 2 files changed, 42 insertions(+), 7 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index d5ac17b..fa942c0 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,11 @@ +2004-12-04 Eli Zaretskii + + * 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. + 2004-11-23 Eli Zaretskii * gdb.texinfo (Files): Add cross-reference to description of 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 -- cgit v1.1