mingw/info/gdbint/Algorithms.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="Algorithms">Algorithms</a>,
  13 Next:<a rel="next" accesskey="n" href="User-Interface.html#User%20Interface">User Interface</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Overall-Structure.html#Overall%20Structure">Overall Structure</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">Algorithms</h2>
  20
  21    GDB uses a number of debugging-specific algorithms.  They are
  22 often not very complicated, but get lost in the thicket of special
  23 cases and real-world issues.  This chapter describes the basic
  24 algorithms and mentions some of the specific target definitions that
  25 they use.
  26
  27 <h3 class="section">Frames</h3>
  28
  29    <p>A frame is a construct that GDB uses to keep track of calling
  30 and called functions.
  31
  32    <p><code>FRAME_FP</code> in the machine description has no meaning to the
  33 machine-independent part of GDB, except that it is used when
  34 setting up a new frame from scratch, as follows:
  35
  36 <pre class="example">           create_new_frame (read_register (FP_REGNUM), read_pc ()));
  37      </pre>
  38
  39    <p>Other than that, all the meaning imparted to <code>FP_REGNUM</code> is
  40 imparted by the machine-dependent code.  So, <code>FP_REGNUM</code> can have
  41 any value that is convenient for the code that creates new frames.
  42 (<code>create_new_frame</code> calls <code>INIT_EXTRA_FRAME_INFO</code> if it is
  43 defined; that is where you should use the <code>FP_REGNUM</code> value, if
  44 your frames are nonstandard.)
  45
  46    <p>Given a GDB frame, define <code>FRAME_CHAIN</code> to determine the
  47 address of the calling function's frame.  This will be used to create
  48 a new GDB frame struct, and then <code>INIT_EXTRA_FRAME_INFO</code>
  49 and <code>INIT_FRAME_PC</code> will be called for the new frame.
  50
  51 <h3 class="section">Breakpoint Handling</h3>
  52
  53    <p>In general, a breakpoint is a user-designated location in the program
  54 where the user wants to regain control if program execution ever reaches
  55 that location.
  56
  57    <p>There are two main ways to implement breakpoints; either as "hardware"
  58 breakpoints or as "software" breakpoints.
  59
  60    <p>Hardware breakpoints are sometimes available as a builtin debugging
  61 features with some chips.  Typically these work by having dedicated
  62 register into which the breakpoint address may be stored.  If the PC
  63 (shorthand for <dfn>program counter</dfn>)
  64 ever matches a value in a breakpoint registers, the CPU raises an
  65 exception and reports it to GDB.
  66
  67    <p>Another possibility is when an emulator is in use; many emulators
  68 include circuitry that watches the address lines coming out from the
  69 processor, and force it to stop if the address matches a breakpoint's
  70 address.
  71
  72    <p>A third possibility is that the target already has the ability to do
  73 breakpoints somehow; for instance, a ROM monitor may do its own
  74 software breakpoints.  So although these are not literally "hardware
  75 breakpoints", from GDB's point of view they work the same;
  76 GDB need not do nothing more than set the breakpoint and wait
  77 for something to happen.
  78
  79    <p>Since they depend on hardware resources, hardware breakpoints may be
  80 limited in number; when the user asks for more, GDB will
  81 start trying to set software breakpoints.  (On some architectures,
  82 notably the 32-bit x86 platforms, GDB cannot alsways know
  83 whether there's enough hardware resources to insert all the hardware
  84 breakpoints and watchpoints.  On those platforms, GDB prints
  85 an error message only when the program being debugged is continued.)
  86
  87    <p>Software breakpoints require GDB to do somewhat more work.
  88 The basic theory is that GDB will replace a program
  89 instruction with a trap, illegal divide, or some other instruction
  90 that will cause an exception, and then when it's encountered,
  91 GDB will take the exception and stop the program.  When the
  92 user says to continue, GDB will restore the original
  93 instruction, single-step, re-insert the trap, and continue on.
  94
  95    <p>Since it literally overwrites the program being tested, the program area
  96 must be writable, so this technique won't work on programs in ROM.  It
  97 can also distort the behavior of programs that examine themselves,
  98 although such a situation would be highly unusual.
  99
 100    <p>Also, the software breakpoint instruction should be the smallest size of
 101 instruction, so it doesn't overwrite an instruction that might be a jump
 102 target, and cause disaster when the program jumps into the middle of the
 103 breakpoint instruction.  (Strictly speaking, the breakpoint must be no
 104 larger than the smallest interval between instructions that may be jump
 105 targets; perhaps there is an architecture where only even-numbered
 106 instructions may jumped to.)  Note that it's possible for an instruction
 107 set not to have any instructions usable for a software breakpoint,
 108 although in practice only the ARC has failed to define such an
 109 instruction.
 110
 111    <p>The basic definition of the software breakpoint is the macro
 112 <code>BREAKPOINT</code>.
 113
 114    <p>Basic breakpoint object handling is in <code>breakpoint.c</code>.  However,
 115 much of the interesting breakpoint action is in <code>infrun.c</code>.
 116
 117 <h3 class="section">Single Stepping</h3>
 118
 119 <h3 class="section">Signal Handling</h3>
 120
 121 <h3 class="section">Thread Handling</h3>
 122
 123 <h3 class="section">Inferior Function Calls</h3>
 124
 125 <h3 class="section">Longjmp Support</h3>
 126
 127    GDB has support for figuring out that the target is doing a
 128 <code>longjmp</code> and for stopping at the target of the jump, if we are
 129 stepping.  This is done with a few specialized internal breakpoints,
 130 which are visible in the output of the <code>maint info breakpoint</code>
 131 command.
 132
 133    <p>To make this work, you need to define a macro called
 134 <code>GET_LONGJMP_TARGET</code>, which will examine the <code>jmp_buf</code>
 135 structure and extract the longjmp target address.  Since <code>jmp_buf</code>
 136 is target specific, you will need to define it in the appropriate
 137 <code>tm-</code><var>target</var><code>.h</code> file.  Look in <code>tm-sun4os4.h</code> and
 138 <code>sparc-tdep.c</code> for examples of how to do this.
 139
 140 <h3 class="section">Watchpoints</h3>
 141
 142    <p>Watchpoints are a special kind of breakpoints (see <a href="Algorithms.html#Algorithms">breakpoints</a>) which break when data is accessed rather than when some
 143 instruction is executed.  When you have data which changes without
 144 your knowing what code does that, watchpoints are the silver bullet to
 145 hunt down and kill such bugs.
 146
 147    <p>Watchpoints can be either hardware-assisted or not; the latter type is
 148 known as "software watchpoints."  GDB always uses
 149 hardware-assisted watchpoints if they are available, and falls back on
 150 software watchpoints otherwise.  Typical situations where GDB
 151 will use software watchpoints are:
 152
 153      <ul>
 154 <li>The watched memory region is too large for the underlying hardware
 155 watchpoint support.  For example, each x86 debug register can watch up
 156 to 4 bytes of memory, so trying to watch data structures whose size is
 157 more than 16 bytes will cause GDB to use software
 158 watchpoints.
 159
 160      <li>The value of the expression to be watched depends on data held in
 161 registers (as opposed to memory).
 162
 163      <li>Too many different watchpoints requested.  (On some architectures,
 164 this situation is impossible to detect until the debugged program is
 165 resumed.)  Note that x86 debug registers are used both for hardware
 166 breakpoints and for watchpoints, so setting too many hardware
 167 breakpoints might cause watchpoint insertion to fail.
 168
 169      <li>No hardware-assisted watchpoints provided by the target
 170 implementation.
 171 </ul>
 172
 173    <p>Software watchpoints are very slow, since GDB needs to
 174 single-step the program being debugged and test the value of the
 175 watched expression(s) after each instruction.  The rest of this
 176 section is mostly irrelevant for software watchpoints.
 177
 178    GDB uses several macros and primitives to support hardware
 179 watchpoints:
 180
 181      <dl>
 182 <dt><code>TARGET_HAS_HARDWARE_WATCHPOINTS</code>
 183      <dd>If defined, the target supports hardware watchpoints.
 184
 185      <br><dt><code>TARGET_CAN_USE_HARDWARE_WATCHPOINT (</code><var>type</var><code>, </code><var>count</var><code>, </code><var>other</var><code>)</code>
 186      <dd>Return the number of hardware watchpoints of type <var>type</var> that are
 187 possible to be set.  The value is positive if <var>count</var> watchpoints
 188 of this type can be set, zero if setting watchpoints of this type is
 189 not supported, and negative if <var>count</var> is more than the maximum
 190 number of watchpoints of type <var>type</var> that can be set.  <var>other</var>
 191 is non-zero if other types of watchpoints are currently enabled (there
 192 are architectures which cannot set watchpoints of different types at
 193 the same time).
 194
 195      <br><dt><code>TARGET_REGION_OK_FOR_HW_WATCHPOINT (</code><var>addr</var><code>, </code><var>len</var><code>)</code>
 196      <dd>Return non-zero if hardware watchpoints can be used to watch a region
 197 whose address is <var>addr</var> and whose length in bytes is <var>len</var>.
 198
 199      <br><dt><code>TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (</code><var>size</var><code>)</code>
 200      <dd>Return non-zero if hardware watchpoints can be used to watch a region
 201 whose size is <var>size</var>.  GDB only uses this macro as a
 202 fall-back, in case <code>TARGET_REGION_OK_FOR_HW_WATCHPOINT</code> is not
 203 defined.
 204
 205      <br><dt><code>TARGET_DISABLE_HW_WATCHPOINTS (</code><var>pid</var><code>)</code>
 206      <dd>Disables watchpoints in the process identified by <var>pid</var>.  This is
 207 used, e.g., on HP-UX which provides operations to disable and enable
 208 the page-level memory protection that implements hardware watchpoints
 209 on that platform.
 210
 211      <br><dt><code>TARGET_ENABLE_HW_WATCHPOINTS (</code><var>pid</var><code>)</code>
 212      <dd>Enables watchpoints in the process identified by <var>pid</var>.  This is
 213 used, e.g., on HP-UX which provides operations to disable and enable
 214 the page-level memory protection that implements hardware watchpoints
 215 on that platform.
 216
 217      <br><dt><code>target_insert_watchpoint (</code><var>addr</var><code>, </code><var>len</var><code>, </code><var>type</var><code>)</code>
 218      <dd><dt><code>target_remove_watchpoint (</code><var>addr</var><code>, </code><var>len</var><code>, </code><var>type</var><code>)</code>
 219      <dd>Insert or remove a hardware watchpoint starting at <var>addr</var>, for
 220 <var>len</var> bytes.  <var>type</var> is the watchpoint type, one of the
 221 possible values of the enumerated data type <code>target_hw_bp_type</code>,
 222 defined by <code>breakpoint.h</code> as follows:
 223
 224      <pre class="example">           enum target_hw_bp_type
 225              {
 226                hw_write   = 0, /* Common (write) HW watchpoint */
 227                hw_read    = 1, /* Read    HW watchpoint */
 228                hw_access  = 2, /* Access (read or write) HW watchpoint */
 229                hw_execute = 3  /* Execute HW breakpoint */
 230              };
 231           </pre>
 232
 233      <p>These two macros should return 0 for success, non-zero for failure.
 234
 235      <br><dt><code>target_remove_hw_breakpoint (</code><var>addr</var><code>, </code><var>shadow</var><code>)</code>
 236      <dd><dt><code>target_insert_hw_breakpoint (</code><var>addr</var><code>, </code><var>shadow</var><code>)</code>
 237      <dd>Insert or remove a hardware-assisted breakpoint at address <var>addr</var>.
 238 Returns zero for success, non-zero for failure.  <var>shadow</var> is the
 239 real contents of the byte where the breakpoint has been inserted; it
 240 is generally not valid when hardware breakpoints are used, but since
 241 no other code touches these values, the implementations of the above
 242 two macros can use them for their internal purposes.
 243
 244      <br><dt><code>target_stopped_data_address ()</code>
 245      <dd>If the inferior has some watchpoint that triggered, return the address
 246 associated with that watchpoint.  Otherwise, return zero.
 247
 248      <br><dt><code>DECR_PC_AFTER_HW_BREAK</code>
 249      <dd>If defined, GDB decrements the program counter by the value
 250 of <code>DECR_PC_AFTER_HW_BREAK</code> after a hardware break-point.  This
 251 overrides the value of <code>DECR_PC_AFTER_BREAK</code> when a breakpoint
 252 that breaks is a hardware-assisted breakpoint.
 253
 254      <br><dt><code>HAVE_STEPPABLE_WATCHPOINT</code>
 255      <dd>If defined to a non-zero value, it is not necessary to disable a
 256 watchpoint to step over it.
 257
 258      <br><dt><code>HAVE_NONSTEPPABLE_WATCHPOINT</code>
 259      <dd>If defined to a non-zero value, GDB should disable a
 260 watchpoint to step the inferior over it.
 261
 262      <br><dt><code>HAVE_CONTINUABLE_WATCHPOINT</code>
 263      <dd>If defined to a non-zero value, it is possible to continue the
 264 inferior after a watchpoint has been hit.
 265
 266      <br><dt><code>CANNOT_STEP_HW_WATCHPOINTS</code>
 267      <dd>If this is defined to a non-zero value, GDB will remove all
 268 watchpoints before stepping the inferior.
 269
 270      <br><dt><code>STOPPED_BY_WATCHPOINT (</code><var>wait_status</var><code>)</code>
 271      <dd>Return non-zero if stopped by a watchpoint.  <var>wait_status</var> is of
 272 the type <code>struct target_waitstatus</code>, defined by <code>target.h</code>.
 273 </dl>
 274
 275 <h4 class="subsection">x86 Watchpoints</h4>
 276
 277    <p>The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug
 278 registers designed to facilitate debugging.  GDB provides a
 279 generic library of functions that x86-based ports can use to implement
 280 support for watchpoints and hardware-assisted breakpoints.  This
 281 subsection documents the x86 watchpoint facilities in GDB.
 282
 283    <p>To use the generic x86 watchpoint support, a port should do the
 284 following:
 285
 286      <ul>
 287 <li>Define the macro <code>I386_USE_GENERIC_WATCHPOINTS</code> somewhere in the
 288 target-dependent headers.
 289
 290      <li>Include the <code>config/i386/nm-i386.h</code> header file <em>after</em>
 291 defining <code>I386_USE_GENERIC_WATCHPOINTS</code>.
 292
 293      <li>Add <code>i386-nat.o</code> to the value of the Make variable
 294 <code>NATDEPFILES</code> (see <a href="Native-Debugging.html#Native%20Debugging">NATDEPFILES</a>) or
 295 <code>TDEPFILES</code> (see <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">TDEPFILES</a>).
 296
 297      <li>Provide implementations for the <code>I386_DR_LOW_*</code> macros described
 298 below.  Typically, each macro should call a target-specific function
 299 which does the real work.
 300 </ul>
 301
 302    <p>The x86 watchpoint support works by maintaining mirror images of the
 303 debug registers.  Values are copied between the mirror images and the
 304 real debug registers via a set of macros which each target needs to
 305 provide:
 306
 307      <dl>
 308 <dt><code>I386_DR_LOW_SET_CONTROL (</code><var>val</var><code>)</code>
 309      <dd>Set the Debug Control (DR7) register to the value <var>val</var>.
 310
 311      <br><dt><code>I386_DR_LOW_SET_ADDR (</code><var>idx</var><code>, </code><var>addr</var><code>)</code>
 312      <dd>Put the address <var>addr</var> into the debug register number <var>idx</var>.
 313
 314      <br><dt><code>I386_DR_LOW_RESET_ADDR (</code><var>idx</var><code>)</code>
 315      <dd>Reset (i.e. zero out) the address stored in the debug register
 316 number <var>idx</var>.
 317
 318      <br><dt><code>I386_DR_LOW_GET_STATUS</code>
 319      <dd>Return the value of the Debug Status (DR6) register.  This value is
 320 used immediately after it is returned by
 321 <code>I386_DR_LOW_GET_STATUS</code>, so as to support per-thread status
 322 register values.
 323 </dl>
 324
 325    <p>For each one of the 4 debug registers (whose indices are from 0 to 3)
 326 that store addresses, a reference count is maintained by GDB,
 327 to allow sharing of debug registers by several watchpoints.  This
 328 allows users to define several watchpoints that watch the same
 329 expression, but with different conditions and/or commands, without
 330 wasting debug registers which are in short supply.  GDB
 331 maintains the reference counts internally, targets don't have to do
 332 anything to use this feature.
 333
 334    <p>The x86 debug registers can each watch a region that is 1, 2, or 4
 335 bytes long.  The ia32 architecture requires that each watched region
 336 be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
 337 region on 4-byte boundary.  However, the x86 watchpoint support in
 338 GDB can watch unaligned regions and regions larger than 4
 339 bytes (up to 16 bytes) by allocating several debug registers to watch
 340 a single region.  This allocation of several registers per a watched
 341 region is also done automatically without target code intervention.
 342
 343    <p>The generic x86 watchpoint support provides the following API for the
 344 GDB's application code:
 345
 346      <dl>
 347 <dt><code>i386_region_ok_for_watchpoint (</code><var>addr</var><code>, </code><var>len</var><code>)</code>
 348      <dd>The macro <code>TARGET_REGION_OK_FOR_HW_WATCHPOINT</code> is set to call
 349 this function.  It counts the number of debug registers required to
 350 watch a given region, and returns a non-zero value if that number is
 351 less than 4, the number of debug registers available to x86
 352 processors.
 353
 354      <br><dt><code>i386_stopped_data_address (void)</code>
 355      <dd>The macros <code>STOPPED_BY_WATCHPOINT</code> and
 356 <code>target_stopped_data_address</code> are set to call this function.  The
 357 argument passed to <code>STOPPED_BY_WATCHPOINT</code> is ignored.  This
 358 function examines the breakpoint condition bits in the DR6 Debug
 359 Status register, as returned by the <code>I386_DR_LOW_GET_STATUS</code>
 360 macro, and returns the address associated with the first bit that is
 361 set in DR6.
 362
 363      <br><dt><code>i386_insert_watchpoint (</code><var>addr</var><code>, </code><var>len</var><code>, </code><var>type</var><code>)</code>
 364      <dd><dt><code>i386_remove_watchpoint (</code><var>addr</var><code>, </code><var>len</var><code>, </code><var>type</var><code>)</code>
 365      <dd>Insert or remove a watchpoint.  The macros
 366 <code>target_insert_watchpoint</code> and <code>target_remove_watchpoint</code>
 367 are set to call these functions.  <code>i386_insert_watchpoint</code> first
 368 looks for a debug register which is already set to watch the same
 369 region for the same access types; if found, it just increments the
 370 reference count of that debug register, thus implementing debug
 371 register sharing between watchpoints.  If no such register is found,
 372 the function looks for a vacant debug register, sets its mirrorred
 373 value to <var>addr</var>, sets the mirrorred value of DR7 Debug Control
 374 register as appropriate for the <var>len</var> and <var>type</var> parameters,
 375 and then passes the new values of the debug register and DR7 to the
 376 inferior by calling <code>I386_DR_LOW_SET_ADDR</code> and
 377 <code>I386_DR_LOW_SET_CONTROL</code>.  If more than one debug register is
 378 required to cover the given region, the above process is repeated for
 379 each debug register.
 380
 381      <p><code>i386_remove_watchpoint</code> does the opposite: it resets the address
 382 in the mirrorred value of the debug register and its read/write and
 383 length bits in the mirrorred value of DR7, then passes these new
 384 values to the inferior via <code>I386_DR_LOW_RESET_ADDR</code> and
 385 <code>I386_DR_LOW_SET_CONTROL</code>.  If a register is shared by several
 386 watchpoints, each time a <code>i386_remove_watchpoint</code> is called, it
 387 decrements the reference count, and only calls
 388 <code>I386_DR_LOW_RESET_ADDR</code> and <code>I386_DR_LOW_SET_CONTROL</code> when
 389 the count goes to zero.
 390
 391      <br><dt><code>i386_insert_hw_breakpoint (</code><var>addr</var><code>, </code><var>shadow</var><code></code>
 392      <dd><dt><code>i386_remove_hw_breakpoint (</code><var>addr</var><code>, </code><var>shadow</var><code>)</code>
 393      <dd>These functions insert and remove hardware-assisted breakpoints.  The
 394 macros <code>target_insert_hw_breakpoint</code> and
 395 <code>target_remove_hw_breakpoint</code> are set to call these functions.
 396 These functions work like <code>i386_insert_watchpoint</code> and
 397 <code>i386_remove_watchpoint</code>, respectively, except that they set up
 398 the debug registers to watch instruction execution, and each
 399 hardware-assisted breakpoint always requires exactly one debug
 400 register.
 401
 402      <br><dt><code>i386_stopped_by_hwbp (void)</code>
 403      <dd>This function returns non-zero if the inferior has some watchpoint or
 404 hardware breakpoint that triggered.  It works like
 405 <code>i386_stopped_data_address</code>, except that it doesn't return the
 406 address whose watchpoint triggered.
 407
 408      <br><dt><code>i386_cleanup_dregs (void)</code>
 409      <dd>This function clears all the reference counts, addresses, and control
 410 bits in the mirror images of the debug registers.  It doesn't affect
 411 the actual debug registers in the inferior process.
 412 </dl>
 413
 414 <p><strong>Notes:</strong>
 415      <ol type=1 start=1>
 416 <li>x86 processors support setting watchpoints on I/O reads or writes.
 417 However, since no target supports this (as of March 2001), and since
 418 <code>enum target_hw_bp_type</code> doesn't even have an enumeration for I/O
 419 watchpoints, this feature is not yet available to GDB running
 420 on x86.
 421
 422      <li>x86 processors can enable watchpoints locally, for the current task
 423 only, or globally, for all the tasks.  For each debug register,
 424 there's a bit in the DR7 Debug Control register that determines
 425 whether the associated address is watched locally or globally.  The
 426 current implementation of x86 watchpoint support in GDB
 427 always sets watchpoints to be locally enabled, since global
 428 watchpoints might interfere with the underlying OS and are probably
 429 unavailable in many platforms.
 430         </ol>
 431
 432    </body></html>
 433