Re: RFA: Elaborate on new overlay support

[Jim Blandy <jimb at zwingli dot cygnus dot com>]

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