Re: awatch and rwatch vs watch

[Eli Zaretskii <eliz@gnu.org>]

  From: jtc@redback.com (J.T. Conklin)
  Date: 09 Aug 1999 11:39:13 -0700

> Eli> Can someone tell why?  Should I submit a patch to handle all
> Eli> watchpoints equally, at least on x86 platforms?
> 
> Access watchpoints are triggered when a memory location is read or
> written and read watchpoints are triggered when a memory location is
> read.  Although it would be possible to examine instructions as they

Thanks for the explanations.

> Eli> Btw, the manual clearly has traces of limitations that are pertinent
> Eli> for platforms other than x86: it says something about "setting both
> Eli> watchpoints with the same command" (what ``both watchpoints''?).
> 
> Correct.  I think the manual refers to the sparclite.  A patch to fix it
> would not be inapropriate.

Is the following okay?

1999-08-10  Eli Zaretskii  <eliz@is.elta.co.il>

	* gdb.texi (Set Watchpoints): Explain some subtleties about watch,
	awatch, and rwatch.  Explain why the latter two cannot be set as
	software watchpoints.  Document that watchpoints for local
	variables are deleted when the debuggee terminates.



*** gdb/doc/gdb.t~0	Fri Feb 12 02:02:44 1999
--- gdb/doc/gdb.texi	Tue Aug 10 19:14:04 1999
***************
*** 2866,2879 ****
  @kindex rwatch
  @item rwatch @var{expr}
  Set a watchpoint that will break when watch @var{expr} is read by the program.
- If you use both watchpoints, both must be set with the @code{rwatch}
- command.
  
  @kindex awatch
  @item awatch @var{expr}
  Set a watchpoint that will break when @var{args} is read and written into
! by the program.  If you use both watchpoints, both must be set with the
! @code{awatch} command.
  
  @kindex info watchpoints
  @item info watchpoints
--- 2866,2876 ----
  @kindex rwatch
  @item rwatch @var{expr}
  Set a watchpoint that will break when watch @var{expr} is read by the program.
  
  @kindex awatch
  @item awatch @var{expr}
  Set a watchpoint that will break when @var{args} is read and written into
! by the program.
  
  @kindex info watchpoints
  @item info watchpoints
***************
*** 2897,2902 ****
--- 2894,2934 ----
  @noindent
  if it was able to set a hardware watchpoint.
  
+ Currently, the @code{awatch} and @code{rwatch} commands can only set
+ hardware watchpoints, because accesses to data that don't change the
+ value of the watched expression cannot be detected without examining
+ every instruction as it is being executed, and @value{GDBN} does not do
+ that currently.  If @value{GDBN} finds that it is unable to set a
+ hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
+ will print a message like this:
+ 
+ @smallexample
+ Expression cannot be implemented with read/access watchpoint.
+ @end smallexample
+ 
+ Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
+ data type of the watched expression is wider than what a hardware watchpoint
+ on the target machine can handle.  For example, some systems can only
+ watch regions that are up to 4 bytes wide; on such systems you cannot
+ set hardware watchpoints for an expression that yields a
+ double-precision floating-point number (which is typically 8 bytes
+ wide).  As a work-around, it might be possible to break the large region
+ into a series of smaller ones and watch them with separate watchpoints.
+ 
+ If you set too many hardware watchpoints, @value{GDBN} might be unable
+ to insert all of them when you resume the execution of your program.
+ Since the precise number of active watchpoints is unknown until such
+ time as the program is about to be resumed, @value{GDBN} might not be
+ able to warn you about this when you set the watchpoints, and the
+ warning will be printed only when the program is resumed:
+ 
+ @smallexample
+ Hardware watchpoint @var{num}: Could not insert watchpoint
+ @end smallexample
+ 
+ @noindent
+ If this happens, delete or disable some of the watchpoints.
+ 
  The SPARClite DSU will generate traps when a program accesses
  some data or instruction address that is assigned to the debug registers.  
  For the data addresses, DSU facilitates the @code{watch} command.
***************
*** 2912,2917 ****
--- 2944,2960 ----
  any watchpoints you have set will be inactive until GDB reaches another
  kind of breakpoint or the call completes.
  
+ @value{GDBN} automatically deletes watchpoints that watch local
+ (a.k.a.@: automatic) variables, or expressions that involve such
+ variables, when they @dfn{go out of scope}, that is, when the execution
+ leaves the block in which these variables were defined.  In particular,
+ when the program being debugged terminates, @emph{all} local variables
+ go out of scope, and so only watchpoints that watch global variables
+ remain set.  If you rerun the program, you will need to set all such
+ watchpoints again.  One way of doing that would be to set a code
+ breakpoint at the entry to the @code{main} function and when it breaks,
+ set all the watchpoints.
+ 
  @ifclear BARETARGET
  @quotation
  @cindex watchpoints and threads