* Testsuite::
* Hints::
+* GDB Observers:: @value{GDBN} Currently available observers
* GNU Free Documentation License:: The license for this documentation
* Index::
@end menu
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
+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.
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
@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
@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}
@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
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}).
+
+Returns the updated top-of-stack pointer.
+
+This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
-@item PUSH_DUMMY_FRAME
-@findex PUSH_DUMMY_FRAME
+@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 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
@end table
+@include observer.texi
@include fdl.texi
@node Index