To use gdb's overlay support, each overlay in your program must
correspond to a separate section of the executable file. The section's
virtual memory address and load memory address must be the overlay's
mapped and load addresses. Identifying overlays with sections allows
gdb to determine the appropriate address of a function or
variable, depending on whether the overlay is mapped or not.
gdb's overlay commands all start with the word overlay;
you can abbreviate this as ov or ovly. The commands are:
overlay off
Disable gdb's overlay support. When overlay support is
disabled, gdb assumes that all functions and variables are
always present at their mapped addresses. By default, gdb's
overlay support is disabled.
overlay manual
Enable manual overlay debugging. In this mode, gdb
relies on you to tell it which overlays are mapped, and which are not,
using the overlay map-overlay and overlay unmap-overlay
commands described below.
overlay map-overlay overlay, overlay map overlay
Tell gdb that overlay is now mapped; overlay must
be the name of the object file section containing the overlay. When an
overlay is mapped, gdb assumes it can find the overlay's
functions and variables at their mapped addresses. gdb assumes
that any other overlays whose mapped ranges overlap that of
overlay are now unmapped.
Tell gdb that overlay is no longer mapped; overlay
must be the name of the object file section containing the overlay.
When an overlay is unmapped, gdb assumes it can find the
overlay's functions and variables at their load addresses.
overlay auto
Enable automatic overlay debugging. In this mode, gdb
consults a data structure the overlay manager maintains in the inferior
to see which overlays are mapped. For details, (refer to Section 13.3 Automatic Overlay Debugging.
overlay load-target, overlay load
Re-read the overlay table from the inferior. Normally, gdb
re-reads the table gdb automatically each time the inferior
stops, so this command should only be necessary if you have changed the
overlay mapping yourself using gdb. This command is only
useful when using automatic overlay debugging.
overlay list-overlays, overlay list
Display a list of the overlays currently mapped, along with their mapped
addresses, load addresses, and sizes.
Normally, when gdb prints a code address, it includes the name
of the function the address falls in:
(gdb) print main
$3 = {int ()} 0x11a0 <main>
When overlay debugging is enabled, gdb recognizes code in
unmapped overlays, and prints the names of unmapped functions with
asterisks around them. For example, if foo is a function in an
unmapped overlay, gdb prints it this way:
(gdb) overlay list
No sections are mapped.
(gdb) print foo
$5 = {int (int)} 0x100000 <*foo*>
When foo's overlay is mapped, gdb prints the function's
name normally:
(gdb) overlay list
Section .ov.foo.text, loaded at 0x100000 - 0x100034,
mapped at 0x1016 - 0x104a
(gdb) print foo
$6 = {int (int)} 0x1016 <foo>
When overlay debugging is enabled, gdb can find the correct
address for functions and variables in an overlay, whether or not the
overlay is mapped. This allows most gdb commands, like
break and disassemble, to work normally, even on unmapped
code. However, gdb's breakpoint support has some limitations:
You can set breakpoints in functions in unmapped overlays, as long as
gdb can write to the overlay at its load address.
gdb 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 gdb which overlays are now mapped, if
you are using manual overlay management), gdb will re-set its
breakpoints properly.
