From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27668 invoked by alias); 30 Nov 2001 21:38:16 -0000 Mailing-List: contact gdb-patches-help@sourceware.cygnus.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 27601 invoked from network); 30 Nov 2001 21:38:09 -0000 Received: from unknown (HELO zwingli.cygnus.com) (208.245.165.35) by hostedprojects.ges.redhat.com with SMTP; 30 Nov 2001 21:38:09 -0000 Received: by zwingli.cygnus.com (Postfix, from userid 442) id 4E5655E9D8; Fri, 30 Nov 2001 16:39:26 -0500 (EST) From: Jim Blandy To: gdb-patches@sources.redhat.com Subject: RFA: GDB overlay docs, ASCII art only Message-Id: <20011130213926.4E5655E9D8@zwingli.cygnus.com> Date: Sat, 24 Nov 2001 20:06:00 -0000 X-SW-Source: 2001-11/txt/msg00419.txt.bz2 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 * 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
+ @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 + @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 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jim Blandy To: gdb-patches@sources.redhat.com Subject: RFA: GDB overlay docs, ASCII art only Date: Fri, 30 Nov 2001 13:38:00 -0000 Message-ID: <20011130213926.4E5655E9D8@zwingli.cygnus.com> X-SW-Source: 2001-11/msg00634.html Message-ID: <20011130133800.Y3cYtTV9cbIFNZMTJsfPJjHiguKl6cvuslzKfFbsJvs@z> 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 * 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
+ @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 + @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