Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
@end ifinfo
@setchapternewpage off
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
@end titlepage
@contents
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{DEPRECATED_FRAME_CHAIN} to
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
implement a new event-loop that GDB would use.
The event-loop will eventually be made re-entrant. This is so that
-@value{GDB} can better handle the problem of some commands blocking
+@value{GDBN} can better handle the problem of some commands blocking
instead of returning.
@subheading Library - @file{gdb.h}
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{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
favor of @code{BREAKPOINT_FROM_PC}.
-@item REMOTE_BREAKPOINT
-@itemx LITTLE_REMOTE_BREAKPOINT
-@itemx BIG_REMOTE_BREAKPOINT
-@findex BIG_REMOTE_BREAKPOINT
-@findex LITTLE_REMOTE_BREAKPOINT
-@findex REMOTE_BREAKPOINT
-Similar to BREAKPOINT, but used for remote targets.
-
-@code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been
-deprecated in favor of @code{BREAKPOINT_FROM_PC}.
+@item DEPRECATED_REMOTE_BREAKPOINT
+@itemx DEPRECATED_LITTLE_REMOTE_BREAKPOINT
+@itemx DEPRECATED_BIG_REMOTE_BREAKPOINT
+@findex DEPRECATED_BIG_REMOTE_BREAKPOINT
+@findex DEPRECATED_LITTLE_REMOTE_BREAKPOINT
+@findex DEPRECATED_REMOTE_BREAKPOINT
+Specify the breakpoint instruction sequence for a remote target.
+@code{DEPRECATED_REMOTE_BREAKPOINT},
+@code{DEPRECATED_BIG_REMOTE_BREAKPOINT} and
+@code{DEPRECATED_LITTLE_REMOTE_BREAKPOINT} have been deprecated in
+favor of @code{BREAKPOINT_FROM_PC} (@pxref{BREAKPOINT_FROM_PC}).
@item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr})
@findex BREAKPOINT_FROM_PC
-Use the program counter to determine the contents and size of a
-breakpoint instruction. It returns a pointer to a string of bytes
-that encode a breakpoint instruction, stores the length of the string
-to *@var{lenptr}, and adjusts pc (if necessary) to point to the actual
-memory location where the breakpoint should be inserted.
+@anchor{BREAKPOINT_FROM_PC} Use the program counter to determine the
+contents and size of a breakpoint instruction. It returns a pointer to
+a string of bytes that encode a breakpoint instruction, stores the
+length of the string to @code{*@var{lenptr}}, and adjusts the program
+counter (if necessary) to point to the actual memory location where the
+breakpoint should be inserted.
Although it is common to use a trap instruction for a breakpoint, it's
not required; for instance, the bit pattern could be an invalid
@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}.
+This method has been replaced by @code{push_dummy_code}
+(@pxref{push_dummy_code}).
+
@item DEPRECATED_CALL_DUMMY_STACK_ADJUST
@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST
Stack adjustment needed when performing an inferior function call. This
@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
Define this to adjust @var{address} so that it meets the alignment
requirements for the start of a new stack frame. A stack frame's
alignment requirements are typically stronger than a target processors
-stack alignment requirements (@pxref{STACK_ALIGN}).
+stack alignment requirements (@pxref{DEPRECATED_STACK_ALIGN}).
This function is used to ensure that, when creating a dummy frame, both
the initial stack pointer and (if needed) the address of the return
value are correctly aligned.
-Unlike @code{STACK_ALIGN}, this function always adjusts the address in
-the direction of stack growth.
+Unlike @code{DEPRECATED_STACK_ALIGN}, this function always adjusts the
+address in the direction of stack growth.
By default, no frame based stack alignment is performed.
-@item FRAME_ARGS_ADDRESS_CORRECT
-@findex FRAME_ARGS_ADDRESS_CORRECT
-See @file{stack.c}.
+@item int frame_red_zone_size
+
+The number of bytes, beyond the innermost-stack-address, reserved by the
+@sc{abi}. A function is permitted to use this scratch area (instead of
+allocating extra stack space).
+
+When performing an inferior function call, to ensure that it does not
+modify this area, @value{GDBN} adjusts the innermost-stack-address by
+@var{frame_red_zone_size} bytes before pushing parameters onto the
+stack.
+
+By default, zero bytes are allocated. The value must be aligned
+(@pxref{frame_align}).
+
+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
@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
@noindent
@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces.
+@item CORE_ADDR unwind_sp (struct frame_info *@var{this_frame})
+@findex unwind_sp
+@anchor{unwind_sp} Return the frame's inner most stack address. This is
+commonly refered to as the frame's @dfn{stack pointer}.
+
+The implementation, which must be frame agnostic (work with any frame),
+is typically no more than:
+
+@smallexample
+ULONGEST sp;
+frame_unwind_unsigned_register (this_frame, D10V_SP_REGNUM, &sp);
+return d10v_make_daddr (sp);
+@end smallexample
+
+@noindent
+@xref{TARGET_READ_SP}, which this method replaces.
+
@item FUNCTION_EPILOGUE_SIZE
@findex FUNCTION_EPILOGUE_SIZE
For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
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, 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{regcache}, @var{dummy_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@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 value (in
-the call dummy at @var{dummy_addr}).
+@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
@findex REGISTER_NAMES
Deprecated in favor of @code{REGISTER_NAME}.
-@item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
-@findex REG_STRUCT_HAS_ADDR
+@item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
+@findex DEPRECATED_REG_STRUCT_HAS_ADDR
Define this to return 1 if the given type will be passed by pointer
rather than directly.
@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
declarations) into @value{GDBN} regnums. If not defined, no conversion will be
done.
-@item STACK_ALIGN (@var{addr})
-@anchor{STACK_ALIGN}
-@findex STACK_ALIGN
+@item DEPRECATED_STACK_ALIGN (@var{addr})
+@anchor{DEPRECATED_STACK_ALIGN}
+@findex DEPRECATED_STACK_ALIGN
Define this to increase @var{addr} so that it meets the alignment
requirements for the processor's stack.
@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 read_fp
-These change the behavior of @code{read_pc}, @code{write_pc},
-@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.
+@anchor{TARGET_READ_SP} These change the behavior of @code{read_pc},
+@code{write_pc}, @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
hard to get at place; for example, part in a segment register and part
in an ordinary register.
+@xref{unwind_sp}, which replaces @code{TARGET_READ_SP}.
+
@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
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{DEPRECATED_FRAME_INIT_SAVED_REGS}
@end table
Define this to be able to, when a breakpoint insertion fails, warn the
user that another process may be running with the same executable.
-@item PREPARE_TO_PROCEED (@var{select_it})
-@findex PREPARE_TO_PROCEED
-This (ugly) macro allows a native configuration to customize the way the
-@code{proceed} function in @file{infrun.c} deals with switching between
-threads.
-
-In a multi-threaded task we may select another thread and then continue
-or step. But if the old thread was stopped at a breakpoint, it will
-immediately cause another breakpoint stop without any execution (i.e. it
-will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
-first.
-
-If defined, @code{PREPARE_TO_PROCEED} should check the current thread
-against the thread that reported the most recent event. If a step-over
-is required, it returns TRUE. If @var{select_it} is non-zero, it should
-reselect the old thread.
-
@item PROC_NAME_FMT
@findex PROC_NAME_FMT
Defines the format for the name of a @file{/proc} device. Should be
@item -Wtrigraphs
@item -Wformat
+@itemx -Wformat-nonliteral
Since @value{GDBN} uses the @code{format printf} attribute on all
-@code{printf} like functions this checks not just @code{printf} calls
+@code{printf} like functions these check not just @code{printf} calls
but also calls to functions such as @code{fprintf_unfiltered}.
@item -Wparentheses
When @value{GDBN} has a local version of a system header file (ex
@file{string.h}) the file name based on the POSIX header prefixed with
-@file{gdb_} (@file{gdb_string.h}).
+@file{gdb_} (@file{gdb_string.h}). These headers should be relatively
+independent: they should use only macros defined by @file{configure},
+the compiler, or the host; they should include only system headers; they
+should refer only to system types. They may be shared between multiple
+programs, e.g.@: @value{GDBN} and @sc{gdbserver}.
For other files @samp{-} is used as the separator.
projects / deliverable / binutils-gdb.git / blobdiff