* Gdb-Internals: (gdbint). The GNU debugger's internals.
@end direntry
-@ifinfo
-This file documents the internals of the GNU debugger @value{GDBN}.
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
- 2002, 2003, 2004, 2005, 2006, 2008
- Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999,
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
+Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
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
+@end copying
+
+@ifnottex
+This file documents the internals of the GNU debugger @value{GDBN}.
+
+@insertcopying
+@end ifnottex
@setchapternewpage off
@settitle @value{GDBN} Internals
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,
- 2002, 2003, 2004, 2005, 2006 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 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''.
+@insertcopying
@end titlepage
@contents
* Algorithms::
* User Interface::
* libgdb::
+* Values::
* Stack Frames::
* Symbol Handling::
* Language Support::
@item
Add @file{i386-nat.o} to the value of the Make variable
-@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or
-@code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}).
+@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}).
@item
Provide implementations for the @code{I386_DR_LOW_*} macros described
builder. The result of the query is constructed using that builder
before the query function returns.
+@node Values
+@chapter Values
+@section Values
+
+@cindex values
+@cindex @code{value} structure
+@value{GDBN} uses @code{struct value}, or @dfn{values}, as an internal
+abstraction for the representation of a variety of inferior objects
+and @value{GDBN} convenience objects.
+
+Values have an associated @code{struct type}, that describes a virtual
+view of the raw data or object stored in or accessed through the
+value.
+
+A value is in addition discriminated by its lvalue-ness, given its
+@code{enum lval_type} enumeration type:
+
+@cindex @code{lval_type} enumeration, for values.
+@table @code
+@item @code{not_lval}
+This value is not an lval. It can't be assigned to.
+
+@item @code{lval_memory}
+This value represents an object in memory.
+
+@item @code{lval_register}
+This value represents an object that lives in a register.
+
+@item @code{lval_internalvar}
+Represents the value of an internal variable.
+
+@item @code{lval_internalvar_component}
+Represents part of a @value{GDBN} internal variable. E.g., a
+structure field.
+
+@cindex computed values
+@item @code{lval_computed}
+These are ``computed'' values. They allow creating specialized value
+objects for specific purposes, all abstracted away from the core value
+support code. The creator of such a value writes specialized
+functions to handle the reading and writing to/from the value's
+backend data, and optionally, a ``copy operator'' and a
+``destructor''.
+
+Pointers to these functions are stored in a @code{struct lval_funcs}
+instance (declared in @file{value.h}), and passed to the
+@code{allocate_computed_value} function, as in the example below.
+
+@smallexample
+static void
+nil_value_read (struct value *v)
+@{
+ /* This callback reads data from some backend, and stores it in V.
+ In this case, we always read null data. You'll want to fill in
+ something more interesting. */
+
+ memset (value_contents_all_raw (v),
+ value_offset (v),
+ TYPE_LENGTH (value_type (v)));
+@}
+
+static void
+nil_value_write (struct value *v, struct value *fromval)
+@{
+ /* Takes the data from FROMVAL and stores it in the backend of V. */
+
+ to_oblivion (value_contents_all_raw (fromval),
+ value_offset (v),
+ TYPE_LENGTH (value_type (fromval)));
+@}
+
+static struct lval_funcs nil_value_funcs =
+ @{
+ nil_value_read,
+ nil_value_write
+ @};
+
+struct value *
+make_nil_value (void)
+@{
+ struct type *type;
+ struct value *v;
+
+ type = make_nils_type ();
+ v = allocate_computed_value (type, &nil_value_funcs, NULL);
+
+ return v;
+@}
+@end smallexample
+
+See the implementation of the @code{$_siginfo} convenience variable in
+@file{infrun.c} as a real example use of lval_computed.
+
+@end table
+
@node Stack Frames
@chapter Stack Frames
Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
@code{parse_exp_1} (defined in @file{parse.c}).
-@item Use macros to trim code
-
-@cindex trimming language-dependent code
-The user has the option of building @value{GDBN} for some or all of the
-languages. If the user decides to build @value{GDBN} for the language
-@var{lang}, then every file dependent on @file{language.h} will have the
-macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
-leave out large routines that the user won't need if he or she is not
-using your language.
-
-Note that you do not need to do this in your YACC parser, since if @value{GDBN}
-is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
-compiled form of your parser) is not linked into @value{GDBN} at all.
-
-See the file @file{configure.in} for how @value{GDBN} is configured
-for different languages.
-
@item Edit @file{Makefile.in}
Add dependencies in @file{Makefile.in}. Make sure you update the macro
@findex gdbarch_breakpoint_from_pc
@anchor{gdbarch_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
+a static 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.
+breakpoint should be inserted. May return @code{NULL} to indicate that
+software breakpoints are not supported.
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
instruction. The breakpoint must be no longer than the shortest
instruction of the architecture.
+Provided breakpoint bytes can be also used by @code{bp_loc_is_permanent} to
+detect permanent breakpoints. @code{gdbarch_breakpoint_from_pc} should return
+an unchanged memory copy if it was called for a location with permanent
+breakpoint as some architectures use breakpoint instructions containing
+arbitrary parameter value.
+
Replaces all the other @var{BREAKPOINT} macros.
@item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt})
@item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum})
@findex gdbarch_cannot_fetch_register
This function should return nonzero if @var{regno} cannot be fetched
-from an inferior process. This is only relevant if
-@code{FETCH_INFERIOR_REGISTERS} is not defined.
+from an inferior process.
@item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum})
@findex gdbarch_cannot_store_register
@var{type} in a non-standard form.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@item int gdbarch_fp0_regnum (@var{gdbarch})
+@findex gdbarch_fp0_regnum
+This function returns the number of the first floating point register,
+if the machine has such registers. Otherwise, it returns -1.
+
@item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch})
@findex gdbarch_decr_pc_after_break
This function shall return the amount by which to decrement the PC after the
The following files add a target to @value{GDBN}:
@table @file
-@vindex TDEPFILES
-@item gdb/config/@var{arch}/@var{ttt}.mt
-Contains a Makefile fragment specific to this target. Specifies what
-object files are needed for target @var{ttt}, by defining
-@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}.
-
-You can also define @samp{TM_CLIBS} and @samp{TM_CDEPS}, but these are
-now deprecated, replaced by autoconf, and may go away in future
-versions of @value{GDBN}.
+@cindex target dependent files
@item gdb/@var{ttt}-tdep.c
Contains any miscellaneous code required for this target machine. On
Also specifies the header file which describes native support on
@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
-@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+@samp{NAT_CDEPS}, @samp{NAT_GENERATED_FILES}, etc.; see @file{Makefile.in}.
@emph{Maintainer's note: The @file{.mh} suffix is because this file
originally contained @file{Makefile} fragments for hosting @value{GDBN}
@table @code
-@item CHILD_PREPARE_TO_STORE
-@findex CHILD_PREPARE_TO_STORE
-If the machine stores all registers at once in the child process, then
-define this to ensure that all values are correct. This usually entails
-a read from the child.
-
-[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
-currently.]
-
-@item FETCH_INFERIOR_REGISTERS
-@findex FETCH_INFERIOR_REGISTERS
-Define this if the native-dependent code will provide its own routines
-@code{fetch_inferior_registers} and @code{store_inferior_registers} in
-@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
-@file{infptrace.c} is included in this configuration, the default
-routines in @file{infptrace.c} are used for these functions.
-
-@item int gdbarch_fp0_regnum (@var{gdbarch})
-@findex gdbarch_fp0_regnum
-This functions normally returns the number of the first floating
-point register, if the machine has such registers. As such, it would
-appear only in target-specific code. However, @file{/proc} support uses this
-to decide whether floats are in use on this target.
-
-@item int gdbarch_get_longjmp_target (@var{gdbarch})
-@findex gdbarch_get_longjmp_target
-This function determines the target PC address that @code{longjmp} will jump to,
-assuming that we have just stopped at a longjmp breakpoint. It takes a
-@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 I386_USE_GENERIC_WATCHPOINTS
An x86-based machine can define this to use the generic x86 watchpoint
support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
-@item ONE_PROCESS_WRITETEXT
-@findex ONE_PROCESS_WRITETEXT
-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 PROC_NAME_FMT
@findex PROC_NAME_FMT
Defines the format for the name of a @file{/proc} device. Should be
left-margin: 8
fill-column: 74
version-control: never
+coding: utf-8
End:
@end smallexample
@item
Update the copyright year in the startup message
-Update the copyright year in file @file{top.c}, function
-@code{print_gdb_version}.
+Update the copyright year in:
+@itemize @bullet
+@item file @file{top.c}, function @code{print_gdb_version}
+@item file @file{gdbserver/server.c}, function @code{gdbserver_version}
+@item file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version}
+@end itemize
@item
Add the new year in the copyright notices of all source and documentation
projects / deliverable / binutils-gdb.git / blobdiff