mingw/info/gdb/Overlay-Commands.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Overlay%20Commands">Overlay Commands</a>,
  13 Next:<a rel="next" accesskey="n" href="Automatic-Overlay-Debugging.html#Automatic%20Overlay%20Debugging">Automatic Overlay Debugging</a>,
  14 Previous:<a rel="previous" accesskey="p" href="How-Overlays-Work.html#How%20Overlays%20Work">How Overlays Work</a>,
  15 Up:<a rel="up" accesskey="u" href="Overlays.html#Overlays">Overlays</a>
  16 <hr><br>
  17 </div>
  18
  19 <h3 class="section">Overlay Commands</h3>
  20
  21    <p>To use GDB's overlay support, each overlay in your program must
  22 correspond to a separate section of the executable file.  The section's
  23 virtual memory address and load memory address must be the overlay's
  24 mapped and load addresses.  Identifying overlays with sections allows
  25 GDB to determine the appropriate address of a function or
  26 variable, depending on whether the overlay is mapped or not.
  27
  28    GDB's overlay commands all start with the word <code>overlay</code>;
  29 you can abbreviate this as <code>ov</code> or <code>ovly</code>.  The commands are:
  30
  31      <dl>
  32 <dt><code>overlay off</code>
  33      <dd>Disable GDB's overlay support.  When overlay support is
  34 disabled, GDB assumes that all functions and variables are
  35 always present at their mapped addresses.  By default, GDB's
  36 overlay support is disabled.
  37
  38      <br><dt><code>overlay manual</code>
  39      <dd>Enable <dfn>manual</dfn> overlay debugging.  In this mode, GDB
  40 relies on you to tell it which overlays are mapped, and which are not,
  41 using the <code>overlay map-overlay</code> and <code>overlay unmap-overlay</code>
  42 commands described below.
  43
  44      <br><dt><code>overlay map-overlay </code><var>overlay</var><code></code>
  45      <dd><dt><code>overlay map </code><var>overlay</var><code></code>
  46      <dd>Tell GDB that <var>overlay</var> is now mapped; <var>overlay</var> must
  47 be the name of the object file section containing the overlay.  When an
  48 overlay is mapped, GDB assumes it can find the overlay's
  49 functions and variables at their mapped addresses.  GDB assumes
  50 that any other overlays whose mapped ranges overlap that of
  51 <var>overlay</var> are now unmapped.
  52
  53      <br><dt><code>overlay unmap-overlay </code><var>overlay</var><code></code>
  54      <dd><dt><code>overlay unmap </code><var>overlay</var><code></code>
  55      <dd>Tell GDB that <var>overlay</var> is no longer mapped; <var>overlay</var>
  56 must be the name of the object file section containing the overlay.
  57 When an overlay is unmapped, GDB assumes it can find the
  58 overlay's functions and variables at their load addresses.
  59
  60      <br><dt><code>overlay auto</code>
  61      <dd>Enable <dfn>automatic</dfn> overlay debugging.  In this mode, GDB
  62 consults a data structure the overlay manager maintains in the inferior
  63 to see which overlays are mapped.  For details, see <a href="Automatic-Overlay-Debugging.html#Automatic%20Overlay%20Debugging">Automatic Overlay Debugging</a>.
  64
  65      <br><dt><code>overlay load-target</code>
  66      <dd><dt><code>overlay load</code>
  67      <dd>Re-read the overlay table from the inferior.  Normally, GDB
  68 re-reads the table GDB automatically each time the inferior
  69 stops, so this command should only be necessary if you have changed the
  70 overlay mapping yourself using GDB.  This command is only
  71 useful when using automatic overlay debugging.
  72
  73      <br><dt><code>overlay list-overlays</code>
  74      <dd><dt><code>overlay list</code>
  75      <dd>Display a list of the overlays currently mapped, along with their mapped
  76 addresses, load addresses, and sizes.
  77
  78    </dl>
  79
  80    <p>Normally, when GDB prints a code address, it includes the name
  81 of the function the address falls in:
  82
  83 <pre class="example">     (gdb) print main
  84      $3 = {int ()} 0x11a0 &lt;main&gt;
  85      </pre>
  86
  87 <p>When overlay debugging is enabled, GDB recognizes code in
  88 unmapped overlays, and prints the names of unmapped functions with
  89 asterisks around them.  For example, if <code>foo</code> is a function in an
  90 unmapped overlay, GDB prints it this way:
  91
  92 <pre class="example">     (gdb) overlay list
  93      No sections are mapped.
  94      (gdb) print foo
  95      $5 = {int (int)} 0x100000 &lt;*foo*&gt;
  96      </pre>
  97
  98 <p>When <code>foo</code>'s overlay is mapped, GDB prints the function's
  99 name normally:
 100
 101 <pre class="example">     (gdb) overlay list
 102      Section .ov.foo.text, loaded at 0x100000 - 0x100034,
 103              mapped at 0x1016 - 0x104a
 104      (gdb) print foo
 105      $6 = {int (int)} 0x1016 &lt;foo&gt;
 106      </pre>
 107
 108    <p>When overlay debugging is enabled, GDB can find the correct
 109 address for functions and variables in an overlay, whether or not the
 110 overlay is mapped.  This allows most GDB commands, like
 111 <code>break</code> and <code>disassemble</code>, to work normally, even on unmapped
 112 code.  However, GDB's breakpoint support has some limitations:
 113
 114      <ul>
 115 <li>You can set breakpoints in functions in unmapped overlays, as long as
 116 GDB can write to the overlay at its load address.
 117 <li>GDB can not set hardware or simulator-based breakpoints in
 118 unmapped overlays.  However, if you set a breakpoint at the end of your
 119 overlay manager (and tell GDB which overlays are now mapped, if
 120 you are using manual overlay management), GDB will re-set its
 121 breakpoints properly.
 122 </ul>
 123
 124    </body></html>
 125