mingw/info/gdbint/Native-Debugging.html

   1 <html lang="en">
   2 <head>
   3 <title>GDB Internals</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="GDB Internals">
   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="Native%20Debugging">Native Debugging</a>,
  13 Next:<a rel="next" accesskey="n" href="Support-Libraries.html#Support%20Libraries">Support Libraries</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Target-Vector-Definition.html#Target%20Vector%20Definition">Target Vector Definition</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">Native Debugging</h2>
  20
  21    <p>Several files control GDB's configuration for native support:
  22
  23      <dl>
  24 <dt><code>gdb/config/</code><var>arch</var><code>/</code><var>xyz</var><code>.mh</code>
  25      <dd>Specifies Makefile fragments needed by a <em>native</em> configuration on
  26 machine <var>xyz</var>.  In particular, this lists the required
  27 native-dependent object files, by defining <code>NATDEPFILES=...</code>.
  28 Also specifies the header file which describes native support on
  29 <var>xyz</var>, by defining <code>NAT_FILE= nm-</code><var>xyz</var><code>.h</code>.  You can also
  30 define <code>NAT_CFLAGS</code>, <code>NAT_ADD_FILES</code>, <code>NAT_CLIBS</code>,
  31 <code>NAT_CDEPS</code>, etc.; see <code>Makefile.in</code>.
  32
  33      <p><em>Maintainer's note: The </em><code>.mh</code><em> suffix is because this file
  34 originally contained </em><code>Makefile</code><em> fragments for hosting GDB
  35 on machine </em><var>xyz</var><em>.  While the file is no longer used for this
  36 purpose, the </em><code>.mh</code><em> suffix remains.  Perhaphs someone will
  37 eventually rename these fragments so that they have a </em><code>.mn</code><em>
  38 suffix.</em>
  39
  40      <br><dt><code>gdb/config/</code><var>arch</var><code>/nm-</code><var>xyz</var><code>.h</code>
  41      <dd>(<code>nm.h</code> is a link to this file, created by <code>configure</code>).  Contains C
  42 macro definitions describing the native system environment, such as
  43 child process control and core file support.
  44
  45      <br><dt><code>gdb/</code><var>xyz</var><code>-nat.c</code>
  46      <dd>Contains any miscellaneous C code required for this native support of
  47 this machine.  On some machines it doesn't exist at all.
  48 </dl>
  49
  50    <p>There are some "generic" versions of routines that can be used by
  51 various systems.  These can be customized in various ways by macros
  52 defined in your <code>nm-</code><var>xyz</var><code>.h</code> file.  If these routines work for
  53 the <var>xyz</var> host, you can just include the generic file's name (with
  54 <code>.o</code>, not <code>.c</code>) in <code>NATDEPFILES</code>.
  55
  56    <p>Otherwise, if your machine needs custom support routines, you will need
  57 to write routines that perform the same functions as the generic file.
  58 Put them into <code></code><var>xyz</var><code>-nat.c</code>, and put <code></code><var>xyz</var><code>-nat.o</code>
  59 into <code>NATDEPFILES</code>.
  60
  61      <dl>
  62 <dt><code>inftarg.c</code>
  63      <dd>This contains the <em>target_ops vector</em> that supports Unix child
  64 processes on systems which use ptrace and wait to control the child.
  65
  66      <br><dt><code>procfs.c</code>
  67      <dd>This contains the <em>target_ops vector</em> that supports Unix child
  68 processes on systems which use /proc to control the child.
  69
  70      <br><dt><code>fork-child.c</code>
  71      <dd>This does the low-level grunge that uses Unix system calls to do a "fork
  72 and exec" to start up a child process.
  73
  74      <br><dt><code>infptrace.c</code>
  75      <dd>This is the low level interface to inferior processes for systems using
  76 the Unix <code>ptrace</code> call in a vanilla way.
  77 </dl>
  78
  79 <h3 class="section">Native core file Support</h3>
  80
  81      <dl>
  82 <dt><code>core-aout.c::fetch_core_registers()</code>
  83      <dd>Support for reading registers out of a core file.  This routine calls
  84 <code>register_addr()</code>, see below.  Now that BFD is used to read core
  85 files, virtually all machines should use <code>core-aout.c</code>, and should
  86 just provide <code>fetch_core_registers</code> in <code></code><var>xyz</var><code>-nat.c</code> (or
  87 <code>REGISTER_U_ADDR</code> in <code>nm-</code><var>xyz</var><code>.h</code>).
  88
  89      <br><dt><code>core-aout.c::register_addr()</code>
  90      <dd>If your <code>nm-</code><var>xyz</var><code>.h</code> file defines the macro
  91 <code>REGISTER_U_ADDR(addr, blockend, regno)</code>, it should be defined to
  92 set <code>addr</code> to the offset within the <code>user</code> struct of GDB
  93 register number <code>regno</code>.  <code>blockend</code> is the offset within the
  94 "upage" of <code>u.u_ar0</code>.  If <code>REGISTER_U_ADDR</code> is defined,
  95 <code>core-aout.c</code> will define the <code>register_addr()</code> function and
  96 use the macro in it.  If you do not define <code>REGISTER_U_ADDR</code>, but
  97 you are using the standard <code>fetch_core_registers()</code>, you will need
  98 to define your own version of <code>register_addr()</code>, put it into your
  99 <code></code><var>xyz</var><code>-nat.c</code> file, and be sure <code></code><var>xyz</var><code>-nat.o</code> is in
 100 the <code>NATDEPFILES</code> list.  If you have your own
 101 <code>fetch_core_registers()</code>, you may not need a separate
 102 <code>register_addr()</code>.  Many custom <code>fetch_core_registers()</code>
 103 implementations simply locate the registers themselves.
 104 </dl>
 105
 106    <p>When making GDB run native on a new operating system, to make it
 107 possible to debug core files, you will need to either write specific
 108 code for parsing your OS's core files, or customize
 109 <code>bfd/trad-core.c</code>.  First, use whatever <code>#include</code> files your
 110 machine uses to define the struct of registers that is accessible
 111 (possibly in the u-area) in a core file (rather than
 112 <code>machine/reg.h</code>), and an include file that defines whatever header
 113 exists on a core file (e.g. the u-area or a <code>struct core</code>).  Then
 114 modify <code>trad_unix_core_file_p</code> to use these values to set up the
 115 section information for the data segment, stack segment, any other
 116 segments in the core file (perhaps shared library contents or control
 117 information), "registers" segment, and if there are two discontiguous
 118 sets of registers (e.g.  integer and float), the "reg2" segment.  This
 119 section information basically delimits areas in the core file in a
 120 standard way, which the section-reading routines in BFD know how to seek
 121 around in.
 122
 123    <p>Then back in GDB, you need a matching routine called
 124 <code>fetch_core_registers</code>.  If you can use the generic one, it's in
 125 <code>core-aout.c</code>; if not, it's in your <code></code><var>xyz</var><code>-nat.c</code> file.
 126 It will be passed a char pointer to the entire "registers" segment,
 127 its length, and a zero; or a char pointer to the entire "regs2"
 128 segment, its length, and a 2.  The routine should suck out the supplied
 129 register values and install them into GDB's "registers" array.
 130
 131    <p>If your system uses <code>/proc</code> to control processes, and uses ELF
 132 format core files, then you may be able to use the same routines for
 133 reading the registers out of processes and out of core files.
 134
 135 <h3 class="section">ptrace</h3>
 136
 137 <h3 class="section">/proc</h3>
 138
 139 <h3 class="section">win32</h3>
 140
 141 <h3 class="section">shared libraries</h3>
 142
 143 <h3 class="section">Native Conditionals</h3>
 144
 145    <p>When GDB is configured and compiled, various macros are
 146 defined or left undefined, to control compilation when the host and
 147 target systems are the same.  These macros should be defined (or left
 148 undefined) in <code>nm-</code><var>system</var><code>.h</code>.
 149
 150      <dl>
 151 <dt><code>ATTACH_DETACH</code>
 152      <dd>If defined, then GDB will include support for the <code>attach</code> and
 153 <code>detach</code> commands.
 154
 155      <br><dt><code>CHILD_PREPARE_TO_STORE</code>
 156      <dd>If the machine stores all registers at once in the child process, then
 157 define this to ensure that all values are correct.  This usually entails
 158 a read from the child.
 159
 160      <p>[Note that this is incorrectly defined in <code>xm-</code><var>system</var><code>.h</code> files
 161 currently.]
 162
 163      <br><dt><code>FETCH_INFERIOR_REGISTERS</code>
 164      <dd>Define this if the native-dependent code will provide its own routines
 165 <code>fetch_inferior_registers</code> and <code>store_inferior_registers</code> in
 166 <code></code><var>host</var><code>-nat.c</code>.  If this symbol is <em>not</em> defined, and
 167 <code>infptrace.c</code> is included in this configuration, the default
 168 routines in <code>infptrace.c</code> are used for these functions.
 169
 170      <br><dt><code>FILES_INFO_HOOK</code>
 171      <dd>(Only defined for Convex.)
 172
 173      <br><dt><code>FP0_REGNUM</code>
 174      <dd>This macro is normally defined to be the number of the first floating
 175 point register, if the machine has such registers.  As such, it would
 176 appear only in target-specific code.  However, <code>/proc</code> support uses this
 177 to decide whether floats are in use on this target.
 178
 179      <br><dt><code>GET_LONGJMP_TARGET</code>
 180      <dd>For most machines, this is a target-dependent parameter.  On the
 181 DECstation and the Iris, this is a native-dependent parameter, since
 182 <code>setjmp.h</code> is needed to define it.
 183
 184      <p>This macro determines the target PC address that <code>longjmp</code> will jump to,
 185 assuming that we have just stopped at a longjmp breakpoint.  It takes a
 186 <code>CORE_ADDR *</code> as argument, and stores the target PC value through this
 187 pointer.  It examines the current state of the machine as needed.
 188
 189      <br><dt><code>I386_USE_GENERIC_WATCHPOINTS</code>
 190      <dd>An x86-based machine can define this to use the generic x86 watchpoint
 191 support; see <a href="Algorithms.html#Algorithms">I386_USE_GENERIC_WATCHPOINTS</a>.
 192
 193      <br><dt><code>KERNEL_U_ADDR</code>
 194      <dd>Define this to the address of the <code>u</code> structure (the "user
 195 struct", also known as the "u-page") in kernel virtual memory.  GDB
 196 needs to know this so that it can subtract this address from absolute
 197 addresses in the upage, that are obtained via ptrace or from core files.
 198 On systems that don't need this value, set it to zero.
 199
 200      <br><dt><code>KERNEL_U_ADDR_BSD</code>
 201      <dd>Define this to cause GDB to determine the address of <code>u</code> at
 202 runtime, by using Berkeley-style <code>nlist</code> on the kernel's image in
 203 the root directory.
 204
 205      <br><dt><code>KERNEL_U_ADDR_HPUX</code>
 206      <dd>Define this to cause GDB to determine the address of <code>u</code> at
 207 runtime, by using HP-style <code>nlist</code> on the kernel's image in the
 208 root directory.
 209
 210      <br><dt><code>ONE_PROCESS_WRITETEXT</code>
 211      <dd>Define this to be able to, when a breakpoint insertion fails, warn the
 212 user that another process may be running with the same executable.
 213
 214      <br><dt><code>PREPARE_TO_PROCEED (</code><var>select_it</var><code>)</code>
 215      <dd>This (ugly) macro allows a native configuration to customize the way the
 216 <code>proceed</code> function in <code>infrun.c</code> deals with switching between
 217 threads.
 218
 219      <p>In a multi-threaded task we may select another thread and then continue
 220 or step.  But if the old thread was stopped at a breakpoint, it will
 221 immediately cause another breakpoint stop without any execution (i.e. it
 222 will report a breakpoint hit incorrectly).  So GDB must step over it
 223 first.
 224
 225      <p>If defined, <code>PREPARE_TO_PROCEED</code> should check the current thread
 226 against the thread that reported the most recent event.  If a step-over
 227 is required, it returns TRUE.  If <var>select_it</var> is non-zero, it should
 228 reselect the old thread.
 229
 230      <br><dt><code>PROC_NAME_FMT</code>
 231      <dd>Defines the format for the name of a <code>/proc</code> device.  Should be
 232 defined in <code>nm.h</code> <em>only</em> in order to override the default
 233 definition in <code>procfs.c</code>.
 234
 235      <br><dt><code>PTRACE_FP_BUG</code>
 236      <dd>See <code>mach386-xdep.c</code>.
 237
 238      <br><dt><code>PTRACE_ARG3_TYPE</code>
 239      <dd>The type of the third argument to the <code>ptrace</code> system call, if it
 240 exists and is different from <code>int</code>.
 241
 242      <br><dt><code>REGISTER_U_ADDR</code>
 243      <dd>Defines the offset of the registers in the "u area".
 244
 245      <br><dt><code>SHELL_COMMAND_CONCAT</code>
 246      <dd>If defined, is a string to prefix on the shell command used to start the
 247 inferior.
 248
 249      <br><dt><code>SHELL_FILE</code>
 250      <dd>If defined, this is the name of the shell to use to run the inferior.
 251 Defaults to <code>"/bin/sh"</code>.
 252
 253      <br><dt><code>SOLIB_ADD (</code><var>filename</var><code>, </code><var>from_tty</var><code>, </code><var>targ</var><code>, </code><var>readsyms</var><code>)</code>
 254      <dd>Define this to expand into an expression that will cause the symbols in
 255 <var>filename</var> to be added to GDB's symbol table. If
 256 <var>readsyms</var> is zero symbols are not read but any necessary low level
 257 processing for <var>filename</var> is still done.
 258
 259      <br><dt><code>SOLIB_CREATE_INFERIOR_HOOK</code>
 260      <dd>Define this to expand into any shared-library-relocation code that you
 261 want to be run just after the child process has been forked.
 262
 263      <br><dt><code>START_INFERIOR_TRAPS_EXPECTED</code>
 264      <dd>When starting an inferior, GDB normally expects to trap
 265 twice; once when
 266 the shell execs, and once when the program itself execs.  If the actual
 267 number of traps is something other than 2, then define this macro to
 268 expand into the number expected.
 269
 270      <br><dt><code>SVR4_SHARED_LIBS</code>
 271      <dd>Define this to indicate that SVR4-style shared libraries are in use.
 272
 273      <br><dt><code>USE_PROC_FS</code>
 274      <dd>This determines whether small routines in <code>*-tdep.c</code>, which
 275 translate register values between GDB's internal
 276 representation and the <code>/proc</code> representation, are compiled.
 277
 278      <br><dt><code>U_REGS_OFFSET</code>
 279      <dd>This is the offset of the registers in the upage.  It need only be
 280 defined if the generic ptrace register access routines in
 281 <code>infptrace.c</code> are being used (that is, <code>infptrace.c</code> is
 282 configured in, and <code>FETCH_INFERIOR_REGISTERS</code> is not defined).  If
 283 the default value from <code>infptrace.c</code> is good enough, leave it
 284 undefined.
 285
 286      <p>The default value means that u.u_ar0 <em>points to</em> the location of
 287 the registers.  I'm guessing that <code>#define U_REGS_OFFSET 0</code> means
 288 that <code>u.u_ar0</code> <em>is</em> the location of the registers.
 289
 290      <br><dt><code>CLEAR_SOLIB</code>
 291      <dd>See <code>objfiles.c</code>.
 292
 293      <br><dt><code>DEBUG_PTRACE</code>
 294      <dd>Define this to debug <code>ptrace</code> calls.
 295 </dl>
 296
 297    </body></html>
 298