Re: RFA: Elaborate on new overlay support

["Eli Zaretskii" <eliz@is.elta.co.il>]

> 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.