11.2 Overlay Commands

To use No value for GDBN'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 No value for GDBN to determine the appropriate address of a function or variable, depending on whether the overlay is mapped or not.

No value for GDBN's overlay commands all start with the word overlay; you can abbreviate this as ov or ovly. The commands are:

overlay off

Disable No value for GDBN's overlay support. When overlay support is disabled, No value for GDBN assumes that all functions and variables are always present at their mapped addresses. By default, No value for GDBN's overlay support is disabled.

overlay manual

Enable manual overlay debugging. In this mode, No value for GDBN 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 No value for GDBN that overlay is now mapped; overlay must be the name of the object file section containing the overlay. When an overlay is mapped, No value for GDBN assumes it can find the overlay's functions and variables at their mapped addresses. No value for GDBN assumes that any other overlays whose mapped ranges overlap that of overlay are now unmapped.

overlay unmap-overlay overlay

overlay unmap overlay

Tell No value for GDBN that overlay is no longer mapped; overlay must be the name of the object file section containing the overlay. When an overlay is unmapped, No value for GDBN assumes it can find the overlay's functions and variables at their load addresses.

overlay auto

Enable automatic overlay debugging. In this mode, No value for GDBN consults a data structure the overlay manager maintains in the inferior to see which overlays are mapped. For details, see Automatic Overlay Debugging.

overlay load-target

overlay load

Re-read the overlay table from the inferior. Normally, No value for GDBN re-reads the table No value for GDBN automatically each time the inferior stops, so this command should only be necessary if you have changed the overlay mapping yourself using No value for GDBN. 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 No value for GDBN prints a code address, it includes the name of the function the address falls in:

(No value for GDBP) print main
$3 = {int ()} 0x11a0 <main>

When overlay debugging is enabled, No value for GDBN 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, No value for GDBN prints it this way:

(No value for GDBP) overlay list
No sections are mapped.
(No value for GDBP) print foo
$5 = {int (int)} 0x100000 <*foo*>

When foo's overlay is mapped, No value for GDBN prints the function's name normally:

(No value for GDBP) overlay list
Section .ov.foo.text, loaded at 0x100000 - 0x100034,
        mapped at 0x1016 - 0x104a
(No value for GDBP) print foo
$6 = {int (int)} 0x1016 <foo>

When overlay debugging is enabled, No value for GDBN can find the correct address for functions and variables in an overlay, whether or not the overlay is mapped. This allows most No value for GDBN commands, like break and disassemble, to work normally, even on unmapped code. However, No value for GDBN's breakpoint support has some limitations:

• You can set breakpoints in functions in unmapped overlays, as long as No value for GDBN can write to the overlay at its load address.
• No value for 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 No value for GDBN which overlays are now mapped, if you are using manual overlay management), No value for GDBN will re-set its breakpoints properly.