[RFA/doc] TARGET_ADJUST_BREAKPOINT_ADDRESS - patch 2 of 4

[RFA/doc] TARGET_ADJUST_BREAKPOINT_ADDRESS - patch 2 of 4

[Kevin Buettner]

[This is a repost of the patch I posted earlier, but with the correct
subject line.]

This is patch 2, the documentation patch for my current set of
TARGET_ADJUST_BREAKPOINT_ADDRESS patch submissions.

For an overview of the past history regarding this patch, see:

    http://sources.redhat.com/ml/gdb-patches/2003-10/msg00070.html

Okay?

Kevin

	* gdbint.texinfo (TARGET_ADJUST_BREAKPOINT_ADDRESS): Document.

Index: doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.172
diff -u -p -r1.172 gdbint.texinfo
--- doc/gdbint.texinfo	2 Oct 2003 20:28:31 -0000	1.172
+++ doc/gdbint.texinfo	3 Oct 2003 23:38:30 -0000
@@ -3052,6 +3052,22 @@ custom breakpoint insertion and removal 
 @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
 reason.
 
+@item TARGET_ADJUST_BREAKPOINT_ADDRESS (@var{address})
+@findex TARGET_ADJUST_BREAKPOINT_ADDRESS
+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 whose VLIW instructions consist of a
+number of RISC-like subinstructions which execute in parallel.  This
+architecture requires that breakpoints only be placed on the first
+subinstruction of a VLIW (aggregate) instruction.
+
+Since the adjustment of a breakpoint may radically 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

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

[Eli Zaretskii]

> Date: Fri, 3 Oct 2003 20:08:30 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> This is patch 2, the documentation patch for my current set of
> TARGET_ADJUST_BREAKPOINT_ADDRESS patch submissions.
> 
> For an overview of the past history regarding this patch, see:
> 
>     http://sources.redhat.com/ml/gdb-patches/2003-10/msg00070.html
> 
> Okay?

Yes, but:

 . See my other comments related to documentation of this (in my
   other mail in this thread);

 . Suggest a "@cindex breakpoint, address adjustment" (or some such)
   entry for this text.

Thanks!

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

[Kevin Buettner]

On Oct 7, 11:38pm, Eli Zaretskii wrote:

> Yes, but:
> 
>  . See my other comments related to documentation of this (in my
>    other mail in this thread);
> 
>  . Suggest a "@cindex breakpoint, address adjustment" (or some such)
>    entry for this text.

How about the following?

	* 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	13 Oct 2003 23:33:34 -0000
@@ -3309,6 +3309,57 @@ 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,
+GDB 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.  Upon seeing one of these warnings, the user
+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	13 Oct 2003 23:33:36 -0000
@@ -3052,6 +3052,38 @@ 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
+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

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

[Eli Zaretskii]

> Date: Mon, 13 Oct 2003 16:47:30 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> How about the following?
> 
> 	* gdb.texinfo (Breakpoint related warnings): New node.
> 	* gdbint.texinfo (ADJUST_BREAKPOINT_ADDRESS): Document.

Thanks; approved with the following comments:

> +Some processor architectures place constraints on the addresses at
> +which breakpoints may be placed.  For architectures thus constrained,
> +GDB will attempt to adjust the breakpoint's address to comply with the
> +constraints dictated by the architecture.

"GDB" here should be "@value{GDBN}".

> +                          Upon seeing one of these warnings, the user
> +should verify that a breakpoint set at the adjusted address will have
> +the desired affect.

I suggest to say "If you see one of these warnings, you should verify
that a breakpoint ..." instead.

> +E.g, it may be sufficient to place the breakpoint at a later instruction.

The "e.g." here lacks a period after `g'.

> +@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

This will almost certainly produce an overfull box when TeX'ed.  I
suggest to break the long line into two (if you think it's important
to know that the message is one long line, you can add a comment to
that effect).

> +@item ADJUST_BREAKPOINT_ADDRESS (@var{address})
> +@findex ADJUST_BREAKPOINT_ADDRESS
> +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.

I'd add a @cindex entry here as well.

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

[Kevin Buettner]

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