\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
set correctly if compiling with GCC. This will almost never need to be
defined.
-@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
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
expectation, @value{GDBN} prints a warning when an adjusted breakpoint
is initially set and each time that that breakpoint is hit.
-@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 CALL_DUMMY_LOCATION
@findex CALL_DUMMY_LOCATION
See the file @file{inferior.h}.
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
@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
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
Return the appropriate register set for a core file section with name
@var{sect_name} and size @var{sect_size}.
-
-@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 SOFTWARE_SINGLE_STEP_P()
@findex SOFTWARE_SINGLE_STEP_P
Define this as 1 if the target does not have a hardware single-step
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
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
This method has been deprecated in favour of @code{gdbarch_return_value}
(@pxref{gdbarch_return_value}).
-@item SUN_FIXED_LBRAC_BUG
-@findex SUN_FIXED_LBRAC_BUG
-(Used only for Sun-3 and Sun-4 targets.)
-
@item SYMBOL_RELOADING_DEFAULT
@findex SYMBOL_RELOADING_DEFAULT
The default value of the ``symbol-reloading'' variable. (Never defined in
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
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
@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:
-
-@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:
+A module can on-demand create architecture dependant data structures
+using @code{post_init}.
-@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
+In the below, the nozel's total is computed on-demand by
+@code{nozel_post_init} using information obtained from the
+architecture.
@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
projects / deliverable / binutils-gdb.git / blobdiff