aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc/gdbint.info-2
diff options
context:
space:
mode:
authorStan Shebs <shebs@codesourcery.com>1999-04-16 01:34:49 +0000
committerStan Shebs <shebs@codesourcery.com>1999-04-16 01:34:49 +0000
commit9733ab3f56072534b447188f48d3d5bc9911189e (patch)
tree26640d911c16263ab87ed1f12b60700a2cd390c2 /gdb/doc/gdbint.info-2
parent071ea11e85eb9d529cc5eb3d35f6247466a21b99 (diff)
downloadgdb-9733ab3f56072534b447188f48d3d5bc9911189e.zip
gdb-9733ab3f56072534b447188f48d3d5bc9911189e.tar.gz
gdb-9733ab3f56072534b447188f48d3d5bc9911189e.tar.bz2
Initial creation of sourceware repository
Diffstat (limited to 'gdb/doc/gdbint.info-2')
-rw-r--r--gdb/doc/gdbint.info-21338
1 files changed, 1338 insertions, 0 deletions
diff --git a/gdb/doc/gdbint.info-2 b/gdb/doc/gdbint.info-2
new file mode 100644
index 0000000..612cf0f
--- /dev/null
+++ b/gdb/doc/gdbint.info-2
@@ -0,0 +1,1338 @@
+This is Info file gdbint.info, produced by Makeinfo version 1.68 from
+the input file ./gdbint.texinfo.
+
+START-INFO-DIR-ENTRY
+* Gdb-Internals: (gdbint). The GNU debugger's internals.
+END-INFO-DIR-ENTRY
+
+ This file documents the internals of the GNU debugger GDB.
+
+ Copyright 1990-1999 Free Software Foundation, Inc. Contributed by
+Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
+Shebs.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy or distribute modified versions of this
+manual under the terms of the GPL (for which purpose this text may be
+regarded as a program in the language TeX).
+
+
+File: gdbint.info, Node: Target Architecture Definition, Next: Target Vector Definition, Prev: Host Definition, Up: Top
+
+Target Architecture Definition
+******************************
+
+ GDB's target architecture defines what sort of machine-language
+programs GDB can work with, and how it works with them.
+
+ At present, the target architecture definition consists of a number
+of C macros.
+
+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 `REGISTER_NAME' and related macros.
+
+ GDB can handle big-endian, little-endian, and bi-endian
+architectures.
+
+Frame Interpretation
+====================
+
+Inferior Call Setup
+===================
+
+Compiler Characteristics
+========================
+
+Target Conditionals
+===================
+
+ This section describes the macros that you can use to define the
+target machine.
+
+`ADDITIONAL_OPTIONS'
+
+`ADDITIONAL_OPTION_CASES'
+
+`ADDITIONAL_OPTION_HANDLER'
+
+`ADDITIONAL_OPTION_HELP'
+ These are a set of macros that allow the addition of additional
+ command line options to GDB. They are currently used only for the
+ unsupported i960 Nindy target, and should not be used in any other
+ configuration.
+
+`ADDR_BITS_REMOVE (addr)'
+ If a raw machine address includes any bits that are not really
+ part of the address, then define this macro to expand into an
+ expression that zeros those bits in ADDR. For example, the two
+ low-order bits of a Motorola 88K address may be used by some
+ kernels for their own purposes, since addresses must always be
+ 4-byte aligned, and so are of no use for addressing. Those bits
+ should be filtered out with an expression such as `((addr) & ~3)'.
+
+`BEFORE_MAIN_LOOP_HOOK'
+ Define this to expand into any code that you want to execute
+ before the main loop starts. Although this is not, strictly
+ speaking, a target conditional, that is how it is currently being
+ used. Note that if a configuration were to define it one way for
+ a host and a different way for the target, GDB will probably not
+ compile, let alone run correctly. This is currently used only for
+ the unsupported i960 Nindy target, and should not be used in any
+ other configuration.
+
+`BELIEVE_PCC_PROMOTION'
+ Define 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.
+
+`BELIEVE_PCC_PROMOTION_TYPE'
+ Define this if GDB should believe the type of a short argument when
+ compiled by pcc, but look within a full int space to get its value.
+ Only defined for Sun-3 at present.
+
+`BITS_BIG_ENDIAN'
+ Define this if the numbering of bits in the targets does *not*
+ match the endianness of the target byte order. A value of 1 means
+ that the bits are numbered in a big-endian order, 0 means
+ 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.
+
+`BIG_BREAKPOINT'
+
+`LITTLE_BREAKPOINT'
+ Similar to BREAKPOINT, but used for bi-endian targets.
+
+`REMOTE_BREAKPOINT'
+
+`LITTLE_REMOTE_BREAKPOINT'
+
+`BIG_REMOTE_BREAKPOINT'
+ Similar to BREAKPOINT, but used for remote targets.
+
+`BREAKPOINT_FROM_PC (pcptr, lenptr)'
+ Use the program counter to determine the contents and size of a
+ breakpoint instruction. It returns a pointer to a string of bytes
+ that encode a breakpoint instruction, stores the length of the
+ string to *lenptr, and adjusts pc (if necessary) to point to the
+ actual memory location where the breakpoint should be inserted.
+
+ 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.
+
+ Replaces all the other BREAKPOINTs.
+
+`CALL_DUMMY'
+ valops.c
+
+`CALL_DUMMY_LOCATION'
+ inferior.h
+
+`CALL_DUMMY_STACK_ADJUST'
+ valops.c
+
+`CANNOT_FETCH_REGISTER (regno)'
+ A C expression that should be nonzero if REGNO cannot be fetched
+ from an inferior process. This is only relevant if
+ `FETCH_INFERIOR_REGISTERS' is not defined.
+
+`CANNOT_STORE_REGISTER (regno)'
+ A C expression that should be nonzero if REGNO should not be
+ written to the target. This is often the case for program
+ counters, status words, and other special registers. If this is
+ not defined, GDB will assume that all registers may be written.
+
+`DO_DEFERRED_STORES'
+
+`CLEAR_DEFERRED_STORES'
+ Define this to execute any deferred stores of registers into the
+ inferior, and to cancel any deferred stores.
+
+ Currently only implemented correctly for native Sparc
+ configurations?
+
+`CPLUS_MARKER'
+ Define this to expand into the character that G++ uses to
+ distinguish compiler-generated identifiers from
+ programmer-specified identifiers. By default, this expands into
+ `'$''. Most System V targets should define this to `'.''.
+
+`DBX_PARM_SYMBOL_CLASS'
+ Hook for the `SYMBOL_CLASS' of a parameter when decoding DBX symbol
+ information. In the i960, parameters can be stored as locals or as
+ args, depending on the type of the debug record.
+
+`DECR_PC_AFTER_BREAK'
+ Define this to be 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.
+
+`DECR_PC_AFTER_HW_BREAK'
+ Similarly, for hardware breakpoints.
+
+`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.
+
+`DO_REGISTERS_INFO'
+ If defined, use this to print the value of a register or all
+ registers.
+
+`END_OF_TEXT_DEFAULT'
+ This is an expression that should designate the end of the text
+ section (? FIXME ?)
+
+`EXTRACT_RETURN_VALUE(type,regbuf,valbuf)'
+ Define this to extract a function's return value of type TYPE from
+ the raw register state REGBUF and copy that, in virtual format,
+ into VALBUF.
+
+`EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)'
+ Define this to extract from an array REGBUF containing the (raw)
+ register state, the address in which a function should return its
+ structure value, as a CORE_ADDR (or an expression that can be used
+ as one).
+
+`FLOAT_INFO'
+ If defined, then the `info float' command will print information
+ about the processor's floating point unit.
+
+`FP_REGNUM'
+ The number of the frame pointer register.
+
+`FRAMELESS_FUNCTION_INVOCATION(fi, frameless)'
+ Define this to set the variable FRAMELESS to 1 if the function
+ invocation represented by FI does not have a stack frame
+ associated with it. Otherwise set it to 0.
+
+`FRAME_ARGS_ADDRESS_CORRECT'
+ stack.c
+
+`FRAME_CHAIN(frame)'
+ Given FRAME, return a pointer to the calling frame.
+
+`FRAME_CHAIN_COMBINE(chain,frame)'
+ Define this to take the frame chain pointer and the frame's nominal
+ address and produce the nominal address of the caller's frame.
+ Presently only defined for HP PA.
+
+`FRAME_CHAIN_VALID(chain,thisframe)'
+ Define this to be an expression that returns zero if the given
+ frame is an outermost frame, with no caller, and nonzero
+ otherwise. Three common definitions are available.
+ `default_frame_chain_valid' (the default) is nonzero if the chain
+ pointer is nonzero and given frame's PC is not inside the startup
+ file (such as `crt0.o'). `alternate_frame_chain_valid' is nonzero
+ if the chain pointer is nonzero and the given frame's PC is not in
+ `main()' or a known entry point function (such as `_start()').
+
+`FRAME_INIT_SAVED_REGS(frame)'
+ See `frame.h'. Determines the address of all registers in the
+ current stack frame storing each in `frame->saved_regs'. Space for
+ `frame->saved_regs' shall be allocated by `FRAME_INIT_SAVED_REGS'
+ using either `frame_saved_regs_zalloc' or `frame_obstack_alloc'.
+
+ FRAME_FIND_SAVED_REGS and EXTRA_FRAME_INFO are deprecated.
+
+`FRAME_NUM_ARGS (val, fi)'
+ For the frame described by FI, set VAL to the number of arguments
+ that are being passed.
+
+`FRAME_SAVED_PC(frame)'
+ Given FRAME, return the pc saved there. That is, the return
+ address.
+
+`FUNCTION_EPILOGUE_SIZE'
+ For some COFF targets, the `x_sym.x_misc.x_fsize' field of the
+ function end symbol is 0. For such targets, you must define
+ `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a
+ function's epilogue.
+
+`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.)
+
+`GDB_TARGET_IS_HPPA'
+ This determines whether horrible kludge code in dbxread.c and
+ partial-stab.h is used to mangle multiple-symbol-table files from
+ HPPA's. This should all be ripped out, and a scheme like elfread.c
+ used.
+
+`GDB_TARGET_IS_MACH386'
+
+`GDB_TARGET_IS_SUN3'
+
+`GDB_TARGET_IS_SUN386'
+ Kludges that should go away.
+
+`GET_LONGJMP_TARGET'
+ For most machines, this is a target-dependent parameter. On the
+ DECstation and the Iris, this is a native-dependent parameter,
+ since <setjmp.h> is needed to define it.
+
+ This macro 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.
+
+`GET_SAVED_REGISTER'
+ Define this if you need to supply your own definition for the
+ function `get_saved_register'. Currently this is only done for
+ the a29k.
+
+`HAVE_REGISTER_WINDOWS'
+ Define this if the target has register windows.
+
+`REGISTER_IN_WINDOW_P (regnum)'
+ Define this to be an expression that is 1 if the given register is
+ in the window.
+
+`IBM6000_TARGET'
+ Shows that we are configured for an IBM RS/6000 target. This
+ conditional should be eliminated (FIXME) and replaced by
+ feature-specific macros. It was introduced in haste and we are
+ repenting at leisure.
+
+`IEEE_FLOAT'
+ Define this if the target system uses IEEE-format floating point
+ numbers.
+
+`INIT_EXTRA_FRAME_INFO (fromleaf, frame)'
+ If additional information about the frame is required this should
+ be stored in `frame->extra_info'. Space for `frame->extra_info'
+ is allocated using `frame_obstack_alloc'.
+
+`INIT_FRAME_PC (fromleaf, prev)'
+ This is a C statement that sets the pc of the frame pointed to by
+ PREV. [By default...]
+
+`INNER_THAN (lhs,rhs)'
+ Returns non-zero if stack address LHS is inner than (nearer to the
+ stack top) stack address RHS. Define this as `lhs < rhs' if the
+ target's stack grows downward in memory, or `lhs > rsh' if the
+ stack grows upward.
+
+`IN_SIGTRAMP (pc, name)'
+ Define this to return true if the given PC and/or NAME indicates
+ that the current function is a sigtramp.
+
+`SIGTRAMP_START (pc)'
+
+`SIGTRAMP_END (pc)'
+ Define these to be the start and end address of the sigtramp for
+ the given PC. On machines where the address is just a compile time
+ constant, the macro expansion will typically just ignore the
+ supplied PC.
+
+`IN_SOLIB_CALL_TRAMPOLINE pc name'
+ Define this to evaluate to nonzero if the program is stopped in the
+ trampoline that connects to a shared library.
+
+`IN_SOLIB_RETURN_TRAMPOLINE pc name'
+ Define this to evaluate to nonzero if the program is stopped in the
+ trampoline that returns from a shared library.
+
+`IS_TRAPPED_INTERNALVAR (name)'
+ This is an ugly hook to allow the specification of special actions
+ that should occur as a side-effect of setting the value of a
+ variable internal to GDB. Currently only used by the h8500. Note
+ that this could be either a host or target conditional.
+
+`NEED_TEXT_START_END'
+ Define this if GDB should determine the start and end addresses of
+ the text section. (Seems dubious.)
+
+`NO_HIF_SUPPORT'
+ (Specific to the a29k.)
+
+`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_breapoints_p)'
+ A function that inserts or removes (dependant on
+ INSERT_BREAPOINTS_P) breakpoints at each possible destinations of
+ the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for
+ examples.
+
+`PCC_SOL_BROKEN'
+ (Used only in the Convex target.)
+
+`PC_IN_CALL_DUMMY'
+ inferior.h
+
+`PC_LOAD_SEGMENT'
+ If defined, print information about the load segment for the
+ program counter. (Defined only for the RS/6000.)
+
+`PC_REGNUM'
+ If the program counter is kept in a register, then define this
+ macro to be the number of that register. This need be defined
+ only if `TARGET_WRITE_PC' is not defined.
+
+`NPC_REGNUM'
+ The number of the "next program counter" register, if defined.
+
+`NNPC_REGNUM'
+ The number of the "next next program counter" register, if defined.
+ Currently, this is only defined for the Motorola 88K.
+
+`PRINT_REGISTER_HOOK (regno)'
+ If defined, this must be a function that prints the contents of the
+ given register to standard output.
+
+`PRINT_TYPELESS_INTEGER'
+ This is an obscure substitute for `print_longest' that seems to
+ have been defined for the Convex target.
+
+`PROCESS_LINENUMBER_HOOK'
+ A hook defined for XCOFF reading.
+
+`PROLOGUE_FIRSTLINE_OVERLAP'
+ (Only used in unsupported Convex configuration.)
+
+`PS_REGNUM'
+ If defined, this is the number of the processor status register.
+ (This definition is only used in generic code when parsing "$ps".)
+
+`POP_FRAME'
+ Used in `call_function_by_hand' to remove an artificial stack
+ frame.
+
+`PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)'
+ Define this to push arguments onto the stack for inferior function
+ call.
+
+`PUSH_DUMMY_FRAME'
+ Used in `call_function_by_hand' to create an artificial stack
+ frame.
+
+`REGISTER_BYTES'
+ The total amount of space needed to store GDB's copy of the
+ machine's register state.
+
+`REGISTER_NAME(i)'
+ Return the name of register I as a string. May return NULL or NUL
+ to indicate that register I is not valid.
+
+`REG_STRUCT_HAS_ADDR (gcc_p, type)'
+ Define this to return 1 if the given type will be passed by pointer
+ rather than directly.
+
+`SDB_REG_TO_REGNUM'
+ Define this to convert sdb register numbers into GDB regnums. If
+ not defined, no conversion will be done.
+
+`SHIFT_INST_REGS'
+ (Only used for m88k targets.)
+
+`SKIP_PROLOGUE (pc)'
+ A C statement that advances the PC across any function entry
+ prologue instructions so as to reach "real" code.
+
+`SKIP_PROLOGUE_FRAMELESS_P'
+ A C statement that should behave similarly, but that can stop as
+ soon as the function is known to have a frame. If not defined,
+ `SKIP_PROLOGUE' will be used instead.
+
+`SKIP_TRAMPOLINE_CODE (pc)'
+ If the target machine has trampoline code that sits between
+ callers and the functions being called, then define this macro to
+ return a new PC that is at the start of the real function.
+
+`SP_REGNUM'
+ Define this to be the number of the register that serves as the
+ stack pointer.
+
+`STAB_REG_TO_REGNUM'
+ Define this to convert stab register numbers (as gotten from `r'
+ declarations) into GDB regnums. If not defined, no conversion
+ will be done.
+
+`STACK_ALIGN (addr)'
+ Define this to adjust the address to the alignment required for the
+ processor's stack.
+
+`STEP_SKIPS_DELAY (addr)'
+ Define this to return true if the address is of an instruction
+ with a delay slot. If a breakpoint has been placed in the
+ instruction's delay slot, GDB will single-step over that
+ instruction before resuming normally. Currently only defined for
+ the Mips.
+
+`STORE_RETURN_VALUE (type, valbuf)'
+ A C expression that stores a function return value of type TYPE,
+ where VALBUF is the address of the value to be stored.
+
+`SUN_FIXED_LBRAC_BUG'
+ (Used only for Sun-3 and Sun-4 targets.)
+
+`SYMBOL_RELOADING_DEFAULT'
+ The default value of the `symbol-reloading' variable. (Never
+ defined in current sources.)
+
+`TARGET_BYTE_ORDER_DEFAULT'
+ The ordering of bytes in the target. This must be either
+ `BIG_ENDIAN' or `LITTLE_ENDIAN'. This macro replaces
+ TARGET_BYTE_ORDER which is deprecated.
+
+`TARGET_BYTE_ORDER_SELECTABLE_P'
+ Non-zero if the target has both `BIG_ENDIAN' and `LITTLE_ENDIAN'
+ variants. This macro replaces TARGET_BYTE_ORDER_SELECTABLE which
+ is deprecated.
+
+`TARGET_CHAR_BIT'
+ Number of bits in a char; defaults to 8.
+
+`TARGET_COMPLEX_BIT'
+ Number of bits in a complex number; defaults to `2 *
+ TARGET_FLOAT_BIT'.
+
+`TARGET_DOUBLE_BIT'
+ Number of bits in a double float; defaults to `8 *
+ TARGET_CHAR_BIT'.
+
+`TARGET_DOUBLE_COMPLEX_BIT'
+ Number of bits in a double complex; defaults to `2 *
+ TARGET_DOUBLE_BIT'.
+
+`TARGET_FLOAT_BIT'
+ Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'.
+
+`TARGET_INT_BIT'
+ Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'.
+
+`TARGET_LONG_BIT'
+ Number of bits in a long integer; defaults to `4 *
+ TARGET_CHAR_BIT'.
+
+`TARGET_LONG_DOUBLE_BIT'
+ Number of bits in a long double float; defaults to `2 *
+ TARGET_DOUBLE_BIT'.
+
+`TARGET_LONG_LONG_BIT'
+ Number of bits in a long long integer; defaults to `2 *
+ TARGET_LONG_BIT'.
+
+`TARGET_PTR_BIT'
+ Number of bits in a pointer; defaults to `TARGET_INT_BIT'.
+
+`TARGET_SHORT_BIT'
+ Number of bits in a short integer; defaults to `2 *
+ TARGET_CHAR_BIT'.
+
+`TARGET_READ_PC'
+
+`TARGET_WRITE_PC (val, pid)'
+
+`TARGET_READ_SP'
+
+`TARGET_WRITE_SP'
+
+`TARGET_READ_FP'
+
+`TARGET_WRITE_FP'
+ These change the behavior of `read_pc', `write_pc', `read_sp',
+ `write_sp', `read_fp' and `write_fp'. For most targets, these may
+ be left undefined. GDB will call the read and write register
+ functions with the relevant `_REGNUM' argument.
+
+ These macros are useful when a target keeps one of these registers
+ in a hard to get at place; for example, part in a segment register
+ and part in an ordinary register.
+
+`TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)'
+ 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
+ `FP_REGNUM', with an offset of zero.
+
+`USE_STRUCT_CONVENTION (gcc_p, type)'
+ If defined, this must be an expression that is nonzero if a value
+ of the given TYPE being returned from a function must have space
+ allocated for it on the stack. GCC_P is true if the function
+ being considered is known to have been compiled by GCC; this is
+ helpful for systems where GCC is known to use different calling
+ convention than other compilers.
+
+`VARIABLES_INSIDE_BLOCK (desc, gcc_p)'
+ For dbx-style debugging information, if the compiler puts variable
+ declarations inside LBRAC/RBRAC blocks, this should be defined to
+ be nonzero. DESC is the value of `n_desc' from the `N_RBRAC'
+ symbol, and GCC_P is true if GDB has noticed the presence of
+ either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'.
+ By default, this is 0.
+
+`OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)'
+ Similarly, for OS/9000. Defaults to 1.
+
+ 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'.
+
+Adding a New Target
+===================
+
+ The following files define a target to GDB:
+
+`gdb/config/ARCH/TTT.mt'
+ Contains a Makefile fragment specific to this target. Specifies
+ what object files are needed for target TTT, by defining
+ `TDEPFILES=...'. Also specifies the header file which describes
+ TTT, by defining `TM_FILE= tm-TTT.h'. You can also define
+ `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', but these are now deprecated
+ and may go away in future versions of GDB.
+
+`gdb/config/ARCH/tm-TTT.h'
+ (`tm.h' is a link to this file, created by configure). Contains
+ macro definitions about the target machine's registers, stack frame
+ format and instructions.
+
+`gdb/TTT-tdep.c'
+ Contains any miscellaneous code required for this target machine.
+ On some machines it doesn't exist at all. Sometimes the macros in
+ `tm-TTT.h' become very complicated, so they are implemented as
+ functions here instead, and the macro is simply defined to call the
+ function. This is vastly preferable, since it is easier to
+ understand and debug.
+
+`gdb/config/ARCH/tm-ARCH.h'
+ This often exists to describe the basic layout of the target
+ machine's processor chip (registers, stack, etc). If used, it is
+ included by `tm-TTT.h'. It can be shared among many targets that
+ use the same processor.
+
+`gdb/ARCH-tdep.c'
+ Similarly, there are often common subroutines that are shared by
+ all target machines that use this particular architecture.
+
+ If you are adding a new operating system for an existing CPU chip,
+add a `config/tm-OS.h' file that describes the operating system
+facilities that are unusual (extra symbol table info; the breakpoint
+instruction needed; etc). Then write a `ARCH/tm-OS.h' that just
+`#include's `tm-ARCH.h' and `config/tm-OS.h'.
+
+
+File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Architecture Definition, Up: Top
+
+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.
+
+File Targets
+============
+
+ Both executables and core files have target vectors.
+
+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 `*-stub.c'.
+
+ 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
+setup 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.
+
+ROM Monitor Interface
+=====================
+
+Custom Protocols
+================
+
+Transport Layer
+===============
+
+Builtin Simulator
+=================
+
+
+File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top
+
+Native Debugging
+****************
+
+ Several files control GDB's configuration for native support:
+
+`gdb/config/ARCH/XYZ.mh'
+ Specifies Makefile fragments needed when hosting *or native* 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', etc.; see
+ `Makefile.in'.
+
+`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.
+
+Native core file Support
+========================
+
+`core-aout.c::fetch_core_registers()'
+ Support for reading registers out of a core file. This routine
+ calls `register_addr()', see below. Now that BFD is used to read
+ core files, virtually all machines should use `core-aout.c', and
+ should just provide `fetch_core_registers' in `XYZ-nat.c' (or
+ `REGISTER_U_ADDR' in `nm-XYZ.h').
+
+`core-aout.c::register_addr()'
+ If your `nm-XYZ.h' file defines the macro `REGISTER_U_ADDR(addr,
+ blockend, regno)', it should be defined to set `addr' to the
+ offset within the `user' struct of GDB register number `regno'.
+ `blockend' is the offset within the "upage" of `u.u_ar0'. If
+ `REGISTER_U_ADDR' is defined, `core-aout.c' will define the
+ `register_addr()' function and use the macro in it. If you do not
+ define `REGISTER_U_ADDR', but you are using the standard
+ `fetch_core_registers()', you will need to define your own version
+ of `register_addr()', put it into your `XYZ-nat.c' file, and be
+ sure `XYZ-nat.o' is in the `NATDEPFILES' list. If you have your
+ own `fetch_core_registers()', you may not need a separate
+ `register_addr()'. Many custom `fetch_core_registers()'
+ implementations simply locate the registers themselves.
+
+ When making GDB run native on a new operating system, to make it
+possible to debug core files, you will need to either write specific
+code for parsing your OS's core files, or customize `bfd/trad-core.c'.
+First, use whatever `#include' files your machine uses to define the
+struct of registers that is accessible (possibly in the u-area) in a
+core file (rather than `machine/reg.h'), and an include file that
+defines whatever header exists on a core file (e.g. the u-area or a
+`struct core'). Then modify `trad_unix_core_file_p()' to use these
+values to set up the section information for the data segment, stack
+segment, any other segments in the core file (perhaps shared library
+contents or control information), "registers" segment, and if there are
+two discontiguous sets of registers (e.g. integer and float), the
+"reg2" segment. This section information basically delimits areas in
+the core file in a standard way, which the section-reading routines in
+BFD know how to seek around in.
+
+ Then back in GDB, you need a matching routine called
+`fetch_core_registers()'. If you can use the generic one, it's in
+`core-aout.c'; if not, it's in your `XYZ-nat.c' file. It will be
+passed a char pointer to the entire "registers" segment, its length,
+and a zero; or a char pointer to the entire "regs2" segment, its
+length, and a 2. The routine should suck out the supplied register
+values and install them into GDB's "registers" array.
+
+ If your system uses `/proc' to control processes, and uses ELF
+format core files, then you may be able to use the same routines for
+reading the registers out of processes and out of core files.
+
+ptrace
+======
+
+/proc
+=====
+
+win32
+=====
+
+shared libraries
+================
+
+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'.
+
+`ATTACH_DETACH'
+ If defined, then GDB will include support for the `attach' and
+ `detach' commands.
+
+`CHILD_PREPARE_TO_STORE'
+ If the machine stores all registers at once in the child process,
+ then define this to ensure that all values are correct. This
+ usually entails a read from the child.
+
+ [Note that this is incorrectly defined in `xm-SYSTEM.h' files
+ currently.]
+
+`FETCH_INFERIOR_REGISTERS'
+ Define this if the native-dependent code will provide its own
+ routines `fetch_inferior_registers' and `store_inferior_registers'
+ in `HOST-nat.c'. If this symbol is *not* defined, and
+ `infptrace.c' is included in this configuration, the default
+ routines in `infptrace.c' are used for these functions.
+
+`FILES_INFO_HOOK'
+ (Only defined for Convex.)
+
+`FP0_REGNUM'
+ This macro is normally defined to be the number of the first
+ floating point register, if the machine has such registers. As
+ such, it would appear only in target-specific code. However,
+ /proc support uses this to decide whether floats are in use on
+ this target.
+
+`GET_LONGJMP_TARGET'
+ For most machines, this is a target-dependent parameter. On the
+ DECstation and the Iris, this is a native-dependent parameter,
+ since <setjmp.h> is needed to define it.
+
+ This macro 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.
+
+`KERNEL_U_ADDR'
+ Define this to the address of the `u' structure (the "user
+ struct", also known as the "u-page") in kernel virtual memory. GDB
+ needs to know this so that it can subtract this address from
+ absolute addresses in the upage, that are obtained via ptrace or
+ from core files. On systems that don't need this value, set it to
+ zero.
+
+`KERNEL_U_ADDR_BSD'
+ Define this to cause GDB to determine the address of `u' at
+ runtime, by using Berkeley-style `nlist' on the kernel's image in
+ the root directory.
+
+`KERNEL_U_ADDR_HPUX'
+ Define this to cause GDB to determine the address of `u' at
+ runtime, by using HP-style `nlist' on the kernel's image in the
+ root directory.
+
+`ONE_PROCESS_WRITETEXT'
+ Define this to be able to, when a breakpoint insertion fails, warn
+ the user that another process may be running with the same
+ executable.
+
+`PROC_NAME_FMT'
+ Defines the format for the name of a `/proc' device. Should be
+ defined in `nm.h' *only* in order to override the default
+ definition in `procfs.c'.
+
+`PTRACE_FP_BUG'
+ mach386-xdep.c
+
+`PTRACE_ARG3_TYPE'
+ The type of the third argument to the `ptrace' system call, if it
+ exists and is different from `int'.
+
+`REGISTER_U_ADDR'
+ Defines the offset of the registers in the "u area".
+
+`SHELL_COMMAND_CONCAT'
+ If defined, is a string to prefix on the shell command used to
+ start the inferior.
+
+`SHELL_FILE'
+ If defined, this is the name of the shell to use to run the
+ inferior. Defaults to `"/bin/sh"'.
+
+`SOLIB_ADD (filename, from_tty, targ)'
+ Define this to expand into an expression that will cause the
+ symbols in FILENAME to be added to GDB's symbol table.
+
+`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.
+
+`SVR4_SHARED_LIBS'
+ Define this to indicate that SVR4-style shared libraries are in
+ use.
+
+`USE_PROC_FS'
+ This determines whether small routines in `*-tdep.c', which
+ translate register values between GDB's internal representation
+ and the /proc representation, are compiled.
+
+`U_REGS_OFFSET'
+ This is the offset of the registers in the upage. It need only be
+ defined if the generic ptrace register access routines in
+ `infptrace.c' are being used (that is, `infptrace.c' is configured
+ in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the
+ default value from `infptrace.c' is good enough, leave it
+ undefined.
+
+ The default value means that u.u_ar0 *points to* the location of
+ the registers. I'm guessing that `#define U_REGS_OFFSET 0' means
+ that u.u_ar0 *is* the location of the registers.
+
+`CLEAR_SOLIB'
+ objfiles.c
+
+`DEBUG_PTRACE'
+ Define this to debug ptrace calls.
+
+
+File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
+
+Support Libraries
+*****************
+
+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.
+
+opcodes
+=======
+
+ The opcodes library provides GDB's disassembler. (It's a separate
+library because it's also used in binutils, for `objdump').
+
+readline
+========
+
+mmalloc
+=======
+
+libiberty
+=========
+
+gnu-regex
+=========
+
+ Regex conditionals.
+
+`C_ALLOCA'
+
+`NFAILURES'
+
+`RE_NREGS'
+
+`SIGN_EXTEND_CHAR'
+
+`SWITCH_ENUM_BUG'
+
+`SYNTAX_TABLE'
+
+`Sword'
+
+`sparc'
+include
+=======
+
+
+File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
+
+Coding
+******
+
+ This chapter covers topics that are lower-level than the major
+algorithms of GDB.
+
+Cleanups
+========
+
+ Cleanups are a structured way to deal with things that need to be
+done later. When your code does something (like `malloc' some memory,
+or open a file) that needs to be undone later (e.g. free 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, when an error occurs,
+or when your code decides it's time to do cleanups.
+
+ You can also discard cleanups, that is, throw them away without doing
+what they say. This is only done if you ask that it be done.
+
+ 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 be
+ passed to `do_cleanups' or `discard_cleanups' later. Unless you
+ are going to call `do_cleanups' or `discard_cleanups' yourself,
+ you can ignore the result from `make_cleanup'.
+
+`do_cleanups (OLD_CHAIN);'
+ Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
+ E.g.:
+ make_cleanup (a, 0);
+ old = make_cleanup (b, 0);
+ do_cleanups (old);
+
+ will call `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.
+
+`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.
+
+ 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).
+
+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.
+
+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.
+
+ You can configure with `--enable-build-warnings' to get GCC to check
+on a number of these rules. GDB sources ought not to engender any
+complaints, unless they are caused by bogus host systems. (The exact
+set of enabled warnings is currently `-Wall -Wpointer-arith
+-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
+
+Formatting
+----------
+
+ The standard GNU recommendations for formatting must be followed
+strictly.
+
+ Note that while in a definition, the function's name must be in
+column zero; in a function declaration, the name must be on the same
+line as the return type.
+
+ In addition, 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.
+
+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.
+
+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.
+
+Function Prototypes
+-------------------
+
+ Prototypes must be used to *declare* functions but never to *define*
+them. Prototypes for GDB functions must include both the argument type
+and name, with the name matching that used in the actual function
+definition.
+
+ For the sake of compatibility with pre-ANSI compilers, define
+prototypes with the `PARAMS' macro:
+
+ extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
+ char *contents_cache));
+
+ Note the double parentheses around the parameter types. This allows
+an arbitrary number of parameters to be described, without freaking out
+the C preprocessor. When the function has no parameters, it should be
+described like:
+
+ extern void noprocess PARAMS ((void));
+
+ The `PARAMS' macro expands to its argument in ANSI C, or to a simple
+`()' in traditional C.
+
+ All external functions should have a `PARAMS' 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.
+
+ All static functions must be declared in a block near the top of the
+source file.
+
+Clean Design
+------------
+
+ 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. If a
+hook is needed at that point, invent a generic hook and define it for
+your configuration, with something like:
+
+ #ifdef WRANGLE_SIGNALS
+ WRANGLE_SIGNALS (signo);
+ #endif
+
+ In your host, target, or native configuration file, as appropriate,
+define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit
+of care in defining the hook, so that it can be used by other ports in
+the future, if they need a hook in the same place.
+
+ If the hook is not defined, the code should do whatever "most"
+machines want. Using `#ifdef', as above, is the preferred way to do
+this, but sometimes that gets convoluted, in which case use
+
+ #ifndef SPECIAL_FOO_HANDLING
+ #define SPECIAL_FOO_HANDLING(pc, sp) (0)
+ #endif
+
+ where the macro is used or in an appropriate header file.
+
+ Whether to include a "small" hook, a hook around the exact pieces of
+code which are system-dependent, or whether to replace a whole function
+with a hook depends on the case. A good example of this dilemma can be
+found in `get_saved_register'. All machines that GDB 2.8 ran on just
+needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
+Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
+`REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required
+the `GET_SAVED_REGISTER' hook. The first three are examples of small
+hooks; the latter replaces a whole function. In this specific case, it
+is useful to have both kinds; it would be a bad idea to replace all the
+uses of the small hooks with `GET_SAVED_REGISTER', since that would
+result in much duplicated code. Other times, duplicating a few lines
+of code here or there is much cleaner than introducing a large number
+of small hooks.
+
+ 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.
+