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