From 1f70da6a3acba8bc6171565c0389aa1f165ca4c7 Mon Sep 17 00:00:00 2001 From: Stan Shebs Date: Tue, 29 Jul 2008 20:26:53 +0000 Subject: [PATCH] * 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. --- gdb/doc/ChangeLog | 31 +++ gdb/doc/gdbint.texinfo | 466 +++++++++++++---------------------------- 2 files changed, 175 insertions(+), 322 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index d5917c65b70..6865945bf4e 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,34 @@ +2008-07-29 Stan Shebs + + * 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. + 2008-07-25 Tom Tromey * observer.texi (GDB Observers): Document new observers: diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 23d5816c5b9..3bb816f3877 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -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, calling @code{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 environment, but which require @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 for a software breakpoint, 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 @code{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. @section Watchpoints @cindex watchpoints @@ -649,6 +648,8 @@ the expression whose value is being watched, and tests whether the watched value has changed. Watchpoints whose watched values have changed are announced as hit. +@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}) @@ -801,6 +803,9 @@ generic library of functions that x86-based ports can use to implement support for watchpoints and hardware-assisted breakpoints. This subsection documents the x86 watchpoint facilities in @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 +1046,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 +1960,21 @@ generally the same as @code{frame_unwind_got_constant}. @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 +1985,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 +2226,10 @@ COFF files may have multiple sections, each prefixed by a header. The number of sections is limited. The COFF specification includes support for debugging. Although this -was a step forward, the debugging information was woefully limited. For -instance, it was not possible to represent code that came from an -included file. +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 +2269,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 +2313,8 @@ ECOFF includes a definition of a special debug format. 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 +2345,11 @@ The same reader is used for both compressed an normal DWARF 2 info. 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 +2365,10 @@ If you need to add a new object file format, you must first add it to BFD. This is beyond the scope of this document. You must then arrange for the BFD code to provide access to the -debugging symbols. Generally @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 +2559,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 +2603,27 @@ using the DJGPP (a.k.a.@: GO32) execution environment. @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 +2648,11 @@ The default value of the prompt string (normally @code{"(gdb) "}). @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 +2664,11 @@ Define this if the host can handle printing of long long integers via 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 +2682,6 @@ of functions to indicate that they never return. The default is already set correctly if compiling with GCC. This will almost never need to be defined. -@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 +2950,8 @@ However, architectures with smaller word sizes are often cramped for address space, so they may choose a pointer representation that breaks this identity, and allows a larger code address space. +@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 +3091,7 @@ This function is normally called from within a symbol reader. See 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 +3215,9 @@ You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register 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 +3232,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 +3319,6 @@ You should only use @code{gdbarch_value_to_register} with registers for which 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 +3580,6 @@ If not defined, no conversion will be performed. 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 +3615,6 @@ The @sc{amd64} (nee x86-64) @sc{abi} documentation refers to the @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 +3623,6 @@ For the frame described by @var{frame} return the number of arguments that 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 +3639,6 @@ return gdbarch_addr_bits_remove (gdbarch, pc); @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 +3664,6 @@ 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 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 +3675,20 @@ respectively. (Currently only defined for the Delta 68.) @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 +3785,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 +3878,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 +3888,6 @@ function descriptors, this contains the function descriptor value. 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 +3902,7 @@ By default, the stack is grown sufficient to hold a frame-aligned (@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 +3981,11 @@ If the stack-pointer is kept in a register, then use this function to return 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 +4072,14 @@ 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{(@var{register}, @var{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. + +@c need to explain virtual frame pointers, they are recorded in agent expressions +@c for tracepoints @item TARGET_HAS_HARDWARE_WATCHPOINTS If non-zero, the target has support for hardware-assisted @@ -4208,14 +4090,12 @@ 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 the header file +@file{include/dis-asm.h}, and 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 +4104,6 @@ frame_id}} that uniquely identifies an inferior function call's dummy frame. The value returned must match the dummy frame stack value previously saved by @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 +4139,28 @@ The following files add a target to @value{GDBN}: @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}. +@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. -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}. +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 +4356,10 @@ Both executables and core files have target vectors. @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{@var{cpu}-stub.c}. Many +operating systems, embedded targets, emulators, and simulators already +have a GDB stub built into them, and maintenance of the remote +protocol must be careful to preserve compatibility. The @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 +4574,6 @@ to decide whether floats are in use on this target. @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 +6987,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 -- 2.30.2