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