+@section Compiler Characteristics
+
+@section Target Conditionals
+
+This section describes the macros that you can use to define the target
+machine.
+
+@table @code
+
+@item ADDITIONAL_OPTIONS
+@itemx ADDITIONAL_OPTION_CASES
+@itemx ADDITIONAL_OPTION_HANDLER
+@itemx ADDITIONAL_OPTION_HELP
+@findex ADDITIONAL_OPTION_HELP
+@findex ADDITIONAL_OPTION_HANDLER
+@findex ADDITIONAL_OPTION_CASES
+@findex ADDITIONAL_OPTIONS
+These are a set of macros that allow the addition of additional command
+line options to @value{GDBN}. They are currently used only for the unsupported
+i960 Nindy target, and should not be used in any other configuration.
+
+@item ADDR_BITS_REMOVE (addr)
+@findex ADDR_BITS_REMOVE
+If a raw machine instruction address includes any bits that are not
+really part of the address, then define this macro to expand into an
+expression that zeroes those bits in @var{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. ADDR_BITS_REMOVE should filter out these
+bits with an expression such as @code{((addr) & ~3)}.
+
+@item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
+@findex ADDRESS_TO_POINTER
+Store in @var{buf} a pointer of type @var{type} representing the address
+@var{addr}, in the appropriate format for the current architecture.
+This macro may safely assume that @var{type} is either a pointer or a
+C@t{++} reference type.
+@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
+
+@item BEFORE_MAIN_LOOP_HOOK
+@findex 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, @value{GDBN} will probably not compile, let alone run
+correctly. This macro is currently used only for the unsupported i960 Nindy
+target, and should not be used in any other configuration.
+
+@item BELIEVE_PCC_PROMOTION
+@findex BELIEVE_PCC_PROMOTION
+Define if the compiler promotes a @code{short} or @code{char}
+parameter to an @code{int}, but still reports the parameter as its
+original type, rather than the promoted type.
+
+@item BELIEVE_PCC_PROMOTION_TYPE
+@findex BELIEVE_PCC_PROMOTION_TYPE
+Define this if @value{GDBN} should believe the type of a @code{short}
+argument when compiled by @code{pcc}, but look within a full int space to get
+its value. Only defined for Sun-3 at present.
+
+@item BITS_BIG_ENDIAN
+@findex BITS_BIG_ENDIAN
+Define this if the numbering of bits in the targets does @strong{not} match the
+endianness 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.
+
+@item BREAKPOINT
+@findex 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.
+
+@code{BREAKPOINT} has been deprecated in favor of
+@code{BREAKPOINT_FROM_PC}.
+
+@item BIG_BREAKPOINT
+@itemx LITTLE_BREAKPOINT
+@findex LITTLE_BREAKPOINT
+@findex BIG_BREAKPOINT
+Similar to BREAKPOINT, but used for bi-endian targets.
+
+@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
+favor of @code{BREAKPOINT_FROM_PC}.
+
+@item REMOTE_BREAKPOINT
+@itemx LITTLE_REMOTE_BREAKPOINT
+@itemx BIG_REMOTE_BREAKPOINT
+@findex BIG_REMOTE_BREAKPOINT
+@findex LITTLE_REMOTE_BREAKPOINT
+@findex REMOTE_BREAKPOINT
+Similar to BREAKPOINT, but used for remote targets.
+
+@code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been
+deprecated in favor of @code{BREAKPOINT_FROM_PC}.
+
+@item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr})
+@findex BREAKPOINT_FROM_PC
+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 *@var{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 @var{BREAKPOINT} macros.
+
+@item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache})
+@itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache})
+@findex MEMORY_REMOVE_BREAKPOINT
+@findex MEMORY_INSERT_BREAKPOINT
+Insert or remove memory based breakpoints. Reasonable defaults
+(@code{default_memory_insert_breakpoint} and
+@code{default_memory_remove_breakpoint} respectively) have been
+provided so that it is not necessary to define these for most
+architectures. Architectures which may want to define
+@code{MEMORY_INSERT_BREAKPOINT} and @code{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
+@code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
+reason.
+
+@item CALL_DUMMY_P
+@findex CALL_DUMMY_P
+A C expression that is non-zero when the target supports inferior function
+calls.
+
+@item CALL_DUMMY_WORDS
+@findex CALL_DUMMY_WORDS
+Pointer to an array of @code{LONGEST} words of data containing
+host-byte-ordered @code{REGISTER_BYTES} sized values that partially
+specify the sequence of instructions needed for an inferior function
+call.
+
+Should be deprecated in favor of a macro that uses target-byte-ordered
+data.
+
+@item SIZEOF_CALL_DUMMY_WORDS
+@findex SIZEOF_CALL_DUMMY_WORDS
+The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must
+return a positive value. See also @code{CALL_DUMMY_LENGTH}.
+
+@item CALL_DUMMY
+@findex CALL_DUMMY
+A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated.
+
+@item CALL_DUMMY_LOCATION
+@findex CALL_DUMMY_LOCATION
+See the file @file{inferior.h}.
+
+@item CALL_DUMMY_STACK_ADJUST
+@findex CALL_DUMMY_STACK_ADJUST
+Stack adjustment needed when performing an inferior function call.
+
+Should be deprecated in favor of something like @code{STACK_ALIGN}.
+
+@item CALL_DUMMY_STACK_ADJUST_P
+@findex CALL_DUMMY_STACK_ADJUST_P
+Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}.
+
+Should be deprecated in favor of something like @code{STACK_ALIGN}.
+
+@item CANNOT_FETCH_REGISTER (@var{regno})
+@findex CANNOT_FETCH_REGISTER
+A C expression that should be nonzero if @var{regno} cannot be fetched
+from an inferior process. This is only relevant if
+@code{FETCH_INFERIOR_REGISTERS} is not defined.
+
+@item CANNOT_STORE_REGISTER (@var{regno})
+@findex CANNOT_STORE_REGISTER
+A C expression that should be nonzero if @var{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,
+@value{GDBN} will assume that all registers may be written.
+
+@item DO_DEFERRED_STORES
+@itemx CLEAR_DEFERRED_STORES
+@findex CLEAR_DEFERRED_STORES
+@findex DO_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?
+
+@item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
+@findex COERCE_FLOAT_TO_DOUBLE
+@cindex promotion to @code{double}
+@cindex @code{float} arguments
+@cindex prototyped functions, passing arguments to
+@cindex passing arguments to prototyped functions
+Return non-zero if GDB should promote @code{float} values to
+@code{double} when calling a non-prototyped function. The argument
+@var{actual} is the type of the value we want to pass to the function.
+The argument @var{formal} is the type of this argument, as it appears in
+the function's definition. Note that @var{formal} may be zero if we
+have no debugging information for the function, or if we're passing more
+arguments than are officially declared (for example, varargs). This
+macro is never invoked if the function definitely has a prototype.
+
+How you should pass arguments to a function depends on whether it was
+defined in K&R style or prototype style. If you define a function using
+the K&R syntax that takes a @code{float} argument, then callers must
+pass that argument as a @code{double}. If you define the function using
+the prototype syntax, then you must pass the argument as a @code{float},
+with no promotion.
+
+Unfortunately, on certain older platforms, the debug info doesn't
+indicate reliably how each function was defined. A function type's
+@code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was
+defined in prototype style. When calling a function whose
+@code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the
+@code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do.
+
+@findex standard_coerce_float_to_double
+For modern targets, it is proper to assume that, if the prototype flag
+is unset, that can be trusted: @code{float} arguments should be promoted
+to @code{double}. You should use the function
+@code{standard_coerce_float_to_double} to get this behavior.
+
+@findex default_coerce_float_to_double
+For some older targets, if the prototype flag is unset, that doesn't
+tell us anything. So we guess that, if we don't have a type for the
+formal parameter (@i{i.e.}, the first argument to
+@code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it;
+otherwise, we should leave it alone. The function
+@code{default_coerce_float_to_double} provides this behavior; it is the
+default value, for compatibility with older configurations.
+
+@item int CONVERT_REGISTER_P(@var{regnum})
+@findex CONVERT_REGISTER_P
+Return non-zero if register @var{regnum} can represent data values in a
+non-standard form.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
+@item CPLUS_MARKER
+@findex CPLUS_MARKERz
+Define this to expand into the character that G@t{++} uses to distinguish
+compiler-generated identifiers from programmer-specified identifiers.
+By default, this expands into @code{'$'}. Most System V targets should
+define this to @code{'.'}.
+
+@item DBX_PARM_SYMBOL_CLASS
+@findex DBX_PARM_SYMBOL_CLASS
+Hook for the @code{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.
+
+@item DECR_PC_AFTER_BREAK
+@findex 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
+@code{BREAKPOINT}, though not always. For most targets this value will be 0.
+
+@item DECR_PC_AFTER_HW_BREAK
+@findex DECR_PC_AFTER_HW_BREAK
+Similarly, for hardware breakpoints.
+
+@item DISABLE_UNSETTABLE_BREAK (@var{addr})
+@findex DISABLE_UNSETTABLE_BREAK
+If defined, this should evaluate to 1 if @var{addr} is in a shared
+library in which breakpoints cannot be set and so should be disabled.
+
+@item DO_REGISTERS_INFO
+@findex DO_REGISTERS_INFO
+If defined, use this to print the value of a register or all registers.
+
+@item PRINT_FLOAT_INFO()
+#findex PRINT_FLOAT_INFO
+If defined, then the @samp{info float} command will print information about
+the processor's floating point unit.
+
+@item DWARF_REG_TO_REGNUM
+@findex DWARF_REG_TO_REGNUM
+Convert DWARF register number into @value{GDBN} regnum. If not defined,
+no conversion will be performed.
+
+@item DWARF2_REG_TO_REGNUM
+@findex DWARF2_REG_TO_REGNUM
+Convert DWARF2 register number into @value{GDBN} regnum. If not
+defined, no conversion will be performed.
+
+@item ECOFF_REG_TO_REGNUM
+@findex ECOFF_REG_TO_REGNUM
+Convert ECOFF register number into @value{GDBN} regnum. If not defined,
+no conversion will be performed.
+
+@item END_OF_TEXT_DEFAULT
+@findex END_OF_TEXT_DEFAULT
+This is an expression that should designate the end of the text section.
+@c (? FIXME ?)
+
+@item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf})
+@findex EXTRACT_RETURN_VALUE
+Define this to extract a function's return value of type @var{type} from
+the raw register state @var{regbuf} and copy that, in virtual format,
+into @var{valbuf}.
+
+@item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
+@findex EXTRACT_STRUCT_VALUE_ADDRESS
+When defined, extract from the array @var{regbuf} (containing the raw
+register state) the @code{CORE_ADDR} at which a function should return
+its structure value.
+
+If not defined, @code{EXTRACT_RETURN_VALUE} is used.
+
+@item EXTRACT_STRUCT_VALUE_ADDRESS_P()
+@findex EXTRACT_STRUCT_VALUE_ADDRESS_P
+Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
+
+@item FLOAT_INFO
+@findex FLOAT_INFO
+Deprecated in favor of @code{PRINT_FLOAT_INFO}.
+
+@item FP_REGNUM
+@findex FP_REGNUM
+If the virtual frame pointer is kept in a register, then define this
+macro to be the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_READ_FP} is not
+defined.
+
+@item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
+@findex FRAMELESS_FUNCTION_INVOCATION
+Define this to an expression that returns 1 if the function invocation
+represented by @var{fi} does not have a stack frame associated with it.
+Otherwise return 0.
+
+@item FRAME_ARGS_ADDRESS_CORRECT
+@findex FRAME_ARGS_ADDRESS_CORRECT
+See @file{stack.c}.
+
+@item FRAME_CHAIN(@var{frame})
+@findex FRAME_CHAIN
+Given @var{frame}, return a pointer to the calling frame.
+
+@item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
+@findex FRAME_CHAIN_VALID
+Define this to be an expression that returns zero if the given frame is
+an outermost frame, with no caller, and nonzero otherwise. Several
+common definitions are available:
+
+@itemize @bullet
+@item
+@code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
+and given frame's PC is not inside the startup file (such as
+@file{crt0.o}).
+
+@item
+@code{func_frame_chain_valid} is nonzero if the chain
+pointer is nonzero and the given frame's PC is not in @code{main} or a
+known entry point function (such as @code{_start}).
+
+@item
+@code{generic_file_frame_chain_valid} and
+@code{generic_func_frame_chain_valid} are equivalent implementations for
+targets using generic dummy frames.
+@end itemize
+
+@item FRAME_INIT_SAVED_REGS(@var{frame})
+@findex FRAME_INIT_SAVED_REGS
+See @file{frame.h}. Determines the address of all registers in the
+current stack frame storing each in @code{frame->saved_regs}. Space for
+@code{frame->saved_regs} shall be allocated by
+@code{FRAME_INIT_SAVED_REGS} using either
+@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
+
+@code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
+
+@item FRAME_NUM_ARGS (@var{fi})
+@findex FRAME_NUM_ARGS
+For the frame described by @var{fi} return the number of arguments that
+are being passed. If the number of arguments is not known, return
+@code{-1}.
+
+@item FRAME_SAVED_PC(@var{frame})
+@findex FRAME_SAVED_PC
+Given @var{frame}, return the pc saved there. This is the return
+address.
+
+@item FUNCTION_EPILOGUE_SIZE
+@findex FUNCTION_EPILOGUE_SIZE
+For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
+function end symbol is 0. For such targets, you must define
+@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
+function's epilogue.
+
+@item FUNCTION_START_OFFSET
+@findex FUNCTION_START_OFFSET
+An integer, giving the offset in bytes from a function's address (as
+used in the values of symbols, function pointers, etc.), and the
+function's first genuine instruction.
+
+This is zero on almost all machines: the function's address is usually
+the address of its first instruction. However, on the VAX, for example,
+each function starts with two bytes containing a bitmask indicating
+which registers to save upon entry to the function. The VAX @code{call}
+instructions check this value, and save the appropriate registers
+automatically. Thus, since the offset from the function's address to
+its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
+be 2 on the VAX.
+
+@item GCC_COMPILED_FLAG_SYMBOL
+@itemx GCC2_COMPILED_FLAG_SYMBOL
+@findex GCC2_COMPILED_FLAG_SYMBOL
+@findex GCC_COMPILED_FLAG_SYMBOL
+If defined, these are the names of the symbols that @value{GDBN} will
+look for to detect that GCC compiled the file. The default symbols
+are @code{gcc_compiled.} and @code{gcc2_compiled.},
+respectively. (Currently only defined for the Delta 68.)
+
+@item @value{GDBN}_MULTI_ARCH
+@findex @value{GDBN}_MULTI_ARCH
+If defined and non-zero, enables support for multiple architectures
+within @value{GDBN}.
+
+This support can be enabled at two levels. At level one, only
+definitions for previously undefined macros are provided; at level two,
+a multi-arch definition of all architecture dependent macros will be
+defined.
+
+@item @value{GDBN}_TARGET_IS_HPPA
+@findex @value{GDBN}_TARGET_IS_HPPA
+This determines whether horrible kludge code in @file{dbxread.c} and
+@file{partial-stab.h} is used to mangle multiple-symbol-table files from
+HPPA's. This should all be ripped out, and a scheme like @file{elfread.c}
+used instead.
+
+@item GET_LONGJMP_TARGET
+@findex 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
+the header file @file{setjmp.h} is needed to define it.
+
+This macro determines the target PC address that @code{longjmp} will jump to,
+assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
+@code{CORE_ADDR *} as argument, and stores the target PC value through this
+pointer. It examines the current state of the machine as needed.
+
+@item GET_SAVED_REGISTER
+@findex GET_SAVED_REGISTER
+@findex get_saved_register
+Define this if you need to supply your own definition for the function
+@code{get_saved_register}.
+
+@item IBM6000_TARGET
+@findex 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 a haste and we are
+repenting at leisure.
+
+@item I386_USE_GENERIC_WATCHPOINTS
+An x86-based target can define this to use the generic x86 watchpoint
+support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
+
+@item SYMBOLS_CAN_START_WITH_DOLLAR
+@findex SYMBOLS_CAN_START_WITH_DOLLAR
+Some systems have routines whose names start with @samp{$}. Giving this
+macro a non-zero value tells @value{GDBN}'s expression parser to check for such
+routines when parsing tokens that begin with @samp{$}.
+
+On HP-UX, certain system routines (millicode) have names beginning with
+@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
+routine that handles inter-space procedure calls on PA-RISC.
+
+@item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
+@findex INIT_EXTRA_FRAME_INFO
+If additional information about the frame is required this should be
+stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
+is allocated using @code{frame_obstack_alloc}.
+
+@item INIT_FRAME_PC (@var{fromleaf}, @var{prev})
+@findex INIT_FRAME_PC
+This is a C statement that sets the pc of the frame pointed to by
+@var{prev}. [By default...]
+
+@item INNER_THAN (@var{lhs}, @var{rhs})
+@findex INNER_THAN
+Returns non-zero if stack address @var{lhs} is inner than (nearer to the
+stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
+the target's stack grows downward in memory, or @code{lhs > rsh} if the
+stack grows upward.
+
+@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc})
+@findex gdbarch_in_function_epilogue_p
+Returns non-zero if the given @var{pc} 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.
+
+@item SIGTRAMP_START (@var{pc})
+@findex SIGTRAMP_START
+@itemx SIGTRAMP_END (@var{pc})
+@findex SIGTRAMP_END
+Define these to be the start and end address of the @code{sigtramp} for the
+given @var{pc}. On machines where the address is just a compile time
+constant, the macro expansion will typically just ignore the supplied
+@var{pc}.
+
+@item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name})
+@findex IN_SOLIB_CALL_TRAMPOLINE
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that connects to a shared library.
+
+@item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name})
+@findex IN_SOLIB_RETURN_TRAMPOLINE
+Define this to evaluate to nonzero if the program is stopped in the
+trampoline that returns from a shared library.
+
+@item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
+@findex IN_SOLIB_DYNSYM_RESOLVE_CODE
+Define this to evaluate to nonzero if the program is stopped in the
+dynamic linker.
+
+@item SKIP_SOLIB_RESOLVER (@var{pc})
+@findex SKIP_SOLIB_RESOLVER
+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.
+
+@item INTEGER_TO_ADDRESS (@var{type}, @var{buf})
+@findex INTEGER_TO_ADDRESS
+@cindex converting integers to addresses
+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.
+
+@emph{Pragmatics: When the user copies a well defined expression from
+their source code and passes it, as a parameter, to @value{GDBN}'s
+@code{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, @value{GDBN} 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 @value{GDBN} casts integers
+to pointers; they are complaining that they can't take an address from a
+disassembly listing and give it to @code{x/i}. Adding an architecture
+method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for
+@value{GDBN} to ``get it right'' in all circumstances.}
+
+@xref{Target Architecture Definition, , Pointers Are Not Always
+Addresses}.
+
+@item IS_TRAPPED_INTERNALVAR (@var{name})
+@findex IS_TRAPPED_INTERNALVAR
+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 @value{GDBN}. Currently only used by the h8500. Note that this
+could be either a host or target conditional.
+
+@item NEED_TEXT_START_END
+@findex NEED_TEXT_START_END
+Define this if @value{GDBN} should determine the start and end addresses of the
+text section. (Seems dubious.)
+
+@item NO_HIF_SUPPORT
+@findex NO_HIF_SUPPORT
+(Specific to the a29k.)
+
+@item POINTER_TO_ADDRESS (@var{type}, @var{buf})
+@findex POINTER_TO_ADDRESS
+Assume that @var{buf} holds a pointer of type @var{type}, in the
+appropriate format for the current architecture. Return the byte
+address the pointer refers to.
+@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
+
+@item REGISTER_CONVERTIBLE (@var{reg})
+@findex REGISTER_CONVERTIBLE
+Return non-zero if @var{reg} uses different raw and virtual formats.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to})
+@findex REGISTER_TO_VALUE
+Convert the raw contents of register @var{regnum} into a value of type
+@var{type}.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
+@item REGISTER_RAW_SIZE (@var{reg})
+@findex REGISTER_RAW_SIZE
+Return the raw size of @var{reg}; defaults to the size of the register's
+virtual type.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_VIRTUAL_SIZE (@var{reg})
+@findex REGISTER_VIRTUAL_SIZE
+Return the virtual size of @var{reg}; defaults to the size of the
+register's virtual type.
+Return the virtual size of @var{reg}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_VIRTUAL_TYPE (@var{reg})
+@findex REGISTER_VIRTUAL_TYPE
+Return the virtual type of @var{reg}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
+@findex REGISTER_CONVERT_TO_VIRTUAL
+Convert the value of register @var{reg} from its raw form to its virtual
+form.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
+@findex REGISTER_CONVERT_TO_RAW
+Convert the value of register @var{reg} from its virtual form to its raw
+form.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item RETURN_VALUE_ON_STACK(@var{type})
+@findex RETURN_VALUE_ON_STACK
+@cindex returning structures by value
+@cindex structures, returning by value
+
+Return non-zero if values of type TYPE are returned on the stack, using
+the ``struct convention'' (i.e., the caller provides a pointer to a
+buffer in which the callee should store the return value). This
+controls how the @samp{finish} command finds a function's return value,
+and whether an inferior function call reserves space on the stack for
+the return value.
+
+The full logic @value{GDBN} uses here is kind of odd.
+
+@itemize @bullet
+@item
+If the type being returned by value is not a structure, union, or array,
+and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
+concludes the value is not returned using the struct convention.
+
+@item
+Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
+If that returns non-zero, @value{GDBN} assumes the struct convention is
+in use.
+@end itemize
+
+In other words, to indicate that a given type is returned by value using
+the struct convention, that type must be either a struct, union, array,
+or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
+that @code{USE_STRUCT_CONVENTION} likes.
+
+Note that, in C and C@t{++}, arrays are never returned by value. In those
+languages, these predicates will always see a pointer type, never an
+array type. All the references above to arrays being returned by value
+apply only to other languages.
+
+@item SOFTWARE_SINGLE_STEP_P()
+@findex SOFTWARE_SINGLE_STEP_P
+Define this as 1 if the target does not have a hardware single-step
+mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
+
+@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p})
+@findex SOFTWARE_SINGLE_STEP
+A function that inserts or removes (depending on
+@var{insert_breapoints_p}) breakpoints at each possible destinations of
+the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
+for examples.
+
+@item SOFUN_ADDRESS_MAYBE_MISSING
+@findex SOFUN_ADDRESS_MAYBE_MISSING
+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.
+
+@code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
+hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
+entries in stabs-format debugging information. @code{N_SO} stabs mark
+the beginning and ending addresses of compilation units in the text
+segment. @code{N_FUN} stabs mark the starts and ends of functions.
+
+@code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
+
+@itemize @bullet
+@item
+@code{N_FUN} stabs have an address of zero. Instead, you should find the
+addresses 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.
+
+@item
+@code{N_SO} stabs have an address of zero, too. You just look at the
+@code{N_FUN} stabs that appear before and after the @code{N_SO} stab,
+and guess the starting and ending addresses of the compilation unit from
+them.
+@end itemize
+
+@item PCC_SOL_BROKEN
+@findex PCC_SOL_BROKEN
+(Used only in the Convex target.)
+
+@item PC_IN_CALL_DUMMY
+@findex PC_IN_CALL_DUMMY
+See @file{inferior.h}.
+
+@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
+@findex PC_IN_SIGTRAMP
+@cindex sigtramp
+The @dfn{sigtramp} is a routine that the kernel calls (which then calls
+the signal handler). On most machines it is a library routine that is
+linked into the executable.
+
+This function, given a program counter value in @var{pc} and the
+(possibly NULL) name of the function in which that @var{pc} resides,
+returns nonzero if the @var{pc} and/or @var{name} show that we are in
+sigtramp.
+
+@item PC_LOAD_SEGMENT
+@findex PC_LOAD_SEGMENT
+If defined, print information about the load segment for the program
+counter. (Defined only for the RS/6000.)
+
+@item PC_REGNUM
+@findex PC_REGNUM
+If the program counter is kept in a register, then define this macro to
+be the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_READ_PC} and
+@code{TARGET_WRITE_PC} are not defined.
+
+@item NPC_REGNUM
+@findex NPC_REGNUM
+The number of the ``next program counter'' register, if defined.
+
+@item PARM_BOUNDARY
+@findex PARM_BOUNDARY
+If non-zero, round arguments to a boundary of this many bits before
+pushing them on the stack.
+
+@item PRINT_REGISTER_HOOK (@var{regno})
+@findex PRINT_REGISTER_HOOK
+If defined, this must be a function that prints the contents of the
+given register to standard output.
+
+@item PRINT_TYPELESS_INTEGER
+@findex PRINT_TYPELESS_INTEGER
+This is an obscure substitute for @code{print_longest} that seems to
+have been defined for the Convex target.
+
+@item PROCESS_LINENUMBER_HOOK
+@findex PROCESS_LINENUMBER_HOOK
+A hook defined for XCOFF reading.
+
+@item PROLOGUE_FIRSTLINE_OVERLAP
+@findex PROLOGUE_FIRSTLINE_OVERLAP
+(Only used in unsupported Convex configuration.)
+
+@item PS_REGNUM
+@findex PS_REGNUM
+If defined, this is the number of the processor status register. (This
+definition is only used in generic code when parsing "$ps".)
+
+@item POP_FRAME
+@findex POP_FRAME
+@findex call_function_by_hand
+@findex return_command
+Used in @samp{call_function_by_hand} to remove an artificial stack
+frame and in @samp{return_command} to remove a real stack frame.
+
+@item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@findex PUSH_ARGUMENTS
+Define this to push arguments onto the stack for inferior function
+call. Returns the updated stack pointer value.
+
+@item PUSH_DUMMY_FRAME
+@findex PUSH_DUMMY_FRAME
+Used in @samp{call_function_by_hand} to create an artificial stack frame.
+
+@item REGISTER_BYTES
+@findex REGISTER_BYTES
+The total amount of space needed to store @value{GDBN}'s copy of the machine's
+register state.
+
+@item REGISTER_NAME(@var{i})
+@findex REGISTER_NAME
+Return the name of register @var{i} as a string. May return @code{NULL}
+or @code{NUL} to indicate that register @var{i} is not valid.
+
+@item REGISTER_NAMES
+@findex REGISTER_NAMES
+Deprecated in favor of @code{REGISTER_NAME}.
+
+@item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
+@findex REG_STRUCT_HAS_ADDR
+Define this to return 1 if the given type will be passed by pointer
+rather than directly.
+
+@item SAVE_DUMMY_FRAME_TOS (@var{sp})
+@findex SAVE_DUMMY_FRAME_TOS
+Used in @samp{call_function_by_hand} to notify the target dependent code
+of the top-of-stack value that will be passed to the the inferior code.
+This is the value of the @code{SP} after both the dummy frame and space
+for parameters/results have been allocated on the stack.
+
+@item SDB_REG_TO_REGNUM
+@findex SDB_REG_TO_REGNUM
+Define this to convert sdb register numbers into @value{GDBN} regnums. If not
+defined, no conversion will be done.
+
+@c OBSOLETE @item SHIFT_INST_REGS
+@c OBSOLETE @findex SHIFT_INST_REGS
+@c OBSOLETE (Only used for m88k targets.)
+
+@item SKIP_PERMANENT_BREAKPOINT
+@findex SKIP_PERMANENT_BREAKPOINT
+Advance the inferior's PC past a permanent breakpoint. @value{GDBN} 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 @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's
+state so that execution will resume just after the breakpoint. This
+macro does the right thing even when the breakpoint is in the delay slot
+of a branch or jump.
+
+@item SKIP_PROLOGUE (@var{pc})
+@findex SKIP_PROLOGUE
+A C expression that returns the address of the ``real'' code beyond the
+function entry prologue found at @var{pc}.
+
+@item SKIP_TRAMPOLINE_CODE (@var{pc})
+@findex SKIP_TRAMPOLINE_CODE
+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.
+
+@item SP_REGNUM
+@findex SP_REGNUM
+If the stack-pointer is kept in a register, then define this macro to be
+the number (greater than or equal to zero) of that register.
+
+This should only need to be defined if @code{TARGET_WRITE_SP} and
+@code{TARGET_WRITE_SP} are not defined.
+
+@item STAB_REG_TO_REGNUM
+@findex STAB_REG_TO_REGNUM
+Define this to convert stab register numbers (as gotten from `r'
+declarations) into @value{GDBN} regnums. If not defined, no conversion will be
+done.
+
+@item STACK_ALIGN (@var{addr})
+@findex STACK_ALIGN
+Define this to adjust the address to the alignment required for the
+processor's stack.
+
+@item STEP_SKIPS_DELAY (@var{addr})
+@findex STEP_SKIPS_DELAY
+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, @value{GDBN} will single-step over that instruction before resuming
+normally. Currently only defined for the Mips.
+
+@item STORE_RETURN_VALUE (@var{type}, @var{valbuf})
+@findex STORE_RETURN_VALUE
+A C expression that stores a function return value of type @var{type},
+where @var{valbuf} is the address of the value to be stored.
+
+@item SUN_FIXED_LBRAC_BUG
+@findex SUN_FIXED_LBRAC_BUG
+(Used only for Sun-3 and Sun-4 targets.)
+
+@item SYMBOL_RELOADING_DEFAULT
+@findex SYMBOL_RELOADING_DEFAULT
+The default value of the ``symbol-reloading'' variable. (Never defined in
+current sources.)
+
+@item TARGET_CHAR_BIT
+@findex TARGET_CHAR_BIT
+Number of bits in a char; defaults to 8.
+
+@item TARGET_CHAR_SIGNED
+@findex TARGET_CHAR_SIGNED
+Non-zero if @code{char} is normally signed on this architecture; zero if
+it should be unsigned.
+
+The ISO C standard requires the compiler to treat @code{char} as
+equivalent to either @code{signed char} or @code{unsigned char}; any
+character in the standard execution set is supposed to be positive.
+Most compilers treat @code{char} as signed, but @code{char} is unsigned
+on the IBM S/390, RS6000, and PowerPC targets.
+
+@item TARGET_COMPLEX_BIT
+@findex TARGET_COMPLEX_BIT
+Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
+
+At present this macro is not used.
+
+@item TARGET_DOUBLE_BIT
+@findex TARGET_DOUBLE_BIT
+Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
+
+@item TARGET_DOUBLE_COMPLEX_BIT
+@findex TARGET_DOUBLE_COMPLEX_BIT
+Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+At present this macro is not used.
+
+@item TARGET_FLOAT_BIT
+@findex TARGET_FLOAT_BIT
+Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_INT_BIT
+@findex TARGET_INT_BIT
+Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_BIT
+@findex TARGET_LONG_BIT
+Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
+
+@item TARGET_LONG_DOUBLE_BIT
+@findex TARGET_LONG_DOUBLE_BIT
+Number of bits in a long double float;
+defaults to @code{2 * TARGET_DOUBLE_BIT}.
+
+@item TARGET_LONG_LONG_BIT
+@findex TARGET_LONG_LONG_BIT
+Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
+
+@item TARGET_PTR_BIT
+@findex TARGET_PTR_BIT
+Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
+
+@item TARGET_SHORT_BIT
+@findex TARGET_SHORT_BIT
+Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
+
+@item TARGET_READ_PC
+@findex TARGET_READ_PC
+@itemx TARGET_WRITE_PC (@var{val}, @var{pid})
+@findex TARGET_WRITE_PC
+@itemx TARGET_READ_SP
+@findex TARGET_READ_SP
+@itemx TARGET_WRITE_SP
+@findex TARGET_WRITE_SP
+@itemx TARGET_READ_FP
+@findex TARGET_READ_FP
+@findex read_pc
+@findex write_pc
+@findex read_sp
+@findex write_sp
+@findex read_fp
+These change the behavior of @code{read_pc}, @code{write_pc},
+@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets,
+these may be left undefined. @value{GDBN} will call the read and write
+register functions with the relevant @code{_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.
+
+@item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp})
+@findex TARGET_VIRTUAL_FRAME_POINTER
+Returns a @code{(register, offset)} pair representing the virtual
+frame pointer in use at the code address @var{pc}. If virtual
+frame pointers are not used, a default definition simply returns
+@code{FP_REGNUM}, with an offset of zero.
+
+@item TARGET_HAS_HARDWARE_WATCHPOINTS
+If non-zero, the target has support for hardware-assisted
+watchpoints. @xref{Algorithms, watchpoints}, for more details and
+other related macros.
+
+@item TARGET_PRINT_INSN (@var{addr}, @var{info})
+@findex TARGET_PRINT_INSN
+This is the function used by @value{GDBN} to print an assembly
+instruction. It prints the instruction at address @var{addr} in
+debugged memory and returns the length of the instruction, in bytes. If
+a target doesn't define its own printing routine, it defaults to an
+accessor function for the global pointer @code{tm_print_insn}. This
+usually points to a function in the @code{opcodes} library (@pxref{Support
+Libraries, ,Opcodes}). @var{info} is a structure (of type
+@code{disassemble_info}) defined in @file{include/dis-asm.h} used to
+pass information to the instruction decoding routine.
+
+@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
+@findex USE_STRUCT_CONVENTION
+If defined, this must be an expression that is nonzero if a value of the
+given @var{type} being returned from a function must have space
+allocated for it on the stack. @var{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.
+
+@item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to})
+@findex VALUE_TO_REGISTER
+Convert a value of type @var{type} into the raw contents of register
+@var{regnum}'s.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
+@item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
+@findex VARIABLES_INSIDE_BLOCK
+For dbx-style debugging information, if the compiler puts variable
+declarations inside LBRAC/RBRAC blocks, this should be defined to be
+nonzero. @var{desc} is the value of @code{n_desc} from the
+@code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the
+presence of either the @code{GCC_COMPILED_SYMBOL} or the
+@code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
+
+@item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
+@findex OS9K_VARIABLES_INSIDE_BLOCK
+Similarly, for OS/9000. Defaults to 1.
+@end table
+
+Motorola M68K target conditionals.
+
+@ftable @code
+@item BPT_VECTOR
+Define this to be the 4-bit location of the breakpoint trap vector. If
+not defined, it will default to @code{0xf}.
+
+@item REMOTE_BPT_VECTOR
+Defaults to @code{1}.
+@end ftable
+
+@section Adding a New Target
+
+@cindex adding a target
+The following files add a target to @value{GDBN}:
+
+@table @file
+@vindex TDEPFILES
+@item gdb/config/@var{arch}/@var{ttt}.mt
+Contains a Makefile fragment specific to this target. Specifies what
+object files are needed for target @var{ttt}, by defining
+@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
+the header file which describes @var{ttt}, by defining @samp{TM_FILE=
+tm-@var{ttt}.h}.
+
+You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
+but these are now deprecated, replaced by autoconf, and may go away in
+future versions of @value{GDBN}.
+
+@item gdb/@var{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
+@file{tm-@var{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.
+
+@item gdb/@var{arch}-tdep.c
+@itemx gdb/@var{arch}-tdep.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
+@file{@var{ttt}-tdep.h}. It can be shared among many targets that use
+the same processor.
+
+@item gdb/config/@var{arch}/tm-@var{ttt}.h
+(@file{tm.h} is a link to this file, created by @code{configure}). Contains
+macro definitions about the target machine's registers, stack frame
+format and instructions.
+
+New targets do not need this file and should not create it.
+
+@item gdb/config/@var{arch}/tm-@var{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
+@file{tm-@var{ttt}.h}. It can be shared among many targets that use the
+same processor.
+
+New targets do not need this file and should not create it.
+
+@end table
+
+If you are adding a new operating system for an existing CPU chip, add a
+@file{config/tm-@var{os}.h} file that describes the operating system
+facilities that are unusual (extra symbol table info; the breakpoint
+instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
+that just @code{#include}s @file{tm-@var{arch}.h} and
+@file{config/tm-@var{os}.h}.
+
+
+@section Converting an existing Target Architecture to Multi-arch
+@cindex converting targets to multi-arch
+
+This section describes the current accepted best practice for converting
+an existing target architecture to the multi-arch framework.
+
+The process consists of generating, testing, posting and committing a
+sequence of patches. Each patch must contain a single change, for
+instance:
+
+@itemize @bullet
+
+@item
+Directly convert a group of functions into macros (the conversion does
+not change the behavior of any of the functions).
+
+@item
+Replace a non-multi-arch with a multi-arch mechanism (e.g.,
+@code{FRAME_INFO}).
+
+@item
+Enable multi-arch level one.
+
+@item
+Delete one or more files.
+
+@end itemize
+
+@noindent
+There isn't a size limit on a patch, however, a developer is strongly
+encouraged to keep the patch size down.
+
+Since each patch is well defined, and since each change has been tested
+and shows no regressions, the patches are considered @emph{fairly}
+obvious. Such patches, when submitted by developers listed in the
+@file{MAINTAINERS} file, do not need approval. Occasional steps in the
+process may be more complicated and less clear. The developer is
+expected to use their judgment and is encouraged to seek advice as
+needed.
+
+@subsection Preparation
+
+The first step is to establish control. Build (with @option{-Werror}
+enabled) and test the target so that there is a baseline against which
+the debugger can be compared.
+
+At no stage can the test results regress or @value{GDBN} stop compiling
+with @option{-Werror}.
+
+@subsection Add the multi-arch initialization code
+
+The objective of this step is to establish the basic multi-arch
+framework. It involves
+
+@itemize @bullet
+
+@item
+The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The
+above is from the original example and uses K&R C. @value{GDBN}
+has since converted to ISO C but lets ignore that.} that creates
+the architecture:
+@smallexample
+static struct gdbarch *
+d10v_gdbarch_init (info, arches)
+ struct gdbarch_info info;
+ struct gdbarch_list *arches;
+@{
+ struct gdbarch *gdbarch;
+ /* there is only one d10v architecture */
+ if (arches != NULL)
+ return arches->gdbarch;
+ gdbarch = gdbarch_alloc (&info, NULL);
+ return gdbarch;
+@}
+@end smallexample
+@noindent
+@emph{}
+
+@item
+A per-architecture dump function to print any architecture specific
+information:
+@smallexample
+static void
+mips_dump_tdep (struct gdbarch *current_gdbarch,
+ struct ui_file *file)
+@{
+ @dots{} code to print architecture specific info @dots{}
+@}
+@end smallexample
+
+@item
+A change to @code{_initialize_@var{arch}_tdep} to register this new
+architecture:
+@smallexample
+void
+_initialize_mips_tdep (void)
+@{
+ gdbarch_register (bfd_arch_mips, mips_gdbarch_init,
+ mips_dump_tdep);
+@end smallexample
+
+@item
+Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@*
+@file{config/@var{arch}/tm-@var{arch}.h}.
+
+@end itemize
+
+@subsection Update multi-arch incompatible mechanisms
+
+Some mechanisms do not work with multi-arch. They include:
+
+@table @code
+@item EXTRA_FRAME_INFO
+Delete.
+@item FRAME_FIND_SAVED_REGS
+Replaced with @code{FRAME_INIT_SAVED_REGS}
+@end table
+
+@noindent
+At this stage you could also consider converting the macros into
+functions.
+
+@subsection Prepare for multi-arch level to one
+
+Temporally set @code{GDB_MULTI_ARCH} to @code{GDB_MULTI_ARCH_PARTIAL}
+and then build and start @value{GDBN} (the change should not be
+committed). @value{GDBN} may not build, and once built, it may die with
+an internal error listing the architecture methods that must be
+provided.
+
+Fix any build problems (patch(es)).
+
+Convert all the architecture methods listed, which are only macros, into
+functions (patch(es)).
+
+Update @code{@var{arch}_gdbarch_init} to set all the missing
+architecture methods and wrap the corresponding macros in @code{#if
+!GDB_MULTI_ARCH} (patch(es)).
+
+@subsection Set multi-arch level one
+
+Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a
+single patch).
+
+Any problems with throwing ``the switch'' should have been fixed
+already.
+
+@subsection Convert remaining macros
+
+Suggest converting macros into functions (and setting the corresponding
+architecture method) in small batches.
+
+@subsection Set multi-arch level to two
+
+This should go smoothly.
+
+@subsection Delete the TM file
+
+The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and
+@file{configure.in} updated.
+
+
+@node Target Vector Definition
+
+@chapter Target Vector Definition
+@cindex target vector
+
+The target vector defines the interface between @value{GDBN}'s
+abstract handling of target systems, and the nitty-gritty code that
+actually exercises control over a process or a serial port.
+@value{GDBN} includes some 30-40 different target vectors; however,
+each configuration of @value{GDBN} includes only a few of them.
+
+@section File Targets
+
+Both executables and core files have target vectors.
+
+@section Standard Protocol and Remote Stubs
+
+@value{GDBN}'s file @file{remote.c} talks a serial protocol to code
+that runs in the target system. @value{GDBN} provides several sample
+@dfn{stubs} that can be integrated into target programs or operating
+systems for this purpose; they are named @file{*-stub.c}.
+
+The @value{GDBN} 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
+@code{trap_low}:
+
+@enumerate
+@item
+%l1 and %l2 contain pc and npc respectively at the time of the trap;
+
+@item
+traps are disabled;
+
+@item
+you are in the correct trap window.
+@end enumerate
+
+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 @code{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 @code{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 @value{GDBN}.
+
+@section ROM Monitor Interface
+
+@section Custom Protocols
+
+@section Transport Layer
+
+@section Builtin Simulator
+
+
+@node Native Debugging
+
+@chapter Native Debugging
+@cindex native debugging
+
+Several files control @value{GDBN}'s configuration for native support:
+
+@table @file
+@vindex NATDEPFILES
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed by a @emph{native} configuration on
+machine @var{xyz}. In particular, this lists the required
+native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
+Also specifies the header file which describes native support on
+@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
+define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
+@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+
+@emph{Maintainer's note: The @file{.mh} suffix is because this file
+originally contained @file{Makefile} fragments for hosting @value{GDBN}
+on machine @var{xyz}. While the file is no longer used for this
+purpose, the @file{.mh} suffix remains. Perhaps someone will
+eventually rename these fragments so that they have a @file{.mn}
+suffix.}
+
+@item gdb/config/@var{arch}/nm-@var{xyz}.h
+(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
+macro definitions describing the native system environment, such as
+child process control and core file support.
+
+@item gdb/@var{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.
+@end table
+
+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 @file{nm-@var{xyz}.h} file. If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{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 @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
+into @code{NATDEPFILES}.
+
+@table @file
+@item inftarg.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use ptrace and wait to control the child.
+
+@item procfs.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use /proc to control the child.
+
+@item 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.
+
+@item infptrace.c
+This is the low level interface to inferior processes for systems using
+the Unix @code{ptrace} call in a vanilla way.
+@end table
+
+@section Native core file Support
+@cindex native core files
+
+@table @file
+@findex fetch_core_registers
+@item core-aout.c::fetch_core_registers()
+Support for reading registers out of a core file. This routine calls
+@code{register_addr()}, see below. Now that BFD is used to read core
+files, virtually all machines should use @code{core-aout.c}, and should
+just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
+@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
+
+@item core-aout.c::register_addr()
+If your @code{nm-@var{xyz}.h} file defines the macro
+@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
+set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
+register number @code{regno}. @code{blockend} is the offset within the
+``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
+@file{core-aout.c} will define the @code{register_addr()} function and
+use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
+you are using the standard @code{fetch_core_registers()}, you will need
+to define your own version of @code{register_addr()}, put it into your
+@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
+the @code{NATDEPFILES} list. If you have your own
+@code{fetch_core_registers()}, you may not need a separate
+@code{register_addr()}. Many custom @code{fetch_core_registers()}
+implementations simply locate the registers themselves.@refill
+@end table
+
+When making @value{GDBN} 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
+@file{bfd/trad-core.c}. First, use whatever @code{#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
+@file{machine/reg.h}), and an include file that defines whatever header
+exists on a core file (e.g. the u-area or a @code{struct core}). Then
+modify @code{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 @value{GDBN}, you need a matching routine called
+@code{fetch_core_registers}. If you can use the generic one, it's in
+@file{core-aout.c}; if not, it's in your @file{@var{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 @value{GDBN}'s ``registers'' array.
+
+If your system uses @file{/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.
+
+@section ptrace
+
+@section /proc
+
+@section win32
+
+@section shared libraries
+
+@section Native Conditionals
+@cindex native conditionals
+
+When @value{GDBN} 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 @file{nm-@var{system}.h}.
+
+@table @code
+@item ATTACH_DETACH
+@findex ATTACH_DETACH
+If defined, then @value{GDBN} will include support for the @code{attach} and
+@code{detach} commands.
+
+@item CHILD_PREPARE_TO_STORE
+@findex 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 @file{xm-@var{system}.h} files
+currently.]
+
+@item FETCH_INFERIOR_REGISTERS
+@findex FETCH_INFERIOR_REGISTERS
+Define this if the native-dependent code will provide its own routines
+@code{fetch_inferior_registers} and @code{store_inferior_registers} in
+@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
+@file{infptrace.c} is included in this configuration, the default
+routines in @file{infptrace.c} are used for these functions.
+
+@item FILES_INFO_HOOK
+@findex FILES_INFO_HOOK
+(Only defined for Convex.)
+
+@item FP0_REGNUM
+@findex 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, @file{/proc} support uses this
+to decide whether floats are in use on this target.
+
+@item GET_LONGJMP_TARGET
+@findex 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
+@file{setjmp.h} is needed to define it.
+
+This macro determines the target PC address that @code{longjmp} will jump to,
+assuming that we have just stopped at a longjmp breakpoint. It takes a
+@code{CORE_ADDR *} as argument, and stores the target PC value through this
+pointer. It examines the current state of the machine as needed.
+
+@item I386_USE_GENERIC_WATCHPOINTS
+An x86-based machine can define this to use the generic x86 watchpoint
+support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
+
+@item KERNEL_U_ADDR
+@findex KERNEL_U_ADDR
+Define this to the address of the @code{u} structure (the ``user
+struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
+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.
+
+@item KERNEL_U_ADDR_BSD
+@findex KERNEL_U_ADDR_BSD
+Define this to cause @value{GDBN} to determine the address of @code{u} at
+runtime, by using Berkeley-style @code{nlist} on the kernel's image in
+the root directory.
+
+@item KERNEL_U_ADDR_HPUX
+@findex KERNEL_U_ADDR_HPUX
+Define this to cause @value{GDBN} to determine the address of @code{u} at
+runtime, by using HP-style @code{nlist} on the kernel's image in the
+root directory.
+
+@item ONE_PROCESS_WRITETEXT
+@findex 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.
+
+@item PREPARE_TO_PROCEED (@var{select_it})
+@findex PREPARE_TO_PROCEED
+This (ugly) macro allows a native configuration to customize the way the
+@code{proceed} function in @file{infrun.c} deals with switching between
+threads.
+
+In a multi-threaded task we may select another thread and then continue
+or step. But if the old thread was stopped at a breakpoint, it will
+immediately cause another breakpoint stop without any execution (i.e. it
+will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
+first.
+
+If defined, @code{PREPARE_TO_PROCEED} should check the current thread
+against the thread that reported the most recent event. If a step-over
+is required, it returns TRUE. If @var{select_it} is non-zero, it should
+reselect the old thread.
+
+@item PROC_NAME_FMT
+@findex PROC_NAME_FMT
+Defines the format for the name of a @file{/proc} device. Should be
+defined in @file{nm.h} @emph{only} in order to override the default
+definition in @file{procfs.c}.
+
+@item PTRACE_FP_BUG
+@findex PTRACE_FP_BUG
+See @file{mach386-xdep.c}.
+
+@item PTRACE_ARG3_TYPE
+@findex PTRACE_ARG3_TYPE
+The type of the third argument to the @code{ptrace} system call, if it
+exists and is different from @code{int}.
+
+@item REGISTER_U_ADDR
+@findex REGISTER_U_ADDR
+Defines the offset of the registers in the ``u area''.
+
+@item SHELL_COMMAND_CONCAT
+@findex SHELL_COMMAND_CONCAT
+If defined, is a string to prefix on the shell command used to start the
+inferior.
+
+@item SHELL_FILE
+@findex SHELL_FILE
+If defined, this is the name of the shell to use to run the inferior.
+Defaults to @code{"/bin/sh"}.
+
+@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
+@findex SOLIB_ADD
+Define this to expand into an expression that will cause the symbols in
+@var{filename} to be added to @value{GDBN}'s symbol table. If
+@var{readsyms} is zero symbols are not read but any necessary low level
+processing for @var{filename} is still done.
+
+@item SOLIB_CREATE_INFERIOR_HOOK
+@findex 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.
+
+@item START_INFERIOR_TRAPS_EXPECTED
+@findex START_INFERIOR_TRAPS_EXPECTED
+When starting an inferior, @value{GDBN} 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.
+
+@item SVR4_SHARED_LIBS
+@findex SVR4_SHARED_LIBS
+Define this to indicate that SVR4-style shared libraries are in use.
+
+@item USE_PROC_FS
+@findex USE_PROC_FS
+This determines whether small routines in @file{*-tdep.c}, which
+translate register values between @value{GDBN}'s internal
+representation and the @file{/proc} representation, are compiled.
+
+@item U_REGS_OFFSET
+@findex 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
+@file{infptrace.c} are being used (that is, @file{infptrace.c} is
+configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
+the default value from @file{infptrace.c} is good enough, leave it
+undefined.
+
+The default value means that u.u_ar0 @emph{points to} the location of
+the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
+that @code{u.u_ar0} @emph{is} the location of the registers.
+
+@item CLEAR_SOLIB
+@findex CLEAR_SOLIB
+See @file{objfiles.c}.
+
+@item DEBUG_PTRACE
+@findex DEBUG_PTRACE
+Define this to debug @code{ptrace} calls.
+@end table
+
+
+@node Support Libraries
+
+@chapter Support Libraries
+
+@section BFD
+@cindex BFD library
+
+BFD provides support for @value{GDBN} in several ways:
+
+@table @emph
+@item 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.
+
+@item 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). @value{GDBN} simply
+calls BFD to read or write section @var{x} at byte offset @var{y} for
+length @var{z}.
+
+@item 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.
+
+@item locating the symbol information
+@value{GDBN} uses an internal interface of BFD to determine where to find the
+symbol information in an executable file or symbol-file. @value{GDBN} itself
+handles the reading of symbols, since BFD does not ``understand'' debug
+symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
+string table, etc.
+@end table
+
+@section opcodes
+@cindex opcodes library
+
+The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
+library because it's also used in binutils, for @file{objdump}).
+
+@section readline
+
+@section mmalloc
+
+@section libiberty
+
+@section gnu-regex
+@cindex regular expressions library
+
+Regex conditionals.
+
+@table @code
+@item C_ALLOCA
+
+@item NFAILURES
+
+@item RE_NREGS
+
+@item SIGN_EXTEND_CHAR
+
+@item SWITCH_ENUM_BUG
+
+@item SYNTAX_TABLE
+
+@item Sword
+
+@item sparc
+@end table
+
+@section include
+
+@node Coding
+
+@chapter Coding
+
+This chapter covers topics that are lower-level than the major
+algorithms of @value{GDBN}.
+
+@section Cleanups
+@cindex cleanups
+
+Cleanups are a structured way to deal with things that need to be done
+later.
+
+When your code does something (e.g., @code{xmalloc} some memory, or
+@code{open} a file) that needs to be undone later (e.g., @code{xfree}
+the memory or @code{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:
+
+@table @code
+@item struct cleanup *@var{old_chain};
+Declare a variable which will hold a cleanup chain handle.
+
+@findex make_cleanup
+@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
+Make a cleanup which will cause @var{function} to be called with
+@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
+handle that can later be passed to @code{do_cleanups} or
+@code{discard_cleanups}. Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
+from @code{make_cleanup}.
+
+@findex do_cleanups
+@item do_cleanups (@var{old_chain});
+Do all cleanups added to the chain since the corresponding
+@code{make_cleanup} call was made.
+
+@findex discard_cleanups
+@item discard_cleanups (@var{old_chain});
+Same as @code{do_cleanups} except that it just removes the cleanups from
+the chain and does not call the specified functions.
+@end table
+
+Cleanups are implemented as a chain. The handle returned by
+@code{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.:
+
+@smallexample
+make_cleanup (a, 0);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 0)
+ ...
+ do_cleanups (old);
+@}
+@end smallexample
+
+@noindent
+will call @code{c()} and @code{b()} but will not call @code{a()}. The
+cleanup that calls @code{a()} will remain in the cleanup chain, and will
+be done later unless otherwise discarded.@refill
+
+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
+@code{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 @code{error} is
+called and a forced stack unwind occurs) by ensuring that the
+@code{xfree} will always be called:
+
+@smallexample
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@end smallexample
+
+The second style is try/except. Before it exits, your code-block calls
+@code{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:
+
+@smallexample
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@end smallexample
+
+Some functions, e.g. @code{fputs_filtered()} or @code{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
+@samp{longjmp} instead).
+
+@section Per-architecture module data
+@cindex per-architecture module data
+@cindex multi-arch data
+@cindex data-pointer, per-architecture/per-module
+
+The multi-arch framework includes a mechanism for adding module specific
+per-architecture data-pointers to the @code{struct gdbarch} architecture
+object.
+
+A module registers one or more per-architecture data-pointers using the
+function @code{register_gdbarch_data}:
+
+@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+
+The @var{init} function is used to obtain an initial value for a
+per-architecture data-pointer. The function is called, after the
+architecture has been created, when the data-pointer is still
+uninitialized (@code{NULL}) and its value has been requested via a call
+to @code{gdbarch_data}. A data-pointer can also be initialize
+explicitly using @code{set_gdbarch_data}.
+
+The @var{free} function is called when a data-pointer needs to be
+destroyed. This occurs when either the corresponding @code{struct
+gdbarch} object is being destroyed or when @code{set_gdbarch_data} is
+overriding a non-@code{NULL} data-pointer value.
+
+The function @code{register_gdbarch_data} returns a @code{struct
+gdbarch_data} that is used to identify the data-pointer that was added
+to the module.
+
+@end deftypefun
+
+A typical module has @code{init} and @code{free} functions of the form:
+
+@smallexample
+static struct gdbarch_data *nozel_handle;
+static void *
+nozel_init (struct gdbarch *gdbarch)
+@{
+ struct nozel *data = XMALLOC (struct nozel);
+ @dots{}
+ return data;
+@}
+@dots{}
+static void
+nozel_free (struct gdbarch *gdbarch, void *data)
+@{
+ xfree (data);
+@}
+@end smallexample
+
+Since uninitialized (@code{NULL}) data-pointers are initialized
+on-demand, an @code{init} function is free to call other modules that
+use data-pointers. Those modules data-pointers will be initialized as
+needed. Care should be taken to ensure that the @code{init} call graph
+does not contain cycles.
+
+The data-pointer is registered with the call:
+
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
+@dots{}
+@end smallexample
+
+The per-architecture data-pointer is accessed using the function:
+
+@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
+Given the architecture @var{arch} and module data handle
+@var{data_handle} (returned by @code{register_gdbarch_data}, this
+function returns the current value of the per-architecture data-pointer.
+@end deftypefun
+
+The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should
+be saved in a local variable and then used directly:
+
+@smallexample
+int
+nozel_total (struct gdbarch *gdbarch)
+@{
+ int total;
+ struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+ @dots{}
+ return total;
+@}
+@end smallexample
+
+It is also possible to directly initialize the data-pointer using:
+
+@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
+Update the data-pointer corresponding to @var{handle} with the value of
+@var{pointer}. If the previous data-pointer value is non-NULL, then it
+is freed using data-pointers @var{free} function.
+@end deftypefun
+
+This function is used by modules that require a mechanism for explicitly
+setting the per-architecture data-pointer during architecture creation:
+
+@smallexample
+/* Called during architecture creation. */
+extern void
+set_gdbarch_nozel (struct gdbarch *gdbarch,
+ int total)
+@{
+ struct nozel *data = XMALLOC (struct nozel);
+ @dots{}
+ set_gdbarch_data (gdbarch, nozel_handle, nozel);
+@}
+@end smallexample
+
+@smallexample
+/* Default, called when nozel not set by set_gdbarch_nozel(). */
+static void *
+nozel_init (struct gdbarch *gdbarch)
+@{
+ struct nozel *default_nozel = XMALLOC (struc nozel);
+ @dots{}
+ return default_nozel;
+@}
+@end smallexample
+
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, NULL);
+ @dots{}
+@end smallexample
+
+@noindent
+Note that an @code{init} function still needs to be registered. It is
+used to initialize the data-pointer when the architecture creation phase
+fail to set an initial value.
+
+
+@section Wrapping Output Lines
+@cindex line wrap in output
+
+@findex wrap_here
+Output that goes through @code{printf_filtered} or @code{fputs_filtered}
+or @code{fputs_demangled} needs only to have calls to @code{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 @code{wrap_here} is an indentation string which is
+printed @emph{only} if the line breaks there. This argument is saved
+away and used later. It must remain valid until the next call to
+@code{wrap_here} or until a newline has been printed through the
+@code{*_filtered} functions. Don't pass in a local variable and then
+return!
+
+It is usually best to call @code{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 (@code{printf}) output. Symbol reading routines that
+print warnings are a good example.
+
+@section @value{GDBN} Coding Standards
+@cindex coding standards
+
+@value{GDBN} follows the GNU coding standards, as described in
+@file{etc/standards.texi}. This file is also available for anonymous
+FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
+of the standard; in general, when the GNU standard recommends a practice
+but does not require it, @value{GDBN} requires it.
+
+@value{GDBN} follows an additional set of coding standards specific to
+@value{GDBN}, as described in the following sections.
+
+
+@subsection ISO C
+
+@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
+compiler.
+
+@value{GDBN} does not assume an ISO C or POSIX compliant C library.
+
+
+@subsection Memory Management
+
+@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
+@code{calloc}, @code{free} and @code{asprintf}.
+
+@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
+@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
+these functions do not return when the memory pool is empty. Instead,
+they unwind the stack using cleanups. These functions return
+@code{NULL} when requested to allocate a chunk of memory of size zero.
+
+@emph{Pragmatics: By using these functions, the need to check every
+memory allocation is removed. These functions provide portable
+behavior.}
+
+@value{GDBN} does not use the function @code{free}.
+
+@value{GDBN} uses the function @code{xfree} to return memory to the
+memory pool. Consistent with ISO-C, this function ignores a request to
+free a @code{NULL} pointer.
+
+@emph{Pragmatics: On some systems @code{free} fails when passed a
+@code{NULL} pointer.}
+
+@value{GDBN} can use the non-portable function @code{alloca} for the
+allocation of small temporary values (such as strings).
+
+@emph{Pragmatics: This function is very non-portable. Some systems
+restrict the memory being allocated to no more than a few kilobytes.}
+
+@value{GDBN} uses the string function @code{xstrdup} and the print
+function @code{xasprintf}.
+
+@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
+functions such as @code{sprintf} are very prone to buffer overflow
+errors.}
+
+
+@subsection Compiler Warnings
+@cindex compiler warnings
+
+With few exceptions, developers should include the configuration option
+@samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}.
+The exceptions are listed in the file @file{gdb/MAINTAINERS}.
+
+This option causes @value{GDBN} (when built using GCC) to be compiled
+with a carefully selected list of compiler warning flags. Any warnings
+from those flags being treated as errors.
+
+The current list of warning flags includes:
+
+@table @samp
+@item -Wimplicit
+Since @value{GDBN} coding standard requires all functions to be declared
+using a prototype, the flag has the side effect of ensuring that
+prototyped functions are always visible with out resorting to
+@samp{-Wstrict-prototypes}.
+
+@item -Wreturn-type
+Such code often appears to work except on instruction set architectures
+that use register windows.
+
+@item -Wcomment
+
+@item -Wtrigraphs
+
+@item -Wformat
+Since @value{GDBN} uses the @code{format printf} attribute on all
+@code{printf} like functions this checks not just @code{printf} calls
+but also calls to functions such as @code{fprintf_unfiltered}.
+
+@item -Wparentheses
+This warning includes uses of the assignment operator within an
+@code{if} statement.
+
+@item -Wpointer-arith
+
+@item -Wuninitialized
+@end table
+
+@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
+functions have unused parameters. Consequently the warning
+@samp{-Wunused-parameter} is precluded from the list. The macro
+@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
+it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
+is being used. The options @samp{-Wall} and @samp{-Wunused} are also
+precluded because they both include @samp{-Wunused-parameter}.}
+
+@emph{Pragmatics: @value{GDBN} has not simply accepted the warnings
+enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings
+when and where their benefits can be demonstrated.}
+
+@subsection Formatting
+
+@cindex source code 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.
+
+@smallexample
+/* Declaration */
+static void foo (void);
+/* Definition */
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+@emph{Pragmatics: This simplifies scripting. Function definitions can
+be found using @samp{^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 @code{diff} and @code{patch} utilities.
+
+Pointers are declared using the traditional K&R C style:
+
+@smallexample
+void *foo;
+@end smallexample
+
+@noindent
+and not:
+
+@smallexample
+void * foo;
+void* foo;
+@end smallexample
+
+@subsection Comments
+
+@cindex comment formatting
+The standard GNU requirements on comments must be followed strictly.
+
+Block comments must appear in the following form, with no @code{/*}- or
+@code{*/}-only lines, and no leading @code{*}:
+
+@smallexample
+/* 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 @value{GDBN} should read more commands. */
+@end smallexample
+
+(Note that this format is encouraged by Emacs; tabbing for a multi-line
+comment works correctly, and @kbd{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.
+
+@subsection C Usage
+
+@cindex C data types
+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.
+
+@cindex function usage
+Use functions freely. There are only a handful of compute-bound areas
+in @value{GDBN} that might be affected by the overhead of a function
+call, mainly in symbol reading. Most of @value{GDBN}'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.
+
+@emph{Macros are bad, M'kay.}
+(But if you have to use a macro, make sure that the macro arguments are
+protected with parentheses.)
+
+@cindex types
+
+Declarations like @samp{struct foo *} should be used in preference to
+declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
+
+
+@subsection Function Prototypes
+@cindex function prototypes
+
+Prototypes must be used when both @emph{declaring} and @emph{defining}
+a function. Prototypes for @value{GDBN} 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 @code{_initialize_*} functions, which must
+be external so that @file{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.
+
+
+@subsection Internal Error Recovery
+
+During its execution, @value{GDBN} 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 @value{GDBN} has detected, at
+run time, a corrupt or erroneous situation.
+
+When reporting an internal error, @value{GDBN} uses
+@code{internal_error} and @code{gdb_assert}.
+
+@value{GDBN} must not call @code{abort} or @code{assert}.
+
+@emph{Pragmatics: There is no @code{internal_warning} function. Either
+the code detected a user error, recovered from it and issued a
+@code{warning} or the code failed to correctly recover from the user
+error and issued an @code{internal_error}.}
+
+@subsection File Names
+
+Any file used when building the core of @value{GDBN} must be in lower
+case. Any file used when building the core of @value{GDBN} must be 8.3
+unique. These requirements apply to both source and generated files.
+
+@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
+platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
+is introduced to the build process both @file{Makefile.in} and
+@file{configure.in} need to be modified accordingly. Compare the
+convoluted conversion process needed to transform @file{COPYING} into
+@file{copying.c} with the conversion needed to transform
+@file{version.in} into @file{version.c}.}
+
+Any file non 8.3 compliant file (that is not used when building the core
+of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
+
+@emph{Pragmatics: This is clearly a compromise.}
+
+When @value{GDBN} has a local version of a system header file (ex
+@file{string.h}) the file name based on the POSIX header prefixed with
+@file{gdb_} (@file{gdb_string.h}).
+
+For other files @samp{-} is used as the separator.
+
+
+@subsection Include Files
+
+A @file{.c} file should include @file{defs.h} first.
+
+A @file{.c} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion.
+
+A @file{.h} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion. Exception: The file @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 @code{.c} file.
+Exception: a declaration for the @code{_initialize} function that
+pacifies @option{-Wmissing-declaration}.
+
+A @code{typedef} definition should only appear in one include file.
+
+An opaque @code{struct} declaration can appear in multiple @file{.h}
+files. Where possible, a @file{.h} file should use an opaque
+@code{struct} declaration instead of an include.
+
+All @file{.h} files should be wrapped in:
+
+@smallexample
+#ifndef INCLUDE_FILE_NAME_H
+#define INCLUDE_FILE_NAME_H
+header body
+#endif
+@end smallexample
+
+
+@subsection Clean Design and Portable Implementation
+
+@cindex design
+In addition to getting the syntax right, there's the little question of
+semantics. Some things are done in certain ways in @value{GDBN} because long
+experience has shown that the more obvious ways caused various kinds of
+trouble.
+
+@cindex assumptions about targets
+You can't assume the byte order of anything that comes from a target
+(including @var{value}s, object files, and instructions). Such things
+must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
+@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
+such as @code{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 @code{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.
+
+@cindex portability
+Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
+to write the code portably than to conditionalize it for various
+systems.