* Testsuite::
* Hints::
+* GDB Observers:: @value{GDBN} Currently available observers
* GNU Free Documentation License:: The license for this documentation
* Index::
@end menu
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{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.)
+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
+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.
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
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
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
@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.
-
-Should be deprecated in favor of something like @code{STACK_ALIGN}.
+This method has been replaced by @code{push_dummy_code}
+(@pxref{push_dummy_code}).
-@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 EXTRACT_STRUCT_VALUE_ADDRESS_P
Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
-@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
@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.
+@code{FRAME_FIND_SAVED_REGS} is deprecated.
@item FRAME_NUM_ARGS (@var{fi})
@findex FRAME_NUM_ARGS
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
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 non-zero, round arguments to a boundary of this many bits before
pushing them on the stack.
-@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.
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
@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
@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
@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
@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
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
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
@end table
+@include observer.texi
@include fdl.texi
@node Index
projects / binutils-gdb.git / blobdiff