* gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document.
+2003-10-14 Kevin Buettner <kevinb@redhat.com>
+
+ * gdb.texinfo (Breakpoint related warnings): New node.
+ * gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document.
+
2003-10-13 Daniel Jacobowitz <drow@mvista.com>
* gdb.texinfo (Remote Protocol): Document v and vCont.
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
@page
@tex
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
-\xdef\manvers{\$Revision: 1.174 $} % For use in headers, footers too
+\xdef\manvers{\$Revision: 1.175 $} % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Solutions\par
\hfill \manvers\par
@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