This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Internals manual fixups


As threatened, here is my first round of bashing on the internals manual. Eli, how does it look to you?

Stan

2008-06-28 Stan Shebs <stan@codesourcery.com>

   * gdbint.texinfo: General round of cleanup and minor
   clarifications.
   (Breakpoint Handling): Remove mention of BREAKPOINT macro.
   (Longjmp Support): Update description to reflect how it is done
   for targets without using native header.
   (Symbol Handling): Add a little more general explanation.
   (COFF, ELF): Mention stabs encapsulation.
   (DWARF 3): New section.
   (Adding a New Host): Scrub out some obsolete bits.
   (Generic Host Support Files): Mention ser-pipe.c, ser-mingw.c.
   (Host Conditionals): Remove descriptions of NO_STD_REGS,
   HAVE_MMAP, HAVE_TERMIO, INT_MAX etc, LONGEST, HAVE_LONG_DOUBLE,
   PRINTF_HAS_LONG_DOUBLE, SCANF_HAS_LONG_DOUBLE, L_SET, SEEK_CUR,
   SEEK_SET, STOP_SIGNAL, USG.
   (Raw and Virtual Register Representations): Ditto for
   DEPRECATED_REGISTER_RAW_SIZE, DEPRECATED_REGISTER_VIRTUAL_SIZE,
   DEPRECATED_REGISTER_VIRTUAL_TYPE, REGISTER_CONVERT_TO_TYPE.
   (Target Conditionals): Ditto for DEPRECATED_FP_REGNUM,
   DEPRECATED_FRAMELESS_FUNCTION_INVOCATION, DEPRECATED_FRAME_CHAIN,
   DEPRECATED_FRAME_CHAIN_VALID, DEPRECATED_FRAME_INIT_SAVED_REGS,
   DEPRECATED_FRAME_SAVED_PC, DEPRECATED_FUNCTION_START_OFFSET,
   DEPRECATED_REGISTER_VIRTUAL_SIZE,
   DEPRECATED_REGISTER_VIRTUAL_TYPE,
   DEPRECATED_USE_STRUCT_CONVENTION.
   Describe gdbarch_deprecated_fp_regnum.
   Update description of gdbarch_print_insn.
   (Adding a New Target): Scrub out obsolete bits.
   (Obsolete Conditionals): Remove entire section.


Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.284
diff -u -p -r1.284 gdbint.texinfo
--- gdbint.texinfo	16 May 2008 00:27:24 -0000	1.284
+++ gdbint.texinfo	28 Jun 2008 18:20:35 -0000
@@ -190,9 +190,10 @@ way.
 executes.  In most cases they are the same machine, in which case a
 third type of @dfn{Native} attributes come into play.
 
-Defines and include files needed to build on the host are host support.
-Examples are tty support, system defined types, host byte order, host
-float format.
+Defines and include files needed to build on the host are host
+support.  Examples are tty support, system defined types, host byte
+order, host float format. These are all calculated by @code{autoconf}
+when the debugger is built.
 
 Defines and information needed to handle the target format are target
 dependent.  Examples are the stack frame format, instruction set,
@@ -201,7 +202,7 @@ to call a function.
 
 Information that is only needed when the host and target are the same,
 is native dependent.  One example is Unix child process support; if the
-host and target are not the same, doing a fork to start the target
+host and target are not the same, doing a fork() to start the target
 process is a bad idea.  The various macros needed for finding the
 registers in the @code{upage}, running @code{ptrace}, and such are all
 in the native-dependent files.
@@ -211,8 +212,8 @@ are really part of the target environmen
 @code{#include} files that are only available on the host system.  Core
 file handling and @code{setjmp} handling are two common cases.
 
-When you want to make @value{GDBN} work ``native'' on a particular machine, you
-have to include all three kinds of information.
+When you want to make @value{GDBN} work as the traditional native debugger
+on a system, you will need to supply both target and native information.
 
 @section Source Tree Structure
 @cindex @value{GDBN} source tree structure
@@ -507,10 +508,6 @@ set not to have any instructions usable 
 although in practice only the ARC has failed to define such an
 instruction.
 
-@findex BREAKPOINT
-The basic definition of the software breakpoint is the macro
-@code{BREAKPOINT}.
-
 Basic breakpoint object handling is in @file{breakpoint.c}.  However,
 much of the interesting breakpoint action is in @file{infrun.c}.
 
@@ -574,11 +571,13 @@ command.
 
 @findex gdbarch_get_longjmp_target
 To make this work, you need to define a function called
-@code{gdbarch_get_longjmp_target}, which will examine the @code{jmp_buf}
-structure and extract the longjmp target address.  Since @code{jmp_buf}
-is target specific, you will need to define it in the appropriate
-@file{tm-@var{target}.h} file.  Look in @file{tm-sun4os4.h} and
-@file{sparc-tdep.c} for examples of how to do this.
+@code{gdbarch_get_longjmp_target}, which will examine the
+@code{jmp_buf} structure and extract the longjmp target address.
+Since @code{jmp_buf} is target specific and typically defined in a
+target header not available to @value{GDBN}, you will need to
+determine the offset of the PC manually and return that; many targets
+define a @code{jb_pc_offset} field in the tdep structure to save the
+value once calculated. See @file{i386-tdep.c} for an example.
 
 @section Watchpoints
 @cindex watchpoints
@@ -649,6 +648,8 @@ the expression whose value is being watc
 watched value has changed.  Watchpoints whose watched values have
 changed are announced as hit.
 
+@c FIXME move these to the main lists of target/native defns
+
 @value{GDBN} uses several macros and primitives to support hardware
 watchpoints:
 
@@ -656,6 +657,7 @@ watchpoints:
 @findex TARGET_HAS_HARDWARE_WATCHPOINTS
 @item TARGET_HAS_HARDWARE_WATCHPOINTS
 If defined, the target supports hardware watchpoints.
+(Currently only used for several native configs.)
 
 @findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
 @item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
@@ -747,7 +749,8 @@ read or write.
 @findex CANNOT_STEP_HW_WATCHPOINTS
 @item CANNOT_STEP_HW_WATCHPOINTS
 If this is defined to a non-zero value, @value{GDBN} will remove all
-watchpoints before stepping the inferior.
+watchpoints before stepping the inferior. Currently this is only
+defined for Solaris x86.
 
 @findex STOPPED_BY_WATCHPOINT
 @item STOPPED_BY_WATCHPOINT (@var{wait_status})
@@ -801,6 +804,9 @@ generic library of functions that x86-ba
 support for watchpoints and hardware-assisted breakpoints.  This
 subsection documents the x86 watchpoint facilities in @value{GDBN}.
 
+(At present, the library functions read and write debug registers directly, and are
+thus only available for native configurations.)
+
 To use the generic x86 watchpoint support, a port should do the
 following:
 
@@ -1041,8 +1047,8 @@ implementation is also briefly discussed
 
 @chapter User Interface
 
-@value{GDBN} has several user interfaces.  Although the command-line interface
-is the most common and most familiar, there are others.
+@value{GDBN} has several user interfaces, of which the traditional
+command-line interface is perhaps the most familiar.
 
 @section Command Interpreter
 
@@ -1955,8 +1961,21 @@ generally the same as @code{frame_unwind
 
 @chapter Symbol Handling
 
-Symbols are a key part of @value{GDBN}'s operation.  Symbols include variables,
-functions, and types.
+Symbols are a key part of @value{GDBN}'s operation.  Symbols include
+variables, functions, and types.
+
+Symbol information for a large program can be truly massive, and
+reading of symbol information is one of the major performance
+bottlenecks in @value{GDBN}; it can take many minutes to process it
+all. Studies have shown that nearly all the time spent is
+computational, rather than file reading.
+
+One of the ways for @value{GDBN} to provide a good user experience is
+to start up quickly, taking no more than a few seconds. It is simply
+not possible to process all of a program's debugging info in that
+time, and so we attempt to handle symbols incrementally. For instance,
+we create @dfn{partial symbol tables} consisting of only selected
+symbols, and only expand them to full symbol tables when necessary.
 
 @section Symbol Reading
 
@@ -1967,8 +1986,9 @@ functions, and types.
 file is the file containing the program which @value{GDBN} is
 debugging.  @value{GDBN} can be directed to use a different file for
 symbols (with the @samp{symbol-file} command), and it can also read
-more symbols via the @samp{add-file} and @samp{load} commands, or while
-reading symbols from shared libraries.
+more symbols via the @samp{add-file} and @samp{load} commands. In
+addition, it may bring in more symbols while loading shared
+libraries.
 
 @findex find_sym_fns
 Symbol files are initially opened by code in @file{symfile.c} using
@@ -2207,9 +2227,10 @@ COFF files may have multiple sections, e
 number of sections is limited.
 
 The COFF specification includes support for debugging.  Although this
-was a step forward, the debugging information was woefully limited.  For
-instance, it was not possible to represent code that came from an
-included file.
+was a step forward, the debugging information was woefully limited.
+For instance, it was not possible to represent code that came from an
+included file. GNU's COFF-using configs often use stabs-type info,
+encapsulated in special sections.
 
 The COFF reader is in @file{coffread.c}.
 
@@ -2249,9 +2270,10 @@ COFF reader.
 @subsection ELF
 
 @cindex ELF format
-The ELF format came with System V Release 4 (SVR4) Unix.  ELF is similar
-to COFF in being organized into a number of sections, but it removes
-many of COFF's limitations.
+The ELF format came with System V Release 4 (SVR4) Unix.  ELF is
+similar to COFF in being organized into a number of sections, but it
+removes many of COFF's limitations. Debugging info may be either stabs
+encapsulated in ELF sections, or more commonly these days, DWARF.
 
 The basic ELF reader is in @file{elfread.c}.
 
@@ -2292,6 +2314,8 @@ ECOFF includes a definition of a special
 
 The file @file{mdebugread.c} implements reading for this format.
 
+@c mention DWARF 1 as a formerly-supported format
+
 @subsection DWARF 2
 
 @cindex DWARF 2 debugging info
@@ -2322,6 +2346,11 @@ The same reader is used for both compres
 Section decompression is done in @code{zlib_decompress_section} in
 @file{dwarf2read.c}.
 
+@subsection DWARF 3
+
+@cindex DWARF 3 debugging info
+DWARF 3 is an improved version of DWARF 2.
+
 @subsection SOM
 
 @cindex SOM debugging info
@@ -2337,10 +2366,10 @@ If you need to add a new object file for
 BFD.  This is beyond the scope of this document.
 
 You must then arrange for the BFD code to provide access to the
-debugging symbols.  Generally @value{GDBN} will have to call swapping routines
-from BFD and a few other BFD internal routines to locate the debugging
-information.  As much as possible, @value{GDBN} should not depend on the BFD
-internal data structures.
+debugging symbols.  Generally @value{GDBN} will have to call swapping
+routines from BFD and a few other BFD internal routines to locate the
+debugging information.  As much as possible, @value{GDBN} should not
+depend on the BFD internal data structures.
 
 For some targets (e.g., COFF), there is a special transfer vector used
 to call swapping routines, since the external data structures on various
@@ -2531,52 +2560,43 @@ eventually disappear.
 
 @table @file
 @item gdb/config/@var{arch}/@var{xyz}.mh
-This file once contained both host and native configuration information
-(@pxref{Native Debugging}) for the machine @var{xyz}.  The host
-configuration information is now handed by Autoconf.
+This file is a Makefile fragment that once contained both host and
+native configuration information (@pxref{Native Debugging}) for the
+machine @var{xyz}.  The host configuration information is now handled
+by Autoconf.
 
-Host configuration information included a definition of
-@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC},
+Host configuration information included definitions for @code{CC},
 @code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
 @code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
 
-New host only configurations do not need this file.
-
-@item gdb/config/@var{arch}/xm-@var{xyz}.h
-This file once contained definitions and includes required when hosting
-gdb on machine @var{xyz}.  Those definitions and includes are now
-handled by Autoconf.
-
-New host and native configurations do not need this file.
-
-@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h}
-file to define the macros @var{HOST_FLOAT_FORMAT},
-@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}.  That code
-also needs to be replaced with either an Autoconf or run-time test.}
+New host-only configurations do not need this file.
 
 @end table
 
+(Files named @file{gdb/config/@var{arch}/xm-@var{xyz}.h} were once
+used to define host-specific macros, but were no longer needed and
+have all been removed.)
+
 @subheading Generic Host Support Files
 
 @cindex generic host support
 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{xm-@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{XDEPFILES}.
-
-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 @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
-into @code{XDEPFILES}.
+various systems.
 
 @table @file
 @cindex remote debugging support
 @cindex serial line support
 @item ser-unix.c
-This contains serial line support for Unix systems.  This is always
-included, via the makefile variable @code{SER_HARDWIRE}; override this
-variable in the @file{.mh} file to avoid it.
+This contains serial line support for Unix systems. It is included by
+default on all Unix-like hosts.
+
+@item ser-pipe.c
+This contains serial pipe support for Unix systems. It is included by
+default on all Unix-like hosts.
+
+@item ser-mingw.c
+This contains serial line support for 32-bit programs running under
+Windows using MinGW.
 
 @item ser-go32.c
 This contains serial line support for 32-bit programs running under DOS,
@@ -2584,25 +2604,27 @@ using the DJGPP (a.k.a.@: GO32) executio
 
 @cindex TCP remote support
 @item ser-tcp.c
-This contains generic TCP support using sockets.
+This contains generic TCP support using sockets. It is included by
+default on all Unix-like hosts and with MinGW.
 @end table
 
 @section Host Conditionals
 
 When @value{GDBN} is configured and compiled, various macros are
 defined or left undefined, to control compilation based on the
-attributes of the host system.  These macros and their meanings (or if
-the meaning is not documented here, then one of the source files where
-they are used is indicated) are:
+attributes of the host system. While formerly they could be set in
+host-specific header files, at present they can be changed only by
+setting @code{CFLAGS} when building, or by editing the source code.
+
+These macros and their meanings (or if the meaning is not documented
+here, then one of the source files where they are used is indicated)
+are:
 
 @ftable @code
 @item @value{GDBN}INIT_FILENAME
 The default name of @value{GDBN}'s initialization file (normally
 @file{.gdbinit}).
 
-@item NO_STD_REGS
-This macro is deprecated.
-
 @item SIGWINCH_HANDLER
 If your host defines @code{SIGWINCH}, you can define this to be the name
 of a function to be called if @code{SIGWINCH} is received.
@@ -2627,31 +2649,11 @@ The default value of the prompt string (
 @cindex terminal device
 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
 
-@item FOPEN_RB
-Define this if binary files are opened the same way as text files.
-
-@item HAVE_MMAP
-@findex mmap
-In some cases, use the system call @code{mmap} for reading symbol
-tables.  For some machines this allows for sharing and quick updates.
-
-@item HAVE_TERMIO
-Define this if the host system has @code{termio.h}.
-
-@item INT_MAX
-@itemx INT_MIN
-@itemx LONG_MAX
-@itemx UINT_MAX
-@itemx ULONG_MAX
-Values for host-side constants.
-
 @item ISATTY
 Substitute for isatty, if not available.
 
-@item LONGEST
-This is the longest integer type available on the host.  If not defined,
-it will default to @code{long long} or @code{long}, depending on
-@code{CC_HAS_LONG_LONG}.
+@item FOPEN_RB
+Define this if binary files are opened the same way as text files.
 
 @item CC_HAS_LONG_LONG
 @cindex @code{long long} data type
@@ -2663,30 +2665,11 @@ Define this if the host can handle print
 the printf format conversion specifier @code{ll}.  This is set by the
 @code{configure} script.
 
-@item HAVE_LONG_DOUBLE
-Define this if the host C compiler supports @code{long double}.  This is
-set by the @code{configure} script.
-
-@item PRINTF_HAS_LONG_DOUBLE
-Define this if the host can handle printing of long double float-point
-numbers via the printf format conversion specifier @code{Lg}.  This is
-set by the @code{configure} script.
-
-@item SCANF_HAS_LONG_DOUBLE
-Define this if the host can handle the parsing of long double
-float-point numbers via the scanf format conversion specifier
-@code{Lg}.  This is set by the @code{configure} script.
-
 @item LSEEK_NOT_LINEAR
 Define this if @code{lseek (n)} does not necessarily move to byte number
 @code{n} in the file.  This is only used when reading source files.  It
 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
 
-@item L_SET
-This macro is used as the argument to @code{lseek} (or, most commonly,
-@code{bfd_seek}).  FIXME, should be replaced by SEEK_SET instead,
-which is the POSIX equivalent.
-
 @item NORETURN
 If defined, this should be one or more tokens, such as @code{volatile},
 that can be used in both the declaration and definition of functions to
@@ -2700,20 +2683,6 @@ of functions to indicate that they never
 set correctly if compiling with GCC.  This will almost never need to be
 defined.
 
-@item SEEK_CUR
-@itemx SEEK_SET
-Define these to appropriate value for the system @code{lseek}, if not already
-defined.
-
-@item STOP_SIGNAL
-This is the signal for stopping @value{GDBN}.  Defaults to
-@code{SIGTSTP}.  (Only redefined for the Convex.)
-
-@item USG
-Means that System V (prior to SVR4) include files are in use.  (FIXME:
-This symbol is abused in @file{infrun.c}, @file{regex.c}, and
-@file{utils.c} for other things, at the moment.)
-
 @item lint
 Define this to help placate @code{lint} in some situations.
 
@@ -2982,6 +2951,8 @@ However, architectures with smaller word
 address space, so they may choose a pointer representation that breaks this
 identity, and allows a larger code address space.
 
+@c D10V is gone from sources - more current example?
+
 For example, the Renesas D10V is a 16-bit VLIW processor whose
 instructions are 32 bits long@footnote{Some D10V instructions are
 actually pairs of 16-bit sub-instructions.  However, since you can't
@@ -3121,7 +3092,7 @@ This function is normally called from wi
 Given the type flags representing an address class qualifier, return
 its name.
 @end deftypefun
-@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{name}, int *var{type_flags_ptr})
+@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{current_gdbarch}, int @var{name}, int *@var{type_flags_ptr})
 Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags
 for that address class qualifier.
 @end deftypefun
@@ -3245,28 +3216,9 @@ You should not use @code{REGISTER_CONVER
 unless this macro returns a non-zero value for that register.
 @end deftypefn
 
-@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg})
-The size of register number @var{reg}'s raw value.  This is the number
-of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
-remote protocol packet.
-@end deftypefn
-
-@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg})
-The size of register number @var{reg}'s value, in its virtual format.
-This is the size a @code{struct value}'s buffer will have, holding that
-register's value.
-@end deftypefn
-
-@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg})
-This is the type of the virtual representation of register number
-@var{reg}.  Note that there is no need for a macro giving a type for the
-register's raw form; once the register's value has been obtained, @value{GDBN}
-always uses the virtual form.
-@end deftypefn
-
 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
 Convert the value of register number @var{reg} to @var{type}, which
-should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}.  The buffer
+should always be @code{gdbarch_register_type (@var{reg})}.  The buffer
 at @var{from} holds the register's value in raw format; the macro should
 convert the value to virtual format, and place it at @var{to}.
 
@@ -3281,7 +3233,7 @@ value.
 
 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
 Convert the value of register number @var{reg} to @var{type}, which
-should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}.  The buffer
+should always be @code{gdbarch_register_type (@var{reg})}.  The buffer
 at @var{from} holds the register's value in raw format; the macro should
 convert the value to virtual format, and place it at @var{to}.
 
@@ -3368,10 +3320,6 @@ You should only use @code{gdbarch_value_
 the @code{gdbarch_convert_register_p} function returns a non-zero value.
 @end deftypefun
 
-@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
-See @file{mips-tdep.c}.  It does not do what you want.
-@end deftypefn
-
 @node Frame Interpretation
 @section Frame Interpretation
 
@@ -3633,20 +3581,6 @@ If not defined, no conversion will be pe
 Convert ECOFF register number  @var{ecoff_regnr} into @value{GDBN} regnum.  If
 not defined, no conversion will be performed.
 
-@item DEPRECATED_FP_REGNUM
-@findex DEPRECATED_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{DEPRECATED_TARGET_READ_FP}
-is not defined.
-
-@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
-@findex DEPRECATED_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 CORE_ADDR frame_align (@var{gdbarch}, @var{address})
 @anchor{frame_align}
 @findex frame_align
@@ -3682,27 +3616,6 @@ The @sc{amd64} (nee x86-64) @sc{abi} doc
 @emph{red zone} when describing this scratch area.
 @cindex red zone
 
-@item DEPRECATED_FRAME_CHAIN(@var{frame})
-@findex DEPRECATED_FRAME_CHAIN
-Given @var{frame}, return a pointer to the calling frame.
-
-@item DEPRECATED_FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
-@findex DEPRECATED_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.  Most normal
-situations can be handled without defining this macro, including @code{NULL}
-chain pointers, dummy frames, and frames whose PC values are inside the
-startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside
-@code{_start}.
-
-@item DEPRECATED_FRAME_INIT_SAVED_REGS(@var{frame})
-@findex DEPRECATED_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{DEPRECATED_FRAME_INIT_SAVED_REGS} using
-@code{frame_saved_regs_zalloc}.
-
 @code{FRAME_FIND_SAVED_REGS} is deprecated.
 
 @item int gdbarch_frame_num_args (@var{gdbarch}, @var{frame})
@@ -3711,13 +3624,6 @@ For the frame described by @var{frame} r
 are being passed.  If the number of arguments is not known, return
 @code{-1}.
 
-@item DEPRECATED_FRAME_SAVED_PC(@var{frame})
-@findex DEPRECATED_FRAME_SAVED_PC
-@anchor{DEPRECATED_FRAME_SAVED_PC} Given @var{frame}, return the pc
-saved there.  This is the return address.
-
-This method is deprecated. @xref{gdbarch_unwind_pc}.
-
 @item CORE_ADDR gdbarch_unwind_pc (@var{next_frame})
 @findex gdbarch_unwind_pc
 @anchor{gdbarch_unwind_pc} Return the instruction address, in
@@ -3734,7 +3640,6 @@ return gdbarch_addr_bits_remove (gdbarch
 @end smallexample
 
 @noindent
-@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces.
 
 @item CORE_ADDR gdbarch_unwind_sp (@var{gdbarch}, @var{next_frame})
 @findex gdbarch_unwind_sp
@@ -3760,21 +3665,6 @@ function end symbol is 0.  For such targ
 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
 function's epilogue.
 
-@item DEPRECATED_FUNCTION_START_OFFSET
-@findex DEPRECATED_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{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
-
 @item GCC_COMPILED_FLAG_SYMBOL
 @itemx GCC2_COMPILED_FLAG_SYMBOL
 @findex GCC2_COMPILED_FLAG_SYMBOL
@@ -3786,20 +3676,20 @@ respectively.  (Currently only defined f
 
 @item gdbarch_get_longjmp_target
 @findex gdbarch_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.
+This function 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, typically by using a manually-determined
+offset into the @code{jmp_buf}. (While we might like to get the offset
+from the target's @file{jmpbuf.h}, that header file cannot be assumed
+to be available when building a cross-debugger.)
 
 @item DEPRECATED_IBM6000_TARGET
 @findex DEPRECATED_IBM6000_TARGET
 Shows that we are configured for an IBM RS/6000 system.  This
 conditional should be eliminated (FIXME) and replaced by
-feature-specific macros.  It was introduced in a haste and we are
+feature-specific macros.  It was introduced in haste and we are
 repenting at leisure.
 
 @item I386_USE_GENERIC_WATCHPOINTS
@@ -3896,23 +3786,11 @@ floating-point.  @samp{float_reggroup}.
 Any register with a valid name.
 @end table
 
-@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
-@findex DEPRECATED_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 DEPRECATED_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 struct type *register_type (@var{gdbarch}, @var{reg})
 @findex register_type
-If defined, return the type of register @var{reg}.  This function
-supersedes @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}.  @xref{Target Architecture
-Definition, , Raw and Virtual Register Representations}.
+If defined, return the type of register @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
@@ -4001,7 +3879,6 @@ register.
 
 @item CORE_ADDR gdbarch_push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{bp_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
 @findex gdbarch_push_dummy_call
-@findex DEPRECATED_PUSH_ARGUMENTS.
 @anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to
 the inferior function onto the stack.  In addition to pushing @var{nargs}, the
 code should push @var{struct_addr} (when @var{struct_return} is non-zero), and
@@ -4012,8 +3889,6 @@ function descriptors, this contains the 
 
 Returns the updated top-of-stack pointer.
 
-This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
-
 @item CORE_ADDR gdbarch_push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}, @var{regcache})
 @findex gdbarch_push_dummy_code
 @anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the
@@ -4028,8 +3903,7 @@ By default, the stack is grown sufficien
 (@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address
 reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.
 
-This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}} and
-@code{DEPRECATED_REGISTER_SIZE}.
+This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}}.
 
 @item const char *gdbarch_register_name (@var{gdbarch}, @var{regnr})
 @findex gdbarch_register_name
@@ -4108,6 +3982,11 @@ If the stack-pointer is kept in a regist
 the number (greater than or equal to zero) of that register, or -1 if
 there is no such register.
 
+@item int gdbarch_deprecated_fp_regnum (@var{gdbarch})
+@findex gdbarch_deprecated_fp_regnum
+If the frame pointer is in a register, use this function to return the
+number of that register.
+
 @item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr})
 @findex gdbarch_stab_reg_to_regnum
 Use this function to convert stab register @var{stab_regnr} into @value{GDBN}
@@ -4194,10 +4073,11 @@ and part in an ordinary register.
 
 @item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset})
 @findex gdbarch_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{DEPRECATED_FP_REGNUM}, with an offset of zero.
+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{gdbarch_deprecated_fp_regnum} (or @code{gdbarch_sp_regnum}, if
+no frame pointer is defined), with an offset of zero.
 
 @item TARGET_HAS_HARDWARE_WATCHPOINTS
 If non-zero, the target has support for hardware-assisted
@@ -4208,14 +4088,11 @@ other related macros.
 @findex gdbarch_print_insn
 This is the function used by @value{GDBN} to print an assembly
 instruction.  It prints the instruction at address @var{vma} 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{deprecated_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.
+debugged memory and returns the length of the instruction, in bytes.
+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 frame_id gdbarch_dummy_id (@var{gdbarch}, @var{frame})
 @findex gdbarch_dummy_id
@@ -4224,18 +4101,6 @@ frame_id}} that uniquely identifies an i
 frame.  The value returned must match the dummy frame stack value
 previously saved by @code{call_function_by_hand}.
 
-@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
-@findex DEPRECATED_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.
-
-This method has been deprecated in favour of @code{gdbarch_return_value}
-(@pxref{gdbarch_return_value}).
-
 @item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf})
 @findex gdbarch_value_to_register
 Convert a value of type @var{type} into the raw contents of a register.
@@ -4271,52 +4136,28 @@ The following files add a target to @val
 @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}.
+@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}.
+
+You can also define @samp{TM_CLIBS} and @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.
+some machines it doesn't exist at all.
 
 @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.
+This is required to describe the basic layout of the target machine's
+processor chip (registers, stack, etc.).  It can be shared among many
+targets that use the same processor architecture.
 
 @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}.
+(Target header files such as
+@file{gdb/config/@var{arch}/tm-@var{ttt}.h},
+@file{gdb/config/@var{arch}/tm-@var{arch}.h}, and
+@file{config/tm-@var{os}.h} are no longer used.)
 
 @node Target Descriptions
 @chapter Target Descriptions
@@ -4512,7 +4353,10 @@ Both executables and core files have tar
 @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}.
+systems for this purpose; they are named @file{*-stub.c}. Many
+operating systems, embedded targets, emulators, and simulators already
+have a GDB stub built into them, and maintenance of the remote
+protocol must be careful to preserve compatibility.
 
 The @value{GDBN} user's manual describes how to put such a stub into
 your target code.  What follows is a discussion of integrating the
@@ -4727,10 +4571,6 @@ to decide whether floats are in use on t
 
 @item int gdbarch_get_longjmp_target (@var{gdbarch})
 @findex gdbarch_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 function 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
@@ -7144,27 +6984,6 @@ be for quite some time.
 Please send patches directly to
 @email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
 
-@section Obsolete Conditionals
-@cindex obsolete code
-
-Fragments of old code in @value{GDBN} sometimes reference or set the following
-configuration macros.  They should not be used by new code, and old uses
-should be removed as those parts of the debugger are otherwise touched.
-
-@table @code
-@item STACK_END_ADDR
-This macro used to define where the end of the stack appeared, for use
-in interpreting core file formats that don't record this address in the
-core file itself.  This information is now configured in BFD, and @value{GDBN}
-gets the info portably from there.  The values in @value{GDBN}'s configuration
-files should be moved into BFD configuration files (if needed there),
-and deleted from all of @value{GDBN}'s config files.
-
-Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
-is so old that it has never been converted to use BFD.  Now that's old!
-
-@end table
-
 @section Build Script
 
 @cindex build script

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]