\input texinfo @c -*- texinfo -*-
@setfilename gdbint.info
@include gdb-cfg.texi
-@dircategory Programming & development tools.
+@dircategory Software development
@direntry
* Gdb-Internals: (gdbint). The GNU debugger's internals.
@end direntry
@ifinfo
This file documents the internals of the GNU debugger @value{GDBN}.
-Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003
+Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004
Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
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
@vskip 0pt plus 1filll
Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,
- 2002, 2003 Free Software Foundation, Inc.
+ 2002, 2003, 2004 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
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
If the inferior has some watchpoint that triggered, return the address
associated with that watchpoint. Otherwise, return zero.
-@findex DECR_PC_AFTER_HW_BREAK
-@item DECR_PC_AFTER_HW_BREAK
-If defined, @value{GDBN} decrements the program counter by the value
-of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This
-overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint
-that breaks is a hardware-assisted breakpoint.
-
@findex HAVE_STEPPABLE_WATCHPOINT
@item HAVE_STEPPABLE_WATCHPOINT
If defined to a non-zero value, it is not necessary to disable a
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}
@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
which is the POSIX equivalent.
-@item MMAP_BASE_ADDRESS
-When using HAVE_MMAP, the first mapping should go at this address.
-
-@item MMAP_INCREMENT
-when using HAVE_MMAP, this is the increment between mappings.
-
@item NORETURN
If defined, this should be one or more tokens, such as @code{volatile},
that can be used in both the declaration and definition of functions to
set correctly if compiling with GCC. This will almost never need to be
defined.
-@item USE_MMALLOC
-@findex mmalloc
-@value{GDBN} will use the @code{mmalloc} library for memory allocation
-for symbol reading if this symbol is defined. Be careful defining it
-since there are systems on which @code{mmalloc} does not work for some
-reason. One example is the DECstation, where its RPC library can't
-cope with our redefinition of @code{malloc} to call @code{mmalloc}.
-When defining @code{USE_MMALLOC}, you will also have to set
-@code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This
-define is set when you configure with @samp{--with-mmalloc}.
-
-@item NO_MMCHECK
-@findex mmcheck
-Define this if you are using @code{mmalloc}, but don't want the overhead
-of checking the heap with @code{mmcheck}. Note that on some systems,
-the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if
-@code{free} is ever called with these pointers after calling
-@code{mmcheck} to enable checking, a memory corruption abort is certain
-to occur. These systems can still use @code{mmalloc}, but must define
-@code{NO_MMCHECK}.
-
-@item MMCHECK_FORCE
-Define this to 1 if the C runtime allocates memory prior to
-@code{mmcheck} being called, but that memory is never freed so we don't
-have to worry about it triggering a memory corruption abort. The
-default is 0, which means that @code{mmcheck} will only install the heap
-checking functions if there has not yet been any memory allocation
-calls, and if it fails to install the functions, @value{GDBN} will issue a
-warning. This is currently defined if you configure using
-@samp{--with-mmalloc}.
-
-@item NO_SIGINTERRUPT
-@findex siginterrupt
-Define this to indicate that @code{siginterrupt} is not available.
-
@item SEEK_CUR
@itemx SEEK_SET
Define these to appropriate value for the system @code{lseek}, if not already
address space, so they may choose a pointer representation that breaks this
identity, and allows a larger code address space.
-For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
+For example, the Renesas D10V is a 16-bit VLIW processor whose
instructions are 32 bits long@footnote{Some D10V instructions are
actually pairs of 16-bit sub-instructions. However, since you can't
jump into the middle of such a pair, code addresses can only refer to
unless this macro returns a non-zero value for that register.
@end deftypefn
-@deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
+@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg})
The size of register number @var{reg}'s raw value. This is the number
of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
remote protocol packet.
@end deftypefn
-@deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
+@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg})
The size of register number @var{reg}'s value, in its virtual format.
This is the size a @code{struct value}'s buffer will have, holding that
register's value.
@end deftypefn
-@deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
+@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg})
This is the type of the virtual representation of register number
@var{reg}. Note that there is no need for a macro giving a type for the
register's raw form; once the register's value has been obtained, @value{GDBN}
@deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
Convert the value of register number @var{reg} to @var{type}, which
-should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
+should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
at @var{from} holds the register's value in raw format; the macro should
convert the value to virtual format, and place it at @var{to}.
@deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
Convert the value of register number @var{reg} to @var{type}, which
-should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
+should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
at @var{from} holds the register's value in raw format; the macro should
convert the value to virtual format, and place it at @var{to}.
parameter to an @code{int}, but still reports the parameter as its
original type, rather than the promoted type.
-@item BELIEVE_PCC_PROMOTION_TYPE
-@findex BELIEVE_PCC_PROMOTION_TYPE
-Define this if @value{GDBN} should believe the type of a @code{short}
-argument when compiled by @code{pcc}, but look within a full int space to get
-its value. Only defined for Sun-3 at present.
-
@item BITS_BIG_ENDIAN
@findex BITS_BIG_ENDIAN
Define this if the numbering of bits in the targets does @strong{not} match the
@code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
reason.
-@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{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.
-
-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{DEPRECATED_CALL_DUMMY_WORDS}.
-Deprecated.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
+@item ADJUST_BREAKPOINT_ADDRESS (@var{address})
+@findex ADJUST_BREAKPOINT_ADDRESS
+@cindex breakpoint address adjusted
+Given an address at which a breakpoint is desired, return a breakpoint
+address adjusted to account for architectural constraints on
+breakpoint placement. This method is not needed by most targets.
+
+The FR-V target (see @file{frv-tdep.c}) requires this method.
+The FR-V is a VLIW architecture in which a number of RISC-like
+instructions are grouped (packed) together into an aggregate
+instruction or instruction bundle. When the processor executes
+one of these bundles, the component instructions are executed
+in parallel.
+
+In the course of optimization, the compiler may group instructions
+from distinct source statements into the same bundle. The line number
+information associated with one of the latter statements will likely
+refer to some instruction other than the first one in the bundle. So,
+if the user attempts to place a breakpoint on one of these latter
+statements, @value{GDBN} must be careful to @emph{not} place the break
+instruction on any instruction other than the first one in the bundle.
+(Remember though that the instructions within a bundle execute
+in parallel, so the @emph{first} instruction is the instruction
+at the lowest address and has nothing to do with execution order.)
+
+The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a
+breakpoint's address by scanning backwards for the beginning of
+the bundle, returning the address of the bundle.
+
+Since the adjustment of a breakpoint may significantly alter a user's
+expectation, @value{GDBN} prints a warning when an adjusted breakpoint
+is initially set and each time that that breakpoint is hit.
@item CALL_DUMMY_LOCATION
@findex CALL_DUMMY_LOCATION
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
-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
A C expression that should be nonzero if @var{regno} cannot be fetched
status words, and other special registers. If this is not defined,
@value{GDBN} will assume that all registers may be written.
-@item DO_DEFERRED_STORES
-@itemx CLEAR_DEFERRED_STORES
-@findex CLEAR_DEFERRED_STORES
-@findex DO_DEFERRED_STORES
-Define this to execute any deferred stores of registers into the inferior,
-and to cancel any deferred stores.
-
-Currently only implemented correctly for native Sparc 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
program encounters a breakpoint. This is often the number of bytes in
@code{BREAKPOINT}, though not always. For most targets this value will be 0.
-@item DECR_PC_AFTER_HW_BREAK
-@findex DECR_PC_AFTER_HW_BREAK
-Similarly, for hardware breakpoints.
-
@item DISABLE_UNSETTABLE_BREAK (@var{addr})
@findex DISABLE_UNSETTABLE_BREAK
If defined, this should evaluate to 1 if @var{addr} is in a shared
the raw register state @var{regbuf} and copy that, in virtual format,
into @var{valbuf}.
-@item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
-@findex EXTRACT_STRUCT_VALUE_ADDRESS
+This method has been deprecated in favour of @code{gdbarch_return_value}
+(@pxref{gdbarch_return_value}).
+
+@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
+@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS
+@anchor{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}
When defined, extract from the array @var{regbuf} (containing the raw
register state) the @code{CORE_ADDR} at which a function should return
its structure value.
-If not defined, @code{EXTRACT_RETURN_VALUE} is used.
+@xref{gdbarch_return_value}.
-@item EXTRACT_STRUCT_VALUE_ADDRESS_P()
-@findex EXTRACT_STRUCT_VALUE_ADDRESS_P
-Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
+@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P()
+@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P
+Predicate for @code{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}.
@item DEPRECATED_FP_REGNUM
@findex DEPRECATED_FP_REGNUM
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
+@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
+@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION
Define this to an expression that returns 1 if the function invocation
represented by @var{fi} does not have a stack frame associated with it.
Otherwise return 0.
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 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
Given @var{frame}, return a pointer to the calling frame.
@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
function's epilogue.
-@item FUNCTION_START_OFFSET
-@findex FUNCTION_START_OFFSET
+@item DEPRECATED_FUNCTION_START_OFFSET
+@findex DEPRECATED_FUNCTION_START_OFFSET
An integer, giving the offset in bytes from a function's address (as
used in the values of symbols, function pointers, etc.), and the
function's first genuine instruction.
This is zero on almost all machines: the function's address is usually
-the address of its first instruction. However, on the VAX, for example,
-each function starts with two bytes containing a bitmask indicating
-which registers to save upon entry to the function. The VAX @code{call}
-instructions check this value, and save the appropriate registers
-automatically. Thus, since the offset from the function's address to
-its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
-be 2 on the VAX.
+the address of its first instruction. However, on the VAX, for
+example, each function starts with two bytes containing a bitmask
+indicating which registers to save upon entry to the function. The
+VAX @code{call} instructions check this value, and save the
+appropriate registers automatically. Thus, since the offset from the
+function's address to its first instruction is two bytes,
+@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
@item GCC_COMPILED_FLAG_SYMBOL
@itemx GCC2_COMPILED_FLAG_SYMBOL
Define this if you need to supply your own definition for the function
@code{DEPRECATED_GET_SAVED_REGISTER}.
-@item IBM6000_TARGET
-@findex IBM6000_TARGET
-Shows that we are configured for an IBM RS/6000 target. This
+@item DEPRECATED_IBM6000_TARGET
+@findex DEPRECATED_IBM6000_TARGET
+Shows that we are configured for an IBM RS/6000 system. This
conditional should be eliminated (FIXME) and replaced by
feature-specific macros. It was introduced in a haste and we are
repenting at leisure.
the stack frame of the function already has been destroyed up to the
final `return from function call' instruction.
-@item SIGTRAMP_START (@var{pc})
-@findex SIGTRAMP_START
-@itemx SIGTRAMP_END (@var{pc})
-@findex SIGTRAMP_END
+@item DEPRECATED_SIGTRAMP_START (@var{pc})
+@findex DEPRECATED_SIGTRAMP_START
+@itemx DEPRECATED_SIGTRAMP_END (@var{pc})
+@findex DEPRECATED_SIGTRAMP_END
Define these to be the start and end address of the @code{sigtramp} for the
given @var{pc}. On machines where the address is just a compile time
constant, the macro expansion will typically just ignore the supplied
@xref{Target Architecture Definition, , Pointers Are Not Always
Addresses}.
-@item NEED_TEXT_START_END
-@findex NEED_TEXT_START_END
-Define this if @value{GDBN} should determine the start and end addresses of the
-text section. (Seems dubious.)
-
@item NO_HIF_SUPPORT
@findex NO_HIF_SUPPORT
(Specific to the a29k.)
@var{type}.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
-@item REGISTER_RAW_SIZE (@var{reg})
-@findex REGISTER_RAW_SIZE
+@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_RAW_SIZE
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}.
Any register with a valid name.
@end table
-@item REGISTER_VIRTUAL_SIZE (@var{reg})
-@findex REGISTER_VIRTUAL_SIZE
+@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_VIRTUAL_SIZE
Return the virtual size of @var{reg}; defaults to the size of the
register's virtual type.
Return the virtual size of @var{reg}.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
-@item REGISTER_VIRTUAL_TYPE (@var{reg})
+@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})
@findex REGISTER_VIRTUAL_TYPE
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
+superseeds @code{DEPRECATED_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})
form.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
-@item RETURN_VALUE_ON_STACK(@var{type})
-@findex RETURN_VALUE_ON_STACK
-@cindex returning structures by value
-@cindex structures, returning by value
-
-Return non-zero if values of type TYPE are returned on the stack, using
-the ``struct convention'' (i.e., the caller provides a pointer to a
-buffer in which the callee should store the return value). This
-controls how the @samp{finish} command finds a function's return value,
-and whether an inferior function call reserves space on the stack for
-the return value.
-
-The full logic @value{GDBN} uses here is kind of odd.
-
-@itemize @bullet
-@item
-If the type being returned by value is not a structure, union, or array,
-and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
-concludes the value is not returned using the struct convention.
-
-@item
-Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
-If that returns non-zero, @value{GDBN} assumes the struct convention is
-in use.
-@end itemize
-
-In other words, to indicate that a given type is returned by value using
-the struct convention, that type must be either a struct, union, array,
-or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
-that @code{USE_STRUCT_CONVENTION} likes.
-
-Note that, in C and C@t{++}, arrays are never returned by value. In those
-languages, these predicates will always see a pointer type, never an
-array type. All the references above to arrays being returned by value
-apply only to other languages.
+@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size})
+@findex regset_from_core_section
+Return the appropriate register set for a core file section with name
+@var{sect_name} and size @var{sect_size}.
@item SOFTWARE_SINGLE_STEP_P()
@findex SOFTWARE_SINGLE_STEP_P
them.
@end itemize
-@item PCC_SOL_BROKEN
-@findex PCC_SOL_BROKEN
-(Used only in the Convex target.)
-
-@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
-@findex PC_IN_SIGTRAMP
-@cindex sigtramp
-The @dfn{sigtramp} is a routine that the kernel calls (which then calls
-the signal handler). On most machines it is a library routine that is
-linked into the executable.
-
-This function, given a program counter value in @var{pc} and the
-(possibly NULL) name of the function in which that @var{pc} resides,
-returns nonzero if the @var{pc} and/or @var{name} show that we are in
-sigtramp.
-
@item PC_LOAD_SEGMENT
@findex PC_LOAD_SEGMENT
If defined, print information about the load segment for the program
This should only need to be defined if @code{TARGET_READ_PC} and
@code{TARGET_WRITE_PC} are not defined.
-@item NPC_REGNUM
-@findex NPC_REGNUM
-The number of the ``next program counter'' register, if defined.
-
@item PARM_BOUNDARY
@findex PARM_BOUNDARY
If non-zero, round arguments to a boundary of this many bits before
pushing them on the stack.
+@item stabs_argument_has_addr (@var{gdbarch}, @var{type})
+@findex stabs_argument_has_addr
+@findex DEPRECATED_REG_STRUCT_HAS_ADDR
+@anchor{stabs_argument_has_addr} Define this to return nonzero if a
+function argument of type @var{type} is passed by reference instead of
+value.
+
+This method replaces @code{DEPRECATED_REG_STRUCT_HAS_ADDR}
+(@pxref{DEPRECATED_REG_STRUCT_HAS_ADDR}).
+
@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{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@item push_dummy_call (@var{gdbarch}, @var{function}, @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
@var{nargs}, the code should push @var{struct_addr} (when
@var{struct_return}), and the return address (@var{bp_addr}).
+@var{function} is a pointer to a @code{struct value}; on architectures that use
+function descriptors, this contains the function descriptor value.
+
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.
(@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 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.
+This method replaces @code{CALL_DUMMY_LOCATION},
+@code{DEPRECATED_REGISTER_SIZE}.
@item REGISTER_NAME(@var{i})
@findex REGISTER_NAME
Return the name of register @var{i} as a string. May return @code{NULL}
or @code{NUL} to indicate that register @var{i} is not valid.
-@item REGISTER_NAMES
-@findex REGISTER_NAMES
-Deprecated in favor of @code{REGISTER_NAME}.
+@item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
+@findex DEPRECATED_REG_STRUCT_HAS_ADDR
+@anchor{DEPRECATED_REG_STRUCT_HAS_ADDR}Define this to return 1 if the
+given type will be passed by pointer rather than directly.
-@item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
-@findex REG_STRUCT_HAS_ADDR
-Define this to return 1 if the given type will be passed by pointer
-rather than directly.
+This method has been replaced by @code{stabs_argument_has_addr}
+(@pxref{stabs_argument_has_addr}).
@item SAVE_DUMMY_FRAME_TOS (@var{sp})
@findex SAVE_DUMMY_FRAME_TOS
Define this to convert sdb register numbers into @value{GDBN} regnums. If not
defined, no conversion will be done.
+@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf})
+@findex gdbarch_return_value
+@anchor{gdbarch_return_value} Given a function with a return-value of
+type @var{rettype}, return which return-value convention that function
+would use.
+
+@value{GDBN} currently recognizes two function return-value conventions:
+@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found
+in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return
+value is found in memory and the address of that memory location is
+passed in as the function's first parameter.
+
+If the register convention is being used, and @var{writebuf} is
+non-@code{NULL}, also copy the return-value in @var{writebuf} into
+@var{regcache}.
+
+If the register convention is being used, and @var{readbuf} is
+non-@code{NULL}, also copy the return value from @var{regcache} into
+@var{readbuf} (@var{regcache} contains a copy of the registers from the
+just returned function).
+
+@xref{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}, for a description of how
+return-values that use the struct convention are handled.
+
+@emph{Maintainer note: This method replaces separate predicate, extract,
+store methods. By having only one method, the logic needed to determine
+the return-value convention need only be implemented in one place. If
+@value{GDBN} were written in an @sc{oo} language, this method would
+instead return an object that knew how to perform the register
+return-value extract and store.}
+
+@emph{Maintainer note: This method does not take a @var{gcc_p}
+parameter, and such a parameter should not be added. If an architecture
+that requires per-compiler or per-function information be identified,
+then the replacement of @var{rettype} with @code{struct value}
+@var{function} should be persued.}
+
+@emph{Maintainer note: The @var{regcache} parameter limits this methods
+to the inner most frame. While replacing @var{regcache} with a
+@code{struct frame_info} @var{frame} parameter would remove that
+limitation there has yet to be a demonstrated need for such a change.}
+
@item SKIP_PERMANENT_BREAKPOINT
@findex SKIP_PERMANENT_BREAKPOINT
Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
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.
@var{valbuf}, into the @var{regcache}. @var{type} is the type of the
value that is to be returned.
-@item SUN_FIXED_LBRAC_BUG
-@findex SUN_FIXED_LBRAC_BUG
-(Used only for Sun-3 and Sun-4 targets.)
+This method has been deprecated in favour of @code{gdbarch_return_value}
+(@pxref{gdbarch_return_value}).
@item SYMBOL_RELOADING_DEFAULT
@findex SYMBOL_RELOADING_DEFAULT
@findex TARGET_READ_PC
@itemx TARGET_WRITE_PC (@var{val}, @var{pid})
@findex TARGET_WRITE_PC
+@anchor{TARGET_WRITE_PC}
@itemx TARGET_READ_SP
@findex TARGET_READ_SP
@itemx TARGET_READ_FP
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
+@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
+@findex DEPRECATED_USE_STRUCT_CONVENTION
If defined, this must be an expression that is nonzero if a value of the
given @var{type} being returned from a function must have space
allocated for it on the stack. @var{gcc_p} is true if the function
for systems where GCC is known to use different calling convention than
other compilers.
+This method has been deprecated in favour of @code{gdbarch_return_value}
+(@pxref{gdbarch_return_value}).
+
@item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to})
@findex VALUE_TO_REGISTER
Convert a value of type @var{type} into the raw contents of register
undefined) in @file{nm-@var{system}.h}.
@table @code
-@item ATTACH_DETACH
-@findex ATTACH_DETACH
-If defined, then @value{GDBN} will include support for the @code{attach} and
-@code{detach} commands.
@item CHILD_PREPARE_TO_STORE
@findex CHILD_PREPARE_TO_STORE
@section mmalloc
@section libiberty
+@cindex @code{libiberty} library
+
+The @code{libiberty} library provides a set of functions and features
+that integrate and improve on functionality found in modern operating
+systems. Broadly speaking, such features can be divided into three
+groups: supplemental functions (functions that may be missing in some
+environments and operating systems), replacement functions (providing
+a uniform and easier to use interface for commonly used standard
+functions), and extensions (which provide additional functionality
+beyond standard functions).
+
+@value{GDBN} uses various features provided by the @code{libiberty}
+library, for instance the C@t{++} demangler, the @acronym{IEEE}
+floating format support functions, the input options parser
+@samp{getopt}, the @samp{obstack} extension, and other functions.
+
+@subsection @code{obstacks} in @value{GDBN}
+@cindex @code{obstacks}
+
+The obstack mechanism provides a convenient way to allocate and free
+chunks of memory. Each obstack is a pool of memory that is managed
+like a stack. Objects (of any nature, size and alignment) are
+allocated and freed in a @acronym{LIFO} fashion on an obstack (see
+@code{libiberty}'s documenatation for a more detailed explanation of
+@code{obstacks}).
+
+The most noticeable use of the @code{obstacks} in @value{GDBN} is in
+object files. There is an obstack associated with each internal
+representation of an object file. Lots of things get allocated on
+these @code{obstacks}: dictionary entries, blocks, blockvectors,
+symbols, minimal symbols, types, vectors of fundamental types, class
+fields of types, object files section lists, object files section
+offets lists, line tables, symbol tables, partial symbol tables,
+string tables, symbol table private data, macros tables, debug
+information sections and entries, import and export lists (som),
+unwind information (hppa), dwarf2 location expressions data. Plus
+various strings such as directory names strings, debug format strings,
+names of types.
+
+An essential and convenient property of all data on @code{obstacks} is
+that memory for it gets allocated (with @code{obstack_alloc}) at
+various times during a debugging sesssion, but it is released all at
+once using the @code{obstack_free} function. The @code{obstack_free}
+function takes a pointer to where in the stack it must start the
+deletion from (much like the cleanup chains have a pointer to where to
+start the cleanups). Because of the stack like structure of the
+@code{obstacks}, this allows to free only a top portion of the
+obstack. There are a few instances in @value{GDBN} where such thing
+happens. Calls to @code{obstack_free} are done after some local data
+is allocated to the obstack. Only the local data is deleted from the
+obstack. Of course this assumes that nothing between the
+@code{obstack_alloc} and the @code{obstack_free} allocates anything
+else on the same obstack. For this reason it is best and safest to
+use temporary @code{obstacks}.
+
+Releasing the whole obstack is also not safe per se. It is safe only
+under the condition that we know the @code{obstacks} memory is no
+longer needed. In @value{GDBN} we get rid of the @code{obstacks} only
+when we get rid of the whole objfile(s), for instance upon reading a
+new symbol file.
@section gnu-regex
@cindex regular expressions library
@cindex multi-arch data
@cindex data-pointer, per-architecture/per-module
-The multi-arch framework includes a mechanism for adding module specific
-per-architecture data-pointers to the @code{struct gdbarch} architecture
-object.
+The multi-arch framework includes a mechanism for adding module
+specific per-architecture data-pointers to the @code{struct gdbarch}
+architecture object.
-A module registers one or more per-architecture data-pointers using the
-function @code{register_gdbarch_data}:
+A module registers one or more per-architecture data-pointers using:
-@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init})
+@var{pre_init} is used to, on-demand, allocate an initial value for a
+per-architecture data-pointer using the architecture's obstack (passed
+in as a parameter). Since @var{pre_init} can be called during
+architecture creation, it is not parameterized with the architecture.
+and must not call modules that use per-architecture data.
+@end deftypefun
-The @var{init} function is used to obtain an initial value for a
-per-architecture data-pointer. The function is called, after the
-architecture has been created, when the data-pointer is still
-uninitialized (@code{NULL}) and its value has been requested via a call
-to @code{gdbarch_data}. A data-pointer can also be initialize
-explicitly using @code{set_gdbarch_data}.
+@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init})
+@var{post_init} is used to obtain an initial value for a
+per-architecture data-pointer @emph{after}. Since @var{post_init} is
+always called after architecture creation, it both receives the fully
+initialized architecture and is free to call modules that use
+per-architecture data (care needs to be taken to ensure that those
+other modules do not try to call back to this module as that will
+create in cycles in the initialization call graph).
+@end deftypefun
-The @var{free} function is called when a data-pointer needs to be
-destroyed. This occurs when either the corresponding @code{struct
-gdbarch} object is being destroyed or when @code{set_gdbarch_data} is
-overriding a non-@code{NULL} data-pointer value.
+These functions return a @code{struct gdbarch_data} that is used to
+identify the per-architecture data-pointer added for that module.
-The function @code{register_gdbarch_data} returns a @code{struct
-gdbarch_data} that is used to identify the data-pointer that was added
-to the module.
+The per-architecture data-pointer is accessed using the function:
+@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
+Given the architecture @var{arch} and module data handle
+@var{data_handle} (returned by @code{gdbarch_data_register_pre_init}
+or @code{gdbarch_data_register_post_init}), this function returns the
+current value of the per-architecture data-pointer. If the data
+pointer is @code{NULL}, it is first initialized by calling the
+corresponding @var{pre_init} or @var{post_init} method.
@end deftypefun
-A typical module has @code{init} and @code{free} functions of the form:
+The examples below assume the following definitions:
@smallexample
+struct nozel @{ int total; @};
static struct gdbarch_data *nozel_handle;
-static void *
-nozel_init (struct gdbarch *gdbarch)
-@{
- struct nozel *data = XMALLOC (struct nozel);
- @dots{}
- return data;
-@}
-@dots{}
-static void
-nozel_free (struct gdbarch *gdbarch, void *data)
-@{
- xfree (data);
-@}
@end smallexample
-Since uninitialized (@code{NULL}) data-pointers are initialized
-on-demand, an @code{init} function is free to call other modules that
-use data-pointers. Those modules data-pointers will be initialized as
-needed. Care should be taken to ensure that the @code{init} call graph
-does not contain cycles.
+A module can extend the architecture vector, adding additional
+per-architecture data, using the @var{pre_init} method. The module's
+per-architecture data is then initialized during architecture
+creation.
-The data-pointer is registered with the call:
+In the below, the module's per-architecture @emph{nozel} is added. An
+architecture can specify its nozel by calling @code{set_gdbarch_nozel}
+from @code{gdbarch_init}.
@smallexample
-void
-_initialize_nozel (void)
+static void *
+nozel_pre_init (struct obstack *obstack)
@{
- nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
-@dots{}
+ struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
+ return data;
+@}
@end smallexample
-The per-architecture data-pointer is accessed using the function:
-
-@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
-Given the architecture @var{arch} and module data handle
-@var{data_handle} (returned by @code{register_gdbarch_data}, this
-function returns the current value of the per-architecture data-pointer.
-@end deftypefun
-
-The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should
-be saved in a local variable and then used directly:
-
@smallexample
-int
-nozel_total (struct gdbarch *gdbarch)
+extern void
+set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
@{
- int total;
struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
- @dots{}
- return total;
+ data->total = nozel;
@}
@end smallexample
-It is also possible to directly initialize the data-pointer using:
+A module can on-demand create architecture dependant data structures
+using @code{post_init}.
-@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
-Update the data-pointer corresponding to @var{handle} with the value of
-@var{pointer}. If the previous data-pointer value is non-NULL, then it
-is freed using data-pointers @var{free} function.
-@end deftypefun
-
-This function is used by modules that require a mechanism for explicitly
-setting the per-architecture data-pointer during architecture creation:
+In the below, the nozel's total is computed on-demand by
+@code{nozel_post_init} using information obtained from the
+architecture.
@smallexample
-/* Called during architecture creation. */
-extern void
-set_gdbarch_nozel (struct gdbarch *gdbarch,
- int total)
-@{
- struct nozel *data = XMALLOC (struct nozel);
- @dots{}
- set_gdbarch_data (gdbarch, nozel_handle, nozel);
-@}
-@end smallexample
-
-@smallexample
-/* Default, called when nozel not set by set_gdbarch_nozel(). */
static void *
-nozel_init (struct gdbarch *gdbarch)
+nozel_post_init (struct gdbarch *gdbarch)
@{
- struct nozel *default_nozel = XMALLOC (struc nozel);
- @dots{}
- return default_nozel;
+ struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
+ nozel->total = gdbarch@dots{} (gdbarch);
+ return data;
@}
@end smallexample
@smallexample
-void
-_initialize_nozel (void)
+extern int
+nozel_total (struct gdbarch *gdbarch)
@{
- nozel_handle = register_gdbarch_data (nozel_init, NULL);
- @dots{}
+ struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+ return data->total;
+@}
@end smallexample
-@noindent
-Note that an @code{init} function still needs to be registered. It is
-used to initialize the data-pointer when the architecture creation phase
-fail to set an initial value.
-
-
@section Wrapping Output Lines
@cindex line wrap in output
restrict the memory being allocated to no more than a few kilobytes.}
@value{GDBN} uses the string function @code{xstrdup} and the print
-function @code{xasprintf}.
+function @code{xstrprintf}.
@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
functions such as @code{sprintf} are very prone to buffer overflow
@item -Wpointer-arith
@item -Wuninitialized
+
+@item -Wunused-label
+This warning has the additional benefit of detecting the absence of the
+@code{case} reserved word in a switch statement:
+@smallexample
+enum @{ FD_SCHEDULED, NOTHING_SCHEDULED @} sched;
+@dots{}
+switch (sched)
+ @{
+ case FD_SCHEDULED:
+ @dots{};
+ break;
+ NOTHING_SCHEDULED:
+ @dots{};
+ break;
+ @}
+@end smallexample
+
+@item -Wunused-function
@end table
@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
This is the base testsuite. The tests in it should apply to all
configurations of @value{GDBN} (but generic native-only tests may live here).
The test programs should be in the subset of C that is valid K&R,
-ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
+ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance
for prototypes).
@item gdb.@var{lang}
Language-specific tests for any language @var{lang} besides C. Examples are
-@file{gdb.c++} and @file{gdb.java}.
+@file{gdb.cp} and @file{gdb.java}.
@item gdb.@var{platform}
Non-portable tests. The tests are specific to a specific configuration
@end table
@include observer.texi
+@raisesections
@include fdl.texi
+@lowersections
@node Index
@unnumbered Index
projects / deliverable / binutils-gdb.git / blobdiff