Re: breakpoint for accessing memory location

Eli Zaretskii
2006-10-21T12:58:36Z

> Date: Fri, 20 Oct 2006 18:55:57 +0200
> From: Erik Leunissen <e.leunissen@hccnet.nl>
>
> So, to summarize a long story:
>
> "expr" can mean a lot of different things, but programmers that are new
> to debugging, or new to gdb will not have much idea about useful
> interpretations of that term. If no words are spent on an explanation of
> the power of this single word then users may get lost.

I fixed the manual as shown below. Please see if this addresses your
concerns.

Daniel, I added a reference to the term "data breakpoints" as well,
thanks for the suggestion.

The patches below are committed.

2006-10-21 Eli Zaretskii <eliz@gnu.org>

* gdb.texinfo (Breakpoints, Set Watchpoints): Elaborate and
clarify on the possible meanings of ``expression'' watched by
watchpoints. Add indexing.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.362
retrieving revision 1.364
diff -u -r1.362 -r1.364
--- gdb.texinfo 21 Oct 2006 12:20:59 -0000 1.362
+++ gdb.texinfo 21 Oct 2006 12:50:16 -0000 1.364
@@ -2773,15 +2773,19 @@
call).

@cindex watchpoints
+@cindex data breakpoints
@cindex memory tracing
@cindex breakpoint on memory address
@cindex breakpoint on variable modification
A @dfn{watchpoint} is a special breakpoint that stops your program
-when the value of an expression changes. You must use a different
-command to set watchpoints (@pxref{Set Watchpoints, ,Setting
-watchpoints}), but aside from that, you can manage a watchpoint like
-any other breakpoint: you enable, disable, and delete both breakpoints
-and watchpoints using the same commands.
+when the value of an expression changes. The expression may be a value
+of a variable, or it could involve values of one or more variables
+combined by operators, such as @samp{a + b}. This is sometimes called
+@dfn{data breakpoints}. You must use a different command to set
+watchpoints (@pxref{Set Watchpoints, ,Setting watchpoints}), but aside
+from that, you can manage a watchpoint like any other breakpoint: you
+enable, disable, and delete both breakpoints and watchpoints using the
+same commands.

You can arrange to have values from your program displayed automatically
whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
@@ -3106,7 +3110,24 @@
@cindex setting watchpoints
You can use a watchpoint to stop execution whenever the value of an
expression changes, without having to predict a particular place where
-this may happen.
+this may happen. (This is sometimes called a @dfn{data breakpoint}.)
+The expression may be as simple as the value of a single variable, or
+as complex as many variables combined by operators. Examples include:
+
+@itemize @bullet
+@item
+A reference to the value of a single variable.
+
+@item
+An address cast to an appropriate data type. For example,
+@samp{*(int *)0x12345678} will watch a 4-byte region at the specified
+address (assuming an @code{int} occupies 4 bytes).
+
+@item
+An arbitrarily complex expression, such as @samp{a*b + c/d}. The
+expression can use any operators valid in the program's native
+language (@pxref{Languages}).
+@end itemize

@cindex software watchpoints
@cindex hardware watchpoints
@@ -3124,8 +3145,14 @@
@table @code
@kindex watch
@item watch @var{expr}
-Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
-is written into by the program and its value changes.
+Set a watchpoint for an expression. @value{GDBN} will break when the
+expression @var{expr} is written into by the program and its value
+changes. The simplest (and the most popular) use of this command is
+to watch the value of a single variable:
+
+@smallexample
+(@value{GDBP}) watch foo
+@end smallexample

@kindex rwatch
@item rwatch @var{expr}
@@ -3217,6 +3244,11 @@
@noindent
If this happens, delete or disable some of the watchpoints.

+Watching complex expressions that reference many variables can also
+exhaust the resources available for hardware-assisted watchpoints.
+That's because @value{GDBN} needs to watch every variable in the
+expression with separately allocated resources.
+
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. However the