RFA: Elaborate on new overlay support
Jim Blandy
jimb@zwingli.cygnus.com
Fri Feb 8 11:26:00 GMT 2002
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
More information about the Gdb-patches
mailing list