Home | History | Annotate | Download | only in info
      1 This is gdbint.info, produced by makeinfo version 4.13 from
      2 /tmp/android-1596/src/build/../gdb/gdb-7.1.x/gdb/doc/gdbint.texinfo.
      3 
      4 INFO-DIR-SECTION Software development
      5 START-INFO-DIR-ENTRY
      6 * Gdb-Internals: (gdbint).	The GNU debugger's internals.
      7 END-INFO-DIR-ENTRY
      8 
      9    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
     10 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Free Software
     11 Foundation, Inc.  Contributed by Cygnus Solutions.  Written by John
     12 Gilmore.  Second Edition by Stan Shebs.
     13 
     14    Permission is granted to copy, distribute and/or modify this document
     15 under the terms of the GNU Free Documentation License, Version 1.1 or
     16 any later version published by the Free Software Foundation; with no
     17 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
     18 Texts.  A copy of the license is included in the section entitled "GNU
     19 Free Documentation License".
     20 
     21    This file documents the internals of the GNU debugger GDB.
     22 
     23    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
     24 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Free Software
     25 Foundation, Inc.  Contributed by Cygnus Solutions.  Written by John
     26 Gilmore.  Second Edition by Stan Shebs.
     27 
     28    Permission is granted to copy, distribute and/or modify this document
     29 under the terms of the GNU Free Documentation License, Version 1.1 or
     30 any later version published by the Free Software Foundation; with no
     31 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
     32 Texts.  A copy of the license is included in the section entitled "GNU
     33 Free Documentation License".
     34 
     35 
     36 File: gdbint.info,  Node: Top,  Next: Summary,  Up: (dir)
     37 
     38 Scope of this Document
     39 **********************
     40 
     41 This document documents the internals of the GNU debugger, GDB.  It
     42 includes description of GDB's key algorithms and operations, as well as
     43 the mechanisms that adapt GDB to specific hosts and targets.
     44 
     45 * Menu:
     46 
     47 * Summary::
     48 * Overall Structure::
     49 * Algorithms::
     50 * User Interface::
     51 * libgdb::
     52 * Values::
     53 * Stack Frames::
     54 * Symbol Handling::
     55 * Language Support::
     56 * Host Definition::
     57 * Target Architecture Definition::
     58 * Target Descriptions::
     59 * Target Vector Definition::
     60 * Native Debugging::
     61 * Support Libraries::
     62 * Coding::
     63 * Porting GDB::
     64 * Versions and Branches::
     65 * Start of New Year Procedure::
     66 * Releasing GDB::
     67 * Testsuite::
     68 * Hints::
     69 
     70 * GDB Observers::  GDB Currently available observers
     71 * GNU Free Documentation License::  The license for this documentation
     72 * Index::
     73 
     74 
     75 File: gdbint.info,  Node: Summary,  Next: Overall Structure,  Prev: Top,  Up: Top
     76 
     77 1 Summary
     78 *********
     79 
     80 * Menu:
     81 
     82 * Requirements::
     83 * Contributors::
     84 
     85 
     86 File: gdbint.info,  Node: Requirements,  Next: Contributors,  Up: Summary
     87 
     88 1.1 Requirements
     89 ================
     90 
     91 Before diving into the internals, you should understand the formal
     92 requirements and other expectations for GDB.  Although some of these
     93 may seem obvious, there have been proposals for GDB that have run
     94 counter to these requirements.
     95 
     96    First of all, GDB is a debugger.  It's not designed to be a front
     97 panel for embedded systems.  It's not a text editor.  It's not a shell.
     98 It's not a programming environment.
     99 
    100    GDB is an interactive tool.  Although a batch mode is available,
    101 GDB's primary role is to interact with a human programmer.
    102 
    103    GDB should be responsive to the user.  A programmer hot on the trail
    104 of a nasty bug, and operating under a looming deadline, is going to be
    105 very impatient of everything, including the response time to debugger
    106 commands.
    107 
    108    GDB should be relatively permissive, such as for expressions.  While
    109 the compiler should be picky (or have the option to be made picky),
    110 since source code lives for a long time usually, the programmer doing
    111 debugging shouldn't be spending time figuring out to mollify the
    112 debugger.
    113 
    114    GDB will be called upon to deal with really large programs.
    115 Executable sizes of 50 to 100 megabytes occur regularly, and we've
    116 heard reports of programs approaching 1 gigabyte in size.
    117 
    118    GDB should be able to run everywhere.  No other debugger is
    119 available for even half as many configurations as GDB supports.
    120 
    121 
    122 File: gdbint.info,  Node: Contributors,  Prev: Requirements,  Up: Summary
    123 
    124 1.2 Contributors
    125 ================
    126 
    127 The first edition of this document was written by John Gilmore of
    128 Cygnus Solutions. The current second edition was written by Stan Shebs
    129 of Cygnus Solutions, who continues to update the manual.
    130 
    131    Over the years, many others have made additions and changes to this
    132 document. This section attempts to record the significant contributors
    133 to that effort. One of the virtues of free software is that everyone is
    134 free to contribute to it; with regret, we cannot actually acknowledge
    135 everyone here.
    136 
    137      _Plea:_ This section has only been added relatively recently (four
    138      years after publication of the second edition). Additions to this
    139      section are particularly welcome.  If you or your friends (or
    140      enemies, to be evenhanded) have been unfairly omitted from this
    141      list, we would like to add your names!
    142 
    143    A document such as this relies on being kept up to date by numerous
    144 small updates by contributing engineers as they make changes to the
    145 code base. The file `ChangeLog' in the GDB distribution approximates a
    146 blow-by-blow account. The most prolific contributors to this important,
    147 but low profile task are Andrew Cagney (responsible for over half the
    148 entries), Daniel Jacobowitz, Mark Kettenis, Jim Blandy and Eli
    149 Zaretskii.
    150 
    151    Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting
    152 watchpoints.
    153 
    154    Jeremy Bennett updated the sections on initializing a new
    155 architecture and register representation, and added the section on
    156 Frame Interpretation.
    157 
    158 
    159 File: gdbint.info,  Node: Overall Structure,  Next: Algorithms,  Prev: Summary,  Up: Top
    160 
    161 2 Overall Structure
    162 *******************
    163 
    164 GDB consists of three major subsystems: user interface, symbol handling
    165 (the "symbol side"), and target system handling (the "target side").
    166 
    167    The user interface consists of several actual interfaces, plus
    168 supporting code.
    169 
    170    The symbol side consists of object file readers, debugging info
    171 interpreters, symbol table management, source language expression
    172 parsing, type and value printing.
    173 
    174    The target side consists of execution control, stack frame analysis,
    175 and physical target manipulation.
    176 
    177    The target side/symbol side division is not formal, and there are a
    178 number of exceptions.  For instance, core file support involves symbolic
    179 elements (the basic core file reader is in BFD) and target elements (it
    180 supplies the contents of memory and the values of registers).  Instead,
    181 this division is useful for understanding how the minor subsystems
    182 should fit together.
    183 
    184 2.1 The Symbol Side
    185 ===================
    186 
    187 The symbolic side of GDB can be thought of as "everything you can do in
    188 GDB without having a live program running".  For instance, you can look
    189 at the types of variables, and evaluate many kinds of expressions.
    190 
    191 2.2 The Target Side
    192 ===================
    193 
    194 The target side of GDB is the "bits and bytes manipulator".  Although
    195 it may make reference to symbolic info here and there, most of the
    196 target side will run with only a stripped executable available--or even
    197 no executable at all, in remote debugging cases.
    198 
    199    Operations such as disassembly, stack frame crawls, and register
    200 display, are able to work with no symbolic info at all.  In some cases,
    201 such as disassembly, GDB will use symbolic info to present addresses
    202 relative to symbols rather than as raw numbers, but it will work either
    203 way.
    204 
    205 2.3 Configurations
    206 ==================
    207 
    208 "Host" refers to attributes of the system where GDB runs.  "Target"
    209 refers to the system where the program being debugged executes.  In
    210 most cases they are the same machine, in which case a third type of
    211 "Native" attributes come into play.
    212 
    213    Defines and include files needed to build on the host are host
    214 support.  Examples are tty support, system defined types, host byte
    215 order, host float format.  These are all calculated by `autoconf' when
    216 the debugger is built.
    217 
    218    Defines and information needed to handle the target format are target
    219 dependent.  Examples are the stack frame format, instruction set,
    220 breakpoint instruction, registers, and how to set up and tear down the
    221 stack to call a function.
    222 
    223    Information that is only needed when the host and target are the
    224 same, is native dependent.  One example is Unix child process support;
    225 if the host and target are not the same, calling `fork' to start the
    226 target process is a bad idea.  The various macros needed for finding the
    227 registers in the `upage', running `ptrace', and such are all in the
    228 native-dependent files.
    229 
    230    Another example of native-dependent code is support for features that
    231 are really part of the target environment, but which require `#include'
    232 files that are only available on the host system.  Core file handling
    233 and `setjmp' handling are two common cases.
    234 
    235    When you want to make GDB work as the traditional native debugger on
    236 a system, you will need to supply both target and native information.
    237 
    238 2.4 Source Tree Structure
    239 =========================
    240 
    241 The GDB source directory has a mostly flat structure--there are only a
    242 few subdirectories.  A file's name usually gives a hint as to what it
    243 does; for example, `stabsread.c' reads stabs, `dwarf2read.c' reads
    244 DWARF 2, etc.
    245 
    246    Files that are related to some common task have names that share
    247 common substrings.  For example, `*-thread.c' files deal with debugging
    248 threads on various platforms; `*read.c' files deal with reading various
    249 kinds of symbol and object files; `inf*.c' files deal with direct
    250 control of the "inferior program" (GDB parlance for the program being
    251 debugged).
    252 
    253    There are several dozens of files in the `*-tdep.c' family.  `tdep'
    254 stands for "target-dependent code"--each of these files implements
    255 debug support for a specific target architecture (sparc, mips, etc).
    256 Usually, only one of these will be used in a specific GDB configuration
    257 (sometimes two, closely related).
    258 
    259    Similarly, there are many `*-nat.c' files, each one for native
    260 debugging on a specific system (e.g., `sparc-linux-nat.c' is for native
    261 debugging of Sparc machines running the Linux kernel).
    262 
    263    The few subdirectories of the source tree are:
    264 
    265 `cli'
    266      Code that implements "CLI", the GDB Command-Line Interpreter.
    267      *Note Command Interpreter: User Interface.
    268 
    269 `gdbserver'
    270      Code for the GDB remote server.
    271 
    272 `gdbtk'
    273      Code for Insight, the GDB TK-based GUI front-end.
    274 
    275 `mi'
    276      The "GDB/MI", the GDB Machine Interface interpreter.
    277 
    278 `signals'
    279      Target signal translation code.
    280 
    281 `tui'
    282      Code for "TUI", the GDB Text-mode full-screen User Interface.
    283      *Note TUI: User Interface.
    284 
    285 
    286 File: gdbint.info,  Node: Algorithms,  Next: User Interface,  Prev: Overall Structure,  Up: Top
    287 
    288 3 Algorithms
    289 ************
    290 
    291 GDB uses a number of debugging-specific algorithms.  They are often not
    292 very complicated, but get lost in the thicket of special cases and
    293 real-world issues.  This chapter describes the basic algorithms and
    294 mentions some of the specific target definitions that they use.
    295 
    296 3.1 Prologue Analysis
    297 =====================
    298 
    299 To produce a backtrace and allow the user to manipulate older frames'
    300 variables and arguments, GDB needs to find the base addresses of older
    301 frames, and discover where those frames' registers have been saved.
    302 Since a frame's "callee-saves" registers get saved by younger frames if
    303 and when they're reused, a frame's registers may be scattered
    304 unpredictably across younger frames.  This means that changing the
    305 value of a register-allocated variable in an older frame may actually
    306 entail writing to a save slot in some younger frame.
    307 
    308    Modern versions of GCC emit Dwarf call frame information ("CFI"),
    309 which describes how to find frame base addresses and saved registers.
    310 But CFI is not always available, so as a fallback GDB uses a technique
    311 called "prologue analysis" to find frame sizes and saved registers.  A
    312 prologue analyzer disassembles the function's machine code starting
    313 from its entry point, and looks for instructions that allocate frame
    314 space, save the stack pointer in a frame pointer register, save
    315 registers, and so on.  Obviously, this can't be done accurately in
    316 general, but it's tractable to do well enough to be very helpful.
    317 Prologue analysis predates the GNU toolchain's support for CFI; at one
    318 time, prologue analysis was the only mechanism GDB used for stack
    319 unwinding at all, when the function calling conventions didn't specify
    320 a fixed frame layout.
    321 
    322    In the olden days, function prologues were generated by hand-written,
    323 target-specific code in GCC, and treated as opaque and untouchable by
    324 optimizers.  Looking at this code, it was usually straightforward to
    325 write a prologue analyzer for GDB that would accurately understand all
    326 the prologues GCC would generate.  However, over time GCC became more
    327 aggressive about instruction scheduling, and began to understand more
    328 about the semantics of the prologue instructions themselves; in
    329 response, GDB's analyzers became more complex and fragile.  Keeping the
    330 prologue analyzers working as GCC (and the instruction sets themselves)
    331 evolved became a substantial task.
    332 
    333    To try to address this problem, the code in `prologue-value.h' and
    334 `prologue-value.c' provides a general framework for writing prologue
    335 analyzers that are simpler and more robust than ad-hoc analyzers.  When
    336 we analyze a prologue using the prologue-value framework, we're really
    337 doing "abstract interpretation" or "pseudo-evaluation": running the
    338 function's code in simulation, but using conservative approximations of
    339 the values registers and memory would hold when the code actually runs.
    340 For example, if our function starts with the instruction:
    341 
    342      addi r1, 42     # add 42 to r1
    343    we don't know exactly what value will be in `r1' after executing
    344 this instruction, but we do know it'll be 42 greater than its original
    345 value.
    346 
    347    If we then see an instruction like:
    348 
    349      addi r1, 22     # add 22 to r1
    350    we still don't know what `r1's' value is, but again, we can say it
    351 is now 64 greater than its original value.
    352 
    353    If the next instruction were:
    354 
    355      mov r2, r1      # set r2 to r1's value
    356    then we can say that `r2's' value is now the original value of `r1'
    357 plus 64.
    358 
    359    It's common for prologues to save registers on the stack, so we'll
    360 need to track the values of stack frame slots, as well as the
    361 registers.  So after an instruction like this:
    362 
    363      mov (fp+4), r2
    364    then we'd know that the stack slot four bytes above the frame pointer
    365 holds the original value of `r1' plus 64.
    366 
    367    And so on.
    368 
    369    Of course, this can only go so far before it gets unreasonable.  If
    370 we wanted to be able to say anything about the value of `r1' after the
    371 instruction:
    372 
    373      xor r1, r3      # exclusive-or r1 and r3, place result in r1
    374    then things would get pretty complex.  But remember, we're just doing
    375 a conservative approximation; if exclusive-or instructions aren't
    376 relevant to prologues, we can just say `r1''s value is now "unknown".
    377 We can ignore things that are too complex, if that loss of information
    378 is acceptable for our application.
    379 
    380    So when we say "conservative approximation" here, what we mean is an
    381 approximation that is either accurate, or marked "unknown", but never
    382 inaccurate.
    383 
    384    Using this framework, a prologue analyzer is simply an interpreter
    385 for machine code, but one that uses conservative approximations for the
    386 contents of registers and memory instead of actual values.  Starting
    387 from the function's entry point, you simulate instructions up to the
    388 current PC, or an instruction that you don't know how to simulate.  Now
    389 you can examine the state of the registers and stack slots you've kept
    390 track of.
    391 
    392    * To see how large your stack frame is, just check the value of the
    393      stack pointer register; if it's the original value of the SP minus
    394      a constant, then that constant is the stack frame's size.  If the
    395      SP's value has been marked as "unknown", then that means the
    396      prologue has done something too complex for us to track, and we
    397      don't know the frame size.
    398 
    399    * To see where we've saved the previous frame's registers, we just
    400      search the values we've tracked -- stack slots, usually, but
    401      registers, too, if you want -- for something equal to the
    402      register's original value.  If the calling conventions suggest a
    403      standard place to save a given register, then we can check there
    404      first, but really, anything that will get us back the original
    405      value will probably work.
    406 
    407    This does take some work.  But prologue analyzers aren't
    408 quick-and-simple pattern patching to recognize a few fixed prologue
    409 forms any more; they're big, hairy functions.  Along with inferior
    410 function calls, prologue analysis accounts for a substantial portion of
    411 the time needed to stabilize a GDB port.  So it's worthwhile to look
    412 for an approach that will be easier to understand and maintain.  In the
    413 approach described above:
    414 
    415    * It's easier to see that the analyzer is correct: you just see
    416      whether the analyzer properly (albeit conservatively) simulates
    417      the effect of each instruction.
    418 
    419    * It's easier to extend the analyzer: you can add support for new
    420      instructions, and know that you haven't broken anything that
    421      wasn't already broken before.
    422 
    423    * It's orthogonal: to gather new information, you don't need to
    424      complicate the code for each instruction.  As long as your domain
    425      of conservative values is already detailed enough to tell you what
    426      you need, then all the existing instruction simulations are
    427      already gathering the right data for you.
    428 
    429 
    430    The file `prologue-value.h' contains detailed comments explaining
    431 the framework and how to use it.
    432 
    433 3.2 Breakpoint Handling
    434 =======================
    435 
    436 In general, a breakpoint is a user-designated location in the program
    437 where the user wants to regain control if program execution ever reaches
    438 that location.
    439 
    440    There are two main ways to implement breakpoints; either as
    441 "hardware" breakpoints or as "software" breakpoints.
    442 
    443    Hardware breakpoints are sometimes available as a builtin debugging
    444 features with some chips.  Typically these work by having dedicated
    445 register into which the breakpoint address may be stored.  If the PC
    446 (shorthand for "program counter") ever matches a value in a breakpoint
    447 registers, the CPU raises an exception and reports it to GDB.
    448 
    449    Another possibility is when an emulator is in use; many emulators
    450 include circuitry that watches the address lines coming out from the
    451 processor, and force it to stop if the address matches a breakpoint's
    452 address.
    453 
    454    A third possibility is that the target already has the ability to do
    455 breakpoints somehow; for instance, a ROM monitor may do its own
    456 software breakpoints.  So although these are not literally "hardware
    457 breakpoints", from GDB's point of view they work the same; GDB need not
    458 do anything more than set the breakpoint and wait for something to
    459 happen.
    460 
    461    Since they depend on hardware resources, hardware breakpoints may be
    462 limited in number; when the user asks for more, GDB will start trying
    463 to set software breakpoints.  (On some architectures, notably the
    464 32-bit x86 platforms, GDB cannot always know whether there's enough
    465 hardware resources to insert all the hardware breakpoints and
    466 watchpoints.  On those platforms, GDB prints an error message only when
    467 the program being debugged is continued.)
    468 
    469    Software breakpoints require GDB to do somewhat more work.  The
    470 basic theory is that GDB will replace a program instruction with a
    471 trap, illegal divide, or some other instruction that will cause an
    472 exception, and then when it's encountered, GDB will take the exception
    473 and stop the program.  When the user says to continue, GDB will restore
    474 the original instruction, single-step, re-insert the trap, and continue
    475 on.
    476 
    477    Since it literally overwrites the program being tested, the program
    478 area must be writable, so this technique won't work on programs in ROM.
    479 It can also distort the behavior of programs that examine themselves,
    480 although such a situation would be highly unusual.
    481 
    482    Also, the software breakpoint instruction should be the smallest
    483 size of instruction, so it doesn't overwrite an instruction that might
    484 be a jump target, and cause disaster when the program jumps into the
    485 middle of the breakpoint instruction.  (Strictly speaking, the
    486 breakpoint must be no larger than the smallest interval between
    487 instructions that may be jump targets; perhaps there is an architecture
    488 where only even-numbered instructions may jumped to.)  Note that it's
    489 possible for an instruction set not to have any instructions usable for
    490 a software breakpoint, although in practice only the ARC has failed to
    491 define such an instruction.
    492 
    493    Basic breakpoint object handling is in `breakpoint.c'.  However,
    494 much of the interesting breakpoint action is in `infrun.c'.
    495 
    496 `target_remove_breakpoint (BP_TGT)'
    497 `target_insert_breakpoint (BP_TGT)'
    498      Insert or remove a software breakpoint at address
    499      `BP_TGT->placed_address'.  Returns zero for success, non-zero for
    500      failure.  On input, BP_TGT contains the address of the breakpoint,
    501      and is otherwise initialized to zero.  The fields of the `struct
    502      bp_target_info' pointed to by BP_TGT are updated to contain other
    503      information about the breakpoint on output.  The field
    504      `placed_address' may be updated if the breakpoint was placed at a
    505      related address; the field `shadow_contents' contains the real
    506      contents of the bytes where the breakpoint has been inserted, if
    507      reading memory would return the breakpoint instead of the
    508      underlying memory; the field `shadow_len' is the length of memory
    509      cached in `shadow_contents', if any; and the field `placed_size'
    510      is optionally set and used by the target, if it could differ from
    511      `shadow_len'.
    512 
    513      For example, the remote target `Z0' packet does not require
    514      shadowing memory, so `shadow_len' is left at zero.  However, the
    515      length reported by `gdbarch_breakpoint_from_pc' is cached in
    516      `placed_size', so that a matching `z0' packet can be used to
    517      remove the breakpoint.
    518 
    519 `target_remove_hw_breakpoint (BP_TGT)'
    520 `target_insert_hw_breakpoint (BP_TGT)'
    521      Insert or remove a hardware-assisted breakpoint at address
    522      `BP_TGT->placed_address'.  Returns zero for success, non-zero for
    523      failure.  See `target_insert_breakpoint' for a description of the
    524      `struct bp_target_info' pointed to by BP_TGT; the
    525      `shadow_contents' and `shadow_len' members are not used for
    526      hardware breakpoints, but `placed_size' may be.
    527 
    528 3.3 Single Stepping
    529 ===================
    530 
    531 3.4 Signal Handling
    532 ===================
    533 
    534 3.5 Thread Handling
    535 ===================
    536 
    537 3.6 Inferior Function Calls
    538 ===========================
    539 
    540 3.7 Longjmp Support
    541 ===================
    542 
    543 GDB has support for figuring out that the target is doing a `longjmp'
    544 and for stopping at the target of the jump, if we are stepping.  This
    545 is done with a few specialized internal breakpoints, which are visible
    546 in the output of the `maint info breakpoint' command.
    547 
    548    To make this work, you need to define a function called
    549 `gdbarch_get_longjmp_target', which will examine the `jmp_buf'
    550 structure and extract the `longjmp' target address.  Since `jmp_buf' is
    551 target specific and typically defined in a target header not available
    552 to GDB, you will need to determine the offset of the PC manually and
    553 return that; many targets define a `jb_pc_offset' field in the tdep
    554 structure to save the value once calculated.
    555 
    556 3.8 Watchpoints
    557 ===============
    558 
    559 Watchpoints are a special kind of breakpoints (*note breakpoints:
    560 Algorithms.) which break when data is accessed rather than when some
    561 instruction is executed.  When you have data which changes without your
    562 knowing what code does that, watchpoints are the silver bullet to hunt
    563 down and kill such bugs.
    564 
    565    Watchpoints can be either hardware-assisted or not; the latter type
    566 is known as "software watchpoints."  GDB always uses hardware-assisted
    567 watchpoints if they are available, and falls back on software
    568 watchpoints otherwise.  Typical situations where GDB will use software
    569 watchpoints are:
    570 
    571    * The watched memory region is too large for the underlying hardware
    572      watchpoint support.  For example, each x86 debug register can
    573      watch up to 4 bytes of memory, so trying to watch data structures
    574      whose size is more than 16 bytes will cause GDB to use software
    575      watchpoints.
    576 
    577    * The value of the expression to be watched depends on data held in
    578      registers (as opposed to memory).
    579 
    580    * Too many different watchpoints requested.  (On some architectures,
    581      this situation is impossible to detect until the debugged program
    582      is resumed.)  Note that x86 debug registers are used both for
    583      hardware breakpoints and for watchpoints, so setting too many
    584      hardware breakpoints might cause watchpoint insertion to fail.
    585 
    586    * No hardware-assisted watchpoints provided by the target
    587      implementation.
    588 
    589    Software watchpoints are very slow, since GDB needs to single-step
    590 the program being debugged and test the value of the watched
    591 expression(s) after each instruction.  The rest of this section is
    592 mostly irrelevant for software watchpoints.
    593 
    594    When the inferior stops, GDB tries to establish, among other
    595 possible reasons, whether it stopped due to a watchpoint being hit.  It
    596 first uses `STOPPED_BY_WATCHPOINT' to see if any watchpoint was hit.
    597 If not, all watchpoint checking is skipped.
    598 
    599    Then GDB calls `target_stopped_data_address' exactly once.  This
    600 method returns the address of the watchpoint which triggered, if the
    601 target can determine it.  If the triggered address is available, GDB
    602 compares the address returned by this method with each watched memory
    603 address in each active watchpoint.  For data-read and data-access
    604 watchpoints, GDB announces every watchpoint that watches the triggered
    605 address as being hit.  For this reason, data-read and data-access
    606 watchpoints _require_ that the triggered address be available; if not,
    607 read and access watchpoints will never be considered hit.  For
    608 data-write watchpoints, if the triggered address is available, GDB
    609 considers only those watchpoints which match that address; otherwise,
    610 GDB considers all data-write watchpoints.  For each data-write
    611 watchpoint that GDB considers, it evaluates the expression whose value
    612 is being watched, and tests whether the watched value has changed.
    613 Watchpoints whose watched values have changed are announced as hit.
    614 
    615    GDB uses several macros and primitives to support hardware
    616 watchpoints:
    617 
    618 `TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'
    619      Return the number of hardware watchpoints of type TYPE that are
    620      possible to be set.  The value is positive if COUNT watchpoints of
    621      this type can be set, zero if setting watchpoints of this type is
    622      not supported, and negative if COUNT is more than the maximum
    623      number of watchpoints of type TYPE that can be set.  OTHER is
    624      non-zero if other types of watchpoints are currently enabled (there
    625      are architectures which cannot set watchpoints of different types
    626      at the same time).
    627 
    628 `TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'
    629      Return non-zero if hardware watchpoints can be used to watch a
    630      region whose address is ADDR and whose length in bytes is LEN.
    631 
    632 `target_insert_watchpoint (ADDR, LEN, TYPE)'
    633 `target_remove_watchpoint (ADDR, LEN, TYPE)'
    634      Insert or remove a hardware watchpoint starting at ADDR, for LEN
    635      bytes.  TYPE is the watchpoint type, one of the possible values of
    636      the enumerated data type `target_hw_bp_type', defined by
    637      `breakpoint.h' as follows:
    638 
    639            enum target_hw_bp_type
    640              {
    641                hw_write   = 0, /* Common (write) HW watchpoint */
    642                hw_read    = 1, /* Read    HW watchpoint */
    643                hw_access  = 2, /* Access (read or write) HW watchpoint */
    644                hw_execute = 3  /* Execute HW breakpoint */
    645              };
    646 
    647      These two macros should return 0 for success, non-zero for failure.
    648 
    649 `target_stopped_data_address (ADDR_P)'
    650      If the inferior has some watchpoint that triggered, place the
    651      address associated with the watchpoint at the location pointed to
    652      by ADDR_P and return non-zero.  Otherwise, return zero.  This is
    653      required for data-read and data-access watchpoints.  It is not
    654      required for data-write watchpoints, but GDB uses it to improve
    655      handling of those also.
    656 
    657      GDB will only call this method once per watchpoint stop,
    658      immediately after calling `STOPPED_BY_WATCHPOINT'.  If the
    659      target's watchpoint indication is sticky, i.e., stays set after
    660      resuming, this method should clear it.  For instance, the x86 debug
    661      control register has sticky triggered flags.
    662 
    663 `target_watchpoint_addr_within_range (TARGET, ADDR, START, LENGTH)'
    664      Check whether ADDR (as returned by `target_stopped_data_address')
    665      lies within the hardware-defined watchpoint region described by
    666      START and LENGTH.  This only needs to be provided if the
    667      granularity of a watchpoint is greater than one byte, i.e., if the
    668      watchpoint can also trigger on nearby addresses outside of the
    669      watched region.
    670 
    671 `HAVE_STEPPABLE_WATCHPOINT'
    672      If defined to a non-zero value, it is not necessary to disable a
    673      watchpoint to step over it.  Like
    674      `gdbarch_have_nonsteppable_watchpoint', this is usually set when
    675      watchpoints trigger at the instruction which will perform an
    676      interesting read or write.  It should be set if there is a
    677      temporary disable bit which allows the processor to step over the
    678      interesting instruction without raising the watchpoint exception
    679      again.
    680 
    681 `int gdbarch_have_nonsteppable_watchpoint (GDBARCH)'
    682      If it returns a non-zero value, GDB should disable a watchpoint to
    683      step the inferior over it.  This is usually set when watchpoints
    684      trigger at the instruction which will perform an interesting read
    685      or write.
    686 
    687 `HAVE_CONTINUABLE_WATCHPOINT'
    688      If defined to a non-zero value, it is possible to continue the
    689      inferior after a watchpoint has been hit.  This is usually set
    690      when watchpoints trigger at the instruction following an
    691      interesting read or write.
    692 
    693 `CANNOT_STEP_HW_WATCHPOINTS'
    694      If this is defined to a non-zero value, GDB will remove all
    695      watchpoints before stepping the inferior.
    696 
    697 `STOPPED_BY_WATCHPOINT (WAIT_STATUS)'
    698      Return non-zero if stopped by a watchpoint.  WAIT_STATUS is of the
    699      type `struct target_waitstatus', defined by `target.h'.  Normally,
    700      this macro is defined to invoke the function pointed to by the
    701      `to_stopped_by_watchpoint' member of the structure (of the type
    702      `target_ops', defined on `target.h') that describes the
    703      target-specific operations; `to_stopped_by_watchpoint' ignores the
    704      WAIT_STATUS argument.
    705 
    706      GDB does not require the non-zero value returned by
    707      `STOPPED_BY_WATCHPOINT' to be 100% correct, so if a target cannot
    708      determine for sure whether the inferior stopped due to a
    709      watchpoint, it could return non-zero "just in case".
    710 
    711 3.8.1 Watchpoints and Threads
    712 -----------------------------
    713 
    714 GDB only supports process-wide watchpoints, which trigger in all
    715 threads.  GDB uses the thread ID to make watchpoints act as if they
    716 were thread-specific, but it cannot set hardware watchpoints that only
    717 trigger in a specific thread.  Therefore, even if the target supports
    718 threads, per-thread debug registers, and watchpoints which only affect
    719 a single thread, it should set the per-thread debug registers for all
    720 threads to the same value.  On GNU/Linux native targets, this is
    721 accomplished by using `ALL_LWPS' in `target_insert_watchpoint' and
    722 `target_remove_watchpoint' and by using `linux_set_new_thread' to
    723 register a handler for newly created threads.
    724 
    725    GDB's GNU/Linux support only reports a single event at a time,
    726 although multiple events can trigger simultaneously for multi-threaded
    727 programs.  When multiple events occur, `linux-nat.c' queues subsequent
    728 events and returns them the next time the program is resumed.  This
    729 means that `STOPPED_BY_WATCHPOINT' and `target_stopped_data_address'
    730 only need to consult the current thread's state--the thread indicated
    731 by `inferior_ptid'.  If two threads have hit watchpoints
    732 simultaneously, those routines will be called a second time for the
    733 second thread.
    734 
    735 3.8.2 x86 Watchpoints
    736 ---------------------
    737 
    738 The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug
    739 registers designed to facilitate debugging.  GDB provides a generic
    740 library of functions that x86-based ports can use to implement support
    741 for watchpoints and hardware-assisted breakpoints.  This subsection
    742 documents the x86 watchpoint facilities in GDB.
    743 
    744    (At present, the library functions read and write debug registers
    745 directly, and are thus only available for native configurations.)
    746 
    747    To use the generic x86 watchpoint support, a port should do the
    748 following:
    749 
    750    * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the
    751      target-dependent headers.
    752 
    753    * Include the `config/i386/nm-i386.h' header file _after_ defining
    754      `I386_USE_GENERIC_WATCHPOINTS'.
    755 
    756    * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'
    757      (*note NATDEPFILES: Native Debugging.).
    758 
    759    * Provide implementations for the `I386_DR_LOW_*' macros described
    760      below.  Typically, each macro should call a target-specific
    761      function which does the real work.
    762 
    763    The x86 watchpoint support works by maintaining mirror images of the
    764 debug registers.  Values are copied between the mirror images and the
    765 real debug registers via a set of macros which each target needs to
    766 provide:
    767 
    768 `I386_DR_LOW_SET_CONTROL (VAL)'
    769      Set the Debug Control (DR7) register to the value VAL.
    770 
    771 `I386_DR_LOW_SET_ADDR (IDX, ADDR)'
    772      Put the address ADDR into the debug register number IDX.
    773 
    774 `I386_DR_LOW_RESET_ADDR (IDX)'
    775      Reset (i.e. zero out) the address stored in the debug register
    776      number IDX.
    777 
    778 `I386_DR_LOW_GET_STATUS'
    779      Return the value of the Debug Status (DR6) register.  This value is
    780      used immediately after it is returned by `I386_DR_LOW_GET_STATUS',
    781      so as to support per-thread status register values.
    782 
    783    For each one of the 4 debug registers (whose indices are from 0 to 3)
    784 that store addresses, a reference count is maintained by GDB, to allow
    785 sharing of debug registers by several watchpoints.  This allows users
    786 to define several watchpoints that watch the same expression, but with
    787 different conditions and/or commands, without wasting debug registers
    788 which are in short supply.  GDB maintains the reference counts
    789 internally, targets don't have to do anything to use this feature.
    790 
    791    The x86 debug registers can each watch a region that is 1, 2, or 4
    792 bytes long.  The ia32 architecture requires that each watched region be
    793 appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region
    794 on 4-byte boundary.  However, the x86 watchpoint support in GDB can
    795 watch unaligned regions and regions larger than 4 bytes (up to 16
    796 bytes) by allocating several debug registers to watch a single region.
    797 This allocation of several registers per a watched region is also done
    798 automatically without target code intervention.
    799 
    800    The generic x86 watchpoint support provides the following API for the
    801 GDB's application code:
    802 
    803 `i386_region_ok_for_watchpoint (ADDR, LEN)'
    804      The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this
    805      function.  It counts the number of debug registers required to
    806      watch a given region, and returns a non-zero value if that number
    807      is less than 4, the number of debug registers available to x86
    808      processors.
    809 
    810 `i386_stopped_data_address (ADDR_P)'
    811      The target function `target_stopped_data_address' is set to call
    812      this function.  This function examines the breakpoint condition
    813      bits in the DR6 Debug Status register, as returned by the
    814      `I386_DR_LOW_GET_STATUS' macro, and returns the address associated
    815      with the first bit that is set in DR6.
    816 
    817 `i386_stopped_by_watchpoint (void)'
    818      The macro `STOPPED_BY_WATCHPOINT' is set to call this function.
    819      The argument passed to `STOPPED_BY_WATCHPOINT' is ignored.  This
    820      function examines the breakpoint condition bits in the DR6 Debug
    821      Status register, as returned by the `I386_DR_LOW_GET_STATUS'
    822      macro, and returns true if any bit is set.  Otherwise, false is
    823      returned.
    824 
    825 `i386_insert_watchpoint (ADDR, LEN, TYPE)'
    826 `i386_remove_watchpoint (ADDR, LEN, TYPE)'
    827      Insert or remove a watchpoint.  The macros
    828      `target_insert_watchpoint' and `target_remove_watchpoint' are set
    829      to call these functions.  `i386_insert_watchpoint' first looks for
    830      a debug register which is already set to watch the same region for
    831      the same access types; if found, it just increments the reference
    832      count of that debug register, thus implementing debug register
    833      sharing between watchpoints.  If no such register is found, the
    834      function looks for a vacant debug register, sets its mirrored
    835      value to ADDR, sets the mirrored value of DR7 Debug Control
    836      register as appropriate for the LEN and TYPE parameters, and then
    837      passes the new values of the debug register and DR7 to the
    838      inferior by calling `I386_DR_LOW_SET_ADDR' and
    839      `I386_DR_LOW_SET_CONTROL'.  If more than one debug register is
    840      required to cover the given region, the above process is repeated
    841      for each debug register.
    842 
    843      `i386_remove_watchpoint' does the opposite: it resets the address
    844      in the mirrored value of the debug register and its read/write and
    845      length bits in the mirrored value of DR7, then passes these new
    846      values to the inferior via `I386_DR_LOW_RESET_ADDR' and
    847      `I386_DR_LOW_SET_CONTROL'.  If a register is shared by several
    848      watchpoints, each time a `i386_remove_watchpoint' is called, it
    849      decrements the reference count, and only calls
    850      `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the
    851      count goes to zero.
    852 
    853 `i386_insert_hw_breakpoint (BP_TGT)'
    854 `i386_remove_hw_breakpoint (BP_TGT)'
    855      These functions insert and remove hardware-assisted breakpoints.
    856      The macros `target_insert_hw_breakpoint' and
    857      `target_remove_hw_breakpoint' are set to call these functions.
    858      The argument is a `struct bp_target_info *', as described in the
    859      documentation for `target_insert_breakpoint'.  These functions
    860      work like `i386_insert_watchpoint' and `i386_remove_watchpoint',
    861      respectively, except that they set up the debug registers to watch
    862      instruction execution, and each hardware-assisted breakpoint
    863      always requires exactly one debug register.
    864 
    865 `i386_cleanup_dregs (void)'
    866      This function clears all the reference counts, addresses, and
    867      control bits in the mirror images of the debug registers.  It
    868      doesn't affect the actual debug registers in the inferior process.
    869 
    870 *Notes:*
    871   1. x86 processors support setting watchpoints on I/O reads or writes.
    872      However, since no target supports this (as of March 2001), and
    873      since `enum target_hw_bp_type' doesn't even have an enumeration
    874      for I/O watchpoints, this feature is not yet available to GDB
    875      running on x86.
    876 
    877   2. x86 processors can enable watchpoints locally, for the current task
    878      only, or globally, for all the tasks.  For each debug register,
    879      there's a bit in the DR7 Debug Control register that determines
    880      whether the associated address is watched locally or globally.  The
    881      current implementation of x86 watchpoint support in GDB always
    882      sets watchpoints to be locally enabled, since global watchpoints
    883      might interfere with the underlying OS and are probably
    884      unavailable in many platforms.
    885 
    886 3.9 Checkpoints
    887 ===============
    888 
    889 In the abstract, a checkpoint is a point in the execution history of
    890 the program, which the user may wish to return to at some later time.
    891 
    892    Internally, a checkpoint is a saved copy of the program state,
    893 including whatever information is required in order to restore the
    894 program to that state at a later time.  This can be expected to include
    895 the state of registers and memory, and may include external state such
    896 as the state of open files and devices.
    897 
    898    There are a number of ways in which checkpoints may be implemented
    899 in gdb, e.g. as corefiles, as forked processes, and as some opaque
    900 method implemented on the target side.
    901 
    902    A corefile can be used to save an image of target memory and register
    903 state, which can in principle be restored later -- but corefiles do not
    904 typically include information about external entities such as open
    905 files.  Currently this method is not implemented in gdb.
    906 
    907    A forked process can save the state of user memory and registers, as
    908 well as some subset of external (kernel) state.  This method is used to
    909 implement checkpoints on Linux, and in principle might be used on other
    910 systems.
    911 
    912    Some targets, e.g. simulators, might have their own built-in method
    913 for saving checkpoints, and gdb might be able to take advantage of that
    914 capability without necessarily knowing any details of how it is done.
    915 
    916 3.10 Observing changes in GDB internals
    917 =======================================
    918 
    919 In order to function properly, several modules need to be notified when
    920 some changes occur in the GDB internals.  Traditionally, these modules
    921 have relied on several paradigms, the most common ones being hooks and
    922 gdb-events.  Unfortunately, none of these paradigms was versatile
    923 enough to become the standard notification mechanism in GDB.  The fact
    924 that they only supported one "client" was also a strong limitation.
    925 
    926    A new paradigm, based on the Observer pattern of the `Design
    927 Patterns' book, has therefore been implemented.  The goal was to provide
    928 a new interface overcoming the issues with the notification mechanisms
    929 previously available.  This new interface needed to be strongly typed,
    930 easy to extend, and versatile enough to be used as the standard
    931 interface when adding new notifications.
    932 
    933    See *note GDB Observers:: for a brief description of the observers
    934 currently implemented in GDB. The rationale for the current
    935 implementation is also briefly discussed.
    936 
    937 
    938 File: gdbint.info,  Node: User Interface,  Next: libgdb,  Prev: Algorithms,  Up: Top
    939 
    940 4 User Interface
    941 ****************
    942 
    943 GDB has several user interfaces, of which the traditional command-line
    944 interface is perhaps the most familiar.
    945 
    946 4.1 Command Interpreter
    947 =======================
    948 
    949 The command interpreter in GDB is fairly simple.  It is designed to
    950 allow for the set of commands to be augmented dynamically, and also has
    951 a recursive subcommand capability, where the first argument to a
    952 command may itself direct a lookup on a different command list.
    953 
    954    For instance, the `set' command just starts a lookup on the
    955 `setlist' command list, while `set thread' recurses to the
    956 `set_thread_cmd_list'.
    957 
    958    To add commands in general, use `add_cmd'.  `add_com' adds to the
    959 main command list, and should be used for those commands.  The usual
    960 place to add commands is in the `_initialize_XYZ' routines at the ends
    961 of most source files.
    962 
    963    To add paired `set' and `show' commands, use `add_setshow_cmd' or
    964 `add_setshow_cmd_full'.  The former is a slightly simpler interface
    965 which is useful when you don't need to further modify the new command
    966 structures, while the latter returns the new command structures for
    967 manipulation.
    968 
    969    Before removing commands from the command set it is a good idea to
    970 deprecate them for some time.  Use `deprecate_cmd' on commands or
    971 aliases to set the deprecated flag.  `deprecate_cmd' takes a `struct
    972 cmd_list_element' as it's first argument.  You can use the return value
    973 from `add_com' or `add_cmd' to deprecate the command immediately after
    974 it is created.
    975 
    976    The first time a command is used the user will be warned and offered
    977 a replacement (if one exists). Note that the replacement string passed
    978 to `deprecate_cmd' should be the full name of the command, i.e., the
    979 entire string the user should type at the command line.
    980 
    981 4.2 UI-Independent Output--the `ui_out' Functions
    982 =================================================
    983 
    984 The `ui_out' functions present an abstraction level for the GDB output
    985 code.  They hide the specifics of different user interfaces supported
    986 by GDB, and thus free the programmer from the need to write several
    987 versions of the same code, one each for every UI, to produce output.
    988 
    989 4.2.1 Overview and Terminology
    990 ------------------------------
    991 
    992 In general, execution of each GDB command produces some sort of output,
    993 and can even generate an input request.
    994 
    995    Output can be generated for the following purposes:
    996 
    997    * to display a _result_ of an operation;
    998 
    999    * to convey _info_ or produce side-effects of a requested operation;
   1000 
   1001    * to provide a _notification_ of an asynchronous event (including
   1002      progress indication of a prolonged asynchronous operation);
   1003 
   1004    * to display _error messages_ (including warnings);
   1005 
   1006    * to show _debug data_;
   1007 
   1008    * to _query_ or prompt a user for input (a special case).
   1009 
   1010 This section mainly concentrates on how to build result output,
   1011 although some of it also applies to other kinds of output.
   1012 
   1013    Generation of output that displays the results of an operation
   1014 involves one or more of the following:
   1015 
   1016    * output of the actual data
   1017 
   1018    * formatting the output as appropriate for console output, to make it
   1019      easily readable by humans
   1020 
   1021    * machine oriented formatting-a more terse formatting to allow for
   1022      easy parsing by programs which read GDB's output
   1023 
   1024    * annotation, whose purpose is to help legacy GUIs to identify
   1025      interesting parts in the output
   1026 
   1027    The `ui_out' routines take care of the first three aspects.
   1028 Annotations are provided by separate annotation routines.  Note that use
   1029 of annotations for an interface between a GUI and GDB is deprecated.
   1030 
   1031    Output can be in the form of a single item, which we call a "field";
   1032 a "list" consisting of identical fields; a "tuple" consisting of
   1033 non-identical fields; or a "table", which is a tuple consisting of a
   1034 header and a body.  In a BNF-like form:
   1035 
   1036 `<table> ==>'
   1037      `<header> <body>'
   1038 
   1039 `<header> ==>'
   1040      `{ <column> }'
   1041 
   1042 `<column> ==>'
   1043      `<width> <alignment> <title>'
   1044 
   1045 `<body> ==>'
   1046      `{<row>}'
   1047 
   1048 4.2.2 General Conventions
   1049 -------------------------
   1050 
   1051 Most `ui_out' routines are of type `void', the exceptions are
   1052 `ui_out_stream_new' (which returns a pointer to the newly created
   1053 object) and the `make_cleanup' routines.
   1054 
   1055    The first parameter is always the `ui_out' vector object, a pointer
   1056 to a `struct ui_out'.
   1057 
   1058    The FORMAT parameter is like in `printf' family of functions.  When
   1059 it is present, there must also be a variable list of arguments
   1060 sufficient used to satisfy the `%' specifiers in the supplied format.
   1061 
   1062    When a character string argument is not used in a `ui_out' function
   1063 call, a `NULL' pointer has to be supplied instead.
   1064 
   1065 4.2.3 Table, Tuple and List Functions
   1066 -------------------------------------
   1067 
   1068 This section introduces `ui_out' routines for building lists, tuples
   1069 and tables.  The routines to output the actual data items (fields) are
   1070 presented in the next section.
   1071 
   1072    To recap: A "tuple" is a sequence of "fields", each field containing
   1073 information about an object; a "list" is a sequence of fields where
   1074 each field describes an identical object.
   1075 
   1076    Use the "table" functions when your output consists of a list of
   1077 rows (tuples) and the console output should include a heading.  Use this
   1078 even when you are listing just one object but you still want the header.
   1079 
   1080    Tables can not be nested.  Tuples and lists can be nested up to a
   1081 maximum of five levels.
   1082 
   1083    The overall structure of the table output code is something like
   1084 this:
   1085 
   1086        ui_out_table_begin
   1087          ui_out_table_header
   1088          ...
   1089          ui_out_table_body
   1090            ui_out_tuple_begin
   1091              ui_out_field_*
   1092              ...
   1093            ui_out_tuple_end
   1094            ...
   1095        ui_out_table_end
   1096 
   1097    Here is the description of table-, tuple- and list-related `ui_out'
   1098 functions:
   1099 
   1100  -- Function: void ui_out_table_begin (struct ui_out *UIOUT, int
   1101           NBROFCOLS, int NR_ROWS, const char *TBLID)
   1102      The function `ui_out_table_begin' marks the beginning of the output
   1103      of a table.  It should always be called before any other `ui_out'
   1104      function for a given table.  NBROFCOLS is the number of columns in
   1105      the table. NR_ROWS is the number of rows in the table.  TBLID is
   1106      an optional string identifying the table.  The string pointed to
   1107      by TBLID is copied by the implementation of `ui_out_table_begin',
   1108      so the application can free the string if it was `malloc'ed.
   1109 
   1110      The companion function `ui_out_table_end', described below, marks
   1111      the end of the table's output.
   1112 
   1113  -- Function: void ui_out_table_header (struct ui_out *UIOUT, int
   1114           WIDTH, enum ui_align ALIGNMENT, const char *COLHDR)
   1115      `ui_out_table_header' provides the header information for a single
   1116      table column.  You call this function several times, one each for
   1117      every column of the table, after `ui_out_table_begin', but before
   1118      `ui_out_table_body'.
   1119 
   1120      The value of WIDTH gives the column width in characters.  The
   1121      value of ALIGNMENT is one of `left', `center', and `right', and it
   1122      specifies how to align the header: left-justify, center, or
   1123      right-justify it.  COLHDR points to a string that specifies the
   1124      column header; the implementation copies that string, so column
   1125      header strings in `malloc'ed storage can be freed after the call.
   1126 
   1127  -- Function: void ui_out_table_body (struct ui_out *UIOUT)
   1128      This function delimits the table header from the table body.
   1129 
   1130  -- Function: void ui_out_table_end (struct ui_out *UIOUT)
   1131      This function signals the end of a table's output.  It should be
   1132      called after the table body has been produced by the list and
   1133      field output functions.
   1134 
   1135      There should be exactly one call to `ui_out_table_end' for each
   1136      call to `ui_out_table_begin', otherwise the `ui_out' functions
   1137      will signal an internal error.
   1138 
   1139    The output of the tuples that represent the table rows must follow
   1140 the call to `ui_out_table_body' and precede the call to
   1141 `ui_out_table_end'.  You build a tuple by calling `ui_out_tuple_begin'
   1142 and `ui_out_tuple_end', with suitable calls to functions which actually
   1143 output fields between them.
   1144 
   1145  -- Function: void ui_out_tuple_begin (struct ui_out *UIOUT, const char
   1146           *ID)
   1147      This function marks the beginning of a tuple output.  ID points to
   1148      an optional string that identifies the tuple; it is copied by the
   1149      implementation, and so strings in `malloc'ed storage can be freed
   1150      after the call.
   1151 
   1152  -- Function: void ui_out_tuple_end (struct ui_out *UIOUT)
   1153      This function signals an end of a tuple output.  There should be
   1154      exactly one call to `ui_out_tuple_end' for each call to
   1155      `ui_out_tuple_begin', otherwise an internal GDB error will be
   1156      signaled.
   1157 
   1158  -- Function: struct cleanup * make_cleanup_ui_out_tuple_begin_end
   1159           (struct ui_out *UIOUT, const char *ID)
   1160      This function first opens the tuple and then establishes a cleanup
   1161      (*note Cleanups: Coding.) to close the tuple.  It provides a
   1162      convenient and correct implementation of the non-portable(1) code
   1163      sequence:
   1164           struct cleanup *old_cleanup;
   1165           ui_out_tuple_begin (uiout, "...");
   1166           old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
   1167                                       uiout);
   1168 
   1169  -- Function: void ui_out_list_begin (struct ui_out *UIOUT, const char
   1170           *ID)
   1171      This function marks the beginning of a list output.  ID points to
   1172      an optional string that identifies the list; it is copied by the
   1173      implementation, and so strings in `malloc'ed storage can be freed
   1174      after the call.
   1175 
   1176  -- Function: void ui_out_list_end (struct ui_out *UIOUT)
   1177      This function signals an end of a list output.  There should be
   1178      exactly one call to `ui_out_list_end' for each call to
   1179      `ui_out_list_begin', otherwise an internal GDB error will be
   1180      signaled.
   1181 
   1182  -- Function: struct cleanup * make_cleanup_ui_out_list_begin_end
   1183           (struct ui_out *UIOUT, const char *ID)
   1184      Similar to `make_cleanup_ui_out_tuple_begin_end', this function
   1185      opens a list and then establishes cleanup (*note Cleanups: Coding.)
   1186      that will close the list.
   1187 
   1188 4.2.4 Item Output Functions
   1189 ---------------------------
   1190 
   1191 The functions described below produce output for the actual data items,
   1192 or fields, which contain information about the object.
   1193 
   1194    Choose the appropriate function accordingly to your particular needs.
   1195 
   1196  -- Function: void ui_out_field_fmt (struct ui_out *UIOUT, char
   1197           *FLDNAME, char *FORMAT, ...)
   1198      This is the most general output function.  It produces the
   1199      representation of the data in the variable-length argument list
   1200      according to formatting specifications in FORMAT, a `printf'-like
   1201      format string.  The optional argument FLDNAME supplies the name of
   1202      the field.  The data items themselves are supplied as additional
   1203      arguments after FORMAT.
   1204 
   1205      This generic function should be used only when it is not possible
   1206      to use one of the specialized versions (see below).
   1207 
   1208  -- Function: void ui_out_field_int (struct ui_out *UIOUT, const char
   1209           *FLDNAME, int VALUE)
   1210      This function outputs a value of an `int' variable.  It uses the
   1211      `"%d"' output conversion specification.  FLDNAME specifies the
   1212      name of the field.
   1213 
   1214  -- Function: void ui_out_field_fmt_int (struct ui_out *UIOUT, int
   1215           WIDTH, enum ui_align ALIGNMENT, const char *FLDNAME, int
   1216           VALUE)
   1217      This function outputs a value of an `int' variable.  It differs
   1218      from `ui_out_field_int' in that the caller specifies the desired
   1219      WIDTH and ALIGNMENT of the output.  FLDNAME specifies the name of
   1220      the field.
   1221 
   1222  -- Function: void ui_out_field_core_addr (struct ui_out *UIOUT, const
   1223           char *FLDNAME, struct gdbarch *GDBARCH, CORE_ADDR ADDRESS)
   1224      This function outputs an address as appropriate for GDBARCH.
   1225 
   1226  -- Function: void ui_out_field_string (struct ui_out *UIOUT, const
   1227           char *FLDNAME, const char *STRING)
   1228      This function outputs a string using the `"%s"' conversion
   1229      specification.
   1230 
   1231    Sometimes, there's a need to compose your output piece by piece using
   1232 functions that operate on a stream, such as `value_print' or
   1233 `fprintf_symbol_filtered'.  These functions accept an argument of the
   1234 type `struct ui_file *', a pointer to a `ui_file' object used to store
   1235 the data stream used for the output.  When you use one of these
   1236 functions, you need a way to pass their results stored in a `ui_file'
   1237 object to the `ui_out' functions.  To this end, you first create a
   1238 `ui_stream' object by calling `ui_out_stream_new', pass the `stream'
   1239 member of that `ui_stream' object to `value_print' and similar
   1240 functions, and finally call `ui_out_field_stream' to output the field
   1241 you constructed.  When the `ui_stream' object is no longer needed, you
   1242 should destroy it and free its memory by calling `ui_out_stream_delete'.
   1243 
   1244  -- Function: struct ui_stream * ui_out_stream_new (struct ui_out
   1245           *UIOUT)
   1246      This function creates a new `ui_stream' object which uses the same
   1247      output methods as the `ui_out' object whose pointer is passed in
   1248      UIOUT.  It returns a pointer to the newly created `ui_stream'
   1249      object.
   1250 
   1251  -- Function: void ui_out_stream_delete (struct ui_stream *STREAMBUF)
   1252      This functions destroys a `ui_stream' object specified by
   1253      STREAMBUF.
   1254 
   1255  -- Function: void ui_out_field_stream (struct ui_out *UIOUT, const
   1256           char *FIELDNAME, struct ui_stream *STREAMBUF)
   1257      This function consumes all the data accumulated in
   1258      `streambuf->stream' and outputs it like `ui_out_field_string'
   1259      does.  After a call to `ui_out_field_stream', the accumulated data
   1260      no longer exists, but the stream is still valid and may be used
   1261      for producing more fields.
   1262 
   1263    *Important:* If there is any chance that your code could bail out
   1264 before completing output generation and reaching the point where
   1265 `ui_out_stream_delete' is called, it is necessary to set up a cleanup,
   1266 to avoid leaking memory and other resources.  Here's a skeleton code to
   1267 do that:
   1268 
   1269       struct ui_stream *mybuf = ui_out_stream_new (uiout);
   1270       struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
   1271       ...
   1272       do_cleanups (old);
   1273 
   1274    If the function already has the old cleanup chain set (for other
   1275 kinds of cleanups), you just have to add your cleanup to it:
   1276 
   1277        mybuf = ui_out_stream_new (uiout);
   1278        make_cleanup (ui_out_stream_delete, mybuf);
   1279 
   1280    Note that with cleanups in place, you should not call
   1281 `ui_out_stream_delete' directly, or you would attempt to free the same
   1282 buffer twice.
   1283 
   1284 4.2.5 Utility Output Functions
   1285 ------------------------------
   1286 
   1287  -- Function: void ui_out_field_skip (struct ui_out *UIOUT, const char
   1288           *FLDNAME)
   1289      This function skips a field in a table.  Use it if you have to
   1290      leave an empty field without disrupting the table alignment.  The
   1291      argument FLDNAME specifies a name for the (missing) filed.
   1292 
   1293  -- Function: void ui_out_text (struct ui_out *UIOUT, const char
   1294           *STRING)
   1295      This function outputs the text in STRING in a way that makes it
   1296      easy to be read by humans.  For example, the console
   1297      implementation of this method filters the text through a built-in
   1298      pager, to prevent it from scrolling off the visible portion of the
   1299      screen.
   1300 
   1301      Use this function for printing relatively long chunks of text
   1302      around the actual field data: the text it produces is not aligned
   1303      according to the table's format.  Use `ui_out_field_string' to
   1304      output a string field, and use `ui_out_message', described below,
   1305      to output short messages.
   1306 
   1307  -- Function: void ui_out_spaces (struct ui_out *UIOUT, int NSPACES)
   1308      This function outputs NSPACES spaces.  It is handy to align the
   1309      text produced by `ui_out_text' with the rest of the table or list.
   1310 
   1311  -- Function: void ui_out_message (struct ui_out *UIOUT, int VERBOSITY,
   1312           const char *FORMAT, ...)
   1313      This function produces a formatted message, provided that the
   1314      current verbosity level is at least as large as given by
   1315      VERBOSITY.  The current verbosity level is specified by the user
   1316      with the `set verbositylevel' command.(2)
   1317 
   1318  -- Function: void ui_out_wrap_hint (struct ui_out *UIOUT, char *INDENT)
   1319      This function gives the console output filter (a paging filter) a
   1320      hint of where to break lines which are too long.  Ignored for all
   1321      other output consumers.  INDENT, if non-`NULL', is the string to
   1322      be printed to indent the wrapped text on the next line; it must
   1323      remain accessible until the next call to `ui_out_wrap_hint', or
   1324      until an explicit newline is produced by one of the other
   1325      functions.  If INDENT is `NULL', the wrapped text will not be
   1326      indented.
   1327 
   1328  -- Function: void ui_out_flush (struct ui_out *UIOUT)
   1329      This function flushes whatever output has been accumulated so far,
   1330      if the UI buffers output.
   1331 
   1332 4.2.6 Examples of Use of `ui_out' functions
   1333 -------------------------------------------
   1334 
   1335 This section gives some practical examples of using the `ui_out'
   1336 functions to generalize the old console-oriented code in GDB.  The
   1337 examples all come from functions defined on the `breakpoints.c' file.
   1338 
   1339    This example, from the `breakpoint_1' function, shows how to produce
   1340 a table.
   1341 
   1342    The original code was:
   1343 
   1344       if (!found_a_breakpoint++)
   1345         {
   1346           annotate_breakpoints_headers ();
   1347 
   1348           annotate_field (0);
   1349           printf_filtered ("Num ");
   1350           annotate_field (1);
   1351           printf_filtered ("Type           ");
   1352           annotate_field (2);
   1353           printf_filtered ("Disp ");
   1354           annotate_field (3);
   1355           printf_filtered ("Enb ");
   1356           if (addressprint)
   1357             {
   1358               annotate_field (4);
   1359               printf_filtered ("Address    ");
   1360             }
   1361           annotate_field (5);
   1362           printf_filtered ("What\n");
   1363 
   1364           annotate_breakpoints_table ();
   1365         }
   1366 
   1367    Here's the new version:
   1368 
   1369        nr_printable_breakpoints = ...;
   1370 
   1371        if (addressprint)
   1372          ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
   1373        else
   1374          ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
   1375 
   1376        if (nr_printable_breakpoints > 0)
   1377          annotate_breakpoints_headers ();
   1378        if (nr_printable_breakpoints > 0)
   1379          annotate_field (0);
   1380        ui_out_table_header (uiout, 3, ui_left, "number", "Num");		/* 1 */
   1381        if (nr_printable_breakpoints > 0)
   1382          annotate_field (1);
   1383        ui_out_table_header (uiout, 14, ui_left, "type", "Type");		/* 2 */
   1384        if (nr_printable_breakpoints > 0)
   1385          annotate_field (2);
   1386        ui_out_table_header (uiout, 4, ui_left, "disp", "Disp");		/* 3 */
   1387        if (nr_printable_breakpoints > 0)
   1388          annotate_field (3);
   1389        ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb");	/* 4 */
   1390        if (addressprint)
   1391          {
   1392           if (nr_printable_breakpoints > 0)
   1393             annotate_field (4);
   1394           if (print_address_bits <= 32)
   1395             ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
   1396           else
   1397             ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
   1398          }
   1399        if (nr_printable_breakpoints > 0)
   1400          annotate_field (5);
   1401        ui_out_table_header (uiout, 40, ui_noalign, "what", "What");	/* 6 */
   1402        ui_out_table_body (uiout);
   1403        if (nr_printable_breakpoints > 0)
   1404          annotate_breakpoints_table ();
   1405 
   1406    This example, from the `print_one_breakpoint' function, shows how to
   1407 produce the actual data for the table whose structure was defined in
   1408 the above example.  The original code was:
   1409 
   1410         annotate_record ();
   1411         annotate_field (0);
   1412         printf_filtered ("%-3d ", b->number);
   1413         annotate_field (1);
   1414         if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
   1415             || ((int) b->type != bptypes[(int) b->type].type))
   1416           internal_error ("bptypes table does not describe type #%d.",
   1417                           (int)b->type);
   1418         printf_filtered ("%-14s ", bptypes[(int)b->type].description);
   1419         annotate_field (2);
   1420         printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
   1421         annotate_field (3);
   1422         printf_filtered ("%-3c ", bpenables[(int)b->enable]);
   1423         ...
   1424 
   1425    This is the new version:
   1426 
   1427         annotate_record ();
   1428         ui_out_tuple_begin (uiout, "bkpt");
   1429         annotate_field (0);
   1430         ui_out_field_int (uiout, "number", b->number);
   1431         annotate_field (1);
   1432         if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
   1433             || ((int) b->type != bptypes[(int) b->type].type))
   1434           internal_error ("bptypes table does not describe type #%d.",
   1435                           (int) b->type);
   1436         ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
   1437         annotate_field (2);
   1438         ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
   1439         annotate_field (3);
   1440         ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
   1441         ...
   1442 
   1443    This example, also from `print_one_breakpoint', shows how to produce
   1444 a complicated output field using the `print_expression' functions which
   1445 requires a stream to be passed.  It also shows how to automate stream
   1446 destruction with cleanups.  The original code was:
   1447 
   1448          annotate_field (5);
   1449          print_expression (b->exp, gdb_stdout);
   1450 
   1451    The new version is:
   1452 
   1453        struct ui_stream *stb = ui_out_stream_new (uiout);
   1454        struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
   1455        ...
   1456        annotate_field (5);
   1457        print_expression (b->exp, stb->stream);
   1458        ui_out_field_stream (uiout, "what", local_stream);
   1459 
   1460    This example, also from `print_one_breakpoint', shows how to use
   1461 `ui_out_text' and `ui_out_field_string'.  The original code was:
   1462 
   1463        annotate_field (5);
   1464        if (b->dll_pathname == NULL)
   1465          printf_filtered ("<any library> ");
   1466        else
   1467          printf_filtered ("library \"%s\" ", b->dll_pathname);
   1468 
   1469    It became:
   1470 
   1471        annotate_field (5);
   1472        if (b->dll_pathname == NULL)
   1473          {
   1474            ui_out_field_string (uiout, "what", "<any library>");
   1475            ui_out_spaces (uiout, 1);
   1476          }
   1477        else
   1478          {
   1479            ui_out_text (uiout, "library \"");
   1480            ui_out_field_string (uiout, "what", b->dll_pathname);
   1481            ui_out_text (uiout, "\" ");
   1482          }
   1483 
   1484    The following example from `print_one_breakpoint' shows how to use
   1485 `ui_out_field_int' and `ui_out_spaces'.  The original code was:
   1486 
   1487        annotate_field (5);
   1488        if (b->forked_inferior_pid != 0)
   1489          printf_filtered ("process %d ", b->forked_inferior_pid);
   1490 
   1491    It became:
   1492 
   1493        annotate_field (5);
   1494        if (b->forked_inferior_pid != 0)
   1495          {
   1496            ui_out_text (uiout, "process ");
   1497            ui_out_field_int (uiout, "what", b->forked_inferior_pid);
   1498            ui_out_spaces (uiout, 1);
   1499          }
   1500 
   1501    Here's an example of using `ui_out_field_string'.  The original code
   1502 was:
   1503 
   1504        annotate_field (5);
   1505        if (b->exec_pathname != NULL)
   1506          printf_filtered ("program \"%s\" ", b->exec_pathname);
   1507 
   1508    It became:
   1509 
   1510        annotate_field (5);
   1511        if (b->exec_pathname != NULL)
   1512          {
   1513            ui_out_text (uiout, "program \"");
   1514            ui_out_field_string (uiout, "what", b->exec_pathname);
   1515            ui_out_text (uiout, "\" ");
   1516          }
   1517 
   1518    Finally, here's an example of printing an address.  The original
   1519 code:
   1520 
   1521        annotate_field (4);
   1522        printf_filtered ("%s ",
   1523              hex_string_custom ((unsigned long) b->address, 8));
   1524 
   1525    It became:
   1526 
   1527        annotate_field (4);
   1528        ui_out_field_core_addr (uiout, "Address", b->address);
   1529 
   1530 4.3 Console Printing
   1531 ====================
   1532 
   1533 4.4 TUI
   1534 =======
   1535 
   1536 ---------- Footnotes ----------
   1537 
   1538    (1) The function cast is not portable ISO C.
   1539 
   1540    (2) As of this writing (April 2001), setting verbosity level is not
   1541 yet implemented, and is always returned as zero.  So calling
   1542 `ui_out_message' with a VERBOSITY argument more than zero will cause
   1543 the message to never be printed.
   1544 
   1545 
   1546 File: gdbint.info,  Node: libgdb,  Next: Values,  Prev: User Interface,  Up: Top
   1547 
   1548 5 libgdb
   1549 ********
   1550 
   1551 5.1 libgdb 1.0
   1552 ==============
   1553 
   1554 `libgdb' 1.0 was an abortive project of years ago.  The theory was to
   1555 provide an API to GDB's functionality.
   1556 
   1557 5.2 libgdb 2.0
   1558 ==============
   1559 
   1560 `libgdb' 2.0 is an ongoing effort to update GDB so that is better able
   1561 to support graphical and other environments.
   1562 
   1563    Since `libgdb' development is on-going, its architecture is still
   1564 evolving.  The following components have so far been identified:
   1565 
   1566    * Observer - `gdb-events.h'.
   1567 
   1568    * Builder - `ui-out.h'
   1569 
   1570    * Event Loop - `event-loop.h'
   1571 
   1572    * Library - `gdb.h'
   1573 
   1574    The model that ties these components together is described below.
   1575 
   1576 5.3 The `libgdb' Model
   1577 ======================
   1578 
   1579 A client of `libgdb' interacts with the library in two ways.
   1580 
   1581    * As an observer (using `gdb-events') receiving notifications from
   1582      `libgdb' of any internal state changes (break point changes, run
   1583      state, etc).
   1584 
   1585    * As a client querying `libgdb' (using the `ui-out' builder) to
   1586      obtain various status values from GDB.
   1587 
   1588    Since `libgdb' could have multiple clients (e.g., a GUI supporting
   1589 the existing GDB CLI), those clients must co-operate when controlling
   1590 `libgdb'.  In particular, a client must ensure that `libgdb' is idle
   1591 (i.e. no other client is using `libgdb') before responding to a
   1592 `gdb-event' by making a query.
   1593 
   1594 5.4 CLI support
   1595 ===============
   1596 
   1597 At present GDB's CLI is very much entangled in with the core of
   1598 `libgdb'.  Consequently, a client wishing to include the CLI in their
   1599 interface needs to carefully co-ordinate its own and the CLI's
   1600 requirements.
   1601 
   1602    It is suggested that the client set `libgdb' up to be bi-modal
   1603 (alternate between CLI and client query modes).  The notes below sketch
   1604 out the theory:
   1605 
   1606    * The client registers itself as an observer of `libgdb'.
   1607 
   1608    * The client create and install `cli-out' builder using its own
   1609      versions of the `ui-file' `gdb_stderr', `gdb_stdtarg' and
   1610      `gdb_stdout' streams.
   1611 
   1612    * The client creates a separate custom `ui-out' builder that is only
   1613      used while making direct queries to `libgdb'.
   1614 
   1615    When the client receives input intended for the CLI, it simply
   1616 passes it along.  Since the `cli-out' builder is installed by default,
   1617 all the CLI output in response to that command is routed (pronounced
   1618 rooted) through to the client controlled `gdb_stdout' et. al. streams.
   1619 At the same time, the client is kept abreast of internal changes by
   1620 virtue of being a `libgdb' observer.
   1621 
   1622    The only restriction on the client is that it must wait until
   1623 `libgdb' becomes idle before initiating any queries (using the client's
   1624 custom builder).
   1625 
   1626 5.5 `libgdb' components
   1627 =======================
   1628 
   1629 Observer - `gdb-events.h'
   1630 -------------------------
   1631 
   1632 `gdb-events' provides the client with a very raw mechanism that can be
   1633 used to implement an observer.  At present it only allows for one
   1634 observer and that observer must, internally, handle the need to delay
   1635 the processing of any event notifications until after `libgdb' has
   1636 finished the current command.
   1637 
   1638 Builder - `ui-out.h'
   1639 --------------------
   1640 
   1641 `ui-out' provides the infrastructure necessary for a client to create a
   1642 builder.  That builder is then passed down to `libgdb' when doing any
   1643 queries.
   1644 
   1645 Event Loop - `event-loop.h'
   1646 ---------------------------
   1647 
   1648 `event-loop', currently non-re-entrant, provides a simple event loop.
   1649 A client would need to either plug its self into this loop or,
   1650 implement a new event-loop that GDB would use.
   1651 
   1652    The event-loop will eventually be made re-entrant.  This is so that
   1653 GDB can better handle the problem of some commands blocking instead of
   1654 returning.
   1655 
   1656 Library - `gdb.h'
   1657 -----------------
   1658 
   1659 `libgdb' is the most obvious component of this system.  It provides the
   1660 query interface.  Each function is parameterized by a `ui-out' builder.
   1661 The result of the query is constructed using that builder before the
   1662 query function returns.
   1663 
   1664 
   1665 File: gdbint.info,  Node: Values,  Next: Stack Frames,  Prev: libgdb,  Up: Top
   1666 
   1667 6 Values
   1668 ********
   1669 
   1670 6.1 Values
   1671 ==========
   1672 
   1673 GDB uses `struct value', or "values", as an internal abstraction for
   1674 the representation of a variety of inferior objects and GDB convenience
   1675 objects.
   1676 
   1677    Values have an associated `struct type', that describes a virtual
   1678 view of the raw data or object stored in or accessed through the value.
   1679 
   1680    A value is in addition discriminated by its lvalue-ness, given its
   1681 `enum lval_type' enumeration type:
   1682 
   1683 ``not_lval''
   1684      This value is not an lval.  It can't be assigned to.
   1685 
   1686 ``lval_memory''
   1687      This value represents an object in memory.
   1688 
   1689 ``lval_register''
   1690      This value represents an object that lives in a register.
   1691 
   1692 ``lval_internalvar''
   1693      Represents the value of an internal variable.
   1694 
   1695 ``lval_internalvar_component''
   1696      Represents part of a GDB internal variable.  E.g., a structure
   1697      field.
   1698 
   1699 ``lval_computed''
   1700      These are "computed" values.  They allow creating specialized value
   1701      objects for specific purposes, all abstracted away from the core
   1702      value support code.  The creator of such a value writes specialized
   1703      functions to handle the reading and writing to/from the value's
   1704      backend data, and optionally, a "copy operator" and a "destructor".
   1705 
   1706      Pointers to these functions are stored in a `struct lval_funcs'
   1707      instance (declared in `value.h'), and passed to the
   1708      `allocate_computed_value' function, as in the example below.
   1709 
   1710           static void
   1711           nil_value_read (struct value *v)
   1712           {
   1713             /* This callback reads data from some backend, and stores it in V.
   1714                In this case, we always read null data.  You'll want to fill in
   1715                something more interesting.  */
   1716 
   1717             memset (value_contents_all_raw (v),
   1718                     value_offset (v),
   1719                     TYPE_LENGTH (value_type (v)));
   1720           }
   1721 
   1722           static void
   1723           nil_value_write (struct value *v, struct value *fromval)
   1724           {
   1725             /* Takes the data from FROMVAL and stores it in the backend of V.  */
   1726 
   1727             to_oblivion (value_contents_all_raw (fromval),
   1728                          value_offset (v),
   1729                          TYPE_LENGTH (value_type (fromval)));
   1730           }
   1731 
   1732           static struct lval_funcs nil_value_funcs =
   1733             {
   1734               nil_value_read,
   1735               nil_value_write
   1736             };
   1737 
   1738           struct value *
   1739           make_nil_value (void)
   1740           {
   1741              struct type *type;
   1742              struct value *v;
   1743 
   1744              type = make_nils_type ();
   1745              v = allocate_computed_value (type, &nil_value_funcs, NULL);
   1746 
   1747              return v;
   1748           }
   1749 
   1750      See the implementation of the `$_siginfo' convenience variable in
   1751      `infrun.c' as a real example use of lval_computed.
   1752 
   1753 
   1754 
   1755 File: gdbint.info,  Node: Stack Frames,  Next: Symbol Handling,  Prev: Values,  Up: Top
   1756 
   1757 7 Stack Frames
   1758 **************
   1759 
   1760 A frame is a construct that GDB uses to keep track of calling and
   1761 called functions.
   1762 
   1763    GDB's frame model, a fresh design, was implemented with the need to
   1764 support DWARF's Call Frame Information in mind.  In fact, the term
   1765 "unwind" is taken directly from that specification.  Developers wishing
   1766 to learn more about unwinders, are encouraged to read the DWARF
   1767 specification, available from `http://www.dwarfstd.org'.
   1768 
   1769    GDB's model is that you find a frame's registers by "unwinding" them
   1770 from the next younger frame.  That is, `get_frame_register' which
   1771 returns the value of a register in frame #1 (the next-to-youngest
   1772 frame), is implemented by calling frame #0's `frame_register_unwind'
   1773 (the youngest frame).  But then the obvious question is: how do you
   1774 access the registers of the youngest frame itself?
   1775 
   1776    To answer this question, GDB has the "sentinel" frame, the "-1st"
   1777 frame.  Unwinding registers from the sentinel frame gives you the
   1778 current values of the youngest real frame's registers.  If F is a
   1779 sentinel frame, then `get_frame_type (F) == SENTINEL_FRAME'.
   1780 
   1781 7.1 Selecting an Unwinder
   1782 =========================
   1783 
   1784 The architecture registers a list of frame unwinders (`struct
   1785 frame_unwind'), using the functions `frame_unwind_prepend_unwinder' and
   1786 `frame_unwind_append_unwinder'.  Each unwinder includes a sniffer.
   1787 Whenever GDB needs to unwind a frame (to fetch the previous frame's
   1788 registers or the current frame's ID), it calls registered sniffers in
   1789 order to find one which recognizes the frame.  The first time a sniffer
   1790 returns non-zero, the corresponding unwinder is assigned to the frame.
   1791 
   1792 7.2 Unwinding the Frame ID
   1793 ==========================
   1794 
   1795 Every frame has an associated ID, of type `struct frame_id'.  The ID
   1796 includes the stack base and function start address for the frame.  The
   1797 ID persists through the entire life of the frame, including while other
   1798 called frames are running; it is used to locate an appropriate `struct
   1799 frame_info' from the cache.
   1800 
   1801    Every time the inferior stops, and at various other times, the frame
   1802 cache is flushed.  Because of this, parts of GDB which need to keep
   1803 track of individual frames cannot use pointers to `struct frame_info'.
   1804 A frame ID provides a stable reference to a frame, even when the
   1805 unwinder must be run again to generate a new `struct frame_info' for
   1806 the same frame.
   1807 
   1808    The frame's unwinder's `this_id' method is called to find the ID.
   1809 Note that this is different from register unwinding, where the next
   1810 frame's `prev_register' is called to unwind this frame's registers.
   1811 
   1812    Both stack base and function address are required to identify the
   1813 frame, because a recursive function has the same function address for
   1814 two consecutive frames and a leaf function may have the same stack
   1815 address as its caller.  On some platforms, a third address is part of
   1816 the ID to further disambiguate frames--for instance, on IA-64 the
   1817 separate register stack address is included in the ID.
   1818 
   1819    An invalid frame ID (`outer_frame_id') returned from the `this_id'
   1820 method means to stop unwinding after this frame.
   1821 
   1822    `null_frame_id' is another invalid frame ID which should be used
   1823 when there is no frame.  For instance, certain breakpoints are attached
   1824 to a specific frame, and that frame is identified through its frame ID
   1825 (we use this to implement the "finish" command).  Using `null_frame_id'
   1826 as the frame ID for a given breakpoint means that the breakpoint is not
   1827 specific to any frame.  The `this_id' method should never return
   1828 `null_frame_id'.
   1829 
   1830 7.3 Unwinding Registers
   1831 =======================
   1832 
   1833 Each unwinder includes a `prev_register' method.  This method takes a
   1834 frame, an associated cache pointer, and a register number.  It returns
   1835 a `struct value *' describing the requested register, as saved by this
   1836 frame.  This is the value of the register that is current in this
   1837 frame's caller.
   1838 
   1839    The returned value must have the same type as the register.  It may
   1840 have any lvalue type.  In most circumstances one of these routines will
   1841 generate the appropriate value:
   1842 
   1843 `frame_unwind_got_optimized'
   1844      This register was not saved.
   1845 
   1846 `frame_unwind_got_register'
   1847      This register was copied into another register in this frame.  This
   1848      is also used for unchanged registers; they are "copied" into the
   1849      same register.
   1850 
   1851 `frame_unwind_got_memory'
   1852      This register was saved in memory.
   1853 
   1854 `frame_unwind_got_constant'
   1855      This register was not saved, but the unwinder can compute the
   1856      previous value some other way.
   1857 
   1858 `frame_unwind_got_address'
   1859      Same as `frame_unwind_got_constant', except that the value is a
   1860      target address.  This is frequently used for the stack pointer,
   1861      which is not explicitly saved but has a known offset from this
   1862      frame's stack pointer.  For architectures with a flat unified
   1863      address space, this is generally the same as
   1864      `frame_unwind_got_constant'.
   1865 
   1866 
   1867 File: gdbint.info,  Node: Symbol Handling,  Next: Language Support,  Prev: Stack Frames,  Up: Top
   1868 
   1869 8 Symbol Handling
   1870 *****************
   1871 
   1872 Symbols are a key part of GDB's operation.  Symbols include variables,
   1873 functions, and types.
   1874 
   1875    Symbol information for a large program can be truly massive, and
   1876 reading of symbol information is one of the major performance
   1877 bottlenecks in GDB; it can take many minutes to process it all.
   1878 Studies have shown that nearly all the time spent is computational,
   1879 rather than file reading.
   1880 
   1881    One of the ways for GDB to provide a good user experience is to
   1882 start up quickly, taking no more than a few seconds.  It is simply not
   1883 possible to process all of a program's debugging info in that time, and
   1884 so we attempt to handle symbols incrementally.  For instance, we create
   1885 "partial symbol tables" consisting of only selected symbols, and only
   1886 expand them to full symbol tables when necessary.
   1887 
   1888 8.1 Symbol Reading
   1889 ==================
   1890 
   1891 GDB reads symbols from "symbol files".  The usual symbol file is the
   1892 file containing the program which GDB is debugging.  GDB can be
   1893 directed to use a different file for symbols (with the `symbol-file'
   1894 command), and it can also read more symbols via the `add-file' and
   1895 `load' commands. In addition, it may bring in more symbols while
   1896 loading shared libraries.
   1897 
   1898    Symbol files are initially opened by code in `symfile.c' using the
   1899 BFD library (*note Support Libraries::).  BFD identifies the type of
   1900 the file by examining its header.  `find_sym_fns' then uses this
   1901 identification to locate a set of symbol-reading functions.
   1902 
   1903    Symbol-reading modules identify themselves to GDB by calling
   1904 `add_symtab_fns' during their module initialization.  The argument to
   1905 `add_symtab_fns' is a `struct sym_fns' which contains the name (or name
   1906 prefix) of the symbol format, the length of the prefix, and pointers to
   1907 four functions.  These functions are called at various times to process
   1908 symbol files whose identification matches the specified prefix.
   1909 
   1910    The functions supplied by each module are:
   1911 
   1912 `XYZ_symfile_init(struct sym_fns *sf)'
   1913      Called from `symbol_file_add' when we are about to read a new
   1914      symbol file.  This function should clean up any internal state
   1915      (possibly resulting from half-read previous files, for example)
   1916      and prepare to read a new symbol file.  Note that the symbol file
   1917      which we are reading might be a new "main" symbol file, or might
   1918      be a secondary symbol file whose symbols are being added to the
   1919      existing symbol table.
   1920 
   1921      The argument to `XYZ_symfile_init' is a newly allocated `struct
   1922      sym_fns' whose `bfd' field contains the BFD for the new symbol
   1923      file being read.  Its `private' field has been zeroed, and can be
   1924      modified as desired.  Typically, a struct of private information
   1925      will be `malloc''d, and a pointer to it will be placed in the
   1926      `private' field.
   1927 
   1928      There is no result from `XYZ_symfile_init', but it can call
   1929      `error' if it detects an unavoidable problem.
   1930 
   1931 `XYZ_new_init()'
   1932      Called from `symbol_file_add' when discarding existing symbols.
   1933      This function needs only handle the symbol-reading module's
   1934      internal state; the symbol table data structures visible to the
   1935      rest of GDB will be discarded by `symbol_file_add'.  It has no
   1936      arguments and no result.  It may be called after
   1937      `XYZ_symfile_init', if a new symbol table is being read, or may be
   1938      called alone if all symbols are simply being discarded.
   1939 
   1940 `XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)'
   1941      Called from `symbol_file_add' to actually read the symbols from a
   1942      symbol-file into a set of psymtabs or symtabs.
   1943 
   1944      `sf' points to the `struct sym_fns' originally passed to
   1945      `XYZ_sym_init' for possible initialization.  `addr' is the offset
   1946      between the file's specified start address and its true address in
   1947      memory.  `mainline' is 1 if this is the main symbol table being
   1948      read, and 0 if a secondary symbol file (e.g., shared library or
   1949      dynamically loaded file) is being read.
   1950 
   1951    In addition, if a symbol-reading module creates psymtabs when
   1952 XYZ_symfile_read is called, these psymtabs will contain a pointer to a
   1953 function `XYZ_psymtab_to_symtab', which can be called from any point in
   1954 the GDB symbol-handling code.
   1955 
   1956 `XYZ_psymtab_to_symtab (struct partial_symtab *pst)'
   1957      Called from `psymtab_to_symtab' (or the `PSYMTAB_TO_SYMTAB' macro)
   1958      if the psymtab has not already been read in and had its
   1959      `pst->symtab' pointer set.  The argument is the psymtab to be
   1960      fleshed-out into a symtab.  Upon return, `pst->readin' should have
   1961      been set to 1, and `pst->symtab' should contain a pointer to the
   1962      new corresponding symtab, or zero if there were no symbols in that
   1963      part of the symbol file.
   1964 
   1965 8.2 Partial Symbol Tables
   1966 =========================
   1967 
   1968 GDB has three types of symbol tables:
   1969 
   1970    * Full symbol tables ("symtabs").  These contain the main
   1971      information about symbols and addresses.
   1972 
   1973    * Partial symbol tables ("psymtabs").  These contain enough
   1974      information to know when to read the corresponding part of the full
   1975      symbol table.
   1976 
   1977    * Minimal symbol tables ("msymtabs").  These contain information
   1978      gleaned from non-debugging symbols.
   1979 
   1980    This section describes partial symbol tables.
   1981 
   1982    A psymtab is constructed by doing a very quick pass over an
   1983 executable file's debugging information.  Small amounts of information
   1984 are extracted--enough to identify which parts of the symbol table will
   1985 need to be re-read and fully digested later, when the user needs the
   1986 information.  The speed of this pass causes GDB to start up very
   1987 quickly.  Later, as the detailed rereading occurs, it occurs in small
   1988 pieces, at various times, and the delay therefrom is mostly invisible to
   1989 the user.
   1990 
   1991    The symbols that show up in a file's psymtab should be, roughly,
   1992 those visible to the debugger's user when the program is not running
   1993 code from that file.  These include external symbols and types, static
   1994 symbols and types, and `enum' values declared at file scope.
   1995 
   1996    The psymtab also contains the range of instruction addresses that the
   1997 full symbol table would represent.
   1998 
   1999    The idea is that there are only two ways for the user (or much of the
   2000 code in the debugger) to reference a symbol:
   2001 
   2002    * By its address (e.g., execution stops at some address which is
   2003      inside a function in this file).  The address will be noticed to
   2004      be in the range of this psymtab, and the full symtab will be read
   2005      in.  `find_pc_function', `find_pc_line', and other `find_pc_...'
   2006      functions handle this.
   2007 
   2008    * By its name (e.g., the user asks to print a variable, or set a
   2009      breakpoint on a function).  Global names and file-scope names will
   2010      be found in the psymtab, which will cause the symtab to be pulled
   2011      in.  Local names will have to be qualified by a global name, or a
   2012      file-scope name, in which case we will have already read in the
   2013      symtab as we evaluated the qualifier.  Or, a local symbol can be
   2014      referenced when we are "in" a local scope, in which case the first
   2015      case applies.  `lookup_symbol' does most of the work here.
   2016 
   2017    The only reason that psymtabs exist is to cause a symtab to be read
   2018 in at the right moment.  Any symbol that can be elided from a psymtab,
   2019 while still causing that to happen, should not appear in it.  Since
   2020 psymtabs don't have the idea of scope, you can't put local symbols in
   2021 them anyway.  Psymtabs don't have the idea of the type of a symbol,
   2022 either, so types need not appear, unless they will be referenced by
   2023 name.
   2024 
   2025    It is a bug for GDB to behave one way when only a psymtab has been
   2026 read, and another way if the corresponding symtab has been read in.
   2027 Such bugs are typically caused by a psymtab that does not contain all
   2028 the visible symbols, or which has the wrong instruction address ranges.
   2029 
   2030    The psymtab for a particular section of a symbol file (objfile)
   2031 could be thrown away after the symtab has been read in.  The symtab
   2032 should always be searched before the psymtab, so the psymtab will never
   2033 be used (in a bug-free environment).  Currently, psymtabs are allocated
   2034 on an obstack, and all the psymbols themselves are allocated in a pair
   2035 of large arrays on an obstack, so there is little to be gained by
   2036 trying to free them unless you want to do a lot more work.
   2037 
   2038 8.3 Types
   2039 =========
   2040 
   2041 Fundamental Types (e.g., `FT_VOID', `FT_BOOLEAN').
   2042 --------------------------------------------------
   2043 
   2044 These are the fundamental types that GDB uses internally.  Fundamental
   2045 types from the various debugging formats (stabs, ELF, etc) are mapped
   2046 into one of these.  They are basically a union of all fundamental types
   2047 that GDB knows about for all the languages that GDB knows about.
   2048 
   2049 Type Codes (e.g., `TYPE_CODE_PTR', `TYPE_CODE_ARRAY').
   2050 ------------------------------------------------------
   2051 
   2052 Each time GDB builds an internal type, it marks it with one of these
   2053 types.  The type may be a fundamental type, such as `TYPE_CODE_INT', or
   2054 a derived type, such as `TYPE_CODE_PTR' which is a pointer to another
   2055 type.  Typically, several `FT_*' types map to one `TYPE_CODE_*' type,
   2056 and are distinguished by other members of the type struct, such as
   2057 whether the type is signed or unsigned, and how many bits it uses.
   2058 
   2059 Builtin Types (e.g., `builtin_type_void', `builtin_type_char').
   2060 ---------------------------------------------------------------
   2061 
   2062 These are instances of type structs that roughly correspond to
   2063 fundamental types and are created as global types for GDB to use for
   2064 various ugly historical reasons.  We eventually want to eliminate
   2065 these.  Note for example that `builtin_type_int' initialized in
   2066 `gdbtypes.c' is basically the same as a `TYPE_CODE_INT' type that is
   2067 initialized in `c-lang.c' for an `FT_INTEGER' fundamental type.  The
   2068 difference is that the `builtin_type' is not associated with any
   2069 particular objfile, and only one instance exists, while `c-lang.c'
   2070 builds as many `TYPE_CODE_INT' types as needed, with each one
   2071 associated with some particular objfile.
   2072 
   2073 8.4 Object File Formats
   2074 =======================
   2075 
   2076 8.4.1 a.out
   2077 -----------
   2078 
   2079 The `a.out' format is the original file format for Unix.  It consists
   2080 of three sections: `text', `data', and `bss', which are for program
   2081 code, initialized data, and uninitialized data, respectively.
   2082 
   2083    The `a.out' format is so simple that it doesn't have any reserved
   2084 place for debugging information.  (Hey, the original Unix hackers used
   2085 `adb', which is a machine-language debugger!)  The only debugging
   2086 format for `a.out' is stabs, which is encoded as a set of normal
   2087 symbols with distinctive attributes.
   2088 
   2089    The basic `a.out' reader is in `dbxread.c'.
   2090 
   2091 8.4.2 COFF
   2092 ----------
   2093 
   2094 The COFF format was introduced with System V Release 3 (SVR3) Unix.
   2095 COFF files may have multiple sections, each prefixed by a header.  The
   2096 number of sections is limited.
   2097 
   2098    The COFF specification includes support for debugging.  Although this
   2099 was a step forward, the debugging information was woefully limited.
   2100 For instance, it was not possible to represent code that came from an
   2101 included file.  GNU's COFF-using configs often use stabs-type info,
   2102 encapsulated in special sections.
   2103 
   2104    The COFF reader is in `coffread.c'.
   2105 
   2106 8.4.3 ECOFF
   2107 -----------
   2108 
   2109 ECOFF is an extended COFF originally introduced for Mips and Alpha
   2110 workstations.
   2111 
   2112    The basic ECOFF reader is in `mipsread.c'.
   2113 
   2114 8.4.4 XCOFF
   2115 -----------
   2116 
   2117 The IBM RS/6000 running AIX uses an object file format called XCOFF.
   2118 The COFF sections, symbols, and line numbers are used, but debugging
   2119 symbols are `dbx'-style stabs whose strings are located in the `.debug'
   2120 section (rather than the string table).  For more information, see
   2121 *note Top: (stabs)Top.
   2122 
   2123    The shared library scheme has a clean interface for figuring out what
   2124 shared libraries are in use, but the catch is that everything which
   2125 refers to addresses (symbol tables and breakpoints at least) needs to be
   2126 relocated for both shared libraries and the main executable.  At least
   2127 using the standard mechanism this can only be done once the program has
   2128 been run (or the core file has been read).
   2129 
   2130 8.4.5 PE
   2131 --------
   2132 
   2133 Windows 95 and NT use the PE ("Portable Executable") format for their
   2134 executables.  PE is basically COFF with additional headers.
   2135 
   2136    While BFD includes special PE support, GDB needs only the basic COFF
   2137 reader.
   2138 
   2139 8.4.6 ELF
   2140 ---------
   2141 
   2142 The ELF format came with System V Release 4 (SVR4) Unix.  ELF is
   2143 similar to COFF in being organized into a number of sections, but it
   2144 removes many of COFF's limitations.  Debugging info may be either stabs
   2145 encapsulated in ELF sections, or more commonly these days, DWARF.
   2146 
   2147    The basic ELF reader is in `elfread.c'.
   2148 
   2149 8.4.7 SOM
   2150 ---------
   2151 
   2152 SOM is HP's object file and debug format (not to be confused with IBM's
   2153 SOM, which is a cross-language ABI).
   2154 
   2155    The SOM reader is in `somread.c'.
   2156 
   2157 8.5 Debugging File Formats
   2158 ==========================
   2159 
   2160 This section describes characteristics of debugging information that
   2161 are independent of the object file format.
   2162 
   2163 8.5.1 stabs
   2164 -----------
   2165 
   2166 `stabs' started out as special symbols within the `a.out' format.
   2167 Since then, it has been encapsulated into other file formats, such as
   2168 COFF and ELF.
   2169 
   2170    While `dbxread.c' does some of the basic stab processing, including
   2171 for encapsulated versions, `stabsread.c' does the real work.
   2172 
   2173 8.5.2 COFF
   2174 ----------
   2175 
   2176 The basic COFF definition includes debugging information.  The level of
   2177 support is minimal and non-extensible, and is not often used.
   2178 
   2179 8.5.3 Mips debug (Third Eye)
   2180 ----------------------------
   2181 
   2182 ECOFF includes a definition of a special debug format.
   2183 
   2184    The file `mdebugread.c' implements reading for this format.
   2185 
   2186 8.5.4 DWARF 2
   2187 -------------
   2188 
   2189 DWARF 2 is an improved but incompatible version of DWARF 1.
   2190 
   2191    The DWARF 2 reader is in `dwarf2read.c'.
   2192 
   2193 8.5.5 Compressed DWARF 2
   2194 ------------------------
   2195 
   2196 Compressed DWARF 2 is not technically a separate debugging format, but
   2197 merely DWARF 2 debug information that has been compressed.  In this
   2198 format, every object-file section holding DWARF 2 debugging information
   2199 is compressed and prepended with a header.  (The section is also
   2200 typically renamed, so a section called `.debug_info' in a DWARF 2
   2201 binary would be called `.zdebug_info' in a compressed DWARF 2 binary.)
   2202 The header is 12 bytes long:
   2203 
   2204    * 4 bytes: the literal string "ZLIB"
   2205 
   2206    * 8 bytes: the uncompressed size of the section, in big-endian byte
   2207      order.
   2208 
   2209    The same reader is used for both compressed an normal DWARF 2 info.
   2210 Section decompression is done in `zlib_decompress_section' in
   2211 `dwarf2read.c'.
   2212 
   2213 8.5.6 DWARF 3
   2214 -------------
   2215 
   2216 DWARF 3 is an improved version of DWARF 2.
   2217 
   2218 8.5.7 SOM
   2219 ---------
   2220 
   2221 Like COFF, the SOM definition includes debugging information.
   2222 
   2223 8.6 Adding a New Symbol Reader to GDB
   2224 =====================================
   2225 
   2226 If you are using an existing object file format (`a.out', COFF, ELF,
   2227 etc), there is probably little to be done.
   2228 
   2229    If you need to add a new object file format, you must first add it to
   2230 BFD.  This is beyond the scope of this document.
   2231 
   2232    You must then arrange for the BFD code to provide access to the
   2233 debugging symbols.  Generally GDB will have to call swapping routines
   2234 from BFD and a few other BFD internal routines to locate the debugging
   2235 information.  As much as possible, GDB should not depend on the BFD
   2236 internal data structures.
   2237 
   2238    For some targets (e.g., COFF), there is a special transfer vector
   2239 used to call swapping routines, since the external data structures on
   2240 various platforms have different sizes and layouts.  Specialized
   2241 routines that will only ever be implemented by one object file format
   2242 may be called directly.  This interface should be described in a file
   2243 `bfd/libXYZ.h', which is included by GDB.
   2244 
   2245 8.7 Memory Management for Symbol Files
   2246 ======================================
   2247 
   2248 Most memory associated with a loaded symbol file is stored on its
   2249 `objfile_obstack'.  This includes symbols, types, namespace data, and
   2250 other information produced by the symbol readers.
   2251 
   2252    Because this data lives on the objfile's obstack, it is automatically
   2253 released when the objfile is unloaded or reloaded.  Therefore one
   2254 objfile must not reference symbol or type data from another objfile;
   2255 they could be unloaded at different times.
   2256 
   2257    User convenience variables, et cetera, have associated types.
   2258 Normally these types live in the associated objfile.  However, when the
   2259 objfile is unloaded, those types are deep copied to global memory, so
   2260 that the values of the user variables and history items are not lost.
   2261 
   2262 
   2263 File: gdbint.info,  Node: Language Support,  Next: Host Definition,  Prev: Symbol Handling,  Up: Top
   2264 
   2265 9 Language Support
   2266 ******************
   2267 
   2268 GDB's language support is mainly driven by the symbol reader, although
   2269 it is possible for the user to set the source language manually.
   2270 
   2271    GDB chooses the source language by looking at the extension of the
   2272 file recorded in the debug info; `.c' means C, `.f' means Fortran, etc.
   2273 It may also use a special-purpose language identifier if the debug
   2274 format supports it, like with DWARF.
   2275 
   2276 9.1 Adding a Source Language to GDB
   2277 ===================================
   2278 
   2279 To add other languages to GDB's expression parser, follow the following
   2280 steps:
   2281 
   2282 _Create the expression parser._
   2283      This should reside in a file `LANG-exp.y'.  Routines for building
   2284      parsed expressions into a `union exp_element' list are in
   2285      `parse.c'.
   2286 
   2287      Since we can't depend upon everyone having Bison, and YACC produces
   2288      parsers that define a bunch of global names, the following lines
   2289      *must* be included at the top of the YACC parser, to prevent the
   2290      various parsers from defining the same global names:
   2291 
   2292           #define yyparse         LANG_parse
   2293           #define yylex           LANG_lex
   2294           #define yyerror         LANG_error
   2295           #define yylval          LANG_lval
   2296           #define yychar          LANG_char
   2297           #define yydebug         LANG_debug
   2298           #define yypact          LANG_pact
   2299           #define yyr1            LANG_r1
   2300           #define yyr2            LANG_r2
   2301           #define yydef           LANG_def
   2302           #define yychk           LANG_chk
   2303           #define yypgo           LANG_pgo
   2304           #define yyact           LANG_act
   2305           #define yyexca          LANG_exca
   2306           #define yyerrflag       LANG_errflag
   2307           #define yynerrs         LANG_nerrs
   2308 
   2309      At the bottom of your parser, define a `struct language_defn' and
   2310      initialize it with the right values for your language.  Define an
   2311      `initialize_LANG' routine and have it call
   2312      `add_language(LANG_language_defn)' to tell the rest of GDB that
   2313      your language exists.  You'll need some other supporting variables
   2314      and functions, which will be used via pointers from your
   2315      `LANG_language_defn'.  See the declaration of `struct
   2316      language_defn' in `language.h', and the other `*-exp.y' files, for
   2317      more information.
   2318 
   2319 _Add any evaluation routines, if necessary_
   2320      If you need new opcodes (that represent the operations of the
   2321      language), add them to the enumerated type in `expression.h'.  Add
   2322      support code for these operations in the `evaluate_subexp' function
   2323      defined in the file `eval.c'.  Add cases for new opcodes in two
   2324      functions from `parse.c': `prefixify_subexp' and
   2325      `length_of_subexp'.  These compute the number of `exp_element's
   2326      that a given operation takes up.
   2327 
   2328 _Update some existing code_
   2329      Add an enumerated identifier for your language to the enumerated
   2330      type `enum language' in `defs.h'.
   2331 
   2332      Update the routines in `language.c' so your language is included.
   2333      These routines include type predicates and such, which (in some
   2334      cases) are language dependent.  If your language does not appear
   2335      in the switch statement, an error is reported.
   2336 
   2337      Also included in `language.c' is the code that updates the variable
   2338      `current_language', and the routines that translate the
   2339      `language_LANG' enumerated identifier into a printable string.
   2340 
   2341      Update the function `_initialize_language' to include your
   2342      language.  This function picks the default language upon startup,
   2343      so is dependent upon which languages that GDB is built for.
   2344 
   2345      Update `allocate_symtab' in `symfile.c' and/or symbol-reading code
   2346      so that the language of each symtab (source file) is set properly.
   2347      This is used to determine the language to use at each stack frame
   2348      level.  Currently, the language is set based upon the extension of
   2349      the source file.  If the language can be better inferred from the
   2350      symbol information, please set the language of the symtab in the
   2351      symbol-reading code.
   2352 
   2353      Add helper code to `print_subexp' (in `expprint.c') to handle any
   2354      new expression opcodes you have added to `expression.h'.  Also,
   2355      add the printed representations of your operators to
   2356      `op_print_tab'.
   2357 
   2358 _Add a place of call_
   2359      Add a call to `LANG_parse()' and `LANG_error' in `parse_exp_1'
   2360      (defined in `parse.c').
   2361 
   2362 _Edit `Makefile.in'_
   2363      Add dependencies in `Makefile.in'.  Make sure you update the macro
   2364      variables such as `HFILES' and `OBJS', otherwise your code may not
   2365      get linked in, or, worse yet, it may not get `tar'red into the
   2366      distribution!
   2367 
   2368 
   2369 File: gdbint.info,  Node: Host Definition,  Next: Target Architecture Definition,  Prev: Language Support,  Up: Top
   2370 
   2371 10 Host Definition
   2372 ******************
   2373 
   2374 With the advent of Autoconf, it's rarely necessary to have host
   2375 definition machinery anymore.  The following information is provided,
   2376 mainly, as an historical reference.
   2377 
   2378 10.1 Adding a New Host
   2379 ======================
   2380 
   2381 GDB's host configuration support normally happens via Autoconf.  New
   2382 host-specific definitions should not be needed.  Older hosts GDB still
   2383 use the host-specific definitions and files listed below, but these
   2384 mostly exist for historical reasons, and will eventually disappear.
   2385 
   2386 `gdb/config/ARCH/XYZ.mh'
   2387      This file is a Makefile fragment that once contained both host and
   2388      native configuration information (*note Native Debugging::) for the
   2389      machine XYZ.  The host configuration information is now handled by
   2390      Autoconf.
   2391 
   2392      Host configuration information included definitions for `CC',
   2393      `SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS',
   2394      `XM_CDEPS', etc.; see `Makefile.in'.
   2395 
   2396      New host-only configurations do not need this file.
   2397 
   2398 
   2399    (Files named `gdb/config/ARCH/xm-XYZ.h' were once used to define
   2400 host-specific macros, but were no longer needed and have all been
   2401 removed.)
   2402 
   2403 Generic Host Support Files
   2404 --------------------------
   2405 
   2406 There are some "generic" versions of routines that can be used by
   2407 various systems.
   2408 
   2409 `ser-unix.c'
   2410      This contains serial line support for Unix systems.  It is
   2411      included by default on all Unix-like hosts.
   2412 
   2413 `ser-pipe.c'
   2414      This contains serial pipe support for Unix systems.  It is
   2415      included by default on all Unix-like hosts.
   2416 
   2417 `ser-mingw.c'
   2418      This contains serial line support for 32-bit programs running under
   2419      Windows using MinGW.
   2420 
   2421 `ser-go32.c'
   2422      This contains serial line support for 32-bit programs running
   2423      under DOS, using the DJGPP (a.k.a. GO32) execution environment.
   2424 
   2425 `ser-tcp.c'
   2426      This contains generic TCP support using sockets.  It is included by
   2427      default on all Unix-like hosts and with MinGW.
   2428 
   2429 10.2 Host Conditionals
   2430 ======================
   2431 
   2432 When GDB is configured and compiled, various macros are defined or left
   2433 undefined, to control compilation based on the attributes of the host
   2434 system.  While formerly they could be set in host-specific header
   2435 files, at present they can be changed only by setting `CFLAGS' when
   2436 building, or by editing the source code.
   2437 
   2438    These macros and their meanings (or if the meaning is not documented
   2439 here, then one of the source files where they are used is indicated)
   2440 are:
   2441 
   2442 `GDBINIT_FILENAME'
   2443      The default name of GDB's initialization file (normally
   2444      `.gdbinit').
   2445 
   2446 `SIGWINCH_HANDLER'
   2447      If your host defines `SIGWINCH', you can define this to be the name
   2448      of a function to be called if `SIGWINCH' is received.
   2449 
   2450 `SIGWINCH_HANDLER_BODY'
   2451      Define this to expand into code that will define the function
   2452      named by the expansion of `SIGWINCH_HANDLER'.
   2453 
   2454 `CRLF_SOURCE_FILES'
   2455      Define this if host files use `\r\n' rather than `\n' as a line
   2456      terminator.  This will cause source file listings to omit `\r'
   2457      characters when printing and it will allow `\r\n' line endings of
   2458      files which are "sourced" by gdb.  It must be possible to open
   2459      files in binary mode using `O_BINARY' or, for fopen, `"rb"'.
   2460 
   2461 `DEFAULT_PROMPT'
   2462      The default value of the prompt string (normally `"(gdb) "').
   2463 
   2464 `DEV_TTY'
   2465      The name of the generic TTY device, defaults to `"/dev/tty"'.
   2466 
   2467 `ISATTY'
   2468      Substitute for isatty, if not available.
   2469 
   2470 `FOPEN_RB'
   2471      Define this if binary files are opened the same way as text files.
   2472 
   2473 `CC_HAS_LONG_LONG'
   2474      Define this if the host C compiler supports `long long'.  This is
   2475      set by the `configure' script.
   2476 
   2477 `PRINTF_HAS_LONG_LONG'
   2478      Define this if the host can handle printing of long long integers
   2479      via the printf format conversion specifier `ll'.  This is set by
   2480      the `configure' script.
   2481 
   2482 `LSEEK_NOT_LINEAR'
   2483      Define this if `lseek (n)' does not necessarily move to byte number
   2484      `n' in the file.  This is only used when reading source files.  It
   2485      is normally faster to define `CRLF_SOURCE_FILES' when possible.
   2486 
   2487 `NORETURN'
   2488      If defined, this should be one or more tokens, such as `volatile',
   2489      that can be used in both the declaration and definition of
   2490      functions to indicate that they never return.  The default is
   2491      already set correctly if compiling with GCC.  This will almost
   2492      never need to be defined.
   2493 
   2494 `ATTR_NORETURN'
   2495      If defined, this should be one or more tokens, such as
   2496      `__attribute__ ((noreturn))', that can be used in the declarations
   2497      of functions to indicate that they never return.  The default is
   2498      already set correctly if compiling with GCC.  This will almost
   2499      never need to be defined.
   2500 
   2501 `lint'
   2502      Define this to help placate `lint' in some situations.
   2503 
   2504 `volatile'
   2505      Define this to override the defaults of `__volatile__' or `/**/'.
   2506 
   2507 
   2508 File: gdbint.info,  Node: Target Architecture Definition,  Next: Target Descriptions,  Prev: Host Definition,  Up: Top
   2509 
   2510 11 Target Architecture Definition
   2511 *********************************
   2512 
   2513 GDB's target architecture defines what sort of machine-language
   2514 programs GDB can work with, and how it works with them.
   2515 
   2516    The target architecture object is implemented as the C structure
   2517 `struct gdbarch *'.  The structure, and its methods, are generated
   2518 using the Bourne shell script `gdbarch.sh'.
   2519 
   2520 * Menu:
   2521 
   2522 * OS ABI Variant Handling::
   2523 * Initialize New Architecture::
   2524 * Registers and Memory::
   2525 * Pointers and Addresses::
   2526 * Address Classes::
   2527 * Register Representation::
   2528 * Frame Interpretation::
   2529 * Inferior Call Setup::
   2530 * Adding support for debugging core files::
   2531 * Defining Other Architecture Features::
   2532 * Adding a New Target::
   2533 
   2534 
   2535 File: gdbint.info,  Node: OS ABI Variant Handling,  Next: Initialize New Architecture,  Up: Target Architecture Definition
   2536 
   2537 11.1 Operating System ABI Variant Handling
   2538 ==========================================
   2539 
   2540 GDB provides a mechanism for handling variations in OS ABIs.  An OS ABI
   2541 variant may have influence over any number of variables in the target
   2542 architecture definition.  There are two major components in the OS ABI
   2543 mechanism: sniffers and handlers.
   2544 
   2545    A "sniffer" examines a file matching a BFD architecture/flavour pair
   2546 (the architecture may be wildcarded) in an attempt to determine the OS
   2547 ABI of that file.  Sniffers with a wildcarded architecture are
   2548 considered to be "generic", while sniffers for a specific architecture
   2549 are considered to be "specific".  A match from a specific sniffer
   2550 overrides a match from a generic sniffer.  Multiple sniffers for an
   2551 architecture/flavour may exist, in order to differentiate between two
   2552 different operating systems which use the same basic file format.  The
   2553 OS ABI framework provides a generic sniffer for ELF-format files which
   2554 examines the `EI_OSABI' field of the ELF header, as well as note
   2555 sections known to be used by several operating systems.
   2556 
   2557    A "handler" is used to fine-tune the `gdbarch' structure for the
   2558 selected OS ABI.  There may be only one handler for a given OS ABI for
   2559 each BFD architecture.
   2560 
   2561    The following OS ABI variants are defined in `defs.h':
   2562 
   2563 `GDB_OSABI_UNINITIALIZED'
   2564      Used for struct gdbarch_info if ABI is still uninitialized.
   2565 
   2566 `GDB_OSABI_UNKNOWN'
   2567      The ABI of the inferior is unknown.  The default `gdbarch'
   2568      settings for the architecture will be used.
   2569 
   2570 `GDB_OSABI_SVR4'
   2571      UNIX System V Release 4.
   2572 
   2573 `GDB_OSABI_HURD'
   2574      GNU using the Hurd kernel.
   2575 
   2576 `GDB_OSABI_SOLARIS'
   2577      Sun Solaris.
   2578 
   2579 `GDB_OSABI_OSF1'
   2580      OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
   2581 
   2582 `GDB_OSABI_LINUX'
   2583      GNU using the Linux kernel.
   2584 
   2585 `GDB_OSABI_FREEBSD_AOUT'
   2586      FreeBSD using the `a.out' executable format.
   2587 
   2588 `GDB_OSABI_FREEBSD_ELF'
   2589      FreeBSD using the ELF executable format.
   2590 
   2591 `GDB_OSABI_NETBSD_AOUT'
   2592      NetBSD using the `a.out' executable format.
   2593 
   2594 `GDB_OSABI_NETBSD_ELF'
   2595      NetBSD using the ELF executable format.
   2596 
   2597 `GDB_OSABI_OPENBSD_ELF'
   2598      OpenBSD using the ELF executable format.
   2599 
   2600 `GDB_OSABI_WINCE'
   2601      Windows CE.
   2602 
   2603 `GDB_OSABI_GO32'
   2604      DJGPP.
   2605 
   2606 `GDB_OSABI_IRIX'
   2607      Irix.
   2608 
   2609 `GDB_OSABI_INTERIX'
   2610      Interix (Posix layer for MS-Windows systems).
   2611 
   2612 `GDB_OSABI_HPUX_ELF'
   2613      HP/UX using the ELF executable format.
   2614 
   2615 `GDB_OSABI_HPUX_SOM'
   2616      HP/UX using the SOM executable format.
   2617 
   2618 `GDB_OSABI_QNXNTO'
   2619      QNX Neutrino.
   2620 
   2621 `GDB_OSABI_CYGWIN'
   2622      Cygwin.
   2623 
   2624 `GDB_OSABI_AIX'
   2625      AIX.
   2626 
   2627 
   2628    Here are the functions that make up the OS ABI framework:
   2629 
   2630  -- Function: const char * gdbarch_osabi_name (enum gdb_osabi OSABI)
   2631      Return the name of the OS ABI corresponding to OSABI.
   2632 
   2633  -- Function: void gdbarch_register_osabi (enum bfd_architecture ARCH,
   2634           unsigned long MACHINE, enum gdb_osabi OSABI, void
   2635           (*INIT_OSABI)(struct gdbarch_info INFO, struct gdbarch
   2636           *GDBARCH))
   2637      Register the OS ABI handler specified by INIT_OSABI for the
   2638      architecture, machine type and OS ABI specified by ARCH, MACHINE
   2639      and OSABI.  In most cases, a value of zero for the machine type,
   2640      which implies the architecture's default machine type, will
   2641      suffice.
   2642 
   2643  -- Function: void gdbarch_register_osabi_sniffer (enum
   2644           bfd_architecture ARCH, enum bfd_flavour FLAVOUR, enum
   2645           gdb_osabi (*SNIFFER)(bfd *ABFD))
   2646      Register the OS ABI file sniffer specified by SNIFFER for the BFD
   2647      architecture/flavour pair specified by ARCH and FLAVOUR.  If ARCH
   2648      is `bfd_arch_unknown', the sniffer is considered to be generic,
   2649      and is allowed to examine FLAVOUR-flavoured files for any
   2650      architecture.
   2651 
   2652  -- Function: enum gdb_osabi gdbarch_lookup_osabi (bfd *ABFD)
   2653      Examine the file described by ABFD to determine its OS ABI.  The
   2654      value `GDB_OSABI_UNKNOWN' is returned if the OS ABI cannot be
   2655      determined.
   2656 
   2657  -- Function: void gdbarch_init_osabi (struct gdbarch info INFO, struct
   2658           gdbarch *GDBARCH, enum gdb_osabi OSABI)
   2659      Invoke the OS ABI handler corresponding to OSABI to fine-tune the
   2660      `gdbarch' structure specified by GDBARCH.  If a handler
   2661      corresponding to OSABI has not been registered for GDBARCH's
   2662      architecture, a warning will be issued and the debugging session
   2663      will continue with the defaults already established for GDBARCH.
   2664 
   2665  -- Function: void generic_elf_osabi_sniff_abi_tag_sections (bfd *ABFD,
   2666           asection *SECT, void *OBJ)
   2667      Helper routine for ELF file sniffers.  Examine the file described
   2668      by ABFD and look at ABI tag note sections to determine the OS ABI
   2669      from the note.  This function should be called via
   2670      `bfd_map_over_sections'.
   2671 
   2672 
   2673 File: gdbint.info,  Node: Initialize New Architecture,  Next: Registers and Memory,  Prev: OS ABI Variant Handling,  Up: Target Architecture Definition
   2674 
   2675 11.2 Initializing a New Architecture
   2676 ====================================
   2677 
   2678 * Menu:
   2679 
   2680 * How an Architecture is Represented::
   2681 * Looking Up an Existing Architecture::
   2682 * Creating a New Architecture::
   2683 
   2684 
   2685 File: gdbint.info,  Node: How an Architecture is Represented,  Next: Looking Up an Existing Architecture,  Up: Initialize New Architecture
   2686 
   2687 11.2.1 How an Architecture is Represented
   2688 -----------------------------------------
   2689 
   2690 Each `gdbarch' is associated with a single BFD architecture, via a
   2691 `bfd_arch_ARCH' in the `bfd_architecture' enumeration.  The `gdbarch'
   2692 is registered by a call to `register_gdbarch_init', usually from the
   2693 file's `_initialize_FILENAME' routine, which will be automatically
   2694 called during GDB startup.  The arguments are a BFD architecture
   2695 constant and an initialization function.
   2696 
   2697    A GDB description for a new architecture, ARCH is created by
   2698 defining a global function `_initialize_ARCH_tdep', by convention in
   2699 the source file `ARCH-tdep.c'.  For example, in the case of the
   2700 OpenRISC 1000, this function is called `_initialize_or1k_tdep' and is
   2701 found in the file `or1k-tdep.c'.
   2702 
   2703    The resulting object files containing the implementation of the
   2704 `_initialize_ARCH_tdep' function are specified in the GDB
   2705 `configure.tgt' file, which includes a large case statement pattern
   2706 matching against the `--target' option of the `configure' script.  The
   2707 new `struct gdbarch' is created within the `_initialize_ARCH_tdep'
   2708 function by calling `gdbarch_register':
   2709 
   2710      void gdbarch_register (enum bfd_architecture    ARCHITECTURE,
   2711                             gdbarch_init_ftype      *INIT_FUNC,
   2712                             gdbarch_dump_tdep_ftype *TDEP_DUMP_FUNC);
   2713 
   2714    The ARCHITECTURE will identify the unique BFD to be associated with
   2715 this `gdbarch'.  The INIT_FUNC funciton is called to create and return
   2716 the new `struct gdbarch'.  The TDEP_DUMP_FUNC function will dump the
   2717 target specific details associated with this architecture.
   2718 
   2719    For example the function `_initialize_or1k_tdep' creates its
   2720 architecture for 32-bit OpenRISC 1000 architectures by calling:
   2721 
   2722      gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep);
   2723 
   2724 
   2725 File: gdbint.info,  Node: Looking Up an Existing Architecture,  Next: Creating a New Architecture,  Prev: How an Architecture is Represented,  Up: Initialize New Architecture
   2726 
   2727 11.2.2 Looking Up an Existing Architecture
   2728 ------------------------------------------
   2729 
   2730 The initialization function has this prototype:
   2731 
   2732      static struct gdbarch *
   2733      ARCH_gdbarch_init (struct gdbarch_info INFO,
   2734                               struct gdbarch_list *ARCHES)
   2735 
   2736    The INFO argument contains parameters used to select the correct
   2737 architecture, and ARCHES is a list of architectures which have already
   2738 been created with the same `bfd_arch_ARCH' value.
   2739 
   2740    The initialization function should first make sure that INFO is
   2741 acceptable, and return `NULL' if it is not.  Then, it should search
   2742 through ARCHES for an exact match to INFO, and return one if found.
   2743 Lastly, if no exact match was found, it should create a new
   2744 architecture based on INFO and return it.
   2745 
   2746    The lookup is done using `gdbarch_list_lookup_by_info'.  It is
   2747 passed the list of existing architectures, ARCHES, and the `struct
   2748 gdbarch_info', INFO, and returns the first matching architecture it
   2749 finds, or `NULL' if none are found.  If an architecture is found it can
   2750 be returned as the result from the initialization function, otherwise a
   2751 new `struct gdbach' will need to be created.
   2752 
   2753    The struct gdbarch_info has the following components:
   2754 
   2755      struct gdbarch_info
   2756      {
   2757         const struct bfd_arch_info *bfd_arch_info;
   2758         int                         byte_order;
   2759         bfd                        *abfd;
   2760         struct gdbarch_tdep_info   *tdep_info;
   2761         enum gdb_osabi              osabi;
   2762         const struct target_desc   *target_desc;
   2763      };
   2764 
   2765    The `bfd_arch_info' member holds the key details about the
   2766 architecture.  The `byte_order' member is a value in an enumeration
   2767 indicating the endianism.  The `abfd' member is a pointer to the full
   2768 BFD, the `tdep_info' member is additional custom target specific
   2769 information, `osabi' identifies which (if any) of a number of operating
   2770 specific ABIs are used by this architecture and the `target_desc'
   2771 member is a set of name-value pairs with information about register
   2772 usage in this target.
   2773 
   2774    When the `struct gdbarch' initialization function is called, not all
   2775 the fields are provided--only those which can be deduced from the BFD.
   2776 The `struct gdbarch_info', INFO is used as a look-up key with the list
   2777 of existing architectures, ARCHES to see if a suitable architecture
   2778 already exists.  The TDEP_INFO, OSABI and TARGET_DESC fields may be
   2779 added before this lookup to refine the search.
   2780 
   2781    Only information in INFO should be used to choose the new
   2782 architecture.  Historically, INFO could be sparse, and defaults would
   2783 be collected from the first element on ARCHES.  However, GDB now fills
   2784 in INFO more thoroughly, so new `gdbarch' initialization functions
   2785 should not take defaults from ARCHES.
   2786 
   2787 
   2788 File: gdbint.info,  Node: Creating a New Architecture,  Prev: Looking Up an Existing Architecture,  Up: Initialize New Architecture
   2789 
   2790 11.2.3 Creating a New Architecture
   2791 ----------------------------------
   2792 
   2793 If no architecture is found, then a new architecture must be created,
   2794 by calling `gdbarch_alloc' using the supplied `struct gdbarch_info' and
   2795 any additional custom target specific information in a `struct
   2796 gdbarch_tdep'.  The prototype for `gdbarch_alloc' is:
   2797 
   2798      struct gdbarch *gdbarch_alloc (const struct gdbarch_info *INFO,
   2799                                     struct gdbarch_tdep       *TDEP);
   2800 
   2801    The newly created struct gdbarch must then be populated.  Although
   2802 there are default values, in most cases they are not what is required.
   2803 
   2804    For each element, X, there is are a pair of corresponding accessor
   2805 functions, one to set the value of that element, `set_gdbarch_X', the
   2806 second to either get the value of an element (if it is a variable) or
   2807 to apply the element (if it is a function), `gdbarch_X'.  Note that
   2808 both accessor functions take a pointer to the `struct gdbarch' as first
   2809 argument.  Populating the new `gdbarch' should use the `set_gdbarch'
   2810 functions.
   2811 
   2812    The following sections identify the main elements that should be set
   2813 in this way.  This is not the complete list, but represents the
   2814 functions and elements that must commonly be specified for a new
   2815 architecture.  Many of the functions and variables are described in the
   2816 header file `gdbarch.h'.
   2817 
   2818    This is the main work in defining a new architecture.  Implementing
   2819 the set of functions to populate the `struct gdbarch'.
   2820 
   2821    `struct gdbarch_tdep' is not defined within GDB--it is up to the
   2822 user to define this struct if it is needed to hold custom target
   2823 information that is not covered by the standard `struct gdbarch'. For
   2824 example with the OpenRISC 1000 architecture it is used to hold the
   2825 number of matchpoints available in the target (along with other
   2826 information).
   2827 
   2828    If there is no additional target specific information, it can be set
   2829 to `NULL'.
   2830 
   2831 
   2832 File: gdbint.info,  Node: Registers and Memory,  Next: Pointers and Addresses,  Prev: Initialize New Architecture,  Up: Target Architecture Definition
   2833 
   2834 11.3 Registers and Memory
   2835 =========================
   2836 
   2837 GDB's model of the target machine is rather simple.  GDB assumes the
   2838 machine includes a bank of registers and a block of memory.  Each
   2839 register may have a different size.
   2840 
   2841    GDB does not have a magical way to match up with the compiler's idea
   2842 of which registers are which; however, it is critical that they do
   2843 match up accurately.  The only way to make this work is to get accurate
   2844 information about the order that the compiler uses, and to reflect that
   2845 in the `gdbarch_register_name' and related functions.
   2846 
   2847    GDB can handle big-endian, little-endian, and bi-endian
   2848 architectures.
   2849 
   2850 
   2851 File: gdbint.info,  Node: Pointers and Addresses,  Next: Address Classes,  Prev: Registers and Memory,  Up: Target Architecture Definition
   2852 
   2853 11.4 Pointers Are Not Always Addresses
   2854 ======================================
   2855 
   2856 On almost all 32-bit architectures, the representation of a pointer is
   2857 indistinguishable from the representation of some fixed-length number
   2858 whose value is the byte address of the object pointed to.  On such
   2859 machines, the words "pointer" and "address" can be used interchangeably.
   2860 However, architectures with smaller word sizes are often cramped for
   2861 address space, so they may choose a pointer representation that breaks
   2862 this identity, and allows a larger code address space.
   2863 
   2864    For example, the Renesas D10V is a 16-bit VLIW processor whose
   2865 instructions are 32 bits long(1).  If the D10V used ordinary byte
   2866 addresses to refer to code locations, then the processor would only be
   2867 able to address 64kb of instructions.  However, since instructions must
   2868 be aligned on four-byte boundaries, the low two bits of any valid
   2869 instruction's byte address are always zero--byte addresses waste two
   2870 bits.  So instead of byte addresses, the D10V uses word addresses--byte
   2871 addresses shifted right two bits--to refer to code.  Thus, the D10V can
   2872 use 16-bit words to address 256kb of code space.
   2873 
   2874    However, this means that code pointers and data pointers have
   2875 different forms on the D10V.  The 16-bit word `0xC020' refers to byte
   2876 address `0xC020' when used as a data address, but refers to byte address
   2877 `0x30080' when used as a code address.
   2878 
   2879    (The D10V also uses separate code and data address spaces, which also
   2880 affects the correspondence between pointers and addresses, but we're
   2881 going to ignore that here; this example is already too long.)
   2882 
   2883    To cope with architectures like this--the D10V is not the only
   2884 one!--GDB tries to distinguish between "addresses", which are byte
   2885 numbers, and "pointers", which are the target's representation of an
   2886 address of a particular type of data.  In the example above, `0xC020'
   2887 is the pointer, which refers to one of the addresses `0xC020' or
   2888 `0x30080', depending on the type imposed upon it.  GDB provides
   2889 functions for turning a pointer into an address and vice versa, in the
   2890 appropriate way for the current architecture.
   2891 
   2892    Unfortunately, since addresses and pointers are identical on almost
   2893 all processors, this distinction tends to bit-rot pretty quickly.  Thus,
   2894 each time you port GDB to an architecture which does distinguish
   2895 between pointers and addresses, you'll probably need to clean up some
   2896 architecture-independent code.
   2897 
   2898    Here are functions which convert between pointers and addresses:
   2899 
   2900  -- Function: CORE_ADDR extract_typed_address (void *BUF, struct type
   2901           *TYPE)
   2902      Treat the bytes at BUF as a pointer or reference of type TYPE, and
   2903      return the address it represents, in a manner appropriate for the
   2904      current architecture.  This yields an address GDB can use to read
   2905      target memory, disassemble, etc.  Note that BUF refers to a buffer
   2906      in GDB's memory, not the inferior's.
   2907 
   2908      For example, if the current architecture is the Intel x86, this
   2909      function extracts a little-endian integer of the appropriate
   2910      length from BUF and returns it.  However, if the current
   2911      architecture is the D10V, this function will return a 16-bit
   2912      integer extracted from BUF, multiplied by four if TYPE is a
   2913      pointer to a function.
   2914 
   2915      If TYPE is not a pointer or reference type, then this function
   2916      will signal an internal error.
   2917 
   2918  -- Function: CORE_ADDR store_typed_address (void *BUF, struct type
   2919           *TYPE, CORE_ADDR ADDR)
   2920      Store the address ADDR in BUF, in the proper format for a pointer
   2921      of type TYPE in the current architecture.  Note that BUF refers to
   2922      a buffer in GDB's memory, not the inferior's.
   2923 
   2924      For example, if the current architecture is the Intel x86, this
   2925      function stores ADDR unmodified as a little-endian integer of the
   2926      appropriate length in BUF.  However, if the current architecture
   2927      is the D10V, this function divides ADDR by four if TYPE is a
   2928      pointer to a function, and then stores it in BUF.
   2929 
   2930      If TYPE is not a pointer or reference type, then this function
   2931      will signal an internal error.
   2932 
   2933  -- Function: CORE_ADDR value_as_address (struct value *VAL)
   2934      Assuming that VAL is a pointer, return the address it represents,
   2935      as appropriate for the current architecture.
   2936 
   2937      This function actually works on integral values, as well as
   2938      pointers.  For pointers, it performs architecture-specific
   2939      conversions as described above for `extract_typed_address'.
   2940 
   2941  -- Function: CORE_ADDR value_from_pointer (struct type *TYPE,
   2942           CORE_ADDR ADDR)
   2943      Create and return a value representing a pointer of type TYPE to
   2944      the address ADDR, as appropriate for the current architecture.
   2945      This function performs architecture-specific conversions as
   2946      described above for `store_typed_address'.
   2947 
   2948    Here are two functions which architectures can define to indicate the
   2949 relationship between pointers and addresses.  These have default
   2950 definitions, appropriate for architectures on which all pointers are
   2951 simple unsigned byte addresses.
   2952 
   2953  -- Function: CORE_ADDR gdbarch_pointer_to_address (struct gdbarch
   2954           *GDBARCH, struct type *TYPE, char *BUF)
   2955      Assume that BUF holds a pointer of type TYPE, in the appropriate
   2956      format for the current architecture.  Return the byte address the
   2957      pointer refers to.
   2958 
   2959      This function may safely assume that TYPE is either a pointer or a
   2960      C++ reference type.
   2961 
   2962  -- Function: void gdbarch_address_to_pointer (struct gdbarch *GDBARCH,
   2963           struct type *TYPE, char *BUF, CORE_ADDR ADDR)
   2964      Store in BUF a pointer of type TYPE representing the address ADDR,
   2965      in the appropriate format for the current architecture.
   2966 
   2967      This function may safely assume that TYPE is either a pointer or a
   2968      C++ reference type.
   2969 
   2970    ---------- Footnotes ----------
   2971 
   2972    (1) Some D10V instructions are actually pairs of 16-bit
   2973 sub-instructions.  However, since you can't jump into the middle of
   2974 such a pair, code addresses can only refer to full 32 bit instructions,
   2975 which is what matters in this explanation.
   2976 
   2977 
   2978 File: gdbint.info,  Node: Address Classes,  Next: Register Representation,  Prev: Pointers and Addresses,  Up: Target Architecture Definition
   2979 
   2980 11.5 Address Classes
   2981 ====================
   2982 
   2983 Sometimes information about different kinds of addresses is available
   2984 via the debug information.  For example, some programming environments
   2985 define addresses of several different sizes.  If the debug information
   2986 distinguishes these kinds of address classes through either the size
   2987 info (e.g, `DW_AT_byte_size' in DWARF 2) or through an explicit address
   2988 class attribute (e.g, `DW_AT_address_class' in DWARF 2), the following
   2989 macros should be defined in order to disambiguate these types within
   2990 GDB as well as provide the added information to a GDB user when
   2991 printing type expressions.
   2992 
   2993  -- Function: int gdbarch_address_class_type_flags (struct gdbarch
   2994           *GDBARCH, int BYTE_SIZE, int DWARF2_ADDR_CLASS)
   2995      Returns the type flags needed to construct a pointer type whose
   2996      size is BYTE_SIZE and whose address class is DWARF2_ADDR_CLASS.
   2997      This function is normally called from within a symbol reader.  See
   2998      `dwarf2read.c'.
   2999 
   3000  -- Function: char * gdbarch_address_class_type_flags_to_name (struct
   3001           gdbarch *GDBARCH, int TYPE_FLAGS)
   3002      Given the type flags representing an address class qualifier,
   3003      return its name.
   3004 
   3005  -- Function: int gdbarch_address_class_name_to_type_flags (struct
   3006           gdbarch *GDBARCH, int NAME, int *TYPE_FLAGS_PTR)
   3007      Given an address qualifier name, set the `int' referenced by
   3008      TYPE_FLAGS_PTR to the type flags for that address class qualifier.
   3009 
   3010    Since the need for address classes is rather rare, none of the
   3011 address class functions are defined by default.  Predicate functions
   3012 are provided to detect when they are defined.
   3013 
   3014    Consider a hypothetical architecture in which addresses are normally
   3015 32-bits wide, but 16-bit addresses are also supported.  Furthermore,
   3016 suppose that the DWARF 2 information for this architecture simply uses
   3017 a `DW_AT_byte_size' value of 2 to indicate the use of one of these
   3018 "short" pointers.  The following functions could be defined to
   3019 implement the address class functions:
   3020 
   3021      somearch_address_class_type_flags (int byte_size,
   3022                                         int dwarf2_addr_class)
   3023      {
   3024        if (byte_size == 2)
   3025          return TYPE_FLAG_ADDRESS_CLASS_1;
   3026        else
   3027          return 0;
   3028      }
   3029 
   3030      static char *
   3031      somearch_address_class_type_flags_to_name (int type_flags)
   3032      {
   3033        if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
   3034          return "short";
   3035        else
   3036          return NULL;
   3037      }
   3038 
   3039      int
   3040      somearch_address_class_name_to_type_flags (char *name,
   3041                                                 int *type_flags_ptr)
   3042      {
   3043        if (strcmp (name, "short") == 0)
   3044          {
   3045            *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
   3046            return 1;
   3047          }
   3048        else
   3049          return 0;
   3050      }
   3051 
   3052    The qualifier `@short' is used in GDB's type expressions to indicate
   3053 the presence of one of these "short" pointers.  For example if the
   3054 debug information indicates that `short_ptr_var' is one of these short
   3055 pointers, GDB might show the following behavior:
   3056 
   3057      (gdb) ptype short_ptr_var
   3058      type = int * @short
   3059 
   3060 
   3061 File: gdbint.info,  Node: Register Representation,  Next: Frame Interpretation,  Prev: Address Classes,  Up: Target Architecture Definition
   3062 
   3063 11.6 Register Representation
   3064 ============================
   3065 
   3066 * Menu:
   3067 
   3068 * Raw and Cooked Registers::
   3069 * Register Architecture Functions & Variables::
   3070 * Register Information Functions::
   3071 * Register and Memory Data::
   3072 * Register Caching::
   3073 
   3074 
   3075 File: gdbint.info,  Node: Raw and Cooked Registers,  Next: Register Architecture Functions & Variables,  Up: Register Representation
   3076 
   3077 11.6.1 Raw and Cooked Registers
   3078 -------------------------------
   3079 
   3080 GDB considers registers to be a set with members numbered linearly from
   3081 0 upwards.  The first part of that set corresponds to real physical
   3082 registers, the second part to any "pseudo-registers".  Pseudo-registers
   3083 have no independent physical existence, but are useful representations
   3084 of information within the architecture.  For example the OpenRISC 1000
   3085 architecture has up to 32 general purpose registers, which are
   3086 typically represented as 32-bit (or 64-bit) integers.  However the GPRs
   3087 are also used as operands to the floating point operations, and it
   3088 could be convenient to define a set of pseudo-registers, to show the
   3089 GPRs represented as floating point values.
   3090 
   3091    For any architecture, the implementer will decide on a mapping from
   3092 hardware to GDB register numbers.  The registers corresponding to real
   3093 hardware are referred to as "raw" registers, the remaining registers are
   3094 "pseudo-registers".  The total register set (raw and pseudo) is called
   3095 the "cooked" register set.
   3096 
   3097 
   3098 File: gdbint.info,  Node: Register Architecture Functions & Variables,  Next: Register Information Functions,  Prev: Raw and Cooked Registers,  Up: Register Representation
   3099 
   3100 11.6.2 Functions and Variables Specifying the Register Architecture
   3101 -------------------------------------------------------------------
   3102 
   3103 These `struct gdbarch' functions and variables specify the number and
   3104 type of registers in the architecture.
   3105 
   3106  -- Architecture Function: CORE_ADDR read_pc (struct regcache *REGCACHE)
   3107 
   3108  -- Architecture Function: void write_pc (struct regcache *REGCACHE,
   3109           CORE_ADDR VAL)
   3110      Read or write the program counter.  The default value of both
   3111      functions is `NULL' (no function available).  If the program
   3112      counter is just an ordinary register, it can be specified in
   3113      `struct gdbarch' instead (see `pc_regnum' below) and it will be
   3114      read or written using the standard routines to access registers.
   3115      This function need only be specified if the program counter is not
   3116      an ordinary register.
   3117 
   3118      Any register information can be obtained using the supplied
   3119      register cache, REGCACHE.  *Note Register Caching: Register
   3120      Caching.
   3121 
   3122 
   3123  -- Architecture Function: void pseudo_register_read (struct gdbarch
   3124           *GDBARCH, struct regcache *REGCACHE, int REGNUM, const
   3125           gdb_byte *BUF)
   3126 
   3127  -- Architecture Function: void pseudo_register_write (struct gdbarch
   3128           *GDBARCH, struct regcache *REGCACHE, int REGNUM, const
   3129           gdb_byte *BUF)
   3130      These functions should be defined if there are any
   3131      pseudo-registers.  The default value is `NULL'.  REGNUM is the
   3132      number of the register to read or write (which will be a "cooked"
   3133      register number) and BUF is the buffer where the value read will be
   3134      placed, or from which the value to be written will be taken.  The
   3135      value in the buffer may be converted to or from a signed or
   3136      unsigned integral value using one of the utility functions (*note
   3137      Using Different Register and Memory Data Representations: Register
   3138      and Memory Data.).
   3139 
   3140      The access should be for the specified architecture, GDBARCH.  Any
   3141      register information can be obtained using the supplied register
   3142      cache, REGCACHE.  *Note Register Caching: Register Caching.
   3143 
   3144 
   3145  -- Architecture Variable: int sp_regnum
   3146      This specifies the register holding the stack pointer, which may
   3147      be a raw or pseudo-register.  It defaults to -1 (not defined), but
   3148      it is an error for it not to be defined.
   3149 
   3150      The value of the stack pointer register can be accessed withing
   3151      GDB as the variable `$sp'.
   3152 
   3153 
   3154  -- Architecture Variable: int pc_regnum
   3155      This specifies the register holding the program counter, which may
   3156      be a raw or pseudo-register.  It defaults to -1 (not defined).  If
   3157      `pc_regnum' is not defined, then the functions `read_pc' and
   3158      `write_pc' (see above) must be defined.
   3159 
   3160      The value of the program counter (whether defined as a register, or
   3161      through `read_pc' and `write_pc') can be accessed withing GDB as
   3162      the variable `$pc'.
   3163 
   3164 
   3165  -- Architecture Variable: int ps_regnum
   3166      This specifies the register holding the processor status (often
   3167      called the status register), which may be a raw or
   3168      pseudo-register.  It defaults to -1 (not defined).
   3169 
   3170      If defined, the value of this register can be accessed withing GDB
   3171      as the variable `$ps'.
   3172 
   3173 
   3174  -- Architecture Variable: int fp0_regnum
   3175      This specifies the first floating point register.  It defaults to
   3176      0.  `fp0_regnum' is not needed unless the target offers support
   3177      for floating point.
   3178 
   3179 
   3180 
   3181 File: gdbint.info,  Node: Register Information Functions,  Next: Register and Memory Data,  Prev: Register Architecture Functions & Variables,  Up: Register Representation
   3182 
   3183 11.6.3 Functions Giving Register Information
   3184 --------------------------------------------
   3185 
   3186 These functions return information about registers.
   3187 
   3188  -- Architecture Function: const char * register_name (struct gdbarch
   3189           *GDBARCH, int REGNUM)
   3190      This function should convert a register number (raw or pseudo) to a
   3191      register name (as a C `const char *').  This is used both to
   3192      determine the name of a register for output and to work out the
   3193      meaning of any register names used as input.  The function may
   3194      also return `NULL', to indicate that REGNUM is not a valid
   3195      register.
   3196 
   3197      For example with the OpenRISC 1000, GDB registers 0-31 are the
   3198      General Purpose Registers, register 32 is the program counter and
   3199      register 33 is the supervision register (i.e. the processor status
   3200      register), which map to the strings `"gpr00"' through `"gpr31"',
   3201      `"pc"' and `"sr"' respectively. This means that the GDB command
   3202      `print $gpr5' should print the value of the OR1K general purpose
   3203      register 5(1).
   3204 
   3205      The default value for this function is `NULL', meaning undefined.
   3206      It should always be defined.
   3207 
   3208      The access should be for the specified architecture, GDBARCH.
   3209 
   3210 
   3211  -- Architecture Function: struct type * register_type (struct gdbarch
   3212           *GDBARCH, int REGNUM)
   3213      Given a register number, this function identifies the type of data
   3214      it may be holding, specified as a `struct type'.  GDB allows
   3215      creation of arbitrary types, but a number of built in types are
   3216      provided (`builtin_type_void', `builtin_type_int32' etc), together
   3217      with functions to derive types from these.
   3218 
   3219      Typically the program counter will have a type of "pointer to
   3220      function" (it points to code), the frame pointer and stack pointer
   3221      will have types of "pointer to void" (they point to data on the
   3222      stack) and all other integer registers will have a type of 32-bit
   3223      integer or 64-bit integer.
   3224 
   3225      This information guides the formatting when displaying register
   3226      information.  The default value is `NULL' meaning no information is
   3227      available to guide formatting when displaying registers.
   3228 
   3229 
   3230  -- Architecture Function: void print_registers_info (struct gdbarch
   3231           *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME, int
   3232           REGNUM, int ALL)
   3233      Define this function to print out one or all of the registers for
   3234      the GDB `info registers' command.  The default value is the
   3235      function `default_print_registers_info', which uses the register
   3236      type information (see `register_type' above) to determine how each
   3237      register should be printed.  Define a custom version of this
   3238      function for fuller control over how the registers are displayed.
   3239 
   3240      The access should be for the specified architecture, GDBARCH, with
   3241      output to the the file specified by the User Interface Independent
   3242      Output file handle, FILE (*note UI-Independent Output--the
   3243      `ui_out' Functions: UI-Independent Output.).
   3244 
   3245      The registers should show their values in the frame specified by
   3246      FRAME.  If REGNUM is -1 and ALL is zero, then all the
   3247      "significant" registers should be shown (the implementer should
   3248      decide which registers are "significant"). Otherwise only the
   3249      value of the register specified by REGNUM should be output.  If
   3250      REGNUM is -1 and ALL is non-zero (true), then the value of all
   3251      registers should be shown.
   3252 
   3253      By default `default_print_registers_info' prints one register per
   3254      line, and if ALL is zero omits floating-point registers.
   3255 
   3256 
   3257  -- Architecture Function: void print_float_info (struct gdbarch
   3258           *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
   3259           const char *ARGS)
   3260      Define this function to provide output about the floating point
   3261      unit and registers for the GDB `info float' command respectively.
   3262      The default value is `NULL' (not defined), meaning no information
   3263      will be provided.
   3264 
   3265      The GDBARCH and FILE and FRAME arguments have the same meaning as
   3266      in the `print_registers_info' function above. The string ARGS
   3267      contains any supplementary arguments to the `info float' command.
   3268 
   3269      Define this function if the target supports floating point
   3270      operations.
   3271 
   3272 
   3273  -- Architecture Function: void print_vector_info (struct gdbarch
   3274           *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
   3275           const char *ARGS)
   3276      Define this function to provide output about the vector unit and
   3277      registers for the GDB `info vector' command respectively.  The
   3278      default value is `NULL' (not defined), meaning no information will
   3279      be provided.
   3280 
   3281      The GDBARCH, FILE and FRAME arguments have the same meaning as in
   3282      the `print_registers_info' function above.  The string ARGS
   3283      contains any supplementary arguments to the `info vector' command.
   3284 
   3285      Define this function if the target supports vector operations.
   3286 
   3287 
   3288  -- Architecture Function: int register_reggroup_p (struct gdbarch
   3289           *GDBARCH, int REGNUM, struct reggroup *GROUP)
   3290      GDB groups registers into different categories (general, vector,
   3291      floating point etc).  This function, given a register, REGNUM, and
   3292      group, GROUP, returns 1 (true) if the register is in the group and
   3293      0 (false) otherwise.
   3294 
   3295      The information should be for the specified architecture, GDBARCH
   3296 
   3297      The default value is the function `default_register_reggroup_p'
   3298      which will do a reasonable job based on the type of the register
   3299      (see the function `register_type' above), with groups for general
   3300      purpose registers, floating point registers, vector registers and
   3301      raw (i.e not pseudo) registers.
   3302 
   3303 
   3304    ---------- Footnotes ----------
   3305 
   3306    (1) Historically, GDB always had a concept of a frame pointer
   3307 register, which could be accessed via the GDB variable, `$fp'.  That
   3308 concept is now deprecated, recognizing that not all architectures have
   3309 a frame pointer.  However if an architecture does have a frame pointer
   3310 register, and defines a register or pseudo-register with the name
   3311 `"fp"', then that register will be used as the value of the `$fp'
   3312 variable.
   3313 
   3314 
   3315 File: gdbint.info,  Node: Register and Memory Data,  Next: Register Caching,  Prev: Register Information Functions,  Up: Register Representation
   3316 
   3317 11.6.4 Using Different Register and Memory Data Representations
   3318 ---------------------------------------------------------------
   3319 
   3320 Some architectures have different representations of data objects,
   3321 depending whether the object is held in a register or memory.  For
   3322 example:
   3323 
   3324    * The Alpha architecture can represent 32 bit integer values in
   3325      floating-point registers.
   3326 
   3327    * The x86 architecture supports 80-bit floating-point registers.  The
   3328      `long double' data type occupies 96 bits in memory but only 80
   3329      bits when stored in a register.
   3330 
   3331 
   3332    In general, the register representation of a data type is determined
   3333 by the architecture, or GDB's interface to the architecture, while the
   3334 memory representation is determined by the Application Binary Interface.
   3335 
   3336    For almost all data types on almost all architectures, the two
   3337 representations are identical, and no special handling is needed.
   3338 However, they do occasionally differ.  An architecture may define the
   3339 following `struct gdbarch' functions to request conversions between the
   3340 register and memory representations of a data type:
   3341 
   3342  -- Architecture Function: int gdbarch_convert_register_p (struct
   3343           gdbarch *GDBARCH, int REG)
   3344      Return non-zero (true) if the representation of a data value
   3345      stored in this register may be different to the representation of
   3346      that same data value when stored in memory.  The default value is
   3347      `NULL' (undefined).
   3348 
   3349      If this function is defined and returns non-zero, the `struct
   3350      gdbarch' functions `gdbarch_register_to_value' and
   3351      `gdbarch_value_to_register' (see below) should be used to perform
   3352      any necessary conversion.
   3353 
   3354      If defined, this function should return zero for the register's
   3355      native type, when no conversion is necessary.
   3356 
   3357  -- Architecture Function: void gdbarch_register_to_value (struct
   3358           gdbarch *GDBARCH, int REG, struct type *TYPE, char *FROM,
   3359           char *TO)
   3360      Convert the value of register number REG to a data object of type
   3361      TYPE.  The buffer at FROM holds the register's value in raw
   3362      format; the converted value should be placed in the buffer at TO.
   3363 
   3364           _Note:_ `gdbarch_register_to_value' and
   3365           `gdbarch_value_to_register' take their REG and TYPE arguments
   3366           in different orders.
   3367 
   3368      `gdbarch_register_to_value' should only be used with registers for
   3369      which the `gdbarch_convert_register_p' function returns a non-zero
   3370      value.
   3371 
   3372 
   3373  -- Architecture Function: void gdbarch_value_to_register (struct
   3374           gdbarch *GDBARCH, struct type *TYPE, int REG, char *FROM,
   3375           char *TO)
   3376      Convert a data value of type TYPE to register number REG' raw
   3377      format.
   3378 
   3379           _Note:_ `gdbarch_register_to_value' and
   3380           `gdbarch_value_to_register' take their REG and TYPE arguments
   3381           in different orders.
   3382 
   3383      `gdbarch_value_to_register' should only be used with registers for
   3384      which the `gdbarch_convert_register_p' function returns a non-zero
   3385      value.
   3386 
   3387 
   3388 
   3389 File: gdbint.info,  Node: Register Caching,  Prev: Register and Memory Data,  Up: Register Representation
   3390 
   3391 11.6.5 Register Caching
   3392 -----------------------
   3393 
   3394 Caching of registers is used, so that the target does not need to be
   3395 accessed and reanalyzed multiple times for each register in
   3396 circumstances where the register value cannot have changed.
   3397 
   3398    GDB provides `struct regcache', associated with a particular `struct
   3399 gdbarch' to hold the cached values of the raw registers.  A set of
   3400 functions is provided to access both the raw registers (with `raw' in
   3401 their name) and the full set of cooked registers (with `cooked' in
   3402 their name).  Functions are provided to ensure the register cache is
   3403 kept synchronized with the values of the actual registers in the target.
   3404 
   3405    Accessing registers through the `struct regcache' routines will
   3406 ensure that the appropriate `struct gdbarch' functions are called when
   3407 necessary to access the underlying target architecture.  In general
   3408 users should use the "cooked" functions, since these will map to the
   3409 "raw" functions automatically as appropriate.
   3410 
   3411    The two key functions are `regcache_cooked_read' and
   3412 `regcache_cooked_write' which read or write a register from or to a
   3413 byte buffer (type `gdb_byte *').  For convenience the wrapper functions
   3414 `regcache_cooked_read_signed', `regcache_cooked_read_unsigned',
   3415 `regcache_cooked_write_signed' and `regcache_cooked_write_unsigned' are
   3416 provided, which read or write the value using the buffer and convert to
   3417 or from an integral value as appropriate.
   3418 
   3419 
   3420 File: gdbint.info,  Node: Frame Interpretation,  Next: Inferior Call Setup,  Prev: Register Representation,  Up: Target Architecture Definition
   3421 
   3422 11.7 Frame Interpretation
   3423 =========================
   3424 
   3425 * Menu:
   3426 
   3427 * All About Stack Frames::
   3428 * Frame Handling Terminology::
   3429 * Prologue Caches::
   3430 * Functions and Variable to Analyze Frames::
   3431 * Functions to Access Frame Data::
   3432 * Analyzing Stacks---Frame Sniffers::
   3433 
   3434 
   3435 File: gdbint.info,  Node: All About Stack Frames,  Next: Frame Handling Terminology,  Up: Frame Interpretation
   3436 
   3437 11.7.1 All About Stack Frames
   3438 -----------------------------
   3439 
   3440 GDB needs to understand the stack on which local (automatic) variables
   3441 are stored.  The area of the stack containing all the local variables
   3442 for a function invocation is known as the "stack frame" for that
   3443 function (or colloquially just as the "frame").  In turn the function
   3444 that called the function will have its stack frame, and so on back
   3445 through the chain of functions that have been called.
   3446 
   3447    Almost all architectures have one register dedicated to point to the
   3448 end of the stack (the "stack pointer").  Many have a second register
   3449 which points to the start of the currently active stack frame (the
   3450 "frame pointer").  The specific arrangements for an architecture are a
   3451 key part of the ABI.
   3452 
   3453    A diagram helps to explain this.  Here is a simple program to compute
   3454 factorials:
   3455 
   3456      #include <stdio.h>
   3457      int fact (int n)
   3458      {
   3459        if (0 == n)
   3460          {
   3461            return 1;
   3462          }
   3463        else
   3464          {
   3465            return n * fact (n - 1);
   3466          }
   3467      }
   3468 
   3469      main ()
   3470      {
   3471        int i;
   3472 
   3473        for (i = 0; i < 10; i++)
   3474          {
   3475            int   f = fact (i);
   3476            printf ("%d! = %d\n", i, f);
   3477          }
   3478      }
   3479 
   3480    Consider the state of the stack when the code reaches line 6 after
   3481 the main program has called `fact (3)'.  The chain of function calls
   3482 will be `main ()', `fact (3)', `fact (2)', `fact (1)' and `fact (0)'.
   3483 
   3484    In this illustration the stack is falling (as used for example by the
   3485 OpenRISC 1000 ABI).  The stack pointer (SP) is at the end of the stack
   3486 (lowest address) and the frame pointer (FP) is at the highest address
   3487 in the current stack frame.  The following diagram shows how the stack
   3488 looks.
   3489 
   3490                   ^    ->|            |
   3491 Frame             |   |  |            |
   3492 Number          - |   |  |============|       int fact (int n)
   3493                |  |   |  |   i = 3    |       {
   3494                |  |   |  |------------|         if (0 == n) {
   3495                |  |   |  |   f = ?    |           return  1;  <-------- PC
   3496   #4 main()   <   |   |  |------------|        }
   3497                |  |   |  |            |         else {
   3498                |  |  -+->|------------|   --->    return n * fact (n - 1);
   3499                |   -+-+--+-----o      |  |      }
   3500                 =   | |  |============|  |    }
   3501                |    | |  |   n = 3    |  |
   3502                |    | |  |------------|  |    main ()
   3503   #3 fact (3) <     | |  |     o---------+-   {
   3504                |   -+-+->|------------|  | |    int  i;
   3505                |  | |  --+-----o      |  | |
   3506                 = | |    |============|  | |    for (i = 0; i < 10; i++) {
   3507                |  | |    |   n = 2    |  |  ->    int  f = fact (i);
   3508                |  | |    |------------|  |        printf ("%d! = %d\n", i , f);
   3509   #2 fact (2) <   | |    |     o------+--|      }
   3510                |  | |  ->|------------|  |    }
   3511                |  |  -+--+-----o      |  |
   3512                 = |   |  |============|  |
   3513                |  |   |  |   n = 1    |  |
   3514                |  |   |  |------------|  |
   3515   #1 fact (1) <   |   |  |     o------+--|
   3516                |  |   |  |------------|  |
   3517                |   ---|--+-----o      |<-+------- FP
   3518                 =     |  |============|  |                   |
   3519                |      |  |   n = 0    |  |                   |
   3520                |      |  |------------|  |                   |
   3521   #0 fact (0) <       |  |     o---------                    |
   3522                |      |  |------------|                      |
   3523                |       --+-----o      |<--------- SP         |
   3524                 =        |============|                      |
   3525                |         |  Red Zone  |                      v
   3526                |         \/\/\/\/\/\/\/                 Direction of
   3527   #-1         <          \/\/\/\/\/\/\/                 stack growth
   3528                |         |            |
   3529 
   3530 In each stack frame, offset 0 from the stack pointer is the frame
   3531 pointer of the previous frame and offset 4 (this is illustrating a
   3532 32-bit architecture) from the stack pointer is the return address.
   3533 Local variables are indexed from the frame pointer, with negative
   3534 indexes.  In the function `fact', offset -4 from the frame pointer is
   3535 the argument N.  In the `main' function, offset -4 from the frame
   3536 pointer is the local variable I and offset -8 from the frame pointer is
   3537 the local variable F(1).
   3538 
   3539    It is very easy to get confused when examining stacks.  GDB has
   3540 terminology it uses rigorously throughout.  The stack frame of the
   3541 function currently executing, or where execution stopped is numbered
   3542 zero.  In this example frame #0 is the stack frame of the call to
   3543 `fact (0)'.  The stack frame of its calling function (`fact (1)' in
   3544 this case) is numbered #1 and so on back through the chain of calls.
   3545 
   3546    The main GDB data structure describing frames is
   3547 `struct frame_info'.  It is not used directly, but only via its
   3548 accessor functions.  `frame_info' includes information about the
   3549 registers in the frame and a pointer to the code of the function with
   3550 which the frame is associated.  The entire stack is represented as a
   3551 linked list of `frame_info' structs.
   3552 
   3553    ---------- Footnotes ----------
   3554 
   3555    (1) This is a simplified example for illustrative purposes only.
   3556 Good optimizing compilers would not put anything on the stack for such
   3557 simple functions.  Indeed they might eliminate the recursion and use of
   3558 the stack entirely!
   3559 
   3560 
   3561 File: gdbint.info,  Node: Frame Handling Terminology,  Next: Prologue Caches,  Prev: All About Stack Frames,  Up: Frame Interpretation
   3562 
   3563 11.7.2 Frame Handling Terminology
   3564 ---------------------------------
   3565 
   3566 It is easy to get confused when referencing stack frames.  GDB uses
   3567 some precise terminology.
   3568 
   3569    * "THIS" frame is the frame currently under consideration.
   3570 
   3571    * The "NEXT" frame, also sometimes called the inner or newer frame
   3572      is the frame of the function called by the function of THIS frame.
   3573 
   3574    * The "PREVIOUS" frame, also sometimes called the outer or older
   3575      frame is the frame of the function which called the function of
   3576      THIS frame.
   3577 
   3578 
   3579    So in the example in the previous section (*note All About Stack
   3580 Frames: All About Stack Frames.), if THIS frame is #3 (the call to
   3581 `fact (3)'), the NEXT frame is frame #2 (the call to `fact (2)') and
   3582 the PREVIOUS frame is frame #4 (the call to `main ()').
   3583 
   3584    The "innermost" frame is the frame of the current executing
   3585 function, or where the program stopped, in this example, in the middle
   3586 of the call to `fact (0))'.  It is always numbered frame #0.
   3587 
   3588    The "base" of a frame is the address immediately before the start of
   3589 the NEXT frame.  For a stack which grows down in memory (a "falling"
   3590 stack) this will be the lowest address and for a stack which grows up
   3591 in memory (a "rising" stack) this will be the highest address in the
   3592 frame.
   3593 
   3594    GDB functions to analyze the stack are typically given a pointer to
   3595 the NEXT frame to determine information about THIS frame.  Information
   3596 about THIS frame includes data on where the registers of the PREVIOUS
   3597 frame are stored in this stack frame.  In this example the frame
   3598 pointer of the PREVIOUS frame is stored at offset 0 from the stack
   3599 pointer of THIS frame.
   3600 
   3601    The process whereby a function is given a pointer to the NEXT frame
   3602 to work out information about THIS frame is referred to as "unwinding".
   3603 The GDB functions involved in this typically include unwind in their
   3604 name.
   3605 
   3606    The process of analyzing a target to determine the information that
   3607 should go in struct frame_info is called "sniffing".  The functions
   3608 that carry this out are called sniffers and typically include sniffer
   3609 in their name.  More than one sniffer may be required to extract all
   3610 the information for a particular frame.
   3611 
   3612    Because so many functions work using the NEXT frame, there is an
   3613 issue about addressing the innermost frame--it has no NEXT frame.  To
   3614 solve this GDB creates a dummy frame #-1, known as the "sentinel" frame.
   3615 
   3616 
   3617 File: gdbint.info,  Node: Prologue Caches,  Next: Functions and Variable to Analyze Frames,  Prev: Frame Handling Terminology,  Up: Frame Interpretation
   3618 
   3619 11.7.3 Prologue Caches
   3620 ----------------------
   3621 
   3622 All the frame sniffing functions typically examine the code at the
   3623 start of the corresponding function, to determine the state of
   3624 registers.  The ABI will save old values and set new values of key
   3625 registers at the start of each function in what is known as the
   3626 function "prologue".
   3627 
   3628    For any particular stack frame this data does not change, so all the
   3629 standard unwinding functions, in addition to receiving a pointer to the
   3630 NEXT frame as their first argument, receive a pointer to a "prologue
   3631 cache" as their second argument.  This can be used to store values
   3632 associated with a particular frame, for reuse on subsequent calls
   3633 involving the same frame.
   3634 
   3635    It is up to the user to define the structure used (it is a `void *'
   3636 pointer) and arrange allocation and deallocation of storage.  However
   3637 for general use, GDB provides `struct trad_frame_cache', with a set of
   3638 accessor routines.  This structure holds the stack and code address of
   3639 THIS frame, the base address of the frame, a pointer to the struct
   3640 `frame_info' for the NEXT frame and details of where the registers of
   3641 the PREVIOUS frame may be found in THIS frame.
   3642 
   3643    Typically the first time any sniffer function is called with NEXT
   3644 frame, the prologue sniffer for THIS frame will be `NULL'.  The sniffer
   3645 will analyze the frame, allocate a prologue cache structure and
   3646 populate it.  Subsequent calls using the same NEXT frame will pass in
   3647 this prologue cache, so the data can be returned with no additional
   3648 analysis.
   3649 
   3650 
   3651 File: gdbint.info,  Node: Functions and Variable to Analyze Frames,  Next: Functions to Access Frame Data,  Prev: Prologue Caches,  Up: Frame Interpretation
   3652 
   3653 11.7.4 Functions and Variable to Analyze Frames
   3654 -----------------------------------------------
   3655 
   3656 These struct `gdbarch' functions and variable should be defined to
   3657 provide analysis of the stack frame and allow it to be adjusted as
   3658 required.
   3659 
   3660  -- Architecture Function: CORE_ADDR skip_prologue (struct gdbarch
   3661           *GDBARCH, CORE_ADDR PC)
   3662      The prologue of a function is the code at the beginning of the
   3663      function which sets up the stack frame, saves the return address
   3664      etc.  The code representing the behavior of the function starts
   3665      after the prologue.
   3666 
   3667      This function skips past the prologue of a function if the program
   3668      counter, PC, is within the prologue of a function.  The result is
   3669      the program counter immediately after the prologue.  With modern
   3670      optimizing compilers, this may be a far from trivial exercise.
   3671      However the required information may be within the binary as
   3672      DWARF2 debugging information, making the job much easier.
   3673 
   3674      The default value is `NULL' (not defined).  This function should
   3675      always be provided, but can take advantage of DWARF2 debugging
   3676      information, if that is available.
   3677 
   3678 
   3679  -- Architecture Function: int inner_than (CORE_ADDR LHS, CORE_ADDR RHS)
   3680      Given two frame or stack pointers, return non-zero (true) if the
   3681      first represents the "inner" stack frame and 0 (false) otherwise.
   3682      This is used to determine whether the target has a stack which
   3683      grows up in memory (rising stack) or grows down in memory (falling
   3684      stack).  *Note All About Stack Frames: All About Stack Frames, for
   3685      an explanation of "inner" frames.
   3686 
   3687      The default value of this function is `NULL' and it should always
   3688      be defined.  However for almost all architectures one of the
   3689      built-in functions can be used: `core_addr_lessthan' (for stacks
   3690      growing down in memory) or `core_addr_greaterthan' (for stacks
   3691      growing up in memory).
   3692 
   3693 
   3694  -- Architecture Function: CORE_ADDR frame_align (struct gdbarch
   3695           *GDBARCH, CORE_ADDR ADDRESS)
   3696      The architecture may have constraints on how its frames are
   3697      aligned.  For example the OpenRISC 1000 ABI requires stack frames
   3698      to be double-word aligned, but 32-bit versions of the architecture
   3699      allocate single-word values to the stack.  Thus extra padding may
   3700      be needed at the end of a stack frame.
   3701 
   3702      Given a proposed address for the stack pointer, this function
   3703      returns a suitably aligned address (by expanding the stack frame).
   3704 
   3705      The default value is `NULL' (undefined).  This function should be
   3706      defined for any architecture where it is possible the stack could
   3707      become misaligned.  The utility functions `align_down' (for falling
   3708      stacks) and `align_up' (for rising stacks) will facilitate the
   3709      implementation of this function.
   3710 
   3711 
   3712  -- Architecture Variable: int frame_red_zone_size
   3713      Some ABIs reserve space beyond the end of the stack for use by leaf
   3714      functions without prologue or epilogue or by exception handlers
   3715      (for example the OpenRISC 1000).
   3716 
   3717      This is known as a "red zone" (AMD terminology).  The AMD64 (nee
   3718      x86-64) ABI documentation refers to the "red zone" when describing
   3719      this scratch area.
   3720 
   3721      The default value is 0.  Set this field if the architecture has
   3722      such a red zone.  The value must be aligned as required by the ABI
   3723      (see `frame_align' above for an explanation of stack frame
   3724      alignment).
   3725 
   3726 
   3727 
   3728 File: gdbint.info,  Node: Functions to Access Frame Data,  Next: Analyzing Stacks---Frame Sniffers,  Prev: Functions and Variable to Analyze Frames,  Up: Frame Interpretation
   3729 
   3730 11.7.5 Functions to Access Frame Data
   3731 -------------------------------------
   3732 
   3733 These functions provide access to key registers and arguments in the
   3734 stack frame.
   3735 
   3736  -- Architecture Function: CORE_ADDR unwind_pc (struct gdbarch
   3737           *GDBARCH, struct frame_info *NEXT_FRAME)
   3738      This function is given a pointer to the NEXT stack frame (*note
   3739      All About Stack Frames: All About Stack Frames, for how frames are
   3740      represented) and returns the value of the program counter in the
   3741      PREVIOUS frame (i.e. the frame of the function that called THIS
   3742      one).  This is commonly referred to as the "return address".
   3743 
   3744      The implementation, which must be frame agnostic (work with any
   3745      frame), is typically no more than:
   3746 
   3747           ULONGEST pc;
   3748           pc = frame_unwind_register_unsigned (next_frame, ARCH_PC_REGNUM);
   3749           return gdbarch_addr_bits_remove (gdbarch, pc);
   3750 
   3751 
   3752  -- Architecture Function: CORE_ADDR unwind_sp (struct gdbarch
   3753           *GDBARCH, struct frame_info *NEXT_FRAME)
   3754      This function is given a pointer to the NEXT stack frame (*note
   3755      All About Stack Frames: All About Stack Frames. for how frames are
   3756      represented) and returns the value of the stack pointer in the
   3757      PREVIOUS frame (i.e. the frame of the function that called THIS
   3758      one).
   3759 
   3760      The implementation, which must be frame agnostic (work with any
   3761      frame), is typically no more than:
   3762 
   3763           ULONGEST sp;
   3764           sp = frame_unwind_register_unsigned (next_frame, ARCH_SP_REGNUM);
   3765           return gdbarch_addr_bits_remove (gdbarch, sp);
   3766 
   3767 
   3768  -- Architecture Function: int frame_num_args (struct gdbarch *GDBARCH,
   3769           struct frame_info *THIS_FRAME)
   3770      This function is given a pointer to THIS stack frame (*note All
   3771      About Stack Frames: All About Stack Frames. for how frames are
   3772      represented), and returns the number of arguments that are being
   3773      passed, or -1 if not known.
   3774 
   3775      The default value is `NULL' (undefined), in which case the number
   3776      of arguments passed on any stack frame is always unknown.  For many
   3777      architectures this will be a suitable default.
   3778 
   3779 
   3780 
   3781 File: gdbint.info,  Node: Analyzing Stacks---Frame Sniffers,  Prev: Functions to Access Frame Data,  Up: Frame Interpretation
   3782 
   3783 11.7.6 Analyzing Stacks--Frame Sniffers
   3784 ---------------------------------------
   3785 
   3786 When a program stops, GDB needs to construct the chain of struct
   3787 `frame_info' representing the state of the stack using appropriate
   3788 "sniffers".
   3789 
   3790    Each architecture requires appropriate sniffers, but they do not form
   3791 entries in `struct gdbarch', since more than one sniffer may be
   3792 required and a sniffer may be suitable for more than one
   3793 `struct gdbarch'.  Instead sniffers are associated with architectures
   3794 using the following functions.
   3795 
   3796    * `frame_unwind_append_sniffer' is used to add a new sniffer to
   3797      analyze THIS frame when given a pointer to the NEXT frame.
   3798 
   3799    * `frame_base_append_sniffer' is used to add a new sniffer which can
   3800      determine information about the base of a stack frame.
   3801 
   3802    * `frame_base_set_default' is used to specify the default base
   3803      sniffer.
   3804 
   3805 
   3806    These functions all take a reference to `struct gdbarch', so they
   3807 are associated with a specific architecture.  They are usually called
   3808 in the `gdbarch' initialization function, after the `gdbarch' struct
   3809 has been set up.  Unless a default has been set, the most recently
   3810 appended sniffer will be tried first.
   3811 
   3812    The main frame unwinding sniffer (as set by
   3813 `frame_unwind_append_sniffer)' returns a structure specifying a set of
   3814 sniffing functions:
   3815 
   3816      struct frame_unwind
   3817      {
   3818         enum frame_type            type;
   3819         frame_this_id_ftype       *this_id;
   3820         frame_prev_register_ftype *prev_register;
   3821         const struct frame_data   *unwind_data;
   3822         frame_sniffer_ftype       *sniffer;
   3823         frame_prev_pc_ftype       *prev_pc;
   3824         frame_dealloc_cache_ftype *dealloc_cache;
   3825      };
   3826 
   3827    The `type' field indicates the type of frame this sniffer can
   3828 handle: normal, dummy (*note Functions Creating Dummy Frames: Functions
   3829 Creating Dummy Frames.), signal handler or sentinel.  Signal handlers
   3830 sometimes have their own simplified stack structure for efficiency, so
   3831 may need their own handlers.
   3832 
   3833    The `unwind_data' field holds additional information which may be
   3834 relevant to particular types of frame.  For example it may hold
   3835 additional information for signal handler frames.
   3836 
   3837    The remaining fields define functions that yield different types of
   3838 information when given a pointer to the NEXT stack frame.  Not all
   3839 functions need be provided.  If an entry is `NULL', the next sniffer
   3840 will be tried instead.
   3841 
   3842    * `this_id' determines the stack pointer and function (code entry
   3843      point) for THIS stack frame.
   3844 
   3845    * `prev_register' determines where the values of registers for the
   3846      PREVIOUS stack frame are stored in THIS stack frame.
   3847 
   3848    * `sniffer' takes a look at THIS frame's registers to determine if
   3849      this is the appropriate unwinder.
   3850 
   3851    * `prev_pc' determines the program counter for THIS frame.  Only
   3852      needed if the program counter is not an ordinary register (*note
   3853      Functions and Variables Specifying the Register Architecture:
   3854      Register Architecture Functions & Variables.).
   3855 
   3856    * `dealloc_cache' frees any additional memory associated with the
   3857      prologue cache for this frame (*note Prologue Caches: Prologue
   3858      Caches.).
   3859 
   3860 
   3861    In general it is only the `this_id' and `prev_register' fields that
   3862 need be defined for custom sniffers.
   3863 
   3864    The frame base sniffer is much simpler.  It is a
   3865 `struct frame_base', which refers to the corresponding `frame_unwind'
   3866 struct and whose fields refer to functions yielding various addresses
   3867 within the frame.
   3868 
   3869      struct frame_base
   3870      {
   3871         const struct frame_unwind *unwind;
   3872         frame_this_base_ftype     *this_base;
   3873         frame_this_locals_ftype   *this_locals;
   3874         frame_this_args_ftype     *this_args;
   3875      };
   3876 
   3877    All the functions referred to take a pointer to the NEXT frame as
   3878 argument. The function referred to by `this_base' returns the base
   3879 address of THIS frame, the function referred to by `this_locals'
   3880 returns the base address of local variables in THIS frame and the
   3881 function referred to by `this_args' returns the base address of the
   3882 function arguments in this frame.
   3883 
   3884    As described above, the base address of a frame is the address
   3885 immediately before the start of the NEXT frame.  For a falling stack,
   3886 this is the lowest address in the frame and for a rising stack it is
   3887 the highest address in the frame.  For most architectures the same
   3888 address is also the base address for local variables and arguments, in
   3889 which case the same function can be used for all three entries(1).
   3890 
   3891    ---------- Footnotes ----------
   3892 
   3893    (1) It is worth noting that if it cannot be determined in any other
   3894 way (for example by there being a register with the name `"fp"'), then
   3895 the result of the `this_base' function will be used as the value of the
   3896 frame pointer variable `$fp' in GDB.  This is very often not correct
   3897 (for example with the OpenRISC 1000, this value is the stack pointer,
   3898 `$sp').  In this case a register (raw or pseudo) with the name `"fp"'
   3899 should be defined.  It will be used in preference as the value of `$fp'.
   3900 
   3901 
   3902 File: gdbint.info,  Node: Inferior Call Setup,  Next: Adding support for debugging core files,  Prev: Frame Interpretation,  Up: Target Architecture Definition
   3903 
   3904 11.8 Inferior Call Setup
   3905 ========================
   3906 
   3907 * Menu:
   3908 
   3909 * About Dummy Frames::
   3910 * Functions Creating Dummy Frames::
   3911 
   3912 
   3913 File: gdbint.info,  Node: About Dummy Frames,  Next: Functions Creating Dummy Frames,  Up: Inferior Call Setup
   3914 
   3915 11.8.1 About Dummy Frames
   3916 -------------------------
   3917 
   3918 GDB can call functions in the target code (for example by using the
   3919 `call' or `print' commands).  These functions may be breakpointed, and
   3920 it is essential that if a function does hit a breakpoint, commands like
   3921 `backtrace' work correctly.
   3922 
   3923    This is achieved by making the stack look as though the function had
   3924 been called from the point where GDB had previously stopped.  This
   3925 requires that GDB can set up stack frames appropriate for such function
   3926 calls.
   3927 
   3928 
   3929 File: gdbint.info,  Node: Functions Creating Dummy Frames,  Prev: About Dummy Frames,  Up: Inferior Call Setup
   3930 
   3931 11.8.2 Functions Creating Dummy Frames
   3932 --------------------------------------
   3933 
   3934 The following functions provide the functionality to set up such
   3935 "dummy" stack frames.
   3936 
   3937  -- Architecture Function: CORE_ADDR push_dummy_call (struct gdbarch
   3938           *GDBARCH, struct value *FUNCTION, struct regcache *REGCACHE,
   3939           CORE_ADDR BP_ADDR, int NARGS, struct value **ARGS, CORE_ADDR
   3940           SP, int STRUCT_RETURN, CORE_ADDR STRUCT_ADDR)
   3941      This function sets up a dummy stack frame for the function about
   3942      to be called.  `push_dummy_call' is given the arguments to be
   3943      passed and must copy them into registers or push them on to the
   3944      stack as appropriate for the ABI.
   3945 
   3946      FUNCTION is a pointer to the function that will be called and
   3947      REGCACHE the register cache from which values should be obtained.
   3948      BP_ADDR is the address to which the function should return (which
   3949      is breakpointed, so GDB can regain control, hence the name).
   3950      NARGS is the number of arguments to pass and ARGS an array
   3951      containing the argument values.  STRUCT_RETURN is non-zero (true)
   3952      if the function returns a structure, and if so STRUCT_ADDR is the
   3953      address in which the structure should be returned.
   3954 
   3955      After calling this function, GDB will pass control to the target
   3956      at the address of the function, which will find the stack and
   3957      registers set up just as expected.
   3958 
   3959      The default value of this function is `NULL' (undefined).  If the
   3960      function is not defined, then GDB will not allow the user to call
   3961      functions within the target being debugged.
   3962 
   3963 
   3964  -- Architecture Function: struct frame_id unwind_dummy_id (struct
   3965           gdbarch *GDBARCH, struct frame_info *NEXT_FRAME)
   3966      This is the inverse of `push_dummy_call' which restores the stack
   3967      pointer and program counter after a call to evaluate a function
   3968      using a dummy stack frame.  The result is a `struct frame_id',
   3969      which contains the value of the stack pointer and program counter
   3970      to be used.
   3971 
   3972      The NEXT frame pointer is provided as argument, NEXT_FRAME.  THIS
   3973      frame is the frame of the dummy function, which can be unwound, to
   3974      yield the required stack pointer and program counter from the
   3975      PREVIOUS frame.
   3976 
   3977      The default value is `NULL' (undefined).  If `push_dummy_call' is
   3978      defined, then this function should also be defined.
   3979 
   3980 
   3981  -- Architecture Function: CORE_ADDR push_dummy_code (struct gdbarch
   3982           *GDBARCH, CORE_ADDR SP, CORE_ADDR FUNADDR, struct value
   3983           **ARGS, int NARGS, struct type *VALUE_TYPE, CORE_ADDR
   3984           *REAL_PC, CORE_ADDR *BP_ADDR, struct regcache *REGCACHE)
   3985      If this function is not defined (its default value is `NULL'), a
   3986      dummy call will use the entry point of the currently loaded code
   3987      on the target as its return address.  A temporary breakpoint will
   3988      be set there, so the location must be writable and have room for a
   3989      breakpoint.
   3990 
   3991      It is possible that this default is not suitable.  It might not be
   3992      writable (in ROM possibly), or the ABI might require code to be
   3993      executed on return from a call to unwind the stack before the
   3994      breakpoint is encountered.
   3995 
   3996      If either of these is the case, then push_dummy_code should be
   3997      defined to push an instruction sequence onto the end of the stack
   3998      to which the dummy call should return.
   3999 
   4000      The arguments are essentially the same as those to
   4001      `push_dummy_call'.  However the function is provided with the type
   4002      of the function result, VALUE_TYPE, BP_ADDR is used to return a
   4003      value (the address at which the breakpoint instruction should be
   4004      inserted) and REAL PC is used to specify the resume address when
   4005      starting the call sequence.  The function should return the
   4006      updated innermost stack address.
   4007 
   4008           _Note:_ This does require that code in the stack can be
   4009           executed.  Some Harvard architectures may not allow this.
   4010 
   4011 
   4012 
   4013 File: gdbint.info,  Node: Adding support for debugging core files,  Next: Defining Other Architecture Features,  Prev: Inferior Call Setup,  Up: Target Architecture Definition
   4014 
   4015 11.9 Adding support for debugging core files
   4016 ============================================
   4017 
   4018 The prerequisite for adding core file support in GDB is to have core
   4019 file support in BFD.
   4020 
   4021    Once BFD support is available, writing the apropriate
   4022 `regset_from_core_section' architecture function should be all that is
   4023 needed in order to add support for core files in GDB.
   4024 
   4025 
   4026 File: gdbint.info,  Node: Defining Other Architecture Features,  Next: Adding a New Target,  Prev: Adding support for debugging core files,  Up: Target Architecture Definition
   4027 
   4028 11.10 Defining Other Architecture Features
   4029 ==========================================
   4030 
   4031 This section describes other functions and values in `gdbarch',
   4032 together with some useful macros, that you can use to define the target
   4033 architecture.
   4034 
   4035 `CORE_ADDR gdbarch_addr_bits_remove (GDBARCH, ADDR)'
   4036      If a raw machine instruction address includes any bits that are not
   4037      really part of the address, then this function is used to zero
   4038      those bits in ADDR.  This is only used for addresses of
   4039      instructions, and even then not in all contexts.
   4040 
   4041      For example, the two low-order bits of the PC on the
   4042      Hewlett-Packard PA 2.0 architecture contain the privilege level of
   4043      the corresponding instruction.  Since instructions must always be
   4044      aligned on four-byte boundaries, the processor masks out these
   4045      bits to generate the actual address of the instruction.
   4046      `gdbarch_addr_bits_remove' would then for example look like that:
   4047           arch_addr_bits_remove (CORE_ADDR addr)
   4048           {
   4049             return (addr &= ~0x3);
   4050           }
   4051 
   4052 `int address_class_name_to_type_flags (GDBARCH, NAME, TYPE_FLAGS_PTR)'
   4053      If NAME is a valid address class qualifier name, set the `int'
   4054      referenced by TYPE_FLAGS_PTR to the mask representing the qualifier
   4055      and return 1.  If NAME is not a valid address class qualifier name,
   4056      return 0.
   4057 
   4058      The value for TYPE_FLAGS_PTR should be one of
   4059      `TYPE_FLAG_ADDRESS_CLASS_1', `TYPE_FLAG_ADDRESS_CLASS_2', or
   4060      possibly some combination of these values or'd together.  *Note
   4061      Address Classes: Target Architecture Definition.
   4062 
   4063 `int address_class_name_to_type_flags_p (GDBARCH)'
   4064      Predicate which indicates whether
   4065      `address_class_name_to_type_flags' has been defined.
   4066 
   4067 `int gdbarch_address_class_type_flags (GDBARCH, BYTE_SIZE, DWARF2_ADDR_CLASS)'
   4068      Given a pointers byte size (as described by the debug information)
   4069      and the possible `DW_AT_address_class' value, return the type flags
   4070      used by GDB to represent this address class.  The value returned
   4071      should be one of `TYPE_FLAG_ADDRESS_CLASS_1',
   4072      `TYPE_FLAG_ADDRESS_CLASS_2', or possibly some combination of these
   4073      values or'd together.  *Note Address Classes: Target Architecture
   4074      Definition.
   4075 
   4076 `int gdbarch_address_class_type_flags_p (GDBARCH)'
   4077      Predicate which indicates whether
   4078      `gdbarch_address_class_type_flags_p' has been defined.
   4079 
   4080 `const char *gdbarch_address_class_type_flags_to_name (GDBARCH, TYPE_FLAGS)'
   4081      Return the name of the address class qualifier associated with the
   4082      type flags given by TYPE_FLAGS.
   4083 
   4084 `int gdbarch_address_class_type_flags_to_name_p (GDBARCH)'
   4085      Predicate which indicates whether
   4086      `gdbarch_address_class_type_flags_to_name' has been defined.
   4087      *Note Address Classes: Target Architecture Definition.
   4088 
   4089 `void gdbarch_address_to_pointer (GDBARCH, TYPE, BUF, ADDR)'
   4090      Store in BUF a pointer of type TYPE representing the address ADDR,
   4091      in the appropriate format for the current architecture.  This
   4092      function may safely assume that TYPE is either a pointer or a C++
   4093      reference type.  *Note Pointers Are Not Always Addresses: Target
   4094      Architecture Definition.
   4095 
   4096 `int gdbarch_believe_pcc_promotion (GDBARCH)'
   4097      Used to notify if the compiler promotes a `short' or `char'
   4098      parameter to an `int', but still reports the parameter as its
   4099      original type, rather than the promoted type.
   4100 
   4101 `gdbarch_bits_big_endian (GDBARCH)'
   4102      This is used if the numbering of bits in the targets does *not*
   4103      match the endianism of the target byte order.  A value of 1 means
   4104      that the bits are numbered in a big-endian bit order, 0 means
   4105      little-endian.
   4106 
   4107 `set_gdbarch_bits_big_endian (GDBARCH, BITS_BIG_ENDIAN)'
   4108      Calling set_gdbarch_bits_big_endian with a value of 1 indicates
   4109      that the bits in the target are numbered in a big-endian bit
   4110      order, 0 indicates little-endian.
   4111 
   4112 `BREAKPOINT'
   4113      This is the character array initializer for the bit pattern to put
   4114      into memory where a breakpoint is set.  Although it's common to
   4115      use a trap instruction for a breakpoint, it's not required; for
   4116      instance, the bit pattern could be an invalid instruction.  The
   4117      breakpoint must be no longer than the shortest instruction of the
   4118      architecture.
   4119 
   4120      `BREAKPOINT' has been deprecated in favor of
   4121      `gdbarch_breakpoint_from_pc'.
   4122 
   4123 `BIG_BREAKPOINT'
   4124 `LITTLE_BREAKPOINT'
   4125      Similar to BREAKPOINT, but used for bi-endian targets.
   4126 
   4127      `BIG_BREAKPOINT' and `LITTLE_BREAKPOINT' have been deprecated in
   4128      favor of `gdbarch_breakpoint_from_pc'.
   4129 
   4130 `const gdb_byte *gdbarch_breakpoint_from_pc (GDBARCH, PCPTR, LENPTR)'
   4131      Use the program counter to determine the contents and size of a
   4132      breakpoint instruction.  It returns a pointer to a static string
   4133      of bytes that encode a breakpoint instruction, stores the length
   4134      of the string to `*LENPTR', and adjusts the program counter (if
   4135      necessary) to point to the actual memory location where the
   4136      breakpoint should be inserted.  May return `NULL' to indicate that
   4137      software breakpoints are not supported.
   4138 
   4139      Although it is common to use a trap instruction for a breakpoint,
   4140      it's not required; for instance, the bit pattern could be an
   4141      invalid instruction.  The breakpoint must be no longer than the
   4142      shortest instruction of the architecture.
   4143 
   4144      Provided breakpoint bytes can be also used by
   4145      `bp_loc_is_permanent' to detect permanent breakpoints.
   4146      `gdbarch_breakpoint_from_pc' should return an unchanged memory
   4147      copy if it was called for a location with permanent breakpoint as
   4148      some architectures use breakpoint instructions containing
   4149      arbitrary parameter value.
   4150 
   4151      Replaces all the other BREAKPOINT macros.
   4152 
   4153 `int gdbarch_memory_insert_breakpoint (GDBARCH, BP_TGT)'
   4154 `gdbarch_memory_remove_breakpoint (GDBARCH, BP_TGT)'
   4155      Insert or remove memory based breakpoints.  Reasonable defaults
   4156      (`default_memory_insert_breakpoint' and
   4157      `default_memory_remove_breakpoint' respectively) have been
   4158      provided so that it is not necessary to set these for most
   4159      architectures.  Architectures which may want to set
   4160      `gdbarch_memory_insert_breakpoint' and
   4161      `gdbarch_memory_remove_breakpoint' will likely have instructions
   4162      that are oddly sized or are not stored in a conventional manner.
   4163 
   4164      It may also be desirable (from an efficiency standpoint) to define
   4165      custom breakpoint insertion and removal routines if
   4166      `gdbarch_breakpoint_from_pc' needs to read the target's memory for
   4167      some reason.
   4168 
   4169 `CORE_ADDR gdbarch_adjust_breakpoint_address (GDBARCH, BPADDR)'
   4170      Given an address at which a breakpoint is desired, return a
   4171      breakpoint address adjusted to account for architectural
   4172      constraints on breakpoint placement.  This method is not needed by
   4173      most targets.
   4174 
   4175      The FR-V target (see `frv-tdep.c') requires this method.  The FR-V
   4176      is a VLIW architecture in which a number of RISC-like instructions
   4177      are grouped (packed) together into an aggregate instruction or
   4178      instruction bundle.  When the processor executes one of these
   4179      bundles, the component instructions are executed in parallel.
   4180 
   4181      In the course of optimization, the compiler may group instructions
   4182      from distinct source statements into the same bundle.  The line
   4183      number information associated with one of the latter statements
   4184      will likely refer to some instruction other than the first one in
   4185      the bundle.  So, if the user attempts to place a breakpoint on one
   4186      of these latter statements, GDB must be careful to _not_ place the
   4187      break instruction on any instruction other than the first one in
   4188      the bundle.  (Remember though that the instructions within a
   4189      bundle execute in parallel, so the _first_ instruction is the
   4190      instruction at the lowest address and has nothing to do with
   4191      execution order.)
   4192 
   4193      The FR-V's `gdbarch_adjust_breakpoint_address' method will adjust a
   4194      breakpoint's address by scanning backwards for the beginning of
   4195      the bundle, returning the address of the bundle.
   4196 
   4197      Since the adjustment of a breakpoint may significantly alter a
   4198      user's expectation, GDB prints a warning when an adjusted
   4199      breakpoint is initially set and each time that that breakpoint is
   4200      hit.
   4201 
   4202 `int gdbarch_call_dummy_location (GDBARCH)'
   4203      See the file `inferior.h'.
   4204 
   4205      This method has been replaced by `gdbarch_push_dummy_code' (*note
   4206      gdbarch_push_dummy_code::).
   4207 
   4208 `int gdbarch_cannot_fetch_register (GDBARCH, REGUM)'
   4209      This function should return nonzero if REGNO cannot be fetched
   4210      from an inferior process.
   4211 
   4212 `int gdbarch_cannot_store_register (GDBARCH, REGNUM)'
   4213      This function should return nonzero if REGNO should not be written
   4214      to the target.  This is often the case for program counters,
   4215      status words, and other special registers.  This function returns
   4216      0 as default so that GDB will assume that all registers may be
   4217      written.
   4218 
   4219 `int gdbarch_convert_register_p (GDBARCH, REGNUM, struct type *TYPE)'
   4220      Return non-zero if register REGNUM represents data values of type
   4221      TYPE in a non-standard form.  *Note Using Different Register and
   4222      Memory Data Representations: Target Architecture Definition.
   4223 
   4224 `int gdbarch_fp0_regnum (GDBARCH)'
   4225      This function returns the number of the first floating point
   4226      register, if the machine has such registers.  Otherwise, it
   4227      returns -1.
   4228 
   4229 `CORE_ADDR gdbarch_decr_pc_after_break (GDBARCH)'
   4230      This function shall return the amount by which to decrement the PC
   4231      after the program encounters a breakpoint.  This is often the
   4232      number of bytes in `BREAKPOINT', though not always.  For most
   4233      targets this value will be 0.
   4234 
   4235 `DISABLE_UNSETTABLE_BREAK (ADDR)'
   4236      If defined, this should evaluate to 1 if ADDR is in a shared
   4237      library in which breakpoints cannot be set and so should be
   4238      disabled.
   4239 
   4240 `int gdbarch_dwarf2_reg_to_regnum (GDBARCH, DWARF2_REGNR)'
   4241      Convert DWARF2 register number DWARF2_REGNR into GDB regnum.  If
   4242      not defined, no conversion will be performed.
   4243 
   4244 `int gdbarch_ecoff_reg_to_regnum (GDBARCH, ECOFF_REGNR)'
   4245      Convert ECOFF register number  ECOFF_REGNR into GDB regnum.  If
   4246      not defined, no conversion will be performed.
   4247 
   4248 `GCC_COMPILED_FLAG_SYMBOL'
   4249 `GCC2_COMPILED_FLAG_SYMBOL'
   4250      If defined, these are the names of the symbols that GDB will look
   4251      for to detect that GCC compiled the file.  The default symbols are
   4252      `gcc_compiled.' and `gcc2_compiled.', respectively.  (Currently
   4253      only defined for the Delta 68.)
   4254 
   4255 `gdbarch_get_longjmp_target'
   4256      This function determines the target PC address that `longjmp' will
   4257      jump to, assuming that we have just stopped at a `longjmp'
   4258      breakpoint.  It takes a `CORE_ADDR *' as argument, and stores the
   4259      target PC value through this pointer.  It examines the current
   4260      state of the machine as needed, typically by using a
   4261      manually-determined offset into the `jmp_buf'.  (While we might
   4262      like to get the offset from the target's `jmpbuf.h', that header
   4263      file cannot be assumed to be available when building a
   4264      cross-debugger.)
   4265 
   4266 `DEPRECATED_IBM6000_TARGET'
   4267      Shows that we are configured for an IBM RS/6000 system.  This
   4268      conditional should be eliminated (FIXME) and replaced by
   4269      feature-specific macros.  It was introduced in haste and we are
   4270      repenting at leisure.
   4271 
   4272 `I386_USE_GENERIC_WATCHPOINTS'
   4273      An x86-based target can define this to use the generic x86
   4274      watchpoint support; see *note I386_USE_GENERIC_WATCHPOINTS:
   4275      Algorithms.
   4276 
   4277 `gdbarch_in_function_epilogue_p (GDBARCH, ADDR)'
   4278      Returns non-zero if the given ADDR is in the epilogue of a
   4279      function.  The epilogue of a function is defined as the part of a
   4280      function where the stack frame of the function already has been
   4281      destroyed up to the final `return from function call' instruction.
   4282 
   4283 `int gdbarch_in_solib_return_trampoline (GDBARCH, PC, NAME)'
   4284      Define this function to return nonzero if the program is stopped
   4285      in the trampoline that returns from a shared library.
   4286 
   4287 `target_so_ops.in_dynsym_resolve_code (PC)'
   4288      Define this to return nonzero if the program is stopped in the
   4289      dynamic linker.
   4290 
   4291 `SKIP_SOLIB_RESOLVER (PC)'
   4292      Define this to evaluate to the (nonzero) address at which execution
   4293      should continue to get past the dynamic linker's symbol resolution
   4294      function.  A zero value indicates that it is not important or
   4295      necessary to set a breakpoint to get through the dynamic linker
   4296      and that single stepping will suffice.
   4297 
   4298 `CORE_ADDR gdbarch_integer_to_address (GDBARCH, TYPE, BUF)'
   4299      Define this when the architecture needs to handle non-pointer to
   4300      address conversions specially.  Converts that value to an address
   4301      according to the current architectures conventions.
   4302 
   4303      _Pragmatics: When the user copies a well defined expression from
   4304      their source code and passes it, as a parameter, to GDB's `print'
   4305      command, they should get the same value as would have been
   4306      computed by the target program.  Any deviation from this rule can
   4307      cause major confusion and annoyance, and needs to be justified
   4308      carefully.  In other words, GDB doesn't really have the freedom to
   4309      do these conversions in clever and useful ways.  It has, however,
   4310      been pointed out that users aren't complaining about how GDB casts
   4311      integers to pointers; they are complaining that they can't take an
   4312      address from a disassembly listing and give it to `x/i'.  Adding
   4313      an architecture method like `gdbarch_integer_to_address' certainly
   4314      makes it possible for GDB to "get it right" in all circumstances._
   4315 
   4316      *Note Pointers Are Not Always Addresses: Target Architecture
   4317      Definition.
   4318 
   4319 `CORE_ADDR gdbarch_pointer_to_address (GDBARCH, TYPE, BUF)'
   4320      Assume that BUF holds a pointer of type TYPE, in the appropriate
   4321      format for the current architecture.  Return the byte address the
   4322      pointer refers to.  *Note Pointers Are Not Always Addresses:
   4323      Target Architecture Definition.
   4324 
   4325 `void gdbarch_register_to_value(GDBARCH, FRAME, REGNUM, TYPE, FUR)'
   4326      Convert the raw contents of register REGNUM into a value of type
   4327      TYPE.  *Note Using Different Register and Memory Data
   4328      Representations: Target Architecture Definition.
   4329 
   4330 `REGISTER_CONVERT_TO_VIRTUAL(REG, TYPE, FROM, TO)'
   4331      Convert the value of register REG from its raw form to its virtual
   4332      form.  *Note Raw and Virtual Register Representations: Target
   4333      Architecture Definition.
   4334 
   4335 `REGISTER_CONVERT_TO_RAW(TYPE, REG, FROM, TO)'
   4336      Convert the value of register REG from its virtual form to its raw
   4337      form.  *Note Raw and Virtual Register Representations: Target
   4338      Architecture Definition.
   4339 
   4340 `const struct regset *regset_from_core_section (struct gdbarch * GDBARCH, const char * SECT_NAME, size_t SECT_SIZE)'
   4341      Return the appropriate register set for a core file section with
   4342      name SECT_NAME and size SECT_SIZE.
   4343 
   4344 `SOFTWARE_SINGLE_STEP_P()'
   4345      Define this as 1 if the target does not have a hardware single-step
   4346      mechanism.  The macro `SOFTWARE_SINGLE_STEP' must also be defined.
   4347 
   4348 `SOFTWARE_SINGLE_STEP(SIGNAL, INSERT_BREAKPOINTS_P)'
   4349      A function that inserts or removes (depending on
   4350      INSERT_BREAKPOINTS_P) breakpoints at each possible destinations of
   4351      the next instruction.  See `sparc-tdep.c' and `rs6000-tdep.c' for
   4352      examples.
   4353 
   4354 `set_gdbarch_sofun_address_maybe_missing (GDBARCH, SET)'
   4355      Somebody clever observed that, the more actual addresses you have
   4356      in the debug information, the more time the linker has to spend
   4357      relocating them.  So whenever there's some other way the debugger
   4358      could find the address it needs, you should omit it from the debug
   4359      info, to make linking faster.
   4360 
   4361      Calling `set_gdbarch_sofun_address_maybe_missing' with a non-zero
   4362      argument SET indicates that a particular set of hacks of this sort
   4363      are in use, affecting `N_SO' and `N_FUN' entries in stabs-format
   4364      debugging information.  `N_SO' stabs mark the beginning and ending
   4365      addresses of compilation units in the text segment.  `N_FUN' stabs
   4366      mark the starts and ends of functions.
   4367 
   4368      In this case, GDB assumes two things:
   4369 
   4370         * `N_FUN' stabs have an address of zero.  Instead of using those
   4371           addresses, you should find the address where the function
   4372           starts by taking the function name from the stab, and then
   4373           looking that up in the minsyms (the linker/assembler symbol
   4374           table).  In other words, the stab has the name, and the
   4375           linker/assembler symbol table is the only place that carries
   4376           the address.
   4377 
   4378         * `N_SO' stabs have an address of zero, too.  You just look at
   4379           the `N_FUN' stabs that appear before and after the `N_SO'
   4380           stab, and guess the starting and ending addresses of the
   4381           compilation unit from them.
   4382 
   4383 `int gdbarch_stabs_argument_has_addr (GDBARCH, TYPE)'
   4384      Define this function to return nonzero if a function argument of
   4385      type TYPE is passed by reference instead of value.
   4386 
   4387 `CORE_ADDR gdbarch_push_dummy_call (GDBARCH, FUNCTION, REGCACHE, BP_ADDR, NARGS, ARGS, SP, STRUCT_RETURN, STRUCT_ADDR)'
   4388      Define this to push the dummy frame's call to the inferior
   4389      function onto the stack.  In addition to pushing NARGS, the code
   4390      should push STRUCT_ADDR (when STRUCT_RETURN is non-zero), and the
   4391      return address (BP_ADDR).
   4392 
   4393      FUNCTION is a pointer to a `struct value'; on architectures that
   4394      use function descriptors, this contains the function descriptor
   4395      value.
   4396 
   4397      Returns the updated top-of-stack pointer.
   4398 
   4399 `CORE_ADDR gdbarch_push_dummy_code (GDBARCH, SP, FUNADDR, USING_GCC, ARGS, NARGS, VALUE_TYPE, REAL_PC, BP_ADDR, REGCACHE)'
   4400      Given a stack based call dummy, push the instruction sequence
   4401      (including space for a breakpoint) to which the called function
   4402      should return.
   4403 
   4404      Set BP_ADDR to the address at which the breakpoint instruction
   4405      should be inserted, REAL_PC to the resume address when starting
   4406      the call sequence, and return the updated inner-most stack address.
   4407 
   4408      By default, the stack is grown sufficient to hold a frame-aligned
   4409      (*note frame_align::) breakpoint, BP_ADDR is set to the address
   4410      reserved for that breakpoint, and REAL_PC set to FUNADDR.
   4411 
   4412      This method replaces `gdbarch_call_dummy_location (GDBARCH)'.
   4413 
   4414 `int gdbarch_sdb_reg_to_regnum (GDBARCH, SDB_REGNR)'
   4415      Use this function to convert sdb register SDB_REGNR into GDB
   4416      regnum.  If not defined, no conversion will be done.
   4417 
   4418 `enum return_value_convention gdbarch_return_value (struct gdbarch *GDBARCH, struct type *VALTYPE, struct regcache *REGCACHE, void *READBUF, const void *WRITEBUF)'
   4419      Given a function with a return-value of type RETTYPE, return which
   4420      return-value convention that function would use.
   4421 
   4422      GDB currently recognizes two function return-value conventions:
   4423      `RETURN_VALUE_REGISTER_CONVENTION' where the return value is found
   4424      in registers; and `RETURN_VALUE_STRUCT_CONVENTION' where the return
   4425      value is found in memory and the address of that memory location is
   4426      passed in as the function's first parameter.
   4427 
   4428      If the register convention is being used, and WRITEBUF is
   4429      non-`NULL', also copy the return-value in WRITEBUF into REGCACHE.
   4430 
   4431      If the register convention is being used, and READBUF is
   4432      non-`NULL', also copy the return value from REGCACHE into READBUF
   4433      (REGCACHE contains a copy of the registers from the just returned
   4434      function).
   4435 
   4436      _Maintainer note: This method replaces separate predicate, extract,
   4437      store methods.  By having only one method, the logic needed to
   4438      determine the return-value convention need only be implemented in
   4439      one place.  If GDB were written in an OO language, this method
   4440      would instead return an object that knew how to perform the
   4441      register return-value extract and store._
   4442 
   4443      _Maintainer note: This method does not take a GCC_P parameter, and
   4444      such a parameter should not be added.  If an architecture that
   4445      requires per-compiler or per-function information be identified,
   4446      then the replacement of RETTYPE with `struct value' FUNCTION
   4447      should be pursued._
   4448 
   4449      _Maintainer note: The REGCACHE parameter limits this methods to
   4450      the inner most frame.  While replacing REGCACHE with a `struct
   4451      frame_info' FRAME parameter would remove that limitation there has
   4452      yet to be a demonstrated need for such a change._
   4453 
   4454 `void gdbarch_skip_permanent_breakpoint (GDBARCH, REGCACHE)'
   4455      Advance the inferior's PC past a permanent breakpoint.  GDB
   4456      normally steps over a breakpoint by removing it, stepping one
   4457      instruction, and re-inserting the breakpoint.  However, permanent
   4458      breakpoints are hardwired into the inferior, and can't be removed,
   4459      so this strategy doesn't work.  Calling
   4460      `gdbarch_skip_permanent_breakpoint' adjusts the processor's state
   4461      so that execution will resume just after the breakpoint.  This
   4462      function does the right thing even when the breakpoint is in the
   4463      delay slot of a branch or jump.
   4464 
   4465 `CORE_ADDR gdbarch_skip_trampoline_code (GDBARCH, FRAME, PC)'
   4466      If the target machine has trampoline code that sits between
   4467      callers and the functions being called, then define this function
   4468      to return a new PC that is at the start of the real function.
   4469 
   4470 `int gdbarch_deprecated_fp_regnum (GDBARCH)'
   4471      If the frame pointer is in a register, use this function to return
   4472      the number of that register.
   4473 
   4474 `int gdbarch_stab_reg_to_regnum (GDBARCH, STAB_REGNR)'
   4475      Use this function to convert stab register STAB_REGNR into GDB
   4476      regnum.  If not defined, no conversion will be done.
   4477 
   4478 `SYMBOL_RELOADING_DEFAULT'
   4479      The default value of the "symbol-reloading" variable.  (Never
   4480      defined in current sources.)
   4481 
   4482 `TARGET_CHAR_BIT'
   4483      Number of bits in a char; defaults to 8.
   4484 
   4485 `int gdbarch_char_signed (GDBARCH)'
   4486      Non-zero if `char' is normally signed on this architecture; zero if
   4487      it should be unsigned.
   4488 
   4489      The ISO C standard requires the compiler to treat `char' as
   4490      equivalent to either `signed char' or `unsigned char'; any
   4491      character in the standard execution set is supposed to be positive.
   4492      Most compilers treat `char' as signed, but `char' is unsigned on
   4493      the IBM S/390, RS6000, and PowerPC targets.
   4494 
   4495 `int gdbarch_double_bit (GDBARCH)'
   4496      Number of bits in a double float; defaults to
   4497      `8 * TARGET_CHAR_BIT'.
   4498 
   4499 `int gdbarch_float_bit (GDBARCH)'
   4500      Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'.
   4501 
   4502 `int gdbarch_int_bit (GDBARCH)'
   4503      Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'.
   4504 
   4505 `int gdbarch_long_bit (GDBARCH)'
   4506      Number of bits in a long integer; defaults to
   4507      `4 * TARGET_CHAR_BIT'.
   4508 
   4509 `int gdbarch_long_double_bit (GDBARCH)'
   4510      Number of bits in a long double float; defaults to
   4511      `2 * gdbarch_double_bit (GDBARCH)'.
   4512 
   4513 `int gdbarch_long_long_bit (GDBARCH)'
   4514      Number of bits in a long long integer; defaults to
   4515      `2 * gdbarch_long_bit (GDBARCH)'.
   4516 
   4517 `int gdbarch_ptr_bit (GDBARCH)'
   4518      Number of bits in a pointer; defaults to
   4519      `gdbarch_int_bit (GDBARCH)'.
   4520 
   4521 `int gdbarch_short_bit (GDBARCH)'
   4522      Number of bits in a short integer; defaults to
   4523      `2 * TARGET_CHAR_BIT'.
   4524 
   4525 `void gdbarch_virtual_frame_pointer (GDBARCH, PC, FRAME_REGNUM, FRAME_OFFSET)'
   4526      Returns a `(REGISTER, OFFSET)' pair representing the virtual frame
   4527      pointer in use at the code address PC.  If virtual frame pointers
   4528      are not used, a default definition simply returns
   4529      `gdbarch_deprecated_fp_regnum' (or `gdbarch_sp_regnum', if no
   4530      frame pointer is defined), with an offset of zero.
   4531 
   4532 `TARGET_HAS_HARDWARE_WATCHPOINTS'
   4533      If non-zero, the target has support for hardware-assisted
   4534      watchpoints.  *Note watchpoints: Algorithms, for more details and
   4535      other related macros.
   4536 
   4537 `int gdbarch_print_insn (GDBARCH, VMA, INFO)'
   4538      This is the function used by GDB to print an assembly instruction.
   4539      It prints the instruction at address VMA in debugged memory and
   4540      returns the length of the instruction, in bytes.  This usually
   4541      points to a function in the `opcodes' library (*note Opcodes:
   4542      Support Libraries.).  INFO is a structure (of type
   4543      `disassemble_info') defined in the header file
   4544      `include/dis-asm.h', and used to pass information to the
   4545      instruction decoding routine.
   4546 
   4547 `frame_id gdbarch_dummy_id (GDBARCH, FRAME)'
   4548      Given FRAME return a `struct frame_id' that uniquely identifies an
   4549      inferior function call's dummy frame.  The value returned must
   4550      match the dummy frame stack value previously saved by
   4551      `call_function_by_hand'.
   4552 
   4553 `void gdbarch_value_to_register (GDBARCH, FRAME, TYPE, BUF)'
   4554      Convert a value of type TYPE into the raw contents of a register.
   4555      *Note Using Different Register and Memory Data Representations:
   4556      Target Architecture Definition.
   4557 
   4558 
   4559    Motorola M68K target conditionals.
   4560 
   4561 `BPT_VECTOR'
   4562      Define this to be the 4-bit location of the breakpoint trap
   4563      vector.  If not defined, it will default to `0xf'.
   4564 
   4565 `REMOTE_BPT_VECTOR'
   4566      Defaults to `1'.
   4567 
   4568 
   4569 
   4570 File: gdbint.info,  Node: Adding a New Target,  Prev: Defining Other Architecture Features,  Up: Target Architecture Definition
   4571 
   4572 11.11 Adding a New Target
   4573 =========================
   4574 
   4575 The following files add a target to GDB:
   4576 
   4577 `gdb/TTT-tdep.c'
   4578      Contains any miscellaneous code required for this target machine.
   4579      On some machines it doesn't exist at all.
   4580 
   4581 `gdb/ARCH-tdep.c'
   4582 `gdb/ARCH-tdep.h'
   4583      This is required to describe the basic layout of the target
   4584      machine's processor chip (registers, stack, etc.).  It can be
   4585      shared among many targets that use the same processor architecture.
   4586 
   4587 
   4588    (Target header files such as `gdb/config/ARCH/tm-TTT.h',
   4589 `gdb/config/ARCH/tm-ARCH.h', and `config/tm-OS.h' are no longer used.)
   4590 
   4591    A GDB description for a new architecture, arch is created by
   4592 defining a global function `_initialize_ARCH_tdep', by convention in
   4593 the source file `ARCH-tdep.c'.  For example, in the case of the
   4594 OpenRISC 1000, this function is called `_initialize_or1k_tdep' and is
   4595 found in the file `or1k-tdep.c'.
   4596 
   4597    The object file resulting from compiling this source file, which will
   4598 contain the implementation of the `_initialize_ARCH_tdep' function is
   4599 specified in the GDB `configure.tgt' file, which includes a large case
   4600 statement pattern matching against the `--target' option of the
   4601 `configure' script.
   4602 
   4603      _Note:_ If the architecture requires multiple source files, the
   4604      corresponding binaries should be included in `configure.tgt'.
   4605      However if there are header files, the dependencies on these will
   4606      not be picked up from the entries in `configure.tgt'. The
   4607      `Makefile.in' file will need extending to show these dependencies.
   4608 
   4609    A new struct gdbarch, defining the new architecture, is created
   4610 within the `_initialize_ARCH_tdep' function by calling
   4611 `gdbarch_register':
   4612 
   4613      void gdbarch_register (enum bfd_architecture    architecture,
   4614                             gdbarch_init_ftype      *init_func,
   4615                             gdbarch_dump_tdep_ftype *tdep_dump_func);
   4616 
   4617    This function has been described fully in an earlier section.  *Note
   4618 How an Architecture is Represented: How an Architecture is Represented.
   4619 
   4620    The new `struct gdbarch' should contain implementations of the
   4621 necessary functions (described in the previous sections) to describe
   4622 the basic layout of the target machine's processor chip (registers,
   4623 stack, etc.).  It can be shared among many targets that use the same
   4624 processor architecture.
   4625 
   4626 
   4627 File: gdbint.info,  Node: Target Descriptions,  Next: Target Vector Definition,  Prev: Target Architecture Definition,  Up: Top
   4628 
   4629 12 Target Descriptions
   4630 **********************
   4631 
   4632 The target architecture definition (*note Target Architecture
   4633 Definition::) contains GDB's hard-coded knowledge about an
   4634 architecture.  For some platforms, it is handy to have more flexible
   4635 knowledge about a specific instance of the architecture--for instance,
   4636 a processor or development board.  "Target descriptions" provide a
   4637 mechanism for the user to tell GDB more about what their target
   4638 supports, or for the target to tell GDB directly.
   4639 
   4640    For details on writing, automatically supplying, and manually
   4641 selecting target descriptions, see *note Target Descriptions:
   4642 (gdb)Target Descriptions.  This section will cover some related topics
   4643 about the GDB internals.
   4644 
   4645 * Menu:
   4646 
   4647 * Target Descriptions Implementation::
   4648 * Adding Target Described Register Support::
   4649 
   4650 
   4651 File: gdbint.info,  Node: Target Descriptions Implementation,  Next: Adding Target Described Register Support,  Up: Target Descriptions
   4652 
   4653 12.1 Target Descriptions Implementation
   4654 =======================================
   4655 
   4656 Before GDB connects to a new target, or runs a new program on an
   4657 existing target, it discards any existing target description and
   4658 reverts to a default gdbarch.  Then, after connecting, it looks for a
   4659 new target description by calling `target_find_description'.
   4660 
   4661    A description may come from a user specified file (XML), the remote
   4662 `qXfer:features:read' packet (also XML), or from any custom
   4663 `to_read_description' routine in the target vector.  For instance, the
   4664 remote target supports guessing whether a MIPS target is 32-bit or
   4665 64-bit based on the size of the `g' packet.
   4666 
   4667    If any target description is found, GDB creates a new gdbarch
   4668 incorporating the description by calling `gdbarch_update_p'.  Any
   4669 `<architecture>' element is handled first, to determine which
   4670 architecture's gdbarch initialization routine is called to create the
   4671 new architecture.  Then the initialization routine is called, and has a
   4672 chance to adjust the constructed architecture based on the contents of
   4673 the target description.  For instance, it can recognize any properties
   4674 set by a `to_read_description' routine.  Also see *note Adding Target
   4675 Described Register Support::.
   4676 
   4677 
   4678 File: gdbint.info,  Node: Adding Target Described Register Support,  Prev: Target Descriptions Implementation,  Up: Target Descriptions
   4679 
   4680 12.2 Adding Target Described Register Support
   4681 =============================================
   4682 
   4683 Target descriptions can report additional registers specific to an
   4684 instance of the target.  But it takes a little work in the architecture
   4685 specific routines to support this.
   4686 
   4687    A target description must either have no registers or a complete
   4688 set--this avoids complexity in trying to merge standard registers with
   4689 the target defined registers.  It is the architecture's responsibility
   4690 to validate that a description with registers has everything it needs.
   4691 To keep architecture code simple, the same mechanism is used to assign
   4692 fixed internal register numbers to standard registers.
   4693 
   4694    If `tdesc_has_registers' returns 1, the description contains
   4695 registers.  The architecture's `gdbarch_init' routine should:
   4696 
   4697    * Call `tdesc_data_alloc' to allocate storage, early, before
   4698      searching for a matching gdbarch or allocating a new one.
   4699 
   4700    * Use `tdesc_find_feature' to locate standard features by name.
   4701 
   4702    * Use `tdesc_numbered_register' and `tdesc_numbered_register_choices'
   4703      to locate the expected registers in the standard features.
   4704 
   4705    * Return `NULL' if a required feature is missing, or if any standard
   4706      feature is missing expected registers.  This will produce a
   4707      warning that the description was incomplete.
   4708 
   4709    * Free the allocated data before returning, unless
   4710      `tdesc_use_registers' is called.
   4711 
   4712    * Call `set_gdbarch_num_regs' as usual, with a number higher than any
   4713      fixed number passed to `tdesc_numbered_register'.
   4714 
   4715    * Call `tdesc_use_registers' after creating a new gdbarch, before
   4716      returning it.
   4717 
   4718 
   4719    After `tdesc_use_registers' has been called, the architecture's
   4720 `register_name', `register_type', and `register_reggroup_p' routines
   4721 will not be called; that information will be taken from the target
   4722 description.  `num_regs' may be increased to account for any additional
   4723 registers in the description.
   4724 
   4725    Pseudo-registers require some extra care:
   4726 
   4727    * Using `tdesc_numbered_register' allows the architecture to give
   4728      constant register numbers to standard architectural registers, e.g.
   4729      as an `enum' in `ARCH-tdep.h'.  But because pseudo-registers are
   4730      always numbered above `num_regs', which may be increased by the
   4731      description, constant numbers can not be used for pseudos.  They
   4732      must be numbered relative to `num_regs' instead.
   4733 
   4734    * The description will not describe pseudo-registers, so the
   4735      architecture must call `set_tdesc_pseudo_register_name',
   4736      `set_tdesc_pseudo_register_type', and
   4737      `set_tdesc_pseudo_register_reggroup_p' to supply routines
   4738      describing pseudo registers.  These routines will be passed
   4739      internal register numbers, so the same routines used for the
   4740      gdbarch equivalents are usually suitable.
   4741 
   4742 
   4743 
   4744 File: gdbint.info,  Node: Target Vector Definition,  Next: Native Debugging,  Prev: Target Descriptions,  Up: Top
   4745 
   4746 13 Target Vector Definition
   4747 ***************************
   4748 
   4749 The target vector defines the interface between GDB's abstract handling
   4750 of target systems, and the nitty-gritty code that actually exercises
   4751 control over a process or a serial port.  GDB includes some 30-40
   4752 different target vectors; however, each configuration of GDB includes
   4753 only a few of them.
   4754 
   4755 * Menu:
   4756 
   4757 * Managing Execution State::
   4758 * Existing Targets::
   4759 
   4760 
   4761 File: gdbint.info,  Node: Managing Execution State,  Next: Existing Targets,  Up: Target Vector Definition
   4762 
   4763 13.1 Managing Execution State
   4764 =============================
   4765 
   4766 A target vector can be completely inactive (not pushed on the target
   4767 stack), active but not running (pushed, but not connected to a fully
   4768 manifested inferior), or completely active (pushed, with an accessible
   4769 inferior).  Most targets are only completely inactive or completely
   4770 active, but some support persistent connections to a target even when
   4771 the target has exited or not yet started.
   4772 
   4773    For example, connecting to the simulator using `target sim' does not
   4774 create a running program.  Neither registers nor memory are accessible
   4775 until `run'.  Similarly, after `kill', the program can not continue
   4776 executing.  But in both cases GDB remains connected to the simulator,
   4777 and target-specific commands are directed to the simulator.
   4778 
   4779    A target which only supports complete activation should push itself
   4780 onto the stack in its `to_open' routine (by calling `push_target'), and
   4781 unpush itself from the stack in its `to_mourn_inferior' routine (by
   4782 calling `unpush_target').
   4783 
   4784    A target which supports both partial and complete activation should
   4785 still call `push_target' in `to_open', but not call `unpush_target' in
   4786 `to_mourn_inferior'.  Instead, it should call either
   4787 `target_mark_running' or `target_mark_exited' in its `to_open',
   4788 depending on whether the target is fully active after connection.  It
   4789 should also call `target_mark_running' any time the inferior becomes
   4790 fully active (e.g. in `to_create_inferior' and `to_attach'), and
   4791 `target_mark_exited' when the inferior becomes inactive (in
   4792 `to_mourn_inferior').  The target should also make sure to call
   4793 `target_mourn_inferior' from its `to_kill', to return the target to
   4794 inactive state.
   4795 
   4796 
   4797 File: gdbint.info,  Node: Existing Targets,  Prev: Managing Execution State,  Up: Target Vector Definition
   4798 
   4799 13.2 Existing Targets
   4800 =====================
   4801 
   4802 13.2.1 File Targets
   4803 -------------------
   4804 
   4805 Both executables and core files have target vectors.
   4806 
   4807 13.2.2 Standard Protocol and Remote Stubs
   4808 -----------------------------------------
   4809 
   4810 GDB's file `remote.c' talks a serial protocol to code that runs in the
   4811 target system.  GDB provides several sample "stubs" that can be
   4812 integrated into target programs or operating systems for this purpose;
   4813 they are named `CPU-stub.c'.  Many operating systems, embedded targets,
   4814 emulators, and simulators already have a GDB stub built into them, and
   4815 maintenance of the remote protocol must be careful to preserve
   4816 compatibility.
   4817 
   4818    The GDB user's manual describes how to put such a stub into your
   4819 target code.  What follows is a discussion of integrating the SPARC
   4820 stub into a complicated operating system (rather than a simple
   4821 program), by Stu Grossman, the author of this stub.
   4822 
   4823    The trap handling code in the stub assumes the following upon entry
   4824 to `trap_low':
   4825 
   4826   1. %l1 and %l2 contain pc and npc respectively at the time of the
   4827      trap;
   4828 
   4829   2. traps are disabled;
   4830 
   4831   3. you are in the correct trap window.
   4832 
   4833    As long as your trap handler can guarantee those conditions, then
   4834 there is no reason why you shouldn't be able to "share" traps with the
   4835 stub.  The stub has no requirement that it be jumped to directly from
   4836 the hardware trap vector.  That is why it calls `exceptionHandler()',
   4837 which is provided by the external environment.  For instance, this could
   4838 set up the hardware traps to actually execute code which calls the stub
   4839 first, and then transfers to its own trap handler.
   4840 
   4841    For the most point, there probably won't be much of an issue with
   4842 "sharing" traps, as the traps we use are usually not used by the kernel,
   4843 and often indicate unrecoverable error conditions.  Anyway, this is all
   4844 controlled by a table, and is trivial to modify.  The most important
   4845 trap for us is for `ta 1'.  Without that, we can't single step or do
   4846 breakpoints.  Everything else is unnecessary for the proper operation
   4847 of the debugger/stub.
   4848 
   4849    From reading the stub, it's probably not obvious how breakpoints
   4850 work.  They are simply done by deposit/examine operations from GDB.
   4851 
   4852 13.2.3 ROM Monitor Interface
   4853 ----------------------------
   4854 
   4855 13.2.4 Custom Protocols
   4856 -----------------------
   4857 
   4858 13.2.5 Transport Layer
   4859 ----------------------
   4860 
   4861 13.2.6 Builtin Simulator
   4862 ------------------------
   4863 
   4864 
   4865 File: gdbint.info,  Node: Native Debugging,  Next: Support Libraries,  Prev: Target Vector Definition,  Up: Top
   4866 
   4867 14 Native Debugging
   4868 *******************
   4869 
   4870 Several files control GDB's configuration for native support:
   4871 
   4872 `gdb/config/ARCH/XYZ.mh'
   4873      Specifies Makefile fragments needed by a _native_ configuration on
   4874      machine XYZ.  In particular, this lists the required
   4875      native-dependent object files, by defining `NATDEPFILES=...'.
   4876      Also specifies the header file which describes native support on
   4877      XYZ, by defining `NAT_FILE= nm-XYZ.h'.  You can also define
   4878      `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS',
   4879      `NAT_GENERATED_FILES', etc.; see `Makefile.in'.
   4880 
   4881      _Maintainer's note: The `.mh' suffix is because this file
   4882      originally contained `Makefile' fragments for hosting GDB on
   4883      machine XYZ.  While the file is no longer used for this purpose,
   4884      the `.mh' suffix remains.  Perhaps someone will eventually rename
   4885      these fragments so that they have a `.mn' suffix._
   4886 
   4887 `gdb/config/ARCH/nm-XYZ.h'
   4888      (`nm.h' is a link to this file, created by `configure').  Contains
   4889      C macro definitions describing the native system environment, such
   4890      as child process control and core file support.
   4891 
   4892 `gdb/XYZ-nat.c'
   4893      Contains any miscellaneous C code required for this native support
   4894      of this machine.  On some machines it doesn't exist at all.
   4895 
   4896    There are some "generic" versions of routines that can be used by
   4897 various systems.  These can be customized in various ways by macros
   4898 defined in your `nm-XYZ.h' file.  If these routines work for the XYZ
   4899 host, you can just include the generic file's name (with `.o', not
   4900 `.c') in `NATDEPFILES'.
   4901 
   4902    Otherwise, if your machine needs custom support routines, you will
   4903 need to write routines that perform the same functions as the generic
   4904 file.  Put them into `XYZ-nat.c', and put `XYZ-nat.o' into
   4905 `NATDEPFILES'.
   4906 
   4907 `inftarg.c'
   4908      This contains the _target_ops vector_ that supports Unix child
   4909      processes on systems which use ptrace and wait to control the
   4910      child.
   4911 
   4912 `procfs.c'
   4913      This contains the _target_ops vector_ that supports Unix child
   4914      processes on systems which use /proc to control the child.
   4915 
   4916 `fork-child.c'
   4917      This does the low-level grunge that uses Unix system calls to do a
   4918      "fork and exec" to start up a child process.
   4919 
   4920 `infptrace.c'
   4921      This is the low level interface to inferior processes for systems
   4922      using the Unix `ptrace' call in a vanilla way.
   4923 
   4924 14.1 ptrace
   4925 ===========
   4926 
   4927 14.2 /proc
   4928 ==========
   4929 
   4930 14.3 win32
   4931 ==========
   4932 
   4933 14.4 shared libraries
   4934 =====================
   4935 
   4936 14.5 Native Conditionals
   4937 ========================
   4938 
   4939 When GDB is configured and compiled, various macros are defined or left
   4940 undefined, to control compilation when the host and target systems are
   4941 the same.  These macros should be defined (or left undefined) in
   4942 `nm-SYSTEM.h'.
   4943 
   4944 `I386_USE_GENERIC_WATCHPOINTS'
   4945      An x86-based machine can define this to use the generic x86
   4946      watchpoint support; see *note I386_USE_GENERIC_WATCHPOINTS:
   4947      Algorithms.
   4948 
   4949 `SOLIB_ADD (FILENAME, FROM_TTY, TARG, READSYMS)'
   4950      Define this to expand into an expression that will cause the
   4951      symbols in FILENAME to be added to GDB's symbol table.  If
   4952      READSYMS is zero symbols are not read but any necessary low level
   4953      processing for FILENAME is still done.
   4954 
   4955 `SOLIB_CREATE_INFERIOR_HOOK'
   4956      Define this to expand into any shared-library-relocation code that
   4957      you want to be run just after the child process has been forked.
   4958 
   4959 `START_INFERIOR_TRAPS_EXPECTED'
   4960      When starting an inferior, GDB normally expects to trap twice;
   4961      once when the shell execs, and once when the program itself execs.
   4962      If the actual number of traps is something other than 2, then
   4963      define this macro to expand into the number expected.
   4964 
   4965 
   4966 
   4967 File: gdbint.info,  Node: Support Libraries,  Next: Coding,  Prev: Native Debugging,  Up: Top
   4968 
   4969 15 Support Libraries
   4970 ********************
   4971 
   4972 15.1 BFD
   4973 ========
   4974 
   4975 BFD provides support for GDB in several ways:
   4976 
   4977 _identifying executable and core files_
   4978      BFD will identify a variety of file types, including a.out, coff,
   4979      and several variants thereof, as well as several kinds of core
   4980      files.
   4981 
   4982 _access to sections of files_
   4983      BFD parses the file headers to determine the names, virtual
   4984      addresses, sizes, and file locations of all the various named
   4985      sections in files (such as the text section or the data section).
   4986      GDB simply calls BFD to read or write section X at byte offset Y
   4987      for length Z.
   4988 
   4989 _specialized core file support_
   4990      BFD provides routines to determine the failing command name stored
   4991      in a core file, the signal with which the program failed, and
   4992      whether a core file matches (i.e. could be a core dump of) a
   4993      particular executable file.
   4994 
   4995 _locating the symbol information_
   4996      GDB uses an internal interface of BFD to determine where to find
   4997      the symbol information in an executable file or symbol-file.  GDB
   4998      itself handles the reading of symbols, since BFD does not
   4999      "understand" debug symbols, but GDB uses BFD's cached information
   5000      to find the symbols, string table, etc.
   5001 
   5002 15.2 opcodes
   5003 ============
   5004 
   5005 The opcodes library provides GDB's disassembler.  (It's a separate
   5006 library because it's also used in binutils, for `objdump').
   5007 
   5008 15.3 readline
   5009 =============
   5010 
   5011 The `readline' library provides a set of functions for use by
   5012 applications that allow users to edit command lines as they are typed
   5013 in.
   5014 
   5015 15.4 libiberty
   5016 ==============
   5017 
   5018 The `libiberty' library provides a set of functions and features that
   5019 integrate and improve on functionality found in modern operating
   5020 systems.  Broadly speaking, such features can be divided into three
   5021 groups: supplemental functions (functions that may be missing in some
   5022 environments and operating systems), replacement functions (providing a
   5023 uniform and easier to use interface for commonly used standard
   5024 functions), and extensions (which provide additional functionality
   5025 beyond standard functions).
   5026 
   5027    GDB uses various features provided by the `libiberty' library, for
   5028 instance the C++ demangler, the IEEE floating format support functions,
   5029 the input options parser `getopt', the `obstack' extension, and other
   5030 functions.
   5031 
   5032 15.4.1 `obstacks' in GDB
   5033 ------------------------
   5034 
   5035 The obstack mechanism provides a convenient way to allocate and free
   5036 chunks of memory.  Each obstack is a pool of memory that is managed
   5037 like a stack.  Objects (of any nature, size and alignment) are
   5038 allocated and freed in a LIFO fashion on an obstack (see `libiberty''s
   5039 documentation for a more detailed explanation of `obstacks').
   5040 
   5041    The most noticeable use of the `obstacks' in GDB is in object files.
   5042 There is an obstack associated with each internal representation of an
   5043 object file.  Lots of things get allocated on these `obstacks':
   5044 dictionary entries, blocks, blockvectors, symbols, minimal symbols,
   5045 types, vectors of fundamental types, class fields of types, object
   5046 files section lists, object files section offset lists, line tables,
   5047 symbol tables, partial symbol tables, string tables, symbol table
   5048 private data, macros tables, debug information sections and entries,
   5049 import and export lists (som), unwind information (hppa), dwarf2
   5050 location expressions data.  Plus various strings such as directory
   5051 names strings, debug format strings, names of types.
   5052 
   5053    An essential and convenient property of all data on `obstacks' is
   5054 that memory for it gets allocated (with `obstack_alloc') at various
   5055 times during a debugging session, but it is released all at once using
   5056 the `obstack_free' function.  The `obstack_free' function takes a
   5057 pointer to where in the stack it must start the deletion from (much
   5058 like the cleanup chains have a pointer to where to start the cleanups).
   5059 Because of the stack like structure of the `obstacks', this allows to
   5060 free only a top portion of the obstack.  There are a few instances in
   5061 GDB where such thing happens.  Calls to `obstack_free' are done after
   5062 some local data is allocated to the obstack.  Only the local data is
   5063 deleted from the obstack.  Of course this assumes that nothing between
   5064 the `obstack_alloc' and the `obstack_free' allocates anything else on
   5065 the same obstack.  For this reason it is best and safest to use
   5066 temporary `obstacks'.
   5067 
   5068    Releasing the whole obstack is also not safe per se.  It is safe only
   5069 under the condition that we know the `obstacks' memory is no longer
   5070 needed.  In GDB we get rid of the `obstacks' only when we get rid of
   5071 the whole objfile(s), for instance upon reading a new symbol file.
   5072 
   5073 15.5 gnu-regex
   5074 ==============
   5075 
   5076 Regex conditionals.
   5077 
   5078 `C_ALLOCA'
   5079 
   5080 `NFAILURES'
   5081 
   5082 `RE_NREGS'
   5083 
   5084 `SIGN_EXTEND_CHAR'
   5085 
   5086 `SWITCH_ENUM_BUG'
   5087 
   5088 `SYNTAX_TABLE'
   5089 
   5090 `Sword'
   5091 
   5092 `sparc'
   5093 
   5094 15.6 Array Containers
   5095 =====================
   5096 
   5097 Often it is necessary to manipulate a dynamic array of a set of
   5098 objects.  C forces some bookkeeping on this, which can get cumbersome
   5099 and repetitive.  The `vec.h' file contains macros for defining and
   5100 using a typesafe vector type.  The functions defined will be inlined
   5101 when compiling, and so the abstraction cost should be zero.  Domain
   5102 checks are added to detect programming errors.
   5103 
   5104    An example use would be an array of symbols or section information.
   5105 The array can be grown as symbols are read in (or preallocated), and
   5106 the accessor macros provided keep care of all the necessary
   5107 bookkeeping.  Because the arrays are type safe, there is no danger of
   5108 accidentally mixing up the contents.  Think of these as C++ templates,
   5109 but implemented in C.
   5110 
   5111    Because of the different behavior of structure objects, scalar
   5112 objects and of pointers, there are three flavors of vector, one for
   5113 each of these variants.  Both the structure object and pointer variants
   5114 pass pointers to objects around -- in the former case the pointers are
   5115 stored into the vector and in the latter case the pointers are
   5116 dereferenced and the objects copied into the vector.  The scalar object
   5117 variant is suitable for `int'-like objects, and the vector elements are
   5118 returned by value.
   5119 
   5120    There are both `index' and `iterate' accessors.  The iterator
   5121 returns a boolean iteration condition and updates the iteration
   5122 variable passed by reference.  Because the iterator will be inlined,
   5123 the address-of can be optimized away.
   5124 
   5125    The vectors are implemented using the trailing array idiom, thus they
   5126 are not resizeable without changing the address of the vector object
   5127 itself.  This means you cannot have variables or fields of vector type
   5128 -- always use a pointer to a vector.  The one exception is the final
   5129 field of a structure, which could be a vector type.  You will have to
   5130 use the `embedded_size' & `embedded_init' calls to create such objects,
   5131 and they will probably not be resizeable (so don't use the "safe"
   5132 allocation variants).  The trailing array idiom is used (rather than a
   5133 pointer to an array of data), because, if we allow `NULL' to also
   5134 represent an empty vector, empty vectors occupy minimal space in the
   5135 structure containing them.
   5136 
   5137    Each operation that increases the number of active elements is
   5138 available in "quick" and "safe" variants.  The former presumes that
   5139 there is sufficient allocated space for the operation to succeed (it
   5140 dies if there is not).  The latter will reallocate the vector, if
   5141 needed.  Reallocation causes an exponential increase in vector size.
   5142 If you know you will be adding N elements, it would be more efficient
   5143 to use the reserve operation before adding the elements with the
   5144 "quick" operation.  This will ensure there are at least as many
   5145 elements as you ask for, it will exponentially increase if there are
   5146 too few spare slots.  If you want reserve a specific number of slots,
   5147 but do not want the exponential increase (for instance, you know this
   5148 is the last allocation), use a negative number for reservation.  You
   5149 can also create a vector of a specific size from the get go.
   5150 
   5151    You should prefer the push and pop operations, as they append and
   5152 remove from the end of the vector.  If you need to remove several items
   5153 in one go, use the truncate operation.  The insert and remove
   5154 operations allow you to change elements in the middle of the vector.
   5155 There are two remove operations, one which preserves the element
   5156 ordering `ordered_remove', and one which does not `unordered_remove'.
   5157 The latter function copies the end element into the removed slot,
   5158 rather than invoke a memmove operation.  The `lower_bound' function
   5159 will determine where to place an item in the array using insert that
   5160 will maintain sorted order.
   5161 
   5162    If you need to directly manipulate a vector, then the `address'
   5163 accessor will return the address of the start of the vector.  Also the
   5164 `space' predicate will tell you whether there is spare capacity in the
   5165 vector.  You will not normally need to use these two functions.
   5166 
   5167    Vector types are defined using a `DEF_VEC_{O,P,I}(TYPENAME)' macro.
   5168 Variables of vector type are declared using a `VEC(TYPENAME)' macro.
   5169 The characters `O', `P' and `I' indicate whether TYPENAME is an object
   5170 (`O'), pointer (`P') or integral (`I') type.  Be careful to pick the
   5171 correct one, as you'll get an awkward and inefficient API if you use
   5172 the wrong one.  There is a check, which results in a compile-time
   5173 warning, for the `P' and `I' versions, but there is no check for the
   5174 `O' versions, as that is not possible in plain C.
   5175 
   5176    An example of their use would be,
   5177 
   5178      DEF_VEC_P(tree);   // non-managed tree vector.
   5179 
   5180      struct my_struct {
   5181        VEC(tree) *v;      // A (pointer to) a vector of tree pointers.
   5182      };
   5183 
   5184      struct my_struct *s;
   5185 
   5186      if (VEC_length(tree, s->v)) { we have some contents }
   5187      VEC_safe_push(tree, s->v, decl); // append some decl onto the end
   5188      for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)
   5189        { do something with elt }
   5190 
   5191    The `vec.h' file provides details on how to invoke the various
   5192 accessors provided.  They are enumerated here:
   5193 
   5194 `VEC_length'
   5195      Return the number of items in the array,
   5196 
   5197 `VEC_empty'
   5198      Return true if the array has no elements.
   5199 
   5200 `VEC_last'
   5201 `VEC_index'
   5202      Return the last or arbitrary item in the array.
   5203 
   5204 `VEC_iterate'
   5205      Access an array element and indicate whether the array has been
   5206      traversed.
   5207 
   5208 `VEC_alloc'
   5209 `VEC_free'
   5210      Create and destroy an array.
   5211 
   5212 `VEC_embedded_size'
   5213 `VEC_embedded_init'
   5214      Helpers for embedding an array as the final element of another
   5215      struct.
   5216 
   5217 `VEC_copy'
   5218      Duplicate an array.
   5219 
   5220 `VEC_space'
   5221      Return the amount of free space in an array.
   5222 
   5223 `VEC_reserve'
   5224      Ensure a certain amount of free space.
   5225 
   5226 `VEC_quick_push'
   5227 `VEC_safe_push'
   5228      Append to an array, either assuming the space is available, or
   5229      making sure that it is.
   5230 
   5231 `VEC_pop'
   5232      Remove the last item from an array.
   5233 
   5234 `VEC_truncate'
   5235      Remove several items from the end of an array.
   5236 
   5237 `VEC_safe_grow'
   5238      Add several items to the end of an array.
   5239 
   5240 `VEC_replace'
   5241      Overwrite an item in the array.
   5242 
   5243 `VEC_quick_insert'
   5244 `VEC_safe_insert'
   5245      Insert an item into the middle of the array.  Either the space must
   5246      already exist, or the space is created.
   5247 
   5248 `VEC_ordered_remove'
   5249 `VEC_unordered_remove'
   5250      Remove an item from the array, preserving order or not.
   5251 
   5252 `VEC_block_remove'
   5253      Remove a set of items from the array.
   5254 
   5255 `VEC_address'
   5256      Provide the address of the first element.
   5257 
   5258 `VEC_lower_bound'
   5259      Binary search the array.
   5260 
   5261 
   5262 15.7 include
   5263 ============
   5264 
   5265 
   5266 File: gdbint.info,  Node: Coding,  Next: Porting GDB,  Prev: Support Libraries,  Up: Top
   5267 
   5268 16 Coding
   5269 *********
   5270 
   5271 This chapter covers topics that are lower-level than the major
   5272 algorithms of GDB.
   5273 
   5274 16.1 Cleanups
   5275 =============
   5276 
   5277 Cleanups are a structured way to deal with things that need to be done
   5278 later.
   5279 
   5280    When your code does something (e.g., `xmalloc' some memory, or
   5281 `open' a file) that needs to be undone later (e.g., `xfree' the memory
   5282 or `close' the file), it can make a cleanup.  The cleanup will be done
   5283 at some future point: when the command is finished and control returns
   5284 to the top level; when an error occurs and the stack is unwound; or
   5285 when your code decides it's time to explicitly perform cleanups.
   5286 Alternatively you can elect to discard the cleanups you created.
   5287 
   5288    Syntax:
   5289 
   5290 `struct cleanup *OLD_CHAIN;'
   5291      Declare a variable which will hold a cleanup chain handle.
   5292 
   5293 `OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
   5294      Make a cleanup which will cause FUNCTION to be called with ARG (a
   5295      `char *') later.  The result, OLD_CHAIN, is a handle that can
   5296      later be passed to `do_cleanups' or `discard_cleanups'.  Unless
   5297      you are going to call `do_cleanups' or `discard_cleanups', you can
   5298      ignore the result from `make_cleanup'.
   5299 
   5300 `do_cleanups (OLD_CHAIN);'
   5301      Do all cleanups added to the chain since the corresponding
   5302      `make_cleanup' call was made.
   5303 
   5304 `discard_cleanups (OLD_CHAIN);'
   5305      Same as `do_cleanups' except that it just removes the cleanups from
   5306      the chain and does not call the specified functions.
   5307 
   5308    Cleanups are implemented as a chain.  The handle returned by
   5309 `make_cleanups' includes the cleanup passed to the call and any later
   5310 cleanups appended to the chain (but not yet discarded or performed).
   5311 E.g.:
   5312 
   5313      make_cleanup (a, 0);
   5314      {
   5315        struct cleanup *old = make_cleanup (b, 0);
   5316        make_cleanup (c, 0)
   5317        ...
   5318        do_cleanups (old);
   5319      }
   5320 
   5321 will call `c()' and `b()' but will not call `a()'.  The cleanup that
   5322 calls `a()' will remain in the cleanup chain, and will be done later
   5323 unless otherwise discarded.
   5324 
   5325    Your function should explicitly do or discard the cleanups it
   5326 creates.  Failing to do this leads to non-deterministic behavior since
   5327 the caller will arbitrarily do or discard your functions cleanups.
   5328 This need leads to two common cleanup styles.
   5329 
   5330    The first style is try/finally.  Before it exits, your code-block
   5331 calls `do_cleanups' with the old cleanup chain and thus ensures that
   5332 your code-block's cleanups are always performed.  For instance, the
   5333 following code-segment avoids a memory leak problem (even when `error'
   5334 is called and a forced stack unwind occurs) by ensuring that the
   5335 `xfree' will always be called:
   5336 
   5337      struct cleanup *old = make_cleanup (null_cleanup, 0);
   5338      data = xmalloc (sizeof blah);
   5339      make_cleanup (xfree, data);
   5340      ... blah blah ...
   5341      do_cleanups (old);
   5342 
   5343    The second style is try/except.  Before it exits, your code-block
   5344 calls `discard_cleanups' with the old cleanup chain and thus ensures
   5345 that any created cleanups are not performed.  For instance, the
   5346 following code segment, ensures that the file will be closed but only
   5347 if there is an error:
   5348 
   5349      FILE *file = fopen ("afile", "r");
   5350      struct cleanup *old = make_cleanup (close_file, file);
   5351      ... blah blah ...
   5352      discard_cleanups (old);
   5353      return file;
   5354 
   5355    Some functions, e.g., `fputs_filtered()' or `error()', specify that
   5356 they "should not be called when cleanups are not in place".  This means
   5357 that any actions you need to reverse in the case of an error or
   5358 interruption must be on the cleanup chain before you call these
   5359 functions, since they might never return to your code (they `longjmp'
   5360 instead).
   5361 
   5362 16.2 Per-architecture module data
   5363 =================================
   5364 
   5365 The multi-arch framework includes a mechanism for adding module
   5366 specific per-architecture data-pointers to the `struct gdbarch'
   5367 architecture object.
   5368 
   5369    A module registers one or more per-architecture data-pointers using:
   5370 
   5371  -- Architecture Function: struct gdbarch_data *
   5372 gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *PRE_INIT)
   5373      PRE_INIT is used to, on-demand, allocate an initial value for a
   5374      per-architecture data-pointer using the architecture's obstack
   5375      (passed in as a parameter).  Since PRE_INIT can be called during
   5376      architecture creation, it is not parameterized with the
   5377      architecture.  and must not call modules that use per-architecture
   5378      data.
   5379 
   5380  -- Architecture Function: struct gdbarch_data *
   5381 gdbarch_data_register_post_init (gdbarch_data_post_init_ftype
   5382           *POST_INIT)
   5383      POST_INIT is used to obtain an initial value for a
   5384      per-architecture data-pointer _after_.  Since POST_INIT is always
   5385      called after architecture creation, it both receives the fully
   5386      initialized architecture and is free to call modules that use
   5387      per-architecture data (care needs to be taken to ensure that those
   5388      other modules do not try to call back to this module as that will
   5389      create in cycles in the initialization call graph).
   5390 
   5391    These functions return a `struct gdbarch_data' that is used to
   5392 identify the per-architecture data-pointer added for that module.
   5393 
   5394    The per-architecture data-pointer is accessed using the function:
   5395 
   5396  -- Architecture Function: void * gdbarch_data (struct gdbarch
   5397           *GDBARCH, struct gdbarch_data *DATA_HANDLE)
   5398      Given the architecture ARCH and module data handle DATA_HANDLE
   5399      (returned by `gdbarch_data_register_pre_init' or
   5400      `gdbarch_data_register_post_init'), this function returns the
   5401      current value of the per-architecture data-pointer.  If the data
   5402      pointer is `NULL', it is first initialized by calling the
   5403      corresponding PRE_INIT or POST_INIT method.
   5404 
   5405    The examples below assume the following definitions:
   5406 
   5407      struct nozel { int total; };
   5408      static struct gdbarch_data *nozel_handle;
   5409 
   5410    A module can extend the architecture vector, adding additional
   5411 per-architecture data, using the PRE_INIT method.  The module's
   5412 per-architecture data is then initialized during architecture creation.
   5413 
   5414    In the below, the module's per-architecture _nozel_ is added.  An
   5415 architecture can specify its nozel by calling `set_gdbarch_nozel' from
   5416 `gdbarch_init'.
   5417 
   5418      static void *
   5419      nozel_pre_init (struct obstack *obstack)
   5420      {
   5421        struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
   5422        return data;
   5423      }
   5424 
   5425      extern void
   5426      set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
   5427      {
   5428        struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
   5429        data->total = nozel;
   5430      }
   5431 
   5432    A module can on-demand create architecture dependent data structures
   5433 using `post_init'.
   5434 
   5435    In the below, the nozel's total is computed on-demand by
   5436 `nozel_post_init' using information obtained from the architecture.
   5437 
   5438      static void *
   5439      nozel_post_init (struct gdbarch *gdbarch)
   5440      {
   5441        struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
   5442        nozel->total = gdbarch... (gdbarch);
   5443        return data;
   5444      }
   5445 
   5446      extern int
   5447      nozel_total (struct gdbarch *gdbarch)
   5448      {
   5449        struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
   5450        return data->total;
   5451      }
   5452 
   5453 16.3 Wrapping Output Lines
   5454 ==========================
   5455 
   5456 Output that goes through `printf_filtered' or `fputs_filtered' or
   5457 `fputs_demangled' needs only to have calls to `wrap_here' added in
   5458 places that would be good breaking points.  The utility routines will
   5459 take care of actually wrapping if the line width is exceeded.
   5460 
   5461    The argument to `wrap_here' is an indentation string which is
   5462 printed _only_ if the line breaks there.  This argument is saved away
   5463 and used later.  It must remain valid until the next call to
   5464 `wrap_here' or until a newline has been printed through the
   5465 `*_filtered' functions.  Don't pass in a local variable and then return!
   5466 
   5467    It is usually best to call `wrap_here' after printing a comma or
   5468 space.  If you call it before printing a space, make sure that your
   5469 indentation properly accounts for the leading space that will print if
   5470 the line wraps there.
   5471 
   5472    Any function or set of functions that produce filtered output must
   5473 finish by printing a newline, to flush the wrap buffer, before switching
   5474 to unfiltered (`printf') output.  Symbol reading routines that print
   5475 warnings are a good example.
   5476 
   5477 16.4 GDB Coding Standards
   5478 =========================
   5479 
   5480 GDB follows the GNU coding standards, as described in
   5481 `etc/standards.texi'.  This file is also available for anonymous FTP
   5482 from GNU archive sites.  GDB takes a strict interpretation of the
   5483 standard; in general, when the GNU standard recommends a practice but
   5484 does not require it, GDB requires it.
   5485 
   5486    GDB follows an additional set of coding standards specific to GDB,
   5487 as described in the following sections.
   5488 
   5489 16.4.1 ISO C
   5490 ------------
   5491 
   5492 GDB assumes an ISO/IEC 9899:1990 (a.k.a. ISO C90) compliant compiler.
   5493 
   5494    GDB does not assume an ISO C or POSIX compliant C library.
   5495 
   5496 16.4.2 Memory Management
   5497 ------------------------
   5498 
   5499 GDB does not use the functions `malloc', `realloc', `calloc', `free'
   5500 and `asprintf'.
   5501 
   5502    GDB uses the functions `xmalloc', `xrealloc' and `xcalloc' when
   5503 allocating memory.  Unlike `malloc' et.al.  these functions do not
   5504 return when the memory pool is empty.  Instead, they unwind the stack
   5505 using cleanups.  These functions return `NULL' when requested to
   5506 allocate a chunk of memory of size zero.
   5507 
   5508    _Pragmatics: By using these functions, the need to check every
   5509 memory allocation is removed.  These functions provide portable
   5510 behavior._
   5511 
   5512    GDB does not use the function `free'.
   5513 
   5514    GDB uses the function `xfree' to return memory to the memory pool.
   5515 Consistent with ISO-C, this function ignores a request to free a `NULL'
   5516 pointer.
   5517 
   5518    _Pragmatics: On some systems `free' fails when passed a `NULL'
   5519 pointer._
   5520 
   5521    GDB can use the non-portable function `alloca' for the allocation of
   5522 small temporary values (such as strings).
   5523 
   5524    _Pragmatics: This function is very non-portable.  Some systems
   5525 restrict the memory being allocated to no more than a few kilobytes._
   5526 
   5527    GDB uses the string function `xstrdup' and the print function
   5528 `xstrprintf'.
   5529 
   5530    _Pragmatics: `asprintf' and `strdup' can fail.  Print functions such
   5531 as `sprintf' are very prone to buffer overflow errors._
   5532 
   5533 16.4.3 Compiler Warnings
   5534 ------------------------
   5535 
   5536 With few exceptions, developers should avoid the configuration option
   5537 `--disable-werror' when building GDB.  The exceptions are listed in the
   5538 file `gdb/MAINTAINERS'.  The default, when building with GCC, is
   5539 `--enable-werror'.
   5540 
   5541    This option causes GDB (when built using GCC) to be compiled with a
   5542 carefully selected list of compiler warning flags.  Any warnings from
   5543 those flags are treated as errors.
   5544 
   5545    The current list of warning flags includes:
   5546 
   5547 `-Wall'
   5548      Recommended GCC warnings.
   5549 
   5550 `-Wdeclaration-after-statement'
   5551      GCC 3.x (and later) and C99 allow declarations mixed with code,
   5552      but GCC 2.x and C89 do not.
   5553 
   5554 `-Wpointer-arith'
   5555 
   5556 `-Wformat-nonliteral'
   5557      Non-literal format strings, with a few exceptions, are bugs - they
   5558      might contain unintended user-supplied format specifiers.  Since
   5559      GDB uses the `format printf' attribute on all `printf' like
   5560      functions this checks not just `printf' calls but also calls to
   5561      functions such as `fprintf_unfiltered'.
   5562 
   5563 `-Wno-pointer-sign'
   5564      In version 4.0, GCC began warning about pointer argument passing or
   5565      assignment even when the source and destination differed only in
   5566      signedness.  However, most GDB code doesn't distinguish carefully
   5567      between `char' and `unsigned char'.  In early 2006 the GDB
   5568      developers decided correcting these warnings wasn't worth the time
   5569      it would take.
   5570 
   5571 `-Wno-unused-parameter'
   5572      Due to the way that GDB is implemented many functions have unused
   5573      parameters.  Consequently this warning is avoided.  The macro
   5574      `ATTRIBUTE_UNUSED' is not used as it leads to false negatives --
   5575      it is not an error to have `ATTRIBUTE_UNUSED' on a parameter that
   5576      is being used.
   5577 
   5578 `-Wno-unused'
   5579 `-Wno-switch'
   5580 `-Wno-char-subscripts'
   5581      These are warnings which might be useful for GDB, but are
   5582      currently too noisy to enable with `-Werror'.
   5583 
   5584 
   5585 16.4.4 Formatting
   5586 -----------------
   5587 
   5588 The standard GNU recommendations for formatting must be followed
   5589 strictly.
   5590 
   5591    A function declaration should not have its name in column zero.  A
   5592 function definition should have its name in column zero.
   5593 
   5594      /* Declaration */
   5595      static void foo (void);
   5596      /* Definition */
   5597      void
   5598      foo (void)
   5599      {
   5600      }
   5601 
   5602    _Pragmatics: This simplifies scripting.  Function definitions can be
   5603 found using `^function-name'._
   5604 
   5605    There must be a space between a function or macro name and the
   5606 opening parenthesis of its argument list (except for macro definitions,
   5607 as required by C).  There must not be a space after an open
   5608 paren/bracket or before a close paren/bracket.
   5609 
   5610    While additional whitespace is generally helpful for reading, do not
   5611 use more than one blank line to separate blocks, and avoid adding
   5612 whitespace after the end of a program line (as of 1/99, some 600 lines
   5613 had whitespace after the semicolon).  Excess whitespace causes
   5614 difficulties for `diff' and `patch' utilities.
   5615 
   5616    Pointers are declared using the traditional K&R C style:
   5617 
   5618      void *foo;
   5619 
   5620 and not:
   5621 
   5622      void * foo;
   5623      void* foo;
   5624 
   5625 16.4.5 Comments
   5626 ---------------
   5627 
   5628 The standard GNU requirements on comments must be followed strictly.
   5629 
   5630    Block comments must appear in the following form, with no `/*'- or
   5631 `*/'-only lines, and no leading `*':
   5632 
   5633      /* Wait for control to return from inferior to debugger.  If inferior
   5634         gets a signal, we may decide to start it up again instead of
   5635         returning.  That is why there is a loop in this function.  When
   5636         this function actually returns it means the inferior should be left
   5637         stopped and GDB should read more commands.  */
   5638 
   5639    (Note that this format is encouraged by Emacs; tabbing for a
   5640 multi-line comment works correctly, and `M-q' fills the block
   5641 consistently.)
   5642 
   5643    Put a blank line between the block comments preceding function or
   5644 variable definitions, and the definition itself.
   5645 
   5646    In general, put function-body comments on lines by themselves, rather
   5647 than trying to fit them into the 20 characters left at the end of a
   5648 line, since either the comment or the code will inevitably get longer
   5649 than will fit, and then somebody will have to move it anyhow.
   5650 
   5651 16.4.6 C Usage
   5652 --------------
   5653 
   5654 Code must not depend on the sizes of C data types, the format of the
   5655 host's floating point numbers, the alignment of anything, or the order
   5656 of evaluation of expressions.
   5657 
   5658    Use functions freely.  There are only a handful of compute-bound
   5659 areas in GDB that might be affected by the overhead of a function call,
   5660 mainly in symbol reading.  Most of GDB's performance is limited by the
   5661 target interface (whether serial line or system call).
   5662 
   5663    However, use functions with moderation.  A thousand one-line
   5664 functions are just as hard to understand as a single thousand-line
   5665 function.
   5666 
   5667    _Macros are bad, M'kay._ (But if you have to use a macro, make sure
   5668 that the macro arguments are protected with parentheses.)
   5669 
   5670    Declarations like `struct foo *' should be used in preference to
   5671 declarations like `typedef struct foo { ... } *foo_ptr'.
   5672 
   5673 16.4.7 Function Prototypes
   5674 --------------------------
   5675 
   5676 Prototypes must be used when both _declaring_ and _defining_ a
   5677 function.  Prototypes for GDB functions must include both the argument
   5678 type and name, with the name matching that used in the actual function
   5679 definition.
   5680 
   5681    All external functions should have a declaration in a header file
   5682 that callers include, except for `_initialize_*' functions, which must
   5683 be external so that `init.c' construction works, but shouldn't be
   5684 visible to random source files.
   5685 
   5686    Where a source file needs a forward declaration of a static function,
   5687 that declaration must appear in a block near the top of the source file.
   5688 
   5689 16.4.8 Internal Error Recovery
   5690 ------------------------------
   5691 
   5692 During its execution, GDB can encounter two types of errors.  User
   5693 errors and internal errors.  User errors include not only a user
   5694 entering an incorrect command but also problems arising from corrupt
   5695 object files and system errors when interacting with the target.
   5696 Internal errors include situations where GDB has detected, at run time,
   5697 a corrupt or erroneous situation.
   5698 
   5699    When reporting an internal error, GDB uses `internal_error' and
   5700 `gdb_assert'.
   5701 
   5702    GDB must not call `abort' or `assert'.
   5703 
   5704    _Pragmatics: There is no `internal_warning' function.  Either the
   5705 code detected a user error, recovered from it and issued a `warning' or
   5706 the code failed to correctly recover from the user error and issued an
   5707 `internal_error'._
   5708 
   5709 16.4.9 File Names
   5710 -----------------
   5711 
   5712 Any file used when building the core of GDB must be in lower case.  Any
   5713 file used when building the core of GDB must be 8.3 unique.  These
   5714 requirements apply to both source and generated files.
   5715 
   5716    _Pragmatics: The core of GDB must be buildable on many platforms
   5717 including DJGPP and MacOS/HFS.  Every time an unfriendly file is
   5718 introduced to the build process both `Makefile.in' and `configure.in'
   5719 need to be modified accordingly.  Compare the convoluted conversion
   5720 process needed to transform `COPYING' into `copying.c' with the
   5721 conversion needed to transform `version.in' into `version.c'._
   5722 
   5723    Any file non 8.3 compliant file (that is not used when building the
   5724 core of GDB) must be added to `gdb/config/djgpp/fnchange.lst'.
   5725 
   5726    _Pragmatics: This is clearly a compromise._
   5727 
   5728    When GDB has a local version of a system header file (ex `string.h')
   5729 the file name based on the POSIX header prefixed with `gdb_'
   5730 (`gdb_string.h').  These headers should be relatively independent: they
   5731 should use only macros defined by `configure', the compiler, or the
   5732 host; they should include only system headers; they should refer only
   5733 to system types.  They may be shared between multiple programs, e.g.
   5734 GDB and GDBSERVER.
   5735 
   5736    For other files `-' is used as the separator.
   5737 
   5738 16.4.10 Include Files
   5739 ---------------------
   5740 
   5741 A `.c' file should include `defs.h' first.
   5742 
   5743    A `.c' file should directly include the `.h' file of every
   5744 declaration and/or definition it directly refers to.  It cannot rely on
   5745 indirect inclusion.
   5746 
   5747    A `.h' file should directly include the `.h' file of every
   5748 declaration and/or definition it directly refers to.  It cannot rely on
   5749 indirect inclusion.  Exception: The file `defs.h' does not need to be
   5750 directly included.
   5751 
   5752    An external declaration should only appear in one include file.
   5753 
   5754    An external declaration should never appear in a `.c' file.
   5755 Exception: a declaration for the `_initialize' function that pacifies
   5756 `-Wmissing-declaration'.
   5757 
   5758    A `typedef' definition should only appear in one include file.
   5759 
   5760    An opaque `struct' declaration can appear in multiple `.h' files.
   5761 Where possible, a `.h' file should use an opaque `struct' declaration
   5762 instead of an include.
   5763 
   5764    All `.h' files should be wrapped in:
   5765 
   5766      #ifndef INCLUDE_FILE_NAME_H
   5767      #define INCLUDE_FILE_NAME_H
   5768      header body
   5769      #endif
   5770 
   5771 16.4.11 Clean Design and Portable Implementation
   5772 ------------------------------------------------
   5773 
   5774 In addition to getting the syntax right, there's the little question of
   5775 semantics.  Some things are done in certain ways in GDB because long
   5776 experience has shown that the more obvious ways caused various kinds of
   5777 trouble.
   5778 
   5779    You can't assume the byte order of anything that comes from a target
   5780 (including VALUEs, object files, and instructions).  Such things must
   5781 be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
   5782 routines defined in `bfd.h', such as `bfd_get_32'.
   5783 
   5784    You can't assume that you know what interface is being used to talk
   5785 to the target system.  All references to the target must go through the
   5786 current `target_ops' vector.
   5787 
   5788    You can't assume that the host and target machines are the same
   5789 machine (except in the "native" support modules).  In particular, you
   5790 can't assume that the target machine's header files will be available
   5791 on the host machine.  Target code must bring along its own header files
   5792 - written from scratch or explicitly donated by their owner, to avoid
   5793 copyright problems.
   5794 
   5795    Insertion of new `#ifdef''s will be frowned upon.  It's much better
   5796 to write the code portably than to conditionalize it for various
   5797 systems.
   5798 
   5799    New `#ifdef''s which test for specific compilers or manufacturers or
   5800 operating systems are unacceptable.  All `#ifdef''s should test for
   5801 features.  The information about which configurations contain which
   5802 features should be segregated into the configuration files.  Experience
   5803 has proven far too often that a feature unique to one particular system
   5804 often creeps into other systems; and that a conditional based on some
   5805 predefined macro for your current system will become worthless over
   5806 time, as new versions of your system come out that behave differently
   5807 with regard to this feature.
   5808 
   5809    Adding code that handles specific architectures, operating systems,
   5810 target interfaces, or hosts, is not acceptable in generic code.
   5811 
   5812    One particularly notorious area where system dependencies tend to
   5813 creep in is handling of file names.  The mainline GDB code assumes
   5814 Posix semantics of file names: absolute file names begin with a forward
   5815 slash `/', slashes are used to separate leading directories,
   5816 case-sensitive file names.  These assumptions are not necessarily true
   5817 on non-Posix systems such as MS-Windows.  To avoid system-dependent
   5818 code where you need to take apart or construct a file name, use the
   5819 following portable macros:
   5820 
   5821 `HAVE_DOS_BASED_FILE_SYSTEM'
   5822      This preprocessing symbol is defined to a non-zero value on hosts
   5823      whose filesystems belong to the MS-DOS/MS-Windows family.  Use this
   5824      symbol to write conditional code which should only be compiled for
   5825      such hosts.
   5826 
   5827 `IS_DIR_SEPARATOR (C)'
   5828      Evaluates to a non-zero value if C is a directory separator
   5829      character.  On Unix and GNU/Linux systems, only a slash `/' is
   5830      such a character, but on Windows, both `/' and `\' will pass.
   5831 
   5832 `IS_ABSOLUTE_PATH (FILE)'
   5833      Evaluates to a non-zero value if FILE is an absolute file name.
   5834      For Unix and GNU/Linux hosts, a name which begins with a slash `/'
   5835      is absolute.  On DOS and Windows, `d:/foo' and `x:\bar' are also
   5836      absolute file names.
   5837 
   5838 `FILENAME_CMP (F1, F2)'
   5839      Calls a function which compares file names F1 and F2 as
   5840      appropriate for the underlying host filesystem.  For Posix systems,
   5841      this simply calls `strcmp'; on case-insensitive filesystems it
   5842      will call `strcasecmp' instead.
   5843 
   5844 `DIRNAME_SEPARATOR'
   5845      Evaluates to a character which separates directories in
   5846      `PATH'-style lists, typically held in environment variables.  This
   5847      character is `:' on Unix, `;' on DOS and Windows.
   5848 
   5849 `SLASH_STRING'
   5850      This evaluates to a constant string you should use to produce an
   5851      absolute filename from leading directories and the file's basename.
   5852      `SLASH_STRING' is `"/"' on most systems, but might be `"\\"' for
   5853      some Windows-based ports.
   5854 
   5855    In addition to using these macros, be sure to use portable library
   5856 functions whenever possible.  For example, to extract a directory or a
   5857 basename part from a file name, use the `dirname' and `basename'
   5858 library functions (available in `libiberty' for platforms which don't
   5859 provide them), instead of searching for a slash with `strrchr'.
   5860 
   5861    Another way to generalize GDB along a particular interface is with an
   5862 attribute struct.  For example, GDB has been generalized to handle
   5863 multiple kinds of remote interfaces--not by `#ifdef's everywhere, but
   5864 by defining the `target_ops' structure and having a current target (as
   5865 well as a stack of targets below it, for memory references).  Whenever
   5866 something needs to be done that depends on which remote interface we are
   5867 using, a flag in the current target_ops structure is tested (e.g.,
   5868 `target_has_stack'), or a function is called through a pointer in the
   5869 current target_ops structure.  In this way, when a new remote interface
   5870 is added, only one module needs to be touched--the one that actually
   5871 implements the new remote interface.  Other examples of
   5872 attribute-structs are BFD access to multiple kinds of object file
   5873 formats, or GDB's access to multiple source languages.
   5874 
   5875    Please avoid duplicating code.  For example, in GDB 3.x all the code
   5876 interfacing between `ptrace' and the rest of GDB was duplicated in
   5877 `*-dep.c', and so changing something was very painful.  In GDB 4.x,
   5878 these have all been consolidated into `infptrace.c'.  `infptrace.c' can
   5879 deal with variations between systems the same way any system-independent
   5880 file would (hooks, `#if defined', etc.), and machines which are
   5881 radically different don't need to use `infptrace.c' at all.
   5882 
   5883    All debugging code must be controllable using the `set debug MODULE'
   5884 command.  Do not use `printf' to print trace messages.  Use
   5885 `fprintf_unfiltered(gdb_stdlog, ...'.  Do not use `#ifdef DEBUG'.
   5886 
   5887 
   5888 File: gdbint.info,  Node: Porting GDB,  Next: Versions and Branches,  Prev: Coding,  Up: Top
   5889 
   5890 17 Porting GDB
   5891 **************
   5892 
   5893 Most of the work in making GDB compile on a new machine is in
   5894 specifying the configuration of the machine.  Porting a new
   5895 architecture to GDB can be broken into a number of steps.
   5896 
   5897    * Ensure a BFD exists for executables of the target architecture in
   5898      the `bfd' directory.  If one does not exist, create one by
   5899      modifying an existing similar one.
   5900 
   5901    * Implement a disassembler for the target architecture in the
   5902      `opcodes' directory.
   5903 
   5904    * Define the target architecture in the `gdb' directory (*note
   5905      Adding a New Target: Adding a New Target.).  Add the pattern for
   5906      the new target to `configure.tgt' with the names of the files that
   5907      contain the code.  By convention the target architecture
   5908      definition for an architecture ARCH is placed in `ARCH-tdep.c'.
   5909 
   5910      Within `ARCH-tdep.c' define the function `_initialize_ARCH_tdep'
   5911      which calls `gdbarch_register' to create the new `struct gdbarch'
   5912      for the architecture.
   5913 
   5914    * If a new remote target is needed, consider adding a new remote
   5915      target by defining a function `_initialize_remote_ARCH'.  However
   5916      if at all possible use the GDB _Remote Serial Protocol_ for this
   5917      and implement the server side protocol independently with the
   5918      target.
   5919 
   5920    * If desired implement a simulator in the `sim' directory.  This
   5921      should create the library `libsim.a' implementing the interface in
   5922      `remote-sim.h' (found in the `include' directory).
   5923 
   5924    * Build and test.  If desired, lobby the GDB steering group to have
   5925      the new port included in the main distribution!
   5926 
   5927    * Add a description of the new architecture to the main GDB user
   5928      guide (*note Configuration Specific Information:
   5929      (gdb)Configuration Specific Information.).
   5930 
   5931 
   5932 
   5933 File: gdbint.info,  Node: Versions and Branches,  Next: Start of New Year Procedure,  Prev: Porting GDB,  Up: Top
   5934 
   5935 18 Versions and Branches
   5936 ************************
   5937 
   5938 18.1 Versions
   5939 =============
   5940 
   5941 GDB's version is determined by the file `gdb/version.in' and takes one
   5942 of the following forms:
   5943 
   5944 MAJOR.MINOR
   5945 MAJOR.MINOR.PATCHLEVEL
   5946      an official release (e.g., 6.2 or 6.2.1)
   5947 
   5948 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD
   5949      a snapshot taken at YYYY-MM-DD-gmt (e.g., 6.1.50.20020302,
   5950      6.1.90.20020304, or 6.1.0.20020308)
   5951 
   5952 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD-cvs
   5953      a CVS check out drawn on YYYY-MM-DD (e.g., 6.1.50.20020302-cvs,
   5954      6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
   5955 
   5956 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD (VENDOR)
   5957      a vendor specific release of GDB, that while based on
   5958      MAJOR.MINOR.PATCHLEVEL.YYYYMMDD, may include additional changes
   5959 
   5960    GDB's mainline uses the MAJOR and MINOR version numbers from the
   5961 most recent release branch, with a PATCHLEVEL of 50.  At the time each
   5962 new release branch is created, the mainline's MAJOR and MINOR version
   5963 numbers are updated.
   5964 
   5965    GDB's release branch is similar.  When the branch is cut, the
   5966 PATCHLEVEL is changed from 50 to 90.  As draft releases are drawn from
   5967 the branch, the PATCHLEVEL is incremented.  Once the first release
   5968 (MAJOR.MINOR) has been made, the PATCHLEVEL is set to 0 and updates
   5969 have an incremented PATCHLEVEL.
   5970 
   5971    For snapshots, and CVS check outs, it is also possible to identify
   5972 the CVS origin:
   5973 
   5974 MAJOR.MINOR.50.YYYYMMDD
   5975      drawn from the HEAD of mainline CVS (e.g., 6.1.50.20020302)
   5976 
   5977 MAJOR.MINOR.90.YYYYMMDD
   5978 MAJOR.MINOR.91.YYYYMMDD ...
   5979      drawn from a release branch prior to the release (e.g.,
   5980      6.1.90.20020304)
   5981 
   5982 MAJOR.MINOR.0.YYYYMMDD
   5983 MAJOR.MINOR.1.YYYYMMDD ...
   5984      drawn from a release branch after the release (e.g.,
   5985      6.2.0.20020308)
   5986 
   5987    If the previous GDB version is 6.1 and the current version is 6.2,
   5988 then, substituting 6 for MAJOR and 1 or 2 for MINOR, here's an
   5989 illustration of a typical sequence:
   5990 
   5991           <HEAD>
   5992              |
   5993      6.1.50.20020302-cvs
   5994              |
   5995              +--------------------------.
   5996              |                    <gdb_6_2-branch>
   5997              |                          |
   5998      6.2.50.20020303-cvs        6.1.90 (draft #1)
   5999              |                          |
   6000      6.2.50.20020304-cvs        6.1.90.20020304-cvs
   6001              |                          |
   6002      6.2.50.20020305-cvs        6.1.91 (draft #2)
   6003              |                          |
   6004      6.2.50.20020306-cvs        6.1.91.20020306-cvs
   6005              |                          |
   6006      6.2.50.20020307-cvs        6.2 (release)
   6007              |                          |
   6008      6.2.50.20020308-cvs        6.2.0.20020308-cvs
   6009              |                          |
   6010      6.2.50.20020309-cvs        6.2.1 (update)
   6011              |                          |
   6012      6.2.50.20020310-cvs         <branch closed>
   6013              |
   6014      6.2.50.20020311-cvs
   6015              |
   6016              +--------------------------.
   6017              |                     <gdb_6_3-branch>
   6018              |                          |
   6019      6.3.50.20020312-cvs        6.2.90 (draft #1)
   6020              |                          |
   6021 
   6022 18.2 Release Branches
   6023 =====================
   6024 
   6025 GDB draws a release series (6.2, 6.2.1, ...) from a single release
   6026 branch, and identifies that branch using the CVS branch tags:
   6027 
   6028      gdb_MAJOR_MINOR-YYYYMMDD-branchpoint
   6029      gdb_MAJOR_MINOR-branch
   6030      gdb_MAJOR_MINOR-YYYYMMDD-release
   6031 
   6032    _Pragmatics: To help identify the date at which a branch or release
   6033 is made, both the branchpoint and release tags include the date that
   6034 they are cut (YYYYMMDD) in the tag.  The branch tag, denoting the head
   6035 of the branch, does not need this._
   6036 
   6037 18.3 Vendor Branches
   6038 ====================
   6039 
   6040 To avoid version conflicts, vendors are expected to modify the file
   6041 `gdb/version.in' to include a vendor unique alphabetic identifier (an
   6042 official GDB release never uses alphabetic characters in its version
   6043 identifier).  E.g., `6.2widgit2', or `6.2 (Widgit Inc Patch 2)'.
   6044 
   6045 18.4 Experimental Branches
   6046 ==========================
   6047 
   6048 18.4.1 Guidelines
   6049 -----------------
   6050 
   6051 GDB permits the creation of branches, cut from the CVS repository, for
   6052 experimental development.  Branches make it possible for developers to
   6053 share preliminary work, and maintainers to examine significant new
   6054 developments.
   6055 
   6056    The following are a set of guidelines for creating such branches:
   6057 
   6058 _a branch has an owner_
   6059      The owner can set further policy for a branch, but may not change
   6060      the ground rules.  In particular, they can set a policy for
   6061      commits (be it adding more reviewers or deciding who can commit).
   6062 
   6063 _all commits are posted_
   6064      All changes committed to a branch shall also be posted to the GDB
   6065      patches mailing list <gdb-patches (a] sourceware.org>.  While
   6066      commentary on such changes are encouraged, people should remember
   6067      that the changes only apply to a branch.
   6068 
   6069 _all commits are covered by an assignment_
   6070      This ensures that all changes belong to the Free Software
   6071      Foundation, and avoids the possibility that the branch may become
   6072      contaminated.
   6073 
   6074 _a branch is focused_
   6075      A focused branch has a single objective or goal, and does not
   6076      contain unnecessary or irrelevant changes.  Cleanups, where
   6077      identified, being be pushed into the mainline as soon as possible.
   6078 
   6079 _a branch tracks mainline_
   6080      This keeps the level of divergence under control.  It also keeps
   6081      the pressure on developers to push cleanups and other stuff into
   6082      the mainline.
   6083 
   6084 _a branch shall contain the entire GDB module_
   6085      The GDB module `gdb' should be specified when creating a branch
   6086      (branches of individual files should be avoided).  *Note Tags::.
   6087 
   6088 _a branch shall be branded using `version.in'_
   6089      The file `gdb/version.in' shall be modified so that it identifies
   6090      the branch OWNER and branch NAME, e.g.,
   6091      `6.2.50.20030303_owner_name' or `6.2 (Owner Name)'.
   6092 
   6093 
   6094 18.4.2 Tags
   6095 -----------
   6096 
   6097 To simplify the identification of GDB branches, the following branch
   6098 tagging convention is strongly recommended:
   6099 
   6100 `OWNER_NAME-YYYYMMDD-branchpoint'
   6101 `OWNER_NAME-YYYYMMDD-branch'
   6102      The branch point and corresponding branch tag.  YYYYMMDD is the
   6103      date that the branch was created.  A branch is created using the
   6104      sequence:
   6105           cvs rtag OWNER_NAME-YYYYMMDD-branchpoint gdb
   6106           cvs rtag -b -r OWNER_NAME-YYYYMMDD-branchpoint \
   6107              OWNER_NAME-YYYYMMDD-branch gdb
   6108 
   6109 `OWNER_NAME-YYYYMMDD-mergepoint'
   6110      The tagged point, on the mainline, that was used when merging the
   6111      branch on YYYYMMDD.  To merge in all changes since the branch was
   6112      cut, use a command sequence like:
   6113           cvs rtag OWNER_NAME-YYYYMMDD-mergepoint gdb
   6114           cvs update \
   6115              -jOWNER_NAME-YYYYMMDD-branchpoint
   6116              -jOWNER_NAME-YYYYMMDD-mergepoint
   6117      Similar sequences can be used to just merge in changes since the
   6118      last merge.
   6119 
   6120 
   6121 For further information on CVS, see Concurrent Versions System
   6122 (http://www.gnu.org/software/cvs/).
   6123 
   6124 
   6125 File: gdbint.info,  Node: Start of New Year Procedure,  Next: Releasing GDB,  Prev: Versions and Branches,  Up: Top
   6126 
   6127 19 Start of New Year Procedure
   6128 ******************************
   6129 
   6130 At the start of each new year, the following actions should be
   6131 performed:
   6132 
   6133    * Rotate the ChangeLog file
   6134 
   6135      The current `ChangeLog' file should be renamed into
   6136      `ChangeLog-YYYY' where YYYY is the year that has just passed.  A
   6137      new `ChangeLog' file should be created, and its contents should
   6138      contain a reference to the previous ChangeLog.  The following
   6139      should also be preserved at the end of the new ChangeLog, in order
   6140      to provide the appropriate settings when editing this file with
   6141      Emacs:
   6142           Local Variables:
   6143           mode: change-log
   6144           left-margin: 8
   6145           fill-column: 74
   6146           version-control: never
   6147           coding: utf-8
   6148           End:
   6149 
   6150    * Add an entry for the newly created ChangeLog file
   6151      (`ChangeLog-YYYY') in `gdb/config/djgpp/fnchange.lst'.
   6152 
   6153    * Update the copyright year in the startup message
   6154 
   6155      Update the copyright year in:
   6156         *   file `top.c', function `print_gdb_version'
   6157 
   6158         *   file `gdbserver/server.c', function `gdbserver_version'
   6159 
   6160         *   file `gdbserver/gdbreplay.c', function `gdbreplay_version'
   6161 
   6162    * Run the `copyright.sh' script to add the new year in the copyright
   6163      notices of most source files.  This script requires Emacs 22 or
   6164      later to be installed.
   6165 
   6166    * The new year also needs to be added manually in all other files
   6167      that are not already taken care of by the `copyright.sh' script:
   6168         *   `*.s'
   6169 
   6170         *   `*.f'
   6171 
   6172         *   `*.f90'
   6173 
   6174         *   `*.igen'
   6175 
   6176         *   `*.ac'
   6177 
   6178         *   `*.texi'
   6179 
   6180         *   `*.texinfo'
   6181 
   6182         *   `*.tex'
   6183 
   6184         *   `*.defs'
   6185 
   6186         *   `*.1'
   6187 
   6188 
   6189 
   6190 File: gdbint.info,  Node: Releasing GDB,  Next: Testsuite,  Prev: Start of New Year Procedure,  Up: Top
   6191 
   6192 20 Releasing GDB
   6193 ****************
   6194 
   6195 20.1 Branch Commit Policy
   6196 =========================
   6197 
   6198 The branch commit policy is pretty slack.  GDB releases 5.0, 5.1 and
   6199 5.2 all used the below:
   6200 
   6201    * The `gdb/MAINTAINERS' file still holds.
   6202 
   6203    * Don't fix something on the branch unless/until it is also fixed in
   6204      the trunk.  If this isn't possible, mentioning it in the
   6205      `gdb/PROBLEMS' file is better than committing a hack.
   6206 
   6207    * When considering a patch for the branch, suggested criteria
   6208      include: Does it fix a build?  Does it fix the sequence `break
   6209      main; run' when debugging a static binary?
   6210 
   6211    * The further a change is from the core of GDB, the less likely the
   6212      change will worry anyone (e.g., target specific code).
   6213 
   6214    * Only post a proposal to change the core of GDB after you've sent
   6215      individual bribes to all the people listed in the `MAINTAINERS'
   6216      file ;-)
   6217 
   6218    _Pragmatics: Provided updates are restricted to non-core
   6219 functionality there is little chance that a broken change will be fatal.
   6220 This means that changes such as adding a new architectures or (within
   6221 reason) support for a new host are considered acceptable._
   6222 
   6223 20.2 Obsoleting code
   6224 ====================
   6225 
   6226 Before anything else, poke the other developers (and around the source
   6227 code) to see if there is anything that can be removed from GDB (an old
   6228 target, an unused file).
   6229 
   6230    Obsolete code is identified by adding an `OBSOLETE' prefix to every
   6231 line.  Doing this means that it is easy to identify something that has
   6232 been obsoleted when greping through the sources.
   6233 
   6234    The process is done in stages -- this is mainly to ensure that the
   6235 wider GDB community has a reasonable opportunity to respond.  Remember,
   6236 everything on the Internet takes a week.
   6237 
   6238   1. Post the proposal on the GDB mailing list <gdb (a] sourceware.org>
   6239      Creating a bug report to track the task's state, is also highly
   6240      recommended.
   6241 
   6242   2. Wait a week or so.
   6243 
   6244   3. Post the proposal on the GDB Announcement mailing list
   6245      <gdb-announce (a] sourceware.org>.
   6246 
   6247   4. Wait a week or so.
   6248 
   6249   5. Go through and edit all relevant files and lines so that they are
   6250      prefixed with the word `OBSOLETE'.
   6251 
   6252   6. Wait until the next GDB version, containing this obsolete code,
   6253      has been released.
   6254 
   6255   7. Remove the obsolete code.
   6256 
   6257 _Maintainer note: While removing old code is regrettable it is
   6258 hopefully better for GDB's long term development.  Firstly it helps the
   6259 developers by removing code that is either no longer relevant or simply
   6260 wrong.  Secondly since it removes any history associated with the file
   6261 (effectively clearing the slate) the developer has a much freer hand
   6262 when it comes to fixing broken files._
   6263 
   6264 20.3 Before the Branch
   6265 ======================
   6266 
   6267 The most important objective at this stage is to find and fix simple
   6268 changes that become a pain to track once the branch is created.  For
   6269 instance, configuration problems that stop GDB from even building.  If
   6270 you can't get the problem fixed, document it in the `gdb/PROBLEMS' file.
   6271 
   6272 Prompt for `gdb/NEWS'
   6273 ---------------------
   6274 
   6275 People always forget.  Send a post reminding them but also if you know
   6276 something interesting happened add it yourself.  The `schedule' script
   6277 will mention this in its e-mail.
   6278 
   6279 Review `gdb/README'
   6280 -------------------
   6281 
   6282 Grab one of the nightly snapshots and then walk through the
   6283 `gdb/README' looking for anything that can be improved.  The `schedule'
   6284 script will mention this in its e-mail.
   6285 
   6286 Refresh any imported files.
   6287 ---------------------------
   6288 
   6289 A number of files are taken from external repositories.  They include:
   6290 
   6291    * `texinfo/texinfo.tex'
   6292 
   6293    * `config.guess' et. al. (see the top-level `MAINTAINERS' file)
   6294 
   6295    * `etc/standards.texi', `etc/make-stds.texi'
   6296 
   6297 Check the ARI
   6298 -------------
   6299 
   6300 A.R.I. is an `awk' script (Awk Regression Index ;-) that checks for a
   6301 number of errors and coding conventions.  The checks include things
   6302 like using `malloc' instead of `xmalloc' and file naming problems.
   6303 There shouldn't be any regressions.
   6304 
   6305 20.3.1 Review the bug data base
   6306 -------------------------------
   6307 
   6308 Close anything obviously fixed.
   6309 
   6310 20.3.2 Check all cross targets build
   6311 ------------------------------------
   6312 
   6313 The targets are listed in `gdb/MAINTAINERS'.
   6314 
   6315 20.4 Cut the Branch
   6316 ===================
   6317 
   6318 Create the branch
   6319 -----------------
   6320 
   6321      $  u=5.1
   6322      $  v=5.2
   6323      $  V=`echo $v | sed 's/\./_/g'`
   6324      $  D=`date -u +%Y-%m-%d`
   6325      $  echo $u $V $D
   6326      5.1 5_2 2002-03-03
   6327      $  echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
   6328      -D $D-gmt gdb_$V-$D-branchpoint insight
   6329      cvs -f -d :ext:sourceware.org:/cvs/src rtag
   6330      -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
   6331      $  ^echo ^^
   6332      ...
   6333      $  echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
   6334      -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
   6335      cvs -f -d :ext:sourceware.org:/cvs/src rtag \
   6336      -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
   6337      $  ^echo ^^
   6338      ...
   6339      $
   6340 
   6341    * By using `-D YYYY-MM-DD-gmt', the branch is forced to an exact
   6342      date/time.
   6343 
   6344    * The trunk is first tagged so that the branch point can easily be
   6345      found.
   6346 
   6347    * Insight, which includes GDB, is tagged at the same time.
   6348 
   6349    * `version.in' gets bumped to avoid version number conflicts.
   6350 
   6351    * The reading of `.cvsrc' is disabled using `-f'.
   6352 
   6353 Update `version.in'
   6354 -------------------
   6355 
   6356      $  u=5.1
   6357      $  v=5.2
   6358      $  V=`echo $v | sed 's/\./_/g'`
   6359      $  echo $u $v$V
   6360      5.1 5_2
   6361      $  cd /tmp
   6362      $  echo cvs -f -d :ext:sourceware.org:/cvs/src co \
   6363      -r gdb_$V-branch src/gdb/version.in
   6364      cvs -f -d :ext:sourceware.org:/cvs/src co
   6365       -r gdb_5_2-branch src/gdb/version.in
   6366      $  ^echo ^^
   6367      U src/gdb/version.in
   6368      $  cd src/gdb
   6369      $  echo $u.90-0000-00-00-cvs > version.in
   6370      $  cat version.in
   6371      5.1.90-0000-00-00-cvs
   6372      $  cvs -f commit version.in
   6373 
   6374    * `0000-00-00' is used as a date to pump prime the version.in update
   6375      mechanism.
   6376 
   6377    * `.90' and the previous branch version are used as fairly arbitrary
   6378      initial branch version number.
   6379 
   6380 Update the web and news pages
   6381 -----------------------------
   6382 
   6383 Something?
   6384 
   6385 Tweak cron to track the new branch
   6386 ----------------------------------
   6387 
   6388 The file `gdbadmin/cron/crontab' contains gdbadmin's cron table.  This
   6389 file needs to be updated so that:
   6390 
   6391    * A daily timestamp is added to the file `version.in'.
   6392 
   6393    * The new branch is included in the snapshot process.
   6394 
   6395 See the file `gdbadmin/cron/README' for how to install the updated cron
   6396 table.
   6397 
   6398    The file `gdbadmin/ss/README' should also be reviewed to reflect any
   6399 changes.  That file is copied to both the branch/ and current/ snapshot
   6400 directories.
   6401 
   6402 Update the NEWS and README files
   6403 --------------------------------
   6404 
   6405 The `NEWS' file needs to be updated so that on the branch it refers to
   6406 _changes in the current release_ while on the trunk it also refers to
   6407 _changes since the current release_.
   6408 
   6409    The `README' file needs to be updated so that it refers to the
   6410 current release.
   6411 
   6412 Post the branch info
   6413 --------------------
   6414 
   6415 Send an announcement to the mailing lists:
   6416 
   6417    * GDB Announcement mailing list <gdb-announce (a] sourceware.org>
   6418 
   6419    * GDB Discussion mailing list <gdb (a] sourceware.org> and GDB Testers
   6420      mailing list <gdb-testers (a] sourceware.org>
   6421 
   6422    _Pragmatics: The branch creation is sent to the announce list to
   6423 ensure that people people not subscribed to the higher volume discussion
   6424 list are alerted._
   6425 
   6426    The announcement should include:
   6427 
   6428    * The branch tag.
   6429 
   6430    * How to check out the branch using CVS.
   6431 
   6432    * The date/number of weeks until the release.
   6433 
   6434    * The branch commit policy still holds.
   6435 
   6436 20.5 Stabilize the branch
   6437 =========================
   6438 
   6439 Something goes here.
   6440 
   6441 20.6 Create a Release
   6442 =====================
   6443 
   6444 The process of creating and then making available a release is broken
   6445 down into a number of stages.  The first part addresses the technical
   6446 process of creating a releasable tar ball.  The later stages address the
   6447 process of releasing that tar ball.
   6448 
   6449    When making a release candidate just the first section is needed.
   6450 
   6451 20.6.1 Create a release candidate
   6452 ---------------------------------
   6453 
   6454 The objective at this stage is to create a set of tar balls that can be
   6455 made available as a formal release (or as a less formal release
   6456 candidate).
   6457 
   6458 Freeze the branch
   6459 .................
   6460 
   6461 Send out an e-mail notifying everyone that the branch is frozen to
   6462 <gdb-patches (a] sourceware.org>.
   6463 
   6464 Establish a few defaults.
   6465 .........................
   6466 
   6467      $  b=gdb_5_2-branch
   6468      $  v=5.2
   6469      $  t=/sourceware/snapshot-tmp/gdbadmin-tmp
   6470      $  echo $t/$b/$v
   6471      /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
   6472      $  mkdir -p $t/$b/$v
   6473      $  cd $t/$b/$v
   6474      $  pwd
   6475      /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
   6476      $  which autoconf
   6477      /home/gdbadmin/bin/autoconf
   6478      $
   6479 
   6480 Notes:
   6481 
   6482    * Check the `autoconf' version carefully.  You want to be using the
   6483      version documented in the toplevel `README-maintainer-mode' file.
   6484      It is very unlikely that the version of `autoconf' installed in
   6485      system directories (e.g., `/usr/bin/autoconf') is correct.
   6486 
   6487 Check out the relevant modules:
   6488 ...............................
   6489 
   6490      $  for m in gdb insight
   6491      do
   6492      ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
   6493      done
   6494      $
   6495 
   6496 Note:
   6497 
   6498    * The reading of `.cvsrc' is disabled (`-f') so that there isn't any
   6499      confusion between what is written here and what your local `cvs'
   6500      really does.
   6501 
   6502 Update relevant files.
   6503 ......................
   6504 
   6505 `gdb/NEWS'
   6506      Major releases get their comments added as part of the mainline.
   6507      Minor releases should probably mention any significant bugs that
   6508      were fixed.
   6509 
   6510      Don't forget to include the `ChangeLog' entry.
   6511 
   6512           $  emacs gdb/src/gdb/NEWS
   6513           ...
   6514           c-x 4 a
   6515           ...
   6516           c-x c-s c-x c-c
   6517           $  cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
   6518           $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
   6519 
   6520 `gdb/README'
   6521      You'll need to update:
   6522 
   6523         * The version.
   6524 
   6525         * The update date.
   6526 
   6527         * Who did it.
   6528 
   6529           $  emacs gdb/src/gdb/README
   6530           ...
   6531           c-x 4 a
   6532           ...
   6533           c-x c-s c-x c-c
   6534           $  cp gdb/src/gdb/README insight/src/gdb/README
   6535           $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
   6536 
   6537      _Maintainer note: Hopefully the `README' file was reviewed before
   6538      the initial branch was cut so just a simple substitute is needed
   6539      to get it updated._
   6540 
   6541      _Maintainer note: Other projects generate `README' and `INSTALL'
   6542      from the core documentation.  This might be worth pursuing._
   6543 
   6544 `gdb/version.in'
   6545           $  echo $v > gdb/src/gdb/version.in
   6546           $  cat gdb/src/gdb/version.in
   6547           5.2
   6548           $  emacs gdb/src/gdb/version.in
   6549           ...
   6550           c-x 4 a
   6551           ... Bump to version ...
   6552           c-x c-s c-x c-c
   6553           $  cp gdb/src/gdb/version.in insight/src/gdb/version.in
   6554           $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
   6555 
   6556 
   6557 Do the dirty work
   6558 .................
   6559 
   6560 This is identical to the process used to create the daily snapshot.
   6561 
   6562      $  for m in gdb insight
   6563      do
   6564      ( cd $m/src && gmake -f src-release $m.tar )
   6565      done
   6566 
   6567    If the top level source directory does not have `src-release' (GDB
   6568 version 5.3.1 or earlier), try these commands instead:
   6569 
   6570      $  for m in gdb insight
   6571      do
   6572      ( cd $m/src && gmake -f Makefile.in $m.tar )
   6573      done
   6574 
   6575 Check the source files
   6576 ......................
   6577 
   6578 You're looking for files that have mysteriously disappeared.
   6579 `distclean' has the habit of deleting files it shouldn't.  Watch out
   6580 for the `version.in' update `cronjob'.
   6581 
   6582      $  ( cd gdb/src && cvs -f -q -n update )
   6583      M djunpack.bat
   6584      ? gdb-5.1.91.tar
   6585      ? proto-toplev
   6586      ... lots of generated files ...
   6587      M gdb/ChangeLog
   6588      M gdb/NEWS
   6589      M gdb/README
   6590      M gdb/version.in
   6591      ... lots of generated files ...
   6592      $
   6593 
   6594 _Don't worry about the `gdb.info-??' or `gdb/p-exp.tab.c'.  They were
   6595 generated (and yes `gdb.info-1' was also generated only something
   6596 strange with CVS means that they didn't get suppressed).  Fixing it
   6597 would be nice though._
   6598 
   6599 Create compressed versions of the release
   6600 .........................................
   6601 
   6602      $  cp */src/*.tar .
   6603      $  cp */src/*.bz2 .
   6604      $  ls -F
   6605      gdb/ gdb-5.2.tar insight/ insight-5.2.tar
   6606      $  for m in gdb insight
   6607      do
   6608      bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
   6609      gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
   6610      done
   6611      $
   6612 
   6613 Note:
   6614 
   6615    * A pipe such as `bunzip2 < xxx.bz2 | gzip -9 > xxx.gz' is not since,
   6616      in that mode, `gzip' does not know the name of the file and, hence,
   6617      can not include it in the compressed file.  This is also why the
   6618      release process runs `tar' and `bzip2' as separate passes.
   6619 
   6620 20.6.2 Sanity check the tar ball
   6621 --------------------------------
   6622 
   6623 Pick a popular machine (Solaris/PPC?) and try the build on that.
   6624 
   6625      $  bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
   6626      $  cd gdb-5.2
   6627      $  ./configure
   6628      $  make
   6629      ...
   6630      $  ./gdb/gdb ./gdb/gdb
   6631      GNU gdb 5.2
   6632      ...
   6633      (gdb)  b main
   6634      Breakpoint 1 at 0x80732bc: file main.c, line 734.
   6635      (gdb)  run
   6636      Starting program: /tmp/gdb-5.2/gdb/gdb
   6637 
   6638      Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
   6639      734       catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
   6640      (gdb)  print args
   6641      $1 = {argc = 136426532, argv = 0x821b7f0}
   6642      (gdb)
   6643 
   6644 20.6.3 Make a release candidate available
   6645 -----------------------------------------
   6646 
   6647 If this is a release candidate then the only remaining steps are:
   6648 
   6649   1. Commit `version.in' and `ChangeLog'
   6650 
   6651   2. Tweak `version.in' (and `ChangeLog' to read L.M.N-0000-00-00-cvs
   6652      so that the version update process can restart.
   6653 
   6654   3. Make the release candidate available in
   6655      `ftp://sourceware.org/pub/gdb/snapshots/branch'
   6656 
   6657   4. Notify the relevant mailing lists ( <gdb (a] sourceware.org> and
   6658      <gdb-testers (a] sourceware.org> that the candidate is available.
   6659 
   6660 20.6.4 Make a formal release available
   6661 --------------------------------------
   6662 
   6663 (And you thought all that was required was to post an e-mail.)
   6664 
   6665 Install on sware
   6666 ................
   6667 
   6668 Copy the new files to both the release and the old release directory:
   6669 
   6670      $  cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
   6671      $  cp *.bz2 *.gz ~ftp/pub/gdb/releases
   6672 
   6673 Clean up the releases directory so that only the most recent releases
   6674 are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
   6675 
   6676      $  cd ~ftp/pub/gdb/releases
   6677      $  rm ...
   6678 
   6679 Update the file `README' and `.message' in the releases directory:
   6680 
   6681      $  vi README
   6682      ...
   6683      $  rm -f .message
   6684      $  ln README .message
   6685 
   6686 Update the web pages.
   6687 .....................
   6688 
   6689 `htdocs/download/ANNOUNCEMENT'
   6690      This file, which is posted as the official announcement, includes:
   6691         * General announcement.
   6692 
   6693         * News.  If making an M.N.1 release, retain the news from
   6694           earlier M.N release.
   6695 
   6696         * Errata.
   6697 
   6698 `htdocs/index.html'
   6699 `htdocs/news/index.html'
   6700 `htdocs/download/index.html'
   6701      These files include:
   6702         * Announcement of the most recent release.
   6703 
   6704         * News entry (remember to update both the top level and the
   6705           news directory).
   6706      These pages also need to be regenerate using `index.sh'.
   6707 
   6708 `download/onlinedocs/'
   6709      You need to find the magic command that is used to generate the
   6710      online docs from the `.tar.bz2'.  The best way is to look in the
   6711      output from one of the nightly `cron' jobs and then just edit
   6712      accordingly.  Something like:
   6713 
   6714           $  ~/ss/update-web-docs \
   6715            ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
   6716            $PWD/www \
   6717            /www/sourceware/htdocs/gdb/download/onlinedocs \
   6718            gdb
   6719 
   6720 `download/ari/'
   6721      Just like the online documentation.  Something like:
   6722 
   6723           $  /bin/sh ~/ss/update-web-ari \
   6724            ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
   6725            $PWD/www \
   6726            /www/sourceware/htdocs/gdb/download/ari \
   6727            gdb
   6728 
   6729 
   6730 Shadow the pages onto gnu
   6731 .........................
   6732 
   6733 Something goes here.
   6734 
   6735 Install the GDB tar ball on GNU
   6736 ...............................
   6737 
   6738 At the time of writing, the GNU machine was `gnudist.gnu.org' in
   6739 `~ftp/gnu/gdb'.
   6740 
   6741 Make the `ANNOUNCEMENT'
   6742 .......................
   6743 
   6744 Post the `ANNOUNCEMENT' file you created above to:
   6745 
   6746    * GDB Announcement mailing list <gdb-announce (a] sourceware.org>
   6747 
   6748    * General GNU Announcement list <info-gnu (a] gnu.org> (but delay it a
   6749      day or so to let things get out)
   6750 
   6751    * GDB Bug Report mailing list <bug-gdb (a] gnu.org>
   6752 
   6753 20.6.5 Cleanup
   6754 --------------
   6755 
   6756 The release is out but you're still not finished.
   6757 
   6758 Commit outstanding changes
   6759 ..........................
   6760 
   6761 In particular you'll need to commit any changes to:
   6762 
   6763    * `gdb/ChangeLog'
   6764 
   6765    * `gdb/version.in'
   6766 
   6767    * `gdb/NEWS'
   6768 
   6769    * `gdb/README'
   6770 
   6771 Tag the release
   6772 ...............
   6773 
   6774 Something like:
   6775 
   6776      $  d=`date -u +%Y-%m-%d`
   6777      $  echo $d
   6778      2002-01-24
   6779      $  ( cd insight/src/gdb && cvs -f -q update )
   6780      $  ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
   6781 
   6782    Insight is used since that contains more of the release than GDB.
   6783 
   6784 Mention the release on the trunk
   6785 ................................
   6786 
   6787 Just put something in the `ChangeLog' so that the trunk also indicates
   6788 when the release was made.
   6789 
   6790 Restart `gdb/version.in'
   6791 ........................
   6792 
   6793 If `gdb/version.in' does not contain an ISO date such as `2002-01-24'
   6794 then the daily `cronjob' won't update it.  Having committed all the
   6795 release changes it can be set to `5.2.0_0000-00-00-cvs' which will
   6796 restart things (yes the `_' is important - it affects the snapshot
   6797 process).
   6798 
   6799    Don't forget the `ChangeLog'.
   6800 
   6801 Merge into trunk
   6802 ................
   6803 
   6804 The files committed to the branch may also need changes merged into the
   6805 trunk.
   6806 
   6807 Revise the release schedule
   6808 ...........................
   6809 
   6810 Post a revised release schedule to GDB Discussion List
   6811 <gdb (a] sourceware.org> with an updated announcement.  The schedule can be
   6812 generated by running:
   6813 
   6814      $  ~/ss/schedule `date +%s` schedule
   6815 
   6816 The first parameter is approximate date/time in seconds (from the epoch)
   6817 of the most recent release.
   6818 
   6819    Also update the schedule `cronjob'.
   6820 
   6821 20.7 Post release
   6822 =================
   6823 
   6824 Remove any `OBSOLETE' code.
   6825 
   6826 
   6827 File: gdbint.info,  Node: Testsuite,  Next: Hints,  Prev: Releasing GDB,  Up: Top
   6828 
   6829 21 Testsuite
   6830 ************
   6831 
   6832 The testsuite is an important component of the GDB package.  While it
   6833 is always worthwhile to encourage user testing, in practice this is
   6834 rarely sufficient; users typically use only a small subset of the
   6835 available commands, and it has proven all too common for a change to
   6836 cause a significant regression that went unnoticed for some time.
   6837 
   6838    The GDB testsuite uses the DejaGNU testing framework.  The tests
   6839 themselves are calls to various `Tcl' procs; the framework runs all the
   6840 procs and summarizes the passes and fails.
   6841 
   6842 21.1 Using the Testsuite
   6843 ========================
   6844 
   6845 To run the testsuite, simply go to the GDB object directory (or to the
   6846 testsuite's objdir) and type `make check'.  This just sets up some
   6847 environment variables and invokes DejaGNU's `runtest' script.  While
   6848 the testsuite is running, you'll get mentions of which test file is in
   6849 use, and a mention of any unexpected passes or fails.  When the
   6850 testsuite is finished, you'll get a summary that looks like this:
   6851 
   6852                      === gdb Summary ===
   6853 
   6854      # of expected passes            6016
   6855      # of unexpected failures        58
   6856      # of unexpected successes       5
   6857      # of expected failures          183
   6858      # of unresolved testcases       3
   6859      # of untested testcases         5
   6860 
   6861    To run a specific test script, type:
   6862      make check RUNTESTFLAGS='TESTS'
   6863    where TESTS is a list of test script file names, separated by spaces.
   6864 
   6865    If you use GNU make, you can use its `-j' option to run the
   6866 testsuite in parallel.  This can greatly reduce the amount of time it
   6867 takes for the testsuite to run.  In this case, if you set
   6868 `RUNTESTFLAGS' then, by default, the tests will be run serially even
   6869 under `-j'.  You can override this and force a parallel run by setting
   6870 the `make' variable `FORCE_PARALLEL' to any non-empty value.  Note that
   6871 the parallel `make check' assumes that you want to run the entire
   6872 testsuite, so it is not compatible with some dejagnu options, like
   6873 `--directory'.
   6874 
   6875    The ideal test run consists of expected passes only; however, reality
   6876 conspires to keep us from this ideal.  Unexpected failures indicate
   6877 real problems, whether in GDB or in the testsuite.  Expected failures
   6878 are still failures, but ones which have been decided are too hard to
   6879 deal with at the time; for instance, a test case might work everywhere
   6880 except on AIX, and there is no prospect of the AIX case being fixed in
   6881 the near future.  Expected failures should not be added lightly, since
   6882 you may be masking serious bugs in GDB.  Unexpected successes are
   6883 expected fails that are passing for some reason, while unresolved and
   6884 untested cases often indicate some minor catastrophe, such as the
   6885 compiler being unable to deal with a test program.
   6886 
   6887    When making any significant change to GDB, you should run the
   6888 testsuite before and after the change, to confirm that there are no
   6889 regressions.  Note that truly complete testing would require that you
   6890 run the testsuite with all supported configurations and a variety of
   6891 compilers; however this is more than really necessary.  In many cases
   6892 testing with a single configuration is sufficient.  Other useful
   6893 options are to test one big-endian (Sparc) and one little-endian (x86)
   6894 host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
   6895 or a 64-bit host (Alpha).
   6896 
   6897    If you add new functionality to GDB, please consider adding tests
   6898 for it as well; this way future GDB hackers can detect and fix their
   6899 changes that break the functionality you added.  Similarly, if you fix
   6900 a bug that was not previously reported as a test failure, please add a
   6901 test case for it.  Some cases are extremely difficult to test, such as
   6902 code that handles host OS failures or bugs in particular versions of
   6903 compilers, and it's OK not to try to write tests for all of those.
   6904 
   6905    DejaGNU supports separate build, host, and target machines.  However,
   6906 some GDB test scripts do not work if the build machine and the host
   6907 machine are not the same.  In such an environment, these scripts will
   6908 give a result of "UNRESOLVED", like this:
   6909 
   6910      UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
   6911 
   6912 21.2 Testsuite Parameters
   6913 =========================
   6914 
   6915 Several variables exist to modify the behavior of the testsuite.
   6916 
   6917    * `TRANSCRIPT'
   6918 
   6919      Sometimes it is convenient to get a transcript of the commands
   6920      which the testsuite sends to GDB.  For example, if GDB crashes
   6921      during testing, a transcript can be used to more easily
   6922      reconstruct the failure when running GDB under GDB.
   6923 
   6924      You can instruct the GDB testsuite to write transcripts by setting
   6925      the DejaGNU variable `TRANSCRIPT' (to any value) before invoking
   6926      `runtest' or `make check'.  The transcripts will be written into
   6927      DejaGNU's output directory.  One transcript will be made for each
   6928      invocation of GDB; they will be named `transcript.N', where N is
   6929      an integer.  The first line of the transcript file will show how
   6930      GDB was invoked; each subsequent line is a command sent as input
   6931      to GDB.
   6932 
   6933           make check RUNTESTFLAGS=TRANSCRIPT=y
   6934 
   6935      Note that the transcript is not always complete.  In particular,
   6936      tests of completion can yield partial command lines.
   6937 
   6938    * `GDB'
   6939 
   6940      Sometimes one wishes to test a different GDB than the one in the
   6941      build directory.  For example, one may wish to run the testsuite on
   6942      `/usr/bin/gdb'.
   6943 
   6944           make check RUNTESTFLAGS=GDB=/usr/bin/gdb
   6945 
   6946    * `GDBSERVER'
   6947 
   6948      When testing a different GDB, it is often useful to also test a
   6949      different gdbserver.
   6950 
   6951           make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
   6952 
   6953    * `INTERNAL_GDBFLAGS'
   6954 
   6955      When running the testsuite normally one doesn't want whatever is in
   6956      `~/.gdbinit' to interfere with the tests, therefore the test
   6957      harness passes `-nx' to GDB.  One also doesn't want any windowed
   6958      version of GDB, e.g., `gdbtui', to run.  This is achieved via
   6959      `INTERNAL_GDBFLAGS'.
   6960 
   6961           set INTERNAL_GDBFLAGS "-nw -nx"
   6962 
   6963      This is all well and good, except when testing an installed GDB
   6964      that has been configured with `--with-system-gdbinit'.  Here one
   6965      does not want `~/.gdbinit' loaded but one may want the system
   6966      `.gdbinit' file loaded.  This can be achieved by pointing `$HOME'
   6967      at a directory without a `.gdbinit' and by overriding
   6968      `INTERNAL_GDBFLAGS' and removing `-nx'.
   6969 
   6970           cd testsuite
   6971           HOME=`pwd` runtest \
   6972             GDB=/usr/bin/gdb \
   6973             GDBSERVER=/usr/bin/gdbserver \
   6974             INTERNAL_GDBFLAGS=-nw
   6975 
   6976 
   6977    There are two ways to run the testsuite and pass additional
   6978 parameters to DejaGnu.  The first is with `make check' and specifying
   6979 the makefile variable `RUNTESTFLAGS'.
   6980 
   6981      make check RUNTESTFLAGS=TRANSCRIPT=y
   6982 
   6983    The second is to cd to the `testsuite' directory and invoke the
   6984 DejaGnu `runtest' command directly.
   6985 
   6986      cd testsuite
   6987      make site.exp
   6988      runtest TRANSCRIPT=y
   6989 
   6990 21.3 Testsuite Configuration
   6991 ============================
   6992 
   6993 It is possible to adjust the behavior of the testsuite by defining the
   6994 global variables listed below, either in a `site.exp' file, or in a
   6995 board file.
   6996 
   6997    * `gdb_test_timeout'
   6998 
   6999      Defining this variable changes the default timeout duration used
   7000      during communication with GDB.  More specifically, the global
   7001      variable used during testing is `timeout', but this variable gets
   7002      reset to `gdb_test_timeout' at the beginning of each testcase,
   7003      making sure that any local change to `timeout' in a testcase does
   7004      not affect subsequent testcases.
   7005 
   7006      This global variable comes in handy when the debugger is slower
   7007      than normal due to the testing environment, triggering unexpected
   7008      `TIMEOUT' test failures.  Examples include when testing on a
   7009      remote machine, or against a system where communications are slow.
   7010 
   7011      If not specifically defined, this variable gets automatically
   7012      defined to the same value as `timeout' during the testsuite
   7013      initialization.  The default value of the timeout is defined in
   7014      the file `gdb/testsuite/config/unix.exp' that is part of the GDB
   7015      test suite(1).
   7016 
   7017 
   7018 21.4 Testsuite Organization
   7019 ===========================
   7020 
   7021 The testsuite is entirely contained in `gdb/testsuite'.  While the
   7022 testsuite includes some makefiles and configury, these are very minimal,
   7023 and used for little besides cleaning up, since the tests themselves
   7024 handle the compilation of the programs that GDB will run.  The file
   7025 `testsuite/lib/gdb.exp' contains common utility procs useful for all
   7026 GDB tests, while the directory `testsuite/config' contains
   7027 configuration-specific files, typically used for special-purpose
   7028 definitions of procs like `gdb_load' and `gdb_start'.
   7029 
   7030    The tests themselves are to be found in `testsuite/gdb.*' and
   7031 subdirectories of those.  The names of the test files must always end
   7032 with `.exp'.  DejaGNU collects the test files by wildcarding in the
   7033 test directories, so both subdirectories and individual files get
   7034 chosen and run in alphabetical order.
   7035 
   7036    The following table lists the main types of subdirectories and what
   7037 they are for.  Since DejaGNU finds test files no matter where they are
   7038 located, and since each test file sets up its own compilation and
   7039 execution environment, this organization is simply for convenience and
   7040 intelligibility.
   7041 
   7042 `gdb.base'
   7043      This is the base testsuite.  The tests in it should apply to all
   7044      configurations of GDB (but generic native-only tests may live
   7045      here).  The test programs should be in the subset of C that is
   7046      valid K&R, ANSI/ISO, and C++ (`#ifdef's are allowed if necessary,
   7047      for instance for prototypes).
   7048 
   7049 `gdb.LANG'
   7050      Language-specific tests for any language LANG besides C.  Examples
   7051      are `gdb.cp' and `gdb.java'.
   7052 
   7053 `gdb.PLATFORM'
   7054      Non-portable tests.  The tests are specific to a specific
   7055      configuration (host or target), such as HP-UX or eCos.  Example is
   7056      `gdb.hp', for HP-UX.
   7057 
   7058 `gdb.COMPILER'
   7059      Tests specific to a particular compiler.  As of this writing (June
   7060      1999), there aren't currently any groups of tests in this category
   7061      that couldn't just as sensibly be made platform-specific, but one
   7062      could imagine a `gdb.gcc', for tests of GDB's handling of GCC
   7063      extensions.
   7064 
   7065 `gdb.SUBSYSTEM'
   7066      Tests that exercise a specific GDB subsystem in more depth.  For
   7067      instance, `gdb.disasm' exercises various disassemblers, while
   7068      `gdb.stabs' tests pathways through the stabs symbol reader.
   7069 
   7070 21.5 Writing Tests
   7071 ==================
   7072 
   7073 In many areas, the GDB tests are already quite comprehensive; you
   7074 should be able to copy existing tests to handle new cases.
   7075 
   7076    You should try to use `gdb_test' whenever possible, since it
   7077 includes cases to handle all the unexpected errors that might happen.
   7078 However, it doesn't cost anything to add new test procedures; for
   7079 instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
   7080 `gdb_test' multiple times.
   7081 
   7082    Only use `send_gdb' and `gdb_expect' when absolutely necessary.
   7083 Even if GDB has several valid responses to a command, you can use
   7084 `gdb_test_multiple'.  Like `gdb_test', `gdb_test_multiple' recognizes
   7085 internal errors and unexpected prompts.
   7086 
   7087    Do not write tests which expect a literal tab character from GDB.
   7088 On some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
   7089 spaces, so by the time GDB's output reaches expect the tab is gone.
   7090 
   7091    The source language programs do _not_ need to be in a consistent
   7092 style.  Since GDB is used to debug programs written in many different
   7093 styles, it's worth having a mix of styles in the testsuite; for
   7094 instance, some GDB bugs involving the display of source lines would
   7095 never manifest themselves if the programs used GNU coding style
   7096 uniformly.
   7097 
   7098    ---------- Footnotes ----------
   7099 
   7100    (1) If you are using a board file, it could override the test-suite
   7101 default; search the board file for "timeout".
   7102 
   7103 
   7104 File: gdbint.info,  Node: Hints,  Next: GDB Observers,  Prev: Testsuite,  Up: Top
   7105 
   7106 22 Hints
   7107 ********
   7108 
   7109 Check the `README' file, it often has useful information that does not
   7110 appear anywhere else in the directory.
   7111 
   7112 * Menu:
   7113 
   7114 * Getting Started::		Getting started working on GDB
   7115 * Debugging GDB::		Debugging GDB with itself
   7116 
   7117 
   7118 File: gdbint.info,  Node: Getting Started,  Up: Hints
   7119 
   7120 22.1 Getting Started
   7121 ====================
   7122 
   7123 GDB is a large and complicated program, and if you first starting to
   7124 work on it, it can be hard to know where to start.  Fortunately, if you
   7125 know how to go about it, there are ways to figure out what is going on.
   7126 
   7127    This manual, the GDB Internals manual, has information which applies
   7128 generally to many parts of GDB.
   7129 
   7130    Information about particular functions or data structures are
   7131 located in comments with those functions or data structures.  If you
   7132 run across a function or a global variable which does not have a
   7133 comment correctly explaining what is does, this can be thought of as a
   7134 bug in GDB; feel free to submit a bug report, with a suggested comment
   7135 if you can figure out what the comment should say.  If you find a
   7136 comment which is actually wrong, be especially sure to report that.
   7137 
   7138    Comments explaining the function of macros defined in host, target,
   7139 or native dependent files can be in several places.  Sometimes they are
   7140 repeated every place the macro is defined.  Sometimes they are where the
   7141 macro is used.  Sometimes there is a header file which supplies a
   7142 default definition of the macro, and the comment is there.  This manual
   7143 also documents all the available macros.
   7144 
   7145    Start with the header files.  Once you have some idea of how GDB's
   7146 internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
   7147 will find it much easier to understand the code which uses and creates
   7148 those symbol tables.
   7149 
   7150    You may wish to process the information you are getting somehow, to
   7151 enhance your understanding of it.  Summarize it, translate it to another
   7152 language, add some (perhaps trivial or non-useful) feature to GDB, use
   7153 the code to predict what a test case would do and write the test case
   7154 and verify your prediction, etc.  If you are reading code and your eyes
   7155 are starting to glaze over, this is a sign you need to use a more active
   7156 approach.
   7157 
   7158    Once you have a part of GDB to start with, you can find more
   7159 specifically the part you are looking for by stepping through each
   7160 function with the `next' command.  Do not use `step' or you will
   7161 quickly get distracted; when the function you are stepping through
   7162 calls another function try only to get a big-picture understanding
   7163 (perhaps using the comment at the beginning of the function being
   7164 called) of what it does.  This way you can identify which of the
   7165 functions being called by the function you are stepping through is the
   7166 one which you are interested in.  You may need to examine the data
   7167 structures generated at each stage, with reference to the comments in
   7168 the header files explaining what the data structures are supposed to
   7169 look like.
   7170 
   7171    Of course, this same technique can be used if you are just reading
   7172 the code, rather than actually stepping through it.  The same general
   7173 principle applies--when the code you are looking at calls something
   7174 else, just try to understand generally what the code being called does,
   7175 rather than worrying about all its details.
   7176 
   7177    A good place to start when tracking down some particular area is with
   7178 a command which invokes that feature.  Suppose you want to know how
   7179 single-stepping works.  As a GDB user, you know that the `step' command
   7180 invokes single-stepping.  The command is invoked via command tables
   7181 (see `command.h'); by convention the function which actually performs
   7182 the command is formed by taking the name of the command and adding
   7183 `_command', or in the case of an `info' subcommand, `_info'.  For
   7184 example, the `step' command invokes the `step_command' function and the
   7185 `info display' command invokes `display_info'.  When this convention is
   7186 not followed, you might have to use `grep' or `M-x tags-search' in
   7187 emacs, or run GDB on itself and set a breakpoint in `execute_command'.
   7188 
   7189    If all of the above fail, it may be appropriate to ask for
   7190 information on `bug-gdb'.  But _never_ post a generic question like "I
   7191 was wondering if anyone could give me some tips about understanding
   7192 GDB"--if we had some magic secret we would put it in this manual.
   7193 Suggestions for improving the manual are always welcome, of course.
   7194 
   7195 
   7196 File: gdbint.info,  Node: Debugging GDB,  Up: Hints
   7197 
   7198 22.2 Debugging GDB with itself
   7199 ==============================
   7200 
   7201 If GDB is limping on your machine, this is the preferred way to get it
   7202 fully functional.  Be warned that in some ancient Unix systems, like
   7203 Ultrix 4.2, a program can't be running in one process while it is being
   7204 debugged in another.  Rather than typing the command `./gdb ./gdb',
   7205 which works on Suns and such, you can copy `gdb' to `gdb2' and then
   7206 type `./gdb ./gdb2'.
   7207 
   7208    When you run GDB in the GDB source directory, it will read a
   7209 `.gdbinit' file that sets up some simple things to make debugging gdb
   7210 easier.  The `info' command, when executed without a subcommand in a
   7211 GDB being debugged by gdb, will pop you back up to the top level gdb.
   7212 See `.gdbinit' for details.
   7213 
   7214    If you use emacs, you will probably want to do a `make TAGS' after
   7215 you configure your distribution; this will put the machine dependent
   7216 routines for your local machine where they will be accessed first by
   7217 `M-.'
   7218 
   7219    Also, make sure that you've either compiled GDB with your local cc,
   7220 or have run `fixincludes' if you are compiling with gcc.
   7221 
   7222 22.3 Submitting Patches
   7223 =======================
   7224 
   7225 Thanks for thinking of offering your changes back to the community of
   7226 GDB users.  In general we like to get well designed enhancements.
   7227 Thanks also for checking in advance about the best way to transfer the
   7228 changes.
   7229 
   7230    The GDB maintainers will only install "cleanly designed" patches.
   7231 This manual summarizes what we believe to be clean design for GDB.
   7232 
   7233    If the maintainers don't have time to put the patch in when it
   7234 arrives, or if there is any question about a patch, it goes into a
   7235 large queue with everyone else's patches and bug reports.
   7236 
   7237    The legal issue is that to incorporate substantial changes requires a
   7238 copyright assignment from you and/or your employer, granting ownership
   7239 of the changes to the Free Software Foundation.  You can get the
   7240 standard documents for doing this by sending mail to `gnu (a] gnu.org' and
   7241 asking for it.  We recommend that people write in "All programs owned
   7242 by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
   7243 in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
   7244 contributed with only one piece of legalese pushed through the
   7245 bureaucracy and filed with the FSF.  We can't start merging changes
   7246 until this paperwork is received by the FSF (their rules, which we
   7247 follow since we maintain it for them).
   7248 
   7249    Technically, the easiest way to receive changes is to receive each
   7250 feature as a small context diff or unidiff, suitable for `patch'.  Each
   7251 message sent to me should include the changes to C code and header
   7252 files for a single feature, plus `ChangeLog' entries for each directory
   7253 where files were modified, and diffs for any changes needed to the
   7254 manuals (`gdb/doc/gdb.texinfo' or `gdb/doc/gdbint.texinfo').  If there
   7255 are a lot of changes for a single feature, they can be split down into
   7256 multiple messages.
   7257 
   7258    In this way, if we read and like the feature, we can add it to the
   7259 sources with a single patch command, do some testing, and check it in.
   7260 If you leave out the `ChangeLog', we have to write one.  If you leave
   7261 out the doc, we have to puzzle out what needs documenting.  Etc., etc.
   7262 
   7263    The reason to send each change in a separate message is that we will
   7264 not install some of the changes.  They'll be returned to you with
   7265 questions or comments.  If we're doing our job correctly, the message
   7266 back to you will say what you have to fix in order to make the change
   7267 acceptable.  The reason to have separate messages for separate features
   7268 is so that the acceptable changes can be installed while one or more
   7269 changes are being reworked.  If multiple features are sent in a single
   7270 message, we tend to not put in the effort to sort out the acceptable
   7271 changes from the unacceptable, so none of the features get installed
   7272 until all are acceptable.
   7273 
   7274    If this sounds painful or authoritarian, well, it is.  But we get a
   7275 lot of bug reports and a lot of patches, and many of them don't get
   7276 installed because we don't have the time to finish the job that the bug
   7277 reporter or the contributor could have done.  Patches that arrive
   7278 complete, working, and well designed, tend to get installed on the day
   7279 they arrive.  The others go into a queue and get installed as time
   7280 permits, which, since the maintainers have many demands to meet, may not
   7281 be for quite some time.
   7282 
   7283    Please send patches directly to the GDB maintainers
   7284 <gdb-patches (a] sourceware.org>.
   7285 
   7286 22.4 Build Script
   7287 =================
   7288 
   7289 The script `gdb_buildall.sh' builds GDB with flag
   7290 `--enable-targets=all' set.  This builds GDB with all supported targets
   7291 activated.  This helps testing GDB when doing changes that affect more
   7292 than one architecture and is much faster than using `gdb_mbuild.sh'.
   7293 
   7294    After building GDB the script checks which architectures are
   7295 supported and then switches the current architecture to each of those
   7296 to get information about the architecture.  The test results are stored
   7297 in log files in the directory the script was called from.
   7298 
   7299 
   7300 File: gdbint.info,  Node: GDB Observers,  Next: GNU Free Documentation License,  Prev: Hints,  Up: Top
   7301 
   7302 Appendix A GDB Currently available observers
   7303 ********************************************
   7304 
   7305 A.1 Implementation rationale
   7306 ============================
   7307 
   7308 An "observer" is an entity which is interested in being notified when
   7309 GDB reaches certain states, or certain events occur in GDB.  The entity
   7310 being observed is called the "subject".  To receive notifications, the
   7311 observer attaches a callback to the subject.  One subject can have
   7312 several observers.
   7313 
   7314    `observer.c' implements an internal generic low-level event
   7315 notification mechanism.  This generic event notification mechanism is
   7316 then re-used to implement the exported high-level notification
   7317 management routines for all possible notifications.
   7318 
   7319    The current implementation of the generic observer provides support
   7320 for contextual data.  This contextual data is given to the subject when
   7321 attaching the callback.  In return, the subject will provide this
   7322 contextual data back to the observer as a parameter of the callback.
   7323 
   7324    Note that the current support for the contextual data is only
   7325 partial, as it lacks a mechanism that would deallocate this data when
   7326 the callback is detached.  This is not a problem so far, as this
   7327 contextual data is only used internally to hold a function pointer.
   7328 Later on, if a certain observer needs to provide support for user-level
   7329 contextual data, then the generic notification mechanism will need to be
   7330 enhanced to allow the observer to provide a routine to deallocate the
   7331 data when attaching the callback.
   7332 
   7333    The observer implementation is also currently not reentrant.  In
   7334 particular, it is therefore not possible to call the attach or detach
   7335 routines during a notification.
   7336 
   7337 A.2 Debugging
   7338 =============
   7339 
   7340 Observer notifications can be traced using the command `set debug
   7341 observer 1' (*note Optional messages about internal happenings:
   7342 (gdb)Debugging Output.).
   7343 
   7344 A.3 `normal_stop' Notifications
   7345 ===============================
   7346 
   7347 GDB notifies all `normal_stop' observers when the inferior execution
   7348 has just stopped, the associated messages and annotations have been
   7349 printed, and the control is about to be returned to the user.
   7350 
   7351    Note that the `normal_stop' notification is not emitted when the
   7352 execution stops due to a breakpoint, and this breakpoint has a
   7353 condition that is not met.  If the breakpoint has any associated
   7354 commands list, the commands are executed after the notification is
   7355 emitted.
   7356 
   7357    The following interfaces are available to manage observers:
   7358 
   7359  -- Function: extern struct observer *observer_attach_EVENT
   7360           (observer_EVENT_ftype *F)
   7361      Using the function F, create an observer that is notified when
   7362      ever EVENT occurs, return the observer.
   7363 
   7364  -- Function: extern void observer_detach_EVENT (struct observer
   7365           *OBSERVER);
   7366      Remove OBSERVER from the list of observers to be notified when
   7367      EVENT occurs.
   7368 
   7369  -- Function: extern void observer_notify_EVENT (void);
   7370      Send a notification to all EVENT observers.
   7371 
   7372    The following observable events are defined:
   7373 
   7374  -- Function: void normal_stop (struct bpstats *BS, int PRINT_FRAME)
   7375      The inferior has stopped for real.  The  BS argument describes the
   7376      breakpoints were are stopped at, if any.  Second argument
   7377      PRINT_FRAME non-zero means display the location where the inferior
   7378      has stopped.
   7379 
   7380  -- Function: void target_changed (struct target_ops *TARGET)
   7381      The target's register contents have changed.
   7382 
   7383  -- Function: void executable_changed (void)
   7384      The executable being debugged by GDB has changed: The user decided
   7385      to debug a different program, or the program he was debugging has
   7386      been modified since being loaded by the debugger (by being
   7387      recompiled, for instance).
   7388 
   7389  -- Function: void inferior_created (struct target_ops *OBJFILE, int
   7390           FROM_TTY)
   7391      GDB has just connected to an inferior.  For `run', GDB calls this
   7392      observer while the inferior is still stopped at the entry-point
   7393      instruction.  For `attach' and `core', GDB calls this observer
   7394      immediately after connecting to the inferior, and before any
   7395      information on the inferior has been printed.
   7396 
   7397  -- Function: void solib_loaded (struct so_list *SOLIB)
   7398      The shared library specified by SOLIB has been loaded.  Note that
   7399      when GDB calls this observer, the library's symbols probably
   7400      haven't been loaded yet.
   7401 
   7402  -- Function: void solib_unloaded (struct so_list *SOLIB)
   7403      The shared library specified by SOLIB has been unloaded.  Note
   7404      that when GDB calls this observer, the library's symbols have not
   7405      been unloaded yet, and thus are still available.
   7406 
   7407  -- Function: void new_objfile (struct objfile *OBJFILE)
   7408      The symbol file specified by OBJFILE has been loaded.  Called with
   7409      OBJFILE equal to `NULL' to indicate previously loaded symbol table
   7410      data has now been invalidated.
   7411 
   7412  -- Function: void new_thread (struct thread_info *T)
   7413      The thread specified by T has been created.
   7414 
   7415  -- Function: void thread_exit (struct thread_info *T, int SILENT)
   7416      The thread specified by T has exited.  The SILENT argument
   7417      indicates that GDB is removing the thread from its tables without
   7418      wanting to notify the user about it.
   7419 
   7420  -- Function: void thread_stop_requested (ptid_t PTID)
   7421      An explicit stop request was issued to PTID.  If PTID equals
   7422      MINUS_ONE_PTID, the request applied to all threads.  If
   7423      `ptid_is_pid(ptid)' returns true, the request applied to all
   7424      threads of the process pointed at by PTID.  Otherwise, the request
   7425      applied to the single thread pointed at by PTID.
   7426 
   7427  -- Function: void target_resumed (ptid_t PTID)
   7428      The target was resumed.  The PTID parameter specifies which thread
   7429      was resume, and may be RESUME_ALL if all threads are resumed.
   7430 
   7431  -- Function: void about_to_proceed (void)
   7432      The target is about to be proceeded.
   7433 
   7434  -- Function: void breakpoint_created (int BPNUM)
   7435      A new breakpoint has been created.  The argument BPNUM is the
   7436      number of the newly-created breakpoint.
   7437 
   7438  -- Function: void breakpoint_deleted (int BPNUM)
   7439      A breakpoint has been destroyed.  The argument BPNUM is the number
   7440      of the newly-destroyed breakpoint.
   7441 
   7442  -- Function: void breakpoint_modified (int BPNUM)
   7443      A breakpoint has been modified in some way.  The argument BPNUM is
   7444      the number of the modified breakpoint.
   7445 
   7446  -- Function: void tracepoint_created (int TPNUM)
   7447      A new tracepoint has been created.  The argument TPNUM is the
   7448      number of the newly-created tracepoint.
   7449 
   7450  -- Function: void tracepoint_deleted (int TPNUM)
   7451      A tracepoint has been destroyed.  The argument TPNUM is the number
   7452      of the newly-destroyed tracepoint.
   7453 
   7454  -- Function: void tracepoint_modified (int TPNUM)
   7455      A tracepoint has been modified in some way.  The argument TPNUM is
   7456      the number of the modified tracepoint.
   7457 
   7458  -- Function: void architecture_changed (struct gdbarch *NEWARCH)
   7459      The current architecture has changed.  The argument NEWARCH is a
   7460      pointer to the new architecture.
   7461 
   7462  -- Function: void thread_ptid_changed (ptid_t OLD_PTID, ptid_t
   7463           NEW_PTID)
   7464      The thread's ptid has changed.  The OLD_PTID parameter specifies
   7465      the old value, and NEW_PTID specifies the new value.
   7466 
   7467  -- Function: void inferior_appeared (int PID)
   7468      GDB has attached to a new inferior identified by PID.
   7469 
   7470  -- Function: void inferior_exit (int PID)
   7471      Either GDB detached from the inferior, or the inferior exited.
   7472      The argument PID identifies the inferior.
   7473 
   7474  -- Function: void memory_changed (CORE_ADDR ADDR, int LEN, const
   7475           bfd_byte *DATA)
   7476      Bytes from DATA to DATA + LEN have been written to the current
   7477      inferior at ADDR.
   7478 
   7479  -- Function: void test_notification (int SOMEARG)
   7480      This observer is used for internal testing.  Do not use.  See
   7481      testsuite/gdb.gdb/observer.exp.
   7482 
   7483 
   7484 File: gdbint.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: GDB Observers,  Up: Top
   7485 
   7486 Appendix B GNU Free Documentation License
   7487 *****************************************
   7488 
   7489                       Version 1.2, November 2002
   7490 
   7491      Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
   7492      51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   7493 
   7494      Everyone is permitted to copy and distribute verbatim copies
   7495      of this license document, but changing it is not allowed.
   7496 
   7497   0. PREAMBLE
   7498 
   7499      The purpose of this License is to make a manual, textbook, or other
   7500      functional and useful document "free" in the sense of freedom: to
   7501      assure everyone the effective freedom to copy and redistribute it,
   7502      with or without modifying it, either commercially or
   7503      noncommercially.  Secondarily, this License preserves for the
   7504      author and publisher a way to get credit for their work, while not
   7505      being considered responsible for modifications made by others.
   7506 
   7507      This License is a kind of "copyleft", which means that derivative
   7508      works of the document must themselves be free in the same sense.
   7509      It complements the GNU General Public License, which is a copyleft
   7510      license designed for free software.
   7511 
   7512      We have designed this License in order to use it for manuals for
   7513      free software, because free software needs free documentation: a
   7514      free program should come with manuals providing the same freedoms
   7515      that the software does.  But this License is not limited to
   7516      software manuals; it can be used for any textual work, regardless
   7517      of subject matter or whether it is published as a printed book.
   7518      We recommend this License principally for works whose purpose is
   7519      instruction or reference.
   7520 
   7521   1. APPLICABILITY AND DEFINITIONS
   7522 
   7523      This License applies to any manual or other work, in any medium,
   7524      that contains a notice placed by the copyright holder saying it
   7525      can be distributed under the terms of this License.  Such a notice
   7526      grants a world-wide, royalty-free license, unlimited in duration,
   7527      to use that work under the conditions stated herein.  The
   7528      "Document", below, refers to any such manual or work.  Any member
   7529      of the public is a licensee, and is addressed as "you".  You
   7530      accept the license if you copy, modify or distribute the work in a
   7531      way requiring permission under copyright law.
   7532 
   7533      A "Modified Version" of the Document means any work containing the
   7534      Document or a portion of it, either copied verbatim, or with
   7535      modifications and/or translated into another language.
   7536 
   7537      A "Secondary Section" is a named appendix or a front-matter section
   7538      of the Document that deals exclusively with the relationship of the
   7539      publishers or authors of the Document to the Document's overall
   7540      subject (or to related matters) and contains nothing that could
   7541      fall directly within that overall subject.  (Thus, if the Document
   7542      is in part a textbook of mathematics, a Secondary Section may not
   7543      explain any mathematics.)  The relationship could be a matter of
   7544      historical connection with the subject or with related matters, or
   7545      of legal, commercial, philosophical, ethical or political position
   7546      regarding them.
   7547 
   7548      The "Invariant Sections" are certain Secondary Sections whose
   7549      titles are designated, as being those of Invariant Sections, in
   7550      the notice that says that the Document is released under this
   7551      License.  If a section does not fit the above definition of
   7552      Secondary then it is not allowed to be designated as Invariant.
   7553      The Document may contain zero Invariant Sections.  If the Document
   7554      does not identify any Invariant Sections then there are none.
   7555 
   7556      The "Cover Texts" are certain short passages of text that are
   7557      listed, as Front-Cover Texts or Back-Cover Texts, in the notice
   7558      that says that the Document is released under this License.  A
   7559      Front-Cover Text may be at most 5 words, and a Back-Cover Text may
   7560      be at most 25 words.
   7561 
   7562      A "Transparent" copy of the Document means a machine-readable copy,
   7563      represented in a format whose specification is available to the
   7564      general public, that is suitable for revising the document
   7565      straightforwardly with generic text editors or (for images
   7566      composed of pixels) generic paint programs or (for drawings) some
   7567      widely available drawing editor, and that is suitable for input to
   7568      text formatters or for automatic translation to a variety of
   7569      formats suitable for input to text formatters.  A copy made in an
   7570      otherwise Transparent file format whose markup, or absence of
   7571      markup, has been arranged to thwart or discourage subsequent
   7572      modification by readers is not Transparent.  An image format is
   7573      not Transparent if used for any substantial amount of text.  A
   7574      copy that is not "Transparent" is called "Opaque".
   7575 
   7576      Examples of suitable formats for Transparent copies include plain
   7577      ASCII without markup, Texinfo input format, LaTeX input format,
   7578      SGML or XML using a publicly available DTD, and
   7579      standard-conforming simple HTML, PostScript or PDF designed for
   7580      human modification.  Examples of transparent image formats include
   7581      PNG, XCF and JPG.  Opaque formats include proprietary formats that
   7582      can be read and edited only by proprietary word processors, SGML or
   7583      XML for which the DTD and/or processing tools are not generally
   7584      available, and the machine-generated HTML, PostScript or PDF
   7585      produced by some word processors for output purposes only.
   7586 
   7587      The "Title Page" means, for a printed book, the title page itself,
   7588      plus such following pages as are needed to hold, legibly, the
   7589      material this License requires to appear in the title page.  For
   7590      works in formats which do not have any title page as such, "Title
   7591      Page" means the text near the most prominent appearance of the
   7592      work's title, preceding the beginning of the body of the text.
   7593 
   7594      A section "Entitled XYZ" means a named subunit of the Document
   7595      whose title either is precisely XYZ or contains XYZ in parentheses
   7596      following text that translates XYZ in another language.  (Here XYZ
   7597      stands for a specific section name mentioned below, such as
   7598      "Acknowledgements", "Dedications", "Endorsements", or "History".)
   7599      To "Preserve the Title" of such a section when you modify the
   7600      Document means that it remains a section "Entitled XYZ" according
   7601      to this definition.
   7602 
   7603      The Document may include Warranty Disclaimers next to the notice
   7604      which states that this License applies to the Document.  These
   7605      Warranty Disclaimers are considered to be included by reference in
   7606      this License, but only as regards disclaiming warranties: any other
   7607      implication that these Warranty Disclaimers may have is void and
   7608      has no effect on the meaning of this License.
   7609 
   7610   2. VERBATIM COPYING
   7611 
   7612      You may copy and distribute the Document in any medium, either
   7613      commercially or noncommercially, provided that this License, the
   7614      copyright notices, and the license notice saying this License
   7615      applies to the Document are reproduced in all copies, and that you
   7616      add no other conditions whatsoever to those of this License.  You
   7617      may not use technical measures to obstruct or control the reading
   7618      or further copying of the copies you make or distribute.  However,
   7619      you may accept compensation in exchange for copies.  If you
   7620      distribute a large enough number of copies you must also follow
   7621      the conditions in section 3.
   7622 
   7623      You may also lend copies, under the same conditions stated above,
   7624      and you may publicly display copies.
   7625 
   7626   3. COPYING IN QUANTITY
   7627 
   7628      If you publish printed copies (or copies in media that commonly
   7629      have printed covers) of the Document, numbering more than 100, and
   7630      the Document's license notice requires Cover Texts, you must
   7631      enclose the copies in covers that carry, clearly and legibly, all
   7632      these Cover Texts: Front-Cover Texts on the front cover, and
   7633      Back-Cover Texts on the back cover.  Both covers must also clearly
   7634      and legibly identify you as the publisher of these copies.  The
   7635      front cover must present the full title with all words of the
   7636      title equally prominent and visible.  You may add other material
   7637      on the covers in addition.  Copying with changes limited to the
   7638      covers, as long as they preserve the title of the Document and
   7639      satisfy these conditions, can be treated as verbatim copying in
   7640      other respects.
   7641 
   7642      If the required texts for either cover are too voluminous to fit
   7643      legibly, you should put the first ones listed (as many as fit
   7644      reasonably) on the actual cover, and continue the rest onto
   7645      adjacent pages.
   7646 
   7647      If you publish or distribute Opaque copies of the Document
   7648      numbering more than 100, you must either include a
   7649      machine-readable Transparent copy along with each Opaque copy, or
   7650      state in or with each Opaque copy a computer-network location from
   7651      which the general network-using public has access to download
   7652      using public-standard network protocols a complete Transparent
   7653      copy of the Document, free of added material.  If you use the
   7654      latter option, you must take reasonably prudent steps, when you
   7655      begin distribution of Opaque copies in quantity, to ensure that
   7656      this Transparent copy will remain thus accessible at the stated
   7657      location until at least one year after the last time you
   7658      distribute an Opaque copy (directly or through your agents or
   7659      retailers) of that edition to the public.
   7660 
   7661      It is requested, but not required, that you contact the authors of
   7662      the Document well before redistributing any large number of
   7663      copies, to give them a chance to provide you with an updated
   7664      version of the Document.
   7665 
   7666   4. MODIFICATIONS
   7667 
   7668      You may copy and distribute a Modified Version of the Document
   7669      under the conditions of sections 2 and 3 above, provided that you
   7670      release the Modified Version under precisely this License, with
   7671      the Modified Version filling the role of the Document, thus
   7672      licensing distribution and modification of the Modified Version to
   7673      whoever possesses a copy of it.  In addition, you must do these
   7674      things in the Modified Version:
   7675 
   7676        A. Use in the Title Page (and on the covers, if any) a title
   7677           distinct from that of the Document, and from those of
   7678           previous versions (which should, if there were any, be listed
   7679           in the History section of the Document).  You may use the
   7680           same title as a previous version if the original publisher of
   7681           that version gives permission.
   7682 
   7683        B. List on the Title Page, as authors, one or more persons or
   7684           entities responsible for authorship of the modifications in
   7685           the Modified Version, together with at least five of the
   7686           principal authors of the Document (all of its principal
   7687           authors, if it has fewer than five), unless they release you
   7688           from this requirement.
   7689 
   7690        C. State on the Title page the name of the publisher of the
   7691           Modified Version, as the publisher.
   7692 
   7693        D. Preserve all the copyright notices of the Document.
   7694 
   7695        E. Add an appropriate copyright notice for your modifications
   7696           adjacent to the other copyright notices.
   7697 
   7698        F. Include, immediately after the copyright notices, a license
   7699           notice giving the public permission to use the Modified
   7700           Version under the terms of this License, in the form shown in
   7701           the Addendum below.
   7702 
   7703        G. Preserve in that license notice the full lists of Invariant
   7704           Sections and required Cover Texts given in the Document's
   7705           license notice.
   7706 
   7707        H. Include an unaltered copy of this License.
   7708 
   7709        I. Preserve the section Entitled "History", Preserve its Title,
   7710           and add to it an item stating at least the title, year, new
   7711           authors, and publisher of the Modified Version as given on
   7712           the Title Page.  If there is no section Entitled "History" in
   7713           the Document, create one stating the title, year, authors,
   7714           and publisher of the Document as given on its Title Page,
   7715           then add an item describing the Modified Version as stated in
   7716           the previous sentence.
   7717 
   7718        J. Preserve the network location, if any, given in the Document
   7719           for public access to a Transparent copy of the Document, and
   7720           likewise the network locations given in the Document for
   7721           previous versions it was based on.  These may be placed in
   7722           the "History" section.  You may omit a network location for a
   7723           work that was published at least four years before the
   7724           Document itself, or if the original publisher of the version
   7725           it refers to gives permission.
   7726 
   7727        K. For any section Entitled "Acknowledgements" or "Dedications",
   7728           Preserve the Title of the section, and preserve in the
   7729           section all the substance and tone of each of the contributor
   7730           acknowledgements and/or dedications given therein.
   7731 
   7732        L. Preserve all the Invariant Sections of the Document,
   7733           unaltered in their text and in their titles.  Section numbers
   7734           or the equivalent are not considered part of the section
   7735           titles.
   7736 
   7737        M. Delete any section Entitled "Endorsements".  Such a section
   7738           may not be included in the Modified Version.
   7739 
   7740        N. Do not retitle any existing section to be Entitled
   7741           "Endorsements" or to conflict in title with any Invariant
   7742           Section.
   7743 
   7744        O. Preserve any Warranty Disclaimers.
   7745 
   7746      If the Modified Version includes new front-matter sections or
   7747      appendices that qualify as Secondary Sections and contain no
   7748      material copied from the Document, you may at your option
   7749      designate some or all of these sections as invariant.  To do this,
   7750      add their titles to the list of Invariant Sections in the Modified
   7751      Version's license notice.  These titles must be distinct from any
   7752      other section titles.
   7753 
   7754      You may add a section Entitled "Endorsements", provided it contains
   7755      nothing but endorsements of your Modified Version by various
   7756      parties--for example, statements of peer review or that the text
   7757      has been approved by an organization as the authoritative
   7758      definition of a standard.
   7759 
   7760      You may add a passage of up to five words as a Front-Cover Text,
   7761      and a passage of up to 25 words as a Back-Cover Text, to the end
   7762      of the list of Cover Texts in the Modified Version.  Only one
   7763      passage of Front-Cover Text and one of Back-Cover Text may be
   7764      added by (or through arrangements made by) any one entity.  If the
   7765      Document already includes a cover text for the same cover,
   7766      previously added by you or by arrangement made by the same entity
   7767      you are acting on behalf of, you may not add another; but you may
   7768      replace the old one, on explicit permission from the previous
   7769      publisher that added the old one.
   7770 
   7771      The author(s) and publisher(s) of the Document do not by this
   7772      License give permission to use their names for publicity for or to
   7773      assert or imply endorsement of any Modified Version.
   7774 
   7775   5. COMBINING DOCUMENTS
   7776 
   7777      You may combine the Document with other documents released under
   7778      this License, under the terms defined in section 4 above for
   7779      modified versions, provided that you include in the combination
   7780      all of the Invariant Sections of all of the original documents,
   7781      unmodified, and list them all as Invariant Sections of your
   7782      combined work in its license notice, and that you preserve all
   7783      their Warranty Disclaimers.
   7784 
   7785      The combined work need only contain one copy of this License, and
   7786      multiple identical Invariant Sections may be replaced with a single
   7787      copy.  If there are multiple Invariant Sections with the same name
   7788      but different contents, make the title of each such section unique
   7789      by adding at the end of it, in parentheses, the name of the
   7790      original author or publisher of that section if known, or else a
   7791      unique number.  Make the same adjustment to the section titles in
   7792      the list of Invariant Sections in the license notice of the
   7793      combined work.
   7794 
   7795      In the combination, you must combine any sections Entitled
   7796      "History" in the various original documents, forming one section
   7797      Entitled "History"; likewise combine any sections Entitled
   7798      "Acknowledgements", and any sections Entitled "Dedications".  You
   7799      must delete all sections Entitled "Endorsements."
   7800 
   7801   6. COLLECTIONS OF DOCUMENTS
   7802 
   7803      You may make a collection consisting of the Document and other
   7804      documents released under this License, and replace the individual
   7805      copies of this License in the various documents with a single copy
   7806      that is included in the collection, provided that you follow the
   7807      rules of this License for verbatim copying of each of the
   7808      documents in all other respects.
   7809 
   7810      You may extract a single document from such a collection, and
   7811      distribute it individually under this License, provided you insert
   7812      a copy of this License into the extracted document, and follow
   7813      this License in all other respects regarding verbatim copying of
   7814      that document.
   7815 
   7816   7. AGGREGATION WITH INDEPENDENT WORKS
   7817 
   7818      A compilation of the Document or its derivatives with other
   7819      separate and independent documents or works, in or on a volume of
   7820      a storage or distribution medium, is called an "aggregate" if the
   7821      copyright resulting from the compilation is not used to limit the
   7822      legal rights of the compilation's users beyond what the individual
   7823      works permit.  When the Document is included in an aggregate, this
   7824      License does not apply to the other works in the aggregate which
   7825      are not themselves derivative works of the Document.
   7826 
   7827      If the Cover Text requirement of section 3 is applicable to these
   7828      copies of the Document, then if the Document is less than one half
   7829      of the entire aggregate, the Document's Cover Texts may be placed
   7830      on covers that bracket the Document within the aggregate, or the
   7831      electronic equivalent of covers if the Document is in electronic
   7832      form.  Otherwise they must appear on printed covers that bracket
   7833      the whole aggregate.
   7834 
   7835   8. TRANSLATION
   7836 
   7837      Translation is considered a kind of modification, so you may
   7838      distribute translations of the Document under the terms of section
   7839      4.  Replacing Invariant Sections with translations requires special
   7840      permission from their copyright holders, but you may include
   7841      translations of some or all Invariant Sections in addition to the
   7842      original versions of these Invariant Sections.  You may include a
   7843      translation of this License, and all the license notices in the
   7844      Document, and any Warranty Disclaimers, provided that you also
   7845      include the original English version of this License and the
   7846      original versions of those notices and disclaimers.  In case of a
   7847      disagreement between the translation and the original version of
   7848      this License or a notice or disclaimer, the original version will
   7849      prevail.
   7850 
   7851      If a section in the Document is Entitled "Acknowledgements",
   7852      "Dedications", or "History", the requirement (section 4) to
   7853      Preserve its Title (section 1) will typically require changing the
   7854      actual title.
   7855 
   7856   9. TERMINATION
   7857 
   7858      You may not copy, modify, sublicense, or distribute the Document
   7859      except as expressly provided for under this License.  Any other
   7860      attempt to copy, modify, sublicense or distribute the Document is
   7861      void, and will automatically terminate your rights under this
   7862      License.  However, parties who have received copies, or rights,
   7863      from you under this License will not have their licenses
   7864      terminated so long as such parties remain in full compliance.
   7865 
   7866  10. FUTURE REVISIONS OF THIS LICENSE
   7867 
   7868      The Free Software Foundation may publish new, revised versions of
   7869      the GNU Free Documentation License from time to time.  Such new
   7870      versions will be similar in spirit to the present version, but may
   7871      differ in detail to address new problems or concerns.  See
   7872      `http://www.gnu.org/copyleft/'.
   7873 
   7874      Each version of the License is given a distinguishing version
   7875      number.  If the Document specifies that a particular numbered
   7876      version of this License "or any later version" applies to it, you
   7877      have the option of following the terms and conditions either of
   7878      that specified version or of any later version that has been
   7879      published (not as a draft) by the Free Software Foundation.  If
   7880      the Document does not specify a version number of this License,
   7881      you may choose any version ever published (not as a draft) by the
   7882      Free Software Foundation.
   7883 
   7884 B.1 ADDENDUM: How to use this License for your documents
   7885 ========================================================
   7886 
   7887 To use this License in a document you have written, include a copy of
   7888 the License in the document and put the following copyright and license
   7889 notices just after the title page:
   7890 
   7891        Copyright (C)  YEAR  YOUR NAME.
   7892        Permission is granted to copy, distribute and/or modify this document
   7893        under the terms of the GNU Free Documentation License, Version 1.2
   7894        or any later version published by the Free Software Foundation;
   7895        with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
   7896        Texts.  A copy of the license is included in the section entitled ``GNU
   7897        Free Documentation License''.
   7898 
   7899    If you have Invariant Sections, Front-Cover Texts and Back-Cover
   7900 Texts, replace the "with...Texts." line with this:
   7901 
   7902          with the Invariant Sections being LIST THEIR TITLES, with
   7903          the Front-Cover Texts being LIST, and with the Back-Cover Texts
   7904          being LIST.
   7905 
   7906    If you have Invariant Sections without Cover Texts, or some other
   7907 combination of the three, merge those two alternatives to suit the
   7908 situation.
   7909 
   7910    If your document contains nontrivial examples of program code, we
   7911 recommend releasing these examples in parallel under your choice of
   7912 free software license, such as the GNU General Public License, to
   7913 permit their use in free software.
   7914 
   7915 
   7916 File: gdbint.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top
   7917 
   7918 Index
   7919 *****
   7920 
   7921 [index]
   7922 * Menu:
   7923 
   7924 * $fp:                                   Register Information Functions.
   7925                                                               (line 126)
   7926 * $pc:                                   Register Architecture Functions & Variables.
   7927                                                               (line  58)
   7928 * $ps:                                   Register Architecture Functions & Variables.
   7929                                                               (line  69)
   7930 * $sp:                                   Register Architecture Functions & Variables.
   7931                                                               (line  49)
   7932 * _initialize_ARCH_tdep <1>:             Adding a New Target. (line  22)
   7933 * _initialize_ARCH_tdep:                 How an Architecture is Represented.
   7934                                                               (line  13)
   7935 * _initialize_language:                  Language Support.    (line  79)
   7936 * a.out format:                          Symbol Handling.     (line 213)
   7937 * about_to_proceed:                      GDB Observers.       (line 133)
   7938 * abstract interpretation of function prologues: Algorithms.  (line  48)
   7939 * add_cmd:                               User Interface.      (line  21)
   7940 * add_com:                               User Interface.      (line  21)
   7941 * add_setshow_cmd:                       User Interface.      (line  26)
   7942 * add_setshow_cmd_full:                  User Interface.      (line  26)
   7943 * add_symtab_fns:                        Symbol Handling.     (line  37)
   7944 * adding a new host:                     Host Definition.     (line  13)
   7945 * adding a symbol-reading module:        Symbol Handling.     (line  37)
   7946 * adding a target:                       Adding a New Target. (line   6)
   7947 * adding debugging info reader:          Symbol Handling.     (line 360)
   7948 * adding source language:                Language Support.    (line  17)
   7949 * address classes:                       Address Classes.     (line   6)
   7950 * address representation:                Pointers and Addresses.
   7951                                                               (line   6)
   7952 * address spaces, separate data and code: Pointers and Addresses.
   7953                                                               (line   6)
   7954 * address_class_name_to_type_flags:      Defining Other Architecture Features.
   7955                                                               (line  28)
   7956 * address_class_name_to_type_flags_p:    Defining Other Architecture Features.
   7957                                                               (line  39)
   7958 * algorithms:                            Algorithms.          (line   6)
   7959 * align_down:                            Functions and Variable to Analyze Frames.
   7960                                                               (line  46)
   7961 * align_up:                              Functions and Variable to Analyze Frames.
   7962                                                               (line  46)
   7963 * allocate_symtab:                       Language Support.    (line  83)
   7964 * ARCH-tdep.c:                           How an Architecture is Represented.
   7965                                                               (line  13)
   7966 * architecture representation:           How an Architecture is Represented.
   7967                                                               (line   6)
   7968 * architecture_changed:                  GDB Observers.       (line 160)
   7969 * Array Containers:                      Support Libraries.   (line 131)
   7970 * assumptions about targets:             Coding.              (line 514)
   7971 * ATTR_NORETURN:                         Host Definition.     (line 126)
   7972 * base of a frame:                       Frame Handling Terminology.
   7973                                                               (line  28)
   7974 * BFD library:                           Support Libraries.   (line   9)
   7975 * bfd_arch_info:                         Looking Up an Existing Architecture.
   7976                                                               (line  41)
   7977 * BIG_BREAKPOINT:                        Defining Other Architecture Features.
   7978                                                               (line 100)
   7979 * BPT_VECTOR:                            Defining Other Architecture Features.
   7980                                                               (line 536)
   7981 * BREAKPOINT:                            Defining Other Architecture Features.
   7982                                                               (line  88)
   7983 * breakpoint address adjusted:           Defining Other Architecture Features.
   7984                                                               (line 145)
   7985 * breakpoint_created:                    GDB Observers.       (line 136)
   7986 * breakpoint_deleted:                    GDB Observers.       (line 140)
   7987 * breakpoint_modified:                   GDB Observers.       (line 144)
   7988 * breakpoints:                           Algorithms.          (line 151)
   7989 * bug-gdb mailing list:                  Getting Started.     (line  72)
   7990 * build script:                          Debugging GDB.       (line  94)
   7991 * C data types:                          Coding.              (line 389)
   7992 * call frame information:                Algorithms.          (line  14)
   7993 * call stack frame:                      Stack Frames.        (line   6)
   7994 * calls to the inferior:                 Inferior Call Setup. (line   6)
   7995 * CANNOT_STEP_HW_WATCHPOINTS:            Algorithms.          (line 408)
   7996 * CC_HAS_LONG_LONG:                      Host Definition.     (line 105)
   7997 * CFI (call frame information):          Algorithms.          (line  14)
   7998 * checkpoints:                           Algorithms.          (line 604)
   7999 * cleanups:                              Coding.              (line  12)
   8000 * CLI:                                   User Interface.      (line  12)
   8001 * code pointers, word-addressed:         Pointers and Addresses.
   8002                                                               (line   6)
   8003 * coding standards:                      Coding.              (line 215)
   8004 * COFF debugging info:                   Symbol Handling.     (line 310)
   8005 * COFF format:                           Symbol Handling.     (line 228)
   8006 * command implementation:                Getting Started.     (line  60)
   8007 * command interpreter:                   User Interface.      (line  12)
   8008 * comment formatting:                    Coding.              (line 363)
   8009 * compiler warnings:                     Coding.              (line 271)
   8010 * Compressed DWARF 2 debugging info:     Symbol Handling.     (line 330)
   8011 * computed values:                       Values.              (line  35)
   8012 * configure.tgt:                         How an Architecture is Represented.
   8013                                                               (line  19)
   8014 * converting between pointers and addresses: Pointers and Addresses.
   8015                                                               (line   6)
   8016 * converting integers to addresses:      Defining Other Architecture Features.
   8017                                                               (line 274)
   8018 * cooked register representation:        Raw and Cooked Registers.
   8019                                                               (line   6)
   8020 * core files:                            Adding support for debugging core files.
   8021                                                               (line   6)
   8022 * core_addr_greaterthan:                 Functions and Variable to Analyze Frames.
   8023                                                               (line  30)
   8024 * core_addr_lessthan:                    Functions and Variable to Analyze Frames.
   8025                                                               (line  30)
   8026 * CRLF_SOURCE_FILES:                     Host Definition.     (line  86)
   8027 * current_language:                      Language Support.    (line  75)
   8028 * D10V addresses:                        Pointers and Addresses.
   8029                                                               (line   6)
   8030 * data output:                           User Interface.      (line 254)
   8031 * data-pointer, per-architecture/per-module: Coding.          (line 100)
   8032 * debugging GDB:                         Debugging GDB.       (line   6)
   8033 * DEFAULT_PROMPT:                        Host Definition.     (line  93)
   8034 * deprecate_cmd:                         User Interface.      (line  32)
   8035 * DEPRECATED_IBM6000_TARGET:             Defining Other Architecture Features.
   8036                                                               (line 242)
   8037 * deprecating commands:                  User Interface.      (line  32)
   8038 * design:                                Coding.              (line 509)
   8039 * DEV_TTY:                               Host Definition.     (line  96)
   8040 * DIRNAME_SEPARATOR:                     Coding.              (line 579)
   8041 * DISABLE_UNSETTABLE_BREAK:              Defining Other Architecture Features.
   8042                                                               (line 211)
   8043 * discard_cleanups:                      Coding.              (line  39)
   8044 * do_cleanups:                           Coding.              (line  35)
   8045 * DOS text files:                        Host Definition.     (line  87)
   8046 * dummy frames:                          About Dummy Frames.  (line   6)
   8047 * DW_AT_address_class:                   Address Classes.     (line   6)
   8048 * DW_AT_byte_size:                       Address Classes.     (line   6)
   8049 * DWARF 2 debugging info:                Symbol Handling.     (line 323)
   8050 * DWARF 3 debugging info:                Symbol Handling.     (line 350)
   8051 * ECOFF debugging info:                  Symbol Handling.     (line 316)
   8052 * ECOFF format:                          Symbol Handling.     (line 243)
   8053 * ELF format:                            Symbol Handling.     (line 276)
   8054 * evaluate_subexp:                       Language Support.    (line  58)
   8055 * executable_changed:                    GDB Observers.       (line  85)
   8056 * execution state:                       Managing Execution State.
   8057                                                               (line   6)
   8058 * experimental branches:                 Versions and Branches.
   8059                                                               (line 116)
   8060 * expression evaluation routines:        Language Support.    (line  58)
   8061 * expression parser:                     Language Support.    (line  21)
   8062 * extract_typed_address:                 Pointers and Addresses.
   8063                                                               (line  52)
   8064 * FDL, GNU Free Documentation License:   GNU Free Documentation License.
   8065                                                               (line   6)
   8066 * field output functions:                User Interface.      (line 254)
   8067 * file names, portability:               Coding.              (line 547)
   8068 * FILENAME_CMP:                          Coding.              (line 573)
   8069 * find_pc_function:                      Symbol Handling.     (line 136)
   8070 * find_pc_line:                          Symbol Handling.     (line 136)
   8071 * find_sym_fns:                          Symbol Handling.     (line  32)
   8072 * finding a symbol:                      Symbol Handling.     (line 133)
   8073 * fine-tuning gdbarch structure:         OS ABI Variant Handling.
   8074                                                               (line  23)
   8075 * first floating point register:         Register Architecture Functions & Variables.
   8076                                                               (line  78)
   8077 * FOPEN_RB:                              Host Definition.     (line 102)
   8078 * fp0_regnum:                            Register Architecture Functions & Variables.
   8079                                                               (line  78)
   8080 * frame:                                 Stack Frames.        (line   6)
   8081 * frame ID:                              Stack Frames.        (line  41)
   8082 * frame pointer:                         Register Information Functions.
   8083                                                               (line 126)
   8084 * frame, definition of base of a frame:  Frame Handling Terminology.
   8085                                                               (line  28)
   8086 * frame, definition of innermost frame:  Frame Handling Terminology.
   8087                                                               (line  24)
   8088 * frame, definition of NEXT frame:       Frame Handling Terminology.
   8089                                                               (line  11)
   8090 * frame, definition of PREVIOUS frame:   Frame Handling Terminology.
   8091                                                               (line  14)
   8092 * frame, definition of sentinel frame:   Frame Handling Terminology.
   8093                                                               (line  52)
   8094 * frame, definition of sniffing:         Frame Handling Terminology.
   8095                                                               (line  46)
   8096 * frame, definition of THIS frame:       Frame Handling Terminology.
   8097                                                               (line   9)
   8098 * frame, definition of unwinding:        Frame Handling Terminology.
   8099                                                               (line  41)
   8100 * frame_align:                           Functions and Variable to Analyze Frames.
   8101                                                               (line  46)
   8102 * frame_base:                            Analyzing Stacks---Frame Sniffers.
   8103                                                               (line  89)
   8104 * frame_base_append_sniffer:             Analyzing Stacks---Frame Sniffers.
   8105                                                               (line  19)
   8106 * frame_base_set_default:                Analyzing Stacks---Frame Sniffers.
   8107                                                               (line  22)
   8108 * frame_num_args:                        Functions to Access Frame Data.
   8109                                                               (line  43)
   8110 * frame_red_zone_size:                   Functions and Variable to Analyze Frames.
   8111                                                               (line  63)
   8112 * frame_register_unwind:                 Stack Frames.        (line  15)
   8113 * frame_unwind:                          Analyzing Stacks---Frame Sniffers.
   8114                                                               (line  36)
   8115 * frame_unwind_append_sniffer:           Analyzing Stacks---Frame Sniffers.
   8116                                                               (line  16)
   8117 * frame_unwind_append_unwinder:          Stack Frames.        (line  30)
   8118 * frame_unwind_got_address:              Stack Frames.        (line 105)
   8119 * frame_unwind_got_constant:             Stack Frames.        (line 101)
   8120 * frame_unwind_got_memory:               Stack Frames.        (line  98)
   8121 * frame_unwind_got_optimized:            Stack Frames.        (line  90)
   8122 * frame_unwind_got_register:             Stack Frames.        (line  93)
   8123 * frame_unwind_prepend_unwinder:         Stack Frames.        (line  30)
   8124 * full symbol table:                     Symbol Handling.     (line 104)
   8125 * function prologue:                     Prologue Caches.     (line   6)
   8126 * function prototypes:                   Coding.              (line 411)
   8127 * function usage:                        Coding.              (line 393)
   8128 * fundamental types:                     Symbol Handling.     (line 178)
   8129 * GCC2_COMPILED_FLAG_SYMBOL:             Defining Other Architecture Features.
   8130                                                               (line 225)
   8131 * GCC_COMPILED_FLAG_SYMBOL:              Defining Other Architecture Features.
   8132                                                               (line 225)
   8133 * GDB source tree structure:             Overall Structure.   (line  83)
   8134 * gdb_byte:                              Register Caching.    (line  23)
   8135 * GDB_OSABI_AIX:                         OS ABI Variant Handling.
   8136                                                               (line  90)
   8137 * GDB_OSABI_CYGWIN:                      OS ABI Variant Handling.
   8138                                                               (line  87)
   8139 * GDB_OSABI_FREEBSD_AOUT:                OS ABI Variant Handling.
   8140                                                               (line  51)
   8141 * GDB_OSABI_FREEBSD_ELF:                 OS ABI Variant Handling.
   8142                                                               (line  54)
   8143 * GDB_OSABI_GO32:                        OS ABI Variant Handling.
   8144                                                               (line  69)
   8145 * GDB_OSABI_HPUX_ELF:                    OS ABI Variant Handling.
   8146                                                               (line  78)
   8147 * GDB_OSABI_HPUX_SOM:                    OS ABI Variant Handling.
   8148                                                               (line  81)
   8149 * GDB_OSABI_HURD:                        OS ABI Variant Handling.
   8150                                                               (line  39)
   8151 * GDB_OSABI_INTERIX:                     OS ABI Variant Handling.
   8152                                                               (line  75)
   8153 * GDB_OSABI_IRIX:                        OS ABI Variant Handling.
   8154                                                               (line  72)
   8155 * GDB_OSABI_LINUX:                       OS ABI Variant Handling.
   8156                                                               (line  48)
   8157 * GDB_OSABI_NETBSD_AOUT:                 OS ABI Variant Handling.
   8158                                                               (line  57)
   8159 * GDB_OSABI_NETBSD_ELF:                  OS ABI Variant Handling.
   8160                                                               (line  60)
   8161 * GDB_OSABI_OPENBSD_ELF:                 OS ABI Variant Handling.
   8162                                                               (line  63)
   8163 * GDB_OSABI_OSF1:                        OS ABI Variant Handling.
   8164                                                               (line  45)
   8165 * GDB_OSABI_QNXNTO:                      OS ABI Variant Handling.
   8166                                                               (line  84)
   8167 * GDB_OSABI_SOLARIS:                     OS ABI Variant Handling.
   8168                                                               (line  42)
   8169 * GDB_OSABI_SVR4:                        OS ABI Variant Handling.
   8170                                                               (line  36)
   8171 * GDB_OSABI_UNINITIALIZED:               OS ABI Variant Handling.
   8172                                                               (line  29)
   8173 * GDB_OSABI_UNKNOWN:                     OS ABI Variant Handling.
   8174                                                               (line  32)
   8175 * GDB_OSABI_WINCE:                       OS ABI Variant Handling.
   8176                                                               (line  66)
   8177 * gdbarch:                               How an Architecture is Represented.
   8178                                                               (line  19)
   8179 * gdbarch accessor functions:            Creating a New Architecture.
   8180                                                               (line  14)
   8181 * gdbarch lookup:                        Looking Up an Existing Architecture.
   8182                                                               (line   6)
   8183 * gdbarch register architecture functions: Register Architecture Functions & Variables.
   8184                                                               (line   6)
   8185 * gdbarch register information functions: Register Information Functions.
   8186                                                               (line   6)
   8187 * gdbarch_addr_bits_remove:              Defining Other Architecture Features.
   8188                                                               (line  11)
   8189 * gdbarch_address_class_name_to_type_flags: Address Classes.  (line  30)
   8190 * gdbarch_address_class_type_flags <1>:  Defining Other Architecture Features.
   8191                                                               (line  43)
   8192 * gdbarch_address_class_type_flags:      Address Classes.     (line  18)
   8193 * gdbarch_address_class_type_flags_p:    Defining Other Architecture Features.
   8194                                                               (line  52)
   8195 * gdbarch_address_class_type_flags_to_name <1>: Defining Other Architecture Features.
   8196                                                               (line  56)
   8197 * gdbarch_address_class_type_flags_to_name: Address Classes.  (line  25)
   8198 * gdbarch_address_class_type_flags_to_name_p: Defining Other Architecture Features.
   8199                                                               (line  60)
   8200 * gdbarch_address_to_pointer <1>:        Defining Other Architecture Features.
   8201                                                               (line  65)
   8202 * gdbarch_address_to_pointer:            Pointers and Addresses.
   8203                                                               (line 114)
   8204 * gdbarch_adjust_breakpoint_address:     Defining Other Architecture Features.
   8205                                                               (line 145)
   8206 * gdbarch_alloc:                         Creating a New Architecture.
   8207                                                               (line   6)
   8208 * gdbarch_believe_pcc_promotion:         Defining Other Architecture Features.
   8209                                                               (line  72)
   8210 * gdbarch_bits_big_endian:               Defining Other Architecture Features.
   8211                                                               (line  77)
   8212 * gdbarch_breakpoint_from_pc:            Defining Other Architecture Features.
   8213                                                               (line 106)
   8214 * gdbarch_call_dummy_location:           Defining Other Architecture Features.
   8215                                                               (line 178)
   8216 * gdbarch_cannot_fetch_register:         Defining Other Architecture Features.
   8217                                                               (line 184)
   8218 * gdbarch_cannot_store_register:         Defining Other Architecture Features.
   8219                                                               (line 188)
   8220 * gdbarch_char_signed:                   Defining Other Architecture Features.
   8221                                                               (line 461)
   8222 * gdbarch_convert_register_p <1>:        Defining Other Architecture Features.
   8223                                                               (line 195)
   8224 * gdbarch_convert_register_p:            Register and Memory Data.
   8225                                                               (line  30)
   8226 * gdbarch_data:                          Coding.              (line 133)
   8227 * gdbarch_data_register_post_init:       Coding.              (line 118)
   8228 * gdbarch_data_register_pre_init:        Coding.              (line 108)
   8229 * gdbarch_decr_pc_after_break:           Defining Other Architecture Features.
   8230                                                               (line 205)
   8231 * gdbarch_deprecated_fp_regnum:          Defining Other Architecture Features.
   8232                                                               (line 446)
   8233 * gdbarch_double_bit:                    Defining Other Architecture Features.
   8234                                                               (line 471)
   8235 * gdbarch_dummy_id:                      Defining Other Architecture Features.
   8236                                                               (line 523)
   8237 * gdbarch_dwarf2_reg_to_regnum:          Defining Other Architecture Features.
   8238                                                               (line 216)
   8239 * gdbarch_ecoff_reg_to_regnum:           Defining Other Architecture Features.
   8240                                                               (line 220)
   8241 * gdbarch_float_bit:                     Defining Other Architecture Features.
   8242                                                               (line 475)
   8243 * gdbarch_fp0_regnum:                    Defining Other Architecture Features.
   8244                                                               (line 200)
   8245 * gdbarch_get_longjmp_target <1>:        Defining Other Architecture Features.
   8246                                                               (line 231)
   8247 * gdbarch_get_longjmp_target:            Algorithms.          (line 263)
   8248 * gdbarch_have_nonsteppable_watchpoint:  Algorithms.          (line 396)
   8249 * gdbarch_in_function_epilogue_p:        Defining Other Architecture Features.
   8250                                                               (line 253)
   8251 * gdbarch_in_solib_return_trampoline:    Defining Other Architecture Features.
   8252                                                               (line 259)
   8253 * gdbarch_info:                          Looking Up an Existing Architecture.
   8254                                                               (line  22)
   8255 * gdbarch_init_osabi:                    OS ABI Variant Handling.
   8256                                                               (line 125)
   8257 * gdbarch_int_bit:                       Defining Other Architecture Features.
   8258                                                               (line 478)
   8259 * gdbarch_integer_to_address:            Defining Other Architecture Features.
   8260                                                               (line 274)
   8261 * gdbarch_list_lookup_by_info:           Looking Up an Existing Architecture.
   8262                                                               (line  22)
   8263 * gdbarch_long_bit:                      Defining Other Architecture Features.
   8264                                                               (line 481)
   8265 * gdbarch_long_double_bit:               Defining Other Architecture Features.
   8266                                                               (line 485)
   8267 * gdbarch_long_long_bit:                 Defining Other Architecture Features.
   8268                                                               (line 489)
   8269 * gdbarch_lookup_osabi:                  OS ABI Variant Handling.
   8270                                                               (line 119)
   8271 * gdbarch_memory_insert_breakpoint:      Defining Other Architecture Features.
   8272                                                               (line 130)
   8273 * gdbarch_memory_remove_breakpoint:      Defining Other Architecture Features.
   8274                                                               (line 130)
   8275 * gdbarch_osabi_name:                    OS ABI Variant Handling.
   8276                                                               (line  97)
   8277 * gdbarch_pointer_to_address <1>:        Defining Other Architecture Features.
   8278                                                               (line 295)
   8279 * gdbarch_pointer_to_address:            Pointers and Addresses.
   8280                                                               (line 105)
   8281 * gdbarch_print_insn:                    Defining Other Architecture Features.
   8282                                                               (line 513)
   8283 * gdbarch_ptr_bit:                       Defining Other Architecture Features.
   8284                                                               (line 493)
   8285 * gdbarch_push_dummy_call:               Defining Other Architecture Features.
   8286                                                               (line 363)
   8287 * gdbarch_push_dummy_code:               Defining Other Architecture Features.
   8288                                                               (line 375)
   8289 * gdbarch_register <1>:                  Adding a New Target. (line  40)
   8290 * gdbarch_register:                      How an Architecture is Represented.
   8291                                                               (line  19)
   8292 * gdbarch_register_osabi:                OS ABI Variant Handling.
   8293                                                               (line 103)
   8294 * gdbarch_register_osabi_sniffer:        OS ABI Variant Handling.
   8295                                                               (line 112)
   8296 * gdbarch_register_to_value <1>:         Defining Other Architecture Features.
   8297                                                               (line 301)
   8298 * gdbarch_register_to_value:             Register and Memory Data.
   8299                                                               (line  46)
   8300 * gdbarch_return_value:                  Defining Other Architecture Features.
   8301                                                               (line 394)
   8302 * gdbarch_sdb_reg_to_regnum:             Defining Other Architecture Features.
   8303                                                               (line 390)
   8304 * gdbarch_short_bit:                     Defining Other Architecture Features.
   8305                                                               (line 497)
   8306 * gdbarch_skip_permanent_breakpoint:     Defining Other Architecture Features.
   8307                                                               (line 430)
   8308 * gdbarch_skip_trampoline_code:          Defining Other Architecture Features.
   8309                                                               (line 441)
   8310 * gdbarch_stab_reg_to_regnum:            Defining Other Architecture Features.
   8311                                                               (line 450)
   8312 * gdbarch_stabs_argument_has_addr:       Defining Other Architecture Features.
   8313                                                               (line 359)
   8314 * gdbarch_tdep definition:               Creating a New Architecture.
   8315                                                               (line  34)
   8316 * gdbarch_tdep when allocating new gdbarch: Creating a New Architecture.
   8317                                                               (line   6)
   8318 * gdbarch_value_to_register <1>:         Defining Other Architecture Features.
   8319                                                               (line 529)
   8320 * gdbarch_value_to_register:             Register and Memory Data.
   8321                                                               (line  62)
   8322 * gdbarch_virtual_frame_pointer:         Defining Other Architecture Features.
   8323                                                               (line 501)
   8324 * GDBINIT_FILENAME:                      Host Definition.     (line  74)
   8325 * generic host support:                  Host Definition.     (line  38)
   8326 * generic_elf_osabi_sniff_abi_tag_sections: OS ABI Variant Handling.
   8327                                                               (line 133)
   8328 * get_frame_register:                    Stack Frames.        (line  15)
   8329 * get_frame_type:                        Stack Frames.        (line  22)
   8330 * hardware breakpoints:                  Algorithms.          (line 158)
   8331 * hardware watchpoints:                  Algorithms.          (line 280)
   8332 * HAVE_CONTINUABLE_WATCHPOINT:           Algorithms.          (line 402)
   8333 * HAVE_DOS_BASED_FILE_SYSTEM:            Coding.              (line 556)
   8334 * HAVE_STEPPABLE_WATCHPOINT:             Algorithms.          (line 386)
   8335 * host:                                  Overall Structure.   (line  50)
   8336 * host, adding:                          Host Definition.     (line  13)
   8337 * i386_cleanup_dregs:                    Algorithms.          (line 580)
   8338 * I386_DR_LOW_GET_STATUS:                Algorithms.          (line 493)
   8339 * I386_DR_LOW_RESET_ADDR:                Algorithms.          (line 489)
   8340 * I386_DR_LOW_SET_ADDR:                  Algorithms.          (line 486)
   8341 * I386_DR_LOW_SET_CONTROL:               Algorithms.          (line 483)
   8342 * i386_insert_hw_breakpoint:             Algorithms.          (line 568)
   8343 * i386_insert_watchpoint:                Algorithms.          (line 540)
   8344 * i386_region_ok_for_watchpoint:         Algorithms.          (line 518)
   8345 * i386_remove_hw_breakpoint:             Algorithms.          (line 568)
   8346 * i386_remove_watchpoint:                Algorithms.          (line 540)
   8347 * i386_stopped_by_watchpoint:            Algorithms.          (line 532)
   8348 * i386_stopped_data_address:             Algorithms.          (line 525)
   8349 * I386_USE_GENERIC_WATCHPOINTS:          Algorithms.          (line 465)
   8350 * in_dynsym_resolve_code:                Defining Other Architecture Features.
   8351                                                               (line 263)
   8352 * inferior_appeared:                     GDB Observers.       (line 169)
   8353 * inferior_created:                      GDB Observers.       (line  92)
   8354 * inferior_exit:                         GDB Observers.       (line 172)
   8355 * inner_than:                            Functions and Variable to Analyze Frames.
   8356                                                               (line  30)
   8357 * innermost frame:                       Frame Handling Terminology.
   8358                                                               (line  24)
   8359 * insert or remove hardware breakpoint:  Algorithms.          (line 234)
   8360 * insert or remove hardware watchpoint:  Algorithms.          (line 347)
   8361 * insert or remove software breakpoint:  Algorithms.          (line 211)
   8362 * IS_ABSOLUTE_PATH:                      Coding.              (line 567)
   8363 * IS_DIR_SEPARATOR:                      Coding.              (line 562)
   8364 * ISATTY:                                Host Definition.     (line  99)
   8365 * item output functions:                 User Interface.      (line 254)
   8366 * language parser:                       Language Support.    (line  25)
   8367 * language support:                      Language Support.    (line   6)
   8368 * legal papers for code contributions:   Debugging GDB.       (line  42)
   8369 * length_of_subexp:                      Language Support.    (line  58)
   8370 * libgdb:                                libgdb.              (line   9)
   8371 * libiberty library:                     Support Libraries.   (line  52)
   8372 * line wrap in output:                   Coding.              (line 191)
   8373 * lint:                                  Host Definition.     (line 133)
   8374 * list output functions:                 User Interface.      (line 131)
   8375 * LITTLE_BREAKPOINT:                     Defining Other Architecture Features.
   8376                                                               (line 100)
   8377 * long long data type:                   Host Definition.     (line 106)
   8378 * longjmp debugging:                     Algorithms.          (line 258)
   8379 * lookup_symbol:                         Symbol Handling.     (line 142)
   8380 * LSEEK_NOT_LINEAR:                      Host Definition.     (line 114)
   8381 * lval_type enumeration, for values.:    Values.              (line  19)
   8382 * make_cleanup:                          Coding.              (line  28)
   8383 * make_cleanup_ui_out_list_begin_end:    User Interface.      (line 247)
   8384 * make_cleanup_ui_out_tuple_begin_end:   User Interface.      (line 223)
   8385 * making a new release of gdb:           Releasing GDB.       (line   6)
   8386 * memory representation:                 Register and Memory Data.
   8387                                                               (line   6)
   8388 * memory_changed:                        GDB Observers.       (line 177)
   8389 * minimal symbol table:                  Symbol Handling.     (line 111)
   8390 * minsymtabs:                            Symbol Handling.     (line 111)
   8391 * multi-arch data:                       Coding.              (line 100)
   8392 * NATDEPFILES:                           Native Debugging.    (line   8)
   8393 * native conditionals:                   Native Debugging.    (line  75)
   8394 * native debugging:                      Native Debugging.    (line   6)
   8395 * nesting level in ui_out functions:     User Interface.      (line 143)
   8396 * new year procedure:                    Start of New Year Procedure.
   8397                                                               (line   6)
   8398 * new_objfile:                           GDB Observers.       (line 109)
   8399 * new_thread:                            GDB Observers.       (line 114)
   8400 * NEXT frame:                            Frame Handling Terminology.
   8401                                                               (line  11)
   8402 * NORETURN:                              Host Definition.     (line 119)
   8403 * normal_stop:                           GDB Observers.       (line  76)
   8404 * normal_stop observer:                  GDB Observers.       (line  48)
   8405 * notification about inferior execution stop: GDB Observers.  (line  48)
   8406 * notifications about changes in internals: Algorithms.       (line 634)
   8407 * object file formats:                   Symbol Handling.     (line 210)
   8408 * observer pattern interface:            Algorithms.          (line 634)
   8409 * observers implementation rationale:    GDB Observers.       (line   9)
   8410 * obstacks:                              Support Libraries.   (line  69)
   8411 * op_print_tab:                          Language Support.    (line  91)
   8412 * opcodes library:                       Support Libraries.   (line  39)
   8413 * OS ABI variants:                       OS ABI Variant Handling.
   8414                                                               (line   6)
   8415 * parse_exp_1:                           Language Support.    (line  97)
   8416 * partial symbol table:                  Symbol Handling.     (line 114)
   8417 * pc_regnum:                             Register Architecture Functions & Variables.
   8418                                                               (line  58)
   8419 * PE-COFF format:                        Symbol Handling.     (line 267)
   8420 * per-architecture module data:          Coding.              (line 100)
   8421 * pointer representation:                Pointers and Addresses.
   8422                                                               (line   6)
   8423 * portability:                           Coding.              (line 530)
   8424 * portable file name handling:           Coding.              (line 547)
   8425 * porting to new machines:               Porting GDB.         (line   6)
   8426 * prefixify_subexp:                      Language Support.    (line  58)
   8427 * PREVIOUS frame:                        Frame Handling Terminology.
   8428                                                               (line  14)
   8429 * print_float_info:                      Register Information Functions.
   8430                                                               (line  80)
   8431 * print_registers_info:                  Register Information Functions.
   8432                                                               (line  53)
   8433 * print_subexp:                          Language Support.    (line  91)
   8434 * print_vector_info:                     Register Information Functions.
   8435                                                               (line  96)
   8436 * PRINTF_HAS_LONG_LONG:                  Host Definition.     (line 109)
   8437 * processor status register:             Register Architecture Functions & Variables.
   8438                                                               (line  69)
   8439 * program counter <1>:                   Register Architecture Functions & Variables.
   8440                                                               (line  58)
   8441 * program counter:                       Algorithms.          (line 158)
   8442 * prologue analysis:                     Algorithms.          (line  14)
   8443 * prologue cache:                        Prologue Caches.     (line  12)
   8444 * prologue of a function:                Prologue Caches.     (line   6)
   8445 * prologue-value.c:                      Algorithms.          (line  48)
   8446 * prompt:                                Host Definition.     (line  94)
   8447 * ps_regnum:                             Register Architecture Functions & Variables.
   8448                                                               (line  69)
   8449 * pseudo-evaluation of function prologues: Algorithms.        (line  48)
   8450 * pseudo_register_read:                  Register Architecture Functions & Variables.
   8451                                                               (line  29)
   8452 * pseudo_register_write:                 Register Architecture Functions & Variables.
   8453                                                               (line  33)
   8454 * psymtabs:                              Symbol Handling.     (line 107)
   8455 * push_dummy_call:                       Functions Creating Dummy Frames.
   8456                                                               (line  13)
   8457 * push_dummy_code:                       Functions Creating Dummy Frames.
   8458                                                               (line  57)
   8459 * raw register representation:           Raw and Cooked Registers.
   8460                                                               (line   6)
   8461 * read_pc:                               Register Architecture Functions & Variables.
   8462                                                               (line  10)
   8463 * reading of symbols:                    Symbol Handling.     (line  25)
   8464 * readline library:                      Support Libraries.   (line  45)
   8465 * regcache_cooked_read:                  Register Caching.    (line  23)
   8466 * regcache_cooked_read_signed:           Register Caching.    (line  23)
   8467 * regcache_cooked_read_unsigned:         Register Caching.    (line  23)
   8468 * regcache_cooked_write:                 Register Caching.    (line  23)
   8469 * regcache_cooked_write_signed:          Register Caching.    (line  23)
   8470 * regcache_cooked_write_unsigned:        Register Caching.    (line  23)
   8471 * register caching:                      Register Caching.    (line   6)
   8472 * register data formats, converting:     Register and Memory Data.
   8473                                                               (line   6)
   8474 * register representation:               Register and Memory Data.
   8475                                                               (line   6)
   8476 * REGISTER_CONVERT_TO_RAW:               Defining Other Architecture Features.
   8477                                                               (line 311)
   8478 * REGISTER_CONVERT_TO_VIRTUAL:           Defining Other Architecture Features.
   8479                                                               (line 306)
   8480 * register_name:                         Register Information Functions.
   8481                                                               (line  10)
   8482 * register_reggroup_p:                   Register Information Functions.
   8483                                                               (line 110)
   8484 * register_type:                         Register Information Functions.
   8485                                                               (line  33)
   8486 * regset_from_core_section:              Defining Other Architecture Features.
   8487                                                               (line 316)
   8488 * regular expressions library:           Support Libraries.   (line 110)
   8489 * Release Branches:                      Versions and Branches.
   8490                                                               (line  93)
   8491 * remote debugging support:              Host Definition.     (line  41)
   8492 * REMOTE_BPT_VECTOR:                     Defining Other Architecture Features.
   8493                                                               (line 540)
   8494 * representation of architecture:        How an Architecture is Represented.
   8495                                                               (line   6)
   8496 * representations, raw and cooked registers: Raw and Cooked Registers.
   8497                                                               (line   6)
   8498 * representations, register and memory:  Register and Memory Data.
   8499                                                               (line   6)
   8500 * requirements for GDB:                  Requirements.        (line   6)
   8501 * restart:                               Algorithms.          (line 604)
   8502 * running the test suite:                Testsuite.           (line  19)
   8503 * secondary symbol file:                 Symbol Handling.     (line  47)
   8504 * sentinel frame <1>:                    Frame Handling Terminology.
   8505                                                               (line  52)
   8506 * sentinel frame:                        Stack Frames.        (line  22)
   8507 * SENTINEL_FRAME:                        Stack Frames.        (line  22)
   8508 * separate data and code address spaces: Pointers and Addresses.
   8509                                                               (line   6)
   8510 * serial line support:                   Host Definition.     (line  41)
   8511 * set_gdbarch functions:                 Creating a New Architecture.
   8512                                                               (line  14)
   8513 * set_gdbarch_bits_big_endian:           Defining Other Architecture Features.
   8514                                                               (line  83)
   8515 * set_gdbarch_sofun_address_maybe_missing: Defining Other Architecture Features.
   8516                                                               (line 330)
   8517 * SIGWINCH_HANDLER:                      Host Definition.     (line  78)
   8518 * SIGWINCH_HANDLER_BODY:                 Host Definition.     (line  82)
   8519 * skip_prologue:                         Functions and Variable to Analyze Frames.
   8520                                                               (line  12)
   8521 * SKIP_SOLIB_RESOLVER:                   Defining Other Architecture Features.
   8522                                                               (line 267)
   8523 * SLASH_STRING:                          Coding.              (line 584)
   8524 * sniffing:                              Frame Handling Terminology.
   8525                                                               (line  46)
   8526 * software breakpoints:                  Algorithms.          (line 184)
   8527 * software watchpoints:                  Algorithms.          (line 280)
   8528 * SOFTWARE_SINGLE_STEP:                  Defining Other Architecture Features.
   8529                                                               (line 324)
   8530 * SOFTWARE_SINGLE_STEP_P:                Defining Other Architecture Features.
   8531                                                               (line 320)
   8532 * SOLIB_ADD:                             Native Debugging.    (line  86)
   8533 * SOLIB_CREATE_INFERIOR_HOOK:            Native Debugging.    (line  92)
   8534 * solib_loaded:                          GDB Observers.       (line  99)
   8535 * solib_unloaded:                        GDB Observers.       (line 104)
   8536 * SOM debugging info:                    Symbol Handling.     (line 355)
   8537 * SOM format:                            Symbol Handling.     (line 286)
   8538 * source code formatting:                Coding.              (line 323)
   8539 * sp_regnum:                             Register Architecture Functions & Variables.
   8540                                                               (line  49)
   8541 * spaces, separate data and code address: Pointers and Addresses.
   8542                                                               (line   6)
   8543 * stabs debugging info:                  Symbol Handling.     (line 300)
   8544 * stack frame, definition of base of a frame: Frame Handling Terminology.
   8545                                                               (line  28)
   8546 * stack frame, definition of innermost frame: Frame Handling Terminology.
   8547                                                               (line  24)
   8548 * stack frame, definition of NEXT frame: Frame Handling Terminology.
   8549                                                               (line  11)
   8550 * stack frame, definition of PREVIOUS frame: Frame Handling Terminology.
   8551                                                               (line  14)
   8552 * stack frame, definition of sentinel frame: Frame Handling Terminology.
   8553                                                               (line  52)
   8554 * stack frame, definition of sniffing:   Frame Handling Terminology.
   8555                                                               (line  46)
   8556 * stack frame, definition of THIS frame: Frame Handling Terminology.
   8557                                                               (line   9)
   8558 * stack frame, definition of unwinding:  Frame Handling Terminology.
   8559                                                               (line  41)
   8560 * stack pointer:                         Register Architecture Functions & Variables.
   8561                                                               (line  49)
   8562 * START_INFERIOR_TRAPS_EXPECTED:         Native Debugging.    (line  96)
   8563 * status register:                       Register Architecture Functions & Variables.
   8564                                                               (line  69)
   8565 * STOPPED_BY_WATCHPOINT:                 Algorithms.          (line 412)
   8566 * store_typed_address:                   Pointers and Addresses.
   8567                                                               (line  70)
   8568 * struct:                                GDB Observers.       (line  62)
   8569 * struct gdbarch creation:               Creating a New Architecture.
   8570                                                               (line   6)
   8571 * struct regcache:                       Register Caching.    (line  10)
   8572 * struct value, converting register contents to: Register and Memory Data.
   8573                                                               (line   6)
   8574 * submitting patches:                    Debugging GDB.       (line  30)
   8575 * sym_fns structure:                     Symbol Handling.     (line  37)
   8576 * symbol files:                          Symbol Handling.     (line  25)
   8577 * symbol lookup:                         Symbol Handling.     (line 133)
   8578 * symbol reading:                        Symbol Handling.     (line  25)
   8579 * SYMBOL_RELOADING_DEFAULT:              Defining Other Architecture Features.
   8580                                                               (line 454)
   8581 * symtabs:                               Symbol Handling.     (line 104)
   8582 * system dependencies:                   Coding.              (line 534)
   8583 * table output functions:                User Interface.      (line 131)
   8584 * target:                                Overall Structure.   (line  50)
   8585 * target architecture definition:        Target Architecture Definition.
   8586                                                               (line   6)
   8587 * target dependent files:                Adding a New Target. (line   8)
   8588 * target descriptions:                   Target Descriptions. (line   6)
   8589 * target descriptions, adding register support: Adding Target Described Register Support.
   8590                                                               (line   6)
   8591 * target descriptions, implementation:   Target Descriptions Implementation.
   8592                                                               (line   6)
   8593 * target vector:                         Target Vector Definition.
   8594                                                               (line   6)
   8595 * TARGET_CAN_USE_HARDWARE_WATCHPOINT:    Algorithms.          (line 333)
   8596 * target_changed:                        GDB Observers.       (line  82)
   8597 * TARGET_CHAR_BIT:                       Defining Other Architecture Features.
   8598                                                               (line 458)
   8599 * target_insert_breakpoint:              Algorithms.          (line 211)
   8600 * target_insert_hw_breakpoint:           Algorithms.          (line 234)
   8601 * target_insert_watchpoint:              Algorithms.          (line 347)
   8602 * TARGET_REGION_OK_FOR_HW_WATCHPOINT:    Algorithms.          (line 343)
   8603 * target_remove_breakpoint:              Algorithms.          (line 211)
   8604 * target_remove_hw_breakpoint:           Algorithms.          (line 234)
   8605 * target_remove_watchpoint:              Algorithms.          (line 347)
   8606 * target_resumed:                        GDB Observers.       (line 129)
   8607 * target_stopped_data_address:           Algorithms.          (line 364)
   8608 * target_watchpoint_addr_within_range:   Algorithms.          (line 378)
   8609 * targets:                               Existing Targets.    (line   6)
   8610 * TCP remote support:                    Host Definition.     (line  57)
   8611 * terminal device:                       Host Definition.     (line  97)
   8612 * test suite:                            Testsuite.           (line   6)
   8613 * test suite organization:               Testsuite.           (line 195)
   8614 * test_notification:                     GDB Observers.       (line 181)
   8615 * Testsuite Configuration:               Testsuite.           (line 167)
   8616 * THIS frame:                            Frame Handling Terminology.
   8617                                                               (line   9)
   8618 * thread_exit:                           GDB Observers.       (line 117)
   8619 * thread_ptid_changed:                   GDB Observers.       (line 165)
   8620 * thread_stop_requested:                 GDB Observers.       (line 122)
   8621 * tracepoint_created:                    GDB Observers.       (line 148)
   8622 * tracepoint_deleted:                    GDB Observers.       (line 152)
   8623 * tracepoint_modified:                   GDB Observers.       (line 156)
   8624 * tuple output functions:                User Interface.      (line 131)
   8625 * type codes:                            Symbol Handling.     (line 186)
   8626 * types:                                 Coding.              (line 405)
   8627 * ui_out functions:                      User Interface.      (line  47)
   8628 * ui_out functions, usage examples:      User Interface.      (line 398)
   8629 * ui_out_field_core_addr:                User Interface.      (line 287)
   8630 * ui_out_field_fmt:                      User Interface.      (line 261)
   8631 * ui_out_field_fmt_int:                  User Interface.      (line 280)
   8632 * ui_out_field_int:                      User Interface.      (line 273)
   8633 * ui_out_field_skip:                     User Interface.      (line 352)
   8634 * ui_out_field_stream:                   User Interface.      (line 320)
   8635 * ui_out_field_string:                   User Interface.      (line 291)
   8636 * ui_out_flush:                          User Interface.      (line 392)
   8637 * ui_out_list_begin:                     User Interface.      (line 234)
   8638 * ui_out_list_end:                       User Interface.      (line 240)
   8639 * ui_out_message:                        User Interface.      (line 376)
   8640 * ui_out_spaces:                         User Interface.      (line 371)
   8641 * ui_out_stream_delete:                  User Interface.      (line 315)
   8642 * ui_out_stream_new:                     User Interface.      (line 309)
   8643 * ui_out_table_begin:                    User Interface.      (line 165)
   8644 * ui_out_table_body:                     User Interface.      (line 191)
   8645 * ui_out_table_end:                      User Interface.      (line 194)
   8646 * ui_out_table_header:                   User Interface.      (line 178)
   8647 * ui_out_text:                           User Interface.      (line 358)
   8648 * ui_out_tuple_begin:                    User Interface.      (line 210)
   8649 * ui_out_tuple_end:                      User Interface.      (line 216)
   8650 * ui_out_wrap_hint:                      User Interface.      (line 382)
   8651 * unwind frame:                          Stack Frames.        (line   9)
   8652 * unwind_dummy_id:                       Functions Creating Dummy Frames.
   8653                                                               (line  38)
   8654 * unwind_pc:                             Functions to Access Frame Data.
   8655                                                               (line  11)
   8656 * unwind_sp:                             Functions to Access Frame Data.
   8657                                                               (line  27)
   8658 * unwinding:                             Frame Handling Terminology.
   8659                                                               (line  41)
   8660 * using ui_out functions:                User Interface.      (line 398)
   8661 * value structure:                       Values.              (line   9)
   8662 * value_as_address:                      Pointers and Addresses.
   8663                                                               (line  84)
   8664 * value_from_pointer:                    Pointers and Addresses.
   8665                                                               (line  93)
   8666 * values:                                Values.              (line   9)
   8667 * VEC:                                   Support Libraries.   (line 131)
   8668 * vendor branches:                       Versions and Branches.
   8669                                                               (line 108)
   8670 * void:                                  GDB Observers.       (line  67)
   8671 * volatile:                              Host Definition.     (line 136)
   8672 * watchpoints:                           Algorithms.          (line 274)
   8673 * watchpoints, on x86:                   Algorithms.          (line 453)
   8674 * watchpoints, with threads:             Algorithms.          (line 429)
   8675 * word-addressed machines:               Pointers and Addresses.
   8676                                                               (line   6)
   8677 * wrap_here:                             Coding.              (line 191)
   8678 * write_pc:                              Register Architecture Functions & Variables.
   8679                                                               (line  13)
   8680 * writing tests:                         Testsuite.           (line 247)
   8681 * x86 debug registers:                   Algorithms.          (line 453)
   8682 * XCOFF format:                          Symbol Handling.     (line 251)
   8683 
   8684 
   8685 
   8686 Tag Table:
   8687 Node: Top1589
   8688 Node: Summary2470
   8689 Node: Requirements2620
   8690 Node: Contributors4099
   8691 Node: Overall Structure5692
   8692 Node: Algorithms10715
   8693 Node: User Interface42299
   8694 Ref: UI-Independent Output44154
   8695 Ref: User Interface-Footnote-166125
   8696 Ref: User Interface-Footnote-266174
   8697 Node: libgdb66409
   8698 Node: Values70360
   8699 Node: Stack Frames73204
   8700 Node: Symbol Handling78186
   8701 Node: Language Support94720
   8702 Node: Host Definition99446
   8703 Node: Target Architecture Definition104437
   8704 Node: OS ABI Variant Handling105257
   8705 Node: Initialize New Architecture110102
   8706 Node: How an Architecture is Represented110453
   8707 Node: Looking Up an Existing Architecture112410
   8708 Node: Creating a New Architecture115329
   8709 Node: Registers and Memory117367
   8710 Node: Pointers and Addresses118159
   8711 Ref: Pointers and Addresses-Footnote-1124160
   8712 Node: Address Classes124403
   8713 Node: Register Representation127648
   8714 Node: Raw and Cooked Registers128022
   8715 Node: Register Architecture Functions & Variables129206
   8716 Node: Register Information Functions132815
   8717 Ref: Register Information Functions-Footnote-1138721
   8718 Node: Register and Memory Data139140
   8719 Node: Register Caching142289
   8720 Node: Frame Interpretation143825
   8721 Node: All About Stack Frames144231
   8722 Ref: All About Stack Frames-Footnote-1149523
   8723 Node: Frame Handling Terminology149755
   8724 Node: Prologue Caches152282
   8725 Node: Functions and Variable to Analyze Frames153963
   8726 Ref: frame_align156061
   8727 Node: Functions to Access Frame Data157575
   8728 Node: Analyzing Stacks---Frame Sniffers159866
   8729 Ref: Analyzing Stacks---Frame Sniffers-Footnote-1164516
   8730 Node: Inferior Call Setup165013
   8731 Node: About Dummy Frames165296
   8732 Node: Functions Creating Dummy Frames165922
   8733 Node: Adding support for debugging core files169979
   8734 Node: Defining Other Architecture Features170523
   8735 Ref: gdbarch_breakpoint_from_pc175370
   8736 Ref: gdbarch_stabs_argument_has_addr187764
   8737 Ref: gdbarch_push_dummy_call188011
   8738 Ref: gdbarch_push_dummy_code188571
   8739 Ref: gdbarch_return_value189553
   8740 Ref: gdbarch_dummy_id195319
   8741 Node: Adding a New Target196007
   8742 Node: Target Descriptions198474
   8743 Node: Target Descriptions Implementation199413
   8744 Node: Adding Target Described Register Support200787
   8745 Node: Target Vector Definition203733
   8746 Node: Managing Execution State204265
   8747 Node: Existing Targets206078
   8748 Node: Native Debugging208593
   8749 Node: Support Libraries212421
   8750 Node: Coding223936
   8751 Node: Porting GDB248945
   8752 Node: Versions and Branches250814
   8753 Ref: Tags256770
   8754 Ref: experimental branch tags257101
   8755 Node: Start of New Year Procedure257833
   8756 Node: Releasing GDB259639
   8757 Node: Testsuite277871
   8758 Ref: Testsuite-Footnote-1289736
   8759 Node: Hints289854
   8760 Node: Getting Started290176
   8761 Node: Debugging GDB294319
   8762 Node: GDB Observers299384
   8763 Node: GNU Free Documentation License307286
   8764 Node: Index329730
   8765 
   8766 End Tag Table
   8767