X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdbint.texinfo;h=dc5c6b809d8d0f5e246e62fe157f382bf7f2bc10;hb=39fe6e8082911722e4605fe70551e61a44a56418;hp=eef2b86f3026ee5f50610901b313307d5fd1dc7d;hpb=b5b0480a1015484fb53dabd390031bbdffdc28e1;p=binutils-gdb.git diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index eef2b86f302..dc5c6b809d8 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -8,7 +8,7 @@ @ifinfo This file documents the internals of the GNU debugger @value{GDBN}. -Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002 +Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003 Free Software Foundation, Inc. Contributed by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan Shebs. @@ -50,8 +50,8 @@ Software Foundation raise funds for GNU development.'' @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, 2002 - Free Software Foundation, Inc. +Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, + 2002, 2003 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -94,6 +94,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Testsuite:: * Hints:: +* GDB Observers:: @value{GDBN} Currently available observers * GNU Free Documentation License:: The license for this documentation * Index:: @end menu @@ -240,22 +241,24 @@ machine-independent part of @value{GDBN}, except that it is used when setting up a new frame from scratch, as follows: @smallexample -create_new_frame (read_register (FP_REGNUM), read_pc ())); +create_new_frame (read_register (DEPRECATED_FP_REGNUM), read_pc ())); @end smallexample @cindex frame pointer register -Other than that, all the meaning imparted to @code{FP_REGNUM} is -imparted by the machine-dependent code. So, @code{FP_REGNUM} can have -any value that is convenient for the code that creates new frames. -(@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is -defined; that is where you should use the @code{FP_REGNUM} value, if -your frames are nonstandard.) +Other than that, all the meaning imparted to @code{DEPRECATED_FP_REGNUM} +is imparted by the machine-dependent code. So, +@code{DEPRECATED_FP_REGNUM} can have any value that is convenient for +the code that creates new frames. (@code{create_new_frame} calls +@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} if it is defined; that is where +you should use the @code{DEPRECATED_FP_REGNUM} value, if your frames are +nonstandard.) @cindex frame chain -Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the -address of the calling function's frame. This will be used to create -a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO} -and @code{INIT_FRAME_PC} will be called for the new frame. +Given a @value{GDBN} frame, define @code{DEPRECATED_FRAME_CHAIN} to +determine the address of the calling function's frame. This will be +used to create a new @value{GDBN} frame struct, and then +@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} and +@code{DEPRECATED_INIT_FRAME_PC} will be called for the new frame. @section Breakpoint Handling @@ -285,7 +288,7 @@ A third possibility is that the target already has the ability to do breakpoints somehow; for instance, a ROM monitor may do its own software breakpoints. So although these are not literally ``hardware breakpoints'', from @value{GDBN}'s point of view they work the same; -@value{GDBN} need not do nothing more than set the breakpoint and wait +@value{GDBN} need not do anything more than set the breakpoint and wait for something to happen. Since they depend on hardware resources, hardware breakpoints may be @@ -695,6 +698,29 @@ watchpoints might interfere with the underlying OS and are probably unavailable in many platforms. @end enumerate +@section Observing changes in @value{GDBN} internals +@cindex observer pattern interface +@cindex notifications about changes in internals + +In order to function properly, several modules need to be notified when +some changes occur in the @value{GDBN} internals. Traditionally, these +modules have relied on several paradigms, the most common ones being +hooks and gdb-events. Unfortunately, none of these paradigms was +versatile enough to become the standard notification mechanism in +@value{GDBN}. The fact that they only supported one ``client'' was also +a strong limitation. + +A new paradigm, based on the Observer pattern of the @cite{Design +Patterns} book, has therefore been implemented. The goal was to provide +a new interface overcoming the issues with the notification mechanisms +previously available. This new interface needed to be strongly typed, +easy to extend, and versatile enough to be used as the standard +interface when adding new notifications. + +See @ref{GDB Observers} for a brief description of the observers +currently implemented in GDB. The rationale for the current +implementation is also briefly discussed. + @node User Interface @chapter User Interface @@ -1841,7 +1867,6 @@ The file @file{mdebugread.c} implements reading for this format. DWARF 1 is a debugging format that was originally designed to be used with ELF in SVR4 systems. -@c OBSOLETE CHILL_PRODUCER @c GCC_PRODUCER @c GPLUS_PRODUCER @c LCC_PRODUCER @@ -2245,11 +2270,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 USE_GENERIC_DUMMY_FRAMES -@cindex generic dummy frames -Define this to 1 if the target is using the generic inferior function -call code. See @code{blockframe.c} for more information. - @item USE_MMALLOC @findex mmalloc @value{GDBN} will use the @code{mmalloc} library for memory allocation @@ -2301,9 +2321,8 @@ always linked in.) @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}, -@file{remote-nindy.c}, and @file{utils.c} for other things, at the -moment.) +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. @@ -2429,9 +2448,12 @@ Here are the functions that make up the OS ABI framework: Return the name of the OS ABI corresponding to @var{osabi}. @end deftypefun -@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch})) +@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, unsigned long @var{machine}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch})) Register the OS ABI handler specified by @var{init_osabi} for the -architecture/OS ABI pair specified by @var{arch} and @var{osabi}. +architecture, machine type and OS ABI specified by @var{arch}, +@var{machine} and @var{osabi}. In most cases, a value of zero for the +machine type, which implies the architecture's default machine type, +will suffice. @end deftypefun @deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd})) @@ -2579,35 +2601,6 @@ This function performs architecture-specific conversions as described above for @code{store_typed_address}. @end deftypefun - -@value{GDBN} also provides functions that do the same tasks, but assume -that pointers are simply byte addresses; they aren't sensitive to the -current architecture, beyond knowing the appropriate endianness. - -@deftypefun CORE_ADDR extract_address (void *@var{addr}, int len) -Extract a @var{len}-byte number from @var{addr} in the appropriate -endianness for the current architecture, and return it. Note that -@var{addr} refers to @value{GDBN}'s memory, not the inferior's. - -This function should only be used in architecture-specific code; it -doesn't have enough information to turn bits into a true address in the -appropriate way for the current architecture. If you can, use -@code{extract_typed_address} instead. -@end deftypefun - -@deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val}) -Store @var{val} at @var{addr} as a @var{len}-byte integer, in the -appropriate endianness for the current architecture. Note that -@var{addr} refers to a buffer in @value{GDBN}'s memory, not the -inferior's. - -This function should only be used in architecture-specific code; it -doesn't have enough information to turn a true address into bits in the -appropriate way for the current architecture. If you can, use -@code{store_typed_address} instead. -@end deftypefun - - Here are some macros which architectures can define to indicate the relationship between pointers and addresses. These have default definitions, appropriate for architectures on which all pointers are @@ -2675,34 +2668,34 @@ to implement the address class macros: @smallexample somearch_address_class_type_flags (int byte_size, int dwarf2_addr_class) -{ +@{ if (byte_size == 2) return TYPE_FLAG_ADDRESS_CLASS_1; else return 0; -} +@} static char * somearch_address_class_type_flags_to_name (int type_flags) -{ +@{ if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1) return "short"; else return NULL; -} +@} int somearch_address_class_name_to_type_flags (char *name, int *type_flags_ptr) -{ +@{ if (strcmp (name, "short") == 0) - { + @{ *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1; return 1; - } + @} else return 0; -} +@} @end smallexample The qualifier @code{@@short} is used in @value{GDBN}'s type expressions @@ -2916,18 +2909,6 @@ 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 @@ -2993,16 +2974,6 @@ 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} @@ -3085,45 +3056,47 @@ 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 +@item DEPRECATED_CALL_DUMMY_WORDS +@findex DEPRECATED_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. +host-byte-ordered @code{DEPRECATED_REGISTER_SIZE} 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}. +This method has been replaced by @code{push_dummy_code} +(@pxref{push_dummy_code}). + +@item DEPRECATED_SIZEOF_CALL_DUMMY_WORDS +@findex DEPRECATED_SIZEOF_CALL_DUMMY_WORDS +The size of @code{DEPRECATED_CALL_DUMMY_WORDS}. This must return a +positive value. See also @code{DEPRECATED_CALL_DUMMY_LENGTH}. + +This method has been replaced by @code{push_dummy_code} +(@pxref{push_dummy_code}). @item CALL_DUMMY @findex CALL_DUMMY -A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated. +A static initializer for @code{DEPRECATED_CALL_DUMMY_WORDS}. +Deprecated. + +This method has been replaced by @code{push_dummy_code} +(@pxref{push_dummy_code}). @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. +This method has been replaced by @code{push_dummy_code} +(@pxref{push_dummy_code}). -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 DEPRECATED_CALL_DUMMY_STACK_ADJUST +@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST +Stack adjustment needed when performing an inferior function call. This +function is no longer needed. @xref{push_dummy_call}, which can handle +all alignment directly. @item CANNOT_FETCH_REGISTER (@var{regno}) @findex CANNOT_FETCH_REGISTER @@ -3147,62 +3120,12 @@ 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 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 @@ -3218,12 +3141,6 @@ Similarly, for hardware breakpoints. 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. - -This method is deprecated. - @item PRINT_FLOAT_INFO() @findex PRINT_FLOAT_INFO If defined, then the @samp{info float} command will print information about @@ -3285,17 +3202,13 @@ If not defined, @code{EXTRACT_RETURN_VALUE} is used. @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 +@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{TARGET_READ_FP} is not -defined. +This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP} +is not defined. @item FRAMELESS_FUNCTION_INVOCATION(@var{fi}) @findex FRAMELESS_FUNCTION_INVOCATION @@ -3324,42 +3237,28 @@ By default, no frame based stack alignment is performed. @findex FRAME_ARGS_ADDRESS_CORRECT See @file{stack.c}. -@item FRAME_CHAIN(@var{frame}) -@findex FRAME_CHAIN +@item DEPRECATED_FRAME_CHAIN(@var{frame}) +@findex DEPRECATED_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 +@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{FRAME_INIT_SAVED_REGS} using either -@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}. +@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using +@code{frame_saved_regs_zalloc}. -@code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated. +@code{FRAME_FIND_SAVED_REGS} is deprecated. @item FRAME_NUM_ARGS (@var{fi}) @findex FRAME_NUM_ARGS @@ -3367,10 +3266,30 @@ 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 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{unwind_pc}. + +@item CORE_ADDR unwind_pc (struct frame_info *@var{this_frame}) +@findex unwind_pc +@anchor{unwind_pc} Return the instruction address, in @var{this_frame}'s +caller, at which execution will resume after @var{this_frame} returns. +This is commonly refered to as the return address. + +The implementation, which must be frame agnostic (work with any frame), +is typically no more than: + +@smallexample +ULONGEST pc; +frame_unwind_unsigned_register (this_frame, D10V_PC_REGNUM, &pc); +return d10v_make_iaddr (pc); +@end smallexample + +@noindent +@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces. @item FUNCTION_EPILOGUE_SIZE @findex FUNCTION_EPILOGUE_SIZE @@ -3431,11 +3350,10 @@ 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 +@item DEPRECATED_GET_SAVED_REGISTER +@findex DEPRECATED_GET_SAVED_REGISTER Define this if you need to supply your own definition for the function -@code{get_saved_register}. +@code{DEPRECATED_GET_SAVED_REGISTER}. @item IBM6000_TARGET @findex IBM6000_TARGET @@ -3458,14 +3376,14 @@ 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 +@item DEPRECATED_INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame}) +@findex DEPRECATED_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}. +is allocated using @code{frame_extra_info_zalloc}. -@item INIT_FRAME_PC (@var{fromleaf}, @var{prev}) -@findex INIT_FRAME_PC +@item DEPRECATED_INIT_FRAME_PC (@var{fromleaf}, @var{prev}) +@findex DEPRECATED_INIT_FRAME_PC This is a C statement that sets the pc of the frame pointed to by @var{prev}. [By default...] @@ -3538,13 +3456,6 @@ method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for @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 @@ -3578,6 +3489,28 @@ 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_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup}) +@findex register_reggroup_p +@cindex register groups +Return non-zero if register @var{regnum} is a member of the register +group @var{reggroup}. + +By default, registers are grouped as follows: + +@table @code +@item float_reggroup +Any register with a valid name and a floating-point type. +@item vector_reggroup +Any register with a valid name and a vector type. +@item general_reggroup +Any register with a valid name and a type other than vector or +floating-point. @samp{float_reggroup}. +@item save_reggroup +@itemx restore_reggroup +@itemx all_reggroup +Any register with a valid name. +@end table + @item REGISTER_VIRTUAL_SIZE (@var{reg}) @findex REGISTER_VIRTUAL_SIZE Return the virtual size of @var{reg}; defaults to the size of the @@ -3590,6 +3523,12 @@ Return the virtual size of @var{reg}. 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 +superseeds @code{REGISTER_VIRTUAL_TYPE}. @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 @@ -3686,10 +3625,6 @@ them. @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 @@ -3724,16 +3659,6 @@ The number of the ``next program counter'' register, if defined. 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. @@ -3747,26 +3672,57 @@ A hook defined for XCOFF reading. 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 +@item DEPRECATED_POP_FRAME +@findex DEPRECATED_POP_FRAME +@findex frame_pop +If defined, used by @code{frame_pop} to remove a stack frame. This +method has been superseeded by generic code. + +@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) +@findex push_dummy_call +@findex DEPRECATED_PUSH_ARGUMENTS. +@anchor{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}), and the return address (@var{bp_addr}). + +Returns the updated top-of-stack pointer. + +This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}. + +@item CORE_ADDR 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}) +@findex push_dummy_code +@findex DEPRECATED_FIX_CALL_DUMMY +@anchor{push_dummy_code} Given a stack based call dummy, push the +instruction sequence (including space for a breakpoint) to which the +called function should return. + +Set @var{bp_addr} to the address at which the breakpoint instruction +should be inserted, @var{real_pc} to the resume address when starting +the call sequence, and return the updated inner-most stack address. + +By default, the stack is grown sufficient to hold a frame-aligned +(@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 @code{DEPRECATED_CALL_DUMMY_WORDS}, +@code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY}, +@code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE}, +@code{GDB_TARGET_IS_HPPA}, +@code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and +@code{DEPRECATED_FIX_CALL_DUMMY}. + +@item DEPRECATED_PUSH_DUMMY_FRAME +@findex DEPRECATED_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 DEPRECATED_REGISTER_BYTES +@findex DEPRECATED_REGISTER_BYTES +The total amount of space needed to store @value{GDBN}'s copy of the +machine's register state. + +This is no longer needed. @value{GDBN} instead computes the size of the +register buffer at run-time. @item REGISTER_NAME(@var{i}) @findex REGISTER_NAME @@ -3784,20 +3740,17 @@ 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. +@anchor{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. @xref{unwind_dummy_id}. @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 @@ -3823,10 +3776,8 @@ 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. +the number (greater than or equal to zero) of that register, or -1 if +there is no such register. @item STAB_REG_TO_REGNUM @findex STAB_REG_TO_REGNUM @@ -3933,18 +3884,15 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. @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 +@code{read_sp} and @code{deprecated_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 @@ -3953,10 +3901,10 @@ 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. +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. @item TARGET_HAS_HARDWARE_WATCHPOINTS If non-zero, the target has support for hardware-assisted @@ -3969,11 +3917,20 @@ 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. +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. + +@item struct frame_id unwind_dummy_id (struct frame_info *@var{frame}) +@findex unwind_dummy_id +@anchor{unwind_dummy_id} Given @var{frame} return a @code{struct +frame_id} that uniquely identifies an inferior function call's dummy +frame. The value returned must match the dummy frame stack value +previously saved using @code{SAVE_DUMMY_FRAME_TOS}. +@xref{SAVE_DUMMY_FRAME_TOS}. @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) @findex USE_STRUCT_CONVENTION @@ -4191,10 +4148,8 @@ Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@* 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} +Replaced with @code{DEPRECATED_FRAME_INIT_SAVED_REGS} @end table @noindent @@ -5472,62 +5427,6 @@ target-dependent @file{.h} and @file{.c} files used for your configuration. @end itemize -@section Configuring @value{GDBN} for Release - -@cindex preparing a release -@cindex making a distribution tarball -From the top level directory (containing @file{gdb}, @file{bfd}, -@file{libiberty}, and so on): - -@smallexample -make -f Makefile.in gdb.tar.gz -@end smallexample - -@noindent -This will properly configure, clean, rebuild any files that are -distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}), -and will then make a tarfile. (If the top level directory has already -been configured, you can just do @code{make gdb.tar.gz} instead.) - -This procedure requires: - -@itemize @bullet - -@item -symbolic links; - -@item -@code{makeinfo} (texinfo2 level); - -@item -@TeX{}; - -@item -@code{dvips}; - -@item -@code{yacc} or @code{bison}. -@end itemize - -@noindent -@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.). - -@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION - -@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, -which are not yet a default for anything (but we have to start using -them sometime). - -For making paper, the only thing this implies is the right generation of -@file{texinfo.tex} needs to be included in the distribution. - -For making info files, however, rather than duplicating the texinfo2 -distribution, generate @file{gdb-all.texinfo} locally, and include the -files @file{gdb.info*} in the distribution. Note the plural; -@code{makeinfo} will split the document into one overall file and five -or so included files. - - @node Releasing GDB @chapter Releasing @value{GDBN} @@ -6060,6 +5959,17 @@ $ ( cd dejagnu/src/dejagnu && autoconf ) This is identical to the process used to create the daily snapshot. +@smallexample +$ for m in gdb insight +do +( cd $m/src && gmake -f src-release $m.tar ) +done +$ ( m=dejagnu; cd $m/src && gmake -f src-release $m.tar.bz2 ) +@end smallexample + +If the top level source directory does not have @file{src-release} +(@value{GDBN} version 5.3.1 or earlier), try these commands instead: + @smallexample $ for m in gdb insight do @@ -6704,6 +6614,7 @@ is so old that it has never been converted to use BFD. Now that's old! @end table +@include observer.texi @include fdl.texi @node Index