mingw/info/gdbint/Target-Architecture-Definition.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="Target%20Architecture%20Definition">Target Architecture Definition</a>,
  13 Next:<a rel="next" accesskey="n" href="Target-Vector-Definition.html#Target%20Vector%20Definition">Target Vector Definition</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Host-Definition.html#Host%20Definition">Host 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">Target Architecture Definition</h2>
  20
  21    GDB's target architecture defines what sort of
  22 machine-language programs GDB can work with, and how it works
  23 with them.
  24
  25    <p>The target architecture object is implemented as the C structure
  26 <code>struct gdbarch *</code>.  The structure, and its methods, are generated
  27 using the Bourne shell script <code>gdbarch.sh</code>.
  28
  29 <h3 class="section">Registers and Memory</h3>
  30
  31    GDB's model of the target machine is rather simple.
  32 GDB assumes the machine includes a bank of registers and a
  33 block of memory.  Each register may have a different size.
  34
  35    GDB does not have a magical way to match up with the
  36 compiler's idea of which registers are which; however, it is critical
  37 that they do match up accurately.  The only way to make this work is
  38 to get accurate information about the order that the compiler uses,
  39 and to reflect that in the <code>REGISTER_NAME</code> and related macros.
  40
  41    GDB can handle big-endian, little-endian, and bi-endian architectures.
  42
  43 <h3 class="section">Pointers Are Not Always Addresses</h3>
  44
  45    <p>On almost all 32-bit architectures, the representation of a pointer is
  46 indistinguishable from the representation of some fixed-length number
  47 whose value is the byte address of the object pointed to.  On such
  48 machines, the words "pointer" and "address" can be used interchangeably.
  49 However, architectures with smaller word sizes are often cramped for
  50 address space, so they may choose a pointer representation that breaks this
  51 identity, and allows a larger code address space.
  52
  53    <p>For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
  54 instructions are 32 bits long<a rel="footnote" href="#fn-1"><sup>1</sup></a>.
  55 If the D10V used ordinary byte addresses to refer to code locations,
  56 then the processor would only be able to address 64kb of instructions.
  57 However, since instructions must be aligned on four-byte boundaries, the
  58 low two bits of any valid instruction's byte address are always
  59 zero--byte addresses waste two bits.  So instead of byte addresses,
  60 the D10V uses word addresses--byte addresses shifted right two bits--to
  61 refer to code.  Thus, the D10V can use 16-bit words to address 256kb of
  62 code space.
  63
  64    <p>However, this means that code pointers and data pointers have different
  65 forms on the D10V.  The 16-bit word <code>0xC020</code> refers to byte address
  66 <code>0xC020</code> when used as a data address, but refers to byte address
  67 <code>0x30080</code> when used as a code address.
  68
  69    <p>(The D10V also uses separate code and data address spaces, which also
  70 affects the correspondence between pointers and addresses, but we're
  71 going to ignore that here; this example is already too long.)
  72
  73    <p>To cope with architectures like this--the D10V is not the only
  74 one!--GDB tries to distinguish between <dfn>addresses</dfn>, which are
  75 byte numbers, and <dfn>pointers</dfn>, which are the target's representation
  76 of an address of a particular type of data.  In the example above,
  77 <code>0xC020</code> is the pointer, which refers to one of the addresses
  78 <code>0xC020</code> or <code>0x30080</code>, depending on the type imposed upon it.
  79 GDB provides functions for turning a pointer into an address
  80 and vice versa, in the appropriate way for the current architecture.
  81
  82    <p>Unfortunately, since addresses and pointers are identical on almost all
  83 processors, this distinction tends to bit-rot pretty quickly.  Thus,
  84 each time you port GDB to an architecture which does
  85 distinguish between pointers and addresses, you'll probably need to
  86 clean up some architecture-independent code.
  87
  88    <p>Here are functions which convert between pointers and addresses:
  89
  90 <p>
  91 <table width="100%">
  92 <tr>
  93 <td align="left">CORE_ADDR <b>extract_typed_address</b><i> </i>(<i>void *</i><var>buf</var><i>, struct type *</i><var>type</var><i></i>)<i>
  94      </i></td>
  95 <td align="right">Function</td>
  96 </tr>
  97 </table>
  98 <table width="95%" align="center">
  99 <tr><td>
 100 Treat the bytes at <var>buf</var> as a pointer or reference of type
 101 <var>type</var>, and return the address it represents, in a manner
 102 appropriate for the current architecture.  This yields an address
 103 GDB can use to read target memory, disassemble, etc.  Note that
 104 <var>buf</var> refers to a buffer in GDB's memory, not the
 105 inferior's.
 106
 107      <p>For example, if the current architecture is the Intel x86, this function
 108 extracts a little-endian integer of the appropriate length from
 109 <var>buf</var> and returns it.  However, if the current architecture is the
 110 D10V, this function will return a 16-bit integer extracted from
 111 <var>buf</var>, multiplied by four if <var>type</var> is a pointer to a function.
 112
 113      <p>If <var>type</var> is not a pointer or reference type, then this function
 114 will signal an internal error.
 115 </td></tr>
 116 </table>
 117
 118 <p>
 119 <table width="100%">
 120 <tr>
 121 <td align="left">CORE_ADDR <b>store_typed_address</b><i> </i>(<i>void *</i><var>buf</var><i>, struct type *</i><var>type</var><i>, CORE_ADDR </i><var>addr</var><i></i>)<i>
 122      </i></td>
 123 <td align="right">Function</td>
 124 </tr>
 125 </table>
 126 <table width="95%" align="center">
 127 <tr><td>
 128 Store the address <var>addr</var> in <var>buf</var>, in the proper format for a
 129 pointer of type <var>type</var> in the current architecture.  Note that
 130 <var>buf</var> refers to a buffer in GDB's memory, not the
 131 inferior's.
 132
 133      <p>For example, if the current architecture is the Intel x86, this function
 134 stores <var>addr</var> unmodified as a little-endian integer of the
 135 appropriate length in <var>buf</var>.  However, if the current architecture
 136 is the D10V, this function divides <var>addr</var> by four if <var>type</var> is
 137 a pointer to a function, and then stores it in <var>buf</var>.
 138
 139      <p>If <var>type</var> is not a pointer or reference type, then this function
 140 will signal an internal error.
 141 </td></tr>
 142 </table>
 143
 144 <p>
 145 <table width="100%">
 146 <tr>
 147 <td align="left">CORE_ADDR <b>value_as_address</b><i> </i>(<i>struct value *</i><var>val</var><i></i>)<i>
 148      </i></td>
 149 <td align="right">Function</td>
 150 </tr>
 151 </table>
 152 <table width="95%" align="center">
 153 <tr><td>
 154 Assuming that <var>val</var> is a pointer, return the address it represents,
 155 as appropriate for the current architecture.
 156
 157      <p>This function actually works on integral values, as well as pointers.
 158 For pointers, it performs architecture-specific conversions as
 159 described above for <code>extract_typed_address</code>.
 160 </td></tr>
 161 </table>
 162
 163 <p>
 164 <table width="100%">
 165 <tr>
 166 <td align="left">CORE_ADDR <b>value_from_pointer</b><i> </i>(<i>struct type *</i><var>type</var><i>, CORE_ADDR </i><var>addr</var><i></i>)<i>
 167      </i></td>
 168 <td align="right">Function</td>
 169 </tr>
 170 </table>
 171 <table width="95%" align="center">
 172 <tr><td>
 173 Create and return a value representing a pointer of type <var>type</var> to
 174 the address <var>addr</var>, as appropriate for the current architecture.
 175 This function performs architecture-specific conversions as described
 176 above for <code>store_typed_address</code>.
 177 </td></tr>
 178 </table>
 179
 180    GDB also provides functions that do the same tasks, but assume
 181 that pointers are simply byte addresses; they aren't sensitive to the
 182 current architecture, beyond knowing the appropriate endianness.
 183
 184 <p>
 185 <table width="100%">
 186 <tr>
 187 <td align="left">CORE_ADDR <b>extract_address</b><i> </i>(<i>void *</i><var>addr</var><i>, int len</i>)<i>
 188      </i></td>
 189 <td align="right">Function</td>
 190 </tr>
 191 </table>
 192 <table width="95%" align="center">
 193 <tr><td>
 194 Extract a <var>len</var>-byte number from <var>addr</var> in the appropriate
 195 endianness for the current architecture, and return it.  Note that
 196 <var>addr</var> refers to GDB's memory, not the inferior's.
 197
 198      <p>This function should only be used in architecture-specific code; it
 199 doesn't have enough information to turn bits into a true address in the
 200 appropriate way for the current architecture.  If you can, use
 201 <code>extract_typed_address</code> instead.
 202 </td></tr>
 203 </table>
 204
 205 <p>
 206 <table width="100%">
 207 <tr>
 208 <td align="left">void <b>store_address</b><i> </i>(<i>void *</i><var>addr</var><i>, int </i><var>len</var><i>, LONGEST </i><var>val</var><i></i>)<i>
 209      </i></td>
 210 <td align="right">Function</td>
 211 </tr>
 212 </table>
 213 <table width="95%" align="center">
 214 <tr><td>
 215 Store <var>val</var> at <var>addr</var> as a <var>len</var>-byte integer, in the
 216 appropriate endianness for the current architecture.  Note that
 217 <var>addr</var> refers to a buffer in GDB's memory, not the
 218 inferior's.
 219
 220      <p>This function should only be used in architecture-specific code; it
 221 doesn't have enough information to turn a true address into bits in the
 222 appropriate way for the current architecture.  If you can, use
 223 <code>store_typed_address</code> instead.
 224 </td></tr>
 225 </table>
 226
 227    <p>Here are some macros which architectures can define to indicate the
 228 relationship between pointers and addresses.  These have default
 229 definitions, appropriate for architectures on which all pointers are
 230 simple unsigned byte addresses.
 231
 232 <p>
 233 <table width="100%">
 234 <tr>
 235 <td align="left">CORE_ADDR <b>POINTER_TO_ADDRESS</b><i> </i>(<i>struct type *</i><var>type</var><i>, char *</i><var>buf</var><i></i>)<i>
 236      </i></td>
 237 <td align="right">Target Macro</td>
 238 </tr>
 239 </table>
 240 <table width="95%" align="center">
 241 <tr><td>
 242 Assume that <var>buf</var> holds a pointer of type <var>type</var>, in the
 243 appropriate format for the current architecture.  Return the byte
 244 address the pointer refers to.
 245
 246      <p>This function may safely assume that <var>type</var> is either a pointer or a
 247 C<tt>++</tt> reference type.
 248 </td></tr>
 249 </table>
 250
 251 <p>
 252 <table width="100%">
 253 <tr>
 254 <td align="left">void <b>ADDRESS_TO_POINTER</b><i> </i>(<i>struct type *</i><var>type</var><i>, char *</i><var>buf</var><i>, CORE_ADDR </i><var>addr</var><i></i>)<i>
 255      </i></td>
 256 <td align="right">Target Macro</td>
 257 </tr>
 258 </table>
 259 <table width="95%" align="center">
 260 <tr><td>
 261 Store in <var>buf</var> a pointer of type <var>type</var> representing the address
 262 <var>addr</var>, in the appropriate format for the current architecture.
 263
 264      <p>This function may safely assume that <var>type</var> is either a pointer or a
 265 C<tt>++</tt> reference type.
 266 </td></tr>
 267 </table>
 268
 269 <h3 class="section">Using Different Register and Memory Data Representations</h3>
 270
 271    <p><em>Maintainer's note: The way GDB manipulates registers is undergoing
 272 significant change.  Many of the macros and functions refered to in the
 273 sections below are likely to be made obsolete.  See the file </em><code>TODO</code><em>
 274 for more up-to-date information.</em>
 275
 276    <p>Some architectures use one representation for a value when it lives in a
 277 register, but use a different representation when it lives in memory.
 278 In GDB's terminology, the <dfn>raw</dfn> representation is the one used in
 279 the target registers, and the <dfn>virtual</dfn> representation is the one
 280 used in memory, and within GDB <code>struct value</code> objects.
 281
 282    <p>For almost all data types on almost all architectures, the virtual and
 283 raw representations are identical, and no special handling is needed.
 284 However, they do occasionally differ.  For example:
 285
 286      <ul>
 287 <li>The x86 architecture supports an 80-bit <code>long double</code> type.  However, when
 288 we store those values in memory, they occupy twelve bytes: the
 289 floating-point number occupies the first ten, and the final two bytes
 290 are unused.  This keeps the values aligned on four-byte boundaries,
 291 allowing more efficient access.  Thus, the x86 80-bit floating-point
 292 type is the raw representation, and the twelve-byte loosely-packed
 293 arrangement is the virtual representation.
 294
 295      <li>Some 64-bit MIPS targets present 32-bit registers to GDB as 64-bit
 296 registers, with garbage in their upper bits.  GDB ignores the top 32
 297 bits.  Thus, the 64-bit form, with garbage in the upper 32 bits, is the
 298 raw representation, and the trimmed 32-bit representation is the
 299 virtual representation.
 300 </ul>
 301
 302    <p>In general, the raw representation is determined by the architecture, or
 303 GDB's interface to the architecture, while the virtual representation
 304 can be chosen for GDB's convenience.  GDB's register file,
 305 <code>registers</code>, holds the register contents in raw format, and the
 306 GDB remote protocol transmits register values in raw format.
 307
 308    <p>Your architecture may define the following macros to request
 309 conversions between the raw and virtual format:
 310
 311 <p>
 312 <table width="100%">
 313 <tr>
 314 <td align="left">int <b>REGISTER_CONVERTIBLE</b><i> </i>(<i>int </i><var>reg</var><i></i>)<i>
 315      </i></td>
 316 <td align="right">Target Macro</td>
 317 </tr>
 318 </table>
 319 <table width="95%" align="center">
 320 <tr><td>
 321 Return non-zero if register number <var>reg</var>'s value needs different raw
 322 and virtual formats.
 323
 324      <p>You should not use <code>REGISTER_CONVERT_TO_VIRTUAL</code> for a register
 325 unless this macro returns a non-zero value for that register.
 326 </td></tr>
 327 </table>
 328
 329 <p>
 330 <table width="100%">
 331 <tr>
 332 <td align="left">int <b>REGISTER_RAW_SIZE</b><i> </i>(<i>int </i><var>reg</var><i></i>)<i>
 333      </i></td>
 334 <td align="right">Target Macro</td>
 335 </tr>
 336 </table>
 337 <table width="95%" align="center">
 338 <tr><td>
 339 The size of register number <var>reg</var>'s raw value.  This is the number
 340 of bytes the register will occupy in <code>registers</code>, or in a GDB
 341 remote protocol packet.
 342 </td></tr>
 343 </table>
 344
 345 <p>
 346 <table width="100%">
 347 <tr>
 348 <td align="left">int <b>REGISTER_VIRTUAL_SIZE</b><i> </i>(<i>int </i><var>reg</var><i></i>)<i>
 349      </i></td>
 350 <td align="right">Target Macro</td>
 351 </tr>
 352 </table>
 353 <table width="95%" align="center">
 354 <tr><td>
 355 The size of register number <var>reg</var>'s value, in its virtual format.
 356 This is the size a <code>struct value</code>'s buffer will have, holding that
 357 register's value.
 358 </td></tr>
 359 </table>
 360
 361 <p>
 362 <table width="100%">
 363 <tr>
 364 <td align="left">struct <b>type</b><i> *REGISTER_VIRTUAL_TYPE </i>(<i>int </i><var>reg</var><i></i>)<i>
 365      </i></td>
 366 <td align="right">Target Macro</td>
 367 </tr>
 368 </table>
 369 <table width="95%" align="center">
 370 <tr><td>
 371 This is the type of the virtual representation of register number
 372 <var>reg</var>.  Note that there is no need for a macro giving a type for the
 373 register's raw form; once the register's value has been obtained, GDB
 374 always uses the virtual form.
 375 </td></tr>
 376 </table>
 377
 378 <p>
 379 <table width="100%">
 380 <tr>
 381 <td align="left">void <b>REGISTER_CONVERT_TO_VIRTUAL</b><i> </i>(<i>int </i><var>reg</var><i>, struct type *</i><var>type</var><i>, char *</i><var>from</var><i>, char *</i><var>to</var><i></i>)<i>
 382      </i></td>
 383 <td align="right">Target Macro</td>
 384 </tr>
 385 </table>
 386 <table width="95%" align="center">
 387 <tr><td>
 388 Convert the value of register number <var>reg</var> to <var>type</var>, which
 389 should always be <code>REGISTER_VIRTUAL_TYPE (</code><var>reg</var><code>)</code>.  The buffer
 390 at <var>from</var> holds the register's value in raw format; the macro should
 391 convert the value to virtual format, and place it at <var>to</var>.
 392
 393      <p>Note that <code>REGISTER_CONVERT_TO_VIRTUAL</code> and
 394 <code>REGISTER_CONVERT_TO_RAW</code> take their <var>reg</var> and <var>type</var>
 395 arguments in different orders.
 396
 397      <p>You should only use <code>REGISTER_CONVERT_TO_VIRTUAL</code> with registers
 398 for which the <code>REGISTER_CONVERTIBLE</code> macro returns a non-zero
 399 value.
 400 </td></tr>
 401 </table>
 402
 403 <p>
 404 <table width="100%">
 405 <tr>
 406 <td align="left">void <b>REGISTER_CONVERT_TO_RAW</b><i> </i>(<i>struct type *</i><var>type</var><i>, int </i><var>reg</var><i>, char *</i><var>from</var><i>, char *</i><var>to</var><i></i>)<i>
 407      </i></td>
 408 <td align="right">Target Macro</td>
 409 </tr>
 410 </table>
 411 <table width="95%" align="center">
 412 <tr><td>
 413 Convert the value of register number <var>reg</var> to <var>type</var>, which
 414 should always be <code>REGISTER_VIRTUAL_TYPE (</code><var>reg</var><code>)</code>.  The buffer
 415 at <var>from</var> holds the register's value in raw format; the macro should
 416 convert the value to virtual format, and place it at <var>to</var>.
 417
 418      <p>Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
 419 their <var>reg</var> and <var>type</var> arguments in different orders.
 420 </td></tr>
 421 </table>
 422
 423 <h3 class="section">Frame Interpretation</h3>
 424
 425 <h3 class="section">Inferior Call Setup</h3>
 426
 427 <h3 class="section">Compiler Characteristics</h3>
 428
 429 <h3 class="section">Target Conditionals</h3>
 430
 431    <p>This section describes the macros that you can use to define the target
 432 machine.
 433
 434      <dl>
 435
 436      <br><dt><code>ADDITIONAL_OPTIONS</code>
 437      <dd><dt><code>ADDITIONAL_OPTION_CASES</code>
 438      <dd><dt><code>ADDITIONAL_OPTION_HANDLER</code>
 439      <dd><dt><code>ADDITIONAL_OPTION_HELP</code>
 440      <dd>These are a set of macros that allow the addition of additional command
 441 line options to GDB.  They are currently used only for the unsupported
 442 i960 Nindy target, and should not be used in any other configuration.
 443
 444      <br><dt><code>ADDR_BITS_REMOVE (addr)</code>
 445      <dd>If a raw machine instruction address includes any bits that are not
 446 really part of the address, then define this macro to expand into an
 447 expression that zeroes those bits in <var>addr</var>.  This is only used for
 448 addresses of instructions, and even then not in all contexts.
 449
 450      <p>For example, the two low-order bits of the PC on the Hewlett-Packard PA
 451 2.0 architecture contain the privilege level of the corresponding
 452 instruction.  Since instructions must always be aligned on four-byte
 453 boundaries, the processor masks out these bits to generate the actual
 454 address of the instruction.  ADDR_BITS_REMOVE should filter out these
 455 bits with an expression such as <code>((addr) &amp; ~3)</code>.
 456
 457      <br><dt><code>ADDRESS_TO_POINTER (</code><var>type</var><code>, </code><var>buf</var><code>, </code><var>addr</var><code>)</code>
 458      <dd>Store in <var>buf</var> a pointer of type <var>type</var> representing the address
 459 <var>addr</var>, in the appropriate format for the current architecture.
 460 This macro may safely assume that <var>type</var> is either a pointer or a
 461 C<tt>++</tt> reference type.
 462 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Pointers Are Not Always Addresses</a>.
 463
 464      <br><dt><code>BEFORE_MAIN_LOOP_HOOK</code>
 465      <dd>Define this to expand into any code that you want to execute before the
 466 main loop starts.  Although this is not, strictly speaking, a target
 467 conditional, that is how it is currently being used.  Note that if a
 468 configuration were to define it one way for a host and a different way
 469 for the target, GDB will probably not compile, let alone run
 470 correctly.  This macro is currently used only for the unsupported i960 Nindy
 471 target, and should not be used in any other configuration.
 472
 473      <br><dt><code>BELIEVE_PCC_PROMOTION</code>
 474      <dd>Define if the compiler promotes a <code>short</code> or <code>char</code>
 475 parameter to an <code>int</code>, but still reports the parameter as its
 476 original type, rather than the promoted type.
 477
 478      <br><dt><code>BELIEVE_PCC_PROMOTION_TYPE</code>
 479      <dd>Define this if GDB should believe the type of a <code>short</code>
 480 argument when compiled by <code>pcc</code>, but look within a full int space to get
 481 its value.  Only defined for Sun-3 at present.
 482
 483      <br><dt><code>BITS_BIG_ENDIAN</code>
 484      <dd>Define this if the numbering of bits in the targets does <strong>not</strong> match the
 485 endianness of the target byte order.  A value of 1 means that the bits
 486 are numbered in a big-endian bit order, 0 means little-endian.
 487
 488      <br><dt><code>BREAKPOINT</code>
 489      <dd>This is the character array initializer for the bit pattern to put into
 490 memory where a breakpoint is set.  Although it's common to use a trap
 491 instruction for a breakpoint, it's not required; for instance, the bit
 492 pattern could be an invalid instruction.  The breakpoint must be no
 493 longer than the shortest instruction of the architecture.
 494
 495      <p><code>BREAKPOINT</code> has been deprecated in favor of
 496 <code>BREAKPOINT_FROM_PC</code>.
 497
 498      <br><dt><code>BIG_BREAKPOINT</code>
 499      <dd><dt><code>LITTLE_BREAKPOINT</code>
 500      <dd>Similar to BREAKPOINT, but used for bi-endian targets.
 501
 502      <p><code>BIG_BREAKPOINT</code> and <code>LITTLE_BREAKPOINT</code> have been deprecated in
 503 favor of <code>BREAKPOINT_FROM_PC</code>.
 504
 505      <br><dt><code>REMOTE_BREAKPOINT</code>
 506      <dd><dt><code>LITTLE_REMOTE_BREAKPOINT</code>
 507      <dd><dt><code>BIG_REMOTE_BREAKPOINT</code>
 508      <dd>Similar to BREAKPOINT, but used for remote targets.
 509
 510      <p><code>BIG_REMOTE_BREAKPOINT</code> and <code>LITTLE_REMOTE_BREAKPOINT</code> have been
 511 deprecated in favor of <code>BREAKPOINT_FROM_PC</code>.
 512
 513      <br><dt><code>BREAKPOINT_FROM_PC (</code><var>pcptr</var><code>, </code><var>lenptr</var><code>)</code>
 514      <dd>Use the program counter to determine the contents and size of a
 515 breakpoint instruction.  It returns a pointer to a string of bytes
 516 that encode a breakpoint instruction, stores the length of the string
 517 to *<var>lenptr</var>, and adjusts pc (if necessary) to point to the actual
 518 memory location where the breakpoint should be inserted.
 519
 520      <p>Although it is common to use a trap instruction for a breakpoint, it's
 521 not required; for instance, the bit pattern could be an invalid
 522 instruction.  The breakpoint must be no longer than the shortest
 523 instruction of the architecture.
 524
 525      <p>Replaces all the other <var>BREAKPOINT</var> macros.
 526
 527      <br><dt><code>MEMORY_INSERT_BREAKPOINT (</code><var>addr</var><code>, </code><var>contents_cache</var><code>)</code>
 528      <dd><dt><code>MEMORY_REMOVE_BREAKPOINT (</code><var>addr</var><code>, </code><var>contents_cache</var><code>)</code>
 529      <dd>Insert or remove memory based breakpoints.  Reasonable defaults
 530 (<code>default_memory_insert_breakpoint</code> and
 531 <code>default_memory_remove_breakpoint</code> respectively) have been
 532 provided so that it is not necessary to define these for most
 533 architectures.  Architectures which may want to define
 534 <code>MEMORY_INSERT_BREAKPOINT</code> and <code>MEMORY_REMOVE_BREAKPOINT</code> will
 535 likely have instructions that are oddly sized or are not stored in a
 536 conventional manner.
 537
 538      <p>It may also be desirable (from an efficiency standpoint) to define
 539 custom breakpoint insertion and removal routines if
 540 <code>BREAKPOINT_FROM_PC</code> needs to read the target's memory for some
 541 reason.
 542
 543      <br><dt><code>CALL_DUMMY_P</code>
 544      <dd>A C expresson that is non-zero when the target suports inferior function
 545 calls.
 546
 547      <br><dt><code>CALL_DUMMY_WORDS</code>
 548      <dd>Pointer to an array of <code>LONGEST</code> words of data containing
 549 host-byte-ordered <code>REGISTER_BYTES</code> sized values that partially
 550 specify the sequence of instructions needed for an inferior function
 551 call.
 552
 553      <p>Should be deprecated in favor of a macro that uses target-byte-ordered
 554 data.
 555
 556      <br><dt><code>SIZEOF_CALL_DUMMY_WORDS</code>
 557      <dd>The size of <code>CALL_DUMMY_WORDS</code>.  When <code>CALL_DUMMY_P</code> this must
 558 return a positive value.  See also <code>CALL_DUMMY_LENGTH</code>.
 559
 560      <br><dt><code>CALL_DUMMY</code>
 561      <dd>A static initializer for <code>CALL_DUMMY_WORDS</code>.  Deprecated.
 562
 563      <br><dt><code>CALL_DUMMY_LOCATION</code>
 564      <dd>See the file <code>inferior.h</code>.
 565
 566      <br><dt><code>CALL_DUMMY_STACK_ADJUST</code>
 567      <dd>Stack adjustment needed when performing an inferior function call.
 568
 569      <p>Should be deprecated in favor of something like <code>STACK_ALIGN</code>.
 570
 571      <br><dt><code>CALL_DUMMY_STACK_ADJUST_P</code>
 572      <dd>Predicate for use of <code>CALL_DUMMY_STACK_ADJUST</code>.
 573
 574      <p>Should be deprecated in favor of something like <code>STACK_ALIGN</code>.
 575
 576      <br><dt><code>CANNOT_FETCH_REGISTER (</code><var>regno</var><code>)</code>
 577      <dd>A C expression that should be nonzero if <var>regno</var> cannot be fetched
 578 from an inferior process.  This is only relevant if
 579 <code>FETCH_INFERIOR_REGISTERS</code> is not defined.
 580
 581      <br><dt><code>CANNOT_STORE_REGISTER (</code><var>regno</var><code>)</code>
 582      <dd>A C expression that should be nonzero if <var>regno</var> should not be
 583 written to the target.  This is often the case for program counters,
 584 status words, and other special registers.  If this is not defined,
 585 GDB will assume that all registers may be written.
 586
 587      <br><dt><code>DO_DEFERRED_STORES</code>
 588      <dd><dt><code>CLEAR_DEFERRED_STORES</code>
 589      <dd>Define this to execute any deferred stores of registers into the inferior,
 590 and to cancel any deferred stores.
 591
 592      <p>Currently only implemented correctly for native Sparc configurations?
 593
 594      <br><dt><code>COERCE_FLOAT_TO_DOUBLE (</code><var>formal</var><code>, </code><var>actual</var><code>)</code>
 595      <dd>Return non-zero if GDB should promote <code>float</code> values to
 596 <code>double</code> when calling a non-prototyped function.  The argument
 597 <var>actual</var> is the type of the value we want to pass to the function.
 598 The argument <var>formal</var> is the type of this argument, as it appears in
 599 the function's definition.  Note that <var>formal</var> may be zero if we
 600 have no debugging information for the function, or if we're passing more
 601 arguments than are officially declared (for example, varargs).  This
 602 macro is never invoked if the function definitely has a prototype.
 603
 604      <p>How you should pass arguments to a function depends on whether it was
 605 defined in K&amp;R style or prototype style.  If you define a function using
 606 the K&amp;R syntax that takes a <code>float</code> argument, then callers must
 607 pass that argument as a <code>double</code>.  If you define the function using
 608 the prototype syntax, then you must pass the argument as a <code>float</code>,
 609 with no promotion.
 610
 611      <p>Unfortunately, on certain older platforms, the debug info doesn't
 612 indicate reliably how each function was defined.  A function type's
 613 <code>TYPE_FLAG_PROTOTYPED</code> flag may be unset, even if the function was
 614 defined in prototype style.  When calling a function whose
 615 <code>TYPE_FLAG_PROTOTYPED</code> flag is unset, GDB consults the
 616 <code>COERCE_FLOAT_TO_DOUBLE</code> macro to decide what to do.
 617
 618      <p>For modern targets, it is proper to assume that, if the prototype flag
 619 is unset, that can be trusted: <code>float</code> arguments should be promoted
 620 to <code>double</code>.  You should use the function
 621 <code>standard_coerce_float_to_double</code> to get this behavior.
 622
 623      <p>For some older targets, if the prototype flag is unset, that doesn't
 624 tell us anything.  So we guess that, if we don't have a type for the
 625 formal parameter (<i>i.e.</i>, the first argument to
 626 <code>COERCE_FLOAT_TO_DOUBLE</code> is null), then we should promote it;
 627 otherwise, we should leave it alone.  The function
 628 <code>default_coerce_float_to_double</code> provides this behavior; it is the
 629 default value, for compatibility with older configurations.
 630
 631      <br><dt><code>CPLUS_MARKER</code>
 632      <dd>Define this to expand into the character that G<tt>++</tt> uses to distinguish
 633 compiler-generated identifiers from programmer-specified identifiers.
 634 By default, this expands into <code>'$'</code>.  Most System V targets should
 635 define this to <code>'.'</code>.
 636
 637      <br><dt><code>DBX_PARM_SYMBOL_CLASS</code>
 638      <dd>Hook for the <code>SYMBOL_CLASS</code> of a parameter when decoding DBX symbol
 639 information.  In the i960, parameters can be stored as locals or as
 640 args, depending on the type of the debug record.
 641
 642      <br><dt><code>DECR_PC_AFTER_BREAK</code>
 643      <dd>Define this to be the amount by which to decrement the PC after the
 644 program encounters a breakpoint.  This is often the number of bytes in
 645 <code>BREAKPOINT</code>, though not always.  For most targets this value will be 0.
 646
 647      <br><dt><code>DECR_PC_AFTER_HW_BREAK</code>
 648      <dd>Similarly, for hardware breakpoints.
 649
 650      <br><dt><code>DISABLE_UNSETTABLE_BREAK (</code><var>addr</var><code>)</code>
 651      <dd>If defined, this should evaluate to 1 if <var>addr</var> is in a shared
 652 library in which breakpoints cannot be set and so should be disabled.
 653
 654      <br><dt><code>DO_REGISTERS_INFO</code>
 655      <dd>If defined, use this to print the value of a register or all registers.
 656
 657      <br><dt><code>PRINT_FLOAT_INFO()</code>
 658      <dd>#findex PRINT_FLOAT_INFO
 659 If defined, then the <code>info float</code> command will print information about
 660 the processor's floating point unit.
 661
 662      <br><dt><code>DWARF_REG_TO_REGNUM</code>
 663      <dd>Convert DWARF register number into GDB regnum.  If not defined,
 664 no conversion will be performed.
 665
 666      <br><dt><code>DWARF2_REG_TO_REGNUM</code>
 667      <dd>Convert DWARF2 register number into GDB regnum.  If not
 668 defined, no conversion will be performed.
 669
 670      <br><dt><code>ECOFF_REG_TO_REGNUM</code>
 671      <dd>Convert ECOFF register number into GDB regnum.  If not defined,
 672 no conversion will be performed.
 673
 674      <br><dt><code>END_OF_TEXT_DEFAULT</code>
 675      <dd>This is an expression that should designate the end of the text section.
 676
 677      <br><dt><code>EXTRACT_RETURN_VALUE(</code><var>type</var><code>, </code><var>regbuf</var><code>, </code><var>valbuf</var><code>)</code>
 678      <dd>Define this to extract a function's return value of type <var>type</var> from
 679 the raw register state <var>regbuf</var> and copy that, in virtual format,
 680 into <var>valbuf</var>.
 681
 682      <br><dt><code>EXTRACT_STRUCT_VALUE_ADDRESS(</code><var>regbuf</var><code>)</code>
 683      <dd>When defined, extract from the array <var>regbuf</var> (containing the raw
 684 register state) the <code>CORE_ADDR</code> at which a function should return
 685 its structure value.
 686
 687      <p>If not defined, <code>EXTRACT_RETURN_VALUE</code> is used.
 688
 689      <br><dt><code>EXTRACT_STRUCT_VALUE_ADDRESS_P()</code>
 690      <dd>Predicate for <code>EXTRACT_STRUCT_VALUE_ADDRESS</code>.
 691
 692      <br><dt><code>FLOAT_INFO</code>
 693      <dd>Deprecated in favor of <code>PRINT_FLOAT_INFO</code>.
 694
 695      <br><dt><code>FP_REGNUM</code>
 696      <dd>If the virtual frame pointer is kept in a register, then define this
 697 macro to be the number (greater than or equal to zero) of that register.
 698
 699      <p>This should only need to be defined if <code>TARGET_READ_FP</code> and
 700 <code>TARGET_WRITE_FP</code> are not defined.
 701
 702      <br><dt><code>FRAMELESS_FUNCTION_INVOCATION(</code><var>fi</var><code>)</code>
 703      <dd>Define this to an expression that returns 1 if the function invocation
 704 represented by <var>fi</var> does not have a stack frame associated with it.
 705 Otherwise return 0.
 706
 707      <br><dt><code>FRAME_ARGS_ADDRESS_CORRECT</code>
 708      <dd>See <code>stack.c</code>.
 709
 710      <br><dt><code>FRAME_CHAIN(</code><var>frame</var><code>)</code>
 711      <dd>Given <var>frame</var>, return a pointer to the calling frame.
 712
 713      <br><dt><code>FRAME_CHAIN_COMBINE(</code><var>chain</var><code>, </code><var>frame</var><code>)</code>
 714      <dd>Define this to take the frame chain pointer and the frame's nominal
 715 address and produce the nominal address of the caller's frame.
 716 Presently only defined for HP PA.
 717
 718      <br><dt><code>FRAME_CHAIN_VALID(</code><var>chain</var><code>, </code><var>thisframe</var><code>)</code>
 719      <dd>Define this to be an expression that returns zero if the given frame is
 720 an outermost frame, with no caller, and nonzero otherwise.  Several
 721 common definitions are available:
 722
 723           <ul>
 724 <li><code>file_frame_chain_valid</code> is nonzero if the chain pointer is nonzero
 725 and given frame's PC is not inside the startup file (such as
 726 <code>crt0.o</code>).
 727
 728           <li><code>func_frame_chain_valid</code> is nonzero if the chain
 729 pointer is nonzero and the given frame's PC is not in <code>main</code> or a
 730 known entry point function (such as <code>_start</code>).
 731
 732           <li><code>generic_file_frame_chain_valid</code> and
 733 <code>generic_func_frame_chain_valid</code> are equivalent implementations for
 734 targets using generic dummy frames.
 735 </ul>
 736
 737      <br><dt><code>FRAME_INIT_SAVED_REGS(</code><var>frame</var><code>)</code>
 738      <dd>See <code>frame.h</code>.  Determines the address of all registers in the
 739 current stack frame storing each in <code>frame-&gt;saved_regs</code>.  Space for
 740 <code>frame-&gt;saved_regs</code> shall be allocated by
 741 <code>FRAME_INIT_SAVED_REGS</code> using either
 742 <code>frame_saved_regs_zalloc</code> or <code>frame_obstack_alloc</code>.
 743
 744      <p><code>FRAME_FIND_SAVED_REGS</code> and <code>EXTRA_FRAME_INFO</code> are deprecated.
 745
 746      <br><dt><code>FRAME_NUM_ARGS (</code><var>fi</var><code>)</code>
 747      <dd>For the frame described by <var>fi</var> return the number of arguments that
 748 are being passed.  If the number of arguments is not known, return
 749 <code>-1</code>.
 750
 751      <br><dt><code>FRAME_SAVED_PC(</code><var>frame</var><code>)</code>
 752      <dd>Given <var>frame</var>, return the pc saved there.  This is the return
 753 address.
 754
 755      <br><dt><code>FUNCTION_EPILOGUE_SIZE</code>
 756      <dd>For some COFF targets, the <code>x_sym.x_misc.x_fsize</code> field of the
 757 function end symbol is 0.  For such targets, you must define
 758 <code>FUNCTION_EPILOGUE_SIZE</code> to expand into the standard size of a
 759 function's epilogue.
 760
 761      <br><dt><code>FUNCTION_START_OFFSET</code>
 762      <dd>An integer, giving the offset in bytes from a function's address (as
 763 used in the values of symbols, function pointers, etc.), and the
 764 function's first genuine instruction.
 765
 766      <p>This is zero on almost all machines: the function's address is usually
 767 the address of its first instruction.  However, on the VAX, for example,
 768 each function starts with two bytes containing a bitmask indicating
 769 which registers to save upon entry to the function.  The VAX <code>call</code>
 770 instructions check this value, and save the appropriate registers
 771 automatically.  Thus, since the offset from the function's address to
 772 its first instruction is two bytes, <code>FUNCTION_START_OFFSET</code> would
 773 be 2 on the VAX.
 774
 775      <br><dt><code>GCC_COMPILED_FLAG_SYMBOL</code>
 776      <dd><dt><code>GCC2_COMPILED_FLAG_SYMBOL</code>
 777      <dd>If defined, these are the names of the symbols that GDB will
 778 look for to detect that GCC compiled the file.  The default symbols
 779 are <code>gcc_compiled.</code> and <code>gcc2_compiled.</code>,
 780 respectively.  (Currently only defined for the Delta 68.)
 781
 782      <br><dt><code>GDB_MULTI_ARCH</code>
 783      <dd>If defined and non-zero, enables suport for multiple architectures
 784 within GDB.
 785
 786      <p>This support can be enabled at two levels.  At level one, only
 787 definitions for previously undefined macros are provided; at level two,
 788 a multi-arch definition of all architecture dependant macros will be
 789 defined.
 790
 791      <br><dt><code>GDB_TARGET_IS_HPPA</code>
 792      <dd>This determines whether horrible kludge code in <code>dbxread.c</code> and
 793 <code>partial-stab.h</code> is used to mangle multiple-symbol-table files from
 794 HPPA's.  This should all be ripped out, and a scheme like <code>elfread.c</code>
 795 used instead.
 796
 797      <br><dt><code>GET_LONGJMP_TARGET</code>
 798      <dd>For most machines, this is a target-dependent parameter.  On the
 799 DECstation and the Iris, this is a native-dependent parameter, since
 800 trhe header file <code>setjmp.h</code> is needed to define it.
 801
 802      <p>This macro determines the target PC address that <code>longjmp</code> will jump to,
 803 assuming that we have just stopped at a <code>longjmp</code> breakpoint.  It takes a
 804 <code>CORE_ADDR *</code> as argument, and stores the target PC value through this
 805 pointer.  It examines the current state of the machine as needed.
 806
 807      <br><dt><code>GET_SAVED_REGISTER</code>
 808      <dd>Define this if you need to supply your own definition for the function
 809 <code>get_saved_register</code>.
 810
 811      <br><dt><code>HAVE_REGISTER_WINDOWS</code>
 812      <dd>Define this if the target has register windows.
 813
 814      <br><dt><code>REGISTER_IN_WINDOW_P (</code><var>regnum</var><code>)</code>
 815      <dd>Define this to be an expression that is 1 if the given register is in
 816 the window.
 817
 818      <br><dt><code>IBM6000_TARGET</code>
 819      <dd>Shows that we are configured for an IBM RS/6000 target.  This
 820 conditional should be eliminated (FIXME) and replaced by
 821 feature-specific macros.  It was introduced in a haste and we are
 822 repenting at leisure.
 823
 824      <br><dt><code>I386_USE_GENERIC_WATCHPOINTS</code>
 825      <dd>An x86-based target can define this to use the generic x86 watchpoint
 826 support; see <a href="Algorithms.html#Algorithms">I386_USE_GENERIC_WATCHPOINTS</a>.
 827
 828      <br><dt><code>SYMBOLS_CAN_START_WITH_DOLLAR</code>
 829      <dd>Some systems have routines whose names start with <code>$</code>.  Giving this
 830 macro a non-zero value tells GDB's expression parser to check for such
 831 routines when parsing tokens that begin with <code>$</code>.
 832
 833      <p>On HP-UX, certain system routines (millicode) have names beginning with
 834 <code>$</code> or <code>$$</code>.  For example, <code>$$dyncall</code> is a millicode
 835 routine that handles inter-space procedure calls on PA-RISC.
 836
 837      <br><dt><code>INIT_EXTRA_FRAME_INFO (</code><var>fromleaf</var><code>, </code><var>frame</var><code>)</code>
 838      <dd>If additional information about the frame is required this should be
 839 stored in <code>frame-&gt;extra_info</code>.  Space for <code>frame-&gt;extra_info</code>
 840 is allocated using <code>frame_obstack_alloc</code>.
 841
 842      <br><dt><code>INIT_FRAME_PC (</code><var>fromleaf</var><code>, </code><var>prev</var><code>)</code>
 843      <dd>This is a C statement that sets the pc of the frame pointed to by
 844 <var>prev</var>.  [By default...]
 845
 846      <br><dt><code>INNER_THAN (</code><var>lhs</var><code>, </code><var>rhs</var><code>)</code>
 847      <dd>Returns non-zero if stack address <var>lhs</var> is inner than (nearer to the
 848 stack top) stack address <var>rhs</var>. Define this as <code>lhs &lt; rhs</code> if
 849 the target's stack grows downward in memory, or <code>lhs &gt; rsh</code> if the
 850 stack grows upward.
 851
 852      <br><dt><code>gdbarch_in_function_epilogue_p (</code><var>gdbarch</var><code>, </code><var>pc</var><code>)</code>
 853      <dd>Returns non-zero if the given <var>pc</var> is in the epilogue of a function.
 854 The epilogue of a function is defined as the part of a function where
 855 the stack frame of the function already has been destroyed up to the
 856 final `return from function call' instruction.
 857
 858      <br><dt><code>IN_SIGTRAMP (</code><var>pc</var><code>, </code><var>name</var><code>)</code>
 859      <dd>Define this to return non-zero if the given <var>pc</var> and/or <var>name</var>
 860 indicates that the current function is a <code>sigtramp</code>.
 861
 862      <br><dt><code>SIGTRAMP_START (</code><var>pc</var><code>)</code>
 863      <dd><dt><code>SIGTRAMP_END (</code><var>pc</var><code>)</code>
 864      <dd>Define these to be the start and end address of the <code>sigtramp</code> for the
 865 given <var>pc</var>.  On machines where the address is just a compile time
 866 constant, the macro expansion will typically just ignore the supplied
 867 <var>pc</var>.
 868
 869      <br><dt><code>IN_SOLIB_CALL_TRAMPOLINE (</code><var>pc</var><code>, </code><var>name</var><code>)</code>
 870      <dd>Define this to evaluate to nonzero if the program is stopped in the
 871 trampoline that connects to a shared library.
 872
 873      <br><dt><code>IN_SOLIB_RETURN_TRAMPOLINE (</code><var>pc</var><code>, </code><var>name</var><code>)</code>
 874      <dd>Define this to evaluate to nonzero if the program is stopped in the
 875 trampoline that returns from a shared library.
 876
 877      <br><dt><code>IN_SOLIB_DYNSYM_RESOLVE_CODE (</code><var>pc</var><code>)</code>
 878      <dd>Define this to evaluate to nonzero if the program is stopped in the
 879 dynamic linker.
 880
 881      <br><dt><code>SKIP_SOLIB_RESOLVER (</code><var>pc</var><code>)</code>
 882      <dd>Define this to evaluate to the (nonzero) address at which execution
 883 should continue to get past the dynamic linker's symbol resolution
 884 function.  A zero value indicates that it is not important or necessary
 885 to set a breakpoint to get through the dynamic linker and that single
 886 stepping will suffice.
 887
 888      <br><dt><code>INTEGER_TO_ADDRESS (</code><var>type</var><code>, </code><var>buf</var><code>)</code>
 889      <dd>Define this when the architecture needs to handle non-pointer to address
 890 conversions specially.  Converts that value to an address according to
 891 the current architectures conventions.
 892
 893      <p><em>Pragmatics: When the user copies a well defined expression from
 894 their source code and passes it, as a parameter, to GDB's
 895 </em><code>print</code><em> command, they should get the same value as would have been
 896 computed by the target program.  Any deviation from this rule can cause
 897 major confusion and annoyance, and needs to be justified carefully.  In
 898 other words, GDB doesn't really have the freedom to do these
 899 conversions in clever and useful ways.  It has, however, been pointed
 900 out that users aren't complaining about how GDB casts integers
 901 to pointers; they are complaining that they can't take an address from a
 902 disassembly listing and give it to </em><code>x/i</code><em>.  Adding an architecture
 903 method like </em><code>INTEGER_TO_ADDRESS</code><em> certainly makes it possible for
 904 GDB to "get it right" in all circumstances.</em>
 905
 906      <p>See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Pointers Are Not Always Addresses</a>.
 907
 908      <br><dt><code>IS_TRAPPED_INTERNALVAR (</code><var>name</var><code>)</code>
 909      <dd>This is an ugly hook to allow the specification of special actions that
 910 should occur as a side-effect of setting the value of a variable
 911 internal to GDB.  Currently only used by the h8500.  Note that this
 912 could be either a host or target conditional.
 913
 914      <br><dt><code>NEED_TEXT_START_END</code>
 915      <dd>Define this if GDB should determine the start and end addresses of the
 916 text section.  (Seems dubious.)
 917
 918      <br><dt><code>NO_HIF_SUPPORT</code>
 919      <dd>(Specific to the a29k.)
 920
 921      <br><dt><code>POINTER_TO_ADDRESS (</code><var>type</var><code>, </code><var>buf</var><code>)</code>
 922      <dd>Assume that <var>buf</var> holds a pointer of type <var>type</var>, in the
 923 appropriate format for the current architecture.  Return the byte
 924 address the pointer refers to.
 925 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Pointers Are Not Always Addresses</a>.
 926
 927      <br><dt><code>REGISTER_CONVERTIBLE (</code><var>reg</var><code>)</code>
 928      <dd>Return non-zero if <var>reg</var> uses different raw and virtual formats.
 929 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 930
 931      <br><dt><code>REGISTER_RAW_SIZE (</code><var>reg</var><code>)</code>
 932      <dd>Return the raw size of <var>reg</var>.
 933 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 934
 935      <br><dt><code>REGISTER_VIRTUAL_SIZE (</code><var>reg</var><code>)</code>
 936      <dd>Return the virtual size of <var>reg</var>.
 937 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 938
 939      <br><dt><code>REGISTER_VIRTUAL_TYPE (</code><var>reg</var><code>)</code>
 940      <dd>Return the virtual type of <var>reg</var>.
 941 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 942
 943      <br><dt><code>REGISTER_CONVERT_TO_VIRTUAL(</code><var>reg</var><code>, </code><var>type</var><code>, </code><var>from</var><code>, </code><var>to</var><code>)</code>
 944      <dd>Convert the value of register <var>reg</var> from its raw form to its virtual
 945 form.
 946 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 947
 948      <br><dt><code>REGISTER_CONVERT_TO_RAW(</code><var>type</var><code>, </code><var>reg</var><code>, </code><var>from</var><code>, </code><var>to</var><code>)</code>
 949      <dd>Convert the value of register <var>reg</var> from its virtual form to its raw
 950 form.
 951 See <a href="Target-Architecture-Definition.html#Target%20Architecture%20Definition">Using Different Register and Memory Data Representations</a>.
 952
 953      <br><dt><code>RETURN_VALUE_ON_STACK(</code><var>type</var><code>)</code>
 954      <dd>
 955
 956      <p>Return non-zero if values of type TYPE are returned on the stack, using
 957 the "struct convention" (i.e., the caller provides a pointer to a
 958 buffer in which the callee should store the return value).  This
 959 controls how the <code>finish</code> command finds a function's return value,
 960 and whether an inferior function call reserves space on the stack for
 961 the return value.
 962
 963      <p>The full logic GDB uses here is kind of odd.
 964
 965           <ul>
 966 <li>If the type being returned by value is not a structure, union, or array,
 967 and <code>RETURN_VALUE_ON_STACK</code> returns zero, then GDB
 968 concludes the value is not returned using the struct convention.
 969
 970           <li>Otherwise, GDB calls <code>USE_STRUCT_CONVENTION</code> (see below).
 971 If that returns non-zero, GDB assumes the struct convention is
 972 in use.
 973 </ul>
 974
 975      <p>In other words, to indicate that a given type is returned by value using
 976 the struct convention, that type must be either a struct, union, array,
 977 or something <code>RETURN_VALUE_ON_STACK</code> likes, <em>and</em> something
 978 that <code>USE_STRUCT_CONVENTION</code> likes.
 979
 980      <p>Note that, in C and C<tt>++</tt>, arrays are never returned by value.  In those
 981 languages, these predicates will always see a pointer type, never an
 982 array type.  All the references above to arrays being returned by value
 983 apply only to other languages.
 984
 985      <br><dt><code>SOFTWARE_SINGLE_STEP_P()</code>
 986      <dd>Define this as 1 if the target does not have a hardware single-step
 987 mechanism.  The macro <code>SOFTWARE_SINGLE_STEP</code> must also be defined.
 988
 989      <br><dt><code>SOFTWARE_SINGLE_STEP(</code><var>signal</var><code>, </code><var>insert_breapoints_p</var><code>)</code>
 990      <dd>A function that inserts or removes (depending on
 991 <var>insert_breapoints_p</var>) breakpoints at each possible destinations of
 992 the next instruction. See <code>sparc-tdep.c</code> and <code>rs6000-tdep.c</code>
 993 for examples.
 994
 995      <br><dt><code>SOFUN_ADDRESS_MAYBE_MISSING</code>
 996      <dd>Somebody clever observed that, the more actual addresses you have in the
 997 debug information, the more time the linker has to spend relocating
 998 them.  So whenever there's some other way the debugger could find the
 999 address it needs, you should omit it from the debug info, to make
1000 linking faster.
1001
1002      <p><code>SOFUN_ADDRESS_MAYBE_MISSING</code> indicates that a particular set of
1003 hacks of this sort are in use, affecting <code>N_SO</code> and <code>N_FUN</code>
1004 entries in stabs-format debugging information.  <code>N_SO</code> stabs mark
1005 the beginning and ending addresses of compilation units in the text
1006 segment.  <code>N_FUN</code> stabs mark the starts and ends of functions.
1007
1008      <p><code>SOFUN_ADDRESS_MAYBE_MISSING</code> means two things:
1009
1010           <ul>
1011 <li><code>N_FUN</code> stabs have an address of zero.  Instead, you should find the
1012 addresses where the function starts by taking the function name from
1013 the stab, and then looking that up in the minsyms (the
1014 linker/assembler symbol table).  In other words, the stab has the
1015 name, and the linker/assembler symbol table is the only place that carries
1016 the address.
1017
1018           <li><code>N_SO</code> stabs have an address of zero, too.  You just look at the
1019 <code>N_FUN</code> stabs that appear before and after the <code>N_SO</code> stab,
1020 and guess the starting and ending addresses of the compilation unit from
1021 them.
1022 </ul>
1023
1024      <br><dt><code>PCC_SOL_BROKEN</code>
1025      <dd>(Used only in the Convex target.)
1026
1027      <br><dt><code>PC_IN_CALL_DUMMY</code>
1028      <dd>See <code>inferior.h</code>.
1029
1030      <br><dt><code>PC_LOAD_SEGMENT</code>
1031      <dd>If defined, print information about the load segment for the program
1032 counter.  (Defined only for the RS/6000.)
1033
1034      <br><dt><code>PC_REGNUM</code>
1035      <dd>If the program counter is kept in a register, then define this macro to
1036 be the number (greater than or equal to zero) of that register.
1037
1038      <p>This should only need to be defined if <code>TARGET_READ_PC</code> and
1039 <code>TARGET_WRITE_PC</code> are not defined.
1040
1041      <br><dt><code>NPC_REGNUM</code>
1042      <dd>The number of the "next program counter" register, if defined.
1043
1044      <br><dt><code>NNPC_REGNUM</code>
1045      <dd>The number of the "next next program counter" register, if defined.
1046 Currently, this is only defined for the Motorola 88K.
1047
1048      <br><dt><code>PARM_BOUNDARY</code>
1049      <dd>If non-zero, round arguments to a boundary of this many bits before
1050 pushing them on the stack.
1051
1052      <br><dt><code>PRINT_REGISTER_HOOK (</code><var>regno</var><code>)</code>
1053      <dd>If defined, this must be a function that prints the contents of the
1054 given register to standard output.
1055
1056      <br><dt><code>PRINT_TYPELESS_INTEGER</code>
1057      <dd>This is an obscure substitute for <code>print_longest</code> that seems to
1058 have been defined for the Convex target.
1059
1060      <br><dt><code>PROCESS_LINENUMBER_HOOK</code>
1061      <dd>A hook defined for XCOFF reading.
1062
1063      <br><dt><code>PROLOGUE_FIRSTLINE_OVERLAP</code>
1064      <dd>(Only used in unsupported Convex configuration.)
1065
1066      <br><dt><code>PS_REGNUM</code>
1067      <dd>If defined, this is the number of the processor status register.  (This
1068 definition is only used in generic code when parsing "$ps".)
1069
1070      <br><dt><code>POP_FRAME</code>
1071      <dd>Used in <code>call_function_by_hand</code> to remove an artificial stack
1072 frame and in <code>return_command</code> to remove a real stack frame.
1073
1074      <br><dt><code>PUSH_ARGUMENTS (</code><var>nargs</var><code>, </code><var>args</var><code>, </code><var>sp</var><code>, </code><var>struct_return</var><code>, </code><var>struct_addr</var><code>)</code>
1075      <dd>Define this to push arguments onto the stack for inferior function
1076 call.  Returns the updated stack pointer value.
1077
1078      <br><dt><code>PUSH_DUMMY_FRAME</code>
1079      <dd>Used in <code>call_function_by_hand</code> to create an artificial stack frame.
1080
1081      <br><dt><code>REGISTER_BYTES</code>
1082      <dd>The total amount of space needed to store GDB's copy of the machine's
1083 register state.
1084
1085      <br><dt><code>REGISTER_NAME(</code><var>i</var><code>)</code>
1086      <dd>Return the name of register <var>i</var> as a string.  May return <code>NULL</code>
1087 or <code>NUL</code> to indicate that register <var>i</var> is not valid.
1088
1089      <br><dt><code>REGISTER_NAMES</code>
1090      <dd>Deprecated in favor of <code>REGISTER_NAME</code>.
1091
1092      <br><dt><code>REG_STRUCT_HAS_ADDR (</code><var>gcc_p</var><code>, </code><var>type</var><code>)</code>
1093      <dd>Define this to return 1 if the given type will be passed by pointer
1094 rather than directly.
1095
1096      <br><dt><code>SAVE_DUMMY_FRAME_TOS (</code><var>sp</var><code>)</code>
1097      <dd>Used in <code>call_function_by_hand</code> to notify the target dependent code
1098 of the top-of-stack value that will be passed to the the inferior code.
1099 This is the value of the <code>SP</code> after both the dummy frame and space
1100 for parameters/results have been allocated on the stack.
1101
1102      <br><dt><code>SDB_REG_TO_REGNUM</code>
1103      <dd>Define this to convert sdb register numbers into GDB regnums.  If not
1104 defined, no conversion will be done.
1105
1106      <br><dt><code>SHIFT_INST_REGS</code>
1107      <dd>(Only used for m88k targets.)
1108
1109      <br><dt><code>SKIP_PERMANENT_BREAKPOINT</code>
1110      <dd>Advance the inferior's PC past a permanent breakpoint.  GDB normally
1111 steps over a breakpoint by removing it, stepping one instruction, and
1112 re-inserting the breakpoint.  However, permanent breakpoints are
1113 hardwired into the inferior, and can't be removed, so this strategy
1114 doesn't work.  Calling <code>SKIP_PERMANENT_BREAKPOINT</code> adjusts the processor's
1115 state so that execution will resume just after the breakpoint.  This
1116 macro does the right thing even when the breakpoint is in the delay slot
1117 of a branch or jump.
1118
1119      <br><dt><code>SKIP_PROLOGUE (</code><var>pc</var><code>)</code>
1120      <dd>A C expression that returns the address of the "real" code beyond the
1121 function entry prologue found at <var>pc</var>.
1122
1123      <br><dt><code>SKIP_PROLOGUE_FRAMELESS_P</code>
1124      <dd>A C expression that should behave similarly, but that can stop as soon
1125 as the function is known to have a frame.  If not defined,
1126 <code>SKIP_PROLOGUE</code> will be used instead.
1127
1128      <br><dt><code>SKIP_TRAMPOLINE_CODE (</code><var>pc</var><code>)</code>
1129      <dd>If the target machine has trampoline code that sits between callers and
1130 the functions being called, then define this macro to return a new PC
1131 that is at the start of the real function.
1132
1133      <br><dt><code>SP_REGNUM</code>
1134      <dd>If the stack-pointer is kept in a register, then define this macro to be
1135 the number (greater than or equal to zero) of that register.
1136
1137      <p>This should only need to be defined if <code>TARGET_WRITE_SP</code> and
1138 <code>TARGET_WRITE_SP</code> are not defined.
1139
1140      <br><dt><code>STAB_REG_TO_REGNUM</code>
1141      <dd>Define this to convert stab register numbers (as gotten from `r'
1142 declarations) into GDB regnums.  If not defined, no conversion will be
1143 done.
1144
1145      <br><dt><code>STACK_ALIGN (</code><var>addr</var><code>)</code>
1146      <dd>Define this to adjust the address to the alignment required for the
1147 processor's stack.
1148
1149      <br><dt><code>STEP_SKIPS_DELAY (</code><var>addr</var><code>)</code>
1150      <dd>Define this to return true if the address is of an instruction with a
1151 delay slot.  If a breakpoint has been placed in the instruction's delay
1152 slot, GDB will single-step over that instruction before resuming
1153 normally.  Currently only defined for the Mips.
1154
1155      <br><dt><code>STORE_RETURN_VALUE (</code><var>type</var><code>, </code><var>valbuf</var><code>)</code>
1156      <dd>A C expression that stores a function return value of type <var>type</var>,
1157 where <var>valbuf</var> is the address of the value to be stored.
1158
1159      <br><dt><code>SUN_FIXED_LBRAC_BUG</code>
1160      <dd>(Used only for Sun-3 and Sun-4 targets.)
1161
1162      <br><dt><code>SYMBOL_RELOADING_DEFAULT</code>
1163      <dd>The default value of the "symbol-reloading" variable.  (Never defined in
1164 current sources.)
1165
1166      <br><dt><code>TARGET_CHAR_BIT</code>
1167      <dd>Number of bits in a char; defaults to 8.
1168
1169      <br><dt><code>TARGET_CHAR_SIGNED</code>
1170      <dd>Non-zero if <code>char</code> is normally signed on this architecture; zero if
1171 it should be unsigned.
1172
1173      <p>The ISO C standard requires the compiler to treat <code>char</code> as
1174 equivalent to either <code>signed char</code> or <code>unsigned char</code>; any
1175 character in the standard execution set is supposed to be positive.
1176 Most compilers treat <code>char</code> as signed, but <code>char</code> is unsigned
1177 on the IBM S/390, RS6000, and PowerPC targets.
1178
1179      <br><dt><code>TARGET_COMPLEX_BIT</code>
1180      <dd>Number of bits in a complex number; defaults to <code>2 * TARGET_FLOAT_BIT</code>.
1181
1182      <p>At present this macro is not used.
1183
1184      <br><dt><code>TARGET_DOUBLE_BIT</code>
1185      <dd>Number of bits in a double float; defaults to <code>8 * TARGET_CHAR_BIT</code>.
1186
1187      <br><dt><code>TARGET_DOUBLE_COMPLEX_BIT</code>
1188      <dd>Number of bits in a double complex; defaults to <code>2 * TARGET_DOUBLE_BIT</code>.
1189
1190      <p>At present this macro is not used.
1191
1192      <br><dt><code>TARGET_FLOAT_BIT</code>
1193      <dd>Number of bits in a float; defaults to <code>4 * TARGET_CHAR_BIT</code>.
1194
1195      <br><dt><code>TARGET_INT_BIT</code>
1196      <dd>Number of bits in an integer; defaults to <code>4 * TARGET_CHAR_BIT</code>.
1197
1198      <br><dt><code>TARGET_LONG_BIT</code>
1199      <dd>Number of bits in a long integer; defaults to <code>4 * TARGET_CHAR_BIT</code>.
1200
1201      <br><dt><code>TARGET_LONG_DOUBLE_BIT</code>
1202      <dd>Number of bits in a long double float;
1203 defaults to <code>2 * TARGET_DOUBLE_BIT</code>.
1204
1205      <br><dt><code>TARGET_LONG_LONG_BIT</code>
1206      <dd>Number of bits in a long long integer; defaults to <code>2 * TARGET_LONG_BIT</code>.
1207
1208      <br><dt><code>TARGET_PTR_BIT</code>
1209      <dd>Number of bits in a pointer; defaults to <code>TARGET_INT_BIT</code>.
1210
1211      <br><dt><code>TARGET_SHORT_BIT</code>
1212      <dd>Number of bits in a short integer; defaults to <code>2 * TARGET_CHAR_BIT</code>.
1213
1214      <br><dt><code>TARGET_READ_PC</code>
1215      <dd><dt><code>TARGET_WRITE_PC (</code><var>val</var><code>, </code><var>pid</var><code>)</code>
1216      <dd><dt><code>TARGET_READ_SP</code>
1217      <dd><dt><code>TARGET_WRITE_SP</code>
1218      <dd><dt><code>TARGET_READ_FP</code>
1219      <dd><dt><code>TARGET_WRITE_FP</code>
1220      <dd>These change the behavior of <code>read_pc</code>, <code>write_pc</code>,
1221 <code>read_sp</code>, <code>write_sp</code>, <code>read_fp</code> and <code>write_fp</code>.
1222 For most targets, these may be left undefined.  GDB will call the read
1223 and write register functions with the relevant <code>_REGNUM</code> argument.
1224
1225      <p>These macros are useful when a target keeps one of these registers in a
1226 hard to get at place; for example, part in a segment register and part
1227 in an ordinary register.
1228
1229      <br><dt><code>TARGET_VIRTUAL_FRAME_POINTER(</code><var>pc</var><code>, </code><var>regp</var><code>, </code><var>offsetp</var><code>)</code>
1230      <dd>Returns a <code>(register, offset)</code> pair representing the virtual
1231 frame pointer in use at the code address <var>pc</var>.  If virtual
1232 frame pointers are not used, a default definition simply returns
1233 <code>FP_REGNUM</code>, with an offset of zero.
1234
1235      <br><dt><code>TARGET_HAS_HARDWARE_WATCHPOINTS</code>
1236      <dd>If non-zero, the target has support for hardware-assisted
1237 watchpoints.  See <a href="Algorithms.html#Algorithms">watchpoints</a>, for more details and
1238 other related macros.
1239
1240      <br><dt><code>TARGET_PRINT_INSN (</code><var>addr</var><code>, </code><var>info</var><code>)</code>
1241      <dd>This is the function used by GDB to print an assembly
1242 instruction.  It prints the instruction at address <var>addr</var> in
1243 debugged memory and returns the length of the instruction, in bytes.  If
1244 a target doesn't define its own printing routine, it defaults to an
1245 accessor function for the global pointer <code>tm_print_insn</code>. This
1246 usually points to a function in the <code>opcodes</code> library (see <a href="Support-Libraries.html#Support%20Libraries">Opcodes</a>).  <var>info</var> is a structure (of type
1247 <code>disassemble_info</code>) defined in <code>include/dis-asm.h</code> used to
1248 pass information to the instruction decoding routine.
1249
1250      <br><dt><code>USE_STRUCT_CONVENTION (</code><var>gcc_p</var><code>, </code><var>type</var><code>)</code>
1251      <dd>If defined, this must be an expression that is nonzero if a value of the
1252 given <var>type</var> being returned from a function must have space
1253 allocated for it on the stack.  <var>gcc_p</var> is true if the function
1254 being considered is known to have been compiled by GCC; this is helpful
1255 for systems where GCC is known to use different calling convention than
1256 other compilers.
1257
1258      <br><dt><code>VARIABLES_INSIDE_BLOCK (</code><var>desc</var><code>, </code><var>gcc_p</var><code>)</code>
1259      <dd>For dbx-style debugging information, if the compiler puts variable
1260 declarations inside LBRAC/RBRAC blocks, this should be defined to be
1261 nonzero.  <var>desc</var> is the value of <code>n_desc</code> from the
1262 <code>N_RBRAC</code> symbol, and <var>gcc_p</var> is true if GDB has noticed the
1263 presence of either the <code>GCC_COMPILED_SYMBOL</code> or the
1264 <code>GCC2_COMPILED_SYMBOL</code>.  By default, this is 0.
1265
1266      <br><dt><code>OS9K_VARIABLES_INSIDE_BLOCK (</code><var>desc</var><code>, </code><var>gcc_p</var><code>)</code>
1267      <dd>Similarly, for OS/9000.  Defaults to 1.
1268 </dl>
1269
1270    <p>Motorola M68K target conditionals.
1271
1272      <dl>
1273 <dt><code>BPT_VECTOR</code>
1274      <dd>Define this to be the 4-bit location of the breakpoint trap vector.  If
1275 not defined, it will default to <code>0xf</code>.
1276
1277      <br><dt><code>REMOTE_BPT_VECTOR</code>
1278      <dd>Defaults to <code>1</code>.
1279 </dl>
1280
1281 <h3 class="section">Adding a New Target</h3>
1282
1283    <p>The following files add a target to GDB:
1284
1285      <dl>
1286 <dt><code>gdb/config/</code><var>arch</var><code>/</code><var>ttt</var><code>.mt</code>
1287      <dd>Contains a Makefile fragment specific to this target.  Specifies what
1288 object files are needed for target <var>ttt</var>, by defining
1289 <code>TDEPFILES=...</code> and <code>TDEPLIBS=...</code>.  Also specifies
1290 the header file which describes <var>ttt</var>, by defining <code>TM_FILE=
1291 tm-</code><var>ttt</var><code>.h</code>.
1292
1293      <p>You can also define <code>TM_CFLAGS</code>, <code>TM_CLIBS</code>, <code>TM_CDEPS</code>,
1294 but these are now deprecated, replaced by autoconf, and may go away in
1295 future versions of GDB.
1296
1297      <br><dt><code>gdb/</code><var>ttt</var><code>-tdep.c</code>
1298      <dd>Contains any miscellaneous code required for this target machine.  On
1299 some machines it doesn't exist at all.  Sometimes the macros in
1300 <code>tm-</code><var>ttt</var><code>.h</code> become very complicated, so they are implemented
1301 as functions here instead, and the macro is simply defined to call the
1302 function.  This is vastly preferable, since it is easier to understand
1303 and debug.
1304
1305      <br><dt><code>gdb/</code><var>arch</var><code>-tdep.c</code>
1306      <dd><dt><code>gdb/</code><var>arch</var><code>-tdep.h</code>
1307      <dd>This often exists to describe the basic layout of the target machine's
1308 processor chip (registers, stack, etc.).  If used, it is included by
1309 <code></code><var>ttt</var><code>-tdep.h</code>.  It can be shared among many targets that use
1310 the same processor.
1311
1312      <br><dt><code>gdb/config/</code><var>arch</var><code>/tm-</code><var>ttt</var><code>.h</code>
1313      <dd>(<code>tm.h</code> is a link to this file, created by <code>configure</code>).  Contains
1314 macro definitions about the target machine's registers, stack frame
1315 format and instructions.
1316
1317      <p>New targets do not need this file and should not create it.
1318
1319      <br><dt><code>gdb/config/</code><var>arch</var><code>/tm-</code><var>arch</var><code>.h</code>
1320      <dd>This often exists to describe the basic layout of the target machine's
1321 processor chip (registers, stack, etc.).  If used, it is included by
1322 <code>tm-</code><var>ttt</var><code>.h</code>.  It can be shared among many targets that use the
1323 same processor.
1324
1325      <p>New targets do not need this file and should not create it.
1326
1327    </dl>
1328
1329    <p>If you are adding a new operating system for an existing CPU chip, add a
1330 <code>config/tm-</code><var>os</var><code>.h</code> file that describes the operating system
1331 facilities that are unusual (extra symbol table info; the breakpoint
1332 instruction needed; etc.).  Then write a <code></code><var>arch</var><code>/tm-</code><var>os</var><code>.h</code>
1333 that just <code>#include</code>s <code>tm-</code><var>arch</var><code>.h</code> and
1334 <code>config/tm-</code><var>os</var><code>.h</code>.
1335
1336    <div class="footnote">
1337 <hr>
1338 <h4>Footnotes</h4>
1339 <ol type="1">
1340 <li><a name="fn-1"></a>
1341 <p>Some D10V instructions are
1342 actually pairs of 16-bit sub-instructions.  However, since you can't
1343 jump into the middle of such a pair, code addresses can only refer to
1344 full 32 bit instructions, which is what matters in this explanation.</p>
1345
1346    </ol><hr></div>
1347
1348    </body></html>
1349