This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
RFA: GDB overlay docs, ASCII art only
- From: Jim Blandy <jimb at zwingli dot cygnus dot com>
- To: gdb-patches at sources dot redhat dot com
- Date: Fri, 30 Nov 2001 16:39:26 -0500 (EST)
- Subject: RFA: GDB overlay docs, ASCII art only
Well, let me do this in a slightly less controversial way. Here is a
patch to document GDB's overlay support, using good old ASCII art.
Just a straightforward patch to gdb.texinfo. I'll post all the
diagramming stuff as a separate patch, once this is approved.
2001-10-09 Jim Blandy <jimb@redhat.com>
* gdb.texinfo (Overlays): New chapter, documenting GDB's
overlay support. Add to top-level menu.
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.58
diff -c -r1.58 gdb.texinfo
*** gdb/doc/gdb.texinfo 2001/11/27 04:14:37 1.58
--- gdb/doc/gdb.texinfo 2001/11/30 21:35:46
***************
*** 127,132 ****
--- 127,133 ----
* Source:: Examining source files
* Data:: Examining data
* Tracepoints:: Debugging remote targets non-intrusively
+ * Overlays:: Debugging programs that use overlays
* Languages:: Using @value{GDBN} with different languages
***************
*** 179,184 ****
--- 180,186 ----
* Source:: Examining source files
* Data:: Examining data
* Tracepoints:: Debugging remote targets non-intrusively
+ * Overlays:: Debugging programs that use overlays
* Languages:: Using @value{GDBN} with different languages
***************
*** 6300,6305 ****
--- 6302,6682 ----
> tfind
> end
@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 GDB.
+ * Automatic Overlay Debugging:: GDB 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 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 @code{overlay}; you can
+ abbreviate this as @code{ov} or @code{ovly}. The commands are:
+
+ @table @code
+ @item overlay off
+ @kindex 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.
+
+ @item overlay manual
+ @kindex overlay manual
+ @cindex manual overlay debugging
+ Enable @dfn{manual} overlay debugging. In this mode, GDB 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 GDB 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, 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 @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 GDB 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, GDB 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, GDB 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, 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.
+
+ @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 GDB 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, GDB 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, GDB 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, GDB 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, 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 @code{break} and
+ @code{disassemble}, to work normally, even on unmapped code. However,
+ GDB's breakpoint support has some limitations:
+
+ @itemize @bullet
+ @item
+ You can set breakpoints in functions in unmapped overlays, as long as
+ GDB can write to the overlay at its load address.
+ @item
+ 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.
+ @end itemize
+
+
+ @node Automatic Overlay Debugging
+ @section Automatic Overlay Debugging
+ @cindex automatic overlay debugging
+
+ GDB 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}), GDB 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 GDB'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, GDB 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 GDB 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 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 GDB's overlay support.
+
+ However, the GDB 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
@chapter Using @value{GDBN} with Different Languages