+++ /dev/null
-This is gdbint.info, produced by makeinfo version 4.13 from
-/home/jingyu/projects/gcc/android-toolchainsrc/build/../gdb/gdb-7.1.x/gdb/doc/gdbint.texinfo.
-
-INFO-DIR-SECTION Software development
-START-INFO-DIR-ENTRY
-* Gdb-Internals: (gdbint). The GNU debugger's internals.
-END-INFO-DIR-ENTRY
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
-2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Free Software
-Foundation, Inc. Contributed by Cygnus Solutions. Written by John
-Gilmore. Second Edition by Stan Shebs.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
- This file documents the internals of the GNU debugger GDB.
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
-2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Free Software
-Foundation, Inc. Contributed by Cygnus Solutions. Written by John
-Gilmore. Second Edition by Stan Shebs.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: gdbint.info, Node: Top, Next: Summary, Up: (dir)
-
-Scope of this Document
-**********************
-
-This document documents the internals of the GNU debugger, GDB. It
-includes description of GDB's key algorithms and operations, as well as
-the mechanisms that adapt GDB to specific hosts and targets.
-
-* Menu:
-
-* Summary::
-* Overall Structure::
-* Algorithms::
-* User Interface::
-* libgdb::
-* Values::
-* Stack Frames::
-* Symbol Handling::
-* Language Support::
-* Host Definition::
-* Target Architecture Definition::
-* Target Descriptions::
-* Target Vector Definition::
-* Native Debugging::
-* Support Libraries::
-* Coding::
-* Porting GDB::
-* Versions and Branches::
-* Start of New Year Procedure::
-* Releasing GDB::
-* Testsuite::
-* Hints::
-
-* GDB Observers:: GDB Currently available observers
-* GNU Free Documentation License:: The license for this documentation
-* Index::
-
-\1f
-File: gdbint.info, Node: Summary, Next: Overall Structure, Prev: Top, Up: Top
-
-1 Summary
-*********
-
-* Menu:
-
-* Requirements::
-* Contributors::
-
-\1f
-File: gdbint.info, Node: Requirements, Next: Contributors, Up: Summary
-
-1.1 Requirements
-================
-
-Before diving into the internals, you should understand the formal
-requirements and other expectations for GDB. Although some of these
-may seem obvious, there have been proposals for GDB that have run
-counter to these requirements.
-
- First of all, GDB is a debugger. It's not designed to be a front
-panel for embedded systems. It's not a text editor. It's not a shell.
-It's not a programming environment.
-
- GDB is an interactive tool. Although a batch mode is available,
-GDB's primary role is to interact with a human programmer.
-
- GDB should be responsive to the user. A programmer hot on the trail
-of a nasty bug, and operating under a looming deadline, is going to be
-very impatient of everything, including the response time to debugger
-commands.
-
- GDB should be relatively permissive, such as for expressions. While
-the compiler should be picky (or have the option to be made picky),
-since source code lives for a long time usually, the programmer doing
-debugging shouldn't be spending time figuring out to mollify the
-debugger.
-
- GDB will be called upon to deal with really large programs.
-Executable sizes of 50 to 100 megabytes occur regularly, and we've
-heard reports of programs approaching 1 gigabyte in size.
-
- GDB should be able to run everywhere. No other debugger is
-available for even half as many configurations as GDB supports.
-
-\1f
-File: gdbint.info, Node: Contributors, Prev: Requirements, Up: Summary
-
-1.2 Contributors
-================
-
-The first edition of this document was written by John Gilmore of
-Cygnus Solutions. The current second edition was written by Stan Shebs
-of Cygnus Solutions, who continues to update the manual.
-
- Over the years, many others have made additions and changes to this
-document. This section attempts to record the significant contributors
-to that effort. One of the virtues of free software is that everyone is
-free to contribute to it; with regret, we cannot actually acknowledge
-everyone here.
-
- _Plea:_ This section has only been added relatively recently (four
- years after publication of the second edition). Additions to this
- section are particularly welcome. If you or your friends (or
- enemies, to be evenhanded) have been unfairly omitted from this
- list, we would like to add your names!
-
- A document such as this relies on being kept up to date by numerous
-small updates by contributing engineers as they make changes to the
-code base. The file `ChangeLog' in the GDB distribution approximates a
-blow-by-blow account. The most prolific contributors to this important,
-but low profile task are Andrew Cagney (responsible for over half the
-entries), Daniel Jacobowitz, Mark Kettenis, Jim Blandy and Eli
-Zaretskii.
-
- Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting
-watchpoints.
-
- Jeremy Bennett updated the sections on initializing a new
-architecture and register representation, and added the section on
-Frame Interpretation.
-
-\1f
-File: gdbint.info, Node: Overall Structure, Next: Algorithms, Prev: Summary, Up: Top
-
-2 Overall Structure
-*******************
-
-GDB consists of three major subsystems: user interface, symbol handling
-(the "symbol side"), and target system handling (the "target side").
-
- The user interface consists of several actual interfaces, plus
-supporting code.
-
- The symbol side consists of object file readers, debugging info
-interpreters, symbol table management, source language expression
-parsing, type and value printing.
-
- The target side consists of execution control, stack frame analysis,
-and physical target manipulation.
-
- The target side/symbol side division is not formal, and there are a
-number of exceptions. For instance, core file support involves symbolic
-elements (the basic core file reader is in BFD) and target elements (it
-supplies the contents of memory and the values of registers). Instead,
-this division is useful for understanding how the minor subsystems
-should fit together.
-
-2.1 The Symbol Side
-===================
-
-The symbolic side of GDB can be thought of as "everything you can do in
-GDB without having a live program running". For instance, you can look
-at the types of variables, and evaluate many kinds of expressions.
-
-2.2 The Target Side
-===================
-
-The target side of GDB is the "bits and bytes manipulator". Although
-it may make reference to symbolic info here and there, most of the
-target side will run with only a stripped executable available--or even
-no executable at all, in remote debugging cases.
-
- Operations such as disassembly, stack frame crawls, and register
-display, are able to work with no symbolic info at all. In some cases,
-such as disassembly, GDB will use symbolic info to present addresses
-relative to symbols rather than as raw numbers, but it will work either
-way.
-
-2.3 Configurations
-==================
-
-"Host" refers to attributes of the system where GDB runs. "Target"
-refers to the system where the program being debugged executes. In
-most cases they are the same machine, in which case a third type of
-"Native" attributes come into play.
-
- Defines and include files needed to build on the host are host
-support. Examples are tty support, system defined types, host byte
-order, host float format. These are all calculated by `autoconf' when
-the debugger is built.
-
- Defines and information needed to handle the target format are target
-dependent. Examples are the stack frame format, instruction set,
-breakpoint instruction, registers, and how to set up and tear down the
-stack to call a function.
-
- Information that is only needed when the host and target are the
-same, is native dependent. One example is Unix child process support;
-if the host and target are not the same, calling `fork' to start the
-target process is a bad idea. The various macros needed for finding the
-registers in the `upage', running `ptrace', and such are all in the
-native-dependent files.
-
- Another example of native-dependent code is support for features that
-are really part of the target environment, but which require `#include'
-files that are only available on the host system. Core file handling
-and `setjmp' handling are two common cases.
-
- When you want to make GDB work as the traditional native debugger on
-a system, you will need to supply both target and native information.
-
-2.4 Source Tree Structure
-=========================
-
-The GDB source directory has a mostly flat structure--there are only a
-few subdirectories. A file's name usually gives a hint as to what it
-does; for example, `stabsread.c' reads stabs, `dwarf2read.c' reads
-DWARF 2, etc.
-
- Files that are related to some common task have names that share
-common substrings. For example, `*-thread.c' files deal with debugging
-threads on various platforms; `*read.c' files deal with reading various
-kinds of symbol and object files; `inf*.c' files deal with direct
-control of the "inferior program" (GDB parlance for the program being
-debugged).
-
- There are several dozens of files in the `*-tdep.c' family. `tdep'
-stands for "target-dependent code"--each of these files implements
-debug support for a specific target architecture (sparc, mips, etc).
-Usually, only one of these will be used in a specific GDB configuration
-(sometimes two, closely related).
-
- Similarly, there are many `*-nat.c' files, each one for native
-debugging on a specific system (e.g., `sparc-linux-nat.c' is for native
-debugging of Sparc machines running the Linux kernel).
-
- The few subdirectories of the source tree are:
-
-`cli'
- Code that implements "CLI", the GDB Command-Line Interpreter.
- *Note Command Interpreter: User Interface.
-
-`gdbserver'
- Code for the GDB remote server.
-
-`gdbtk'
- Code for Insight, the GDB TK-based GUI front-end.
-
-`mi'
- The "GDB/MI", the GDB Machine Interface interpreter.
-
-`signals'
- Target signal translation code.
-
-`tui'
- Code for "TUI", the GDB Text-mode full-screen User Interface.
- *Note TUI: User Interface.
-
-\1f
-File: gdbint.info, Node: Algorithms, Next: User Interface, Prev: Overall Structure, Up: Top
-
-3 Algorithms
-************
-
-GDB uses a number of debugging-specific algorithms. They are often not
-very complicated, but get lost in the thicket of special cases and
-real-world issues. This chapter describes the basic algorithms and
-mentions some of the specific target definitions that they use.
-
-3.1 Prologue Analysis
-=====================
-
-To produce a backtrace and allow the user to manipulate older frames'
-variables and arguments, GDB needs to find the base addresses of older
-frames, and discover where those frames' registers have been saved.
-Since a frame's "callee-saves" registers get saved by younger frames if
-and when they're reused, a frame's registers may be scattered
-unpredictably across younger frames. This means that changing the
-value of a register-allocated variable in an older frame may actually
-entail writing to a save slot in some younger frame.
-
- Modern versions of GCC emit Dwarf call frame information ("CFI"),
-which describes how to find frame base addresses and saved registers.
-But CFI is not always available, so as a fallback GDB uses a technique
-called "prologue analysis" to find frame sizes and saved registers. A
-prologue analyzer disassembles the function's machine code starting
-from its entry point, and looks for instructions that allocate frame
-space, save the stack pointer in a frame pointer register, save
-registers, and so on. Obviously, this can't be done accurately in
-general, but it's tractable to do well enough to be very helpful.
-Prologue analysis predates the GNU toolchain's support for CFI; at one
-time, prologue analysis was the only mechanism GDB used for stack
-unwinding at all, when the function calling conventions didn't specify
-a fixed frame layout.
-
- In the olden days, function prologues were generated by hand-written,
-target-specific code in GCC, and treated as opaque and untouchable by
-optimizers. Looking at this code, it was usually straightforward to
-write a prologue analyzer for GDB that would accurately understand all
-the prologues GCC would generate. However, over time GCC became more
-aggressive about instruction scheduling, and began to understand more
-about the semantics of the prologue instructions themselves; in
-response, GDB's analyzers became more complex and fragile. Keeping the
-prologue analyzers working as GCC (and the instruction sets themselves)
-evolved became a substantial task.
-
- To try to address this problem, the code in `prologue-value.h' and
-`prologue-value.c' provides a general framework for writing prologue
-analyzers that are simpler and more robust than ad-hoc analyzers. When
-we analyze a prologue using the prologue-value framework, we're really
-doing "abstract interpretation" or "pseudo-evaluation": running the
-function's code in simulation, but using conservative approximations of
-the values registers and memory would hold when the code actually runs.
-For example, if our function starts with the instruction:
-
- addi r1, 42 # add 42 to r1
- we don't know exactly what value will be in `r1' after executing
-this instruction, but we do know it'll be 42 greater than its original
-value.
-
- If we then see an instruction like:
-
- addi r1, 22 # add 22 to r1
- we still don't know what `r1's' value is, but again, we can say it
-is now 64 greater than its original value.
-
- If the next instruction were:
-
- mov r2, r1 # set r2 to r1's value
- then we can say that `r2's' value is now the original value of `r1'
-plus 64.
-
- It's common for prologues to save registers on the stack, so we'll
-need to track the values of stack frame slots, as well as the
-registers. So after an instruction like this:
-
- mov (fp+4), r2
- then we'd know that the stack slot four bytes above the frame pointer
-holds the original value of `r1' plus 64.
-
- And so on.
-
- Of course, this can only go so far before it gets unreasonable. If
-we wanted to be able to say anything about the value of `r1' after the
-instruction:
-
- xor r1, r3 # exclusive-or r1 and r3, place result in r1
- then things would get pretty complex. But remember, we're just doing
-a conservative approximation; if exclusive-or instructions aren't
-relevant to prologues, we can just say `r1''s value is now "unknown".
-We can ignore things that are too complex, if that loss of information
-is acceptable for our application.
-
- So when we say "conservative approximation" here, what we mean is an
-approximation that is either accurate, or marked "unknown", but never
-inaccurate.
-
- Using this framework, a prologue analyzer is simply an interpreter
-for machine code, but one that uses conservative approximations for the
-contents of registers and memory instead of actual values. Starting
-from the function's entry point, you simulate instructions up to the
-current PC, or an instruction that you don't know how to simulate. Now
-you can examine the state of the registers and stack slots you've kept
-track of.
-
- * To see how large your stack frame is, just check the value of the
- stack pointer register; if it's the original value of the SP minus
- a constant, then that constant is the stack frame's size. If the
- SP's value has been marked as "unknown", then that means the
- prologue has done something too complex for us to track, and we
- don't know the frame size.
-
- * To see where we've saved the previous frame's registers, we just
- search the values we've tracked -- stack slots, usually, but
- registers, too, if you want -- for something equal to the
- register's original value. If the calling conventions suggest a
- standard place to save a given register, then we can check there
- first, but really, anything that will get us back the original
- value will probably work.
-
- This does take some work. But prologue analyzers aren't
-quick-and-simple pattern patching to recognize a few fixed prologue
-forms any more; they're big, hairy functions. Along with inferior
-function calls, prologue analysis accounts for a substantial portion of
-the time needed to stabilize a GDB port. So it's worthwhile to look
-for an approach that will be easier to understand and maintain. In the
-approach described above:
-
- * It's easier to see that the analyzer is correct: you just see
- whether the analyzer properly (albeit conservatively) simulates
- the effect of each instruction.
-
- * It's easier to extend the analyzer: you can add support for new
- instructions, and know that you haven't broken anything that
- wasn't already broken before.
-
- * It's orthogonal: to gather new information, you don't need to
- complicate the code for each instruction. As long as your domain
- of conservative values is already detailed enough to tell you what
- you need, then all the existing instruction simulations are
- already gathering the right data for you.
-
-
- The file `prologue-value.h' contains detailed comments explaining
-the framework and how to use it.
-
-3.2 Breakpoint Handling
-=======================
-
-In general, a breakpoint is a user-designated location in the program
-where the user wants to regain control if program execution ever reaches
-that location.
-
- There are two main ways to implement breakpoints; either as
-"hardware" breakpoints or as "software" breakpoints.
-
- Hardware breakpoints are sometimes available as a builtin debugging
-features with some chips. Typically these work by having dedicated
-register into which the breakpoint address may be stored. If the PC
-(shorthand for "program counter") ever matches a value in a breakpoint
-registers, the CPU raises an exception and reports it to GDB.
-
- Another possibility is when an emulator is in use; many emulators
-include circuitry that watches the address lines coming out from the
-processor, and force it to stop if the address matches a breakpoint's
-address.
-
- A third possibility is that the target already has the ability to do
-breakpoints somehow; for instance, a ROM monitor may do its own
-software breakpoints. So although these are not literally "hardware
-breakpoints", from GDB's point of view they work the same; GDB need not
-do anything more than set the breakpoint and wait for something to
-happen.
-
- Since they depend on hardware resources, hardware breakpoints may be
-limited in number; when the user asks for more, GDB will start trying
-to set software breakpoints. (On some architectures, notably the
-32-bit x86 platforms, GDB cannot always know whether there's enough
-hardware resources to insert all the hardware breakpoints and
-watchpoints. On those platforms, GDB prints an error message only when
-the program being debugged is continued.)
-
- Software breakpoints require GDB to do somewhat more work. The
-basic theory is that GDB will replace a program instruction with a
-trap, illegal divide, or some other instruction that will cause an
-exception, and then when it's encountered, GDB will take the exception
-and stop the program. When the user says to continue, GDB will restore
-the original instruction, single-step, re-insert the trap, and continue
-on.
-
- Since it literally overwrites the program being tested, the program
-area must be writable, so this technique won't work on programs in ROM.
-It can also distort the behavior of programs that examine themselves,
-although such a situation would be highly unusual.
-
- Also, the software breakpoint instruction should be the smallest
-size of instruction, so it doesn't overwrite an instruction that might
-be a jump target, and cause disaster when the program jumps into the
-middle of the breakpoint instruction. (Strictly speaking, the
-breakpoint must be no larger than the smallest interval between
-instructions that may be jump targets; perhaps there is an architecture
-where only even-numbered instructions may jumped to.) Note that it's
-possible for an instruction set not to have any instructions usable for
-a software breakpoint, although in practice only the ARC has failed to
-define such an instruction.
-
- Basic breakpoint object handling is in `breakpoint.c'. However,
-much of the interesting breakpoint action is in `infrun.c'.
-
-`target_remove_breakpoint (BP_TGT)'
-`target_insert_breakpoint (BP_TGT)'
- Insert or remove a software breakpoint at address
- `BP_TGT->placed_address'. Returns zero for success, non-zero for
- failure. On input, BP_TGT contains the address of the breakpoint,
- and is otherwise initialized to zero. The fields of the `struct
- bp_target_info' pointed to by BP_TGT are updated to contain other
- information about the breakpoint on output. The field
- `placed_address' may be updated if the breakpoint was placed at a
- related address; the field `shadow_contents' contains the real
- contents of the bytes where the breakpoint has been inserted, if
- reading memory would return the breakpoint instead of the
- underlying memory; the field `shadow_len' is the length of memory
- cached in `shadow_contents', if any; and the field `placed_size'
- is optionally set and used by the target, if it could differ from
- `shadow_len'.
-
- For example, the remote target `Z0' packet does not require
- shadowing memory, so `shadow_len' is left at zero. However, the
- length reported by `gdbarch_breakpoint_from_pc' is cached in
- `placed_size', so that a matching `z0' packet can be used to
- remove the breakpoint.
-
-`target_remove_hw_breakpoint (BP_TGT)'
-`target_insert_hw_breakpoint (BP_TGT)'
- Insert or remove a hardware-assisted breakpoint at address
- `BP_TGT->placed_address'. Returns zero for success, non-zero for
- failure. See `target_insert_breakpoint' for a description of the
- `struct bp_target_info' pointed to by BP_TGT; the
- `shadow_contents' and `shadow_len' members are not used for
- hardware breakpoints, but `placed_size' may be.
-
-3.3 Single Stepping
-===================
-
-3.4 Signal Handling
-===================
-
-3.5 Thread Handling
-===================
-
-3.6 Inferior Function Calls
-===========================
-
-3.7 Longjmp Support
-===================
-
-GDB has support for figuring out that the target is doing a `longjmp'
-and for stopping at the target of the jump, if we are stepping. This
-is done with a few specialized internal breakpoints, which are visible
-in the output of the `maint info breakpoint' command.
-
- To make this work, you need to define a function called
-`gdbarch_get_longjmp_target', which will examine the `jmp_buf'
-structure and extract the `longjmp' target address. Since `jmp_buf' is
-target specific and typically defined in a target header not available
-to GDB, you will need to determine the offset of the PC manually and
-return that; many targets define a `jb_pc_offset' field in the tdep
-structure to save the value once calculated.
-
-3.8 Watchpoints
-===============
-
-Watchpoints are a special kind of breakpoints (*note breakpoints:
-Algorithms.) which break when data is accessed rather than when some
-instruction is executed. When you have data which changes without your
-knowing what code does that, watchpoints are the silver bullet to hunt
-down and kill such bugs.
-
- Watchpoints can be either hardware-assisted or not; the latter type
-is known as "software watchpoints." GDB always uses hardware-assisted
-watchpoints if they are available, and falls back on software
-watchpoints otherwise. Typical situations where GDB will use software
-watchpoints are:
-
- * The watched memory region is too large for the underlying hardware
- watchpoint support. For example, each x86 debug register can
- watch up to 4 bytes of memory, so trying to watch data structures
- whose size is more than 16 bytes will cause GDB to use software
- watchpoints.
-
- * The value of the expression to be watched depends on data held in
- registers (as opposed to memory).
-
- * Too many different watchpoints requested. (On some architectures,
- this situation is impossible to detect until the debugged program
- is resumed.) Note that x86 debug registers are used both for
- hardware breakpoints and for watchpoints, so setting too many
- hardware breakpoints might cause watchpoint insertion to fail.
-
- * No hardware-assisted watchpoints provided by the target
- implementation.
-
- Software watchpoints are very slow, since GDB needs to single-step
-the program being debugged and test the value of the watched
-expression(s) after each instruction. The rest of this section is
-mostly irrelevant for software watchpoints.
-
- When the inferior stops, GDB tries to establish, among other
-possible reasons, whether it stopped due to a watchpoint being hit. It
-first uses `STOPPED_BY_WATCHPOINT' to see if any watchpoint was hit.
-If not, all watchpoint checking is skipped.
-
- Then GDB calls `target_stopped_data_address' exactly once. This
-method returns the address of the watchpoint which triggered, if the
-target can determine it. If the triggered address is available, GDB
-compares the address returned by this method with each watched memory
-address in each active watchpoint. For data-read and data-access
-watchpoints, GDB announces every watchpoint that watches the triggered
-address as being hit. For this reason, data-read and data-access
-watchpoints _require_ that the triggered address be available; if not,
-read and access watchpoints will never be considered hit. For
-data-write watchpoints, if the triggered address is available, GDB
-considers only those watchpoints which match that address; otherwise,
-GDB considers all data-write watchpoints. For each data-write
-watchpoint that GDB considers, it evaluates the expression whose value
-is being watched, and tests whether the watched value has changed.
-Watchpoints whose watched values have changed are announced as hit.
-
- GDB uses several macros and primitives to support hardware
-watchpoints:
-
-`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'
- Return the number of hardware watchpoints of type TYPE that are
- possible to be set. The value is positive if COUNT watchpoints of
- this type can be set, zero if setting watchpoints of this type is
- not supported, and negative if COUNT is more than the maximum
- number of watchpoints of type TYPE that can be set. OTHER is
- non-zero if other types of watchpoints are currently enabled (there
- are architectures which cannot set watchpoints of different types
- at the same time).
-
-`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'
- Return non-zero if hardware watchpoints can be used to watch a
- region whose address is ADDR and whose length in bytes is LEN.
-
-`target_insert_watchpoint (ADDR, LEN, TYPE)'
-`target_remove_watchpoint (ADDR, LEN, TYPE)'
- Insert or remove a hardware watchpoint starting at ADDR, for LEN
- bytes. TYPE is the watchpoint type, one of the possible values of
- the enumerated data type `target_hw_bp_type', defined by
- `breakpoint.h' as follows:
-
- enum target_hw_bp_type
- {
- hw_write = 0, /* Common (write) HW watchpoint */
- hw_read = 1, /* Read HW watchpoint */
- hw_access = 2, /* Access (read or write) HW watchpoint */
- hw_execute = 3 /* Execute HW breakpoint */
- };
-
- These two macros should return 0 for success, non-zero for failure.
-
-`target_stopped_data_address (ADDR_P)'
- If the inferior has some watchpoint that triggered, place the
- address associated with the watchpoint at the location pointed to
- by ADDR_P and return non-zero. Otherwise, return zero. This is
- required for data-read and data-access watchpoints. It is not
- required for data-write watchpoints, but GDB uses it to improve
- handling of those also.
-
- GDB will only call this method once per watchpoint stop,
- immediately after calling `STOPPED_BY_WATCHPOINT'. If the
- target's watchpoint indication is sticky, i.e., stays set after
- resuming, this method should clear it. For instance, the x86 debug
- control register has sticky triggered flags.
-
-`target_watchpoint_addr_within_range (TARGET, ADDR, START, LENGTH)'
- Check whether ADDR (as returned by `target_stopped_data_address')
- lies within the hardware-defined watchpoint region described by
- START and LENGTH. This only needs to be provided if the
- granularity of a watchpoint is greater than one byte, i.e., if the
- watchpoint can also trigger on nearby addresses outside of the
- watched region.
-
-`HAVE_STEPPABLE_WATCHPOINT'
- If defined to a non-zero value, it is not necessary to disable a
- watchpoint to step over it. Like
- `gdbarch_have_nonsteppable_watchpoint', this is usually set when
- watchpoints trigger at the instruction which will perform an
- interesting read or write. It should be set if there is a
- temporary disable bit which allows the processor to step over the
- interesting instruction without raising the watchpoint exception
- again.
-
-`int gdbarch_have_nonsteppable_watchpoint (GDBARCH)'
- If it returns a non-zero value, GDB should disable a watchpoint to
- step the inferior over it. This is usually set when watchpoints
- trigger at the instruction which will perform an interesting read
- or write.
-
-`HAVE_CONTINUABLE_WATCHPOINT'
- If defined to a non-zero value, it is possible to continue the
- inferior after a watchpoint has been hit. This is usually set
- when watchpoints trigger at the instruction following an
- interesting read or write.
-
-`CANNOT_STEP_HW_WATCHPOINTS'
- If this is defined to a non-zero value, GDB will remove all
- watchpoints before stepping the inferior.
-
-`STOPPED_BY_WATCHPOINT (WAIT_STATUS)'
- Return non-zero if stopped by a watchpoint. WAIT_STATUS is of the
- type `struct target_waitstatus', defined by `target.h'. Normally,
- this macro is defined to invoke the function pointed to by the
- `to_stopped_by_watchpoint' member of the structure (of the type
- `target_ops', defined on `target.h') that describes the
- target-specific operations; `to_stopped_by_watchpoint' ignores the
- WAIT_STATUS argument.
-
- GDB does not require the non-zero value returned by
- `STOPPED_BY_WATCHPOINT' to be 100% correct, so if a target cannot
- determine for sure whether the inferior stopped due to a
- watchpoint, it could return non-zero "just in case".
-
-3.8.1 Watchpoints and Threads
------------------------------
-
-GDB only supports process-wide watchpoints, which trigger in all
-threads. GDB uses the thread ID to make watchpoints act as if they
-were thread-specific, but it cannot set hardware watchpoints that only
-trigger in a specific thread. Therefore, even if the target supports
-threads, per-thread debug registers, and watchpoints which only affect
-a single thread, it should set the per-thread debug registers for all
-threads to the same value. On GNU/Linux native targets, this is
-accomplished by using `ALL_LWPS' in `target_insert_watchpoint' and
-`target_remove_watchpoint' and by using `linux_set_new_thread' to
-register a handler for newly created threads.
-
- GDB's GNU/Linux support only reports a single event at a time,
-although multiple events can trigger simultaneously for multi-threaded
-programs. When multiple events occur, `linux-nat.c' queues subsequent
-events and returns them the next time the program is resumed. This
-means that `STOPPED_BY_WATCHPOINT' and `target_stopped_data_address'
-only need to consult the current thread's state--the thread indicated
-by `inferior_ptid'. If two threads have hit watchpoints
-simultaneously, those routines will be called a second time for the
-second thread.
-
-3.8.2 x86 Watchpoints
----------------------
-
-The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug
-registers designed to facilitate debugging. GDB provides a generic
-library of functions that x86-based ports can use to implement support
-for watchpoints and hardware-assisted breakpoints. This subsection
-documents the x86 watchpoint facilities in GDB.
-
- (At present, the library functions read and write debug registers
-directly, and are thus only available for native configurations.)
-
- To use the generic x86 watchpoint support, a port should do the
-following:
-
- * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the
- target-dependent headers.
-
- * Include the `config/i386/nm-i386.h' header file _after_ defining
- `I386_USE_GENERIC_WATCHPOINTS'.
-
- * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'
- (*note NATDEPFILES: Native Debugging.).
-
- * Provide implementations for the `I386_DR_LOW_*' macros described
- below. Typically, each macro should call a target-specific
- function which does the real work.
-
- The x86 watchpoint support works by maintaining mirror images of the
-debug registers. Values are copied between the mirror images and the
-real debug registers via a set of macros which each target needs to
-provide:
-
-`I386_DR_LOW_SET_CONTROL (VAL)'
- Set the Debug Control (DR7) register to the value VAL.
-
-`I386_DR_LOW_SET_ADDR (IDX, ADDR)'
- Put the address ADDR into the debug register number IDX.
-
-`I386_DR_LOW_RESET_ADDR (IDX)'
- Reset (i.e. zero out) the address stored in the debug register
- number IDX.
-
-`I386_DR_LOW_GET_STATUS'
- Return the value of the Debug Status (DR6) register. This value is
- used immediately after it is returned by `I386_DR_LOW_GET_STATUS',
- so as to support per-thread status register values.
-
- For each one of the 4 debug registers (whose indices are from 0 to 3)
-that store addresses, a reference count is maintained by GDB, to allow
-sharing of debug registers by several watchpoints. This allows users
-to define several watchpoints that watch the same expression, but with
-different conditions and/or commands, without wasting debug registers
-which are in short supply. GDB maintains the reference counts
-internally, targets don't have to do anything to use this feature.
-
- The x86 debug registers can each watch a region that is 1, 2, or 4
-bytes long. The ia32 architecture requires that each watched region be
-appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region
-on 4-byte boundary. However, the x86 watchpoint support in GDB can
-watch unaligned regions and regions larger than 4 bytes (up to 16
-bytes) by allocating several debug registers to watch a single region.
-This allocation of several registers per a watched region is also done
-automatically without target code intervention.
-
- The generic x86 watchpoint support provides the following API for the
-GDB's application code:
-
-`i386_region_ok_for_watchpoint (ADDR, LEN)'
- The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this
- function. It counts the number of debug registers required to
- watch a given region, and returns a non-zero value if that number
- is less than 4, the number of debug registers available to x86
- processors.
-
-`i386_stopped_data_address (ADDR_P)'
- The target function `target_stopped_data_address' is set to call
- this function. This function examines the breakpoint condition
- bits in the DR6 Debug Status register, as returned by the
- `I386_DR_LOW_GET_STATUS' macro, and returns the address associated
- with the first bit that is set in DR6.
-
-`i386_stopped_by_watchpoint (void)'
- The macro `STOPPED_BY_WATCHPOINT' is set to call this function.
- The argument passed to `STOPPED_BY_WATCHPOINT' is ignored. This
- function examines the breakpoint condition bits in the DR6 Debug
- Status register, as returned by the `I386_DR_LOW_GET_STATUS'
- macro, and returns true if any bit is set. Otherwise, false is
- returned.
-
-`i386_insert_watchpoint (ADDR, LEN, TYPE)'
-`i386_remove_watchpoint (ADDR, LEN, TYPE)'
- Insert or remove a watchpoint. The macros
- `target_insert_watchpoint' and `target_remove_watchpoint' are set
- to call these functions. `i386_insert_watchpoint' first looks for
- a debug register which is already set to watch the same region for
- the same access types; if found, it just increments the reference
- count of that debug register, thus implementing debug register
- sharing between watchpoints. If no such register is found, the
- function looks for a vacant debug register, sets its mirrored
- value to ADDR, sets the mirrored value of DR7 Debug Control
- register as appropriate for the LEN and TYPE parameters, and then
- passes the new values of the debug register and DR7 to the
- inferior by calling `I386_DR_LOW_SET_ADDR' and
- `I386_DR_LOW_SET_CONTROL'. If more than one debug register is
- required to cover the given region, the above process is repeated
- for each debug register.
-
- `i386_remove_watchpoint' does the opposite: it resets the address
- in the mirrored value of the debug register and its read/write and
- length bits in the mirrored value of DR7, then passes these new
- values to the inferior via `I386_DR_LOW_RESET_ADDR' and
- `I386_DR_LOW_SET_CONTROL'. If a register is shared by several
- watchpoints, each time a `i386_remove_watchpoint' is called, it
- decrements the reference count, and only calls
- `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the
- count goes to zero.
-
-`i386_insert_hw_breakpoint (BP_TGT)'
-`i386_remove_hw_breakpoint (BP_TGT)'
- These functions insert and remove hardware-assisted breakpoints.
- The macros `target_insert_hw_breakpoint' and
- `target_remove_hw_breakpoint' are set to call these functions.
- The argument is a `struct bp_target_info *', as described in the
- documentation for `target_insert_breakpoint'. These functions
- work like `i386_insert_watchpoint' and `i386_remove_watchpoint',
- respectively, except that they set up the debug registers to watch
- instruction execution, and each hardware-assisted breakpoint
- always requires exactly one debug register.
-
-`i386_cleanup_dregs (void)'
- This function clears all the reference counts, addresses, and
- control bits in the mirror images of the debug registers. It
- doesn't affect the actual debug registers in the inferior process.
-
-*Notes:*
- 1. x86 processors support setting watchpoints on I/O reads or writes.
- However, since no target supports this (as of March 2001), and
- since `enum target_hw_bp_type' doesn't even have an enumeration
- for I/O watchpoints, this feature is not yet available to GDB
- running on x86.
-
- 2. x86 processors can enable watchpoints locally, for the current task
- only, or globally, for all the tasks. For each debug register,
- there's a bit in the DR7 Debug Control register that determines
- whether the associated address is watched locally or globally. The
- current implementation of x86 watchpoint support in GDB always
- sets watchpoints to be locally enabled, since global watchpoints
- might interfere with the underlying OS and are probably
- unavailable in many platforms.
-
-3.9 Checkpoints
-===============
-
-In the abstract, a checkpoint is a point in the execution history of
-the program, which the user may wish to return to at some later time.
-
- Internally, a checkpoint is a saved copy of the program state,
-including whatever information is required in order to restore the
-program to that state at a later time. This can be expected to include
-the state of registers and memory, and may include external state such
-as the state of open files and devices.
-
- There are a number of ways in which checkpoints may be implemented
-in gdb, e.g. as corefiles, as forked processes, and as some opaque
-method implemented on the target side.
-
- A corefile can be used to save an image of target memory and register
-state, which can in principle be restored later -- but corefiles do not
-typically include information about external entities such as open
-files. Currently this method is not implemented in gdb.
-
- A forked process can save the state of user memory and registers, as
-well as some subset of external (kernel) state. This method is used to
-implement checkpoints on Linux, and in principle might be used on other
-systems.
-
- Some targets, e.g. simulators, might have their own built-in method
-for saving checkpoints, and gdb might be able to take advantage of that
-capability without necessarily knowing any details of how it is done.
-
-3.10 Observing changes in GDB internals
-=======================================
-
-In order to function properly, several modules need to be notified when
-some changes occur in the GDB internals. Traditionally, these modules
-have relied on several paradigms, the most common ones being hooks and
-gdb-events. Unfortunately, none of these paradigms was versatile
-enough to become the standard notification mechanism in GDB. The fact
-that they only supported one "client" was also a strong limitation.
-
- A new paradigm, based on the Observer pattern of the `Design
-Patterns' book, has therefore been implemented. The goal was to provide
-a new interface overcoming the issues with the notification mechanisms
-previously available. This new interface needed to be strongly typed,
-easy to extend, and versatile enough to be used as the standard
-interface when adding new notifications.
-
- See *note GDB Observers:: for a brief description of the observers
-currently implemented in GDB. The rationale for the current
-implementation is also briefly discussed.
-
-\1f
-File: gdbint.info, Node: User Interface, Next: libgdb, Prev: Algorithms, Up: Top
-
-4 User Interface
-****************
-
-GDB has several user interfaces, of which the traditional command-line
-interface is perhaps the most familiar.
-
-4.1 Command Interpreter
-=======================
-
-The command interpreter in GDB is fairly simple. It is designed to
-allow for the set of commands to be augmented dynamically, and also has
-a recursive subcommand capability, where the first argument to a
-command may itself direct a lookup on a different command list.
-
- For instance, the `set' command just starts a lookup on the
-`setlist' command list, while `set thread' recurses to the
-`set_thread_cmd_list'.
-
- To add commands in general, use `add_cmd'. `add_com' adds to the
-main command list, and should be used for those commands. The usual
-place to add commands is in the `_initialize_XYZ' routines at the ends
-of most source files.
-
- To add paired `set' and `show' commands, use `add_setshow_cmd' or
-`add_setshow_cmd_full'. The former is a slightly simpler interface
-which is useful when you don't need to further modify the new command
-structures, while the latter returns the new command structures for
-manipulation.
-
- Before removing commands from the command set it is a good idea to
-deprecate them for some time. Use `deprecate_cmd' on commands or
-aliases to set the deprecated flag. `deprecate_cmd' takes a `struct
-cmd_list_element' as it's first argument. You can use the return value
-from `add_com' or `add_cmd' to deprecate the command immediately after
-it is created.
-
- The first time a command is used the user will be warned and offered
-a replacement (if one exists). Note that the replacement string passed
-to `deprecate_cmd' should be the full name of the command, i.e., the
-entire string the user should type at the command line.
-
-4.2 UI-Independent Output--the `ui_out' Functions
-=================================================
-
-The `ui_out' functions present an abstraction level for the GDB output
-code. They hide the specifics of different user interfaces supported
-by GDB, and thus free the programmer from the need to write several
-versions of the same code, one each for every UI, to produce output.
-
-4.2.1 Overview and Terminology
-------------------------------
-
-In general, execution of each GDB command produces some sort of output,
-and can even generate an input request.
-
- Output can be generated for the following purposes:
-
- * to display a _result_ of an operation;
-
- * to convey _info_ or produce side-effects of a requested operation;
-
- * to provide a _notification_ of an asynchronous event (including
- progress indication of a prolonged asynchronous operation);
-
- * to display _error messages_ (including warnings);
-
- * to show _debug data_;
-
- * to _query_ or prompt a user for input (a special case).
-
-This section mainly concentrates on how to build result output,
-although some of it also applies to other kinds of output.
-
- Generation of output that displays the results of an operation
-involves one or more of the following:
-
- * output of the actual data
-
- * formatting the output as appropriate for console output, to make it
- easily readable by humans
-
- * machine oriented formatting-a more terse formatting to allow for
- easy parsing by programs which read GDB's output
-
- * annotation, whose purpose is to help legacy GUIs to identify
- interesting parts in the output
-
- The `ui_out' routines take care of the first three aspects.
-Annotations are provided by separate annotation routines. Note that use
-of annotations for an interface between a GUI and GDB is deprecated.
-
- Output can be in the form of a single item, which we call a "field";
-a "list" consisting of identical fields; a "tuple" consisting of
-non-identical fields; or a "table", which is a tuple consisting of a
-header and a body. In a BNF-like form:
-
-`<table> ==>'
- `<header> <body>'
-
-`<header> ==>'
- `{ <column> }'
-
-`<column> ==>'
- `<width> <alignment> <title>'
-
-`<body> ==>'
- `{<row>}'
-
-4.2.2 General Conventions
--------------------------
-
-Most `ui_out' routines are of type `void', the exceptions are
-`ui_out_stream_new' (which returns a pointer to the newly created
-object) and the `make_cleanup' routines.
-
- The first parameter is always the `ui_out' vector object, a pointer
-to a `struct ui_out'.
-
- The FORMAT parameter is like in `printf' family of functions. When
-it is present, there must also be a variable list of arguments
-sufficient used to satisfy the `%' specifiers in the supplied format.
-
- When a character string argument is not used in a `ui_out' function
-call, a `NULL' pointer has to be supplied instead.
-
-4.2.3 Table, Tuple and List Functions
--------------------------------------
-
-This section introduces `ui_out' routines for building lists, tuples
-and tables. The routines to output the actual data items (fields) are
-presented in the next section.
-
- To recap: A "tuple" is a sequence of "fields", each field containing
-information about an object; a "list" is a sequence of fields where
-each field describes an identical object.
-
- Use the "table" functions when your output consists of a list of
-rows (tuples) and the console output should include a heading. Use this
-even when you are listing just one object but you still want the header.
-
- Tables can not be nested. Tuples and lists can be nested up to a
-maximum of five levels.
-
- The overall structure of the table output code is something like
-this:
-
- ui_out_table_begin
- ui_out_table_header
- ...
- ui_out_table_body
- ui_out_tuple_begin
- ui_out_field_*
- ...
- ui_out_tuple_end
- ...
- ui_out_table_end
-
- Here is the description of table-, tuple- and list-related `ui_out'
-functions:
-
- -- Function: void ui_out_table_begin (struct ui_out *UIOUT, int
- NBROFCOLS, int NR_ROWS, const char *TBLID)
- The function `ui_out_table_begin' marks the beginning of the output
- of a table. It should always be called before any other `ui_out'
- function for a given table. NBROFCOLS is the number of columns in
- the table. NR_ROWS is the number of rows in the table. TBLID is
- an optional string identifying the table. The string pointed to
- by TBLID is copied by the implementation of `ui_out_table_begin',
- so the application can free the string if it was `malloc'ed.
-
- The companion function `ui_out_table_end', described below, marks
- the end of the table's output.
-
- -- Function: void ui_out_table_header (struct ui_out *UIOUT, int
- WIDTH, enum ui_align ALIGNMENT, const char *COLHDR)
- `ui_out_table_header' provides the header information for a single
- table column. You call this function several times, one each for
- every column of the table, after `ui_out_table_begin', but before
- `ui_out_table_body'.
-
- The value of WIDTH gives the column width in characters. The
- value of ALIGNMENT is one of `left', `center', and `right', and it
- specifies how to align the header: left-justify, center, or
- right-justify it. COLHDR points to a string that specifies the
- column header; the implementation copies that string, so column
- header strings in `malloc'ed storage can be freed after the call.
-
- -- Function: void ui_out_table_body (struct ui_out *UIOUT)
- This function delimits the table header from the table body.
-
- -- Function: void ui_out_table_end (struct ui_out *UIOUT)
- This function signals the end of a table's output. It should be
- called after the table body has been produced by the list and
- field output functions.
-
- There should be exactly one call to `ui_out_table_end' for each
- call to `ui_out_table_begin', otherwise the `ui_out' functions
- will signal an internal error.
-
- The output of the tuples that represent the table rows must follow
-the call to `ui_out_table_body' and precede the call to
-`ui_out_table_end'. You build a tuple by calling `ui_out_tuple_begin'
-and `ui_out_tuple_end', with suitable calls to functions which actually
-output fields between them.
-
- -- Function: void ui_out_tuple_begin (struct ui_out *UIOUT, const char
- *ID)
- This function marks the beginning of a tuple output. ID points to
- an optional string that identifies the tuple; it is copied by the
- implementation, and so strings in `malloc'ed storage can be freed
- after the call.
-
- -- Function: void ui_out_tuple_end (struct ui_out *UIOUT)
- This function signals an end of a tuple output. There should be
- exactly one call to `ui_out_tuple_end' for each call to
- `ui_out_tuple_begin', otherwise an internal GDB error will be
- signaled.
-
- -- Function: struct cleanup * make_cleanup_ui_out_tuple_begin_end
- (struct ui_out *UIOUT, const char *ID)
- This function first opens the tuple and then establishes a cleanup
- (*note Cleanups: Coding.) to close the tuple. It provides a
- convenient and correct implementation of the non-portable(1) code
- sequence:
- struct cleanup *old_cleanup;
- ui_out_tuple_begin (uiout, "...");
- old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
- uiout);
-
- -- Function: void ui_out_list_begin (struct ui_out *UIOUT, const char
- *ID)
- This function marks the beginning of a list output. ID points to
- an optional string that identifies the list; it is copied by the
- implementation, and so strings in `malloc'ed storage can be freed
- after the call.
-
- -- Function: void ui_out_list_end (struct ui_out *UIOUT)
- This function signals an end of a list output. There should be
- exactly one call to `ui_out_list_end' for each call to
- `ui_out_list_begin', otherwise an internal GDB error will be
- signaled.
-
- -- Function: struct cleanup * make_cleanup_ui_out_list_begin_end
- (struct ui_out *UIOUT, const char *ID)
- Similar to `make_cleanup_ui_out_tuple_begin_end', this function
- opens a list and then establishes cleanup (*note Cleanups: Coding.)
- that will close the list.
-
-4.2.4 Item Output Functions
----------------------------
-
-The functions described below produce output for the actual data items,
-or fields, which contain information about the object.
-
- Choose the appropriate function accordingly to your particular needs.
-
- -- Function: void ui_out_field_fmt (struct ui_out *UIOUT, char
- *FLDNAME, char *FORMAT, ...)
- This is the most general output function. It produces the
- representation of the data in the variable-length argument list
- according to formatting specifications in FORMAT, a `printf'-like
- format string. The optional argument FLDNAME supplies the name of
- the field. The data items themselves are supplied as additional
- arguments after FORMAT.
-
- This generic function should be used only when it is not possible
- to use one of the specialized versions (see below).
-
- -- Function: void ui_out_field_int (struct ui_out *UIOUT, const char
- *FLDNAME, int VALUE)
- This function outputs a value of an `int' variable. It uses the
- `"%d"' output conversion specification. FLDNAME specifies the
- name of the field.
-
- -- Function: void ui_out_field_fmt_int (struct ui_out *UIOUT, int
- WIDTH, enum ui_align ALIGNMENT, const char *FLDNAME, int
- VALUE)
- This function outputs a value of an `int' variable. It differs
- from `ui_out_field_int' in that the caller specifies the desired
- WIDTH and ALIGNMENT of the output. FLDNAME specifies the name of
- the field.
-
- -- Function: void ui_out_field_core_addr (struct ui_out *UIOUT, const
- char *FLDNAME, struct gdbarch *GDBARCH, CORE_ADDR ADDRESS)
- This function outputs an address as appropriate for GDBARCH.
-
- -- Function: void ui_out_field_string (struct ui_out *UIOUT, const
- char *FLDNAME, const char *STRING)
- This function outputs a string using the `"%s"' conversion
- specification.
-
- Sometimes, there's a need to compose your output piece by piece using
-functions that operate on a stream, such as `value_print' or
-`fprintf_symbol_filtered'. These functions accept an argument of the
-type `struct ui_file *', a pointer to a `ui_file' object used to store
-the data stream used for the output. When you use one of these
-functions, you need a way to pass their results stored in a `ui_file'
-object to the `ui_out' functions. To this end, you first create a
-`ui_stream' object by calling `ui_out_stream_new', pass the `stream'
-member of that `ui_stream' object to `value_print' and similar
-functions, and finally call `ui_out_field_stream' to output the field
-you constructed. When the `ui_stream' object is no longer needed, you
-should destroy it and free its memory by calling `ui_out_stream_delete'.
-
- -- Function: struct ui_stream * ui_out_stream_new (struct ui_out
- *UIOUT)
- This function creates a new `ui_stream' object which uses the same
- output methods as the `ui_out' object whose pointer is passed in
- UIOUT. It returns a pointer to the newly created `ui_stream'
- object.
-
- -- Function: void ui_out_stream_delete (struct ui_stream *STREAMBUF)
- This functions destroys a `ui_stream' object specified by
- STREAMBUF.
-
- -- Function: void ui_out_field_stream (struct ui_out *UIOUT, const
- char *FIELDNAME, struct ui_stream *STREAMBUF)
- This function consumes all the data accumulated in
- `streambuf->stream' and outputs it like `ui_out_field_string'
- does. After a call to `ui_out_field_stream', the accumulated data
- no longer exists, but the stream is still valid and may be used
- for producing more fields.
-
- *Important:* If there is any chance that your code could bail out
-before completing output generation and reaching the point where
-`ui_out_stream_delete' is called, it is necessary to set up a cleanup,
-to avoid leaking memory and other resources. Here's a skeleton code to
-do that:
-
- struct ui_stream *mybuf = ui_out_stream_new (uiout);
- struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
- ...
- do_cleanups (old);
-
- If the function already has the old cleanup chain set (for other
-kinds of cleanups), you just have to add your cleanup to it:
-
- mybuf = ui_out_stream_new (uiout);
- make_cleanup (ui_out_stream_delete, mybuf);
-
- Note that with cleanups in place, you should not call
-`ui_out_stream_delete' directly, or you would attempt to free the same
-buffer twice.
-
-4.2.5 Utility Output Functions
-------------------------------
-
- -- Function: void ui_out_field_skip (struct ui_out *UIOUT, const char
- *FLDNAME)
- This function skips a field in a table. Use it if you have to
- leave an empty field without disrupting the table alignment. The
- argument FLDNAME specifies a name for the (missing) filed.
-
- -- Function: void ui_out_text (struct ui_out *UIOUT, const char
- *STRING)
- This function outputs the text in STRING in a way that makes it
- easy to be read by humans. For example, the console
- implementation of this method filters the text through a built-in
- pager, to prevent it from scrolling off the visible portion of the
- screen.
-
- Use this function for printing relatively long chunks of text
- around the actual field data: the text it produces is not aligned
- according to the table's format. Use `ui_out_field_string' to
- output a string field, and use `ui_out_message', described below,
- to output short messages.
-
- -- Function: void ui_out_spaces (struct ui_out *UIOUT, int NSPACES)
- This function outputs NSPACES spaces. It is handy to align the
- text produced by `ui_out_text' with the rest of the table or list.
-
- -- Function: void ui_out_message (struct ui_out *UIOUT, int VERBOSITY,
- const char *FORMAT, ...)
- This function produces a formatted message, provided that the
- current verbosity level is at least as large as given by
- VERBOSITY. The current verbosity level is specified by the user
- with the `set verbositylevel' command.(2)
-
- -- Function: void ui_out_wrap_hint (struct ui_out *UIOUT, char *INDENT)
- This function gives the console output filter (a paging filter) a
- hint of where to break lines which are too long. Ignored for all
- other output consumers. INDENT, if non-`NULL', is the string to
- be printed to indent the wrapped text on the next line; it must
- remain accessible until the next call to `ui_out_wrap_hint', or
- until an explicit newline is produced by one of the other
- functions. If INDENT is `NULL', the wrapped text will not be
- indented.
-
- -- Function: void ui_out_flush (struct ui_out *UIOUT)
- This function flushes whatever output has been accumulated so far,
- if the UI buffers output.
-
-4.2.6 Examples of Use of `ui_out' functions
--------------------------------------------
-
-This section gives some practical examples of using the `ui_out'
-functions to generalize the old console-oriented code in GDB. The
-examples all come from functions defined on the `breakpoints.c' file.
-
- This example, from the `breakpoint_1' function, shows how to produce
-a table.
-
- The original code was:
-
- if (!found_a_breakpoint++)
- {
- annotate_breakpoints_headers ();
-
- annotate_field (0);
- printf_filtered ("Num ");
- annotate_field (1);
- printf_filtered ("Type ");
- annotate_field (2);
- printf_filtered ("Disp ");
- annotate_field (3);
- printf_filtered ("Enb ");
- if (addressprint)
- {
- annotate_field (4);
- printf_filtered ("Address ");
- }
- annotate_field (5);
- printf_filtered ("What\n");
-
- annotate_breakpoints_table ();
- }
-
- Here's the new version:
-
- nr_printable_breakpoints = ...;
-
- if (addressprint)
- ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
- else
- ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
-
- if (nr_printable_breakpoints > 0)
- annotate_breakpoints_headers ();
- if (nr_printable_breakpoints > 0)
- annotate_field (0);
- ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
- if (nr_printable_breakpoints > 0)
- annotate_field (1);
- ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
- if (nr_printable_breakpoints > 0)
- annotate_field (2);
- ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
- if (nr_printable_breakpoints > 0)
- annotate_field (3);
- ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
- if (addressprint)
- {
- if (nr_printable_breakpoints > 0)
- annotate_field (4);
- if (print_address_bits <= 32)
- ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
- else
- ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
- }
- if (nr_printable_breakpoints > 0)
- annotate_field (5);
- ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
- ui_out_table_body (uiout);
- if (nr_printable_breakpoints > 0)
- annotate_breakpoints_table ();
-
- This example, from the `print_one_breakpoint' function, shows how to
-produce the actual data for the table whose structure was defined in
-the above example. The original code was:
-
- annotate_record ();
- annotate_field (0);
- printf_filtered ("%-3d ", b->number);
- annotate_field (1);
- if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
- || ((int) b->type != bptypes[(int) b->type].type))
- internal_error ("bptypes table does not describe type #%d.",
- (int)b->type);
- printf_filtered ("%-14s ", bptypes[(int)b->type].description);
- annotate_field (2);
- printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
- annotate_field (3);
- printf_filtered ("%-3c ", bpenables[(int)b->enable]);
- ...
-
- This is the new version:
-
- annotate_record ();
- ui_out_tuple_begin (uiout, "bkpt");
- annotate_field (0);
- ui_out_field_int (uiout, "number", b->number);
- annotate_field (1);
- if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
- || ((int) b->type != bptypes[(int) b->type].type))
- internal_error ("bptypes table does not describe type #%d.",
- (int) b->type);
- ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
- annotate_field (2);
- ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
- annotate_field (3);
- ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
- ...
-
- This example, also from `print_one_breakpoint', shows how to produce
-a complicated output field using the `print_expression' functions which
-requires a stream to be passed. It also shows how to automate stream
-destruction with cleanups. The original code was:
-
- annotate_field (5);
- print_expression (b->exp, gdb_stdout);
-
- The new version is:
-
- struct ui_stream *stb = ui_out_stream_new (uiout);
- struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
- ...
- annotate_field (5);
- print_expression (b->exp, stb->stream);
- ui_out_field_stream (uiout, "what", local_stream);
-
- This example, also from `print_one_breakpoint', shows how to use
-`ui_out_text' and `ui_out_field_string'. The original code was:
-
- annotate_field (5);
- if (b->dll_pathname == NULL)
- printf_filtered ("<any library> ");
- else
- printf_filtered ("library \"%s\" ", b->dll_pathname);
-
- It became:
-
- annotate_field (5);
- if (b->dll_pathname == NULL)
- {
- ui_out_field_string (uiout, "what", "<any library>");
- ui_out_spaces (uiout, 1);
- }
- else
- {
- ui_out_text (uiout, "library \"");
- ui_out_field_string (uiout, "what", b->dll_pathname);
- ui_out_text (uiout, "\" ");
- }
-
- The following example from `print_one_breakpoint' shows how to use
-`ui_out_field_int' and `ui_out_spaces'. The original code was:
-
- annotate_field (5);
- if (b->forked_inferior_pid != 0)
- printf_filtered ("process %d ", b->forked_inferior_pid);
-
- It became:
-
- annotate_field (5);
- if (b->forked_inferior_pid != 0)
- {
- ui_out_text (uiout, "process ");
- ui_out_field_int (uiout, "what", b->forked_inferior_pid);
- ui_out_spaces (uiout, 1);
- }
-
- Here's an example of using `ui_out_field_string'. The original code
-was:
-
- annotate_field (5);
- if (b->exec_pathname != NULL)
- printf_filtered ("program \"%s\" ", b->exec_pathname);
-
- It became:
-
- annotate_field (5);
- if (b->exec_pathname != NULL)
- {
- ui_out_text (uiout, "program \"");
- ui_out_field_string (uiout, "what", b->exec_pathname);
- ui_out_text (uiout, "\" ");
- }
-
- Finally, here's an example of printing an address. The original
-code:
-
- annotate_field (4);
- printf_filtered ("%s ",
- hex_string_custom ((unsigned long) b->address, 8));
-
- It became:
-
- annotate_field (4);
- ui_out_field_core_addr (uiout, "Address", b->address);
-
-4.3 Console Printing
-====================
-
-4.4 TUI
-=======
-
----------- Footnotes ----------
-
- (1) The function cast is not portable ISO C.
-
- (2) As of this writing (April 2001), setting verbosity level is not
-yet implemented, and is always returned as zero. So calling
-`ui_out_message' with a VERBOSITY argument more than zero will cause
-the message to never be printed.
-
-\1f
-File: gdbint.info, Node: libgdb, Next: Values, Prev: User Interface, Up: Top
-
-5 libgdb
-********
-
-5.1 libgdb 1.0
-==============
-
-`libgdb' 1.0 was an abortive project of years ago. The theory was to
-provide an API to GDB's functionality.
-
-5.2 libgdb 2.0
-==============
-
-`libgdb' 2.0 is an ongoing effort to update GDB so that is better able
-to support graphical and other environments.
-
- Since `libgdb' development is on-going, its architecture is still
-evolving. The following components have so far been identified:
-
- * Observer - `gdb-events.h'.
-
- * Builder - `ui-out.h'
-
- * Event Loop - `event-loop.h'
-
- * Library - `gdb.h'
-
- The model that ties these components together is described below.
-
-5.3 The `libgdb' Model
-======================
-
-A client of `libgdb' interacts with the library in two ways.
-
- * As an observer (using `gdb-events') receiving notifications from
- `libgdb' of any internal state changes (break point changes, run
- state, etc).
-
- * As a client querying `libgdb' (using the `ui-out' builder) to
- obtain various status values from GDB.
-
- Since `libgdb' could have multiple clients (e.g., a GUI supporting
-the existing GDB CLI), those clients must co-operate when controlling
-`libgdb'. In particular, a client must ensure that `libgdb' is idle
-(i.e. no other client is using `libgdb') before responding to a
-`gdb-event' by making a query.
-
-5.4 CLI support
-===============
-
-At present GDB's CLI is very much entangled in with the core of
-`libgdb'. Consequently, a client wishing to include the CLI in their
-interface needs to carefully co-ordinate its own and the CLI's
-requirements.
-
- It is suggested that the client set `libgdb' up to be bi-modal
-(alternate between CLI and client query modes). The notes below sketch
-out the theory:
-
- * The client registers itself as an observer of `libgdb'.
-
- * The client create and install `cli-out' builder using its own
- versions of the `ui-file' `gdb_stderr', `gdb_stdtarg' and
- `gdb_stdout' streams.
-
- * The client creates a separate custom `ui-out' builder that is only
- used while making direct queries to `libgdb'.
-
- When the client receives input intended for the CLI, it simply
-passes it along. Since the `cli-out' builder is installed by default,
-all the CLI output in response to that command is routed (pronounced
-rooted) through to the client controlled `gdb_stdout' et. al. streams.
-At the same time, the client is kept abreast of internal changes by
-virtue of being a `libgdb' observer.
-
- The only restriction on the client is that it must wait until
-`libgdb' becomes idle before initiating any queries (using the client's
-custom builder).
-
-5.5 `libgdb' components
-=======================
-
-Observer - `gdb-events.h'
--------------------------
-
-`gdb-events' provides the client with a very raw mechanism that can be
-used to implement an observer. At present it only allows for one
-observer and that observer must, internally, handle the need to delay
-the processing of any event notifications until after `libgdb' has
-finished the current command.
-
-Builder - `ui-out.h'
---------------------
-
-`ui-out' provides the infrastructure necessary for a client to create a
-builder. That builder is then passed down to `libgdb' when doing any
-queries.
-
-Event Loop - `event-loop.h'
----------------------------
-
-`event-loop', currently non-re-entrant, provides a simple event loop.
-A client would need to either plug its self into this loop or,
-implement a new event-loop that GDB would use.
-
- The event-loop will eventually be made re-entrant. This is so that
-GDB can better handle the problem of some commands blocking instead of
-returning.
-
-Library - `gdb.h'
------------------
-
-`libgdb' is the most obvious component of this system. It provides the
-query interface. Each function is parameterized by a `ui-out' builder.
-The result of the query is constructed using that builder before the
-query function returns.
-
-\1f
-File: gdbint.info, Node: Values, Next: Stack Frames, Prev: libgdb, Up: Top
-
-6 Values
-********
-
-6.1 Values
-==========
-
-GDB uses `struct value', or "values", as an internal abstraction for
-the representation of a variety of inferior objects and GDB convenience
-objects.
-
- Values have an associated `struct type', that describes a virtual
-view of the raw data or object stored in or accessed through the value.
-
- A value is in addition discriminated by its lvalue-ness, given its
-`enum lval_type' enumeration type:
-
-``not_lval''
- This value is not an lval. It can't be assigned to.
-
-``lval_memory''
- This value represents an object in memory.
-
-``lval_register''
- This value represents an object that lives in a register.
-
-``lval_internalvar''
- Represents the value of an internal variable.
-
-``lval_internalvar_component''
- Represents part of a GDB internal variable. E.g., a structure
- field.
-
-``lval_computed''
- These are "computed" values. They allow creating specialized value
- objects for specific purposes, all abstracted away from the core
- value support code. The creator of such a value writes specialized
- functions to handle the reading and writing to/from the value's
- backend data, and optionally, a "copy operator" and a "destructor".
-
- Pointers to these functions are stored in a `struct lval_funcs'
- instance (declared in `value.h'), and passed to the
- `allocate_computed_value' function, as in the example below.
-
- static void
- nil_value_read (struct value *v)
- {
- /* This callback reads data from some backend, and stores it in V.
- In this case, we always read null data. You'll want to fill in
- something more interesting. */
-
- memset (value_contents_all_raw (v),
- value_offset (v),
- TYPE_LENGTH (value_type (v)));
- }
-
- static void
- nil_value_write (struct value *v, struct value *fromval)
- {
- /* Takes the data from FROMVAL and stores it in the backend of V. */
-
- to_oblivion (value_contents_all_raw (fromval),
- value_offset (v),
- TYPE_LENGTH (value_type (fromval)));
- }
-
- static struct lval_funcs nil_value_funcs =
- {
- nil_value_read,
- nil_value_write
- };
-
- struct value *
- make_nil_value (void)
- {
- struct type *type;
- struct value *v;
-
- type = make_nils_type ();
- v = allocate_computed_value (type, &nil_value_funcs, NULL);
-
- return v;
- }
-
- See the implementation of the `$_siginfo' convenience variable in
- `infrun.c' as a real example use of lval_computed.
-
-
-\1f
-File: gdbint.info, Node: Stack Frames, Next: Symbol Handling, Prev: Values, Up: Top
-
-7 Stack Frames
-**************
-
-A frame is a construct that GDB uses to keep track of calling and
-called functions.
-
- GDB's frame model, a fresh design, was implemented with the need to
-support DWARF's Call Frame Information in mind. In fact, the term
-"unwind" is taken directly from that specification. Developers wishing
-to learn more about unwinders, are encouraged to read the DWARF
-specification, available from `http://www.dwarfstd.org'.
-
- GDB's model is that you find a frame's registers by "unwinding" them
-from the next younger frame. That is, `get_frame_register' which
-returns the value of a register in frame #1 (the next-to-youngest
-frame), is implemented by calling frame #0's `frame_register_unwind'
-(the youngest frame). But then the obvious question is: how do you
-access the registers of the youngest frame itself?
-
- To answer this question, GDB has the "sentinel" frame, the "-1st"
-frame. Unwinding registers from the sentinel frame gives you the
-current values of the youngest real frame's registers. If F is a
-sentinel frame, then `get_frame_type (F) == SENTINEL_FRAME'.
-
-7.1 Selecting an Unwinder
-=========================
-
-The architecture registers a list of frame unwinders (`struct
-frame_unwind'), using the functions `frame_unwind_prepend_unwinder' and
-`frame_unwind_append_unwinder'. Each unwinder includes a sniffer.
-Whenever GDB needs to unwind a frame (to fetch the previous frame's
-registers or the current frame's ID), it calls registered sniffers in
-order to find one which recognizes the frame. The first time a sniffer
-returns non-zero, the corresponding unwinder is assigned to the frame.
-
-7.2 Unwinding the Frame ID
-==========================
-
-Every frame has an associated ID, of type `struct frame_id'. The ID
-includes the stack base and function start address for the frame. The
-ID persists through the entire life of the frame, including while other
-called frames are running; it is used to locate an appropriate `struct
-frame_info' from the cache.
-
- Every time the inferior stops, and at various other times, the frame
-cache is flushed. Because of this, parts of GDB which need to keep
-track of individual frames cannot use pointers to `struct frame_info'.
-A frame ID provides a stable reference to a frame, even when the
-unwinder must be run again to generate a new `struct frame_info' for
-the same frame.
-
- The frame's unwinder's `this_id' method is called to find the ID.
-Note that this is different from register unwinding, where the next
-frame's `prev_register' is called to unwind this frame's registers.
-
- Both stack base and function address are required to identify the
-frame, because a recursive function has the same function address for
-two consecutive frames and a leaf function may have the same stack
-address as its caller. On some platforms, a third address is part of
-the ID to further disambiguate frames--for instance, on IA-64 the
-separate register stack address is included in the ID.
-
- An invalid frame ID (`outer_frame_id') returned from the `this_id'
-method means to stop unwinding after this frame.
-
- `null_frame_id' is another invalid frame ID which should be used
-when there is no frame. For instance, certain breakpoints are attached
-to a specific frame, and that frame is identified through its frame ID
-(we use this to implement the "finish" command). Using `null_frame_id'
-as the frame ID for a given breakpoint means that the breakpoint is not
-specific to any frame. The `this_id' method should never return
-`null_frame_id'.
-
-7.3 Unwinding Registers
-=======================
-
-Each unwinder includes a `prev_register' method. This method takes a
-frame, an associated cache pointer, and a register number. It returns
-a `struct value *' describing the requested register, as saved by this
-frame. This is the value of the register that is current in this
-frame's caller.
-
- The returned value must have the same type as the register. It may
-have any lvalue type. In most circumstances one of these routines will
-generate the appropriate value:
-
-`frame_unwind_got_optimized'
- This register was not saved.
-
-`frame_unwind_got_register'
- This register was copied into another register in this frame. This
- is also used for unchanged registers; they are "copied" into the
- same register.
-
-`frame_unwind_got_memory'
- This register was saved in memory.
-
-`frame_unwind_got_constant'
- This register was not saved, but the unwinder can compute the
- previous value some other way.
-
-`frame_unwind_got_address'
- Same as `frame_unwind_got_constant', except that the value is a
- target address. This is frequently used for the stack pointer,
- which is not explicitly saved but has a known offset from this
- frame's stack pointer. For architectures with a flat unified
- address space, this is generally the same as
- `frame_unwind_got_constant'.
-
-\1f
-File: gdbint.info, Node: Symbol Handling, Next: Language Support, Prev: Stack Frames, Up: Top
-
-8 Symbol Handling
-*****************
-
-Symbols are a key part of GDB's operation. Symbols include variables,
-functions, and types.
-
- Symbol information for a large program can be truly massive, and
-reading of symbol information is one of the major performance
-bottlenecks in GDB; it can take many minutes to process it all.
-Studies have shown that nearly all the time spent is computational,
-rather than file reading.
-
- One of the ways for GDB to provide a good user experience is to
-start up quickly, taking no more than a few seconds. It is simply not
-possible to process all of a program's debugging info in that time, and
-so we attempt to handle symbols incrementally. For instance, we create
-"partial symbol tables" consisting of only selected symbols, and only
-expand them to full symbol tables when necessary.
-
-8.1 Symbol Reading
-==================
-
-GDB reads symbols from "symbol files". The usual symbol file is the
-file containing the program which GDB is debugging. GDB can be
-directed to use a different file for symbols (with the `symbol-file'
-command), and it can also read more symbols via the `add-file' and
-`load' commands. In addition, it may bring in more symbols while
-loading shared libraries.
-
- Symbol files are initially opened by code in `symfile.c' using the
-BFD library (*note Support Libraries::). BFD identifies the type of
-the file by examining its header. `find_sym_fns' then uses this
-identification to locate a set of symbol-reading functions.
-
- Symbol-reading modules identify themselves to GDB by calling
-`add_symtab_fns' during their module initialization. The argument to
-`add_symtab_fns' is a `struct sym_fns' which contains the name (or name
-prefix) of the symbol format, the length of the prefix, and pointers to
-four functions. These functions are called at various times to process
-symbol files whose identification matches the specified prefix.
-
- The functions supplied by each module are:
-
-`XYZ_symfile_init(struct sym_fns *sf)'
- Called from `symbol_file_add' when we are about to read a new
- symbol file. This function should clean up any internal state
- (possibly resulting from half-read previous files, for example)
- and prepare to read a new symbol file. Note that the symbol file
- which we are reading might be a new "main" symbol file, or might
- be a secondary symbol file whose symbols are being added to the
- existing symbol table.
-
- The argument to `XYZ_symfile_init' is a newly allocated `struct
- sym_fns' whose `bfd' field contains the BFD for the new symbol
- file being read. Its `private' field has been zeroed, and can be
- modified as desired. Typically, a struct of private information
- will be `malloc''d, and a pointer to it will be placed in the
- `private' field.
-
- There is no result from `XYZ_symfile_init', but it can call
- `error' if it detects an unavoidable problem.
-
-`XYZ_new_init()'
- Called from `symbol_file_add' when discarding existing symbols.
- This function needs only handle the symbol-reading module's
- internal state; the symbol table data structures visible to the
- rest of GDB will be discarded by `symbol_file_add'. It has no
- arguments and no result. It may be called after
- `XYZ_symfile_init', if a new symbol table is being read, or may be
- called alone if all symbols are simply being discarded.
-
-`XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)'
- Called from `symbol_file_add' to actually read the symbols from a
- symbol-file into a set of psymtabs or symtabs.
-
- `sf' points to the `struct sym_fns' originally passed to
- `XYZ_sym_init' for possible initialization. `addr' is the offset
- between the file's specified start address and its true address in
- memory. `mainline' is 1 if this is the main symbol table being
- read, and 0 if a secondary symbol file (e.g., shared library or
- dynamically loaded file) is being read.
-
- In addition, if a symbol-reading module creates psymtabs when
-XYZ_symfile_read is called, these psymtabs will contain a pointer to a
-function `XYZ_psymtab_to_symtab', which can be called from any point in
-the GDB symbol-handling code.
-
-`XYZ_psymtab_to_symtab (struct partial_symtab *pst)'
- Called from `psymtab_to_symtab' (or the `PSYMTAB_TO_SYMTAB' macro)
- if the psymtab has not already been read in and had its
- `pst->symtab' pointer set. The argument is the psymtab to be
- fleshed-out into a symtab. Upon return, `pst->readin' should have
- been set to 1, and `pst->symtab' should contain a pointer to the
- new corresponding symtab, or zero if there were no symbols in that
- part of the symbol file.
-
-8.2 Partial Symbol Tables
-=========================
-
-GDB has three types of symbol tables:
-
- * Full symbol tables ("symtabs"). These contain the main
- information about symbols and addresses.
-
- * Partial symbol tables ("psymtabs"). These contain enough
- information to know when to read the corresponding part of the full
- symbol table.
-
- * Minimal symbol tables ("msymtabs"). These contain information
- gleaned from non-debugging symbols.
-
- This section describes partial symbol tables.
-
- A psymtab is constructed by doing a very quick pass over an
-executable file's debugging information. Small amounts of information
-are extracted--enough to identify which parts of the symbol table will
-need to be re-read and fully digested later, when the user needs the
-information. The speed of this pass causes GDB to start up very
-quickly. Later, as the detailed rereading occurs, it occurs in small
-pieces, at various times, and the delay therefrom is mostly invisible to
-the user.
-
- The symbols that show up in a file's psymtab should be, roughly,
-those visible to the debugger's user when the program is not running
-code from that file. These include external symbols and types, static
-symbols and types, and `enum' values declared at file scope.
-
- The psymtab also contains the range of instruction addresses that the
-full symbol table would represent.
-
- The idea is that there are only two ways for the user (or much of the
-code in the debugger) to reference a symbol:
-
- * By its address (e.g., execution stops at some address which is
- inside a function in this file). The address will be noticed to
- be in the range of this psymtab, and the full symtab will be read
- in. `find_pc_function', `find_pc_line', and other `find_pc_...'
- functions handle this.
-
- * By its name (e.g., the user asks to print a variable, or set a
- breakpoint on a function). Global names and file-scope names will
- be found in the psymtab, which will cause the symtab to be pulled
- in. Local names will have to be qualified by a global name, or a
- file-scope name, in which case we will have already read in the
- symtab as we evaluated the qualifier. Or, a local symbol can be
- referenced when we are "in" a local scope, in which case the first
- case applies. `lookup_symbol' does most of the work here.
-
- The only reason that psymtabs exist is to cause a symtab to be read
-in at the right moment. Any symbol that can be elided from a psymtab,
-while still causing that to happen, should not appear in it. Since
-psymtabs don't have the idea of scope, you can't put local symbols in
-them anyway. Psymtabs don't have the idea of the type of a symbol,
-either, so types need not appear, unless they will be referenced by
-name.
-
- It is a bug for GDB to behave one way when only a psymtab has been
-read, and another way if the corresponding symtab has been read in.
-Such bugs are typically caused by a psymtab that does not contain all
-the visible symbols, or which has the wrong instruction address ranges.
-
- The psymtab for a particular section of a symbol file (objfile)
-could be thrown away after the symtab has been read in. The symtab
-should always be searched before the psymtab, so the psymtab will never
-be used (in a bug-free environment). Currently, psymtabs are allocated
-on an obstack, and all the psymbols themselves are allocated in a pair
-of large arrays on an obstack, so there is little to be gained by
-trying to free them unless you want to do a lot more work.
-
-8.3 Types
-=========
-
-Fundamental Types (e.g., `FT_VOID', `FT_BOOLEAN').
---------------------------------------------------
-
-These are the fundamental types that GDB uses internally. Fundamental
-types from the various debugging formats (stabs, ELF, etc) are mapped
-into one of these. They are basically a union of all fundamental types
-that GDB knows about for all the languages that GDB knows about.
-
-Type Codes (e.g., `TYPE_CODE_PTR', `TYPE_CODE_ARRAY').
-------------------------------------------------------
-
-Each time GDB builds an internal type, it marks it with one of these
-types. The type may be a fundamental type, such as `TYPE_CODE_INT', or
-a derived type, such as `TYPE_CODE_PTR' which is a pointer to another
-type. Typically, several `FT_*' types map to one `TYPE_CODE_*' type,
-and are distinguished by other members of the type struct, such as
-whether the type is signed or unsigned, and how many bits it uses.
-
-Builtin Types (e.g., `builtin_type_void', `builtin_type_char').
----------------------------------------------------------------
-
-These are instances of type structs that roughly correspond to
-fundamental types and are created as global types for GDB to use for
-various ugly historical reasons. We eventually want to eliminate
-these. Note for example that `builtin_type_int' initialized in
-`gdbtypes.c' is basically the same as a `TYPE_CODE_INT' type that is
-initialized in `c-lang.c' for an `FT_INTEGER' fundamental type. The
-difference is that the `builtin_type' is not associated with any
-particular objfile, and only one instance exists, while `c-lang.c'
-builds as many `TYPE_CODE_INT' types as needed, with each one
-associated with some particular objfile.
-
-8.4 Object File Formats
-=======================
-
-8.4.1 a.out
------------
-
-The `a.out' format is the original file format for Unix. It consists
-of three sections: `text', `data', and `bss', which are for program
-code, initialized data, and uninitialized data, respectively.
-
- The `a.out' format is so simple that it doesn't have any reserved
-place for debugging information. (Hey, the original Unix hackers used
-`adb', which is a machine-language debugger!) The only debugging
-format for `a.out' is stabs, which is encoded as a set of normal
-symbols with distinctive attributes.
-
- The basic `a.out' reader is in `dbxread.c'.
-
-8.4.2 COFF
-----------
-
-The COFF format was introduced with System V Release 3 (SVR3) Unix.
-COFF files may have multiple sections, each prefixed by a header. The
-number of sections is limited.
-
- The COFF specification includes support for debugging. Although this
-was a step forward, the debugging information was woefully limited.
-For instance, it was not possible to represent code that came from an
-included file. GNU's COFF-using configs often use stabs-type info,
-encapsulated in special sections.
-
- The COFF reader is in `coffread.c'.
-
-8.4.3 ECOFF
------------
-
-ECOFF is an extended COFF originally introduced for Mips and Alpha
-workstations.
-
- The basic ECOFF reader is in `mipsread.c'.
-
-8.4.4 XCOFF
------------
-
-The IBM RS/6000 running AIX uses an object file format called XCOFF.
-The COFF sections, symbols, and line numbers are used, but debugging
-symbols are `dbx'-style stabs whose strings are located in the `.debug'
-section (rather than the string table). For more information, see
-*note Top: (stabs)Top.
-
- The shared library scheme has a clean interface for figuring out what
-shared libraries are in use, but the catch is that everything which
-refers to addresses (symbol tables and breakpoints at least) needs to be
-relocated for both shared libraries and the main executable. At least
-using the standard mechanism this can only be done once the program has
-been run (or the core file has been read).
-
-8.4.5 PE
---------
-
-Windows 95 and NT use the PE ("Portable Executable") format for their
-executables. PE is basically COFF with additional headers.
-
- While BFD includes special PE support, GDB needs only the basic COFF
-reader.
-
-8.4.6 ELF
----------
-
-The ELF format came with System V Release 4 (SVR4) Unix. ELF is
-similar to COFF in being organized into a number of sections, but it
-removes many of COFF's limitations. Debugging info may be either stabs
-encapsulated in ELF sections, or more commonly these days, DWARF.
-
- The basic ELF reader is in `elfread.c'.
-
-8.4.7 SOM
----------
-
-SOM is HP's object file and debug format (not to be confused with IBM's
-SOM, which is a cross-language ABI).
-
- The SOM reader is in `somread.c'.
-
-8.5 Debugging File Formats
-==========================
-
-This section describes characteristics of debugging information that
-are independent of the object file format.
-
-8.5.1 stabs
------------
-
-`stabs' started out as special symbols within the `a.out' format.
-Since then, it has been encapsulated into other file formats, such as
-COFF and ELF.
-
- While `dbxread.c' does some of the basic stab processing, including
-for encapsulated versions, `stabsread.c' does the real work.
-
-8.5.2 COFF
-----------
-
-The basic COFF definition includes debugging information. The level of
-support is minimal and non-extensible, and is not often used.
-
-8.5.3 Mips debug (Third Eye)
-----------------------------
-
-ECOFF includes a definition of a special debug format.
-
- The file `mdebugread.c' implements reading for this format.
-
-8.5.4 DWARF 2
--------------
-
-DWARF 2 is an improved but incompatible version of DWARF 1.
-
- The DWARF 2 reader is in `dwarf2read.c'.
-
-8.5.5 Compressed DWARF 2
-------------------------
-
-Compressed DWARF 2 is not technically a separate debugging format, but
-merely DWARF 2 debug information that has been compressed. In this
-format, every object-file section holding DWARF 2 debugging information
-is compressed and prepended with a header. (The section is also
-typically renamed, so a section called `.debug_info' in a DWARF 2
-binary would be called `.zdebug_info' in a compressed DWARF 2 binary.)
-The header is 12 bytes long:
-
- * 4 bytes: the literal string "ZLIB"
-
- * 8 bytes: the uncompressed size of the section, in big-endian byte
- order.
-
- The same reader is used for both compressed an normal DWARF 2 info.
-Section decompression is done in `zlib_decompress_section' in
-`dwarf2read.c'.
-
-8.5.6 DWARF 3
--------------
-
-DWARF 3 is an improved version of DWARF 2.
-
-8.5.7 SOM
----------
-
-Like COFF, the SOM definition includes debugging information.
-
-8.6 Adding a New Symbol Reader to GDB
-=====================================
-
-If you are using an existing object file format (`a.out', COFF, ELF,
-etc), there is probably little to be done.
-
- If you need to add a new object file format, you must first add it to
-BFD. This is beyond the scope of this document.
-
- You must then arrange for the BFD code to provide access to the
-debugging symbols. Generally GDB will have to call swapping routines
-from BFD and a few other BFD internal routines to locate the debugging
-information. As much as possible, GDB should not depend on the BFD
-internal data structures.
-
- For some targets (e.g., COFF), there is a special transfer vector
-used to call swapping routines, since the external data structures on
-various platforms have different sizes and layouts. Specialized
-routines that will only ever be implemented by one object file format
-may be called directly. This interface should be described in a file
-`bfd/libXYZ.h', which is included by GDB.
-
-8.7 Memory Management for Symbol Files
-======================================
-
-Most memory associated with a loaded symbol file is stored on its
-`objfile_obstack'. This includes symbols, types, namespace data, and
-other information produced by the symbol readers.
-
- Because this data lives on the objfile's obstack, it is automatically
-released when the objfile is unloaded or reloaded. Therefore one
-objfile must not reference symbol or type data from another objfile;
-they could be unloaded at different times.
-
- User convenience variables, et cetera, have associated types.
-Normally these types live in the associated objfile. However, when the
-objfile is unloaded, those types are deep copied to global memory, so
-that the values of the user variables and history items are not lost.
-
-\1f
-File: gdbint.info, Node: Language Support, Next: Host Definition, Prev: Symbol Handling, Up: Top
-
-9 Language Support
-******************
-
-GDB's language support is mainly driven by the symbol reader, although
-it is possible for the user to set the source language manually.
-
- GDB chooses the source language by looking at the extension of the
-file recorded in the debug info; `.c' means C, `.f' means Fortran, etc.
-It may also use a special-purpose language identifier if the debug
-format supports it, like with DWARF.
-
-9.1 Adding a Source Language to GDB
-===================================
-
-To add other languages to GDB's expression parser, follow the following
-steps:
-
-_Create the expression parser._
- This should reside in a file `LANG-exp.y'. Routines for building
- parsed expressions into a `union exp_element' list are in
- `parse.c'.
-
- Since we can't depend upon everyone having Bison, and YACC produces
- parsers that define a bunch of global names, the following lines
- *must* be included at the top of the YACC parser, to prevent the
- various parsers from defining the same global names:
-
- #define yyparse LANG_parse
- #define yylex LANG_lex
- #define yyerror LANG_error
- #define yylval LANG_lval
- #define yychar LANG_char
- #define yydebug LANG_debug
- #define yypact LANG_pact
- #define yyr1 LANG_r1
- #define yyr2 LANG_r2
- #define yydef LANG_def
- #define yychk LANG_chk
- #define yypgo LANG_pgo
- #define yyact LANG_act
- #define yyexca LANG_exca
- #define yyerrflag LANG_errflag
- #define yynerrs LANG_nerrs
-
- At the bottom of your parser, define a `struct language_defn' and
- initialize it with the right values for your language. Define an
- `initialize_LANG' routine and have it call
- `add_language(LANG_language_defn)' to tell the rest of GDB that
- your language exists. You'll need some other supporting variables
- and functions, which will be used via pointers from your
- `LANG_language_defn'. See the declaration of `struct
- language_defn' in `language.h', and the other `*-exp.y' files, for
- more information.
-
-_Add any evaluation routines, if necessary_
- If you need new opcodes (that represent the operations of the
- language), add them to the enumerated type in `expression.h'. Add
- support code for these operations in the `evaluate_subexp' function
- defined in the file `eval.c'. Add cases for new opcodes in two
- functions from `parse.c': `prefixify_subexp' and
- `length_of_subexp'. These compute the number of `exp_element's
- that a given operation takes up.
-
-_Update some existing code_
- Add an enumerated identifier for your language to the enumerated
- type `enum language' in `defs.h'.
-
- Update the routines in `language.c' so your language is included.
- These routines include type predicates and such, which (in some
- cases) are language dependent. If your language does not appear
- in the switch statement, an error is reported.
-
- Also included in `language.c' is the code that updates the variable
- `current_language', and the routines that translate the
- `language_LANG' enumerated identifier into a printable string.
-
- Update the function `_initialize_language' to include your
- language. This function picks the default language upon startup,
- so is dependent upon which languages that GDB is built for.
-
- Update `allocate_symtab' in `symfile.c' and/or symbol-reading code
- so that the language of each symtab (source file) is set properly.
- This is used to determine the language to use at each stack frame
- level. Currently, the language is set based upon the extension of
- the source file. If the language can be better inferred from the
- symbol information, please set the language of the symtab in the
- symbol-reading code.
-
- Add helper code to `print_subexp' (in `expprint.c') to handle any
- new expression opcodes you have added to `expression.h'. Also,
- add the printed representations of your operators to
- `op_print_tab'.
-
-_Add a place of call_
- Add a call to `LANG_parse()' and `LANG_error' in `parse_exp_1'
- (defined in `parse.c').
-
-_Edit `Makefile.in'_
- Add dependencies in `Makefile.in'. Make sure you update the macro
- variables such as `HFILES' and `OBJS', otherwise your code may not
- get linked in, or, worse yet, it may not get `tar'red into the
- distribution!
-
-\1f
-File: gdbint.info, Node: Host Definition, Next: Target Architecture Definition, Prev: Language Support, Up: Top
-
-10 Host Definition
-******************
-
-With the advent of Autoconf, it's rarely necessary to have host
-definition machinery anymore. The following information is provided,
-mainly, as an historical reference.
-
-10.1 Adding a New Host
-======================
-
-GDB's host configuration support normally happens via Autoconf. New
-host-specific definitions should not be needed. Older hosts GDB still
-use the host-specific definitions and files listed below, but these
-mostly exist for historical reasons, and will eventually disappear.
-
-`gdb/config/ARCH/XYZ.mh'
- This file is a Makefile fragment that once contained both host and
- native configuration information (*note Native Debugging::) for the
- machine XYZ. The host configuration information is now handled by
- Autoconf.
-
- Host configuration information included definitions for `CC',
- `SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS',
- `XM_CDEPS', etc.; see `Makefile.in'.
-
- New host-only configurations do not need this file.
-
-
- (Files named `gdb/config/ARCH/xm-XYZ.h' were once used to define
-host-specific macros, but were no longer needed and have all been
-removed.)
-
-Generic Host Support Files
---------------------------
-
-There are some "generic" versions of routines that can be used by
-various systems.
-
-`ser-unix.c'
- This contains serial line support for Unix systems. It is
- included by default on all Unix-like hosts.
-
-`ser-pipe.c'
- This contains serial pipe support for Unix systems. It is
- included by default on all Unix-like hosts.
-
-`ser-mingw.c'
- This contains serial line support for 32-bit programs running under
- Windows using MinGW.
-
-`ser-go32.c'
- This contains serial line support for 32-bit programs running
- under DOS, using the DJGPP (a.k.a. GO32) execution environment.
-
-`ser-tcp.c'
- This contains generic TCP support using sockets. It is included by
- default on all Unix-like hosts and with MinGW.
-
-10.2 Host Conditionals
-======================
-
-When GDB is configured and compiled, various macros are defined or left
-undefined, to control compilation based on the attributes of the host
-system. While formerly they could be set in host-specific header
-files, at present they can be changed only by setting `CFLAGS' when
-building, or by editing the source code.
-
- These macros and their meanings (or if the meaning is not documented
-here, then one of the source files where they are used is indicated)
-are:
-
-`GDBINIT_FILENAME'
- The default name of GDB's initialization file (normally
- `.gdbinit').
-
-`SIGWINCH_HANDLER'
- If your host defines `SIGWINCH', you can define this to be the name
- of a function to be called if `SIGWINCH' is received.
-
-`SIGWINCH_HANDLER_BODY'
- Define this to expand into code that will define the function
- named by the expansion of `SIGWINCH_HANDLER'.
-
-`CRLF_SOURCE_FILES'
- Define this if host files use `\r\n' rather than `\n' as a line
- terminator. This will cause source file listings to omit `\r'
- characters when printing and it will allow `\r\n' line endings of
- files which are "sourced" by gdb. It must be possible to open
- files in binary mode using `O_BINARY' or, for fopen, `"rb"'.
-
-`DEFAULT_PROMPT'
- The default value of the prompt string (normally `"(gdb) "').
-
-`DEV_TTY'
- The name of the generic TTY device, defaults to `"/dev/tty"'.
-
-`ISATTY'
- Substitute for isatty, if not available.
-
-`FOPEN_RB'
- Define this if binary files are opened the same way as text files.
-
-`CC_HAS_LONG_LONG'
- Define this if the host C compiler supports `long long'. This is
- set by the `configure' script.
-
-`PRINTF_HAS_LONG_LONG'
- Define this if the host can handle printing of long long integers
- via the printf format conversion specifier `ll'. This is set by
- the `configure' script.
-
-`LSEEK_NOT_LINEAR'
- Define this if `lseek (n)' does not necessarily move to byte number
- `n' in the file. This is only used when reading source files. It
- is normally faster to define `CRLF_SOURCE_FILES' when possible.
-
-`NORETURN'
- If defined, this should be one or more tokens, such as `volatile',
- that can be used in both the declaration and definition of
- functions to indicate that they never return. The default is
- already set correctly if compiling with GCC. This will almost
- never need to be defined.
-
-`ATTR_NORETURN'
- If defined, this should be one or more tokens, such as
- `__attribute__ ((noreturn))', that can be used in the declarations
- of functions to indicate that they never return. The default is
- already set correctly if compiling with GCC. This will almost
- never need to be defined.
-
-`lint'
- Define this to help placate `lint' in some situations.
-
-`volatile'
- Define this to override the defaults of `__volatile__' or `/**/'.
-
-\1f
-File: gdbint.info, Node: Target Architecture Definition, Next: Target Descriptions, Prev: Host Definition, Up: Top
-
-11 Target Architecture Definition
-*********************************
-
-GDB's target architecture defines what sort of machine-language
-programs GDB can work with, and how it works with them.
-
- The target architecture object is implemented as the C structure
-`struct gdbarch *'. The structure, and its methods, are generated
-using the Bourne shell script `gdbarch.sh'.
-
-* Menu:
-
-* OS ABI Variant Handling::
-* Initialize New Architecture::
-* Registers and Memory::
-* Pointers and Addresses::
-* Address Classes::
-* Register Representation::
-* Frame Interpretation::
-* Inferior Call Setup::
-* Adding support for debugging core files::
-* Defining Other Architecture Features::
-* Adding a New Target::
-
-\1f
-File: gdbint.info, Node: OS ABI Variant Handling, Next: Initialize New Architecture, Up: Target Architecture Definition
-
-11.1 Operating System ABI Variant Handling
-==========================================
-
-GDB provides a mechanism for handling variations in OS ABIs. An OS ABI
-variant may have influence over any number of variables in the target
-architecture definition. There are two major components in the OS ABI
-mechanism: sniffers and handlers.
-
- A "sniffer" examines a file matching a BFD architecture/flavour pair
-(the architecture may be wildcarded) in an attempt to determine the OS
-ABI of that file. Sniffers with a wildcarded architecture are
-considered to be "generic", while sniffers for a specific architecture
-are considered to be "specific". A match from a specific sniffer
-overrides a match from a generic sniffer. Multiple sniffers for an
-architecture/flavour may exist, in order to differentiate between two
-different operating systems which use the same basic file format. The
-OS ABI framework provides a generic sniffer for ELF-format files which
-examines the `EI_OSABI' field of the ELF header, as well as note
-sections known to be used by several operating systems.
-
- A "handler" is used to fine-tune the `gdbarch' structure for the
-selected OS ABI. There may be only one handler for a given OS ABI for
-each BFD architecture.
-
- The following OS ABI variants are defined in `defs.h':
-
-`GDB_OSABI_UNINITIALIZED'
- Used for struct gdbarch_info if ABI is still uninitialized.
-
-`GDB_OSABI_UNKNOWN'
- The ABI of the inferior is unknown. The default `gdbarch'
- settings for the architecture will be used.
-
-`GDB_OSABI_SVR4'
- UNIX System V Release 4.
-
-`GDB_OSABI_HURD'
- GNU using the Hurd kernel.
-
-`GDB_OSABI_SOLARIS'
- Sun Solaris.
-
-`GDB_OSABI_OSF1'
- OSF/1, including Digital UNIX and Compaq Tru64 UNIX.
-
-`GDB_OSABI_LINUX'
- GNU using the Linux kernel.
-
-`GDB_OSABI_FREEBSD_AOUT'
- FreeBSD using the `a.out' executable format.
-
-`GDB_OSABI_FREEBSD_ELF'
- FreeBSD using the ELF executable format.
-
-`GDB_OSABI_NETBSD_AOUT'
- NetBSD using the `a.out' executable format.
-
-`GDB_OSABI_NETBSD_ELF'
- NetBSD using the ELF executable format.
-
-`GDB_OSABI_OPENBSD_ELF'
- OpenBSD using the ELF executable format.
-
-`GDB_OSABI_WINCE'
- Windows CE.
-
-`GDB_OSABI_GO32'
- DJGPP.
-
-`GDB_OSABI_IRIX'
- Irix.
-
-`GDB_OSABI_INTERIX'
- Interix (Posix layer for MS-Windows systems).
-
-`GDB_OSABI_HPUX_ELF'
- HP/UX using the ELF executable format.
-
-`GDB_OSABI_HPUX_SOM'
- HP/UX using the SOM executable format.
-
-`GDB_OSABI_QNXNTO'
- QNX Neutrino.
-
-`GDB_OSABI_CYGWIN'
- Cygwin.
-
-`GDB_OSABI_AIX'
- AIX.
-
-
- Here are the functions that make up the OS ABI framework:
-
- -- Function: const char * gdbarch_osabi_name (enum gdb_osabi OSABI)
- Return the name of the OS ABI corresponding to OSABI.
-
- -- Function: void gdbarch_register_osabi (enum bfd_architecture ARCH,
- unsigned long MACHINE, enum gdb_osabi OSABI, void
- (*INIT_OSABI)(struct gdbarch_info INFO, struct gdbarch
- *GDBARCH))
- Register the OS ABI handler specified by INIT_OSABI for the
- architecture, machine type and OS ABI specified by ARCH, MACHINE
- and OSABI. In most cases, a value of zero for the machine type,
- which implies the architecture's default machine type, will
- suffice.
-
- -- Function: void gdbarch_register_osabi_sniffer (enum
- bfd_architecture ARCH, enum bfd_flavour FLAVOUR, enum
- gdb_osabi (*SNIFFER)(bfd *ABFD))
- Register the OS ABI file sniffer specified by SNIFFER for the BFD
- architecture/flavour pair specified by ARCH and FLAVOUR. If ARCH
- is `bfd_arch_unknown', the sniffer is considered to be generic,
- and is allowed to examine FLAVOUR-flavoured files for any
- architecture.
-
- -- Function: enum gdb_osabi gdbarch_lookup_osabi (bfd *ABFD)
- Examine the file described by ABFD to determine its OS ABI. The
- value `GDB_OSABI_UNKNOWN' is returned if the OS ABI cannot be
- determined.
-
- -- Function: void gdbarch_init_osabi (struct gdbarch info INFO, struct
- gdbarch *GDBARCH, enum gdb_osabi OSABI)
- Invoke the OS ABI handler corresponding to OSABI to fine-tune the
- `gdbarch' structure specified by GDBARCH. If a handler
- corresponding to OSABI has not been registered for GDBARCH's
- architecture, a warning will be issued and the debugging session
- will continue with the defaults already established for GDBARCH.
-
- -- Function: void generic_elf_osabi_sniff_abi_tag_sections (bfd *ABFD,
- asection *SECT, void *OBJ)
- Helper routine for ELF file sniffers. Examine the file described
- by ABFD and look at ABI tag note sections to determine the OS ABI
- from the note. This function should be called via
- `bfd_map_over_sections'.
-
-\1f
-File: gdbint.info, Node: Initialize New Architecture, Next: Registers and Memory, Prev: OS ABI Variant Handling, Up: Target Architecture Definition
-
-11.2 Initializing a New Architecture
-====================================
-
-* Menu:
-
-* How an Architecture is Represented::
-* Looking Up an Existing Architecture::
-* Creating a New Architecture::
-
-\1f
-File: gdbint.info, Node: How an Architecture is Represented, Next: Looking Up an Existing Architecture, Up: Initialize New Architecture
-
-11.2.1 How an Architecture is Represented
------------------------------------------
-
-Each `gdbarch' is associated with a single BFD architecture, via a
-`bfd_arch_ARCH' in the `bfd_architecture' enumeration. The `gdbarch'
-is registered by a call to `register_gdbarch_init', usually from the
-file's `_initialize_FILENAME' routine, which will be automatically
-called during GDB startup. The arguments are a BFD architecture
-constant and an initialization function.
-
- A GDB description for a new architecture, ARCH is created by
-defining a global function `_initialize_ARCH_tdep', by convention in
-the source file `ARCH-tdep.c'. For example, in the case of the
-OpenRISC 1000, this function is called `_initialize_or1k_tdep' and is
-found in the file `or1k-tdep.c'.
-
- The resulting object files containing the implementation of the
-`_initialize_ARCH_tdep' function are specified in the GDB
-`configure.tgt' file, which includes a large case statement pattern
-matching against the `--target' option of the `configure' script. The
-new `struct gdbarch' is created within the `_initialize_ARCH_tdep'
-function by calling `gdbarch_register':
-
- void gdbarch_register (enum bfd_architecture ARCHITECTURE,
- gdbarch_init_ftype *INIT_FUNC,
- gdbarch_dump_tdep_ftype *TDEP_DUMP_FUNC);
-
- The ARCHITECTURE will identify the unique BFD to be associated with
-this `gdbarch'. The INIT_FUNC funciton is called to create and return
-the new `struct gdbarch'. The TDEP_DUMP_FUNC function will dump the
-target specific details associated with this architecture.
-
- For example the function `_initialize_or1k_tdep' creates its
-architecture for 32-bit OpenRISC 1000 architectures by calling:
-
- gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep);
-
-\1f
-File: gdbint.info, Node: Looking Up an Existing Architecture, Next: Creating a New Architecture, Prev: How an Architecture is Represented, Up: Initialize New Architecture
-
-11.2.2 Looking Up an Existing Architecture
-------------------------------------------
-
-The initialization function has this prototype:
-
- static struct gdbarch *
- ARCH_gdbarch_init (struct gdbarch_info INFO,
- struct gdbarch_list *ARCHES)
-
- The INFO argument contains parameters used to select the correct
-architecture, and ARCHES is a list of architectures which have already
-been created with the same `bfd_arch_ARCH' value.
-
- The initialization function should first make sure that INFO is
-acceptable, and return `NULL' if it is not. Then, it should search
-through ARCHES for an exact match to INFO, and return one if found.
-Lastly, if no exact match was found, it should create a new
-architecture based on INFO and return it.
-
- The lookup is done using `gdbarch_list_lookup_by_info'. It is
-passed the list of existing architectures, ARCHES, and the `struct
-gdbarch_info', INFO, and returns the first matching architecture it
-finds, or `NULL' if none are found. If an architecture is found it can
-be returned as the result from the initialization function, otherwise a
-new `struct gdbach' will need to be created.
-
- The struct gdbarch_info has the following components:
-
- struct gdbarch_info
- {
- const struct bfd_arch_info *bfd_arch_info;
- int byte_order;
- bfd *abfd;
- struct gdbarch_tdep_info *tdep_info;
- enum gdb_osabi osabi;
- const struct target_desc *target_desc;
- };
-
- The `bfd_arch_info' member holds the key details about the
-architecture. The `byte_order' member is a value in an enumeration
-indicating the endianism. The `abfd' member is a pointer to the full
-BFD, the `tdep_info' member is additional custom target specific
-information, `osabi' identifies which (if any) of a number of operating
-specific ABIs are used by this architecture and the `target_desc'
-member is a set of name-value pairs with information about register
-usage in this target.
-
- When the `struct gdbarch' initialization function is called, not all
-the fields are provided--only those which can be deduced from the BFD.
-The `struct gdbarch_info', INFO is used as a look-up key with the list
-of existing architectures, ARCHES to see if a suitable architecture
-already exists. The TDEP_INFO, OSABI and TARGET_DESC fields may be
-added before this lookup to refine the search.
-
- Only information in INFO should be used to choose the new
-architecture. Historically, INFO could be sparse, and defaults would
-be collected from the first element on ARCHES. However, GDB now fills
-in INFO more thoroughly, so new `gdbarch' initialization functions
-should not take defaults from ARCHES.
-
-\1f
-File: gdbint.info, Node: Creating a New Architecture, Prev: Looking Up an Existing Architecture, Up: Initialize New Architecture
-
-11.2.3 Creating a New Architecture
-----------------------------------
-
-If no architecture is found, then a new architecture must be created,
-by calling `gdbarch_alloc' using the supplied `struct gdbarch_info' and
-any additional custom target specific information in a `struct
-gdbarch_tdep'. The prototype for `gdbarch_alloc' is:
-
- struct gdbarch *gdbarch_alloc (const struct gdbarch_info *INFO,
- struct gdbarch_tdep *TDEP);
-
- The newly created struct gdbarch must then be populated. Although
-there are default values, in most cases they are not what is required.
-
- For each element, X, there is are a pair of corresponding accessor
-functions, one to set the value of that element, `set_gdbarch_X', the
-second to either get the value of an element (if it is a variable) or
-to apply the element (if it is a function), `gdbarch_X'. Note that
-both accessor functions take a pointer to the `struct gdbarch' as first
-argument. Populating the new `gdbarch' should use the `set_gdbarch'
-functions.
-
- The following sections identify the main elements that should be set
-in this way. This is not the complete list, but represents the
-functions and elements that must commonly be specified for a new
-architecture. Many of the functions and variables are described in the
-header file `gdbarch.h'.
-
- This is the main work in defining a new architecture. Implementing
-the set of functions to populate the `struct gdbarch'.
-
- `struct gdbarch_tdep' is not defined within GDB--it is up to the
-user to define this struct if it is needed to hold custom target
-information that is not covered by the standard `struct gdbarch'. For
-example with the OpenRISC 1000 architecture it is used to hold the
-number of matchpoints available in the target (along with other
-information).
-
- If there is no additional target specific information, it can be set
-to `NULL'.
-
-\1f
-File: gdbint.info, Node: Registers and Memory, Next: Pointers and Addresses, Prev: Initialize New Architecture, Up: Target Architecture Definition
-
-11.3 Registers and Memory
-=========================
-
-GDB's model of the target machine is rather simple. GDB assumes the
-machine includes a bank of registers and a block of memory. Each
-register may have a different size.
-
- GDB does not have a magical way to match up with the compiler's idea
-of which registers are which; however, it is critical that they do
-match up accurately. The only way to make this work is to get accurate
-information about the order that the compiler uses, and to reflect that
-in the `gdbarch_register_name' and related functions.
-
- GDB can handle big-endian, little-endian, and bi-endian
-architectures.
-
-\1f
-File: gdbint.info, Node: Pointers and Addresses, Next: Address Classes, Prev: Registers and Memory, Up: Target Architecture Definition
-
-11.4 Pointers Are Not Always Addresses
-======================================
-
-On almost all 32-bit architectures, the representation of a pointer is
-indistinguishable from the representation of some fixed-length number
-whose value is the byte address of the object pointed to. On such
-machines, the words "pointer" and "address" can be used interchangeably.
-However, architectures with smaller word sizes are often cramped for
-address space, so they may choose a pointer representation that breaks
-this identity, and allows a larger code address space.
-
- For example, the Renesas D10V is a 16-bit VLIW processor whose
-instructions are 32 bits long(1). If the D10V used ordinary byte
-addresses to refer to code locations, then the processor would only be
-able to address 64kb of instructions. However, since instructions must
-be aligned on four-byte boundaries, the low two bits of any valid
-instruction's byte address are always zero--byte addresses waste two
-bits. So instead of byte addresses, the D10V uses word addresses--byte
-addresses shifted right two bits--to refer to code. Thus, the D10V can
-use 16-bit words to address 256kb of code space.
-
- However, this means that code pointers and data pointers have
-different forms on the D10V. The 16-bit word `0xC020' refers to byte
-address `0xC020' when used as a data address, but refers to byte address
-`0x30080' when used as a code address.
-
- (The D10V also uses separate code and data address spaces, which also
-affects the correspondence between pointers and addresses, but we're
-going to ignore that here; this example is already too long.)
-
- To cope with architectures like this--the D10V is not the only
-one!--GDB tries to distinguish between "addresses", which are byte
-numbers, and "pointers", which are the target's representation of an
-address of a particular type of data. In the example above, `0xC020'
-is the pointer, which refers to one of the addresses `0xC020' or
-`0x30080', depending on the type imposed upon it. GDB provides
-functions for turning a pointer into an address and vice versa, in the
-appropriate way for the current architecture.
-
- Unfortunately, since addresses and pointers are identical on almost
-all processors, this distinction tends to bit-rot pretty quickly. Thus,
-each time you port GDB to an architecture which does distinguish
-between pointers and addresses, you'll probably need to clean up some
-architecture-independent code.
-
- Here are functions which convert between pointers and addresses:
-
- -- Function: CORE_ADDR extract_typed_address (void *BUF, struct type
- *TYPE)
- Treat the bytes at BUF as a pointer or reference of type TYPE, and
- return the address it represents, in a manner appropriate for the
- current architecture. This yields an address GDB can use to read
- target memory, disassemble, etc. Note that BUF refers to a buffer
- in GDB's memory, not the inferior's.
-
- For example, if the current architecture is the Intel x86, this
- function extracts a little-endian integer of the appropriate
- length from BUF and returns it. However, if the current
- architecture is the D10V, this function will return a 16-bit
- integer extracted from BUF, multiplied by four if TYPE is a
- pointer to a function.
-
- If TYPE is not a pointer or reference type, then this function
- will signal an internal error.
-
- -- Function: CORE_ADDR store_typed_address (void *BUF, struct type
- *TYPE, CORE_ADDR ADDR)
- Store the address ADDR in BUF, in the proper format for a pointer
- of type TYPE in the current architecture. Note that BUF refers to
- a buffer in GDB's memory, not the inferior's.
-
- For example, if the current architecture is the Intel x86, this
- function stores ADDR unmodified as a little-endian integer of the
- appropriate length in BUF. However, if the current architecture
- is the D10V, this function divides ADDR by four if TYPE is a
- pointer to a function, and then stores it in BUF.
-
- If TYPE is not a pointer or reference type, then this function
- will signal an internal error.
-
- -- Function: CORE_ADDR value_as_address (struct value *VAL)
- Assuming that VAL is a pointer, return the address it represents,
- as appropriate for the current architecture.
-
- This function actually works on integral values, as well as
- pointers. For pointers, it performs architecture-specific
- conversions as described above for `extract_typed_address'.
-
- -- Function: CORE_ADDR value_from_pointer (struct type *TYPE,
- CORE_ADDR ADDR)
- Create and return a value representing a pointer of type TYPE to
- the address ADDR, as appropriate for the current architecture.
- This function performs architecture-specific conversions as
- described above for `store_typed_address'.
-
- Here are two functions which architectures can define to indicate the
-relationship between pointers and addresses. These have default
-definitions, appropriate for architectures on which all pointers are
-simple unsigned byte addresses.
-
- -- Function: CORE_ADDR gdbarch_pointer_to_address (struct gdbarch
- *GDBARCH, struct type *TYPE, char *BUF)
- Assume that BUF holds a pointer of type TYPE, in the appropriate
- format for the current architecture. Return the byte address the
- pointer refers to.
-
- This function may safely assume that TYPE is either a pointer or a
- C++ reference type.
-
- -- Function: void gdbarch_address_to_pointer (struct gdbarch *GDBARCH,
- struct type *TYPE, char *BUF, CORE_ADDR ADDR)
- Store in BUF a pointer of type TYPE representing the address ADDR,
- in the appropriate format for the current architecture.
-
- This function may safely assume that TYPE is either a pointer or a
- C++ reference type.
-
- ---------- Footnotes ----------
-
- (1) Some D10V instructions are actually pairs of 16-bit
-sub-instructions. However, since you can't jump into the middle of
-such a pair, code addresses can only refer to full 32 bit instructions,
-which is what matters in this explanation.
-
-\1f
-File: gdbint.info, Node: Address Classes, Next: Register Representation, Prev: Pointers and Addresses, Up: Target Architecture Definition
-
-11.5 Address Classes
-====================
-
-Sometimes information about different kinds of addresses is available
-via the debug information. For example, some programming environments
-define addresses of several different sizes. If the debug information
-distinguishes these kinds of address classes through either the size
-info (e.g, `DW_AT_byte_size' in DWARF 2) or through an explicit address
-class attribute (e.g, `DW_AT_address_class' in DWARF 2), the following
-macros should be defined in order to disambiguate these types within
-GDB as well as provide the added information to a GDB user when
-printing type expressions.
-
- -- Function: int gdbarch_address_class_type_flags (struct gdbarch
- *GDBARCH, int BYTE_SIZE, int DWARF2_ADDR_CLASS)
- Returns the type flags needed to construct a pointer type whose
- size is BYTE_SIZE and whose address class is DWARF2_ADDR_CLASS.
- This function is normally called from within a symbol reader. See
- `dwarf2read.c'.
-
- -- Function: char * gdbarch_address_class_type_flags_to_name (struct
- gdbarch *GDBARCH, int TYPE_FLAGS)
- Given the type flags representing an address class qualifier,
- return its name.
-
- -- Function: int gdbarch_address_class_name_to_type_flags (struct
- gdbarch *GDBARCH, int NAME, int *TYPE_FLAGS_PTR)
- Given an address qualifier name, set the `int' referenced by
- TYPE_FLAGS_PTR to the type flags for that address class qualifier.
-
- Since the need for address classes is rather rare, none of the
-address class functions are defined by default. Predicate functions
-are provided to detect when they are defined.
-
- Consider a hypothetical architecture in which addresses are normally
-32-bits wide, but 16-bit addresses are also supported. Furthermore,
-suppose that the DWARF 2 information for this architecture simply uses
-a `DW_AT_byte_size' value of 2 to indicate the use of one of these
-"short" pointers. The following functions could be defined to
-implement the address class functions:
-
- somearch_address_class_type_flags (int byte_size,
- int dwarf2_addr_class)
- {
- if (byte_size == 2)
- return TYPE_FLAG_ADDRESS_CLASS_1;
- else
- return 0;
- }
-
- static char *
- somearch_address_class_type_flags_to_name (int type_flags)
- {
- if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
- return "short";
- else
- return NULL;
- }
-
- int
- somearch_address_class_name_to_type_flags (char *name,
- int *type_flags_ptr)
- {
- if (strcmp (name, "short") == 0)
- {
- *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
- return 1;
- }
- else
- return 0;
- }
-
- The qualifier `@short' is used in GDB's type expressions to indicate
-the presence of one of these "short" pointers. For example if the
-debug information indicates that `short_ptr_var' is one of these short
-pointers, GDB might show the following behavior:
-
- (gdb) ptype short_ptr_var
- type = int * @short
-
-\1f
-File: gdbint.info, Node: Register Representation, Next: Frame Interpretation, Prev: Address Classes, Up: Target Architecture Definition
-
-11.6 Register Representation
-============================
-
-* Menu:
-
-* Raw and Cooked Registers::
-* Register Architecture Functions & Variables::
-* Register Information Functions::
-* Register and Memory Data::
-* Register Caching::
-
-\1f
-File: gdbint.info, Node: Raw and Cooked Registers, Next: Register Architecture Functions & Variables, Up: Register Representation
-
-11.6.1 Raw and Cooked Registers
--------------------------------
-
-GDB considers registers to be a set with members numbered linearly from
-0 upwards. The first part of that set corresponds to real physical
-registers, the second part to any "pseudo-registers". Pseudo-registers
-have no independent physical existence, but are useful representations
-of information within the architecture. For example the OpenRISC 1000
-architecture has up to 32 general purpose registers, which are
-typically represented as 32-bit (or 64-bit) integers. However the GPRs
-are also used as operands to the floating point operations, and it
-could be convenient to define a set of pseudo-registers, to show the
-GPRs represented as floating point values.
-
- For any architecture, the implementer will decide on a mapping from
-hardware to GDB register numbers. The registers corresponding to real
-hardware are referred to as "raw" registers, the remaining registers are
-"pseudo-registers". The total register set (raw and pseudo) is called
-the "cooked" register set.
-
-\1f
-File: gdbint.info, Node: Register Architecture Functions & Variables, Next: Register Information Functions, Prev: Raw and Cooked Registers, Up: Register Representation
-
-11.6.2 Functions and Variables Specifying the Register Architecture
--------------------------------------------------------------------
-
-These `struct gdbarch' functions and variables specify the number and
-type of registers in the architecture.
-
- -- Architecture Function: CORE_ADDR read_pc (struct regcache *REGCACHE)
-
- -- Architecture Function: void write_pc (struct regcache *REGCACHE,
- CORE_ADDR VAL)
- Read or write the program counter. The default value of both
- functions is `NULL' (no function available). If the program
- counter is just an ordinary register, it can be specified in
- `struct gdbarch' instead (see `pc_regnum' below) and it will be
- read or written using the standard routines to access registers.
- This function need only be specified if the program counter is not
- an ordinary register.
-
- Any register information can be obtained using the supplied
- register cache, REGCACHE. *Note Register Caching: Register
- Caching.
-
-
- -- Architecture Function: void pseudo_register_read (struct gdbarch
- *GDBARCH, struct regcache *REGCACHE, int REGNUM, const
- gdb_byte *BUF)
-
- -- Architecture Function: void pseudo_register_write (struct gdbarch
- *GDBARCH, struct regcache *REGCACHE, int REGNUM, const
- gdb_byte *BUF)
- These functions should be defined if there are any
- pseudo-registers. The default value is `NULL'. REGNUM is the
- number of the register to read or write (which will be a "cooked"
- register number) and BUF is the buffer where the value read will be
- placed, or from which the value to be written will be taken. The
- value in the buffer may be converted to or from a signed or
- unsigned integral value using one of the utility functions (*note
- Using Different Register and Memory Data Representations: Register
- and Memory Data.).
-
- The access should be for the specified architecture, GDBARCH. Any
- register information can be obtained using the supplied register
- cache, REGCACHE. *Note Register Caching: Register Caching.
-
-
- -- Architecture Variable: int sp_regnum
- This specifies the register holding the stack pointer, which may
- be a raw or pseudo-register. It defaults to -1 (not defined), but
- it is an error for it not to be defined.
-
- The value of the stack pointer register can be accessed withing
- GDB as the variable `$sp'.
-
-
- -- Architecture Variable: int pc_regnum
- This specifies the register holding the program counter, which may
- be a raw or pseudo-register. It defaults to -1 (not defined). If
- `pc_regnum' is not defined, then the functions `read_pc' and
- `write_pc' (see above) must be defined.
-
- The value of the program counter (whether defined as a register, or
- through `read_pc' and `write_pc') can be accessed withing GDB as
- the variable `$pc'.
-
-
- -- Architecture Variable: int ps_regnum
- This specifies the register holding the processor status (often
- called the status register), which may be a raw or
- pseudo-register. It defaults to -1 (not defined).
-
- If defined, the value of this register can be accessed withing GDB
- as the variable `$ps'.
-
-
- -- Architecture Variable: int fp0_regnum
- This specifies the first floating point register. It defaults to
- 0. `fp0_regnum' is not needed unless the target offers support
- for floating point.
-
-
-\1f
-File: gdbint.info, Node: Register Information Functions, Next: Register and Memory Data, Prev: Register Architecture Functions & Variables, Up: Register Representation
-
-11.6.3 Functions Giving Register Information
---------------------------------------------
-
-These functions return information about registers.
-
- -- Architecture Function: const char * register_name (struct gdbarch
- *GDBARCH, int REGNUM)
- This function should convert a register number (raw or pseudo) to a
- register name (as a C `const char *'). This is used both to
- determine the name of a register for output and to work out the
- meaning of any register names used as input. The function may
- also return `NULL', to indicate that REGNUM is not a valid
- register.
-
- For example with the OpenRISC 1000, GDB registers 0-31 are the
- General Purpose Registers, register 32 is the program counter and
- register 33 is the supervision register (i.e. the processor status
- register), which map to the strings `"gpr00"' through `"gpr31"',
- `"pc"' and `"sr"' respectively. This means that the GDB command
- `print $gpr5' should print the value of the OR1K general purpose
- register 5(1).
-
- The default value for this function is `NULL', meaning undefined.
- It should always be defined.
-
- The access should be for the specified architecture, GDBARCH.
-
-
- -- Architecture Function: struct type * register_type (struct gdbarch
- *GDBARCH, int REGNUM)
- Given a register number, this function identifies the type of data
- it may be holding, specified as a `struct type'. GDB allows
- creation of arbitrary types, but a number of built in types are
- provided (`builtin_type_void', `builtin_type_int32' etc), together
- with functions to derive types from these.
-
- Typically the program counter will have a type of "pointer to
- function" (it points to code), the frame pointer and stack pointer
- will have types of "pointer to void" (they point to data on the
- stack) and all other integer registers will have a type of 32-bit
- integer or 64-bit integer.
-
- This information guides the formatting when displaying register
- information. The default value is `NULL' meaning no information is
- available to guide formatting when displaying registers.
-
-
- -- Architecture Function: void print_registers_info (struct gdbarch
- *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME, int
- REGNUM, int ALL)
- Define this function to print out one or all of the registers for
- the GDB `info registers' command. The default value is the
- function `default_print_registers_info', which uses the register
- type information (see `register_type' above) to determine how each
- register should be printed. Define a custom version of this
- function for fuller control over how the registers are displayed.
-
- The access should be for the specified architecture, GDBARCH, with
- output to the the file specified by the User Interface Independent
- Output file handle, FILE (*note UI-Independent Output--the
- `ui_out' Functions: UI-Independent Output.).
-
- The registers should show their values in the frame specified by
- FRAME. If REGNUM is -1 and ALL is zero, then all the
- "significant" registers should be shown (the implementer should
- decide which registers are "significant"). Otherwise only the
- value of the register specified by REGNUM should be output. If
- REGNUM is -1 and ALL is non-zero (true), then the value of all
- registers should be shown.
-
- By default `default_print_registers_info' prints one register per
- line, and if ALL is zero omits floating-point registers.
-
-
- -- Architecture Function: void print_float_info (struct gdbarch
- *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
- const char *ARGS)
- Define this function to provide output about the floating point
- unit and registers for the GDB `info float' command respectively.
- The default value is `NULL' (not defined), meaning no information
- will be provided.
-
- The GDBARCH and FILE and FRAME arguments have the same meaning as
- in the `print_registers_info' function above. The string ARGS
- contains any supplementary arguments to the `info float' command.
-
- Define this function if the target supports floating point
- operations.
-
-
- -- Architecture Function: void print_vector_info (struct gdbarch
- *GDBARCH, struct ui_file *FILE, struct frame_info *FRAME,
- const char *ARGS)
- Define this function to provide output about the vector unit and
- registers for the GDB `info vector' command respectively. The
- default value is `NULL' (not defined), meaning no information will
- be provided.
-
- The GDBARCH, FILE and FRAME arguments have the same meaning as in
- the `print_registers_info' function above. The string ARGS
- contains any supplementary arguments to the `info vector' command.
-
- Define this function if the target supports vector operations.
-
-
- -- Architecture Function: int register_reggroup_p (struct gdbarch
- *GDBARCH, int REGNUM, struct reggroup *GROUP)
- GDB groups registers into different categories (general, vector,
- floating point etc). This function, given a register, REGNUM, and
- group, GROUP, returns 1 (true) if the register is in the group and
- 0 (false) otherwise.
-
- The information should be for the specified architecture, GDBARCH
-
- The default value is the function `default_register_reggroup_p'
- which will do a reasonable job based on the type of the register
- (see the function `register_type' above), with groups for general
- purpose registers, floating point registers, vector registers and
- raw (i.e not pseudo) registers.
-
-
- ---------- Footnotes ----------
-
- (1) Historically, GDB always had a concept of a frame pointer
-register, which could be accessed via the GDB variable, `$fp'. That
-concept is now deprecated, recognizing that not all architectures have
-a frame pointer. However if an architecture does have a frame pointer
-register, and defines a register or pseudo-register with the name
-`"fp"', then that register will be used as the value of the `$fp'
-variable.
-
-\1f
-File: gdbint.info, Node: Register and Memory Data, Next: Register Caching, Prev: Register Information Functions, Up: Register Representation
-
-11.6.4 Using Different Register and Memory Data Representations
----------------------------------------------------------------
-
-Some architectures have different representations of data objects,
-depending whether the object is held in a register or memory. For
-example:
-
- * The Alpha architecture can represent 32 bit integer values in
- floating-point registers.
-
- * The x86 architecture supports 80-bit floating-point registers. The
- `long double' data type occupies 96 bits in memory but only 80
- bits when stored in a register.
-
-
- In general, the register representation of a data type is determined
-by the architecture, or GDB's interface to the architecture, while the
-memory representation is determined by the Application Binary Interface.
-
- For almost all data types on almost all architectures, the two
-representations are identical, and no special handling is needed.
-However, they do occasionally differ. An architecture may define the
-following `struct gdbarch' functions to request conversions between the
-register and memory representations of a data type:
-
- -- Architecture Function: int gdbarch_convert_register_p (struct
- gdbarch *GDBARCH, int REG)
- Return non-zero (true) if the representation of a data value
- stored in this register may be different to the representation of
- that same data value when stored in memory. The default value is
- `NULL' (undefined).
-
- If this function is defined and returns non-zero, the `struct
- gdbarch' functions `gdbarch_register_to_value' and
- `gdbarch_value_to_register' (see below) should be used to perform
- any necessary conversion.
-
- If defined, this function should return zero for the register's
- native type, when no conversion is necessary.
-
- -- Architecture Function: void gdbarch_register_to_value (struct
- gdbarch *GDBARCH, int REG, struct type *TYPE, char *FROM,
- char *TO)
- Convert the value of register number REG to a data object of type
- TYPE. The buffer at FROM holds the register's value in raw
- format; the converted value should be placed in the buffer at TO.
-
- _Note:_ `gdbarch_register_to_value' and
- `gdbarch_value_to_register' take their REG and TYPE arguments
- in different orders.
-
- `gdbarch_register_to_value' should only be used with registers for
- which the `gdbarch_convert_register_p' function returns a non-zero
- value.
-
-
- -- Architecture Function: void gdbarch_value_to_register (struct
- gdbarch *GDBARCH, struct type *TYPE, int REG, char *FROM,
- char *TO)
- Convert a data value of type TYPE to register number REG' raw
- format.
-
- _Note:_ `gdbarch_register_to_value' and
- `gdbarch_value_to_register' take their REG and TYPE arguments
- in different orders.
-
- `gdbarch_value_to_register' should only be used with registers for
- which the `gdbarch_convert_register_p' function returns a non-zero
- value.
-
-
-\1f
-File: gdbint.info, Node: Register Caching, Prev: Register and Memory Data, Up: Register Representation
-
-11.6.5 Register Caching
------------------------
-
-Caching of registers is used, so that the target does not need to be
-accessed and reanalyzed multiple times for each register in
-circumstances where the register value cannot have changed.
-
- GDB provides `struct regcache', associated with a particular `struct
-gdbarch' to hold the cached values of the raw registers. A set of
-functions is provided to access both the raw registers (with `raw' in
-their name) and the full set of cooked registers (with `cooked' in
-their name). Functions are provided to ensure the register cache is
-kept synchronized with the values of the actual registers in the target.
-
- Accessing registers through the `struct regcache' routines will
-ensure that the appropriate `struct gdbarch' functions are called when
-necessary to access the underlying target architecture. In general
-users should use the "cooked" functions, since these will map to the
-"raw" functions automatically as appropriate.
-
- The two key functions are `regcache_cooked_read' and
-`regcache_cooked_write' which read or write a register from or to a
-byte buffer (type `gdb_byte *'). For convenience the wrapper functions
-`regcache_cooked_read_signed', `regcache_cooked_read_unsigned',
-`regcache_cooked_write_signed' and `regcache_cooked_write_unsigned' are
-provided, which read or write the value using the buffer and convert to
-or from an integral value as appropriate.
-
-\1f
-File: gdbint.info, Node: Frame Interpretation, Next: Inferior Call Setup, Prev: Register Representation, Up: Target Architecture Definition
-
-11.7 Frame Interpretation
-=========================
-
-* Menu:
-
-* All About Stack Frames::
-* Frame Handling Terminology::
-* Prologue Caches::
-* Functions and Variable to Analyze Frames::
-* Functions to Access Frame Data::
-* Analyzing Stacks---Frame Sniffers::
-
-\1f
-File: gdbint.info, Node: All About Stack Frames, Next: Frame Handling Terminology, Up: Frame Interpretation
-
-11.7.1 All About Stack Frames
------------------------------
-
-GDB needs to understand the stack on which local (automatic) variables
-are stored. The area of the stack containing all the local variables
-for a function invocation is known as the "stack frame" for that
-function (or colloquially just as the "frame"). In turn the function
-that called the function will have its stack frame, and so on back
-through the chain of functions that have been called.
-
- Almost all architectures have one register dedicated to point to the
-end of the stack (the "stack pointer"). Many have a second register
-which points to the start of the currently active stack frame (the
-"frame pointer"). The specific arrangements for an architecture are a
-key part of the ABI.
-
- A diagram helps to explain this. Here is a simple program to compute
-factorials:
-
- #include <stdio.h>
- int fact (int n)
- {
- if (0 == n)
- {
- return 1;
- }
- else
- {
- return n * fact (n - 1);
- }
- }
-
- main ()
- {
- int i;
-
- for (i = 0; i < 10; i++)
- {
- int f = fact (i);
- printf ("%d! = %d\n", i, f);
- }
- }
-
- Consider the state of the stack when the code reaches line 6 after
-the main program has called `fact (3)'. The chain of function calls
-will be `main ()', `fact (3)', `fact (2)', `fact (1)' and `fact (0)'.
-
- In this illustration the stack is falling (as used for example by the
-OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack
-(lowest address) and the frame pointer (FP) is at the highest address
-in the current stack frame. The following diagram shows how the stack
-looks.
-
- ^ ->| |
-Frame | | | |
-Number - | | |============| int fact (int n)
- | | | | i = 3 | {
- | | | |------------| if (0 == n) {
- | | | | f = ? | return 1; <-------- PC
- #4 main() < | | |------------| }
- | | | | | else {
- | | -+->|------------| ---> return n * fact (n - 1);
- | -+-+--+-----o | | }
- = | | |============| | }
- | | | | n = 3 | |
- | | | |------------| | main ()
- #3 fact (3) < | | | o---------+- {
- | -+-+->|------------| | | int i;
- | | | --+-----o | | |
- = | | |============| | | for (i = 0; i < 10; i++) {
- | | | | n = 2 | | -> int f = fact (i);
- | | | |------------| | printf ("%d! = %d\n", i , f);
- #2 fact (2) < | | | o------+--| }
- | | | ->|------------| | }
- | | -+--+-----o | |
- = | | |============| |
- | | | | n = 1 | |
- | | | |------------| |
- #1 fact (1) < | | | o------+--|
- | | | |------------| |
- | ---|--+-----o |<-+------- FP
- = | |============| | |
- | | | n = 0 | | |
- | | |------------| | |
- #0 fact (0) < | | o--------- |
- | | |------------| |
- | --+-----o |<--------- SP |
- = |============| |
- | | Red Zone | v
- | \/\/\/\/\/\/\/ Direction of
- #-1 < \/\/\/\/\/\/\/ stack growth
- | | |
-
-In each stack frame, offset 0 from the stack pointer is the frame
-pointer of the previous frame and offset 4 (this is illustrating a
-32-bit architecture) from the stack pointer is the return address.
-Local variables are indexed from the frame pointer, with negative
-indexes. In the function `fact', offset -4 from the frame pointer is
-the argument N. In the `main' function, offset -4 from the frame
-pointer is the local variable I and offset -8 from the frame pointer is
-the local variable F(1).
-
- It is very easy to get confused when examining stacks. GDB has
-terminology it uses rigorously throughout. The stack frame of the
-function currently executing, or where execution stopped is numbered
-zero. In this example frame #0 is the stack frame of the call to
-`fact (0)'. The stack frame of its calling function (`fact (1)' in
-this case) is numbered #1 and so on back through the chain of calls.
-
- The main GDB data structure describing frames is
-`struct frame_info'. It is not used directly, but only via its
-accessor functions. `frame_info' includes information about the
-registers in the frame and a pointer to the code of the function with
-which the frame is associated. The entire stack is represented as a
-linked list of `frame_info' structs.
-
- ---------- Footnotes ----------
-
- (1) This is a simplified example for illustrative purposes only.
-Good optimizing compilers would not put anything on the stack for such
-simple functions. Indeed they might eliminate the recursion and use of
-the stack entirely!
-
-\1f
-File: gdbint.info, Node: Frame Handling Terminology, Next: Prologue Caches, Prev: All About Stack Frames, Up: Frame Interpretation
-
-11.7.2 Frame Handling Terminology
----------------------------------
-
-It is easy to get confused when referencing stack frames. GDB uses
-some precise terminology.
-
- * "THIS" frame is the frame currently under consideration.
-
- * The "NEXT" frame, also sometimes called the inner or newer frame
- is the frame of the function called by the function of THIS frame.
-
- * The "PREVIOUS" frame, also sometimes called the outer or older
- frame is the frame of the function which called the function of
- THIS frame.
-
-
- So in the example in the previous section (*note All About Stack
-Frames: All About Stack Frames.), if THIS frame is #3 (the call to
-`fact (3)'), the NEXT frame is frame #2 (the call to `fact (2)') and
-the PREVIOUS frame is frame #4 (the call to `main ()').
-
- The "innermost" frame is the frame of the current executing
-function, or where the program stopped, in this example, in the middle
-of the call to `fact (0))'. It is always numbered frame #0.
-
- The "base" of a frame is the address immediately before the start of
-the NEXT frame. For a stack which grows down in memory (a "falling"
-stack) this will be the lowest address and for a stack which grows up
-in memory (a "rising" stack) this will be the highest address in the
-frame.
-
- GDB functions to analyze the stack are typically given a pointer to
-the NEXT frame to determine information about THIS frame. Information
-about THIS frame includes data on where the registers of the PREVIOUS
-frame are stored in this stack frame. In this example the frame
-pointer of the PREVIOUS frame is stored at offset 0 from the stack
-pointer of THIS frame.
-
- The process whereby a function is given a pointer to the NEXT frame
-to work out information about THIS frame is referred to as "unwinding".
-The GDB functions involved in this typically include unwind in their
-name.
-
- The process of analyzing a target to determine the information that
-should go in struct frame_info is called "sniffing". The functions
-that carry this out are called sniffers and typically include sniffer
-in their name. More than one sniffer may be required to extract all
-the information for a particular frame.
-
- Because so many functions work using the NEXT frame, there is an
-issue about addressing the innermost frame--it has no NEXT frame. To
-solve this GDB creates a dummy frame #-1, known as the "sentinel" frame.
-
-\1f
-File: gdbint.info, Node: Prologue Caches, Next: Functions and Variable to Analyze Frames, Prev: Frame Handling Terminology, Up: Frame Interpretation
-
-11.7.3 Prologue Caches
-----------------------
-
-All the frame sniffing functions typically examine the code at the
-start of the corresponding function, to determine the state of
-registers. The ABI will save old values and set new values of key
-registers at the start of each function in what is known as the
-function "prologue".
-
- For any particular stack frame this data does not change, so all the
-standard unwinding functions, in addition to receiving a pointer to the
-NEXT frame as their first argument, receive a pointer to a "prologue
-cache" as their second argument. This can be used to store values
-associated with a particular frame, for reuse on subsequent calls
-involving the same frame.
-
- It is up to the user to define the structure used (it is a `void *'
-pointer) and arrange allocation and deallocation of storage. However
-for general use, GDB provides `struct trad_frame_cache', with a set of
-accessor routines. This structure holds the stack and code address of
-THIS frame, the base address of the frame, a pointer to the struct
-`frame_info' for the NEXT frame and details of where the registers of
-the PREVIOUS frame may be found in THIS frame.
-
- Typically the first time any sniffer function is called with NEXT
-frame, the prologue sniffer for THIS frame will be `NULL'. The sniffer
-will analyze the frame, allocate a prologue cache structure and
-populate it. Subsequent calls using the same NEXT frame will pass in
-this prologue cache, so the data can be returned with no additional
-analysis.
-
-\1f
-File: gdbint.info, Node: Functions and Variable to Analyze Frames, Next: Functions to Access Frame Data, Prev: Prologue Caches, Up: Frame Interpretation
-
-11.7.4 Functions and Variable to Analyze Frames
------------------------------------------------
-
-These struct `gdbarch' functions and variable should be defined to
-provide analysis of the stack frame and allow it to be adjusted as
-required.
-
- -- Architecture Function: CORE_ADDR skip_prologue (struct gdbarch
- *GDBARCH, CORE_ADDR PC)
- The prologue of a function is the code at the beginning of the
- function which sets up the stack frame, saves the return address
- etc. The code representing the behavior of the function starts
- after the prologue.
-
- This function skips past the prologue of a function if the program
- counter, PC, is within the prologue of a function. The result is
- the program counter immediately after the prologue. With modern
- optimizing compilers, this may be a far from trivial exercise.
- However the required information may be within the binary as
- DWARF2 debugging information, making the job much easier.
-
- The default value is `NULL' (not defined). This function should
- always be provided, but can take advantage of DWARF2 debugging
- information, if that is available.
-
-
- -- Architecture Function: int inner_than (CORE_ADDR LHS, CORE_ADDR RHS)
- Given two frame or stack pointers, return non-zero (true) if the
- first represents the "inner" stack frame and 0 (false) otherwise.
- This is used to determine whether the target has a stack which
- grows up in memory (rising stack) or grows down in memory (falling
- stack). *Note All About Stack Frames: All About Stack Frames, for
- an explanation of "inner" frames.
-
- The default value of this function is `NULL' and it should always
- be defined. However for almost all architectures one of the
- built-in functions can be used: `core_addr_lessthan' (for stacks
- growing down in memory) or `core_addr_greaterthan' (for stacks
- growing up in memory).
-
-
- -- Architecture Function: CORE_ADDR frame_align (struct gdbarch
- *GDBARCH, CORE_ADDR ADDRESS)
- The architecture may have constraints on how its frames are
- aligned. For example the OpenRISC 1000 ABI requires stack frames
- to be double-word aligned, but 32-bit versions of the architecture
- allocate single-word values to the stack. Thus extra padding may
- be needed at the end of a stack frame.
-
- Given a proposed address for the stack pointer, this function
- returns a suitably aligned address (by expanding the stack frame).
-
- The default value is `NULL' (undefined). This function should be
- defined for any architecture where it is possible the stack could
- become misaligned. The utility functions `align_down' (for falling
- stacks) and `align_up' (for rising stacks) will facilitate the
- implementation of this function.
-
-
- -- Architecture Variable: int frame_red_zone_size
- Some ABIs reserve space beyond the end of the stack for use by leaf
- functions without prologue or epilogue or by exception handlers
- (for example the OpenRISC 1000).
-
- This is known as a "red zone" (AMD terminology). The AMD64 (nee
- x86-64) ABI documentation refers to the "red zone" when describing
- this scratch area.
-
- The default value is 0. Set this field if the architecture has
- such a red zone. The value must be aligned as required by the ABI
- (see `frame_align' above for an explanation of stack frame
- alignment).
-
-
-\1f
-File: gdbint.info, Node: Functions to Access Frame Data, Next: Analyzing Stacks---Frame Sniffers, Prev: Functions and Variable to Analyze Frames, Up: Frame Interpretation
-
-11.7.5 Functions to Access Frame Data
--------------------------------------
-
-These functions provide access to key registers and arguments in the
-stack frame.
-
- -- Architecture Function: CORE_ADDR unwind_pc (struct gdbarch
- *GDBARCH, struct frame_info *NEXT_FRAME)
- This function is given a pointer to the NEXT stack frame (*note
- All About Stack Frames: All About Stack Frames, for how frames are
- represented) and returns the value of the program counter in the
- PREVIOUS frame (i.e. the frame of the function that called THIS
- one). This is commonly referred to as the "return address".
-
- The implementation, which must be frame agnostic (work with any
- frame), is typically no more than:
-
- ULONGEST pc;
- pc = frame_unwind_register_unsigned (next_frame, ARCH_PC_REGNUM);
- return gdbarch_addr_bits_remove (gdbarch, pc);
-
-
- -- Architecture Function: CORE_ADDR unwind_sp (struct gdbarch
- *GDBARCH, struct frame_info *NEXT_FRAME)
- This function is given a pointer to the NEXT stack frame (*note
- All About Stack Frames: All About Stack Frames. for how frames are
- represented) and returns the value of the stack pointer in the
- PREVIOUS frame (i.e. the frame of the function that called THIS
- one).
-
- The implementation, which must be frame agnostic (work with any
- frame), is typically no more than:
-
- ULONGEST sp;
- sp = frame_unwind_register_unsigned (next_frame, ARCH_SP_REGNUM);
- return gdbarch_addr_bits_remove (gdbarch, sp);
-
-
- -- Architecture Function: int frame_num_args (struct gdbarch *GDBARCH,
- struct frame_info *THIS_FRAME)
- This function is given a pointer to THIS stack frame (*note All
- About Stack Frames: All About Stack Frames. for how frames are
- represented), and returns the number of arguments that are being
- passed, or -1 if not known.
-
- The default value is `NULL' (undefined), in which case the number
- of arguments passed on any stack frame is always unknown. For many
- architectures this will be a suitable default.
-
-
-\1f
-File: gdbint.info, Node: Analyzing Stacks---Frame Sniffers, Prev: Functions to Access Frame Data, Up: Frame Interpretation
-
-11.7.6 Analyzing Stacks--Frame Sniffers
----------------------------------------
-
-When a program stops, GDB needs to construct the chain of struct
-`frame_info' representing the state of the stack using appropriate
-"sniffers".
-
- Each architecture requires appropriate sniffers, but they do not form
-entries in `struct gdbarch', since more than one sniffer may be
-required and a sniffer may be suitable for more than one
-`struct gdbarch'. Instead sniffers are associated with architectures
-using the following functions.
-
- * `frame_unwind_append_sniffer' is used to add a new sniffer to
- analyze THIS frame when given a pointer to the NEXT frame.
-
- * `frame_base_append_sniffer' is used to add a new sniffer which can
- determine information about the base of a stack frame.
-
- * `frame_base_set_default' is used to specify the default base
- sniffer.
-
-
- These functions all take a reference to `struct gdbarch', so they
-are associated with a specific architecture. They are usually called
-in the `gdbarch' initialization function, after the `gdbarch' struct
-has been set up. Unless a default has been set, the most recently
-appended sniffer will be tried first.
-
- The main frame unwinding sniffer (as set by
-`frame_unwind_append_sniffer)' returns a structure specifying a set of
-sniffing functions:
-
- struct frame_unwind
- {
- enum frame_type type;
- frame_this_id_ftype *this_id;
- frame_prev_register_ftype *prev_register;
- const struct frame_data *unwind_data;
- frame_sniffer_ftype *sniffer;
- frame_prev_pc_ftype *prev_pc;
- frame_dealloc_cache_ftype *dealloc_cache;
- };
-
- The `type' field indicates the type of frame this sniffer can
-handle: normal, dummy (*note Functions Creating Dummy Frames: Functions
-Creating Dummy Frames.), signal handler or sentinel. Signal handlers
-sometimes have their own simplified stack structure for efficiency, so
-may need their own handlers.
-
- The `unwind_data' field holds additional information which may be
-relevant to particular types of frame. For example it may hold
-additional information for signal handler frames.
-
- The remaining fields define functions that yield different types of
-information when given a pointer to the NEXT stack frame. Not all
-functions need be provided. If an entry is `NULL', the next sniffer
-will be tried instead.
-
- * `this_id' determines the stack pointer and function (code entry
- point) for THIS stack frame.
-
- * `prev_register' determines where the values of registers for the
- PREVIOUS stack frame are stored in THIS stack frame.
-
- * `sniffer' takes a look at THIS frame's registers to determine if
- this is the appropriate unwinder.
-
- * `prev_pc' determines the program counter for THIS frame. Only
- needed if the program counter is not an ordinary register (*note
- Functions and Variables Specifying the Register Architecture:
- Register Architecture Functions & Variables.).
-
- * `dealloc_cache' frees any additional memory associated with the
- prologue cache for this frame (*note Prologue Caches: Prologue
- Caches.).
-
-
- In general it is only the `this_id' and `prev_register' fields that
-need be defined for custom sniffers.
-
- The frame base sniffer is much simpler. It is a
-`struct frame_base', which refers to the corresponding `frame_unwind'
-struct and whose fields refer to functions yielding various addresses
-within the frame.
-
- struct frame_base
- {
- const struct frame_unwind *unwind;
- frame_this_base_ftype *this_base;
- frame_this_locals_ftype *this_locals;
- frame_this_args_ftype *this_args;
- };
-
- All the functions referred to take a pointer to the NEXT frame as
-argument. The function referred to by `this_base' returns the base
-address of THIS frame, the function referred to by `this_locals'
-returns the base address of local variables in THIS frame and the
-function referred to by `this_args' returns the base address of the
-function arguments in this frame.
-
- As described above, the base address of a frame is the address
-immediately before the start of the NEXT frame. For a falling stack,
-this is the lowest address in the frame and for a rising stack it is
-the highest address in the frame. For most architectures the same
-address is also the base address for local variables and arguments, in
-which case the same function can be used for all three entries(1).
-
- ---------- Footnotes ----------
-
- (1) It is worth noting that if it cannot be determined in any other
-way (for example by there being a register with the name `"fp"'), then
-the result of the `this_base' function will be used as the value of the
-frame pointer variable `$fp' in GDB. This is very often not correct
-(for example with the OpenRISC 1000, this value is the stack pointer,
-`$sp'). In this case a register (raw or pseudo) with the name `"fp"'
-should be defined. It will be used in preference as the value of `$fp'.
-
-\1f
-File: gdbint.info, Node: Inferior Call Setup, Next: Adding support for debugging core files, Prev: Frame Interpretation, Up: Target Architecture Definition
-
-11.8 Inferior Call Setup
-========================
-
-* Menu:
-
-* About Dummy Frames::
-* Functions Creating Dummy Frames::
-
-\1f
-File: gdbint.info, Node: About Dummy Frames, Next: Functions Creating Dummy Frames, Up: Inferior Call Setup
-
-11.8.1 About Dummy Frames
--------------------------
-
-GDB can call functions in the target code (for example by using the
-`call' or `print' commands). These functions may be breakpointed, and
-it is essential that if a function does hit a breakpoint, commands like
-`backtrace' work correctly.
-
- This is achieved by making the stack look as though the function had
-been called from the point where GDB had previously stopped. This
-requires that GDB can set up stack frames appropriate for such function
-calls.
-
-\1f
-File: gdbint.info, Node: Functions Creating Dummy Frames, Prev: About Dummy Frames, Up: Inferior Call Setup
-
-11.8.2 Functions Creating Dummy Frames
---------------------------------------
-
-The following functions provide the functionality to set up such
-"dummy" stack frames.
-
- -- Architecture Function: CORE_ADDR push_dummy_call (struct gdbarch
- *GDBARCH, struct value *FUNCTION, struct regcache *REGCACHE,
- CORE_ADDR BP_ADDR, int NARGS, struct value **ARGS, CORE_ADDR
- SP, int STRUCT_RETURN, CORE_ADDR STRUCT_ADDR)
- This function sets up a dummy stack frame for the function about
- to be called. `push_dummy_call' is given the arguments to be
- passed and must copy them into registers or push them on to the
- stack as appropriate for the ABI.
-
- FUNCTION is a pointer to the function that will be called and
- REGCACHE the register cache from which values should be obtained.
- BP_ADDR is the address to which the function should return (which
- is breakpointed, so GDB can regain control, hence the name).
- NARGS is the number of arguments to pass and ARGS an array
- containing the argument values. STRUCT_RETURN is non-zero (true)
- if the function returns a structure, and if so STRUCT_ADDR is the
- address in which the structure should be returned.
-
- After calling this function, GDB will pass control to the target
- at the address of the function, which will find the stack and
- registers set up just as expected.
-
- The default value of this function is `NULL' (undefined). If the
- function is not defined, then GDB will not allow the user to call
- functions within the target being debugged.
-
-
- -- Architecture Function: struct frame_id unwind_dummy_id (struct
- gdbarch *GDBARCH, struct frame_info *NEXT_FRAME)
- This is the inverse of `push_dummy_call' which restores the stack
- pointer and program counter after a call to evaluate a function
- using a dummy stack frame. The result is a `struct frame_id',
- which contains the value of the stack pointer and program counter
- to be used.
-
- The NEXT frame pointer is provided as argument, NEXT_FRAME. THIS
- frame is the frame of the dummy function, which can be unwound, to
- yield the required stack pointer and program counter from the
- PREVIOUS frame.
-
- The default value is `NULL' (undefined). If `push_dummy_call' is
- defined, then this function should also be defined.
-
-
- -- Architecture Function: CORE_ADDR push_dummy_code (struct gdbarch
- *GDBARCH, CORE_ADDR SP, CORE_ADDR FUNADDR, struct value
- **ARGS, int NARGS, struct type *VALUE_TYPE, CORE_ADDR
- *REAL_PC, CORE_ADDR *BP_ADDR, struct regcache *REGCACHE)
- If this function is not defined (its default value is `NULL'), a
- dummy call will use the entry point of the currently loaded code
- on the target as its return address. A temporary breakpoint will
- be set there, so the location must be writable and have room for a
- breakpoint.
-
- It is possible that this default is not suitable. It might not be
- writable (in ROM possibly), or the ABI might require code to be
- executed on return from a call to unwind the stack before the
- breakpoint is encountered.
-
- If either of these is the case, then push_dummy_code should be
- defined to push an instruction sequence onto the end of the stack
- to which the dummy call should return.
-
- The arguments are essentially the same as those to
- `push_dummy_call'. However the function is provided with the type
- of the function result, VALUE_TYPE, BP_ADDR is used to return a
- value (the address at which the breakpoint instruction should be
- inserted) and REAL PC is used to specify the resume address when
- starting the call sequence. The function should return the
- updated innermost stack address.
-
- _Note:_ This does require that code in the stack can be
- executed. Some Harvard architectures may not allow this.
-
-
-\1f
-File: gdbint.info, Node: Adding support for debugging core files, Next: Defining Other Architecture Features, Prev: Inferior Call Setup, Up: Target Architecture Definition
-
-11.9 Adding support for debugging core files
-============================================
-
-The prerequisite for adding core file support in GDB is to have core
-file support in BFD.
-
- Once BFD support is available, writing the apropriate
-`regset_from_core_section' architecture function should be all that is
-needed in order to add support for core files in GDB.
-
-\1f
-File: gdbint.info, Node: Defining Other Architecture Features, Next: Adding a New Target, Prev: Adding support for debugging core files, Up: Target Architecture Definition
-
-11.10 Defining Other Architecture Features
-==========================================
-
-This section describes other functions and values in `gdbarch',
-together with some useful macros, that you can use to define the target
-architecture.
-
-`CORE_ADDR gdbarch_addr_bits_remove (GDBARCH, ADDR)'
- If a raw machine instruction address includes any bits that are not
- really part of the address, then this function is used to zero
- those bits in ADDR. This is only used for addresses of
- instructions, and even then not in all contexts.
-
- For example, the two low-order bits of the PC on the
- Hewlett-Packard PA 2.0 architecture contain the privilege level of
- the corresponding instruction. Since instructions must always be
- aligned on four-byte boundaries, the processor masks out these
- bits to generate the actual address of the instruction.
- `gdbarch_addr_bits_remove' would then for example look like that:
- arch_addr_bits_remove (CORE_ADDR addr)
- {
- return (addr &= ~0x3);
- }
-
-`int address_class_name_to_type_flags (GDBARCH, NAME, TYPE_FLAGS_PTR)'
- If NAME is a valid address class qualifier name, set the `int'
- referenced by TYPE_FLAGS_PTR to the mask representing the qualifier
- and return 1. If NAME is not a valid address class qualifier name,
- return 0.
-
- The value for TYPE_FLAGS_PTR should be one of
- `TYPE_FLAG_ADDRESS_CLASS_1', `TYPE_FLAG_ADDRESS_CLASS_2', or
- possibly some combination of these values or'd together. *Note
- Address Classes: Target Architecture Definition.
-
-`int address_class_name_to_type_flags_p (GDBARCH)'
- Predicate which indicates whether
- `address_class_name_to_type_flags' has been defined.
-
-`int gdbarch_address_class_type_flags (GDBARCH, BYTE_SIZE, DWARF2_ADDR_CLASS)'
- Given a pointers byte size (as described by the debug information)
- and the possible `DW_AT_address_class' value, return the type flags
- used by GDB to represent this address class. The value returned
- should be one of `TYPE_FLAG_ADDRESS_CLASS_1',
- `TYPE_FLAG_ADDRESS_CLASS_2', or possibly some combination of these
- values or'd together. *Note Address Classes: Target Architecture
- Definition.
-
-`int gdbarch_address_class_type_flags_p (GDBARCH)'
- Predicate which indicates whether
- `gdbarch_address_class_type_flags_p' has been defined.
-
-`const char *gdbarch_address_class_type_flags_to_name (GDBARCH, TYPE_FLAGS)'
- Return the name of the address class qualifier associated with the
- type flags given by TYPE_FLAGS.
-
-`int gdbarch_address_class_type_flags_to_name_p (GDBARCH)'
- Predicate which indicates whether
- `gdbarch_address_class_type_flags_to_name' has been defined.
- *Note Address Classes: Target Architecture Definition.
-
-`void gdbarch_address_to_pointer (GDBARCH, TYPE, BUF, ADDR)'
- Store in BUF a pointer of type TYPE representing the address ADDR,
- in the appropriate format for the current architecture. This
- function may safely assume that TYPE is either a pointer or a C++
- reference type. *Note Pointers Are Not Always Addresses: Target
- Architecture Definition.
-
-`int gdbarch_believe_pcc_promotion (GDBARCH)'
- Used to notify if the compiler promotes a `short' or `char'
- parameter to an `int', but still reports the parameter as its
- original type, rather than the promoted type.
-
-`gdbarch_bits_big_endian (GDBARCH)'
- This is used if the numbering of bits in the targets does *not*
- match the endianism of the target byte order. A value of 1 means
- that the bits are numbered in a big-endian bit order, 0 means
- little-endian.
-
-`set_gdbarch_bits_big_endian (GDBARCH, BITS_BIG_ENDIAN)'
- Calling set_gdbarch_bits_big_endian with a value of 1 indicates
- that the bits in the target are numbered in a big-endian bit
- order, 0 indicates little-endian.
-
-`BREAKPOINT'
- This is the character array initializer for the bit pattern to put
- into memory where a breakpoint is set. Although it's common to
- use a trap instruction for a breakpoint, it's not required; for
- instance, the bit pattern could be an invalid instruction. The
- breakpoint must be no longer than the shortest instruction of the
- architecture.
-
- `BREAKPOINT' has been deprecated in favor of
- `gdbarch_breakpoint_from_pc'.
-
-`BIG_BREAKPOINT'
-`LITTLE_BREAKPOINT'
- Similar to BREAKPOINT, but used for bi-endian targets.
-
- `BIG_BREAKPOINT' and `LITTLE_BREAKPOINT' have been deprecated in
- favor of `gdbarch_breakpoint_from_pc'.
-
-`const gdb_byte *gdbarch_breakpoint_from_pc (GDBARCH, PCPTR, LENPTR)'
- Use the program counter to determine the contents and size of a
- breakpoint instruction. It returns a pointer to a static string
- of bytes that encode a breakpoint instruction, stores the length
- of the string to `*LENPTR', and adjusts the program counter (if
- necessary) to point to the actual memory location where the
- breakpoint should be inserted. May return `NULL' to indicate that
- software breakpoints are not supported.
-
- Although it is common to use a trap instruction for a breakpoint,
- it's not required; for instance, the bit pattern could be an
- invalid instruction. The breakpoint must be no longer than the
- shortest instruction of the architecture.
-
- Provided breakpoint bytes can be also used by
- `bp_loc_is_permanent' to detect permanent breakpoints.
- `gdbarch_breakpoint_from_pc' should return an unchanged memory
- copy if it was called for a location with permanent breakpoint as
- some architectures use breakpoint instructions containing
- arbitrary parameter value.
-
- Replaces all the other BREAKPOINT macros.
-
-`int gdbarch_memory_insert_breakpoint (GDBARCH, BP_TGT)'
-`gdbarch_memory_remove_breakpoint (GDBARCH, BP_TGT)'
- Insert or remove memory based breakpoints. Reasonable defaults
- (`default_memory_insert_breakpoint' and
- `default_memory_remove_breakpoint' respectively) have been
- provided so that it is not necessary to set these for most
- architectures. Architectures which may want to set
- `gdbarch_memory_insert_breakpoint' and
- `gdbarch_memory_remove_breakpoint' will likely have instructions
- that are oddly sized or are not stored in a conventional manner.
-
- It may also be desirable (from an efficiency standpoint) to define
- custom breakpoint insertion and removal routines if
- `gdbarch_breakpoint_from_pc' needs to read the target's memory for
- some reason.
-
-`CORE_ADDR gdbarch_adjust_breakpoint_address (GDBARCH, BPADDR)'
- Given an address at which a breakpoint is desired, return a
- breakpoint address adjusted to account for architectural
- constraints on breakpoint placement. This method is not needed by
- most targets.
-
- The FR-V target (see `frv-tdep.c') requires this method. The FR-V
- is a VLIW architecture in which a number of RISC-like instructions
- are grouped (packed) together into an aggregate instruction or
- instruction bundle. When the processor executes one of these
- bundles, the component instructions are executed in parallel.
-
- In the course of optimization, the compiler may group instructions
- from distinct source statements into the same bundle. The line
- number information associated with one of the latter statements
- will likely refer to some instruction other than the first one in
- the bundle. So, if the user attempts to place a breakpoint on one
- of these latter statements, GDB must be careful to _not_ place the
- break instruction on any instruction other than the first one in
- the bundle. (Remember though that the instructions within a
- bundle execute in parallel, so the _first_ instruction is the
- instruction at the lowest address and has nothing to do with
- execution order.)
-
- The FR-V's `gdbarch_adjust_breakpoint_address' method will adjust a
- breakpoint's address by scanning backwards for the beginning of
- the bundle, returning the address of the bundle.
-
- Since the adjustment of a breakpoint may significantly alter a
- user's expectation, GDB prints a warning when an adjusted
- breakpoint is initially set and each time that that breakpoint is
- hit.
-
-`int gdbarch_call_dummy_location (GDBARCH)'
- See the file `inferior.h'.
-
- This method has been replaced by `gdbarch_push_dummy_code' (*note
- gdbarch_push_dummy_code::).
-
-`int gdbarch_cannot_fetch_register (GDBARCH, REGUM)'
- This function should return nonzero if REGNO cannot be fetched
- from an inferior process.
-
-`int gdbarch_cannot_store_register (GDBARCH, REGNUM)'
- This function should return nonzero if REGNO should not be written
- to the target. This is often the case for program counters,
- status words, and other special registers. This function returns
- 0 as default so that GDB will assume that all registers may be
- written.
-
-`int gdbarch_convert_register_p (GDBARCH, REGNUM, struct type *TYPE)'
- Return non-zero if register REGNUM represents data values of type
- TYPE in a non-standard form. *Note Using Different Register and
- Memory Data Representations: Target Architecture Definition.
-
-`int gdbarch_fp0_regnum (GDBARCH)'
- This function returns the number of the first floating point
- register, if the machine has such registers. Otherwise, it
- returns -1.
-
-`CORE_ADDR gdbarch_decr_pc_after_break (GDBARCH)'
- This function shall return the amount by which to decrement the PC
- after the program encounters a breakpoint. This is often the
- number of bytes in `BREAKPOINT', though not always. For most
- targets this value will be 0.
-
-`DISABLE_UNSETTABLE_BREAK (ADDR)'
- If defined, this should evaluate to 1 if ADDR is in a shared
- library in which breakpoints cannot be set and so should be
- disabled.
-
-`int gdbarch_dwarf2_reg_to_regnum (GDBARCH, DWARF2_REGNR)'
- Convert DWARF2 register number DWARF2_REGNR into GDB regnum. If
- not defined, no conversion will be performed.
-
-`int gdbarch_ecoff_reg_to_regnum (GDBARCH, ECOFF_REGNR)'
- Convert ECOFF register number ECOFF_REGNR into GDB regnum. If
- not defined, no conversion will be performed.
-
-`GCC_COMPILED_FLAG_SYMBOL'
-`GCC2_COMPILED_FLAG_SYMBOL'
- If defined, these are the names of the symbols that GDB will look
- for to detect that GCC compiled the file. The default symbols are
- `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently
- only defined for the Delta 68.)
-
-`gdbarch_get_longjmp_target'
- This function determines the target PC address that `longjmp' will
- jump to, assuming that we have just stopped at a `longjmp'
- breakpoint. It takes a `CORE_ADDR *' as argument, and stores the
- target PC value through this pointer. It examines the current
- state of the machine as needed, typically by using a
- manually-determined offset into the `jmp_buf'. (While we might
- like to get the offset from the target's `jmpbuf.h', that header
- file cannot be assumed to be available when building a
- cross-debugger.)
-
-`DEPRECATED_IBM6000_TARGET'
- Shows that we are configured for an IBM RS/6000 system. This
- conditional should be eliminated (FIXME) and replaced by
- feature-specific macros. It was introduced in haste and we are
- repenting at leisure.
-
-`I386_USE_GENERIC_WATCHPOINTS'
- An x86-based target can define this to use the generic x86
- watchpoint support; see *note I386_USE_GENERIC_WATCHPOINTS:
- Algorithms.
-
-`gdbarch_in_function_epilogue_p (GDBARCH, ADDR)'
- Returns non-zero if the given ADDR is in the epilogue of a
- function. The epilogue of a function is defined as the part of a
- function where the stack frame of the function already has been
- destroyed up to the final `return from function call' instruction.
-
-`int gdbarch_in_solib_return_trampoline (GDBARCH, PC, NAME)'
- Define this function to return nonzero if the program is stopped
- in the trampoline that returns from a shared library.
-
-`target_so_ops.in_dynsym_resolve_code (PC)'
- Define this to return nonzero if the program is stopped in the
- dynamic linker.
-
-`SKIP_SOLIB_RESOLVER (PC)'
- Define this to evaluate to the (nonzero) address at which execution
- should continue to get past the dynamic linker's symbol resolution
- function. A zero value indicates that it is not important or
- necessary to set a breakpoint to get through the dynamic linker
- and that single stepping will suffice.
-
-`CORE_ADDR gdbarch_integer_to_address (GDBARCH, TYPE, BUF)'
- Define this when the architecture needs to handle non-pointer to
- address conversions specially. Converts that value to an address
- according to the current architectures conventions.
-
- _Pragmatics: When the user copies a well defined expression from
- their source code and passes it, as a parameter, to GDB's `print'
- command, they should get the same value as would have been
- computed by the target program. Any deviation from this rule can
- cause major confusion and annoyance, and needs to be justified
- carefully. In other words, GDB doesn't really have the freedom to
- do these conversions in clever and useful ways. It has, however,
- been pointed out that users aren't complaining about how GDB casts
- integers to pointers; they are complaining that they can't take an
- address from a disassembly listing and give it to `x/i'. Adding
- an architecture method like `gdbarch_integer_to_address' certainly
- makes it possible for GDB to "get it right" in all circumstances._
-
- *Note Pointers Are Not Always Addresses: Target Architecture
- Definition.
-
-`CORE_ADDR gdbarch_pointer_to_address (GDBARCH, TYPE, BUF)'
- Assume that BUF holds a pointer of type TYPE, in the appropriate
- format for the current architecture. Return the byte address the
- pointer refers to. *Note Pointers Are Not Always Addresses:
- Target Architecture Definition.
-
-`void gdbarch_register_to_value(GDBARCH, FRAME, REGNUM, TYPE, FUR)'
- Convert the raw contents of register REGNUM into a value of type
- TYPE. *Note Using Different Register and Memory Data
- Representations: Target Architecture Definition.
-
-`REGISTER_CONVERT_TO_VIRTUAL(REG, TYPE, FROM, TO)'
- Convert the value of register REG from its raw form to its virtual
- form. *Note Raw and Virtual Register Representations: Target
- Architecture Definition.
-
-`REGISTER_CONVERT_TO_RAW(TYPE, REG, FROM, TO)'
- Convert the value of register REG from its virtual form to its raw
- form. *Note Raw and Virtual Register Representations: Target
- Architecture Definition.
-
-`const struct regset *regset_from_core_section (struct gdbarch * GDBARCH, const char * SECT_NAME, size_t SECT_SIZE)'
- Return the appropriate register set for a core file section with
- name SECT_NAME and size SECT_SIZE.
-
-`SOFTWARE_SINGLE_STEP_P()'
- Define this as 1 if the target does not have a hardware single-step
- mechanism. The macro `SOFTWARE_SINGLE_STEP' must also be defined.
-
-`SOFTWARE_SINGLE_STEP(SIGNAL, INSERT_BREAKPOINTS_P)'
- A function that inserts or removes (depending on
- INSERT_BREAKPOINTS_P) breakpoints at each possible destinations of
- the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for
- examples.
-
-`set_gdbarch_sofun_address_maybe_missing (GDBARCH, SET)'
- Somebody clever observed that, the more actual addresses you have
- in the debug information, the more time the linker has to spend
- relocating them. So whenever there's some other way the debugger
- could find the address it needs, you should omit it from the debug
- info, to make linking faster.
-
- Calling `set_gdbarch_sofun_address_maybe_missing' with a non-zero
- argument SET indicates that a particular set of hacks of this sort
- are in use, affecting `N_SO' and `N_FUN' entries in stabs-format
- debugging information. `N_SO' stabs mark the beginning and ending
- addresses of compilation units in the text segment. `N_FUN' stabs
- mark the starts and ends of functions.
-
- In this case, GDB assumes two things:
-
- * `N_FUN' stabs have an address of zero. Instead of using those
- addresses, you should find the address where the function
- starts by taking the function name from the stab, and then
- looking that up in the minsyms (the linker/assembler symbol
- table). In other words, the stab has the name, and the
- linker/assembler symbol table is the only place that carries
- the address.
-
- * `N_SO' stabs have an address of zero, too. You just look at
- the `N_FUN' stabs that appear before and after the `N_SO'
- stab, and guess the starting and ending addresses of the
- compilation unit from them.
-
-`int gdbarch_stabs_argument_has_addr (GDBARCH, TYPE)'
- Define this function to return nonzero if a function argument of
- type TYPE is passed by reference instead of value.
-
-`CORE_ADDR gdbarch_push_dummy_call (GDBARCH, FUNCTION, REGCACHE, BP_ADDR, NARGS, ARGS, SP, STRUCT_RETURN, STRUCT_ADDR)'
- Define this to push the dummy frame's call to the inferior
- function onto the stack. In addition to pushing NARGS, the code
- should push STRUCT_ADDR (when STRUCT_RETURN is non-zero), and the
- return address (BP_ADDR).
-
- FUNCTION is a pointer to a `struct value'; on architectures that
- use function descriptors, this contains the function descriptor
- value.
-
- Returns the updated top-of-stack pointer.
-
-`CORE_ADDR gdbarch_push_dummy_code (GDBARCH, SP, FUNADDR, USING_GCC, ARGS, NARGS, VALUE_TYPE, REAL_PC, BP_ADDR, REGCACHE)'
- Given a stack based call dummy, push the instruction sequence
- (including space for a breakpoint) to which the called function
- should return.
-
- Set BP_ADDR to the address at which the breakpoint instruction
- should be inserted, REAL_PC to the resume address when starting
- the call sequence, and return the updated inner-most stack address.
-
- By default, the stack is grown sufficient to hold a frame-aligned
- (*note frame_align::) breakpoint, BP_ADDR is set to the address
- reserved for that breakpoint, and REAL_PC set to FUNADDR.
-
- This method replaces `gdbarch_call_dummy_location (GDBARCH)'.
-
-`int gdbarch_sdb_reg_to_regnum (GDBARCH, SDB_REGNR)'
- Use this function to convert sdb register SDB_REGNR into GDB
- regnum. If not defined, no conversion will be done.
-
-`enum return_value_convention gdbarch_return_value (struct gdbarch *GDBARCH, struct type *VALTYPE, struct regcache *REGCACHE, void *READBUF, const void *WRITEBUF)'
- Given a function with a return-value of type RETTYPE, return which
- return-value convention that function would use.
-
- GDB currently recognizes two function return-value conventions:
- `RETURN_VALUE_REGISTER_CONVENTION' where the return value is found
- in registers; and `RETURN_VALUE_STRUCT_CONVENTION' where the return
- value is found in memory and the address of that memory location is
- passed in as the function's first parameter.
-
- If the register convention is being used, and WRITEBUF is
- non-`NULL', also copy the return-value in WRITEBUF into REGCACHE.
-
- If the register convention is being used, and READBUF is
- non-`NULL', also copy the return value from REGCACHE into READBUF
- (REGCACHE contains a copy of the registers from the just returned
- function).
-
- _Maintainer note: This method replaces separate predicate, extract,
- store methods. By having only one method, the logic needed to
- determine the return-value convention need only be implemented in
- one place. If GDB were written in an OO language, this method
- would instead return an object that knew how to perform the
- register return-value extract and store._
-
- _Maintainer note: This method does not take a GCC_P parameter, and
- such a parameter should not be added. If an architecture that
- requires per-compiler or per-function information be identified,
- then the replacement of RETTYPE with `struct value' FUNCTION
- should be pursued._
-
- _Maintainer note: The REGCACHE parameter limits this methods to
- the inner most frame. While replacing REGCACHE with a `struct
- frame_info' FRAME parameter would remove that limitation there has
- yet to be a demonstrated need for such a change._
-
-`void gdbarch_skip_permanent_breakpoint (GDBARCH, REGCACHE)'
- Advance the inferior's PC past a permanent breakpoint. GDB
- normally steps over a breakpoint by removing it, stepping one
- instruction, and re-inserting the breakpoint. However, permanent
- breakpoints are hardwired into the inferior, and can't be removed,
- so this strategy doesn't work. Calling
- `gdbarch_skip_permanent_breakpoint' adjusts the processor's state
- so that execution will resume just after the breakpoint. This
- function does the right thing even when the breakpoint is in the
- delay slot of a branch or jump.
-
-`CORE_ADDR gdbarch_skip_trampoline_code (GDBARCH, FRAME, PC)'
- If the target machine has trampoline code that sits between
- callers and the functions being called, then define this function
- to return a new PC that is at the start of the real function.
-
-`int gdbarch_deprecated_fp_regnum (GDBARCH)'
- If the frame pointer is in a register, use this function to return
- the number of that register.
-
-`int gdbarch_stab_reg_to_regnum (GDBARCH, STAB_REGNR)'
- Use this function to convert stab register STAB_REGNR into GDB
- regnum. If not defined, no conversion will be done.
-
-`SYMBOL_RELOADING_DEFAULT'
- The default value of the "symbol-reloading" variable. (Never
- defined in current sources.)
-
-`TARGET_CHAR_BIT'
- Number of bits in a char; defaults to 8.
-
-`int gdbarch_char_signed (GDBARCH)'
- Non-zero if `char' is normally signed on this architecture; zero if
- it should be unsigned.
-
- The ISO C standard requires the compiler to treat `char' as
- equivalent to either `signed char' or `unsigned char'; any
- character in the standard execution set is supposed to be positive.
- Most compilers treat `char' as signed, but `char' is unsigned on
- the IBM S/390, RS6000, and PowerPC targets.
-
-`int gdbarch_double_bit (GDBARCH)'
- Number of bits in a double float; defaults to
- `8 * TARGET_CHAR_BIT'.
-
-`int gdbarch_float_bit (GDBARCH)'
- Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'.
-
-`int gdbarch_int_bit (GDBARCH)'
- Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'.
-
-`int gdbarch_long_bit (GDBARCH)'
- Number of bits in a long integer; defaults to
- `4 * TARGET_CHAR_BIT'.
-
-`int gdbarch_long_double_bit (GDBARCH)'
- Number of bits in a long double float; defaults to
- `2 * gdbarch_double_bit (GDBARCH)'.
-
-`int gdbarch_long_long_bit (GDBARCH)'
- Number of bits in a long long integer; defaults to
- `2 * gdbarch_long_bit (GDBARCH)'.
-
-`int gdbarch_ptr_bit (GDBARCH)'
- Number of bits in a pointer; defaults to
- `gdbarch_int_bit (GDBARCH)'.
-
-`int gdbarch_short_bit (GDBARCH)'
- Number of bits in a short integer; defaults to
- `2 * TARGET_CHAR_BIT'.
-
-`void gdbarch_virtual_frame_pointer (GDBARCH, PC, FRAME_REGNUM, FRAME_OFFSET)'
- Returns a `(REGISTER, OFFSET)' pair representing the virtual frame
- pointer in use at the code address PC. If virtual frame pointers
- are not used, a default definition simply returns
- `gdbarch_deprecated_fp_regnum' (or `gdbarch_sp_regnum', if no
- frame pointer is defined), with an offset of zero.
-
-`TARGET_HAS_HARDWARE_WATCHPOINTS'
- If non-zero, the target has support for hardware-assisted
- watchpoints. *Note watchpoints: Algorithms, for more details and
- other related macros.
-
-`int gdbarch_print_insn (GDBARCH, VMA, INFO)'
- This is the function used by GDB to print an assembly instruction.
- It prints the instruction at address VMA in debugged memory and
- returns the length of the instruction, in bytes. This usually
- points to a function in the `opcodes' library (*note Opcodes:
- Support Libraries.). INFO is a structure (of type
- `disassemble_info') defined in the header file
- `include/dis-asm.h', and used to pass information to the
- instruction decoding routine.
-
-`frame_id gdbarch_dummy_id (GDBARCH, FRAME)'
- Given FRAME return a `struct frame_id' that uniquely identifies an
- inferior function call's dummy frame. The value returned must
- match the dummy frame stack value previously saved by
- `call_function_by_hand'.
-
-`void gdbarch_value_to_register (GDBARCH, FRAME, TYPE, BUF)'
- Convert a value of type TYPE into the raw contents of a register.
- *Note Using Different Register and Memory Data Representations:
- Target Architecture Definition.
-
-
- Motorola M68K target conditionals.
-
-`BPT_VECTOR'
- Define this to be the 4-bit location of the breakpoint trap
- vector. If not defined, it will default to `0xf'.
-
-`REMOTE_BPT_VECTOR'
- Defaults to `1'.
-
-
-\1f
-File: gdbint.info, Node: Adding a New Target, Prev: Defining Other Architecture Features, Up: Target Architecture Definition
-
-11.11 Adding a New Target
-=========================
-
-The following files add a target to GDB:
-
-`gdb/TTT-tdep.c'
- Contains any miscellaneous code required for this target machine.
- On some machines it doesn't exist at all.
-
-`gdb/ARCH-tdep.c'
-`gdb/ARCH-tdep.h'
- This is required to describe the basic layout of the target
- machine's processor chip (registers, stack, etc.). It can be
- shared among many targets that use the same processor architecture.
-
-
- (Target header files such as `gdb/config/ARCH/tm-TTT.h',
-`gdb/config/ARCH/tm-ARCH.h', and `config/tm-OS.h' are no longer used.)
-
- A GDB description for a new architecture, arch is created by
-defining a global function `_initialize_ARCH_tdep', by convention in
-the source file `ARCH-tdep.c'. For example, in the case of the
-OpenRISC 1000, this function is called `_initialize_or1k_tdep' and is
-found in the file `or1k-tdep.c'.
-
- The object file resulting from compiling this source file, which will
-contain the implementation of the `_initialize_ARCH_tdep' function is
-specified in the GDB `configure.tgt' file, which includes a large case
-statement pattern matching against the `--target' option of the
-`configure' script.
-
- _Note:_ If the architecture requires multiple source files, the
- corresponding binaries should be included in `configure.tgt'.
- However if there are header files, the dependencies on these will
- not be picked up from the entries in `configure.tgt'. The
- `Makefile.in' file will need extending to show these dependencies.
-
- A new struct gdbarch, defining the new architecture, is created
-within the `_initialize_ARCH_tdep' function by calling
-`gdbarch_register':
-
- void gdbarch_register (enum bfd_architecture architecture,
- gdbarch_init_ftype *init_func,
- gdbarch_dump_tdep_ftype *tdep_dump_func);
-
- This function has been described fully in an earlier section. *Note
-How an Architecture is Represented: How an Architecture is Represented.
-
- The new `struct gdbarch' should contain implementations of the
-necessary functions (described in the previous sections) to describe
-the basic layout of the target machine's processor chip (registers,
-stack, etc.). It can be shared among many targets that use the same
-processor architecture.
-
-\1f
-File: gdbint.info, Node: Target Descriptions, Next: Target Vector Definition, Prev: Target Architecture Definition, Up: Top
-
-12 Target Descriptions
-**********************
-
-The target architecture definition (*note Target Architecture
-Definition::) contains GDB's hard-coded knowledge about an
-architecture. For some platforms, it is handy to have more flexible
-knowledge about a specific instance of the architecture--for instance,
-a processor or development board. "Target descriptions" provide a
-mechanism for the user to tell GDB more about what their target
-supports, or for the target to tell GDB directly.
-
- For details on writing, automatically supplying, and manually
-selecting target descriptions, see *note Target Descriptions:
-(gdb)Target Descriptions. This section will cover some related topics
-about the GDB internals.
-
-* Menu:
-
-* Target Descriptions Implementation::
-* Adding Target Described Register Support::
-
-\1f
-File: gdbint.info, Node: Target Descriptions Implementation, Next: Adding Target Described Register Support, Up: Target Descriptions
-
-12.1 Target Descriptions Implementation
-=======================================
-
-Before GDB connects to a new target, or runs a new program on an
-existing target, it discards any existing target description and
-reverts to a default gdbarch. Then, after connecting, it looks for a
-new target description by calling `target_find_description'.
-
- A description may come from a user specified file (XML), the remote
-`qXfer:features:read' packet (also XML), or from any custom
-`to_read_description' routine in the target vector. For instance, the
-remote target supports guessing whether a MIPS target is 32-bit or
-64-bit based on the size of the `g' packet.
-
- If any target description is found, GDB creates a new gdbarch
-incorporating the description by calling `gdbarch_update_p'. Any
-`<architecture>' element is handled first, to determine which
-architecture's gdbarch initialization routine is called to create the
-new architecture. Then the initialization routine is called, and has a
-chance to adjust the constructed architecture based on the contents of
-the target description. For instance, it can recognize any properties
-set by a `to_read_description' routine. Also see *note Adding Target
-Described Register Support::.
-
-\1f
-File: gdbint.info, Node: Adding Target Described Register Support, Prev: Target Descriptions Implementation, Up: Target Descriptions
-
-12.2 Adding Target Described Register Support
-=============================================
-
-Target descriptions can report additional registers specific to an
-instance of the target. But it takes a little work in the architecture
-specific routines to support this.
-
- A target description must either have no registers or a complete
-set--this avoids complexity in trying to merge standard registers with
-the target defined registers. It is the architecture's responsibility
-to validate that a description with registers has everything it needs.
-To keep architecture code simple, the same mechanism is used to assign
-fixed internal register numbers to standard registers.
-
- If `tdesc_has_registers' returns 1, the description contains
-registers. The architecture's `gdbarch_init' routine should:
-
- * Call `tdesc_data_alloc' to allocate storage, early, before
- searching for a matching gdbarch or allocating a new one.
-
- * Use `tdesc_find_feature' to locate standard features by name.
-
- * Use `tdesc_numbered_register' and `tdesc_numbered_register_choices'
- to locate the expected registers in the standard features.
-
- * Return `NULL' if a required feature is missing, or if any standard
- feature is missing expected registers. This will produce a
- warning that the description was incomplete.
-
- * Free the allocated data before returning, unless
- `tdesc_use_registers' is called.
-
- * Call `set_gdbarch_num_regs' as usual, with a number higher than any
- fixed number passed to `tdesc_numbered_register'.
-
- * Call `tdesc_use_registers' after creating a new gdbarch, before
- returning it.
-
-
- After `tdesc_use_registers' has been called, the architecture's
-`register_name', `register_type', and `register_reggroup_p' routines
-will not be called; that information will be taken from the target
-description. `num_regs' may be increased to account for any additional
-registers in the description.
-
- Pseudo-registers require some extra care:
-
- * Using `tdesc_numbered_register' allows the architecture to give
- constant register numbers to standard architectural registers, e.g.
- as an `enum' in `ARCH-tdep.h'. But because pseudo-registers are
- always numbered above `num_regs', which may be increased by the
- description, constant numbers can not be used for pseudos. They
- must be numbered relative to `num_regs' instead.
-
- * The description will not describe pseudo-registers, so the
- architecture must call `set_tdesc_pseudo_register_name',
- `set_tdesc_pseudo_register_type', and
- `set_tdesc_pseudo_register_reggroup_p' to supply routines
- describing pseudo registers. These routines will be passed
- internal register numbers, so the same routines used for the
- gdbarch equivalents are usually suitable.
-
-
-\1f
-File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Descriptions, Up: Top
-
-13 Target Vector Definition
-***************************
-
-The target vector defines the interface between GDB's abstract handling
-of target systems, and the nitty-gritty code that actually exercises
-control over a process or a serial port. GDB includes some 30-40
-different target vectors; however, each configuration of GDB includes
-only a few of them.
-
-* Menu:
-
-* Managing Execution State::
-* Existing Targets::
-
-\1f
-File: gdbint.info, Node: Managing Execution State, Next: Existing Targets, Up: Target Vector Definition
-
-13.1 Managing Execution State
-=============================
-
-A target vector can be completely inactive (not pushed on the target
-stack), active but not running (pushed, but not connected to a fully
-manifested inferior), or completely active (pushed, with an accessible
-inferior). Most targets are only completely inactive or completely
-active, but some support persistent connections to a target even when
-the target has exited or not yet started.
-
- For example, connecting to the simulator using `target sim' does not
-create a running program. Neither registers nor memory are accessible
-until `run'. Similarly, after `kill', the program can not continue
-executing. But in both cases GDB remains connected to the simulator,
-and target-specific commands are directed to the simulator.
-
- A target which only supports complete activation should push itself
-onto the stack in its `to_open' routine (by calling `push_target'), and
-unpush itself from the stack in its `to_mourn_inferior' routine (by
-calling `unpush_target').
-
- A target which supports both partial and complete activation should
-still call `push_target' in `to_open', but not call `unpush_target' in
-`to_mourn_inferior'. Instead, it should call either
-`target_mark_running' or `target_mark_exited' in its `to_open',
-depending on whether the target is fully active after connection. It
-should also call `target_mark_running' any time the inferior becomes
-fully active (e.g. in `to_create_inferior' and `to_attach'), and
-`target_mark_exited' when the inferior becomes inactive (in
-`to_mourn_inferior'). The target should also make sure to call
-`target_mourn_inferior' from its `to_kill', to return the target to
-inactive state.
-
-\1f
-File: gdbint.info, Node: Existing Targets, Prev: Managing Execution State, Up: Target Vector Definition
-
-13.2 Existing Targets
-=====================
-
-13.2.1 File Targets
--------------------
-
-Both executables and core files have target vectors.
-
-13.2.2 Standard Protocol and Remote Stubs
------------------------------------------
-
-GDB's file `remote.c' talks a serial protocol to code that runs in the
-target system. GDB provides several sample "stubs" that can be
-integrated into target programs or operating systems for this purpose;
-they are named `CPU-stub.c'. Many operating systems, embedded targets,
-emulators, and simulators already have a GDB stub built into them, and
-maintenance of the remote protocol must be careful to preserve
-compatibility.
-
- The GDB user's manual describes how to put such a stub into your
-target code. What follows is a discussion of integrating the SPARC
-stub into a complicated operating system (rather than a simple
-program), by Stu Grossman, the author of this stub.
-
- The trap handling code in the stub assumes the following upon entry
-to `trap_low':
-
- 1. %l1 and %l2 contain pc and npc respectively at the time of the
- trap;
-
- 2. traps are disabled;
-
- 3. you are in the correct trap window.
-
- As long as your trap handler can guarantee those conditions, then
-there is no reason why you shouldn't be able to "share" traps with the
-stub. The stub has no requirement that it be jumped to directly from
-the hardware trap vector. That is why it calls `exceptionHandler()',
-which is provided by the external environment. For instance, this could
-set up the hardware traps to actually execute code which calls the stub
-first, and then transfers to its own trap handler.
-
- For the most point, there probably won't be much of an issue with
-"sharing" traps, as the traps we use are usually not used by the kernel,
-and often indicate unrecoverable error conditions. Anyway, this is all
-controlled by a table, and is trivial to modify. The most important
-trap for us is for `ta 1'. Without that, we can't single step or do
-breakpoints. Everything else is unnecessary for the proper operation
-of the debugger/stub.
-
- From reading the stub, it's probably not obvious how breakpoints
-work. They are simply done by deposit/examine operations from GDB.
-
-13.2.3 ROM Monitor Interface
-----------------------------
-
-13.2.4 Custom Protocols
------------------------
-
-13.2.5 Transport Layer
-----------------------
-
-13.2.6 Builtin Simulator
-------------------------
-
-\1f
-File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top
-
-14 Native Debugging
-*******************
-
-Several files control GDB's configuration for native support:
-
-`gdb/config/ARCH/XYZ.mh'
- Specifies Makefile fragments needed by a _native_ configuration on
- machine XYZ. In particular, this lists the required
- native-dependent object files, by defining `NATDEPFILES=...'.
- Also specifies the header file which describes native support on
- XYZ, by defining `NAT_FILE= nm-XYZ.h'. You can also define
- `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS',
- `NAT_GENERATED_FILES', etc.; see `Makefile.in'.
-
- _Maintainer's note: The `.mh' suffix is because this file
- originally contained `Makefile' fragments for hosting GDB on
- machine XYZ. While the file is no longer used for this purpose,
- the `.mh' suffix remains. Perhaps someone will eventually rename
- these fragments so that they have a `.mn' suffix._
-
-`gdb/config/ARCH/nm-XYZ.h'
- (`nm.h' is a link to this file, created by `configure'). Contains
- C macro definitions describing the native system environment, such
- as child process control and core file support.
-
-`gdb/XYZ-nat.c'
- Contains any miscellaneous C code required for this native support
- of this machine. On some machines it doesn't exist at all.
-
- There are some "generic" versions of routines that can be used by
-various systems. These can be customized in various ways by macros
-defined in your `nm-XYZ.h' file. If these routines work for the XYZ
-host, you can just include the generic file's name (with `.o', not
-`.c') in `NATDEPFILES'.
-
- Otherwise, if your machine needs custom support routines, you will
-need to write routines that perform the same functions as the generic
-file. Put them into `XYZ-nat.c', and put `XYZ-nat.o' into
-`NATDEPFILES'.
-
-`inftarg.c'
- This contains the _target_ops vector_ that supports Unix child
- processes on systems which use ptrace and wait to control the
- child.
-
-`procfs.c'
- This contains the _target_ops vector_ that supports Unix child
- processes on systems which use /proc to control the child.
-
-`fork-child.c'
- This does the low-level grunge that uses Unix system calls to do a
- "fork and exec" to start up a child process.
-
-`infptrace.c'
- This is the low level interface to inferior processes for systems
- using the Unix `ptrace' call in a vanilla way.
-
-14.1 ptrace
-===========
-
-14.2 /proc
-==========
-
-14.3 win32
-==========
-
-14.4 shared libraries
-=====================
-
-14.5 Native Conditionals
-========================
-
-When GDB is configured and compiled, various macros are defined or left
-undefined, to control compilation when the host and target systems are
-the same. These macros should be defined (or left undefined) in
-`nm-SYSTEM.h'.
-
-`I386_USE_GENERIC_WATCHPOINTS'
- An x86-based machine can define this to use the generic x86
- watchpoint support; see *note I386_USE_GENERIC_WATCHPOINTS:
- Algorithms.
-
-`SOLIB_ADD (FILENAME, FROM_TTY, TARG, READSYMS)'
- Define this to expand into an expression that will cause the
- symbols in FILENAME to be added to GDB's symbol table. If
- READSYMS is zero symbols are not read but any necessary low level
- processing for FILENAME is still done.
-
-`SOLIB_CREATE_INFERIOR_HOOK'
- Define this to expand into any shared-library-relocation code that
- you want to be run just after the child process has been forked.
-
-`START_INFERIOR_TRAPS_EXPECTED'
- When starting an inferior, GDB normally expects to trap twice;
- once when the shell execs, and once when the program itself execs.
- If the actual number of traps is something other than 2, then
- define this macro to expand into the number expected.
-
-
-\1f
-File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
-
-15 Support Libraries
-********************
-
-15.1 BFD
-========
-
-BFD provides support for GDB in several ways:
-
-_identifying executable and core files_
- BFD will identify a variety of file types, including a.out, coff,
- and several variants thereof, as well as several kinds of core
- files.
-
-_access to sections of files_
- BFD parses the file headers to determine the names, virtual
- addresses, sizes, and file locations of all the various named
- sections in files (such as the text section or the data section).
- GDB simply calls BFD to read or write section X at byte offset Y
- for length Z.
-
-_specialized core file support_
- BFD provides routines to determine the failing command name stored
- in a core file, the signal with which the program failed, and
- whether a core file matches (i.e. could be a core dump of) a
- particular executable file.
-
-_locating the symbol information_
- GDB uses an internal interface of BFD to determine where to find
- the symbol information in an executable file or symbol-file. GDB
- itself handles the reading of symbols, since BFD does not
- "understand" debug symbols, but GDB uses BFD's cached information
- to find the symbols, string table, etc.
-
-15.2 opcodes
-============
-
-The opcodes library provides GDB's disassembler. (It's a separate
-library because it's also used in binutils, for `objdump').
-
-15.3 readline
-=============
-
-The `readline' library provides a set of functions for use by
-applications that allow users to edit command lines as they are typed
-in.
-
-15.4 libiberty
-==============
-
-The `libiberty' library provides a set of functions and features that
-integrate and improve on functionality found in modern operating
-systems. Broadly speaking, such features can be divided into three
-groups: supplemental functions (functions that may be missing in some
-environments and operating systems), replacement functions (providing a
-uniform and easier to use interface for commonly used standard
-functions), and extensions (which provide additional functionality
-beyond standard functions).
-
- GDB uses various features provided by the `libiberty' library, for
-instance the C++ demangler, the IEEE floating format support functions,
-the input options parser `getopt', the `obstack' extension, and other
-functions.
-
-15.4.1 `obstacks' in GDB
-------------------------
-
-The obstack mechanism provides a convenient way to allocate and free
-chunks of memory. Each obstack is a pool of memory that is managed
-like a stack. Objects (of any nature, size and alignment) are
-allocated and freed in a LIFO fashion on an obstack (see `libiberty''s
-documentation for a more detailed explanation of `obstacks').
-
- The most noticeable use of the `obstacks' in GDB is in object files.
-There is an obstack associated with each internal representation of an
-object file. Lots of things get allocated on these `obstacks':
-dictionary entries, blocks, blockvectors, symbols, minimal symbols,
-types, vectors of fundamental types, class fields of types, object
-files section lists, object files section offset lists, line tables,
-symbol tables, partial symbol tables, string tables, symbol table
-private data, macros tables, debug information sections and entries,
-import and export lists (som), unwind information (hppa), dwarf2
-location expressions data. Plus various strings such as directory
-names strings, debug format strings, names of types.
-
- An essential and convenient property of all data on `obstacks' is
-that memory for it gets allocated (with `obstack_alloc') at various
-times during a debugging session, but it is released all at once using
-the `obstack_free' function. The `obstack_free' function takes a
-pointer to where in the stack it must start the deletion from (much
-like the cleanup chains have a pointer to where to start the cleanups).
-Because of the stack like structure of the `obstacks', this allows to
-free only a top portion of the obstack. There are a few instances in
-GDB where such thing happens. Calls to `obstack_free' are done after
-some local data is allocated to the obstack. Only the local data is
-deleted from the obstack. Of course this assumes that nothing between
-the `obstack_alloc' and the `obstack_free' allocates anything else on
-the same obstack. For this reason it is best and safest to use
-temporary `obstacks'.
-
- Releasing the whole obstack is also not safe per se. It is safe only
-under the condition that we know the `obstacks' memory is no longer
-needed. In GDB we get rid of the `obstacks' only when we get rid of
-the whole objfile(s), for instance upon reading a new symbol file.
-
-15.5 gnu-regex
-==============
-
-Regex conditionals.
-
-`C_ALLOCA'
-
-`NFAILURES'
-
-`RE_NREGS'
-
-`SIGN_EXTEND_CHAR'
-
-`SWITCH_ENUM_BUG'
-
-`SYNTAX_TABLE'
-
-`Sword'
-
-`sparc'
-
-15.6 Array Containers
-=====================
-
-Often it is necessary to manipulate a dynamic array of a set of
-objects. C forces some bookkeeping on this, which can get cumbersome
-and repetitive. The `vec.h' file contains macros for defining and
-using a typesafe vector type. The functions defined will be inlined
-when compiling, and so the abstraction cost should be zero. Domain
-checks are added to detect programming errors.
-
- An example use would be an array of symbols or section information.
-The array can be grown as symbols are read in (or preallocated), and
-the accessor macros provided keep care of all the necessary
-bookkeeping. Because the arrays are type safe, there is no danger of
-accidentally mixing up the contents. Think of these as C++ templates,
-but implemented in C.
-
- Because of the different behavior of structure objects, scalar
-objects and of pointers, there are three flavors of vector, one for
-each of these variants. Both the structure object and pointer variants
-pass pointers to objects around -- in the former case the pointers are
-stored into the vector and in the latter case the pointers are
-dereferenced and the objects copied into the vector. The scalar object
-variant is suitable for `int'-like objects, and the vector elements are
-returned by value.
-
- There are both `index' and `iterate' accessors. The iterator
-returns a boolean iteration condition and updates the iteration
-variable passed by reference. Because the iterator will be inlined,
-the address-of can be optimized away.
-
- The vectors are implemented using the trailing array idiom, thus they
-are not resizeable without changing the address of the vector object
-itself. This means you cannot have variables or fields of vector type
--- always use a pointer to a vector. The one exception is the final
-field of a structure, which could be a vector type. You will have to
-use the `embedded_size' & `embedded_init' calls to create such objects,
-and they will probably not be resizeable (so don't use the "safe"
-allocation variants). The trailing array idiom is used (rather than a
-pointer to an array of data), because, if we allow `NULL' to also
-represent an empty vector, empty vectors occupy minimal space in the
-structure containing them.
-
- Each operation that increases the number of active elements is
-available in "quick" and "safe" variants. The former presumes that
-there is sufficient allocated space for the operation to succeed (it
-dies if there is not). The latter will reallocate the vector, if
-needed. Reallocation causes an exponential increase in vector size.
-If you know you will be adding N elements, it would be more efficient
-to use the reserve operation before adding the elements with the
-"quick" operation. This will ensure there are at least as many
-elements as you ask for, it will exponentially increase if there are
-too few spare slots. If you want reserve a specific number of slots,
-but do not want the exponential increase (for instance, you know this
-is the last allocation), use a negative number for reservation. You
-can also create a vector of a specific size from the get go.
-
- You should prefer the push and pop operations, as they append and
-remove from the end of the vector. If you need to remove several items
-in one go, use the truncate operation. The insert and remove
-operations allow you to change elements in the middle of the vector.
-There are two remove operations, one which preserves the element
-ordering `ordered_remove', and one which does not `unordered_remove'.
-The latter function copies the end element into the removed slot,
-rather than invoke a memmove operation. The `lower_bound' function
-will determine where to place an item in the array using insert that
-will maintain sorted order.
-
- If you need to directly manipulate a vector, then the `address'
-accessor will return the address of the start of the vector. Also the
-`space' predicate will tell you whether there is spare capacity in the
-vector. You will not normally need to use these two functions.
-
- Vector types are defined using a `DEF_VEC_{O,P,I}(TYPENAME)' macro.
-Variables of vector type are declared using a `VEC(TYPENAME)' macro.
-The characters `O', `P' and `I' indicate whether TYPENAME is an object
-(`O'), pointer (`P') or integral (`I') type. Be careful to pick the
-correct one, as you'll get an awkward and inefficient API if you use
-the wrong one. There is a check, which results in a compile-time
-warning, for the `P' and `I' versions, but there is no check for the
-`O' versions, as that is not possible in plain C.
-
- An example of their use would be,
-
- DEF_VEC_P(tree); // non-managed tree vector.
-
- struct my_struct {
- VEC(tree) *v; // A (pointer to) a vector of tree pointers.
- };
-
- struct my_struct *s;
-
- if (VEC_length(tree, s->v)) { we have some contents }
- VEC_safe_push(tree, s->v, decl); // append some decl onto the end
- for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)
- { do something with elt }
-
- The `vec.h' file provides details on how to invoke the various
-accessors provided. They are enumerated here:
-
-`VEC_length'
- Return the number of items in the array,
-
-`VEC_empty'
- Return true if the array has no elements.
-
-`VEC_last'
-`VEC_index'
- Return the last or arbitrary item in the array.
-
-`VEC_iterate'
- Access an array element and indicate whether the array has been
- traversed.
-
-`VEC_alloc'
-`VEC_free'
- Create and destroy an array.
-
-`VEC_embedded_size'
-`VEC_embedded_init'
- Helpers for embedding an array as the final element of another
- struct.
-
-`VEC_copy'
- Duplicate an array.
-
-`VEC_space'
- Return the amount of free space in an array.
-
-`VEC_reserve'
- Ensure a certain amount of free space.
-
-`VEC_quick_push'
-`VEC_safe_push'
- Append to an array, either assuming the space is available, or
- making sure that it is.
-
-`VEC_pop'
- Remove the last item from an array.
-
-`VEC_truncate'
- Remove several items from the end of an array.
-
-`VEC_safe_grow'
- Add several items to the end of an array.
-
-`VEC_replace'
- Overwrite an item in the array.
-
-`VEC_quick_insert'
-`VEC_safe_insert'
- Insert an item into the middle of the array. Either the space must
- already exist, or the space is created.
-
-`VEC_ordered_remove'
-`VEC_unordered_remove'
- Remove an item from the array, preserving order or not.
-
-`VEC_block_remove'
- Remove a set of items from the array.
-
-`VEC_address'
- Provide the address of the first element.
-
-`VEC_lower_bound'
- Binary search the array.
-
-
-15.7 include
-============
-
-\1f
-File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
-
-16 Coding
-*********
-
-This chapter covers topics that are lower-level than the major
-algorithms of GDB.
-
-16.1 Cleanups
-=============
-
-Cleanups are a structured way to deal with things that need to be done
-later.
-
- When your code does something (e.g., `xmalloc' some memory, or
-`open' a file) that needs to be undone later (e.g., `xfree' the memory
-or `close' the file), it can make a cleanup. The cleanup will be done
-at some future point: when the command is finished and control returns
-to the top level; when an error occurs and the stack is unwound; or
-when your code decides it's time to explicitly perform cleanups.
-Alternatively you can elect to discard the cleanups you created.
-
- Syntax:
-
-`struct cleanup *OLD_CHAIN;'
- Declare a variable which will hold a cleanup chain handle.
-
-`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
- Make a cleanup which will cause FUNCTION to be called with ARG (a
- `char *') later. The result, OLD_CHAIN, is a handle that can
- later be passed to `do_cleanups' or `discard_cleanups'. Unless
- you are going to call `do_cleanups' or `discard_cleanups', you can
- ignore the result from `make_cleanup'.
-
-`do_cleanups (OLD_CHAIN);'
- Do all cleanups added to the chain since the corresponding
- `make_cleanup' call was made.
-
-`discard_cleanups (OLD_CHAIN);'
- Same as `do_cleanups' except that it just removes the cleanups from
- the chain and does not call the specified functions.
-
- Cleanups are implemented as a chain. The handle returned by
-`make_cleanups' includes the cleanup passed to the call and any later
-cleanups appended to the chain (but not yet discarded or performed).
-E.g.:
-
- make_cleanup (a, 0);
- {
- struct cleanup *old = make_cleanup (b, 0);
- make_cleanup (c, 0)
- ...
- do_cleanups (old);
- }
-
-will call `c()' and `b()' but will not call `a()'. The cleanup that
-calls `a()' will remain in the cleanup chain, and will be done later
-unless otherwise discarded.
-
- Your function should explicitly do or discard the cleanups it
-creates. Failing to do this leads to non-deterministic behavior since
-the caller will arbitrarily do or discard your functions cleanups.
-This need leads to two common cleanup styles.
-
- The first style is try/finally. Before it exits, your code-block
-calls `do_cleanups' with the old cleanup chain and thus ensures that
-your code-block's cleanups are always performed. For instance, the
-following code-segment avoids a memory leak problem (even when `error'
-is called and a forced stack unwind occurs) by ensuring that the
-`xfree' will always be called:
-
- struct cleanup *old = make_cleanup (null_cleanup, 0);
- data = xmalloc (sizeof blah);
- make_cleanup (xfree, data);
- ... blah blah ...
- do_cleanups (old);
-
- The second style is try/except. Before it exits, your code-block
-calls `discard_cleanups' with the old cleanup chain and thus ensures
-that any created cleanups are not performed. For instance, the
-following code segment, ensures that the file will be closed but only
-if there is an error:
-
- FILE *file = fopen ("afile", "r");
- struct cleanup *old = make_cleanup (close_file, file);
- ... blah blah ...
- discard_cleanups (old);
- return file;
-
- Some functions, e.g., `fputs_filtered()' or `error()', specify that
-they "should not be called when cleanups are not in place". This means
-that any actions you need to reverse in the case of an error or
-interruption must be on the cleanup chain before you call these
-functions, since they might never return to your code (they `longjmp'
-instead).
-
-16.2 Per-architecture module data
-=================================
-
-The multi-arch framework includes a mechanism for adding module
-specific per-architecture data-pointers to the `struct gdbarch'
-architecture object.
-
- A module registers one or more per-architecture data-pointers using:
-
- -- Architecture Function: struct gdbarch_data *
-gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *PRE_INIT)
- PRE_INIT is used to, on-demand, allocate an initial value for a
- per-architecture data-pointer using the architecture's obstack
- (passed in as a parameter). Since PRE_INIT can be called during
- architecture creation, it is not parameterized with the
- architecture. and must not call modules that use per-architecture
- data.
-
- -- Architecture Function: struct gdbarch_data *
-gdbarch_data_register_post_init (gdbarch_data_post_init_ftype
- *POST_INIT)
- POST_INIT is used to obtain an initial value for a
- per-architecture data-pointer _after_. Since POST_INIT is always
- called after architecture creation, it both receives the fully
- initialized architecture and is free to call modules that use
- per-architecture data (care needs to be taken to ensure that those
- other modules do not try to call back to this module as that will
- create in cycles in the initialization call graph).
-
- These functions return a `struct gdbarch_data' that is used to
-identify the per-architecture data-pointer added for that module.
-
- The per-architecture data-pointer is accessed using the function:
-
- -- Architecture Function: void * gdbarch_data (struct gdbarch
- *GDBARCH, struct gdbarch_data *DATA_HANDLE)
- Given the architecture ARCH and module data handle DATA_HANDLE
- (returned by `gdbarch_data_register_pre_init' or
- `gdbarch_data_register_post_init'), this function returns the
- current value of the per-architecture data-pointer. If the data
- pointer is `NULL', it is first initialized by calling the
- corresponding PRE_INIT or POST_INIT method.
-
- The examples below assume the following definitions:
-
- struct nozel { int total; };
- static struct gdbarch_data *nozel_handle;
-
- A module can extend the architecture vector, adding additional
-per-architecture data, using the PRE_INIT method. The module's
-per-architecture data is then initialized during architecture creation.
-
- In the below, the module's per-architecture _nozel_ is added. An
-architecture can specify its nozel by calling `set_gdbarch_nozel' from
-`gdbarch_init'.
-
- static void *
- nozel_pre_init (struct obstack *obstack)
- {
- struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
- return data;
- }
-
- extern void
- set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
- {
- struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
- data->total = nozel;
- }
-
- A module can on-demand create architecture dependent data structures
-using `post_init'.
-
- In the below, the nozel's total is computed on-demand by
-`nozel_post_init' using information obtained from the architecture.
-
- static void *
- nozel_post_init (struct gdbarch *gdbarch)
- {
- struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
- nozel->total = gdbarch... (gdbarch);
- return data;
- }
-
- extern int
- nozel_total (struct gdbarch *gdbarch)
- {
- struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
- return data->total;
- }
-
-16.3 Wrapping Output Lines
-==========================
-
-Output that goes through `printf_filtered' or `fputs_filtered' or
-`fputs_demangled' needs only to have calls to `wrap_here' added in
-places that would be good breaking points. The utility routines will
-take care of actually wrapping if the line width is exceeded.
-
- The argument to `wrap_here' is an indentation string which is
-printed _only_ if the line breaks there. This argument is saved away
-and used later. It must remain valid until the next call to
-`wrap_here' or until a newline has been printed through the
-`*_filtered' functions. Don't pass in a local variable and then return!
-
- It is usually best to call `wrap_here' after printing a comma or
-space. If you call it before printing a space, make sure that your
-indentation properly accounts for the leading space that will print if
-the line wraps there.
-
- Any function or set of functions that produce filtered output must
-finish by printing a newline, to flush the wrap buffer, before switching
-to unfiltered (`printf') output. Symbol reading routines that print
-warnings are a good example.
-
-16.4 GDB Coding Standards
-=========================
-
-GDB follows the GNU coding standards, as described in
-`etc/standards.texi'. This file is also available for anonymous FTP
-from GNU archive sites. GDB takes a strict interpretation of the
-standard; in general, when the GNU standard recommends a practice but
-does not require it, GDB requires it.
-
- GDB follows an additional set of coding standards specific to GDB,
-as described in the following sections.
-
-16.4.1 ISO C
-------------
-
-GDB assumes an ISO/IEC 9899:1990 (a.k.a. ISO C90) compliant compiler.
-
- GDB does not assume an ISO C or POSIX compliant C library.
-
-16.4.2 Memory Management
-------------------------
-
-GDB does not use the functions `malloc', `realloc', `calloc', `free'
-and `asprintf'.
-
- GDB uses the functions `xmalloc', `xrealloc' and `xcalloc' when
-allocating memory. Unlike `malloc' et.al. these functions do not
-return when the memory pool is empty. Instead, they unwind the stack
-using cleanups. These functions return `NULL' when requested to
-allocate a chunk of memory of size zero.
-
- _Pragmatics: By using these functions, the need to check every
-memory allocation is removed. These functions provide portable
-behavior._
-
- GDB does not use the function `free'.
-
- GDB uses the function `xfree' to return memory to the memory pool.
-Consistent with ISO-C, this function ignores a request to free a `NULL'
-pointer.
-
- _Pragmatics: On some systems `free' fails when passed a `NULL'
-pointer._
-
- GDB can use the non-portable function `alloca' for the allocation of
-small temporary values (such as strings).
-
- _Pragmatics: This function is very non-portable. Some systems
-restrict the memory being allocated to no more than a few kilobytes._
-
- GDB uses the string function `xstrdup' and the print function
-`xstrprintf'.
-
- _Pragmatics: `asprintf' and `strdup' can fail. Print functions such
-as `sprintf' are very prone to buffer overflow errors._
-
-16.4.3 Compiler Warnings
-------------------------
-
-With few exceptions, developers should avoid the configuration option
-`--disable-werror' when building GDB. The exceptions are listed in the
-file `gdb/MAINTAINERS'. The default, when building with GCC, is
-`--enable-werror'.
-
- This option causes GDB (when built using GCC) to be compiled with a
-carefully selected list of compiler warning flags. Any warnings from
-those flags are treated as errors.
-
- The current list of warning flags includes:
-
-`-Wall'
- Recommended GCC warnings.
-
-`-Wdeclaration-after-statement'
- GCC 3.x (and later) and C99 allow declarations mixed with code,
- but GCC 2.x and C89 do not.
-
-`-Wpointer-arith'
-
-`-Wformat-nonliteral'
- Non-literal format strings, with a few exceptions, are bugs - they
- might contain unintended user-supplied format specifiers. Since
- GDB uses the `format printf' attribute on all `printf' like
- functions this checks not just `printf' calls but also calls to
- functions such as `fprintf_unfiltered'.
-
-`-Wno-pointer-sign'
- In version 4.0, GCC began warning about pointer argument passing or
- assignment even when the source and destination differed only in
- signedness. However, most GDB code doesn't distinguish carefully
- between `char' and `unsigned char'. In early 2006 the GDB
- developers decided correcting these warnings wasn't worth the time
- it would take.
-
-`-Wno-unused-parameter'
- Due to the way that GDB is implemented many functions have unused
- parameters. Consequently this warning is avoided. The macro
- `ATTRIBUTE_UNUSED' is not used as it leads to false negatives --
- it is not an error to have `ATTRIBUTE_UNUSED' on a parameter that
- is being used.
-
-`-Wno-unused'
-`-Wno-switch'
-`-Wno-char-subscripts'
- These are warnings which might be useful for GDB, but are
- currently too noisy to enable with `-Werror'.
-
-
-16.4.4 Formatting
------------------
-
-The standard GNU recommendations for formatting must be followed
-strictly.
-
- A function declaration should not have its name in column zero. A
-function definition should have its name in column zero.
-
- /* Declaration */
- static void foo (void);
- /* Definition */
- void
- foo (void)
- {
- }
-
- _Pragmatics: This simplifies scripting. Function definitions can be
-found using `^function-name'._
-
- There must be a space between a function or macro name and the
-opening parenthesis of its argument list (except for macro definitions,
-as required by C). There must not be a space after an open
-paren/bracket or before a close paren/bracket.
-
- While additional whitespace is generally helpful for reading, do not
-use more than one blank line to separate blocks, and avoid adding
-whitespace after the end of a program line (as of 1/99, some 600 lines
-had whitespace after the semicolon). Excess whitespace causes
-difficulties for `diff' and `patch' utilities.
-
- Pointers are declared using the traditional K&R C style:
-
- void *foo;
-
-and not:
-
- void * foo;
- void* foo;
-
-16.4.5 Comments
----------------
-
-The standard GNU requirements on comments must be followed strictly.
-
- Block comments must appear in the following form, with no `/*'- or
-`*/'-only lines, and no leading `*':
-
- /* Wait for control to return from inferior to debugger. If inferior
- gets a signal, we may decide to start it up again instead of
- returning. That is why there is a loop in this function. When
- this function actually returns it means the inferior should be left
- stopped and GDB should read more commands. */
-
- (Note that this format is encouraged by Emacs; tabbing for a
-multi-line comment works correctly, and `M-q' fills the block
-consistently.)
-
- Put a blank line between the block comments preceding function or
-variable definitions, and the definition itself.
-
- In general, put function-body comments on lines by themselves, rather
-than trying to fit them into the 20 characters left at the end of a
-line, since either the comment or the code will inevitably get longer
-than will fit, and then somebody will have to move it anyhow.
-
-16.4.6 C Usage
---------------
-
-Code must not depend on the sizes of C data types, the format of the
-host's floating point numbers, the alignment of anything, or the order
-of evaluation of expressions.
-
- Use functions freely. There are only a handful of compute-bound
-areas in GDB that might be affected by the overhead of a function call,
-mainly in symbol reading. Most of GDB's performance is limited by the
-target interface (whether serial line or system call).
-
- However, use functions with moderation. A thousand one-line
-functions are just as hard to understand as a single thousand-line
-function.
-
- _Macros are bad, M'kay._ (But if you have to use a macro, make sure
-that the macro arguments are protected with parentheses.)
-
- Declarations like `struct foo *' should be used in preference to
-declarations like `typedef struct foo { ... } *foo_ptr'.
-
-16.4.7 Function Prototypes
---------------------------
-
-Prototypes must be used when both _declaring_ and _defining_ a
-function. Prototypes for GDB functions must include both the argument
-type and name, with the name matching that used in the actual function
-definition.
-
- All external functions should have a declaration in a header file
-that callers include, except for `_initialize_*' functions, which must
-be external so that `init.c' construction works, but shouldn't be
-visible to random source files.
-
- Where a source file needs a forward declaration of a static function,
-that declaration must appear in a block near the top of the source file.
-
-16.4.8 Internal Error Recovery
-------------------------------
-
-During its execution, GDB can encounter two types of errors. User
-errors and internal errors. User errors include not only a user
-entering an incorrect command but also problems arising from corrupt
-object files and system errors when interacting with the target.
-Internal errors include situations where GDB has detected, at run time,
-a corrupt or erroneous situation.
-
- When reporting an internal error, GDB uses `internal_error' and
-`gdb_assert'.
-
- GDB must not call `abort' or `assert'.
-
- _Pragmatics: There is no `internal_warning' function. Either the
-code detected a user error, recovered from it and issued a `warning' or
-the code failed to correctly recover from the user error and issued an
-`internal_error'._
-
-16.4.9 File Names
------------------
-
-Any file used when building the core of GDB must be in lower case. Any
-file used when building the core of GDB must be 8.3 unique. These
-requirements apply to both source and generated files.
-
- _Pragmatics: The core of GDB must be buildable on many platforms
-including DJGPP and MacOS/HFS. Every time an unfriendly file is
-introduced to the build process both `Makefile.in' and `configure.in'
-need to be modified accordingly. Compare the convoluted conversion
-process needed to transform `COPYING' into `copying.c' with the
-conversion needed to transform `version.in' into `version.c'._
-
- Any file non 8.3 compliant file (that is not used when building the
-core of GDB) must be added to `gdb/config/djgpp/fnchange.lst'.
-
- _Pragmatics: This is clearly a compromise._
-
- When GDB has a local version of a system header file (ex `string.h')
-the file name based on the POSIX header prefixed with `gdb_'
-(`gdb_string.h'). These headers should be relatively independent: they
-should use only macros defined by `configure', the compiler, or the
-host; they should include only system headers; they should refer only
-to system types. They may be shared between multiple programs, e.g.
-GDB and GDBSERVER.
-
- For other files `-' is used as the separator.
-
-16.4.10 Include Files
----------------------
-
-A `.c' file should include `defs.h' first.
-
- A `.c' file should directly include the `.h' file of every
-declaration and/or definition it directly refers to. It cannot rely on
-indirect inclusion.
-
- A `.h' file should directly include the `.h' file of every
-declaration and/or definition it directly refers to. It cannot rely on
-indirect inclusion. Exception: The file `defs.h' does not need to be
-directly included.
-
- An external declaration should only appear in one include file.
-
- An external declaration should never appear in a `.c' file.
-Exception: a declaration for the `_initialize' function that pacifies
-`-Wmissing-declaration'.
-
- A `typedef' definition should only appear in one include file.
-
- An opaque `struct' declaration can appear in multiple `.h' files.
-Where possible, a `.h' file should use an opaque `struct' declaration
-instead of an include.
-
- All `.h' files should be wrapped in:
-
- #ifndef INCLUDE_FILE_NAME_H
- #define INCLUDE_FILE_NAME_H
- header body
- #endif
-
-16.4.11 Clean Design and Portable Implementation
-------------------------------------------------
-
-In addition to getting the syntax right, there's the little question of
-semantics. Some things are done in certain ways in GDB because long
-experience has shown that the more obvious ways caused various kinds of
-trouble.
-
- You can't assume the byte order of anything that comes from a target
-(including VALUEs, object files, and instructions). Such things must
-be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
-routines defined in `bfd.h', such as `bfd_get_32'.
-
- You can't assume that you know what interface is being used to talk
-to the target system. All references to the target must go through the
-current `target_ops' vector.
-
- You can't assume that the host and target machines are the same
-machine (except in the "native" support modules). In particular, you
-can't assume that the target machine's header files will be available
-on the host machine. Target code must bring along its own header files
-- written from scratch or explicitly donated by their owner, to avoid
-copyright problems.
-
- Insertion of new `#ifdef''s will be frowned upon. It's much better
-to write the code portably than to conditionalize it for various
-systems.
-
- New `#ifdef''s which test for specific compilers or manufacturers or
-operating systems are unacceptable. All `#ifdef''s should test for
-features. The information about which configurations contain which
-features should be segregated into the configuration files. Experience
-has proven far too often that a feature unique to one particular system
-often creeps into other systems; and that a conditional based on some
-predefined macro for your current system will become worthless over
-time, as new versions of your system come out that behave differently
-with regard to this feature.
-
- Adding code that handles specific architectures, operating systems,
-target interfaces, or hosts, is not acceptable in generic code.
-
- One particularly notorious area where system dependencies tend to
-creep in is handling of file names. The mainline GDB code assumes
-Posix semantics of file names: absolute file names begin with a forward
-slash `/', slashes are used to separate leading directories,
-case-sensitive file names. These assumptions are not necessarily true
-on non-Posix systems such as MS-Windows. To avoid system-dependent
-code where you need to take apart or construct a file name, use the
-following portable macros:
-
-`HAVE_DOS_BASED_FILE_SYSTEM'
- This preprocessing symbol is defined to a non-zero value on hosts
- whose filesystems belong to the MS-DOS/MS-Windows family. Use this
- symbol to write conditional code which should only be compiled for
- such hosts.
-
-`IS_DIR_SEPARATOR (C)'
- Evaluates to a non-zero value if C is a directory separator
- character. On Unix and GNU/Linux systems, only a slash `/' is
- such a character, but on Windows, both `/' and `\' will pass.
-
-`IS_ABSOLUTE_PATH (FILE)'
- Evaluates to a non-zero value if FILE is an absolute file name.
- For Unix and GNU/Linux hosts, a name which begins with a slash `/'
- is absolute. On DOS and Windows, `d:/foo' and `x:\bar' are also
- absolute file names.
-
-`FILENAME_CMP (F1, F2)'
- Calls a function which compares file names F1 and F2 as
- appropriate for the underlying host filesystem. For Posix systems,
- this simply calls `strcmp'; on case-insensitive filesystems it
- will call `strcasecmp' instead.
-
-`DIRNAME_SEPARATOR'
- Evaluates to a character which separates directories in
- `PATH'-style lists, typically held in environment variables. This
- character is `:' on Unix, `;' on DOS and Windows.
-
-`SLASH_STRING'
- This evaluates to a constant string you should use to produce an
- absolute filename from leading directories and the file's basename.
- `SLASH_STRING' is `"/"' on most systems, but might be `"\\"' for
- some Windows-based ports.
-
- In addition to using these macros, be sure to use portable library
-functions whenever possible. For example, to extract a directory or a
-basename part from a file name, use the `dirname' and `basename'
-library functions (available in `libiberty' for platforms which don't
-provide them), instead of searching for a slash with `strrchr'.
-
- Another way to generalize GDB along a particular interface is with an
-attribute struct. For example, GDB has been generalized to handle
-multiple kinds of remote interfaces--not by `#ifdef's everywhere, but
-by defining the `target_ops' structure and having a current target (as
-well as a stack of targets below it, for memory references). Whenever
-something needs to be done that depends on which remote interface we are
-using, a flag in the current target_ops structure is tested (e.g.,
-`target_has_stack'), or a function is called through a pointer in the
-current target_ops structure. In this way, when a new remote interface
-is added, only one module needs to be touched--the one that actually
-implements the new remote interface. Other examples of
-attribute-structs are BFD access to multiple kinds of object file
-formats, or GDB's access to multiple source languages.
-
- Please avoid duplicating code. For example, in GDB 3.x all the code
-interfacing between `ptrace' and the rest of GDB was duplicated in
-`*-dep.c', and so changing something was very painful. In GDB 4.x,
-these have all been consolidated into `infptrace.c'. `infptrace.c' can
-deal with variations between systems the same way any system-independent
-file would (hooks, `#if defined', etc.), and machines which are
-radically different don't need to use `infptrace.c' at all.
-
- All debugging code must be controllable using the `set debug MODULE'
-command. Do not use `printf' to print trace messages. Use
-`fprintf_unfiltered(gdb_stdlog, ...'. Do not use `#ifdef DEBUG'.
-
-\1f
-File: gdbint.info, Node: Porting GDB, Next: Versions and Branches, Prev: Coding, Up: Top
-
-17 Porting GDB
-**************
-
-Most of the work in making GDB compile on a new machine is in
-specifying the configuration of the machine. Porting a new
-architecture to GDB can be broken into a number of steps.
-
- * Ensure a BFD exists for executables of the target architecture in
- the `bfd' directory. If one does not exist, create one by
- modifying an existing similar one.
-
- * Implement a disassembler for the target architecture in the
- `opcodes' directory.
-
- * Define the target architecture in the `gdb' directory (*note
- Adding a New Target: Adding a New Target.). Add the pattern for
- the new target to `configure.tgt' with the names of the files that
- contain the code. By convention the target architecture
- definition for an architecture ARCH is placed in `ARCH-tdep.c'.
-
- Within `ARCH-tdep.c' define the function `_initialize_ARCH_tdep'
- which calls `gdbarch_register' to create the new `struct gdbarch'
- for the architecture.
-
- * If a new remote target is needed, consider adding a new remote
- target by defining a function `_initialize_remote_ARCH'. However
- if at all possible use the GDB _Remote Serial Protocol_ for this
- and implement the server side protocol independently with the
- target.
-
- * If desired implement a simulator in the `sim' directory. This
- should create the library `libsim.a' implementing the interface in
- `remote-sim.h' (found in the `include' directory).
-
- * Build and test. If desired, lobby the GDB steering group to have
- the new port included in the main distribution!
-
- * Add a description of the new architecture to the main GDB user
- guide (*note Configuration Specific Information:
- (gdb)Configuration Specific Information.).
-
-
-\1f
-File: gdbint.info, Node: Versions and Branches, Next: Start of New Year Procedure, Prev: Porting GDB, Up: Top
-
-18 Versions and Branches
-************************
-
-18.1 Versions
-=============
-
-GDB's version is determined by the file `gdb/version.in' and takes one
-of the following forms:
-
-MAJOR.MINOR
-MAJOR.MINOR.PATCHLEVEL
- an official release (e.g., 6.2 or 6.2.1)
-
-MAJOR.MINOR.PATCHLEVEL.YYYYMMDD
- a snapshot taken at YYYY-MM-DD-gmt (e.g., 6.1.50.20020302,
- 6.1.90.20020304, or 6.1.0.20020308)
-
-MAJOR.MINOR.PATCHLEVEL.YYYYMMDD-cvs
- a CVS check out drawn on YYYY-MM-DD (e.g., 6.1.50.20020302-cvs,
- 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
-
-MAJOR.MINOR.PATCHLEVEL.YYYYMMDD (VENDOR)
- a vendor specific release of GDB, that while based on
- MAJOR.MINOR.PATCHLEVEL.YYYYMMDD, may include additional changes
-
- GDB's mainline uses the MAJOR and MINOR version numbers from the
-most recent release branch, with a PATCHLEVEL of 50. At the time each
-new release branch is created, the mainline's MAJOR and MINOR version
-numbers are updated.
-
- GDB's release branch is similar. When the branch is cut, the
-PATCHLEVEL is changed from 50 to 90. As draft releases are drawn from
-the branch, the PATCHLEVEL is incremented. Once the first release
-(MAJOR.MINOR) has been made, the PATCHLEVEL is set to 0 and updates
-have an incremented PATCHLEVEL.
-
- For snapshots, and CVS check outs, it is also possible to identify
-the CVS origin:
-
-MAJOR.MINOR.50.YYYYMMDD
- drawn from the HEAD of mainline CVS (e.g., 6.1.50.20020302)
-
-MAJOR.MINOR.90.YYYYMMDD
-MAJOR.MINOR.91.YYYYMMDD ...
- drawn from a release branch prior to the release (e.g.,
- 6.1.90.20020304)
-
-MAJOR.MINOR.0.YYYYMMDD
-MAJOR.MINOR.1.YYYYMMDD ...
- drawn from a release branch after the release (e.g.,
- 6.2.0.20020308)
-
- If the previous GDB version is 6.1 and the current version is 6.2,
-then, substituting 6 for MAJOR and 1 or 2 for MINOR, here's an
-illustration of a typical sequence:
-
- <HEAD>
- |
- 6.1.50.20020302-cvs
- |
- +--------------------------.
- | <gdb_6_2-branch>
- | |
- 6.2.50.20020303-cvs 6.1.90 (draft #1)
- | |
- 6.2.50.20020304-cvs 6.1.90.20020304-cvs
- | |
- 6.2.50.20020305-cvs 6.1.91 (draft #2)
- | |
- 6.2.50.20020306-cvs 6.1.91.20020306-cvs
- | |
- 6.2.50.20020307-cvs 6.2 (release)
- | |
- 6.2.50.20020308-cvs 6.2.0.20020308-cvs
- | |
- 6.2.50.20020309-cvs 6.2.1 (update)
- | |
- 6.2.50.20020310-cvs <branch closed>
- |
- 6.2.50.20020311-cvs
- |
- +--------------------------.
- | <gdb_6_3-branch>
- | |
- 6.3.50.20020312-cvs 6.2.90 (draft #1)
- | |
-
-18.2 Release Branches
-=====================
-
-GDB draws a release series (6.2, 6.2.1, ...) from a single release
-branch, and identifies that branch using the CVS branch tags:
-
- gdb_MAJOR_MINOR-YYYYMMDD-branchpoint
- gdb_MAJOR_MINOR-branch
- gdb_MAJOR_MINOR-YYYYMMDD-release
-
- _Pragmatics: To help identify the date at which a branch or release
-is made, both the branchpoint and release tags include the date that
-they are cut (YYYYMMDD) in the tag. The branch tag, denoting the head
-of the branch, does not need this._
-
-18.3 Vendor Branches
-====================
-
-To avoid version conflicts, vendors are expected to modify the file
-`gdb/version.in' to include a vendor unique alphabetic identifier (an
-official GDB release never uses alphabetic characters in its version
-identifier). E.g., `6.2widgit2', or `6.2 (Widgit Inc Patch 2)'.
-
-18.4 Experimental Branches
-==========================
-
-18.4.1 Guidelines
------------------
-
-GDB permits the creation of branches, cut from the CVS repository, for
-experimental development. Branches make it possible for developers to
-share preliminary work, and maintainers to examine significant new
-developments.
-
- The following are a set of guidelines for creating such branches:
-
-_a branch has an owner_
- The owner can set further policy for a branch, but may not change
- the ground rules. In particular, they can set a policy for
- commits (be it adding more reviewers or deciding who can commit).
-
-_all commits are posted_
- All changes committed to a branch shall also be posted to the GDB
- patches mailing list <gdb-patches@sourceware.org>. While
- commentary on such changes are encouraged, people should remember
- that the changes only apply to a branch.
-
-_all commits are covered by an assignment_
- This ensures that all changes belong to the Free Software
- Foundation, and avoids the possibility that the branch may become
- contaminated.
-
-_a branch is focused_
- A focused branch has a single objective or goal, and does not
- contain unnecessary or irrelevant changes. Cleanups, where
- identified, being be pushed into the mainline as soon as possible.
-
-_a branch tracks mainline_
- This keeps the level of divergence under control. It also keeps
- the pressure on developers to push cleanups and other stuff into
- the mainline.
-
-_a branch shall contain the entire GDB module_
- The GDB module `gdb' should be specified when creating a branch
- (branches of individual files should be avoided). *Note Tags::.
-
-_a branch shall be branded using `version.in'_
- The file `gdb/version.in' shall be modified so that it identifies
- the branch OWNER and branch NAME, e.g.,
- `6.2.50.20030303_owner_name' or `6.2 (Owner Name)'.
-
-
-18.4.2 Tags
------------
-
-To simplify the identification of GDB branches, the following branch
-tagging convention is strongly recommended:
-
-`OWNER_NAME-YYYYMMDD-branchpoint'
-`OWNER_NAME-YYYYMMDD-branch'
- The branch point and corresponding branch tag. YYYYMMDD is the
- date that the branch was created. A branch is created using the
- sequence:
- cvs rtag OWNER_NAME-YYYYMMDD-branchpoint gdb
- cvs rtag -b -r OWNER_NAME-YYYYMMDD-branchpoint \
- OWNER_NAME-YYYYMMDD-branch gdb
-
-`OWNER_NAME-YYYYMMDD-mergepoint'
- The tagged point, on the mainline, that was used when merging the
- branch on YYYYMMDD. To merge in all changes since the branch was
- cut, use a command sequence like:
- cvs rtag OWNER_NAME-YYYYMMDD-mergepoint gdb
- cvs update \
- -jOWNER_NAME-YYYYMMDD-branchpoint
- -jOWNER_NAME-YYYYMMDD-mergepoint
- Similar sequences can be used to just merge in changes since the
- last merge.
-
-
-For further information on CVS, see Concurrent Versions System
-(http://www.gnu.org/software/cvs/).
-
-\1f
-File: gdbint.info, Node: Start of New Year Procedure, Next: Releasing GDB, Prev: Versions and Branches, Up: Top
-
-19 Start of New Year Procedure
-******************************
-
-At the start of each new year, the following actions should be
-performed:
-
- * Rotate the ChangeLog file
-
- The current `ChangeLog' file should be renamed into
- `ChangeLog-YYYY' where YYYY is the year that has just passed. A
- new `ChangeLog' file should be created, and its contents should
- contain a reference to the previous ChangeLog. The following
- should also be preserved at the end of the new ChangeLog, in order
- to provide the appropriate settings when editing this file with
- Emacs:
- Local Variables:
- mode: change-log
- left-margin: 8
- fill-column: 74
- version-control: never
- coding: utf-8
- End:
-
- * Add an entry for the newly created ChangeLog file
- (`ChangeLog-YYYY') in `gdb/config/djgpp/fnchange.lst'.
-
- * Update the copyright year in the startup message
-
- Update the copyright year in:
- * file `top.c', function `print_gdb_version'
-
- * file `gdbserver/server.c', function `gdbserver_version'
-
- * file `gdbserver/gdbreplay.c', function `gdbreplay_version'
-
- * Run the `copyright.sh' script to add the new year in the copyright
- notices of most source files. This script requires Emacs 22 or
- later to be installed.
-
- * The new year also needs to be added manually in all other files
- that are not already taken care of by the `copyright.sh' script:
- * `*.s'
-
- * `*.f'
-
- * `*.f90'
-
- * `*.igen'
-
- * `*.ac'
-
- * `*.texi'
-
- * `*.texinfo'
-
- * `*.tex'
-
- * `*.defs'
-
- * `*.1'
-
-
-\1f
-File: gdbint.info, Node: Releasing GDB, Next: Testsuite, Prev: Start of New Year Procedure, Up: Top
-
-20 Releasing GDB
-****************
-
-20.1 Branch Commit Policy
-=========================
-
-The branch commit policy is pretty slack. GDB releases 5.0, 5.1 and
-5.2 all used the below:
-
- * The `gdb/MAINTAINERS' file still holds.
-
- * Don't fix something on the branch unless/until it is also fixed in
- the trunk. If this isn't possible, mentioning it in the
- `gdb/PROBLEMS' file is better than committing a hack.
-
- * When considering a patch for the branch, suggested criteria
- include: Does it fix a build? Does it fix the sequence `break
- main; run' when debugging a static binary?
-
- * The further a change is from the core of GDB, the less likely the
- change will worry anyone (e.g., target specific code).
-
- * Only post a proposal to change the core of GDB after you've sent
- individual bribes to all the people listed in the `MAINTAINERS'
- file ;-)
-
- _Pragmatics: Provided updates are restricted to non-core
-functionality there is little chance that a broken change will be fatal.
-This means that changes such as adding a new architectures or (within
-reason) support for a new host are considered acceptable._
-
-20.2 Obsoleting code
-====================
-
-Before anything else, poke the other developers (and around the source
-code) to see if there is anything that can be removed from GDB (an old
-target, an unused file).
-
- Obsolete code is identified by adding an `OBSOLETE' prefix to every
-line. Doing this means that it is easy to identify something that has
-been obsoleted when greping through the sources.
-
- The process is done in stages -- this is mainly to ensure that the
-wider GDB community has a reasonable opportunity to respond. Remember,
-everything on the Internet takes a week.
-
- 1. Post the proposal on the GDB mailing list <gdb@sourceware.org>
- Creating a bug report to track the task's state, is also highly
- recommended.
-
- 2. Wait a week or so.
-
- 3. Post the proposal on the GDB Announcement mailing list
- <gdb-announce@sourceware.org>.
-
- 4. Wait a week or so.
-
- 5. Go through and edit all relevant files and lines so that they are
- prefixed with the word `OBSOLETE'.
-
- 6. Wait until the next GDB version, containing this obsolete code,
- has been released.
-
- 7. Remove the obsolete code.
-
-_Maintainer note: While removing old code is regrettable it is
-hopefully better for GDB's long term development. Firstly it helps the
-developers by removing code that is either no longer relevant or simply
-wrong. Secondly since it removes any history associated with the file
-(effectively clearing the slate) the developer has a much freer hand
-when it comes to fixing broken files._
-
-20.3 Before the Branch
-======================
-
-The most important objective at this stage is to find and fix simple
-changes that become a pain to track once the branch is created. For
-instance, configuration problems that stop GDB from even building. If
-you can't get the problem fixed, document it in the `gdb/PROBLEMS' file.
-
-Prompt for `gdb/NEWS'
----------------------
-
-People always forget. Send a post reminding them but also if you know
-something interesting happened add it yourself. The `schedule' script
-will mention this in its e-mail.
-
-Review `gdb/README'
--------------------
-
-Grab one of the nightly snapshots and then walk through the
-`gdb/README' looking for anything that can be improved. The `schedule'
-script will mention this in its e-mail.
-
-Refresh any imported files.
----------------------------
-
-A number of files are taken from external repositories. They include:
-
- * `texinfo/texinfo.tex'
-
- * `config.guess' et. al. (see the top-level `MAINTAINERS' file)
-
- * `etc/standards.texi', `etc/make-stds.texi'
-
-Check the ARI
--------------
-
-A.R.I. is an `awk' script (Awk Regression Index ;-) that checks for a
-number of errors and coding conventions. The checks include things
-like using `malloc' instead of `xmalloc' and file naming problems.
-There shouldn't be any regressions.
-
-20.3.1 Review the bug data base
--------------------------------
-
-Close anything obviously fixed.
-
-20.3.2 Check all cross targets build
-------------------------------------
-
-The targets are listed in `gdb/MAINTAINERS'.
-
-20.4 Cut the Branch
-===================
-
-Create the branch
------------------
-
- $ u=5.1
- $ v=5.2
- $ V=`echo $v | sed 's/\./_/g'`
- $ D=`date -u +%Y-%m-%d`
- $ echo $u $V $D
- 5.1 5_2 2002-03-03
- $ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
- -D $D-gmt gdb_$V-$D-branchpoint insight
- cvs -f -d :ext:sourceware.org:/cvs/src rtag
- -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
- $ ^echo ^^
- ...
- $ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
- -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
- cvs -f -d :ext:sourceware.org:/cvs/src rtag \
- -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
- $ ^echo ^^
- ...
- $
-
- * By using `-D YYYY-MM-DD-gmt', the branch is forced to an exact
- date/time.
-
- * The trunk is first tagged so that the branch point can easily be
- found.
-
- * Insight, which includes GDB, is tagged at the same time.
-
- * `version.in' gets bumped to avoid version number conflicts.
-
- * The reading of `.cvsrc' is disabled using `-f'.
-
-Update `version.in'
--------------------
-
- $ u=5.1
- $ v=5.2
- $ V=`echo $v | sed 's/\./_/g'`
- $ echo $u $v$V
- 5.1 5_2
- $ cd /tmp
- $ echo cvs -f -d :ext:sourceware.org:/cvs/src co \
- -r gdb_$V-branch src/gdb/version.in
- cvs -f -d :ext:sourceware.org:/cvs/src co
- -r gdb_5_2-branch src/gdb/version.in
- $ ^echo ^^
- U src/gdb/version.in
- $ cd src/gdb
- $ echo $u.90-0000-00-00-cvs > version.in
- $ cat version.in
- 5.1.90-0000-00-00-cvs
- $ cvs -f commit version.in
-
- * `0000-00-00' is used as a date to pump prime the version.in update
- mechanism.
-
- * `.90' and the previous branch version are used as fairly arbitrary
- initial branch version number.
-
-Update the web and news pages
------------------------------
-
-Something?
-
-Tweak cron to track the new branch
-----------------------------------
-
-The file `gdbadmin/cron/crontab' contains gdbadmin's cron table. This
-file needs to be updated so that:
-
- * A daily timestamp is added to the file `version.in'.
-
- * The new branch is included in the snapshot process.
-
-See the file `gdbadmin/cron/README' for how to install the updated cron
-table.
-
- The file `gdbadmin/ss/README' should also be reviewed to reflect any
-changes. That file is copied to both the branch/ and current/ snapshot
-directories.
-
-Update the NEWS and README files
---------------------------------
-
-The `NEWS' file needs to be updated so that on the branch it refers to
-_changes in the current release_ while on the trunk it also refers to
-_changes since the current release_.
-
- The `README' file needs to be updated so that it refers to the
-current release.
-
-Post the branch info
---------------------
-
-Send an announcement to the mailing lists:
-
- * GDB Announcement mailing list <gdb-announce@sourceware.org>
-
- * GDB Discussion mailing list <gdb@sourceware.org> and GDB Testers
- mailing list <gdb-testers@sourceware.org>
-
- _Pragmatics: The branch creation is sent to the announce list to
-ensure that people people not subscribed to the higher volume discussion
-list are alerted._
-
- The announcement should include:
-
- * The branch tag.
-
- * How to check out the branch using CVS.
-
- * The date/number of weeks until the release.
-
- * The branch commit policy still holds.
-
-20.5 Stabilize the branch
-=========================
-
-Something goes here.
-
-20.6 Create a Release
-=====================
-
-The process of creating and then making available a release is broken
-down into a number of stages. The first part addresses the technical
-process of creating a releasable tar ball. The later stages address the
-process of releasing that tar ball.
-
- When making a release candidate just the first section is needed.
-
-20.6.1 Create a release candidate
----------------------------------
-
-The objective at this stage is to create a set of tar balls that can be
-made available as a formal release (or as a less formal release
-candidate).
-
-Freeze the branch
-.................
-
-Send out an e-mail notifying everyone that the branch is frozen to
-<gdb-patches@sourceware.org>.
-
-Establish a few defaults.
-.........................
-
- $ b=gdb_5_2-branch
- $ v=5.2
- $ t=/sourceware/snapshot-tmp/gdbadmin-tmp
- $ echo $t/$b/$v
- /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
- $ mkdir -p $t/$b/$v
- $ cd $t/$b/$v
- $ pwd
- /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
- $ which autoconf
- /home/gdbadmin/bin/autoconf
- $
-
-Notes:
-
- * Check the `autoconf' version carefully. You want to be using the
- version documented in the toplevel `README-maintainer-mode' file.
- It is very unlikely that the version of `autoconf' installed in
- system directories (e.g., `/usr/bin/autoconf') is correct.
-
-Check out the relevant modules:
-...............................
-
- $ for m in gdb insight
- do
- ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
- done
- $
-
-Note:
-
- * The reading of `.cvsrc' is disabled (`-f') so that there isn't any
- confusion between what is written here and what your local `cvs'
- really does.
-
-Update relevant files.
-......................
-
-`gdb/NEWS'
- Major releases get their comments added as part of the mainline.
- Minor releases should probably mention any significant bugs that
- were fixed.
-
- Don't forget to include the `ChangeLog' entry.
-
- $ emacs gdb/src/gdb/NEWS
- ...
- c-x 4 a
- ...
- c-x c-s c-x c-c
- $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
- $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-
-`gdb/README'
- You'll need to update:
-
- * The version.
-
- * The update date.
-
- * Who did it.
-
- $ emacs gdb/src/gdb/README
- ...
- c-x 4 a
- ...
- c-x c-s c-x c-c
- $ cp gdb/src/gdb/README insight/src/gdb/README
- $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-
- _Maintainer note: Hopefully the `README' file was reviewed before
- the initial branch was cut so just a simple substitute is needed
- to get it updated._
-
- _Maintainer note: Other projects generate `README' and `INSTALL'
- from the core documentation. This might be worth pursuing._
-
-`gdb/version.in'
- $ echo $v > gdb/src/gdb/version.in
- $ cat gdb/src/gdb/version.in
- 5.2
- $ emacs gdb/src/gdb/version.in
- ...
- c-x 4 a
- ... Bump to version ...
- c-x c-s c-x c-c
- $ cp gdb/src/gdb/version.in insight/src/gdb/version.in
- $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-
-
-Do the dirty work
-.................
-
-This is identical to the process used to create the daily snapshot.
-
- $ for m in gdb insight
- do
- ( cd $m/src && gmake -f src-release $m.tar )
- done
-
- If the top level source directory does not have `src-release' (GDB
-version 5.3.1 or earlier), try these commands instead:
-
- $ for m in gdb insight
- do
- ( cd $m/src && gmake -f Makefile.in $m.tar )
- done
-
-Check the source files
-......................
-
-You're looking for files that have mysteriously disappeared.
-`distclean' has the habit of deleting files it shouldn't. Watch out
-for the `version.in' update `cronjob'.
-
- $ ( cd gdb/src && cvs -f -q -n update )
- M djunpack.bat
- ? gdb-5.1.91.tar
- ? proto-toplev
- ... lots of generated files ...
- M gdb/ChangeLog
- M gdb/NEWS
- M gdb/README
- M gdb/version.in
- ... lots of generated files ...
- $
-
-_Don't worry about the `gdb.info-??' or `gdb/p-exp.tab.c'. They were
-generated (and yes `gdb.info-1' was also generated only something
-strange with CVS means that they didn't get suppressed). Fixing it
-would be nice though._
-
-Create compressed versions of the release
-.........................................
-
- $ cp */src/*.tar .
- $ cp */src/*.bz2 .
- $ ls -F
- gdb/ gdb-5.2.tar insight/ insight-5.2.tar
- $ for m in gdb insight
- do
- bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
- gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
- done
- $
-
-Note:
-
- * A pipe such as `bunzip2 < xxx.bz2 | gzip -9 > xxx.gz' is not since,
- in that mode, `gzip' does not know the name of the file and, hence,
- can not include it in the compressed file. This is also why the
- release process runs `tar' and `bzip2' as separate passes.
-
-20.6.2 Sanity check the tar ball
---------------------------------
-
-Pick a popular machine (Solaris/PPC?) and try the build on that.
-
- $ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
- $ cd gdb-5.2
- $ ./configure
- $ make
- ...
- $ ./gdb/gdb ./gdb/gdb
- GNU gdb 5.2
- ...
- (gdb) b main
- Breakpoint 1 at 0x80732bc: file main.c, line 734.
- (gdb) run
- Starting program: /tmp/gdb-5.2/gdb/gdb
-
- Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
- 734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
- (gdb) print args
- $1 = {argc = 136426532, argv = 0x821b7f0}
- (gdb)
-
-20.6.3 Make a release candidate available
------------------------------------------
-
-If this is a release candidate then the only remaining steps are:
-
- 1. Commit `version.in' and `ChangeLog'
-
- 2. Tweak `version.in' (and `ChangeLog' to read L.M.N-0000-00-00-cvs
- so that the version update process can restart.
-
- 3. Make the release candidate available in
- `ftp://sourceware.org/pub/gdb/snapshots/branch'
-
- 4. Notify the relevant mailing lists ( <gdb@sourceware.org> and
- <gdb-testers@sourceware.org> that the candidate is available.
-
-20.6.4 Make a formal release available
---------------------------------------
-
-(And you thought all that was required was to post an e-mail.)
-
-Install on sware
-................
-
-Copy the new files to both the release and the old release directory:
-
- $ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
- $ cp *.bz2 *.gz ~ftp/pub/gdb/releases
-
-Clean up the releases directory so that only the most recent releases
-are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
-
- $ cd ~ftp/pub/gdb/releases
- $ rm ...
-
-Update the file `README' and `.message' in the releases directory:
-
- $ vi README
- ...
- $ rm -f .message
- $ ln README .message
-
-Update the web pages.
-.....................
-
-`htdocs/download/ANNOUNCEMENT'
- This file, which is posted as the official announcement, includes:
- * General announcement.
-
- * News. If making an M.N.1 release, retain the news from
- earlier M.N release.
-
- * Errata.
-
-`htdocs/index.html'
-`htdocs/news/index.html'
-`htdocs/download/index.html'
- These files include:
- * Announcement of the most recent release.
-
- * News entry (remember to update both the top level and the
- news directory).
- These pages also need to be regenerate using `index.sh'.
-
-`download/onlinedocs/'
- You need to find the magic command that is used to generate the
- online docs from the `.tar.bz2'. The best way is to look in the
- output from one of the nightly `cron' jobs and then just edit
- accordingly. Something like:
-
- $ ~/ss/update-web-docs \
- ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
- $PWD/www \
- /www/sourceware/htdocs/gdb/download/onlinedocs \
- gdb
-
-`download/ari/'
- Just like the online documentation. Something like:
-
- $ /bin/sh ~/ss/update-web-ari \
- ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
- $PWD/www \
- /www/sourceware/htdocs/gdb/download/ari \
- gdb
-
-
-Shadow the pages onto gnu
-.........................
-
-Something goes here.
-
-Install the GDB tar ball on GNU
-...............................
-
-At the time of writing, the GNU machine was `gnudist.gnu.org' in
-`~ftp/gnu/gdb'.
-
-Make the `ANNOUNCEMENT'
-.......................
-
-Post the `ANNOUNCEMENT' file you created above to:
-
- * GDB Announcement mailing list <gdb-announce@sourceware.org>
-
- * General GNU Announcement list <info-gnu@gnu.org> (but delay it a
- day or so to let things get out)
-
- * GDB Bug Report mailing list <bug-gdb@gnu.org>
-
-20.6.5 Cleanup
---------------
-
-The release is out but you're still not finished.
-
-Commit outstanding changes
-..........................
-
-In particular you'll need to commit any changes to:
-
- * `gdb/ChangeLog'
-
- * `gdb/version.in'
-
- * `gdb/NEWS'
-
- * `gdb/README'
-
-Tag the release
-...............
-
-Something like:
-
- $ d=`date -u +%Y-%m-%d`
- $ echo $d
- 2002-01-24
- $ ( cd insight/src/gdb && cvs -f -q update )
- $ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
-
- Insight is used since that contains more of the release than GDB.
-
-Mention the release on the trunk
-................................
-
-Just put something in the `ChangeLog' so that the trunk also indicates
-when the release was made.
-
-Restart `gdb/version.in'
-........................
-
-If `gdb/version.in' does not contain an ISO date such as `2002-01-24'
-then the daily `cronjob' won't update it. Having committed all the
-release changes it can be set to `5.2.0_0000-00-00-cvs' which will
-restart things (yes the `_' is important - it affects the snapshot
-process).
-
- Don't forget the `ChangeLog'.
-
-Merge into trunk
-................
-
-The files committed to the branch may also need changes merged into the
-trunk.
-
-Revise the release schedule
-...........................
-
-Post a revised release schedule to GDB Discussion List
-<gdb@sourceware.org> with an updated announcement. The schedule can be
-generated by running:
-
- $ ~/ss/schedule `date +%s` schedule
-
-The first parameter is approximate date/time in seconds (from the epoch)
-of the most recent release.
-
- Also update the schedule `cronjob'.
-
-20.7 Post release
-=================
-
-Remove any `OBSOLETE' code.
-
-\1f
-File: gdbint.info, Node: Testsuite, Next: Hints, Prev: Releasing GDB, Up: Top
-
-21 Testsuite
-************
-
-The testsuite is an important component of the GDB package. While it
-is always worthwhile to encourage user testing, in practice this is
-rarely sufficient; users typically use only a small subset of the
-available commands, and it has proven all too common for a change to
-cause a significant regression that went unnoticed for some time.
-
- The GDB testsuite uses the DejaGNU testing framework. The tests
-themselves are calls to various `Tcl' procs; the framework runs all the
-procs and summarizes the passes and fails.
-
-21.1 Using the Testsuite
-========================
-
-To run the testsuite, simply go to the GDB object directory (or to the
-testsuite's objdir) and type `make check'. This just sets up some
-environment variables and invokes DejaGNU's `runtest' script. While
-the testsuite is running, you'll get mentions of which test file is in
-use, and a mention of any unexpected passes or fails. When the
-testsuite is finished, you'll get a summary that looks like this:
-
- === gdb Summary ===
-
- # of expected passes 6016
- # of unexpected failures 58
- # of unexpected successes 5
- # of expected failures 183
- # of unresolved testcases 3
- # of untested testcases 5
-
- To run a specific test script, type:
- make check RUNTESTFLAGS='TESTS'
- where TESTS is a list of test script file names, separated by spaces.
-
- If you use GNU make, you can use its `-j' option to run the
-testsuite in parallel. This can greatly reduce the amount of time it
-takes for the testsuite to run. In this case, if you set
-`RUNTESTFLAGS' then, by default, the tests will be run serially even
-under `-j'. You can override this and force a parallel run by setting
-the `make' variable `FORCE_PARALLEL' to any non-empty value. Note that
-the parallel `make check' assumes that you want to run the entire
-testsuite, so it is not compatible with some dejagnu options, like
-`--directory'.
-
- The ideal test run consists of expected passes only; however, reality
-conspires to keep us from this ideal. Unexpected failures indicate
-real problems, whether in GDB or in the testsuite. Expected failures
-are still failures, but ones which have been decided are too hard to
-deal with at the time; for instance, a test case might work everywhere
-except on AIX, and there is no prospect of the AIX case being fixed in
-the near future. Expected failures should not be added lightly, since
-you may be masking serious bugs in GDB. Unexpected successes are
-expected fails that are passing for some reason, while unresolved and
-untested cases often indicate some minor catastrophe, such as the
-compiler being unable to deal with a test program.
-
- When making any significant change to GDB, you should run the
-testsuite before and after the change, to confirm that there are no
-regressions. Note that truly complete testing would require that you
-run the testsuite with all supported configurations and a variety of
-compilers; however this is more than really necessary. In many cases
-testing with a single configuration is sufficient. Other useful
-options are to test one big-endian (Sparc) and one little-endian (x86)
-host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
-or a 64-bit host (Alpha).
-
- If you add new functionality to GDB, please consider adding tests
-for it as well; this way future GDB hackers can detect and fix their
-changes that break the functionality you added. Similarly, if you fix
-a bug that was not previously reported as a test failure, please add a
-test case for it. Some cases are extremely difficult to test, such as
-code that handles host OS failures or bugs in particular versions of
-compilers, and it's OK not to try to write tests for all of those.
-
- DejaGNU supports separate build, host, and target machines. However,
-some GDB test scripts do not work if the build machine and the host
-machine are not the same. In such an environment, these scripts will
-give a result of "UNRESOLVED", like this:
-
- UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
-
-21.2 Testsuite Parameters
-=========================
-
-Several variables exist to modify the behavior of the testsuite.
-
- * `TRANSCRIPT'
-
- Sometimes it is convenient to get a transcript of the commands
- which the testsuite sends to GDB. For example, if GDB crashes
- during testing, a transcript can be used to more easily
- reconstruct the failure when running GDB under GDB.
-
- You can instruct the GDB testsuite to write transcripts by setting
- the DejaGNU variable `TRANSCRIPT' (to any value) before invoking
- `runtest' or `make check'. The transcripts will be written into
- DejaGNU's output directory. One transcript will be made for each
- invocation of GDB; they will be named `transcript.N', where N is
- an integer. The first line of the transcript file will show how
- GDB was invoked; each subsequent line is a command sent as input
- to GDB.
-
- make check RUNTESTFLAGS=TRANSCRIPT=y
-
- Note that the transcript is not always complete. In particular,
- tests of completion can yield partial command lines.
-
- * `GDB'
-
- Sometimes one wishes to test a different GDB than the one in the
- build directory. For example, one may wish to run the testsuite on
- `/usr/bin/gdb'.
-
- make check RUNTESTFLAGS=GDB=/usr/bin/gdb
-
- * `GDBSERVER'
-
- When testing a different GDB, it is often useful to also test a
- different gdbserver.
-
- make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"
-
- * `INTERNAL_GDBFLAGS'
-
- When running the testsuite normally one doesn't want whatever is in
- `~/.gdbinit' to interfere with the tests, therefore the test
- harness passes `-nx' to GDB. One also doesn't want any windowed
- version of GDB, e.g., `gdbtui', to run. This is achieved via
- `INTERNAL_GDBFLAGS'.
-
- set INTERNAL_GDBFLAGS "-nw -nx"
-
- This is all well and good, except when testing an installed GDB
- that has been configured with `--with-system-gdbinit'. Here one
- does not want `~/.gdbinit' loaded but one may want the system
- `.gdbinit' file loaded. This can be achieved by pointing `$HOME'
- at a directory without a `.gdbinit' and by overriding
- `INTERNAL_GDBFLAGS' and removing `-nx'.
-
- cd testsuite
- HOME=`pwd` runtest \
- GDB=/usr/bin/gdb \
- GDBSERVER=/usr/bin/gdbserver \
- INTERNAL_GDBFLAGS=-nw
-
-
- There are two ways to run the testsuite and pass additional
-parameters to DejaGnu. The first is with `make check' and specifying
-the makefile variable `RUNTESTFLAGS'.
-
- make check RUNTESTFLAGS=TRANSCRIPT=y
-
- The second is to cd to the `testsuite' directory and invoke the
-DejaGnu `runtest' command directly.
-
- cd testsuite
- make site.exp
- runtest TRANSCRIPT=y
-
-21.3 Testsuite Configuration
-============================
-
-It is possible to adjust the behavior of the testsuite by defining the
-global variables listed below, either in a `site.exp' file, or in a
-board file.
-
- * `gdb_test_timeout'
-
- Defining this variable changes the default timeout duration used
- during communication with GDB. More specifically, the global
- variable used during testing is `timeout', but this variable gets
- reset to `gdb_test_timeout' at the beginning of each testcase,
- making sure that any local change to `timeout' in a testcase does
- not affect subsequent testcases.
-
- This global variable comes in handy when the debugger is slower
- than normal due to the testing environment, triggering unexpected
- `TIMEOUT' test failures. Examples include when testing on a
- remote machine, or against a system where communications are slow.
-
- If not specifically defined, this variable gets automatically
- defined to the same value as `timeout' during the testsuite
- initialization. The default value of the timeout is defined in
- the file `gdb/testsuite/config/unix.exp' that is part of the GDB
- test suite(1).
-
-
-21.4 Testsuite Organization
-===========================
-
-The testsuite is entirely contained in `gdb/testsuite'. While the
-testsuite includes some makefiles and configury, these are very minimal,
-and used for little besides cleaning up, since the tests themselves
-handle the compilation of the programs that GDB will run. The file
-`testsuite/lib/gdb.exp' contains common utility procs useful for all
-GDB tests, while the directory `testsuite/config' contains
-configuration-specific files, typically used for special-purpose
-definitions of procs like `gdb_load' and `gdb_start'.
-
- The tests themselves are to be found in `testsuite/gdb.*' and
-subdirectories of those. The names of the test files must always end
-with `.exp'. DejaGNU collects the test files by wildcarding in the
-test directories, so both subdirectories and individual files get
-chosen and run in alphabetical order.
-
- The following table lists the main types of subdirectories and what
-they are for. Since DejaGNU finds test files no matter where they are
-located, and since each test file sets up its own compilation and
-execution environment, this organization is simply for convenience and
-intelligibility.
-
-`gdb.base'
- This is the base testsuite. The tests in it should apply to all
- configurations of GDB (but generic native-only tests may live
- here). The test programs should be in the subset of C that is
- valid K&R, ANSI/ISO, and C++ (`#ifdef's are allowed if necessary,
- for instance for prototypes).
-
-`gdb.LANG'
- Language-specific tests for any language LANG besides C. Examples
- are `gdb.cp' and `gdb.java'.
-
-`gdb.PLATFORM'
- Non-portable tests. The tests are specific to a specific
- configuration (host or target), such as HP-UX or eCos. Example is
- `gdb.hp', for HP-UX.
-
-`gdb.COMPILER'
- Tests specific to a particular compiler. As of this writing (June
- 1999), there aren't currently any groups of tests in this category
- that couldn't just as sensibly be made platform-specific, but one
- could imagine a `gdb.gcc', for tests of GDB's handling of GCC
- extensions.
-
-`gdb.SUBSYSTEM'
- Tests that exercise a specific GDB subsystem in more depth. For
- instance, `gdb.disasm' exercises various disassemblers, while
- `gdb.stabs' tests pathways through the stabs symbol reader.
-
-21.5 Writing Tests
-==================
-
-In many areas, the GDB tests are already quite comprehensive; you
-should be able to copy existing tests to handle new cases.
-
- You should try to use `gdb_test' whenever possible, since it
-includes cases to handle all the unexpected errors that might happen.
-However, it doesn't cost anything to add new test procedures; for
-instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
-`gdb_test' multiple times.
-
- Only use `send_gdb' and `gdb_expect' when absolutely necessary.
-Even if GDB has several valid responses to a command, you can use
-`gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes
-internal errors and unexpected prompts.
-
- Do not write tests which expect a literal tab character from GDB.
-On some operating systems (e.g. OpenBSD) the TTY layer expands tabs to
-spaces, so by the time GDB's output reaches expect the tab is gone.
-
- The source language programs do _not_ need to be in a consistent
-style. Since GDB is used to debug programs written in many different
-styles, it's worth having a mix of styles in the testsuite; for
-instance, some GDB bugs involving the display of source lines would
-never manifest themselves if the programs used GNU coding style
-uniformly.
-
- ---------- Footnotes ----------
-
- (1) If you are using a board file, it could override the test-suite
-default; search the board file for "timeout".
-
-\1f
-File: gdbint.info, Node: Hints, Next: GDB Observers, Prev: Testsuite, Up: Top
-
-22 Hints
-********
-
-Check the `README' file, it often has useful information that does not
-appear anywhere else in the directory.
-
-* Menu:
-
-* Getting Started:: Getting started working on GDB
-* Debugging GDB:: Debugging GDB with itself
-
-\1f
-File: gdbint.info, Node: Getting Started, Up: Hints
-
-22.1 Getting Started
-====================
-
-GDB is a large and complicated program, and if you first starting to
-work on it, it can be hard to know where to start. Fortunately, if you
-know how to go about it, there are ways to figure out what is going on.
-
- This manual, the GDB Internals manual, has information which applies
-generally to many parts of GDB.
-
- Information about particular functions or data structures are
-located in comments with those functions or data structures. If you
-run across a function or a global variable which does not have a
-comment correctly explaining what is does, this can be thought of as a
-bug in GDB; feel free to submit a bug report, with a suggested comment
-if you can figure out what the comment should say. If you find a
-comment which is actually wrong, be especially sure to report that.
-
- Comments explaining the function of macros defined in host, target,
-or native dependent files can be in several places. Sometimes they are
-repeated every place the macro is defined. Sometimes they are where the
-macro is used. Sometimes there is a header file which supplies a
-default definition of the macro, and the comment is there. This manual
-also documents all the available macros.
-
- Start with the header files. Once you have some idea of how GDB's
-internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
-will find it much easier to understand the code which uses and creates
-those symbol tables.
-
- You may wish to process the information you are getting somehow, to
-enhance your understanding of it. Summarize it, translate it to another
-language, add some (perhaps trivial or non-useful) feature to GDB, use
-the code to predict what a test case would do and write the test case
-and verify your prediction, etc. If you are reading code and your eyes
-are starting to glaze over, this is a sign you need to use a more active
-approach.
-
- Once you have a part of GDB to start with, you can find more
-specifically the part you are looking for by stepping through each
-function with the `next' command. Do not use `step' or you will
-quickly get distracted; when the function you are stepping through
-calls another function try only to get a big-picture understanding
-(perhaps using the comment at the beginning of the function being
-called) of what it does. This way you can identify which of the
-functions being called by the function you are stepping through is the
-one which you are interested in. You may need to examine the data
-structures generated at each stage, with reference to the comments in
-the header files explaining what the data structures are supposed to
-look like.
-
- Of course, this same technique can be used if you are just reading
-the code, rather than actually stepping through it. The same general
-principle applies--when the code you are looking at calls something
-else, just try to understand generally what the code being called does,
-rather than worrying about all its details.
-
- A good place to start when tracking down some particular area is with
-a command which invokes that feature. Suppose you want to know how
-single-stepping works. As a GDB user, you know that the `step' command
-invokes single-stepping. The command is invoked via command tables
-(see `command.h'); by convention the function which actually performs
-the command is formed by taking the name of the command and adding
-`_command', or in the case of an `info' subcommand, `_info'. For
-example, the `step' command invokes the `step_command' function and the
-`info display' command invokes `display_info'. When this convention is
-not followed, you might have to use `grep' or `M-x tags-search' in
-emacs, or run GDB on itself and set a breakpoint in `execute_command'.
-
- If all of the above fail, it may be appropriate to ask for
-information on `bug-gdb'. But _never_ post a generic question like "I
-was wondering if anyone could give me some tips about understanding
-GDB"--if we had some magic secret we would put it in this manual.
-Suggestions for improving the manual are always welcome, of course.
-
-\1f
-File: gdbint.info, Node: Debugging GDB, Up: Hints
-
-22.2 Debugging GDB with itself
-==============================
-
-If GDB is limping on your machine, this is the preferred way to get it
-fully functional. Be warned that in some ancient Unix systems, like
-Ultrix 4.2, a program can't be running in one process while it is being
-debugged in another. Rather than typing the command `./gdb ./gdb',
-which works on Suns and such, you can copy `gdb' to `gdb2' and then
-type `./gdb ./gdb2'.
-
- When you run GDB in the GDB source directory, it will read a
-`.gdbinit' file that sets up some simple things to make debugging gdb
-easier. The `info' command, when executed without a subcommand in a
-GDB being debugged by gdb, will pop you back up to the top level gdb.
-See `.gdbinit' for details.
-
- If you use emacs, you will probably want to do a `make TAGS' after
-you configure your distribution; this will put the machine dependent
-routines for your local machine where they will be accessed first by
-`M-.'
-
- Also, make sure that you've either compiled GDB with your local cc,
-or have run `fixincludes' if you are compiling with gcc.
-
-22.3 Submitting Patches
-=======================
-
-Thanks for thinking of offering your changes back to the community of
-GDB users. In general we like to get well designed enhancements.
-Thanks also for checking in advance about the best way to transfer the
-changes.
-
- The GDB maintainers will only install "cleanly designed" patches.
-This manual summarizes what we believe to be clean design for GDB.
-
- If the maintainers don't have time to put the patch in when it
-arrives, or if there is any question about a patch, it goes into a
-large queue with everyone else's patches and bug reports.
-
- The legal issue is that to incorporate substantial changes requires a
-copyright assignment from you and/or your employer, granting ownership
-of the changes to the Free Software Foundation. You can get the
-standard documents for doing this by sending mail to `gnu@gnu.org' and
-asking for it. We recommend that people write in "All programs owned
-by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
-in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
-contributed with only one piece of legalese pushed through the
-bureaucracy and filed with the FSF. We can't start merging changes
-until this paperwork is received by the FSF (their rules, which we
-follow since we maintain it for them).
-
- Technically, the easiest way to receive changes is to receive each
-feature as a small context diff or unidiff, suitable for `patch'. Each
-message sent to me should include the changes to C code and header
-files for a single feature, plus `ChangeLog' entries for each directory
-where files were modified, and diffs for any changes needed to the
-manuals (`gdb/doc/gdb.texinfo' or `gdb/doc/gdbint.texinfo'). If there
-are a lot of changes for a single feature, they can be split down into
-multiple messages.
-
- In this way, if we read and like the feature, we can add it to the
-sources with a single patch command, do some testing, and check it in.
-If you leave out the `ChangeLog', we have to write one. If you leave
-out the doc, we have to puzzle out what needs documenting. Etc., etc.
-
- The reason to send each change in a separate message is that we will
-not install some of the changes. They'll be returned to you with
-questions or comments. If we're doing our job correctly, the message
-back to you will say what you have to fix in order to make the change
-acceptable. The reason to have separate messages for separate features
-is so that the acceptable changes can be installed while one or more
-changes are being reworked. If multiple features are sent in a single
-message, we tend to not put in the effort to sort out the acceptable
-changes from the unacceptable, so none of the features get installed
-until all are acceptable.
-
- If this sounds painful or authoritarian, well, it is. But we get a
-lot of bug reports and a lot of patches, and many of them don't get
-installed because we don't have the time to finish the job that the bug
-reporter or the contributor could have done. Patches that arrive
-complete, working, and well designed, tend to get installed on the day
-they arrive. The others go into a queue and get installed as time
-permits, which, since the maintainers have many demands to meet, may not
-be for quite some time.
-
- Please send patches directly to the GDB maintainers
-<gdb-patches@sourceware.org>.
-
-22.4 Build Script
-=================
-
-The script `gdb_buildall.sh' builds GDB with flag
-`--enable-targets=all' set. This builds GDB with all supported targets
-activated. This helps testing GDB when doing changes that affect more
-than one architecture and is much faster than using `gdb_mbuild.sh'.
-
- After building GDB the script checks which architectures are
-supported and then switches the current architecture to each of those
-to get information about the architecture. The test results are stored
-in log files in the directory the script was called from.
-
-\1f
-File: gdbint.info, Node: GDB Observers, Next: GNU Free Documentation License, Prev: Hints, Up: Top
-
-Appendix A GDB Currently available observers
-********************************************
-
-A.1 Implementation rationale
-============================
-
-An "observer" is an entity which is interested in being notified when
-GDB reaches certain states, or certain events occur in GDB. The entity
-being observed is called the "subject". To receive notifications, the
-observer attaches a callback to the subject. One subject can have
-several observers.
-
- `observer.c' implements an internal generic low-level event
-notification mechanism. This generic event notification mechanism is
-then re-used to implement the exported high-level notification
-management routines for all possible notifications.
-
- The current implementation of the generic observer provides support
-for contextual data. This contextual data is given to the subject when
-attaching the callback. In return, the subject will provide this
-contextual data back to the observer as a parameter of the callback.
-
- Note that the current support for the contextual data is only
-partial, as it lacks a mechanism that would deallocate this data when
-the callback is detached. This is not a problem so far, as this
-contextual data is only used internally to hold a function pointer.
-Later on, if a certain observer needs to provide support for user-level
-contextual data, then the generic notification mechanism will need to be
-enhanced to allow the observer to provide a routine to deallocate the
-data when attaching the callback.
-
- The observer implementation is also currently not reentrant. In
-particular, it is therefore not possible to call the attach or detach
-routines during a notification.
-
-A.2 Debugging
-=============
-
-Observer notifications can be traced using the command `set debug
-observer 1' (*note Optional messages about internal happenings:
-(gdb)Debugging Output.).
-
-A.3 `normal_stop' Notifications
-===============================
-
-GDB notifies all `normal_stop' observers when the inferior execution
-has just stopped, the associated messages and annotations have been
-printed, and the control is about to be returned to the user.
-
- Note that the `normal_stop' notification is not emitted when the
-execution stops due to a breakpoint, and this breakpoint has a
-condition that is not met. If the breakpoint has any associated
-commands list, the commands are executed after the notification is
-emitted.
-
- The following interfaces are available to manage observers:
-
- -- Function: extern struct observer *observer_attach_EVENT
- (observer_EVENT_ftype *F)
- Using the function F, create an observer that is notified when
- ever EVENT occurs, return the observer.
-
- -- Function: extern void observer_detach_EVENT (struct observer
- *OBSERVER);
- Remove OBSERVER from the list of observers to be notified when
- EVENT occurs.
-
- -- Function: extern void observer_notify_EVENT (void);
- Send a notification to all EVENT observers.
-
- The following observable events are defined:
-
- -- Function: void normal_stop (struct bpstats *BS, int PRINT_FRAME)
- The inferior has stopped for real. The BS argument describes the
- breakpoints were are stopped at, if any. Second argument
- PRINT_FRAME non-zero means display the location where the inferior
- has stopped.
-
- -- Function: void target_changed (struct target_ops *TARGET)
- The target's register contents have changed.
-
- -- Function: void executable_changed (void)
- The executable being debugged by GDB has changed: The user decided
- to debug a different program, or the program he was debugging has
- been modified since being loaded by the debugger (by being
- recompiled, for instance).
-
- -- Function: void inferior_created (struct target_ops *OBJFILE, int
- FROM_TTY)
- GDB has just connected to an inferior. For `run', GDB calls this
- observer while the inferior is still stopped at the entry-point
- instruction. For `attach' and `core', GDB calls this observer
- immediately after connecting to the inferior, and before any
- information on the inferior has been printed.
-
- -- Function: void solib_loaded (struct so_list *SOLIB)
- The shared library specified by SOLIB has been loaded. Note that
- when GDB calls this observer, the library's symbols probably
- haven't been loaded yet.
-
- -- Function: void solib_unloaded (struct so_list *SOLIB)
- The shared library specified by SOLIB has been unloaded. Note
- that when GDB calls this observer, the library's symbols have not
- been unloaded yet, and thus are still available.
-
- -- Function: void new_objfile (struct objfile *OBJFILE)
- The symbol file specified by OBJFILE has been loaded. Called with
- OBJFILE equal to `NULL' to indicate previously loaded symbol table
- data has now been invalidated.
-
- -- Function: void new_thread (struct thread_info *T)
- The thread specified by T has been created.
-
- -- Function: void thread_exit (struct thread_info *T, int SILENT)
- The thread specified by T has exited. The SILENT argument
- indicates that GDB is removing the thread from its tables without
- wanting to notify the user about it.
-
- -- Function: void thread_stop_requested (ptid_t PTID)
- An explicit stop request was issued to PTID. If PTID equals
- MINUS_ONE_PTID, the request applied to all threads. If
- `ptid_is_pid(ptid)' returns true, the request applied to all
- threads of the process pointed at by PTID. Otherwise, the request
- applied to the single thread pointed at by PTID.
-
- -- Function: void target_resumed (ptid_t PTID)
- The target was resumed. The PTID parameter specifies which thread
- was resume, and may be RESUME_ALL if all threads are resumed.
-
- -- Function: void about_to_proceed (void)
- The target is about to be proceeded.
-
- -- Function: void breakpoint_created (int BPNUM)
- A new breakpoint has been created. The argument BPNUM is the
- number of the newly-created breakpoint.
-
- -- Function: void breakpoint_deleted (int BPNUM)
- A breakpoint has been destroyed. The argument BPNUM is the number
- of the newly-destroyed breakpoint.
-
- -- Function: void breakpoint_modified (int BPNUM)
- A breakpoint has been modified in some way. The argument BPNUM is
- the number of the modified breakpoint.
-
- -- Function: void tracepoint_created (int TPNUM)
- A new tracepoint has been created. The argument TPNUM is the
- number of the newly-created tracepoint.
-
- -- Function: void tracepoint_deleted (int TPNUM)
- A tracepoint has been destroyed. The argument TPNUM is the number
- of the newly-destroyed tracepoint.
-
- -- Function: void tracepoint_modified (int TPNUM)
- A tracepoint has been modified in some way. The argument TPNUM is
- the number of the modified tracepoint.
-
- -- Function: void architecture_changed (struct gdbarch *NEWARCH)
- The current architecture has changed. The argument NEWARCH is a
- pointer to the new architecture.
-
- -- Function: void thread_ptid_changed (ptid_t OLD_PTID, ptid_t
- NEW_PTID)
- The thread's ptid has changed. The OLD_PTID parameter specifies
- the old value, and NEW_PTID specifies the new value.
-
- -- Function: void inferior_appeared (int PID)
- GDB has attached to a new inferior identified by PID.
-
- -- Function: void inferior_exit (int PID)
- Either GDB detached from the inferior, or the inferior exited.
- The argument PID identifies the inferior.
-
- -- Function: void memory_changed (CORE_ADDR ADDR, int LEN, const
- bfd_byte *DATA)
- Bytes from DATA to DATA + LEN have been written to the current
- inferior at ADDR.
-
- -- Function: void test_notification (int SOMEARG)
- This observer is used for internal testing. Do not use. See
- testsuite/gdb.gdb/observer.exp.
-
-\1f
-File: gdbint.info, Node: GNU Free Documentation License, Next: Index, Prev: GDB Observers, Up: Top
-
-Appendix B GNU Free Documentation License
-*****************************************
-
- Version 1.2, November 2002
-
- Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- functional and useful document "free" in the sense of freedom: to
- assure everyone the effective freedom to copy and redistribute it,
- with or without modifying it, either commercially or
- noncommercially. Secondarily, this License preserves for the
- author and publisher a way to get credit for their work, while not
- being considered responsible for modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work, in any medium,
- that contains a notice placed by the copyright holder saying it
- can be distributed under the terms of this License. Such a notice
- grants a world-wide, royalty-free license, unlimited in duration,
- to use that work under the conditions stated herein. The
- "Document", below, refers to any such manual or work. Any member
- of the public is a licensee, and is addressed as "you". You
- accept the license if you copy, modify or distribute the work in a
- way requiring permission under copyright law.
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter section
- of the Document that deals exclusively with the relationship of the
- publishers or authors of the Document to the Document's overall
- subject (or to related matters) and contains nothing that could
- fall directly within that overall subject. (Thus, if the Document
- is in part a textbook of mathematics, a Secondary Section may not
- explain any mathematics.) The relationship could be a matter of
- historical connection with the subject or with related matters, or
- of legal, commercial, philosophical, ethical or political position
- regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License. If a section does not fit the above definition of
- Secondary then it is not allowed to be designated as Invariant.
- The Document may contain zero Invariant Sections. If the Document
- does not identify any Invariant Sections then there are none.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License. A
- Front-Cover Text may be at most 5 words, and a Back-Cover Text may
- be at most 25 words.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, that is suitable for revising the document
- straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup, or absence of
- markup, has been arranged to thwart or discourage subsequent
- modification by readers is not Transparent. An image format is
- not Transparent if used for any substantial amount of text. A
- copy that is not "Transparent" is called "Opaque".
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML, PostScript or PDF designed for
- human modification. Examples of transparent image formats include
- PNG, XCF and JPG. Opaque formats include proprietary formats that
- can be read and edited only by proprietary word processors, SGML or
- XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML, PostScript or PDF
- produced by some word processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- A section "Entitled XYZ" means a named subunit of the Document
- whose title either is precisely XYZ or contains XYZ in parentheses
- following text that translates XYZ in another language. (Here XYZ
- stands for a specific section name mentioned below, such as
- "Acknowledgements", "Dedications", "Endorsements", or "History".)
- To "Preserve the Title" of such a section when you modify the
- Document means that it remains a section "Entitled XYZ" according
- to this definition.
-
- The Document may include Warranty Disclaimers next to the notice
- which states that this License applies to the Document. These
- Warranty Disclaimers are considered to be included by reference in
- this License, but only as regards disclaiming warranties: any other
- implication that these Warranty Disclaimers may have is void and
- has no effect on the meaning of this License.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies (or copies in media that commonly
- have printed covers) of the Document, numbering more than 100, and
- the Document's license notice requires Cover Texts, you must
- enclose the copies in covers that carry, clearly and legibly, all
- these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a computer-network location from
- which the general network-using public has access to download
- using public-standard network protocols a complete Transparent
- copy of the Document, free of added material. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of
- previous versions (which should, if there were any, be listed
- in the History section of the Document). You may use the
- same title as a previous version if the original publisher of
- that version gives permission.
-
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in
- the Modified Version, together with at least five of the
- principal authors of the Document (all of its principal
- authors, if it has fewer than five), unless they release you
- from this requirement.
-
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
- D. Preserve all the copyright notices of the Document.
-
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified
- Version under the terms of this License, in the form shown in
- the Addendum below.
-
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
-
- H. Include an unaltered copy of this License.
-
- I. Preserve the section Entitled "History", Preserve its Title,
- and add to it an item stating at least the title, year, new
- authors, and publisher of the Modified Version as given on
- the Title Page. If there is no section Entitled "History" in
- the Document, create one stating the title, year, authors,
- and publisher of the Document as given on its Title Page,
- then add an item describing the Modified Version as stated in
- the previous sentence.
-
- J. Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in
- the "History" section. You may omit a network location for a
- work that was published at least four years before the
- Document itself, or if the original publisher of the version
- it refers to gives permission.
-
- K. For any section Entitled "Acknowledgements" or "Dedications",
- Preserve the Title of the section, and preserve in the
- section all the substance and tone of each of the contributor
- acknowledgements and/or dedications given therein.
-
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section
- titles.
-
- M. Delete any section Entitled "Endorsements". Such a section
- may not be included in the Modified Version.
-
- N. Do not retitle any existing section to be Entitled
- "Endorsements" or to conflict in title with any Invariant
- Section.
-
- O. Preserve any Warranty Disclaimers.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section Entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice, and that you preserve all
- their Warranty Disclaimers.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections Entitled
- "History" in the various original documents, forming one section
- Entitled "History"; likewise combine any sections Entitled
- "Acknowledgements", and any sections Entitled "Dedications". You
- must delete all sections Entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, is called an "aggregate" if the
- copyright resulting from the compilation is not used to limit the
- legal rights of the compilation's users beyond what the individual
- works permit. When the Document is included in an aggregate, this
- License does not apply to the other works in the aggregate which
- are not themselves derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one half
- of the entire aggregate, the Document's Cover Texts may be placed
- on covers that bracket the Document within the aggregate, or the
- electronic equivalent of covers if the Document is in electronic
- form. Otherwise they must appear on printed covers that bracket
- the whole aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License, and all the license notices in the
- Document, and any Warranty Disclaimers, provided that you also
- include the original English version of this License and the
- original versions of those notices and disclaimers. In case of a
- disagreement between the translation and the original version of
- this License or a notice or disclaimer, the original version will
- prevail.
-
- If a section in the Document is Entitled "Acknowledgements",
- "Dedications", or "History", the requirement (section 4) to
- Preserve its Title (section 1) will typically require changing the
- actual title.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- `http://www.gnu.org/copyleft/'.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-B.1 ADDENDUM: How to use this License for your documents
-========================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.2
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-
- If you have Invariant Sections, Front-Cover Texts and Back-Cover
-Texts, replace the "with...Texts." line with this:
-
- with the Invariant Sections being LIST THEIR TITLES, with
- the Front-Cover Texts being LIST, and with the Back-Cover Texts
- being LIST.
-
- If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: gdbint.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
-
-Index
-*****
-
-\0\b[index\0\b]
-* Menu:
-
-* $fp: Register Information Functions.
- (line 126)
-* $pc: Register Architecture Functions & Variables.
- (line 58)
-* $ps: Register Architecture Functions & Variables.
- (line 69)
-* $sp: Register Architecture Functions & Variables.
- (line 49)
-* _initialize_ARCH_tdep <1>: Adding a New Target. (line 22)
-* _initialize_ARCH_tdep: How an Architecture is Represented.
- (line 13)
-* _initialize_language: Language Support. (line 79)
-* a.out format: Symbol Handling. (line 213)
-* about_to_proceed: GDB Observers. (line 133)
-* abstract interpretation of function prologues: Algorithms. (line 48)
-* add_cmd: User Interface. (line 21)
-* add_com: User Interface. (line 21)
-* add_setshow_cmd: User Interface. (line 26)
-* add_setshow_cmd_full: User Interface. (line 26)
-* add_symtab_fns: Symbol Handling. (line 37)
-* adding a new host: Host Definition. (line 13)
-* adding a symbol-reading module: Symbol Handling. (line 37)
-* adding a target: Adding a New Target. (line 6)
-* adding debugging info reader: Symbol Handling. (line 360)
-* adding source language: Language Support. (line 17)
-* address classes: Address Classes. (line 6)
-* address representation: Pointers and Addresses.
- (line 6)
-* address spaces, separate data and code: Pointers and Addresses.
- (line 6)
-* address_class_name_to_type_flags: Defining Other Architecture Features.
- (line 28)
-* address_class_name_to_type_flags_p: Defining Other Architecture Features.
- (line 39)
-* algorithms: Algorithms. (line 6)
-* align_down: Functions and Variable to Analyze Frames.
- (line 46)
-* align_up: Functions and Variable to Analyze Frames.
- (line 46)
-* allocate_symtab: Language Support. (line 83)
-* ARCH-tdep.c: How an Architecture is Represented.
- (line 13)
-* architecture representation: How an Architecture is Represented.
- (line 6)
-* architecture_changed: GDB Observers. (line 160)
-* Array Containers: Support Libraries. (line 131)
-* assumptions about targets: Coding. (line 514)
-* ATTR_NORETURN: Host Definition. (line 126)
-* base of a frame: Frame Handling Terminology.
- (line 28)
-* BFD library: Support Libraries. (line 9)
-* bfd_arch_info: Looking Up an Existing Architecture.
- (line 41)
-* BIG_BREAKPOINT: Defining Other Architecture Features.
- (line 100)
-* BPT_VECTOR: Defining Other Architecture Features.
- (line 536)
-* BREAKPOINT: Defining Other Architecture Features.
- (line 88)
-* breakpoint address adjusted: Defining Other Architecture Features.
- (line 145)
-* breakpoint_created: GDB Observers. (line 136)
-* breakpoint_deleted: GDB Observers. (line 140)
-* breakpoint_modified: GDB Observers. (line 144)
-* breakpoints: Algorithms. (line 151)
-* bug-gdb mailing list: Getting Started. (line 72)
-* build script: Debugging GDB. (line 94)
-* C data types: Coding. (line 389)
-* call frame information: Algorithms. (line 14)
-* call stack frame: Stack Frames. (line 6)
-* calls to the inferior: Inferior Call Setup. (line 6)
-* CANNOT_STEP_HW_WATCHPOINTS: Algorithms. (line 408)
-* CC_HAS_LONG_LONG: Host Definition. (line 105)
-* CFI (call frame information): Algorithms. (line 14)
-* checkpoints: Algorithms. (line 604)
-* cleanups: Coding. (line 12)
-* CLI: User Interface. (line 12)
-* code pointers, word-addressed: Pointers and Addresses.
- (line 6)
-* coding standards: Coding. (line 215)
-* COFF debugging info: Symbol Handling. (line 310)
-* COFF format: Symbol Handling. (line 228)
-* command implementation: Getting Started. (line 60)
-* command interpreter: User Interface. (line 12)
-* comment formatting: Coding. (line 363)
-* compiler warnings: Coding. (line 271)
-* Compressed DWARF 2 debugging info: Symbol Handling. (line 330)
-* computed values: Values. (line 35)
-* configure.tgt: How an Architecture is Represented.
- (line 19)
-* converting between pointers and addresses: Pointers and Addresses.
- (line 6)
-* converting integers to addresses: Defining Other Architecture Features.
- (line 274)
-* cooked register representation: Raw and Cooked Registers.
- (line 6)
-* core files: Adding support for debugging core files.
- (line 6)
-* core_addr_greaterthan: Functions and Variable to Analyze Frames.
- (line 30)
-* core_addr_lessthan: Functions and Variable to Analyze Frames.
- (line 30)
-* CRLF_SOURCE_FILES: Host Definition. (line 86)
-* current_language: Language Support. (line 75)
-* D10V addresses: Pointers and Addresses.
- (line 6)
-* data output: User Interface. (line 254)
-* data-pointer, per-architecture/per-module: Coding. (line 100)
-* debugging GDB: Debugging GDB. (line 6)
-* DEFAULT_PROMPT: Host Definition. (line 93)
-* deprecate_cmd: User Interface. (line 32)
-* DEPRECATED_IBM6000_TARGET: Defining Other Architecture Features.
- (line 242)
-* deprecating commands: User Interface. (line 32)
-* design: Coding. (line 509)
-* DEV_TTY: Host Definition. (line 96)
-* DIRNAME_SEPARATOR: Coding. (line 579)
-* DISABLE_UNSETTABLE_BREAK: Defining Other Architecture Features.
- (line 211)
-* discard_cleanups: Coding. (line 39)
-* do_cleanups: Coding. (line 35)
-* DOS text files: Host Definition. (line 87)
-* dummy frames: About Dummy Frames. (line 6)
-* DW_AT_address_class: Address Classes. (line 6)
-* DW_AT_byte_size: Address Classes. (line 6)
-* DWARF 2 debugging info: Symbol Handling. (line 323)
-* DWARF 3 debugging info: Symbol Handling. (line 350)
-* ECOFF debugging info: Symbol Handling. (line 316)
-* ECOFF format: Symbol Handling. (line 243)
-* ELF format: Symbol Handling. (line 276)
-* evaluate_subexp: Language Support. (line 58)
-* executable_changed: GDB Observers. (line 85)
-* execution state: Managing Execution State.
- (line 6)
-* experimental branches: Versions and Branches.
- (line 116)
-* expression evaluation routines: Language Support. (line 58)
-* expression parser: Language Support. (line 21)
-* extract_typed_address: Pointers and Addresses.
- (line 52)
-* FDL, GNU Free Documentation License: GNU Free Documentation License.
- (line 6)
-* field output functions: User Interface. (line 254)
-* file names, portability: Coding. (line 547)
-* FILENAME_CMP: Coding. (line 573)
-* find_pc_function: Symbol Handling. (line 136)
-* find_pc_line: Symbol Handling. (line 136)
-* find_sym_fns: Symbol Handling. (line 32)
-* finding a symbol: Symbol Handling. (line 133)
-* fine-tuning gdbarch structure: OS ABI Variant Handling.
- (line 23)
-* first floating point register: Register Architecture Functions & Variables.
- (line 78)
-* FOPEN_RB: Host Definition. (line 102)
-* fp0_regnum: Register Architecture Functions & Variables.
- (line 78)
-* frame: Stack Frames. (line 6)
-* frame ID: Stack Frames. (line 41)
-* frame pointer: Register Information Functions.
- (line 126)
-* frame, definition of base of a frame: Frame Handling Terminology.
- (line 28)
-* frame, definition of innermost frame: Frame Handling Terminology.
- (line 24)
-* frame, definition of NEXT frame: Frame Handling Terminology.
- (line 11)
-* frame, definition of PREVIOUS frame: Frame Handling Terminology.
- (line 14)
-* frame, definition of sentinel frame: Frame Handling Terminology.
- (line 52)
-* frame, definition of sniffing: Frame Handling Terminology.
- (line 46)
-* frame, definition of THIS frame: Frame Handling Terminology.
- (line 9)
-* frame, definition of unwinding: Frame Handling Terminology.
- (line 41)
-* frame_align: Functions and Variable to Analyze Frames.
- (line 46)
-* frame_base: Analyzing Stacks---Frame Sniffers.
- (line 89)
-* frame_base_append_sniffer: Analyzing Stacks---Frame Sniffers.
- (line 19)
-* frame_base_set_default: Analyzing Stacks---Frame Sniffers.
- (line 22)
-* frame_num_args: Functions to Access Frame Data.
- (line 43)
-* frame_red_zone_size: Functions and Variable to Analyze Frames.
- (line 63)
-* frame_register_unwind: Stack Frames. (line 15)
-* frame_unwind: Analyzing Stacks---Frame Sniffers.
- (line 36)
-* frame_unwind_append_sniffer: Analyzing Stacks---Frame Sniffers.
- (line 16)
-* frame_unwind_append_unwinder: Stack Frames. (line 30)
-* frame_unwind_got_address: Stack Frames. (line 105)
-* frame_unwind_got_constant: Stack Frames. (line 101)
-* frame_unwind_got_memory: Stack Frames. (line 98)
-* frame_unwind_got_optimized: Stack Frames. (line 90)
-* frame_unwind_got_register: Stack Frames. (line 93)
-* frame_unwind_prepend_unwinder: Stack Frames. (line 30)
-* full symbol table: Symbol Handling. (line 104)
-* function prologue: Prologue Caches. (line 6)
-* function prototypes: Coding. (line 411)
-* function usage: Coding. (line 393)
-* fundamental types: Symbol Handling. (line 178)
-* GCC2_COMPILED_FLAG_SYMBOL: Defining Other Architecture Features.
- (line 225)
-* GCC_COMPILED_FLAG_SYMBOL: Defining Other Architecture Features.
- (line 225)
-* GDB source tree structure: Overall Structure. (line 83)
-* gdb_byte: Register Caching. (line 23)
-* GDB_OSABI_AIX: OS ABI Variant Handling.
- (line 90)
-* GDB_OSABI_CYGWIN: OS ABI Variant Handling.
- (line 87)
-* GDB_OSABI_FREEBSD_AOUT: OS ABI Variant Handling.
- (line 51)
-* GDB_OSABI_FREEBSD_ELF: OS ABI Variant Handling.
- (line 54)
-* GDB_OSABI_GO32: OS ABI Variant Handling.
- (line 69)
-* GDB_OSABI_HPUX_ELF: OS ABI Variant Handling.
- (line 78)
-* GDB_OSABI_HPUX_SOM: OS ABI Variant Handling.
- (line 81)
-* GDB_OSABI_HURD: OS ABI Variant Handling.
- (line 39)
-* GDB_OSABI_INTERIX: OS ABI Variant Handling.
- (line 75)
-* GDB_OSABI_IRIX: OS ABI Variant Handling.
- (line 72)
-* GDB_OSABI_LINUX: OS ABI Variant Handling.
- (line 48)
-* GDB_OSABI_NETBSD_AOUT: OS ABI Variant Handling.
- (line 57)
-* GDB_OSABI_NETBSD_ELF: OS ABI Variant Handling.
- (line 60)
-* GDB_OSABI_OPENBSD_ELF: OS ABI Variant Handling.
- (line 63)
-* GDB_OSABI_OSF1: OS ABI Variant Handling.
- (line 45)
-* GDB_OSABI_QNXNTO: OS ABI Variant Handling.
- (line 84)
-* GDB_OSABI_SOLARIS: OS ABI Variant Handling.
- (line 42)
-* GDB_OSABI_SVR4: OS ABI Variant Handling.
- (line 36)
-* GDB_OSABI_UNINITIALIZED: OS ABI Variant Handling.
- (line 29)
-* GDB_OSABI_UNKNOWN: OS ABI Variant Handling.
- (line 32)
-* GDB_OSABI_WINCE: OS ABI Variant Handling.
- (line 66)
-* gdbarch: How an Architecture is Represented.
- (line 19)
-* gdbarch accessor functions: Creating a New Architecture.
- (line 14)
-* gdbarch lookup: Looking Up an Existing Architecture.
- (line 6)
-* gdbarch register architecture functions: Register Architecture Functions & Variables.
- (line 6)
-* gdbarch register information functions: Register Information Functions.
- (line 6)
-* gdbarch_addr_bits_remove: Defining Other Architecture Features.
- (line 11)
-* gdbarch_address_class_name_to_type_flags: Address Classes. (line 30)
-* gdbarch_address_class_type_flags <1>: Defining Other Architecture Features.
- (line 43)
-* gdbarch_address_class_type_flags: Address Classes. (line 18)
-* gdbarch_address_class_type_flags_p: Defining Other Architecture Features.
- (line 52)
-* gdbarch_address_class_type_flags_to_name <1>: Defining Other Architecture Features.
- (line 56)
-* gdbarch_address_class_type_flags_to_name: Address Classes. (line 25)
-* gdbarch_address_class_type_flags_to_name_p: Defining Other Architecture Features.
- (line 60)
-* gdbarch_address_to_pointer <1>: Defining Other Architecture Features.
- (line 65)
-* gdbarch_address_to_pointer: Pointers and Addresses.
- (line 114)
-* gdbarch_adjust_breakpoint_address: Defining Other Architecture Features.
- (line 145)
-* gdbarch_alloc: Creating a New Architecture.
- (line 6)
-* gdbarch_believe_pcc_promotion: Defining Other Architecture Features.
- (line 72)
-* gdbarch_bits_big_endian: Defining Other Architecture Features.
- (line 77)
-* gdbarch_breakpoint_from_pc: Defining Other Architecture Features.
- (line 106)
-* gdbarch_call_dummy_location: Defining Other Architecture Features.
- (line 178)
-* gdbarch_cannot_fetch_register: Defining Other Architecture Features.
- (line 184)
-* gdbarch_cannot_store_register: Defining Other Architecture Features.
- (line 188)
-* gdbarch_char_signed: Defining Other Architecture Features.
- (line 461)
-* gdbarch_convert_register_p <1>: Defining Other Architecture Features.
- (line 195)
-* gdbarch_convert_register_p: Register and Memory Data.
- (line 30)
-* gdbarch_data: Coding. (line 133)
-* gdbarch_data_register_post_init: Coding. (line 118)
-* gdbarch_data_register_pre_init: Coding. (line 108)
-* gdbarch_decr_pc_after_break: Defining Other Architecture Features.
- (line 205)
-* gdbarch_deprecated_fp_regnum: Defining Other Architecture Features.
- (line 446)
-* gdbarch_double_bit: Defining Other Architecture Features.
- (line 471)
-* gdbarch_dummy_id: Defining Other Architecture Features.
- (line 523)
-* gdbarch_dwarf2_reg_to_regnum: Defining Other Architecture Features.
- (line 216)
-* gdbarch_ecoff_reg_to_regnum: Defining Other Architecture Features.
- (line 220)
-* gdbarch_float_bit: Defining Other Architecture Features.
- (line 475)
-* gdbarch_fp0_regnum: Defining Other Architecture Features.
- (line 200)
-* gdbarch_get_longjmp_target <1>: Defining Other Architecture Features.
- (line 231)
-* gdbarch_get_longjmp_target: Algorithms. (line 263)
-* gdbarch_have_nonsteppable_watchpoint: Algorithms. (line 396)
-* gdbarch_in_function_epilogue_p: Defining Other Architecture Features.
- (line 253)
-* gdbarch_in_solib_return_trampoline: Defining Other Architecture Features.
- (line 259)
-* gdbarch_info: Looking Up an Existing Architecture.
- (line 22)
-* gdbarch_init_osabi: OS ABI Variant Handling.
- (line 125)
-* gdbarch_int_bit: Defining Other Architecture Features.
- (line 478)
-* gdbarch_integer_to_address: Defining Other Architecture Features.
- (line 274)
-* gdbarch_list_lookup_by_info: Looking Up an Existing Architecture.
- (line 22)
-* gdbarch_long_bit: Defining Other Architecture Features.
- (line 481)
-* gdbarch_long_double_bit: Defining Other Architecture Features.
- (line 485)
-* gdbarch_long_long_bit: Defining Other Architecture Features.
- (line 489)
-* gdbarch_lookup_osabi: OS ABI Variant Handling.
- (line 119)
-* gdbarch_memory_insert_breakpoint: Defining Other Architecture Features.
- (line 130)
-* gdbarch_memory_remove_breakpoint: Defining Other Architecture Features.
- (line 130)
-* gdbarch_osabi_name: OS ABI Variant Handling.
- (line 97)
-* gdbarch_pointer_to_address <1>: Defining Other Architecture Features.
- (line 295)
-* gdbarch_pointer_to_address: Pointers and Addresses.
- (line 105)
-* gdbarch_print_insn: Defining Other Architecture Features.
- (line 513)
-* gdbarch_ptr_bit: Defining Other Architecture Features.
- (line 493)
-* gdbarch_push_dummy_call: Defining Other Architecture Features.
- (line 363)
-* gdbarch_push_dummy_code: Defining Other Architecture Features.
- (line 375)
-* gdbarch_register <1>: Adding a New Target. (line 40)
-* gdbarch_register: How an Architecture is Represented.
- (line 19)
-* gdbarch_register_osabi: OS ABI Variant Handling.
- (line 103)
-* gdbarch_register_osabi_sniffer: OS ABI Variant Handling.
- (line 112)
-* gdbarch_register_to_value <1>: Defining Other Architecture Features.
- (line 301)
-* gdbarch_register_to_value: Register and Memory Data.
- (line 46)
-* gdbarch_return_value: Defining Other Architecture Features.
- (line 394)
-* gdbarch_sdb_reg_to_regnum: Defining Other Architecture Features.
- (line 390)
-* gdbarch_short_bit: Defining Other Architecture Features.
- (line 497)
-* gdbarch_skip_permanent_breakpoint: Defining Other Architecture Features.
- (line 430)
-* gdbarch_skip_trampoline_code: Defining Other Architecture Features.
- (line 441)
-* gdbarch_stab_reg_to_regnum: Defining Other Architecture Features.
- (line 450)
-* gdbarch_stabs_argument_has_addr: Defining Other Architecture Features.
- (line 359)
-* gdbarch_tdep definition: Creating a New Architecture.
- (line 34)
-* gdbarch_tdep when allocating new gdbarch: Creating a New Architecture.
- (line 6)
-* gdbarch_value_to_register <1>: Defining Other Architecture Features.
- (line 529)
-* gdbarch_value_to_register: Register and Memory Data.
- (line 62)
-* gdbarch_virtual_frame_pointer: Defining Other Architecture Features.
- (line 501)
-* GDBINIT_FILENAME: Host Definition. (line 74)
-* generic host support: Host Definition. (line 38)
-* generic_elf_osabi_sniff_abi_tag_sections: OS ABI Variant Handling.
- (line 133)
-* get_frame_register: Stack Frames. (line 15)
-* get_frame_type: Stack Frames. (line 22)
-* hardware breakpoints: Algorithms. (line 158)
-* hardware watchpoints: Algorithms. (line 280)
-* HAVE_CONTINUABLE_WATCHPOINT: Algorithms. (line 402)
-* HAVE_DOS_BASED_FILE_SYSTEM: Coding. (line 556)
-* HAVE_STEPPABLE_WATCHPOINT: Algorithms. (line 386)
-* host: Overall Structure. (line 50)
-* host, adding: Host Definition. (line 13)
-* i386_cleanup_dregs: Algorithms. (line 580)
-* I386_DR_LOW_GET_STATUS: Algorithms. (line 493)
-* I386_DR_LOW_RESET_ADDR: Algorithms. (line 489)
-* I386_DR_LOW_SET_ADDR: Algorithms. (line 486)
-* I386_DR_LOW_SET_CONTROL: Algorithms. (line 483)
-* i386_insert_hw_breakpoint: Algorithms. (line 568)
-* i386_insert_watchpoint: Algorithms. (line 540)
-* i386_region_ok_for_watchpoint: Algorithms. (line 518)
-* i386_remove_hw_breakpoint: Algorithms. (line 568)
-* i386_remove_watchpoint: Algorithms. (line 540)
-* i386_stopped_by_watchpoint: Algorithms. (line 532)
-* i386_stopped_data_address: Algorithms. (line 525)
-* I386_USE_GENERIC_WATCHPOINTS: Algorithms. (line 465)
-* in_dynsym_resolve_code: Defining Other Architecture Features.
- (line 263)
-* inferior_appeared: GDB Observers. (line 169)
-* inferior_created: GDB Observers. (line 92)
-* inferior_exit: GDB Observers. (line 172)
-* inner_than: Functions and Variable to Analyze Frames.
- (line 30)
-* innermost frame: Frame Handling Terminology.
- (line 24)
-* insert or remove hardware breakpoint: Algorithms. (line 234)
-* insert or remove hardware watchpoint: Algorithms. (line 347)
-* insert or remove software breakpoint: Algorithms. (line 211)
-* IS_ABSOLUTE_PATH: Coding. (line 567)
-* IS_DIR_SEPARATOR: Coding. (line 562)
-* ISATTY: Host Definition. (line 99)
-* item output functions: User Interface. (line 254)
-* language parser: Language Support. (line 25)
-* language support: Language Support. (line 6)
-* legal papers for code contributions: Debugging GDB. (line 42)
-* length_of_subexp: Language Support. (line 58)
-* libgdb: libgdb. (line 9)
-* libiberty library: Support Libraries. (line 52)
-* line wrap in output: Coding. (line 191)
-* lint: Host Definition. (line 133)
-* list output functions: User Interface. (line 131)
-* LITTLE_BREAKPOINT: Defining Other Architecture Features.
- (line 100)
-* long long data type: Host Definition. (line 106)
-* longjmp debugging: Algorithms. (line 258)
-* lookup_symbol: Symbol Handling. (line 142)
-* LSEEK_NOT_LINEAR: Host Definition. (line 114)
-* lval_type enumeration, for values.: Values. (line 19)
-* make_cleanup: Coding. (line 28)
-* make_cleanup_ui_out_list_begin_end: User Interface. (line 247)
-* make_cleanup_ui_out_tuple_begin_end: User Interface. (line 223)
-* making a new release of gdb: Releasing GDB. (line 6)
-* memory representation: Register and Memory Data.
- (line 6)
-* memory_changed: GDB Observers. (line 177)
-* minimal symbol table: Symbol Handling. (line 111)
-* minsymtabs: Symbol Handling. (line 111)
-* multi-arch data: Coding. (line 100)
-* NATDEPFILES: Native Debugging. (line 8)
-* native conditionals: Native Debugging. (line 75)
-* native debugging: Native Debugging. (line 6)
-* nesting level in ui_out functions: User Interface. (line 143)
-* new year procedure: Start of New Year Procedure.
- (line 6)
-* new_objfile: GDB Observers. (line 109)
-* new_thread: GDB Observers. (line 114)
-* NEXT frame: Frame Handling Terminology.
- (line 11)
-* NORETURN: Host Definition. (line 119)
-* normal_stop: GDB Observers. (line 76)
-* normal_stop observer: GDB Observers. (line 48)
-* notification about inferior execution stop: GDB Observers. (line 48)
-* notifications about changes in internals: Algorithms. (line 634)
-* object file formats: Symbol Handling. (line 210)
-* observer pattern interface: Algorithms. (line 634)
-* observers implementation rationale: GDB Observers. (line 9)
-* obstacks: Support Libraries. (line 69)
-* op_print_tab: Language Support. (line 91)
-* opcodes library: Support Libraries. (line 39)
-* OS ABI variants: OS ABI Variant Handling.
- (line 6)
-* parse_exp_1: Language Support. (line 97)
-* partial symbol table: Symbol Handling. (line 114)
-* pc_regnum: Register Architecture Functions & Variables.
- (line 58)
-* PE-COFF format: Symbol Handling. (line 267)
-* per-architecture module data: Coding. (line 100)
-* pointer representation: Pointers and Addresses.
- (line 6)
-* portability: Coding. (line 530)
-* portable file name handling: Coding. (line 547)
-* porting to new machines: Porting GDB. (line 6)
-* prefixify_subexp: Language Support. (line 58)
-* PREVIOUS frame: Frame Handling Terminology.
- (line 14)
-* print_float_info: Register Information Functions.
- (line 80)
-* print_registers_info: Register Information Functions.
- (line 53)
-* print_subexp: Language Support. (line 91)
-* print_vector_info: Register Information Functions.
- (line 96)
-* PRINTF_HAS_LONG_LONG: Host Definition. (line 109)
-* processor status register: Register Architecture Functions & Variables.
- (line 69)
-* program counter <1>: Register Architecture Functions & Variables.
- (line 58)
-* program counter: Algorithms. (line 158)
-* prologue analysis: Algorithms. (line 14)
-* prologue cache: Prologue Caches. (line 12)
-* prologue of a function: Prologue Caches. (line 6)
-* prologue-value.c: Algorithms. (line 48)
-* prompt: Host Definition. (line 94)
-* ps_regnum: Register Architecture Functions & Variables.
- (line 69)
-* pseudo-evaluation of function prologues: Algorithms. (line 48)
-* pseudo_register_read: Register Architecture Functions & Variables.
- (line 29)
-* pseudo_register_write: Register Architecture Functions & Variables.
- (line 33)
-* psymtabs: Symbol Handling. (line 107)
-* push_dummy_call: Functions Creating Dummy Frames.
- (line 13)
-* push_dummy_code: Functions Creating Dummy Frames.
- (line 57)
-* raw register representation: Raw and Cooked Registers.
- (line 6)
-* read_pc: Register Architecture Functions & Variables.
- (line 10)
-* reading of symbols: Symbol Handling. (line 25)
-* readline library: Support Libraries. (line 45)
-* regcache_cooked_read: Register Caching. (line 23)
-* regcache_cooked_read_signed: Register Caching. (line 23)
-* regcache_cooked_read_unsigned: Register Caching. (line 23)
-* regcache_cooked_write: Register Caching. (line 23)
-* regcache_cooked_write_signed: Register Caching. (line 23)
-* regcache_cooked_write_unsigned: Register Caching. (line 23)
-* register caching: Register Caching. (line 6)
-* register data formats, converting: Register and Memory Data.
- (line 6)
-* register representation: Register and Memory Data.
- (line 6)
-* REGISTER_CONVERT_TO_RAW: Defining Other Architecture Features.
- (line 311)
-* REGISTER_CONVERT_TO_VIRTUAL: Defining Other Architecture Features.
- (line 306)
-* register_name: Register Information Functions.
- (line 10)
-* register_reggroup_p: Register Information Functions.
- (line 110)
-* register_type: Register Information Functions.
- (line 33)
-* regset_from_core_section: Defining Other Architecture Features.
- (line 316)
-* regular expressions library: Support Libraries. (line 110)
-* Release Branches: Versions and Branches.
- (line 93)
-* remote debugging support: Host Definition. (line 41)
-* REMOTE_BPT_VECTOR: Defining Other Architecture Features.
- (line 540)
-* representation of architecture: How an Architecture is Represented.
- (line 6)
-* representations, raw and cooked registers: Raw and Cooked Registers.
- (line 6)
-* representations, register and memory: Register and Memory Data.
- (line 6)
-* requirements for GDB: Requirements. (line 6)
-* restart: Algorithms. (line 604)
-* running the test suite: Testsuite. (line 19)
-* secondary symbol file: Symbol Handling. (line 47)
-* sentinel frame <1>: Frame Handling Terminology.
- (line 52)
-* sentinel frame: Stack Frames. (line 22)
-* SENTINEL_FRAME: Stack Frames. (line 22)
-* separate data and code address spaces: Pointers and Addresses.
- (line 6)
-* serial line support: Host Definition. (line 41)
-* set_gdbarch functions: Creating a New Architecture.
- (line 14)
-* set_gdbarch_bits_big_endian: Defining Other Architecture Features.
- (line 83)
-* set_gdbarch_sofun_address_maybe_missing: Defining Other Architecture Features.
- (line 330)
-* SIGWINCH_HANDLER: Host Definition. (line 78)
-* SIGWINCH_HANDLER_BODY: Host Definition. (line 82)
-* skip_prologue: Functions and Variable to Analyze Frames.
- (line 12)
-* SKIP_SOLIB_RESOLVER: Defining Other Architecture Features.
- (line 267)
-* SLASH_STRING: Coding. (line 584)
-* sniffing: Frame Handling Terminology.
- (line 46)
-* software breakpoints: Algorithms. (line 184)
-* software watchpoints: Algorithms. (line 280)
-* SOFTWARE_SINGLE_STEP: Defining Other Architecture Features.
- (line 324)
-* SOFTWARE_SINGLE_STEP_P: Defining Other Architecture Features.
- (line 320)
-* SOLIB_ADD: Native Debugging. (line 86)
-* SOLIB_CREATE_INFERIOR_HOOK: Native Debugging. (line 92)
-* solib_loaded: GDB Observers. (line 99)
-* solib_unloaded: GDB Observers. (line 104)
-* SOM debugging info: Symbol Handling. (line 355)
-* SOM format: Symbol Handling. (line 286)
-* source code formatting: Coding. (line 323)
-* sp_regnum: Register Architecture Functions & Variables.
- (line 49)
-* spaces, separate data and code address: Pointers and Addresses.
- (line 6)
-* stabs debugging info: Symbol Handling. (line 300)
-* stack frame, definition of base of a frame: Frame Handling Terminology.
- (line 28)
-* stack frame, definition of innermost frame: Frame Handling Terminology.
- (line 24)
-* stack frame, definition of NEXT frame: Frame Handling Terminology.
- (line 11)
-* stack frame, definition of PREVIOUS frame: Frame Handling Terminology.
- (line 14)
-* stack frame, definition of sentinel frame: Frame Handling Terminology.
- (line 52)
-* stack frame, definition of sniffing: Frame Handling Terminology.
- (line 46)
-* stack frame, definition of THIS frame: Frame Handling Terminology.
- (line 9)
-* stack frame, definition of unwinding: Frame Handling Terminology.
- (line 41)
-* stack pointer: Register Architecture Functions & Variables.
- (line 49)
-* START_INFERIOR_TRAPS_EXPECTED: Native Debugging. (line 96)
-* status register: Register Architecture Functions & Variables.
- (line 69)
-* STOPPED_BY_WATCHPOINT: Algorithms. (line 412)
-* store_typed_address: Pointers and Addresses.
- (line 70)
-* struct: GDB Observers. (line 62)
-* struct gdbarch creation: Creating a New Architecture.
- (line 6)
-* struct regcache: Register Caching. (line 10)
-* struct value, converting register contents to: Register and Memory Data.
- (line 6)
-* submitting patches: Debugging GDB. (line 30)
-* sym_fns structure: Symbol Handling. (line 37)
-* symbol files: Symbol Handling. (line 25)
-* symbol lookup: Symbol Handling. (line 133)
-* symbol reading: Symbol Handling. (line 25)
-* SYMBOL_RELOADING_DEFAULT: Defining Other Architecture Features.
- (line 454)
-* symtabs: Symbol Handling. (line 104)
-* system dependencies: Coding. (line 534)
-* table output functions: User Interface. (line 131)
-* target: Overall Structure. (line 50)
-* target architecture definition: Target Architecture Definition.
- (line 6)
-* target dependent files: Adding a New Target. (line 8)
-* target descriptions: Target Descriptions. (line 6)
-* target descriptions, adding register support: Adding Target Described Register Support.
- (line 6)
-* target descriptions, implementation: Target Descriptions Implementation.
- (line 6)
-* target vector: Target Vector Definition.
- (line 6)
-* TARGET_CAN_USE_HARDWARE_WATCHPOINT: Algorithms. (line 333)
-* target_changed: GDB Observers. (line 82)
-* TARGET_CHAR_BIT: Defining Other Architecture Features.
- (line 458)
-* target_insert_breakpoint: Algorithms. (line 211)
-* target_insert_hw_breakpoint: Algorithms. (line 234)
-* target_insert_watchpoint: Algorithms. (line 347)
-* TARGET_REGION_OK_FOR_HW_WATCHPOINT: Algorithms. (line 343)
-* target_remove_breakpoint: Algorithms. (line 211)
-* target_remove_hw_breakpoint: Algorithms. (line 234)
-* target_remove_watchpoint: Algorithms. (line 347)
-* target_resumed: GDB Observers. (line 129)
-* target_stopped_data_address: Algorithms. (line 364)
-* target_watchpoint_addr_within_range: Algorithms. (line 378)
-* targets: Existing Targets. (line 6)
-* TCP remote support: Host Definition. (line 57)
-* terminal device: Host Definition. (line 97)
-* test suite: Testsuite. (line 6)
-* test suite organization: Testsuite. (line 195)
-* test_notification: GDB Observers. (line 181)
-* Testsuite Configuration: Testsuite. (line 167)
-* THIS frame: Frame Handling Terminology.
- (line 9)
-* thread_exit: GDB Observers. (line 117)
-* thread_ptid_changed: GDB Observers. (line 165)
-* thread_stop_requested: GDB Observers. (line 122)
-* tracepoint_created: GDB Observers. (line 148)
-* tracepoint_deleted: GDB Observers. (line 152)
-* tracepoint_modified: GDB Observers. (line 156)
-* tuple output functions: User Interface. (line 131)
-* type codes: Symbol Handling. (line 186)
-* types: Coding. (line 405)
-* ui_out functions: User Interface. (line 47)
-* ui_out functions, usage examples: User Interface. (line 398)
-* ui_out_field_core_addr: User Interface. (line 287)
-* ui_out_field_fmt: User Interface. (line 261)
-* ui_out_field_fmt_int: User Interface. (line 280)
-* ui_out_field_int: User Interface. (line 273)
-* ui_out_field_skip: User Interface. (line 352)
-* ui_out_field_stream: User Interface. (line 320)
-* ui_out_field_string: User Interface. (line 291)
-* ui_out_flush: User Interface. (line 392)
-* ui_out_list_begin: User Interface. (line 234)
-* ui_out_list_end: User Interface. (line 240)
-* ui_out_message: User Interface. (line 376)
-* ui_out_spaces: User Interface. (line 371)
-* ui_out_stream_delete: User Interface. (line 315)
-* ui_out_stream_new: User Interface. (line 309)
-* ui_out_table_begin: User Interface. (line 165)
-* ui_out_table_body: User Interface. (line 191)
-* ui_out_table_end: User Interface. (line 194)
-* ui_out_table_header: User Interface. (line 178)
-* ui_out_text: User Interface. (line 358)
-* ui_out_tuple_begin: User Interface. (line 210)
-* ui_out_tuple_end: User Interface. (line 216)
-* ui_out_wrap_hint: User Interface. (line 382)
-* unwind frame: Stack Frames. (line 9)
-* unwind_dummy_id: Functions Creating Dummy Frames.
- (line 38)
-* unwind_pc: Functions to Access Frame Data.
- (line 11)
-* unwind_sp: Functions to Access Frame Data.
- (line 27)
-* unwinding: Frame Handling Terminology.
- (line 41)
-* using ui_out functions: User Interface. (line 398)
-* value structure: Values. (line 9)
-* value_as_address: Pointers and Addresses.
- (line 84)
-* value_from_pointer: Pointers and Addresses.
- (line 93)
-* values: Values. (line 9)
-* VEC: Support Libraries. (line 131)
-* vendor branches: Versions and Branches.
- (line 108)
-* void: GDB Observers. (line 67)
-* volatile: Host Definition. (line 136)
-* watchpoints: Algorithms. (line 274)
-* watchpoints, on x86: Algorithms. (line 453)
-* watchpoints, with threads: Algorithms. (line 429)
-* word-addressed machines: Pointers and Addresses.
- (line 6)
-* wrap_here: Coding. (line 191)
-* write_pc: Register Architecture Functions & Variables.
- (line 13)
-* writing tests: Testsuite. (line 247)
-* x86 debug registers: Algorithms. (line 453)
-* XCOFF format: Symbol Handling. (line 251)
-
-
-\1f
-Tag Table:
-Node: Top\7f1614
-Node: Summary\7f2495
-Node: Requirements\7f2645
-Node: Contributors\7f4124
-Node: Overall Structure\7f5717
-Node: Algorithms\7f10740
-Node: User Interface\7f42324
-Ref: UI-Independent Output\7f44179
-Ref: User Interface-Footnote-1\7f66150
-Ref: User Interface-Footnote-2\7f66199
-Node: libgdb\7f66434
-Node: Values\7f70385
-Node: Stack Frames\7f73229
-Node: Symbol Handling\7f78211
-Node: Language Support\7f94745
-Node: Host Definition\7f99471
-Node: Target Architecture Definition\7f104462
-Node: OS ABI Variant Handling\7f105282
-Node: Initialize New Architecture\7f110127
-Node: How an Architecture is Represented\7f110478
-Node: Looking Up an Existing Architecture\7f112435
-Node: Creating a New Architecture\7f115354
-Node: Registers and Memory\7f117392
-Node: Pointers and Addresses\7f118184
-Ref: Pointers and Addresses-Footnote-1\7f124185
-Node: Address Classes\7f124428
-Node: Register Representation\7f127673
-Node: Raw and Cooked Registers\7f128047
-Node: Register Architecture Functions & Variables\7f129231
-Node: Register Information Functions\7f132840
-Ref: Register Information Functions-Footnote-1\7f138746
-Node: Register and Memory Data\7f139165
-Node: Register Caching\7f142314
-Node: Frame Interpretation\7f143850
-Node: All About Stack Frames\7f144256
-Ref: All About Stack Frames-Footnote-1\7f149548
-Node: Frame Handling Terminology\7f149780
-Node: Prologue Caches\7f152307
-Node: Functions and Variable to Analyze Frames\7f153988
-Ref: frame_align\7f156086
-Node: Functions to Access Frame Data\7f157600
-Node: Analyzing Stacks---Frame Sniffers\7f159891
-Ref: Analyzing Stacks---Frame Sniffers-Footnote-1\7f164541
-Node: Inferior Call Setup\7f165038
-Node: About Dummy Frames\7f165321
-Node: Functions Creating Dummy Frames\7f165947
-Node: Adding support for debugging core files\7f170004
-Node: Defining Other Architecture Features\7f170548
-Ref: gdbarch_breakpoint_from_pc\7f175395
-Ref: gdbarch_stabs_argument_has_addr\7f187789
-Ref: gdbarch_push_dummy_call\7f188036
-Ref: gdbarch_push_dummy_code\7f188596
-Ref: gdbarch_return_value\7f189578
-Ref: gdbarch_dummy_id\7f195344
-Node: Adding a New Target\7f196032
-Node: Target Descriptions\7f198499
-Node: Target Descriptions Implementation\7f199438
-Node: Adding Target Described Register Support\7f200812
-Node: Target Vector Definition\7f203758
-Node: Managing Execution State\7f204290
-Node: Existing Targets\7f206103
-Node: Native Debugging\7f208618
-Node: Support Libraries\7f212446
-Node: Coding\7f223961
-Node: Porting GDB\7f248970
-Node: Versions and Branches\7f250839
-Ref: Tags\7f256795
-Ref: experimental branch tags\7f257126
-Node: Start of New Year Procedure\7f257858
-Node: Releasing GDB\7f259664
-Node: Testsuite\7f277896
-Ref: Testsuite-Footnote-1\7f289761
-Node: Hints\7f289879
-Node: Getting Started\7f290201
-Node: Debugging GDB\7f294344
-Node: GDB Observers\7f299409
-Node: GNU Free Documentation License\7f307311
-Node: Index\7f329755
-\1f
-End Tag Table
OSDN Git Service
