* Testsuite::
* Hints::
+* GDB Observers:: @value{GDBN} Currently available observers
* GNU Free Documentation License:: The license for this documentation
* Index::
@end menu
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.)
+(@code{create_new_frame} calls @code{DEPRECATED_INIT_EXTRA_FRAME_INFO}
+if it is defined; that is where you should use the @code{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
+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
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
@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.
@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
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}
@findex CALL_DUMMY_LOCATION
See the file @file{inferior.h}.
-@item CALL_DUMMY_STACK_ADJUST
-@findex CALL_DUMMY_STACK_ADJUST
-Stack adjustment needed when performing an inferior function call.
-
-Should be deprecated in favor of something like @code{STACK_ALIGN}.
-
-@item CALL_DUMMY_STACK_ADJUST_P
-@findex CALL_DUMMY_STACK_ADJUST_P
-Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}.
-
-Should be deprecated in favor of something like @code{STACK_ALIGN}.
+@item 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
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
@findex EXTRACT_STRUCT_VALUE_ADDRESS_P
Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
-@item FLOAT_INFO
-@findex FLOAT_INFO
-Deprecated in favor of @code{PRINT_FLOAT_INFO}.
-
@item FP_REGNUM
@findex FP_REGNUM
If the virtual frame pointer is kept in a register, then define this
@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
+@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}
startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside
@code{_start}.
-@item FRAME_INIT_SAVED_REGS(@var{frame})
-@findex FRAME_INIT_SAVED_REGS
+@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 @code{frame_saved_regs_zalloc}.
+@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using
+@code{frame_saved_regs_zalloc}.
@code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
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
@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
@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_extra_info_zalloc}.
@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
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
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
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 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_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_call (@var{gdbarch}, @var{regcache}, @var{dummy_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 value (in
+the call dummy at @var{dummy_addr}).
-@item PUSH_DUMMY_FRAME
-@findex PUSH_DUMMY_FRAME
+Returns the updated top-of-stack pointer.
+
+This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
+
+@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
@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
@findex read_pc
@findex write_pc
@findex read_sp
-@findex write_sp
@findex read_fp
These change the behavior of @code{read_pc}, @code{write_pc},
-@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets,
-these may be left undefined. @value{GDBN} will call the read and write
-register functions with the relevant @code{_REGNUM} argument.
+@code{read_sp} and @code{read_fp}. For most targets, these may be left
+undefined. @value{GDBN} will call the read and write register functions
+with the relevant @code{_REGNUM} argument.
These macros are useful when a target keeps one of these registers in a
hard to get at place; for example, part in a segment register and part
@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
If defined, this must be an expression that is nonzero if a value of the
@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
@end table
+@include observer.texi
@include fdl.texi
@node Index
projects / deliverable / binutils-gdb.git / blobdiff