RFA: Elaborate on new overlay support

RFA: Elaborate on new overlay support

[Jim Blandy]

Michael's recent fixes missed a separate discussion of the limitations
of breakpoints, which is now obsolete.  This patch also goes into more
detail on how _ovly_debug_event behaves, and why it is necessary.

2002-02-08  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Overlay Commands): Elaborate on the limitations and
	requirements of breakpoints in overlays.
        (Automatic Overlay Debugging): Elaborate on the role of
	_ovly_debug_event.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.87
diff -c -r1.87 gdb.texinfo
*** gdb/doc/gdb.texinfo	2002/02/06 18:29:38	1.87
--- gdb/doc/gdb.texinfo	2002/02/08 19:23:07
***************
*** 6579,6601 ****
  address for functions and variables in an overlay, whether or not the
  overlay is mapped.  This allows most @value{GDBN} commands, like
  @code{break} and @code{disassemble}, to work normally, even on unmapped
! code.  However, @value{GDBN}'s breakpoint support has some limitations:
  
- @itemize @bullet
- @item
  @cindex breakpoints in overlays
  @cindex overlays, setting breakpoints in
! You can set breakpoints in functions in unmapped overlays, as long as
! @value{GDBN} can write to the overlay at its load address.
  @item
! @value{GDBN} can not set hardware or simulator-based breakpoints in
! unmapped overlays.  However, if you set a breakpoint at the end of your
! overlay manager (and tell @value{GDBN} which overlays are now mapped, if
! you are using manual overlay management), @value{GDBN} will re-set its
! breakpoints properly.
  @end itemize
  
  
  @node Automatic Overlay Debugging
  @section Automatic Overlay Debugging
  @cindex automatic overlay debugging
--- 6579,6636 ----
  address for functions and variables in an overlay, whether or not the
  overlay is mapped.  This allows most @value{GDBN} commands, like
  @code{break} and @code{disassemble}, to work normally, even on unmapped
! code.
  
  @cindex breakpoints in overlays
  @cindex overlays, setting breakpoints in
! However, @value{GDBN}'s breakpoint commands have some special
! requirements.  @value{GDBN} supports two different implementations of
! breakpoints:
! 
! @itemize @bullet
! @item
! Usually, @value{GDBN} uses @dfn{software breakpoints}.  To place a
! software breakpoint, @value{GDBN} actually modifies the program's code:
! it replaces the instruction at the breakpoint's address with a special
! breakpoint instruction which, when executed, suspends the program and
! transfers control to the debugger, which then reports a breakpoint hit.
! @value{GDBN} puts the original instruction back when stepping past the
! breakpoint, or when the breakpoint is deleted.
! 
  @item
! In some cases, @value{GDBN} uses @dfn{hardware breakpoints}.  These are
! usually facilities built into the processor itself, which cause it to
! suspend the program and transfer control to the debugger when execution
! reaches a certain addresses.  To place a hardware breakpoint, @value{GDBN}
! need not modify the program's instructions.
! 
  @end itemize
  
+ These two breakpoint implementations have different characteristics:
+ 
+ @itemize @bullet
+ 
+ @item
+ Since software breakpoints depend on modifying the program's code,
+ @value{GDBN} clearly cannot place them in code located in read-only
+ memory.  In that case, @value{GDBN} could use hardware breakpoints
+ instead, if the processor supports them.
  
+ @item
+ When the overlay manager copies an overlay's code from its load address
+ to its mapped address, it will carry any software breakpoints set in the
+ load area into the overlay area.  However, copying the code will not
+ automatically carry over hardware breakpoints, so the debugger must
+ insert them in each newly mapped overlay before the program ever
+ executes the overlay's code, and remove them from the overlay area when
+ the overlay is unmapped.  For this reason, @value{GDBN} can only set
+ hardware breakpoints in overlays when you are using automatic overlay
+ debugging, and your overlay manager provides the
+ @code{_ovly_debug_event} function; @xref{Automatic Overlay Debugging}.
+ 
+ @end itemize
+ 
+ 
  @node Automatic Overlay Debugging
  @section Automatic Overlay Debugging
  @cindex automatic overlay debugging
***************
*** 6647,6660 ****
  currently mapped.
  
  In addition, your overlay manager may define a function called
! @var{_ovly_debug_event}.  If this function is defined, @value{GDBN}
! will silently set a breakpoint there.  If the overlay manager then
! calls this function whenever it has changed the overlay table, this
! will enable @value{GDBN} to accurately keep track of which overlays
! are in program memory, and update any breakpoints that may be set
! in overlays.  This will allow breakpoints to work even if the 
! overlays are kept in ROM or other non-writable memory while they
! are not being executed.
  
  @node Overlay Sample Program
  @section Overlay Sample Program
--- 6682,6712 ----
  currently mapped.
  
  In addition, your overlay manager may define a function called
! @code{_ovly_debug_event}.  If this function is defined, @value{GDBN}
! silently sets a breakpoint there.  If your overlay manager calls this
! function whenever it has changed the overlay table, @value{GDBN}
! re-reads the overlay table from the inferior, relocates any breakpoints
! whose addresses are affected, and silently continues your program.
! 
! The @code{_ovly_debug_event} function needn't actually do anything; it
! exists only to allow the debugger to set a breakpoint on it.  The
! following is an adequate definition:
! 
! @example
! void _ovly_debug_event () @{ @}
! @end example
! 
! If your overlay manager does not provide the @code{_ovly_debug_event}
! function, then @value{GDBN} has no way to know when an overlay becomes
! mapped or unmapped.  This means it is impossible for @value{GDBN} to
! support hardware breakpoints, or to place any kind of breakpoint in an
! overlay stored in read-only memory; see the discussion in @ref{Overlay
! Commands}.  By calling @code{_ovly_debug_event}, the overlay manager
! gives @value{GDBN} the opportunity to insert or remove hardware
! breakpoints for overlays that have been mapped or unmapped.  It also
! gives @value{GDBN} the opportunity to write in any software breakpoints
! that it was unable to place in overlays located in read-only memory.
! 
  
  @node Overlay Sample Program
  @section Overlay Sample Program

Re: RFA: Elaborate on new overlay support

[Eli Zaretskii]

> From: Jim Blandy <jimb@zwingli.cygnus.com>
> Date: Fri,  8 Feb 2002 14:27:55 -0500 (EST)
> 
> Michael's recent fixes missed a separate discussion of the limitations
> of breakpoints, which is now obsolete.  This patch also goes into more
> detail on how _ovly_debug_event behaves, and why it is necessary.

Thanks.  I have a few minor comments on this.

> ! However, @value{GDBN}'s breakpoint commands have some special
> ! requirements.  @value{GDBN} supports two different implementations of
> ! breakpoints:

This is a very useful description, but I don't think it belongs to a
section which talks about debugging overlays.  So I suggest to move
this text to the beginning of the "Breakpoints" node, before the
menu, and leave in "Overlay Commands" an xref to that description
(you can use @anchor to land the reader exactly on the relevant chunk
of text, since we now require Texinfo 4.0 or later).

> + These two breakpoint implementations have different characteristics:
> + 
> + @itemize @bullet
> + 
> + @item
> + Since software breakpoints depend on modifying the program's code,
> + @value{GDBN} clearly cannot place them in code located in read-only
> + memory.  In that case, @value{GDBN} could use hardware breakpoints
> + instead, if the processor supports them.

Is the read-only memory issue relevant only to overlays?  If not, this
part, too, should go to the "Breakpoints" node.

> + @item
> + When the overlay manager copies an overlay's code from its load address
> + to its mapped address

I don't have the CVS version of gdb.texinfo where I type this; does
the reader already know, by the time she reads this, what are ``load
address'' and ``mapped address''?  If not, perhaps we should explain
that here.

> + the overlay is unmapped.  For this reason, @value{GDBN} can only set
> + hardware breakpoints in overlays when you are using automatic overlay
> + debugging, and your overlay manager provides the
> + @code{_ovly_debug_event} function; @xref{Automatic Overlay Debugging}.

Please use "see @ref" instead of "@xref" here, since @xref is only
appropriate for the beginning of a statement (it generates an
upper-case "Note" in Info and an upper-case "See" in the printed
manual).

>   In addition, your overlay manager may define a function called
> ! @code{_ovly_debug_event}.  If this function is defined, @value{GDBN}
> ! silently sets a breakpoint there.  If your overlay manager calls this
> ! function whenever it has changed the overlay table, @value{GDBN}
> ! re-reads the overlay table from the inferior, relocates any breakpoints
> ! whose addresses are affected, and silently continues your program.

I suggest an index entry here for _ovly_debug_event.

> ! If your overlay manager does not provide the @code{_ovly_debug_event}
> ! function, then @value{GDBN} has no way to know when an overlay becomes
> ! mapped or unmapped.  This means it is impossible for @value{GDBN} to
> ! support hardware breakpoints, or to place any kind of breakpoint in an
> ! overlay stored in read-only memory; see the discussion in @ref{Overlay
> ! Commands}.

I suggest an index entry here, something like this:

  @cindex hardware breakpoints, and overlays

Otherwise, this can go in.

Re: RFA: Elaborate on new overlay support

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:
> > ! However, @value{GDBN}'s breakpoint commands have some special
> > ! requirements.  @value{GDBN} supports two different implementations of
> > ! breakpoints:
> 
> This is a very useful description, but I don't think it belongs to a
> section which talks about debugging overlays.  So I suggest to move
> this text to the beginning of the "Breakpoints" node, before the
> menu, and leave in "Overlay Commands" an xref to that description
> (you can use @anchor to land the reader exactly on the relevant chunk
> of text, since we now require Texinfo 4.0 or later).

Are you sure this is the right thing?  How breakpoints are implemented
is usually completely hidden from the user.  It's only when the user
is writing an overlay manager that the breakpoint implementation
becomes something they have to worry about.

But I'll give it a try, and see if I can make it work well.

> > + These two breakpoint implementations have different characteristics:
> > + 
> > + @itemize @bullet
> > + 
> > + @item
> > + Since software breakpoints depend on modifying the program's code,
> > + @value{GDBN} clearly cannot place them in code located in read-only
> > + memory.  In that case, @value{GDBN} could use hardware breakpoints
> > + instead, if the processor supports them.
> 
> Is the read-only memory issue relevant only to overlays?  If not, this
> part, too, should go to the "Breakpoints" node.

The fact that only hardware breakpoints can be set in read-only memory
is not specific to overlays.  This should definitely go in the
breakpoints section, or be repeated there, since it's information you
may need in order to use breakpoints successfully at all.


> > + @item
> > + When the overlay manager copies an overlay's code from its load address
> > + to its mapped address
> 
> I don't have the CVS version of gdb.texinfo where I type this; does
> the reader already know, by the time she reads this, what are ``load
> address'' and ``mapped address''?  If not, perhaps we should explain
> that here.

Yes, those are terms introduced at the front of the overlay chapter,
where we have the diagram.


> > + the overlay is unmapped.  For this reason, @value{GDBN} can only set
> > + hardware breakpoints in overlays when you are using automatic overlay
> > + debugging, and your overlay manager provides the
> > + @code{_ovly_debug_event} function; @xref{Automatic Overlay Debugging}.
> 
> Please use "see @ref" instead of "@xref" here, since @xref is only
> appropriate for the beginning of a statement (it generates an
> upper-case "Note" in Info and an upper-case "See" in the printed
> manual).

Got it, thanks.


> >   In addition, your overlay manager may define a function called
> > ! @code{_ovly_debug_event}.  If this function is defined, @value{GDBN}
> > ! silently sets a breakpoint there.  If your overlay manager calls this
> > ! function whenever it has changed the overlay table, @value{GDBN}
> > ! re-reads the overlay table from the inferior, relocates any breakpoints
> > ! whose addresses are affected, and silently continues your program.
> 
> I suggest an index entry here for _ovly_debug_event.

Of course.


> > ! If your overlay manager does not provide the @code{_ovly_debug_event}
> > ! function, then @value{GDBN} has no way to know when an overlay becomes
> > ! mapped or unmapped.  This means it is impossible for @value{GDBN} to
> > ! support hardware breakpoints, or to place any kind of breakpoint in an
> > ! overlay stored in read-only memory; see the discussion in @ref{Overlay
> > ! Commands}.
> 
> I suggest an index entry here, something like this:
> 
>   @cindex hardware breakpoints, and overlays

Thanks again.

> Otherwise, this can go in.

I'll post another patch with the breakpoint explanation relocated, and
we'll see how it looks.

Re: RFA: Elaborate on new overlay support

[Eli Zaretskii]

> From: Jim Blandy <jimb@zwingli.cygnus.com>
> Date: 09 Feb 2002 11:17:46 -0500
> 
> Are you sure this is the right thing?  How breakpoints are implemented
> is usually completely hidden from the user.

Not completely: we have the "hbreak" command, for example.

If you meant to tell that even "break" sometimes sets a hardware
breakpoint, then I agree that it's an internal GDB matter, but if
those are the cases you refer to here, there's no need to explain at
length what hardware breakpoints are, just make a cross-reference to
the "Breakpoints" node, where the detailed explanation should live.

Re: RFA: Elaborate on new overlay support

[Andrew Cagney]

> From: Jim Blandy <jimb@zwingli.cygnus.com>
>> Date: 09 Feb 2002 11:17:46 -0500
>> 
>> Are you sure this is the right thing?  How breakpoints are implemented
>> is usually completely hidden from the user.
> 
> 
> Not completely: we have the "hbreak" command, for example.
> 
> If you meant to tell that even "break" sometimes sets a hardware
> breakpoint, then I agree that it's an internal GDB matter, but if
> those are the cases you refer to here, there's no need to explain at
> length what hardware breakpoints are, just make a cross-reference to
> the "Breakpoints" node, where the detailed explanation should live.


Er, yes.  I think there is something more basic going on here.

The hbreak VS break command question comes up irregularly.  Should 
``break'' be allowed to set hardware breakpoints?  My memory of the 
rationale for separate break and hbreak commands is that the hardware 
breakpoint is (at least traditionally) very scarce.  Consequently the 
user is given complete and explicit control over them.  This allowing 
the user to carefully allocate those valueable resources to things like 
a breakpoint on that ROM.

Software breakpoints on the other hand were cheap. They do come with 
certain implied semantics.  They work by modifying memory in the target 
and hence move around when the target moves their memory around.  If 
this isn't happening then I would argue it isn't a software breakpoint.

I get the feeling that there are two issues lurking here:

--

Firstly there looks to be a bug in the software-breakpoint packet.

Consider the sequence:
	set software breakpoint at 0xdead
	program resumes
	program copies *0xdead to *0xbeef
	program stops
GDB knows (via the overlay table) that there is a breakpoint at both FOO 
and BAR.  Removing the breakpoint at foo is easy:
	z0,dead,4
Removing the breakpoint at ``beef'' though is impossible.  GDB knows 
what memory should be at that location.  The target doesn't - the target 
can't track where the breakpoint is (that is unless the target also 
starts tracking overlays).

I guess this suggests that when a software breakpoint is set, it returns 
the original memory value, and when cleared, that original memory value 
is included in the packet.  I remember this being suggested at the time 
(I think so that the target didn't need to record the replaced memory?), 
sigh.

--

Secondly it looks like there is a broken target.  As noted above, a 
software breakpoint has certain implied semantics (it works by modifying 
target memory).  A target implementing software breakpoints using a 
hardware breakpoint mechanisms, I think, is broken - it has broken the 
contract it made with GDB.

Presumably such a target has an infinite (or nearly so) number of 
hardware breakpoints and so doesn't see any point in using 
software-breakpoints.  While OK, this decision needs to be communicated 
back to GDB so that GDB knows what is really going on.  The old ``never 
lie'' rule applies.

enjoy,
Andrew

Re: RFA: Elaborate on new overlay support

[Andrew Cagney]

> GDB knows (via the overlay table) that there is a breakpoint at both FOO and BAR.  Removing the 

typo, 0xdead and 0xbeef.  I s/foo/0xdead/ et.al. but missed these.