Re: [RFA/doc] TARGET_ADJUST_BREAKPOINT_ADDRESS - patch 2 of 4

[Kevin Buettner <kevinb@redhat.com>]

On Oct 14,  7:54am, Eli Zaretskii wrote:

> > How about the following?
> > 
> > 	* gdb.texinfo (Breakpoint related warnings): New node.
> > 	* gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document.
> 
> Thanks; approved with the following comments:
[comments snipped]

Committed with the suggested modifications.  Here's what went in:

 	* gdb.texinfo (Breakpoint related warnings): New node.
 	* gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document.

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.179
diff -u -p -r1.179 gdb.texinfo
--- doc/gdb.texinfo	13 Oct 2003 16:11:57 -0000	1.179
+++ doc/gdb.texinfo	14 Oct 2003 20:21:01 -0000
@@ -3309,6 +3309,58 @@ watchpoints it needs to insert.
 When this message is printed, you need to disable or remove some of the
 hardware-assisted breakpoints and watchpoints, and then continue.
 
+@node Breakpoint related warnings
+@subsection ``Breakpoint address adjusted...''
+@cindex breakpoint address adjusted
+
+Some processor architectures place constraints on the addresses at
+which breakpoints may be placed.  For architectures thus constrained,
+@value{GDBN} will attempt to adjust the breakpoint's address to comply
+with the constraints dictated by the architecture.
+
+One example of such an architecture is the Fujitsu FR-V.  The FR-V is
+a VLIW architecture in which a number of RISC-like instructions may be
+bundled together for parallel execution.  The FR-V architecture
+constrains the location of a breakpoint instruction within such a
+bundle to the instruction with the lowest address.  @value{GDBN}
+honors this constraint by adjusting a breakpoint's address to the
+first in the bundle.
+
+It is not uncommon for optimized code to have bundles which contain
+instructions from different source statements, thus it may happen that
+a breakpoint's address will be adjusted from one source statement to
+another.  Since this adjustment may significantly alter @value{GDBN}'s
+breakpoint related behavior from what the user expects, a warning is
+printed when the breakpoint is first set and also when the breakpoint
+is hit.
+
+A warning like the one below is printed when setting a breakpoint
+that's been subject to address adjustment:
+
+@smallexample
+warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
+@end smallexample
+
+Such warnings are printed both for user settable and @value{GDBN}'s
+internal breakpoints.  If you see one of these warnings, you should
+verify that a breakpoint set at the adjusted address will have the
+desired affect.  If not, the breakpoint in question may be removed and
+other breakpoints may be set which will have the desired behavior. 
+E.g., it may be sufficient to place the breakpoint at a later
+instruction.  A conditional breakpoint may also be useful in some
+cases to prevent the breakpoint from triggering too often.
+
+@value{GDBN} will also issue a warning when stopping at one of these
+adjusted breakpoints:
+
+@smallexample
+warning: Breakpoint 1 address previously adjusted from 0x00010414
+to 0x00010410.
+@end smallexample
+
+When this warning is encountered, it may be too late to take remedial
+action except in cases where the breakpoint is hit earlier or more
+frequently than expected.
 
 @node Continuing and Stepping
 @section Continuing and stepping
Index: doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.174
diff -u -p -r1.174 gdbint.texinfo
--- doc/gdbint.texinfo	10 Oct 2003 07:08:53 -0000	1.174
+++ doc/gdbint.texinfo	14 Oct 2003 20:21:03 -0000
@@ -3052,6 +3052,39 @@ custom breakpoint insertion and removal 
 @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
 reason.
 
+@item ADJUST_BREAKPOINT_ADDRESS (@var{address})
+@findex ADJUST_BREAKPOINT_ADDRESS
+@cindex breakpoint address adjusted
+Given an address at which a breakpoint is desired, return a breakpoint
+address adjusted to account for architectural constraints on
+breakpoint placement.  This method is not needed by most targets.
+
+The FR-V target (see @file{frv-tdep.c}) requires this method.
+The FR-V is a VLIW architecture in which a number of RISC-like
+instructions are grouped (packed) together into an aggregate
+instruction or instruction bundle.  When the processor executes
+one of these bundles, the component instructions are executed
+in parallel.
+
+In the course of optimization, the compiler may group instructions
+from distinct source statements into the same bundle.  The line number
+information associated with one of the latter statements will likely
+refer to some instruction other than the first one in the bundle.  So,
+if the user attempts to place a breakpoint on one of these latter
+statements, @value{GDBN} must be careful to @emph{not} place the break
+instruction on any instruction other than the first one in the bundle.
+(Remember though that the instructions within a bundle execute
+in parallel, so the @emph{first} instruction is the instruction
+at the lowest address and has nothing to do with execution order.)
+
+The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a
+breakpoint's address by scanning backwards for the beginning of
+the bundle, returning the address of the bundle.
+
+Since the adjustment of a breakpoint may significantly alter a user's
+expectation, @value{GDBN} prints a warning when an adjusted breakpoint
+is initially set and each time that that breakpoint is hit.
+
 @item DEPRECATED_CALL_DUMMY_WORDS
 @findex DEPRECATED_CALL_DUMMY_WORDS
 Pointer to an array of @code{LONGEST} words of data containing