\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
* Support Libraries::
* Coding::
* Porting GDB::
+* Versions and Branches::
* Releasing GDB::
* Testsuite::
* Hints::
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
watched expression(s) after each instruction. The rest of this
section is mostly irrelevant for software watchpoints.
+When the inferior stops, @value{GDBN} tries to establish, among other
+possible reasons, whether it stopped due to a watchpoint being hit.
+For a data-write watchpoint, it does so by evaluating, for each
+watchpoint, the expression whose value is being watched, and testing
+whether the watched value has changed. For data-read and data-access
+watchpoints, @value{GDBN} needs the target to supply a primitive that
+returns the address of the data that was accessed or read (see the
+description of @code{target_stopped_data_address} below): if this
+primitive returns a valid address, @value{GDBN} infers that a
+watchpoint triggered if it watches an expression whose evaluation uses
+that address.
+
@value{GDBN} uses several macros and primitives to support hardware
watchpoints:
fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not
defined.
-@findex TARGET_DISABLE_HW_WATCHPOINTS
-@item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid})
-Disables watchpoints in the process identified by @var{pid}. This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
-
-@findex TARGET_ENABLE_HW_WATCHPOINTS
-@item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid})
-Enables watchpoints in the process identified by @var{pid}. This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
-
+@cindex insert or remove hardware watchpoint
@findex target_insert_watchpoint
@findex target_remove_watchpoint
@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
two macros can use them for their internal purposes.
@findex target_stopped_data_address
-@item target_stopped_data_address ()
-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.
+@item target_stopped_data_address (@var{addr_p})
+If the inferior has some watchpoint that triggered, place the address
+associated with the watchpoint at the location pointed to by
+@var{addr_p} and return non-zero. Otherwise, return zero. Note that
+this primitive is used by @value{GDBN} only on targets that support
+data-read or data-access type watchpoints, so targets that have
+support only for data-write watchpoints need not implement these
+primitives.
@findex HAVE_STEPPABLE_WATCHPOINT
@item HAVE_STEPPABLE_WATCHPOINT
@item STOPPED_BY_WATCHPOINT (@var{wait_status})
Return non-zero if stopped by a watchpoint. @var{wait_status} is of
the type @code{struct target_waitstatus}, defined by @file{target.h}.
+Normally, this macro is defined to invoke the function pointed to by
+the @code{to_stopped_by_watchpoint} member of the structure (of the
+type @code{target_ops}, defined on @file{target.h}) that describes the
+target-specific operations; @code{to_stopped_by_watchpoint} ignores
+the @var{wait_status} argument.
+
+@value{GDBN} does not require the non-zero value returned by
+@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot
+determine for sure whether the inferior stopped due to a watchpoint,
+it could return non-zero ``just in case''.
@end table
@subsection x86 Watchpoints
processors.
@findex i386_stopped_data_address
-@item i386_stopped_data_address (void)
-The macros @code{STOPPED_BY_WATCHPOINT} and
-@code{target_stopped_data_address} are set to call this function. The
-argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
+@item i386_stopped_data_address (@var{addr_p})
+The target function
+@code{target_stopped_data_address} is set to call this function.
+This
function examines the breakpoint condition bits in the DR6 Debug
Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
macro, and returns the address associated with the first bit that is
set in DR6.
+@findex i386_stopped_by_watchpoint
+@item i386_stopped_by_watchpoint (void)
+The macro @code{STOPPED_BY_WATCHPOINT}
+is set to call this function. The
+argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
+function examines the breakpoint condition bits in the DR6 Debug
+Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
+macro, and returns true if any bit is set. Otherwise, false is
+returned.
+
@findex i386_insert_watchpoint
@findex i386_remove_watchpoint
@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
@item i386_stopped_by_hwbp (void)
This function returns non-zero if the inferior has some watchpoint or
hardware breakpoint that triggered. It works like
-@code{i386_stopped_data_address}, except that it doesn't return the
+@code{i386_stopped_data_address}, except that it doesn't record the
address whose watchpoint triggered.
@findex i386_cleanup_dregs
@smallexample
annotate_field (4);
printf_filtered ("%s ",
- local_hex_string_custom ((unsigned long) b->address, "08l"));
+ hex_string_custom ((unsigned long) b->address, 8));
@end smallexample
It became:
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}
@item NO_STD_REGS
This macro is deprecated.
-@item NO_SYS_FILE
-Define this if your system does not have a @code{<sys/file.h>}.
-
@item SIGWINCH_HANDLER
If your host defines @code{SIGWINCH}, you can define this to be the name
of a function to be called if @code{SIGWINCH} is received.
@cindex terminal device
The name of the generic TTY device, defaults to @code{"/dev/tty"}.
-@item FCLOSE_PROVIDED
-Define this if the system declares @code{fclose} in the headers included
-in @code{defs.h}. This isn't needed unless your compiler is unusually
-anal.
-
@item FOPEN_RB
Define this if binary files are opened the same way as text files.
-@item GETENV_PROVIDED
-Define this if the system declares @code{getenv} in its headers included
-in @code{defs.h}. This isn't needed unless your compiler is unusually
-anal.
-
@item HAVE_MMAP
@findex mmap
In some cases, use the system call @code{mmap} for reading symbol
@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
This is the signal for stopping @value{GDBN}. Defaults to
@code{SIGTSTP}. (Only redefined for the Convex.)
-@item USE_O_NOCTTY
-Define this if the interior's tty should be opened with the @code{O_NOCTTY}
-flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
-always linked in.)
-
@item USG
Means that System V (prior to SVR4) include files are in use. (FIXME:
This symbol is abused in @file{infrun.c}, @file{regex.c}, and
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
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
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{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
-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.
-
-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}.
-
-@item CALL_DUMMY
-@findex CALL_DUMMY
-A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated.
+@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
See the file @file{inferior.h}.
-@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.
+This method has been replaced by @code{push_dummy_code}
+(@pxref{push_dummy_code}).
@item CANNOT_FETCH_REGISTER (@var{regno})
@findex CANNOT_FETCH_REGISTER
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 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
+@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 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
@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 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 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
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{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 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}).
+
+@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 DEPRECATED_PUSH_DUMMY_FRAME
-@findex DEPRECATED_PUSH_DUMMY_FRAME
-Used in @samp{call_function_by_hand} to create an artificial stack frame.
+@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
+@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.
-@item REGISTER_BYTES
-@findex REGISTER_BYTES
-The total amount of space needed to store @value{GDBN}'s copy of the machine's
-register state.
+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{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
@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.
@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_WRITE_SP
-@findex TARGET_WRITE_SP
@itemx TARGET_READ_FP
@findex TARGET_READ_FP
@findex read_pc
@findex write_pc
@findex read_sp
-@findex write_sp
@findex read_fp
-These change the behavior of @code{read_pc}, @code{write_pc},
-@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets,
-these may be left undefined. @value{GDBN} will call the read and write
-register functions with the relevant @code{_REGNUM} argument.
+@anchor{TARGET_READ_SP} These change the behavior of @code{read_pc},
+@code{write_pc}, and @code{read_sp}. 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
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
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
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
@file{infptrace.c} is included in this configuration, the default
routines in @file{infptrace.c} are used for these functions.
-@item FILES_INFO_HOOK
-@findex FILES_INFO_HOOK
-(Only defined for Convex.)
-
@item FP0_REGNUM
@findex FP0_REGNUM
This macro is normally defined to be the number of the first floating
addresses in the upage, that are obtained via ptrace or from core files.
On systems that don't need this value, set it to zero.
-@item KERNEL_U_ADDR_BSD
-@findex KERNEL_U_ADDR_BSD
-Define this to cause @value{GDBN} to determine the address of @code{u} at
-runtime, by using Berkeley-style @code{nlist} on the kernel's image in
-the root directory.
-
@item KERNEL_U_ADDR_HPUX
@findex KERNEL_U_ADDR_HPUX
Define this to cause @value{GDBN} to determine the address of @code{u} at
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
defined in @file{nm.h} @emph{only} in order to override the default
definition in @file{procfs.c}.
-@item PTRACE_FP_BUG
-@findex PTRACE_FP_BUG
-See @file{mach386-xdep.c}.
-
@item PTRACE_ARG3_TYPE
@findex PTRACE_ARG3_TYPE
The type of the third argument to the @code{ptrace} system call, if it
number of traps is something other than 2, then define this macro to
expand into the number expected.
-@item SVR4_SHARED_LIBS
-@findex SVR4_SHARED_LIBS
-Define this to indicate that SVR4-style shared libraries are in use.
-
@item USE_PROC_FS
@findex USE_PROC_FS
This determines whether small routines in @file{*-tdep.c}, which
@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 -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
@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
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.
configuration.
@end itemize
-@node Releasing GDB
-
-@chapter Releasing @value{GDBN}
-@cindex making a new release of gdb
+@node Versions and Branches
+@chapter Versions and Branches
-@section Versions and Branches
+@section Versions
-@subsection Version Identifiers
+@value{GDBN}'s version is determined by the file
+@file{gdb/version.in} and takes one of the following forms:
-@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
+@table @asis
+@item @var{major}.@var{minor}
+@itemx @var{major}.@var{minor}.@var{patchlevel}
+an official release (e.g., 6.2 or 6.2.1)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}
+a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g.,
+6.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs
+a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g.,
+6.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor})
+a vendor specific release of @value{GDBN}, that while based on@*
+@var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD},
+may include additional changes
+@end table
-@value{GDBN}'s mainline uses ISO dates to differentiate between
-versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs
-while the corresponding snapshot uses @var{YYYYMMDD}.
+@value{GDBN}'s mainline uses the @var{major} and @var{minor} version
+numbers from the most recent release branch, with a @var{patchlevel}
+of 50. At the time each new release branch is created, the mainline's
+@var{major} and @var{minor} version numbers are updated.
-@value{GDBN}'s release branch uses a slightly more complicated scheme.
-When the branch is first cut, the mainline version identifier is
-prefixed with the @var{major}.@var{minor} from of the previous release
-series but with .90 appended. As draft releases are drawn from the
-branch, the minor minor number (.90) is incremented. Once the first
-release (@var{M}.@var{N}) has been made, the version prefix is updated
-to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have
-an incremented minor minor version number (.0).
+@value{GDBN}'s release branch is similar. When the branch is cut, the
+@var{patchlevel} is changed from 50 to 90. As draft releases are
+drawn from the branch, the @var{patchlevel} is incremented. Once the
+first release (@var{major}.@var{minor}) has been made, the
+@var{patchlevel} is set to 0 and updates have an incremented
+@var{patchlevel}.
-Using 5.1 (previous) and 5.2 (current), the example below illustrates a
-typical sequence of version identifiers:
+For snapshots, and @sc{cvs} check outs, it is also possible to
+identify the @sc{cvs} origin:
@table @asis
-@item 5.1.1
-final release from previous branch
-@item 2002-03-03-cvs
-main-line the day the branch is cut
-@item 5.1.90-2002-03-03-cvs
-corresponding branch version
-@item 5.1.91
-first draft release candidate
-@item 5.1.91-2002-03-17-cvs
-updated branch version
-@item 5.1.92
-second draft release candidate
-@item 5.1.92-2002-03-31-cvs
-updated branch version
-@item 5.1.93
-final release candidate (see below)
-@item 5.2
-official release
-@item 5.2.0.90-2002-04-07-cvs
-updated CVS branch version
-@item 5.2.1
-second official release
+@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD}
+drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302)
+@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD}
+@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{}
+drawn from a release branch prior to the release (e.g.,
+6.1.90.20020304)
+@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD}
+@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{}
+drawn from a release branch after the release (e.g., 6.2.0.20020308)
@end table
-Notes:
+If the previous @value{GDBN} version is 6.1 and the current version is
+6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},
+here's an illustration of a typical sequence:
-@itemize @bullet
-@item
-Minor minor minor draft release candidates such as 5.2.0.91 have been
-omitted from the example. Such release candidates are, typically, never
-made.
-@item
-For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the
-official @file{gdb-5.2.tar} renamed and compressed.
-@end itemize
+@smallexample
+ <HEAD>
+ |
+6.1.50.20020302-cvs
+ |
+ +--------------------------.
+ | <gdb_6_2-branch>
+ | |
+6.2.50.20020303-cvs 6.1.90 (draft #1)
+ | |
+6.2.50.20020304-cvs 6.1.90.20020304-cvs
+ | |
+6.2.50.20020305-cvs 6.1.91 (draft #2)
+ | |
+6.2.50.20020306-cvs 6.1.91.20020306-cvs
+ | |
+6.2.50.20020307-cvs 6.2 (release)
+ | |
+6.2.50.20020308-cvs 6.2.0.20020308-cvs
+ | |
+6.2.50.20020309-cvs 6.2.1 (update)
+ | |
+6.2.50.20020310-cvs <branch closed>
+ |
+6.2.50.20020311-cvs
+ |
+ +--------------------------.
+ | <gdb_6_3-branch>
+ | |
+6.3.50.20020312-cvs 6.2.90 (draft #1)
+ | |
+@end smallexample
+
+@section Release Branches
+@cindex Release Branches
+
+@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a
+single release branch, and identifies that branch using the @sc{cvs}
+branch tags:
+
+@smallexample
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint
+gdb_@var{major}_@var{minor}-branch
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release
+@end smallexample
+
+@emph{Pragmatics: To help identify the date at which a branch or
+release is made, both the branchpoint and release tags include the
+date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The
+branch tag, denoting the head of the branch, does not need this.}
+
+@section Vendor Branches
+@cindex vendor branches
To avoid version conflicts, vendors are expected to modify the file
@file{gdb/version.in} to include a vendor unique alphabetic identifier
(an official @value{GDBN} release never uses alphabetic characters in
-its version identifer).
+its version identifer). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit
+Inc Patch 2)}.
-Since @value{GDBN} does not make minor minor minor releases (e.g.,
-5.1.0.1) the conflict between that and a minor minor draft release
-identifier (e.g., 5.1.0.90) is avoided.
+@section Experimental Branches
+@cindex experimental branches
+
+@subsection Guidelines
+
+@value{GDBN} permits the creation of branches, cut from the @sc{cvs}
+repository, for experimental development. Branches make it possible
+for developers to share preliminary work, and maintainers to examine
+significant new developments.
+
+The following are a set of guidelines for creating such branches:
+
+@table @emph
+@item a branch has an owner
+The owner can set further policy for a branch, but may not change the
+ground rules. In particular, they can set a policy for commits (be it
+adding more reviewers or deciding who can commit).
-@subsection Branches
+@item all commits are posted
+All changes committed to a branch shall also be posted to
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
+mailing list}. While commentary on such changes are encouraged, people
+should remember that the changes only apply to a branch.
-@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single
-release branch (gdb_5_2-branch). Since minor minor minor releases
-(5.1.0.1) are not made, the need to branch the release branch is avoided
-(it also turns out that the effort required for such a a branch and
-release is significantly greater than the effort needed to create a new
-release from the head of the release branch).
+@item all commits are covered by an assignment
+This ensures that all changes belong to the Free Software Foundation,
+and avoids the possibility that the branch may become contaminated.
-Releases 5.0 and 5.1 used branch and release tags of the form:
+@item a branch is focused
+A focused branch has a single objective or goal, and does not contain
+unnecessary or irrelevant changes. Cleanups, where identified, being
+be pushed into the mainline as soon as possible.
+@item a branch tracks mainline
+This keeps the level of divergence under control. It also keeps the
+pressure on developers to push cleanups and other stuff into the
+mainline.
+
+@item a branch shall contain the entire @value{GDBN} module
+The @value{GDBN} module @code{gdb} should be specified when creating a
+branch (branches of individual files should be avoided). @xref{Tags}.
+
+@item a branch shall be branded using @file{version.in}
+The file @file{gdb/version.in} shall be modified so that it identifies
+the branch @var{owner} and branch @var{name}, e.g.,
+@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}.
+
+@end table
+
+@subsection Tags
+@anchor{Tags}
+
+To simplify the identification of @value{GDBN} branches, the following
+branch tagging convention is strongly recommended:
+
+@table @code
+
+@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
+@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch
+The branch point and corresponding branch tag. @var{YYYYMMDD} is the
+date that the branch was created. A branch is created using the
+sequence: @anchor{experimental branch tags}
@smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-YYYY-MM-DD-branch
-gdb_M_N-YYYY-MM-DD-release
+cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb
+cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
+ @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb
@end smallexample
-Release 5.2 is trialing the branch and release tags:
-
+@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
+The tagged point, on the mainline, that was used when merging the branch
+on @var{yyyymmdd}. To merge in all changes since the branch was cut,
+use a command sequence like:
@smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-branch
-gdb_M_N-YYYY-MM-DD-release
+cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb
+cvs update \
+ -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
+ -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
@end smallexample
+@noindent
+Similar sequences can be used to just merge in changes since the last
+merge.
-@emph{Pragmatics: The branchpoint and release tags need to identify when
-a branch and release are made. The branch tag, denoting the head of the
-branch, does not have this criteria.}
+@end table
+@noindent
+For further information on @sc{cvs}, see
+@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
+
+@node Releasing GDB
+
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
@section Branch Commit Policy
in particular versions of compilers, and it's OK not to try to write
tests for all of those.
+DejaGNU supports separate build, host, and target machines. However,
+some @value{GDBN} test scripts do not work if the build machine and
+the host machine are not the same. In such an environment, these scripts
+will give a result of ``UNRESOLVED'', like this:
+
+@smallexample
+UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
+@end smallexample
+
@section Testsuite Organization
@cindex test suite organization
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