* gdb.texinfo (Overlays): New chapter, documenting GDB's
overlay support. Add to top-level menu.
This commit is contained in:
parent
2d43aa5e5f
commit
df0cd8c5a7
|
@ -1,3 +1,8 @@
|
||||||
|
2001-11-30 Jim Blandy <jimb@redhat.com>
|
||||||
|
|
||||||
|
* gdb.texinfo (Overlays): New chapter, documenting GDB's
|
||||||
|
overlay support. Add to top-level menu.
|
||||||
|
|
||||||
2001-11-26 Tom Tromey <tromey@redhat.com>
|
2001-11-26 Tom Tromey <tromey@redhat.com>
|
||||||
|
|
||||||
* gdb.texinfo (Command Syntax): Document C-o binding.
|
* gdb.texinfo (Command Syntax): Document C-o binding.
|
||||||
|
|
|
@ -127,6 +127,7 @@ Copyright (C) 1988-2001 Free Software Foundation, Inc.
|
||||||
* Source:: Examining source files
|
* Source:: Examining source files
|
||||||
* Data:: Examining data
|
* Data:: Examining data
|
||||||
* Tracepoints:: Debugging remote targets non-intrusively
|
* Tracepoints:: Debugging remote targets non-intrusively
|
||||||
|
* Overlays:: Debugging programs that use overlays
|
||||||
|
|
||||||
* Languages:: Using @value{GDBN} with different languages
|
* Languages:: Using @value{GDBN} with different languages
|
||||||
|
|
||||||
|
@ -179,6 +180,7 @@ Copyright (C) 1988-2000 Free Software Foundation, Inc.
|
||||||
* Source:: Examining source files
|
* Source:: Examining source files
|
||||||
* Data:: Examining data
|
* Data:: Examining data
|
||||||
* Tracepoints:: Debugging remote targets non-intrusively
|
* Tracepoints:: Debugging remote targets non-intrusively
|
||||||
|
* Overlays:: Debugging programs that use overlays
|
||||||
|
|
||||||
* Languages:: Using @value{GDBN} with different languages
|
* Languages:: Using @value{GDBN} with different languages
|
||||||
|
|
||||||
|
@ -6301,6 +6303,386 @@ data.
|
||||||
> end
|
> end
|
||||||
@end smallexample
|
@end smallexample
|
||||||
|
|
||||||
|
@node Overlays
|
||||||
|
@chapter Debugging Programs That Use Overlays
|
||||||
|
@cindex overlays
|
||||||
|
|
||||||
|
If your program is too large to fit completely in your target system's
|
||||||
|
memory, you can sometimes use @dfn{overlays} to work around this
|
||||||
|
problem. @value{GDBN} provides some support for debugging programs that
|
||||||
|
use overlays.
|
||||||
|
|
||||||
|
@menu
|
||||||
|
* How Overlays Work:: A general explanation of overlays.
|
||||||
|
* Overlay Commands:: Managing overlays in @value{GDBN}.
|
||||||
|
* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
|
||||||
|
mapped by asking the inferior.
|
||||||
|
* Overlay Sample Program:: A sample program using overlays.
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@node How Overlays Work
|
||||||
|
@section How Overlays Work
|
||||||
|
@cindex mapped overlays
|
||||||
|
@cindex unmapped overlays
|
||||||
|
@cindex load address, overlay's
|
||||||
|
@cindex mapped address
|
||||||
|
@cindex overlay area
|
||||||
|
|
||||||
|
Suppose you have a computer whose instruction address space is only 64
|
||||||
|
kilobytes long, but which has much more memory which can be accessed by
|
||||||
|
other means: special instructions, segment registers, or memory
|
||||||
|
management hardware, for example. Suppose further that you want to
|
||||||
|
adapt a program which is larger than 64 kilobytes to run on this system.
|
||||||
|
|
||||||
|
One solution is to identify modules of your program which are relatively
|
||||||
|
independent, and need not call each other directly; call these modules
|
||||||
|
@dfn{overlays}. Separate the overlays from the main program, and place
|
||||||
|
their machine code in the larger memory. Place your main program in
|
||||||
|
instruction memory, but leave at least enough space there to hold the
|
||||||
|
largest overlay as well.
|
||||||
|
|
||||||
|
Now, to call a function located in an overlay, you must first copy that
|
||||||
|
overlay's machine code from the large memory into the space set aside
|
||||||
|
for it in the instruction memory, and then jump to its entry point
|
||||||
|
there.
|
||||||
|
|
||||||
|
@example
|
||||||
|
@group
|
||||||
|
Data Instruction Larger
|
||||||
|
Address Space Address Space Address Space
|
||||||
|
+-----------+ +-----------+ +-----------+
|
||||||
|
| | | | | |
|
||||||
|
+-----------+ +-----------+ +-----------+<-- overlay 1
|
||||||
|
| program | | main | | | load address
|
||||||
|
| variables | | program | | overlay 1 |
|
||||||
|
| and heap | | | ,---| |
|
||||||
|
+-----------+ | | | | |
|
||||||
|
| | +-----------+ | +-----------+
|
||||||
|
+-----------+ | | | | |
|
||||||
|
mapped --->+-----------+ / +-----------+<-- overlay 2
|
||||||
|
address | overlay | <-' | overlay 2 | load address
|
||||||
|
| area | <-----| |
|
||||||
|
| | <---. +-----------+
|
||||||
|
| | | | |
|
||||||
|
+-----------+ | | |
|
||||||
|
| | | +-----------+<-- overlay 3
|
||||||
|
+-----------+ `--| | load address
|
||||||
|
| overlay 3 |
|
||||||
|
| |
|
||||||
|
+-----------+
|
||||||
|
| |
|
||||||
|
+-----------+
|
||||||
|
|
||||||
|
To map an overlay, copy its code from the larger address space
|
||||||
|
to the instruction address space. Since the overlays shown here
|
||||||
|
all use the same mapped address, only one may be mapped at a time.
|
||||||
|
@end group
|
||||||
|
@end example
|
||||||
|
|
||||||
|
This diagram shows a system with separate data and instruction address
|
||||||
|
spaces. For a system with a single address space for data and
|
||||||
|
instructions, the diagram would be similar, except that the program
|
||||||
|
variables and heap would share an address space with the main program
|
||||||
|
and the overlay area.
|
||||||
|
|
||||||
|
An overlay loaded into instruction memory and ready for use is called a
|
||||||
|
@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
|
||||||
|
instruction memory. An overlay not present (or only partially present)
|
||||||
|
in instruction memory is called @dfn{unmapped}; its @dfn{load address}
|
||||||
|
is its address in the larger memory. The mapped address is also called
|
||||||
|
the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
|
||||||
|
called the @dfn{load memory address}, or @dfn{LMA}.
|
||||||
|
|
||||||
|
Unfortunately, overlays are not a completely transparent way to adapt a
|
||||||
|
program to limited instruction memory. They introduce a new set of
|
||||||
|
global constraints you must keep in mind as you design your program:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
|
||||||
|
@item
|
||||||
|
Before calling or returning to a function in an overlay, your program
|
||||||
|
must make sure that overlay is actually mapped. Otherwise, the call or
|
||||||
|
return will transfer control to the right address, but in the wrong
|
||||||
|
overlay, and your program will probably crash.
|
||||||
|
|
||||||
|
@item
|
||||||
|
If the process of mapping an overlay is expensive on your system, you
|
||||||
|
will need to choose your overlays carefully to minimize their effect on
|
||||||
|
your program's performance.
|
||||||
|
|
||||||
|
@item
|
||||||
|
The executable file you load onto your system must contain each
|
||||||
|
overlay's instructions, appearing at the overlay's load address, not its
|
||||||
|
mapped address. However, each overlay's instructions must be relocated
|
||||||
|
and its symbols defined as if the overlay were at its mapped address.
|
||||||
|
You can use GNU linker scripts to specify different load and relocation
|
||||||
|
addresses for pieces of your program; see @ref{Overlay Description,,,
|
||||||
|
ld.info, Using ld: the GNU linker}.
|
||||||
|
|
||||||
|
@item
|
||||||
|
The procedure for loading executable files onto your system must be able
|
||||||
|
to load their contents into the larger address space as well as the
|
||||||
|
instruction and data spaces.
|
||||||
|
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
The overlay system described above is rather simple, and could be
|
||||||
|
improved in many ways:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
|
||||||
|
@item
|
||||||
|
If your system has suitable bank switch registers or memory management
|
||||||
|
hardware, you could use those facilities to make an overlay's load area
|
||||||
|
contents simply appear at their mapped address in instruction space.
|
||||||
|
This would probably be faster than copying the overlay to its mapped
|
||||||
|
area in the usual way.
|
||||||
|
|
||||||
|
@item
|
||||||
|
If your overlays are small enough, you could set aside more than one
|
||||||
|
overlay area, and have more than one overlay mapped at a time.
|
||||||
|
|
||||||
|
@item
|
||||||
|
You can use overlays to manage data, as well as instructions. In
|
||||||
|
general, data overlays are even less transparent to your design than
|
||||||
|
code overlays: whereas code overlays only require care when you call or
|
||||||
|
return to functions, data overlays require care every time you access
|
||||||
|
the data. Also, if you change the contents of a data overlay, you
|
||||||
|
must copy its contents back out to its load address before you can copy a
|
||||||
|
different data overlay into the same mapped area.
|
||||||
|
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
|
||||||
|
@node Overlay Commands
|
||||||
|
@section Overlay Commands
|
||||||
|
|
||||||
|
To use @value{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
|
||||||
|
@value{GDBN} to determine the appropriate address of a function or
|
||||||
|
variable, depending on whether the overlay is mapped or not.
|
||||||
|
|
||||||
|
@value{GDBN}'s overlay commands all start with the word @code{overlay};
|
||||||
|
you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item overlay off
|
||||||
|
@kindex overlay off
|
||||||
|
Disable @value{GDBN}'s overlay support. When overlay support is
|
||||||
|
disabled, @value{GDBN} assumes that all functions and variables are
|
||||||
|
always present at their mapped addresses. By default, @value{GDBN}'s
|
||||||
|
overlay support is disabled.
|
||||||
|
|
||||||
|
@item overlay manual
|
||||||
|
@kindex overlay manual
|
||||||
|
@cindex manual overlay debugging
|
||||||
|
Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
|
||||||
|
relies on you to tell it which overlays are mapped, and which are not,
|
||||||
|
using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
|
||||||
|
commands described below.
|
||||||
|
|
||||||
|
@item overlay map-overlay @var{overlay}
|
||||||
|
@itemx overlay map @var{overlay}
|
||||||
|
@kindex overlay map-overlay
|
||||||
|
@cindex map an overlay
|
||||||
|
Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
|
||||||
|
be the name of the object file section containing the overlay. When an
|
||||||
|
overlay is mapped, @value{GDBN} assumes it can find the overlay's
|
||||||
|
functions and variables at their mapped addresses. @value{GDBN} assumes
|
||||||
|
that any other overlays whose mapped ranges overlap that of
|
||||||
|
@var{overlay} are now unmapped.
|
||||||
|
|
||||||
|
@item overlay unmap-overlay @var{overlay}
|
||||||
|
@itemx overlay unmap @var{overlay}
|
||||||
|
@kindex overlay unmap-overlay
|
||||||
|
@cindex unmap an overlay
|
||||||
|
Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
|
||||||
|
must be the name of the object file section containing the overlay.
|
||||||
|
When an overlay is unmapped, @value{GDBN} assumes it can find the
|
||||||
|
overlay's functions and variables at their load addresses.
|
||||||
|
|
||||||
|
@item overlay auto
|
||||||
|
@kindex overlay auto
|
||||||
|
Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
|
||||||
|
consults a data structure the overlay manager maintains in the inferior
|
||||||
|
to see which overlays are mapped. For details, see @ref{Automatic
|
||||||
|
Overlay Debugging}.
|
||||||
|
|
||||||
|
@item overlay load-target
|
||||||
|
@itemx overlay load
|
||||||
|
@kindex overlay load-target
|
||||||
|
@cindex reloading the overlay table
|
||||||
|
Re-read the overlay table from the inferior. Normally, @value{GDBN}
|
||||||
|
re-reads the table @value{GDBN} automatically each time the inferior
|
||||||
|
stops, so this command should only be necessary if you have changed the
|
||||||
|
overlay mapping yourself using @value{GDBN}. This command is only
|
||||||
|
useful when using automatic overlay debugging.
|
||||||
|
|
||||||
|
@item overlay list-overlays
|
||||||
|
@itemx overlay list
|
||||||
|
@cindex listing mapped overlays
|
||||||
|
Display a list of the overlays currently mapped, along with their mapped
|
||||||
|
addresses, load addresses, and sizes.
|
||||||
|
|
||||||
|
@end table
|
||||||
|
|
||||||
|
Normally, when @value{GDBN} prints a code address, it includes the name
|
||||||
|
of the function the address falls in:
|
||||||
|
|
||||||
|
@example
|
||||||
|
(gdb) print main
|
||||||
|
$3 = @{int ()@} 0x11a0 <main>
|
||||||
|
@end example
|
||||||
|
@noindent
|
||||||
|
When overlay debugging is enabled, @value{GDBN} recognizes code in
|
||||||
|
unmapped overlays, and prints the names of unmapped functions with
|
||||||
|
asterisks around them. For example, if @code{foo} is a function in an
|
||||||
|
unmapped overlay, @value{GDBN} prints it this way:
|
||||||
|
|
||||||
|
@example
|
||||||
|
(gdb) overlay list
|
||||||
|
No sections are mapped.
|
||||||
|
(gdb) print foo
|
||||||
|
$5 = @{int (int)@} 0x100000 <*foo*>
|
||||||
|
@end example
|
||||||
|
@noindent
|
||||||
|
When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
|
||||||
|
name normally:
|
||||||
|
|
||||||
|
@example
|
||||||
|
(gdb) overlay list
|
||||||
|
Section .ov.foo.text, loaded at 0x100000 - 0x100034,
|
||||||
|
mapped at 0x1016 - 0x104a
|
||||||
|
(gdb) print foo
|
||||||
|
$6 = @{int (int)@} 0x1016 <foo>
|
||||||
|
@end example
|
||||||
|
|
||||||
|
When overlay debugging is enabled, @value{GDBN} can find the correct
|
||||||
|
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
|
||||||
|
|
||||||
|
@value{GDBN} can automatically track which overlays are mapped and which
|
||||||
|
are not, given some simple co-operation from the overlay manager in the
|
||||||
|
inferior. If you enable automatic overlay debugging with the
|
||||||
|
@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
|
||||||
|
looks in the inferior's memory for certain variables describing the
|
||||||
|
current state of the overlays.
|
||||||
|
|
||||||
|
Here are the variables your overlay manager must define to support
|
||||||
|
@value{GDBN}'s automatic overlay debugging:
|
||||||
|
|
||||||
|
@table @asis
|
||||||
|
|
||||||
|
@item @code{_ovly_table}:
|
||||||
|
This variable must be an array of the following structures:
|
||||||
|
|
||||||
|
@example
|
||||||
|
struct
|
||||||
|
@{
|
||||||
|
/* The overlay's mapped address. */
|
||||||
|
unsigned long vma;
|
||||||
|
|
||||||
|
/* The size of the overlay, in bytes. */
|
||||||
|
unsigned long size;
|
||||||
|
|
||||||
|
/* The overlay's load address. */
|
||||||
|
unsigned long lma;
|
||||||
|
|
||||||
|
/* Non-zero if the overlay is currently mapped;
|
||||||
|
zero otherwise. */
|
||||||
|
unsigned long mapped;
|
||||||
|
@}
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@item @code{_novlys}:
|
||||||
|
This variable must be a four-byte signed integer, holding the total
|
||||||
|
number of elements in @code{_ovly_table}.
|
||||||
|
|
||||||
|
@end table
|
||||||
|
|
||||||
|
To decide whether a particular overlay is mapped or not, @value{GDBN}
|
||||||
|
looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
|
||||||
|
@code{lma} members equal the VMA and LMA of the overlay's section in the
|
||||||
|
executable file. When @value{GDBN} finds a matching entry, it consults
|
||||||
|
the entry's @code{mapped} member to determine whether the overlay is
|
||||||
|
currently mapped.
|
||||||
|
|
||||||
|
|
||||||
|
@node Overlay Sample Program
|
||||||
|
@section Overlay Sample Program
|
||||||
|
@cindex overlay example program
|
||||||
|
|
||||||
|
When linking a program which uses overlays, you must place the overlays
|
||||||
|
at their load addresses, while relocating them to run at their mapped
|
||||||
|
addresses. To do this, you must write a linker script (@pxref{Overlay
|
||||||
|
Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
|
||||||
|
since linker scripts are specific to a particular host system, target
|
||||||
|
architecture, and target memory layout, this manual cannot provide
|
||||||
|
portable sample code demonstrating @value{GDBN}'s overlay support.
|
||||||
|
|
||||||
|
However, the @value{GDBN} source distribution does contain an overlaid
|
||||||
|
program, with linker scripts for a few systems, as part of its test
|
||||||
|
suite. The program consists of the following files from
|
||||||
|
@file{gdb/testsuite/gdb.base}:
|
||||||
|
|
||||||
|
@table @file
|
||||||
|
@item overlays.c
|
||||||
|
The main program file.
|
||||||
|
@item ovlymgr.c
|
||||||
|
A simple overlay manager, used by @file{overlays.c}.
|
||||||
|
@item foo.c
|
||||||
|
@itemx bar.c
|
||||||
|
@itemx baz.c
|
||||||
|
@itemx grbx.c
|
||||||
|
Overlay modules, loaded and used by @file{overlays.c}.
|
||||||
|
@item d10v.ld
|
||||||
|
@itemx m32r.ld
|
||||||
|
Linker scripts for linking the test program on the @code{d10v-elf}
|
||||||
|
and @code{m32r-elf} targets.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
You can build the test program using the @code{d10v-elf} GCC
|
||||||
|
cross-compiler like this:
|
||||||
|
|
||||||
|
@example
|
||||||
|
$ d10v-elf-gcc -g -c overlays.c
|
||||||
|
$ d10v-elf-gcc -g -c ovlymgr.c
|
||||||
|
$ d10v-elf-gcc -g -c foo.c
|
||||||
|
$ d10v-elf-gcc -g -c bar.c
|
||||||
|
$ d10v-elf-gcc -g -c baz.c
|
||||||
|
$ d10v-elf-gcc -g -c grbx.c
|
||||||
|
$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
|
||||||
|
baz.o grbx.o -Wl,-Td10v.ld -o overlays
|
||||||
|
@end example
|
||||||
|
|
||||||
|
The build process is identical for any other architecture, except that
|
||||||
|
you must substitute the appropriate compiler and linker script for the
|
||||||
|
target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
|
||||||
|
|
||||||
|
|
||||||
@node Languages
|
@node Languages
|
||||||
@chapter Using @value{GDBN} with Different Languages
|
@chapter Using @value{GDBN} with Different Languages
|
||||||
@cindex languages
|
@cindex languages
|
||||||
|
|
Loading…
Reference in New Issue