\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 (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
+ 2002, 2003, 2004, 2005, 2006
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, 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 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::
+* Start of New Year Procedure::
* Releasing GDB::
* Testsuite::
* Hints::
When you want to make @value{GDBN} work ``native'' on a particular machine, you
have to include all three kinds of information.
+@section Source Tree Structure
+@cindex @value{GDBN} source tree structure
+
+The @value{GDBN} source directory has a mostly flat structure---there
+are only a few subdirectories. A file's name usually gives a hint as
+to what it does; for example, @file{stabsread.c} reads stabs,
+@file{dwarfread.c} reads DWARF, etc.
+
+Files that are related to some common task have names that share
+common substrings. For example, @file{*-thread.c} files deal with
+debugging threads on various platforms; @file{*read.c} files deal with
+reading various kinds of symbol and object files; @file{inf*.c} files
+deal with direct control of the @dfn{inferior program} (@value{GDBN}
+parlance for the program being debugged).
+
+There are several dozens of files in the @file{*-tdep.c} family.
+@samp{tdep} stands for @dfn{target-dependent code}---each of these
+files implements debug support for a specific target architecture
+(sparc, mips, etc). Usually, only one of these will be used in a
+specific @value{GDBN} configuration (sometimes two, closely related).
+
+Similarly, there are many @file{*-nat.c} files, each one for native
+debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for
+native debugging of Sparc machines running the Linux kernel).
+
+The few subdirectories of the source tree are:
+
+@table @file
+@item cli
+Code that implements @dfn{CLI}, the @value{GDBN} Command-Line
+Interpreter. @xref{User Interface, Command Interpreter}.
+
+@item gdbserver
+Code for the @value{GDBN} remote server.
+
+@item gdbtk
+Code for Insight, the @value{GDBN} TK-based GUI front-end.
+
+@item mi
+The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.
+
+@item signals
+Target signal translation code.
+
+@item tui
+Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User
+Interface. @xref{User Interface, TUI}.
+@end table
@node Algorithms
A frame is a construct that @value{GDBN} uses to keep track of calling
and called functions.
-@findex create_new_frame
-@vindex FRAME_FP
-@code{FRAME_FP} in the machine description has no meaning to the
-machine-independent part of @value{GDBN}, except that it is used when
-setting up a new frame from scratch, as follows:
+@cindex frame, unwind
+@value{GDBN}'s frame model, a fresh design, was implemented with the
+need to support @sc{dwarf}'s Call Frame Information in mind. In fact,
+the term ``unwind'' is taken directly from that specification.
+Developers wishing to learn more about unwinders, are encouraged to
+read the the @sc{dwarf} specification.
+
+@findex frame_register_unwind
+@findex get_frame_register
+@value{GDBN}'s model is that you find a frame's registers by
+``unwinding'' them from the next younger frame. That is,
+@samp{get_frame_register} which returns the value of a register in
+frame #1 (the next-to-youngest frame), is implemented by calling frame
+#0's @code{frame_register_unwind} (the youngest frame). But then the
+obvious question is: how do you access the registers of the youngest
+frame itself?
+
+@cindex sentinel frame
+@findex get_frame_type
+@vindex SENTINEL_FRAME
+To answer this question, GDB has the @dfn{sentinel} frame, the
+``-1st'' frame. Unwinding registers from the sentinel frame gives you
+the current values of the youngest real frame's registers. If @var{f}
+is a sentinel frame, then @code{get_frame_type (@var{f}) ==
+SENTINEL_FRAME}.
+
+@section Prologue Analysis
+
+@cindex prologue analysis
+@cindex call frame information
+@cindex CFI (call frame information)
+To produce a backtrace and allow the user to manipulate older frames'
+variables and arguments, @value{GDBN} needs to find the base addresses
+of older frames, and discover where those frames' registers have been
+saved. Since a frame's ``callee-saves'' registers get saved by
+younger frames if and when they're reused, a frame's registers may be
+scattered unpredictably across younger frames. This means that
+changing the value of a register-allocated variable in an older frame
+may actually entail writing to a save slot in some younger frame.
+
+Modern versions of GCC emit Dwarf call frame information (``CFI''),
+which describes how to find frame base addresses and saved registers.
+But CFI is not always available, so as a fallback @value{GDBN} uses a
+technique called @dfn{prologue analysis} to find frame sizes and saved
+registers. A prologue analyzer disassembles the function's machine
+code starting from its entry point, and looks for instructions that
+allocate frame space, save the stack pointer in a frame pointer
+register, save registers, and so on. Obviously, this can't be done
+accurately in general, but it's tractable to do well enough to be very
+helpful. Prologue analysis predates the GNU toolchain's support for
+CFI; at one time, prologue analysis was the only mechanism
+@value{GDBN} used for stack unwinding at all, when the function
+calling conventions didn't specify a fixed frame layout.
+
+In the olden days, function prologues were generated by hand-written,
+target-specific code in GCC, and treated as opaque and untouchable by
+optimizers. Looking at this code, it was usually straightforward to
+write a prologue analyzer for @value{GDBN} that would accurately
+understand all the prologues GCC would generate. However, over time
+GCC became more aggressive about instruction scheduling, and began to
+understand more about the semantics of the prologue instructions
+themselves; in response, @value{GDBN}'s analyzers became more complex
+and fragile. Keeping the prologue analyzers working as GCC (and the
+instruction sets themselves) evolved became a substantial task.
+
+@cindex @file{prologue-value.c}
+@cindex abstract interpretation of function prologues
+@cindex pseudo-evaluation of function prologues
+To try to address this problem, the code in @file{prologue-value.h}
+and @file{prologue-value.c} provides a general framework for writing
+prologue analyzers that are simpler and more robust than ad-hoc
+analyzers. When we analyze a prologue using the prologue-value
+framework, we're really doing ``abstract interpretation'' or
+``pseudo-evaluation'': running the function's code in simulation, but
+using conservative approximations of the values registers and memory
+would hold when the code actually runs. For example, if our function
+starts with the instruction:
+
+@example
+addi r1, 42 # add 42 to r1
+@end example
+@noindent
+we don't know exactly what value will be in @code{r1} after executing
+this instruction, but we do know it'll be 42 greater than its original
+value.
-@smallexample
-create_new_frame (read_register (DEPRECATED_FP_REGNUM), read_pc ()));
-@end smallexample
+If we then see an instruction like:
+
+@example
+addi r1, 22 # add 22 to r1
+@end example
+@noindent
+we still don't know what @code{r1's} value is, but again, we can say
+it is now 64 greater than its original value.
+
+If the next instruction were:
+
+@example
+mov r2, r1 # set r2 to r1's value
+@end example
+@noindent
+then we can say that @code{r2's} value is now the original value of
+@code{r1} plus 64.
+
+It's common for prologues to save registers on the stack, so we'll
+need to track the values of stack frame slots, as well as the
+registers. So after an instruction like this:
+
+@example
+mov (fp+4), r2
+@end example
+@noindent
+then we'd know that the stack slot four bytes above the frame pointer
+holds the original value of @code{r1} plus 64.
+
+And so on.
+
+Of course, this can only go so far before it gets unreasonable. If we
+wanted to be able to say anything about the value of @code{r1} after
+the instruction:
+
+@example
+xor r1, r3 # exclusive-or r1 and r3, place result in r1
+@end example
+@noindent
+then things would get pretty complex. But remember, we're just doing
+a conservative approximation; if exclusive-or instructions aren't
+relevant to prologues, we can just say @code{r1}'s value is now
+``unknown''. We can ignore things that are too complex, if that loss of
+information is acceptable for our application.
+
+So when we say ``conservative approximation'' here, what we mean is an
+approximation that is either accurate, or marked ``unknown'', but
+never inaccurate.
+
+Using this framework, a prologue analyzer is simply an interpreter for
+machine code, but one that uses conservative approximations for the
+contents of registers and memory instead of actual values. Starting
+from the function's entry point, you simulate instructions up to the
+current PC, or an instruction that you don't know how to simulate.
+Now you can examine the state of the registers and stack slots you've
+kept track of.
+
+@itemize @bullet
+
+@item
+To see how large your stack frame is, just check the value of the
+stack pointer register; if it's the original value of the SP
+minus a constant, then that constant is the stack frame's size.
+If the SP's value has been marked as ``unknown'', then that means
+the prologue has done something too complex for us to track, and
+we don't know the frame size.
+
+@item
+To see where we've saved the previous frame's registers, we just
+search the values we've tracked --- stack slots, usually, but
+registers, too, if you want --- for something equal to the register's
+original value. If the calling conventions suggest a standard place
+to save a given register, then we can check there first, but really,
+anything that will get us back the original value will probably work.
+@end itemize
+
+This does take some work. But prologue analyzers aren't
+quick-and-simple pattern patching to recognize a few fixed prologue
+forms any more; they're big, hairy functions. Along with inferior
+function calls, prologue analysis accounts for a substantial portion
+of the time needed to stabilize a @value{GDBN} port. So it's
+worthwhile to look for an approach that will be easier to understand
+and maintain. In the approach described above:
+
+@itemize @bullet
+
+@item
+It's easier to see that the analyzer is correct: you just see
+whether the analyzer properly (albeit conservatively) simulates
+the effect of each instruction.
+
+@item
+It's easier to extend the analyzer: you can add support for new
+instructions, and know that you haven't broken anything that
+wasn't already broken before.
+
+@item
+It's orthogonal: to gather new information, you don't need to
+complicate the code for each instruction. As long as your domain
+of conservative values is already detailed enough to tell you
+what you need, then all the existing instruction simulations are
+already gathering the right data for you.
+
+@end itemize
+
+The file @file{prologue-value.h} contains detailed comments explaining
+the framework and how to use it.
-@cindex frame pointer register
-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
-determine the address of the calling function's frame. This will be
-used to create a new @value{GDBN} frame struct, and then
-@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} and
-@code{DEPRECATED_INIT_FRAME_PC} will be called for the new frame.
@section Breakpoint Handling
Basic breakpoint object handling is in @file{breakpoint.c}. However,
much of the interesting breakpoint action is in @file{infrun.c}.
+@table @code
+@cindex insert or remove software breakpoint
+@findex target_remove_breakpoint
+@findex target_insert_breakpoint
+@item target_remove_breakpoint (@var{bp_tgt})
+@itemx target_insert_breakpoint (@var{bp_tgt})
+Insert or remove a software breakpoint at address
+@code{@var{bp_tgt}->placed_address}. Returns zero for success,
+non-zero for failure. On input, @var{bp_tgt} contains the address of the
+breakpoint, and is otherwise initialized to zero. The fields of the
+@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated
+to contain other information about the breakpoint on output. The field
+@code{placed_address} may be updated if the breakpoint was placed at a
+related address; the field @code{shadow_contents} contains the real
+contents of the bytes where the breakpoint has been inserted,
+if reading memory would return the breakpoint instead of the
+underlying memory; the field @code{shadow_len} is the length of
+memory cached in @code{shadow_contents}, if any; and the field
+@code{placed_size} is optionally set and used by the target, if
+it could differ from @code{shadow_len}.
+
+For example, the remote target @samp{Z0} packet does not require
+shadowing memory, so @code{shadow_len} is left at zero. However,
+the length reported by @code{BREAKPOINT_FROM_PC} is cached in
+@code{placed_size}, so that a matching @samp{z0} packet can be
+used to remove the breakpoint.
+
+@cindex insert or remove hardware breakpoint
+@findex target_remove_hw_breakpoint
+@findex target_insert_hw_breakpoint
+@item target_remove_hw_breakpoint (@var{bp_tgt})
+@itemx target_insert_hw_breakpoint (@var{bp_tgt})
+Insert or remove a hardware-assisted breakpoint at address
+@code{@var{bp_tgt}->placed_address}. Returns zero for success,
+non-zero for failure. See @code{target_insert_breakpoint} for
+a description of the @code{struct bp_target_info} pointed to by
+@var{bp_tgt}; the @code{shadow_contents} and
+@code{shadow_len} members are not used for hardware breakpoints,
+but @code{placed_size} may be.
+@end table
+
@section Single Stepping
@section Signal Handling
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:
Return non-zero if hardware watchpoints can be used to watch a region
whose address is @var{addr} and whose length in bytes is @var{len}.
-@findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT
-@item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size})
-Return non-zero if hardware watchpoints can be used to watch a region
-whose size is @var{size}. @value{GDBN} only uses this macro as a
-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})
@noindent
These two macros should return 0 for success, non-zero for failure.
-@cindex insert or remove hardware breakpoint
-@findex target_remove_hw_breakpoint
-@findex target_insert_hw_breakpoint
-@item target_remove_hw_breakpoint (@var{addr}, @var{shadow})
-@itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow})
-Insert or remove a hardware-assisted breakpoint at address @var{addr}.
-Returns zero for success, non-zero for failure. @var{shadow} is the
-real contents of the byte where the breakpoint has been inserted; it
-is generally not valid when hardware breakpoints are used, but since
-no other code touches these values, the implementations of the above
-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})
@findex i386_insert_hw_breakpoint
@findex i386_remove_hw_breakpoint
-@item i386_insert_hw_breakpoint (@var{addr}, @var{shadow}
-@itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow})
+@item i386_insert_hw_breakpoint (@var{bp_tgt})
+@itemx i386_remove_hw_breakpoint (@var{bp_tgt})
These functions insert and remove hardware-assisted breakpoints. The
macros @code{target_insert_hw_breakpoint} and
@code{target_remove_hw_breakpoint} are set to call these functions.
+The argument is a @code{struct bp_target_info *}, as described in
+the documentation for @code{target_insert_breakpoint}.
These functions work like @code{i386_insert_watchpoint} and
@code{i386_remove_watchpoint}, respectively, except that they set up
the debug registers to watch instruction execution, and each
@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
unavailable in many platforms.
@end enumerate
+@section Checkpoints
+@cindex checkpoints
+@cindex restart
+In the abstract, a checkpoint is a point in the execution history of
+the program, which the user may wish to return to at some later time.
+
+Internally, a checkpoint is a saved copy of the program state, including
+whatever information is required in order to restore the program to that
+state at a later time. This can be expected to include the state of
+registers and memory, and may include external state such as the state
+of open files and devices.
+
+There are a number of ways in which checkpoints may be implemented
+in gdb, e.g.@: as corefiles, as forked processes, and as some opaque
+method implemented on the target side.
+
+A corefile can be used to save an image of target memory and register
+state, which can in principle be restored later --- but corefiles do
+not typically include information about external entities such as
+open files. Currently this method is not implemented in gdb.
+
+A forked process can save the state of user memory and registers,
+as well as some subset of external (kernel) state. This method
+is used to implement checkpoints on Linux, and in principle might
+be used on other systems.
+
+Some targets, e.g.@: simulators, might have their own built-in
+method for saving checkpoints, and gdb might be able to take
+advantage of that capability without necessarily knowing any
+details of how it is done.
+
+
@section Observing changes in @value{GDBN} internals
@cindex observer pattern interface
@cindex notifications about changes in internals
@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:
obtain various status values from @value{GDBN}.
@end itemize
-Since @code{libgdb} could have multiple clients (e.g. a GUI supporting
+Since @code{libgdb} could have multiple clients (e.g., a GUI supporting
the existing @value{GDBN} CLI), those clients must co-operate when
controlling @code{libgdb}. In particular, a client must ensure that
@code{libgdb} is idle (i.e. no other client is using @code{libgdb})
@code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
the offset between the file's specified start address and its true
address in memory. @code{mainline} is 1 if this is the main symbol
-table being read, and 0 if a secondary symbol file (e.g. shared library
+table being read, and 0 if a secondary symbol file (e.g., shared library
or dynamically loaded file) is being read.@refill
@end table
@findex find_pc_function
@findex find_pc_line
@item
-By its address (e.g. execution stops at some address which is inside a
+By its address (e.g., execution stops at some address which is inside a
function in this file). The address will be noticed to be in the
range of this psymtab, and the full symtab will be read in.
@code{find_pc_function}, @code{find_pc_line}, and other
@cindex lookup_symbol
@item
By its name
-(e.g. the user asks to print a variable, or set a breakpoint on a
+(e.g., the user asks to print a variable, or set a breakpoint on a
function). Global names and file-scope names will be found in the
psymtab, which will cause the symtab to be pulled in. Local names will
have to be qualified by a global name, or a file-scope name, in which
directly. This interface should be described in a file
@file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
+@section Memory Management for Symbol Files
+
+Most memory associated with a loaded symbol file is stored on
+its @code{objfile_obstack}. This includes symbols, types,
+namespace data, and other information produced by the symbol readers.
+
+Because this data lives on the objfile's obstack, it is automatically
+released when the objfile is unloaded or reloaded. Therefore one
+objfile must not reference symbol or type data from another objfile;
+they could be unloaded at different times.
+
+User convenience variables, et cetera, have associated types. Normally
+these types live in the associated objfile. However, when the objfile
+is unloaded, those types are deep copied to global memory, so that
+the values of the user variables and history items are not lost.
+
@node Language Support
@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
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
Replaces all the other @var{BREAKPOINT} macros.
-@item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache})
-@itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache})
+@item MEMORY_INSERT_BREAKPOINT (@var{bp_tgt})
+@itemx MEMORY_REMOVE_BREAKPOINT (@var{bp_tgt})
@findex MEMORY_REMOVE_BREAKPOINT
@findex MEMORY_INSERT_BREAKPOINT
Insert or remove memory based breakpoints. Reasonable defaults
@code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
reason.
-@item DEPRECATED_CALL_DUMMY_WORDS
-@findex DEPRECATED_CALL_DUMMY_WORDS
-Pointer to an array of @code{LONGEST} words of data containing
-host-byte-ordered @code{DEPRECATED_REGISTER_SIZE} sized values that
-partially specify the sequence of instructions needed for an inferior
-function call.
-
-Should be deprecated in favor of a macro that uses target-byte-ordered
-data.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
-
-@item DEPRECATED_SIZEOF_CALL_DUMMY_WORDS
-@findex DEPRECATED_SIZEOF_CALL_DUMMY_WORDS
-The size of @code{DEPRECATED_CALL_DUMMY_WORDS}. This must return a
-positive value. See also @code{DEPRECATED_CALL_DUMMY_LENGTH}.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
-
-@item CALL_DUMMY
-@findex CALL_DUMMY
-A static initializer for @code{DEPRECATED_CALL_DUMMY_WORDS}.
-Deprecated.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
+@item ADJUST_BREAKPOINT_ADDRESS (@var{address})
+@findex ADJUST_BREAKPOINT_ADDRESS
+@cindex breakpoint address adjusted
+Given an address at which a breakpoint is desired, return a breakpoint
+address adjusted to account for architectural constraints on
+breakpoint placement. This method is not needed by most targets.
+
+The FR-V target (see @file{frv-tdep.c}) requires this method.
+The FR-V is a VLIW architecture in which a number of RISC-like
+instructions are grouped (packed) together into an aggregate
+instruction or instruction bundle. When the processor executes
+one of these bundles, the component instructions are executed
+in parallel.
+
+In the course of optimization, the compiler may group instructions
+from distinct source statements into the same bundle. The line number
+information associated with one of the latter statements will likely
+refer to some instruction other than the first one in the bundle. So,
+if the user attempts to place a breakpoint on one of these latter
+statements, @value{GDBN} must be careful to @emph{not} place the break
+instruction on any instruction other than the first one in the bundle.
+(Remember though that the instructions within a bundle execute
+in parallel, so the @emph{first} instruction is the instruction
+at the lowest address and has nothing to do with execution order.)
+
+The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a
+breakpoint's address by scanning backwards for the beginning of
+the bundle, returning the address of the bundle.
+
+Since the adjustment of a breakpoint may significantly alter a user's
+expectation, @value{GDBN} prints a warning when an adjusted breakpoint
+is initially set and each time that that breakpoint is hit.
@item CALL_DUMMY_LOCATION
@findex CALL_DUMMY_LOCATION
This method has been replaced by @code{push_dummy_code}
(@pxref{push_dummy_code}).
-@item DEPRECATED_CALL_DUMMY_STACK_ADJUST
-@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST
-Stack adjustment needed when performing an inferior function call. This
-function is no longer needed. @xref{push_dummy_call}, which can handle
-all alignment directly.
-
@item CANNOT_FETCH_REGISTER (@var{regno})
@findex CANNOT_FETCH_REGISTER
A C expression that should be nonzero if @var{regno} cannot be fetched
status words, and other special registers. If this is not defined,
@value{GDBN} will assume that all registers may be written.
-@item DO_DEFERRED_STORES
-@itemx CLEAR_DEFERRED_STORES
-@findex CLEAR_DEFERRED_STORES
-@findex DO_DEFERRED_STORES
-Define this to execute any deferred stores of registers into the inferior,
-and to cancel any deferred stores.
-
-Currently only implemented correctly for native Sparc configurations?
-
@item int CONVERT_REGISTER_P(@var{regnum})
@findex CONVERT_REGISTER_P
Return non-zero if register @var{regnum} can represent data values in a
program encounters a breakpoint. This is often the number of bytes in
@code{BREAKPOINT}, though not always. For most targets this value will be 0.
-@item DECR_PC_AFTER_HW_BREAK
-@findex DECR_PC_AFTER_HW_BREAK
-Similarly, for hardware breakpoints.
-
@item DISABLE_UNSETTABLE_BREAK (@var{addr})
@findex DISABLE_UNSETTABLE_BREAK
If defined, this should evaluate to 1 if @var{addr} is in a shared
the raw register state @var{regbuf} and copy that, in virtual format,
into @var{valbuf}.
-@item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
-@findex EXTRACT_STRUCT_VALUE_ADDRESS
+This method has been deprecated in favour of @code{gdbarch_return_value}
+(@pxref{gdbarch_return_value}).
+
+@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
+@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS
+@anchor{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}
When defined, extract from the array @var{regbuf} (containing the raw
register state) the @code{CORE_ADDR} at which a function should return
its structure value.
-If not defined, @code{EXTRACT_RETURN_VALUE} is used.
+@xref{gdbarch_return_value}.
-@item EXTRACT_STRUCT_VALUE_ADDRESS_P()
-@findex EXTRACT_STRUCT_VALUE_ADDRESS_P
-Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
+@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P()
+@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P
+Predicate for @code{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}.
@item DEPRECATED_FP_REGNUM
@findex DEPRECATED_FP_REGNUM
This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP}
is not defined.
-@item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
-@findex FRAMELESS_FUNCTION_INVOCATION
+@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
+@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION
Define this to an expression that returns 1 if the function invocation
represented by @var{fi} does not have a stack frame associated with it.
Otherwise return 0.
Define this to adjust @var{address} so that it meets the alignment
requirements for the start of a new stack frame. A stack frame's
alignment requirements are typically stronger than a target processors
-stack alignment requirements (@pxref{STACK_ALIGN}).
+stack alignment requirements (@pxref{DEPRECATED_STACK_ALIGN}).
This function is used to ensure that, when creating a dummy frame, both
the initial stack pointer and (if needed) the address of the return
value are correctly aligned.
-Unlike @code{STACK_ALIGN}, this function always adjusts the address in
-the direction of stack growth.
+Unlike @code{DEPRECATED_STACK_ALIGN}, this function always adjusts the
+address in the direction of stack growth.
By default, no frame based stack alignment is performed.
+@item int frame_red_zone_size
+
+The number of bytes, beyond the innermost-stack-address, reserved by the
+@sc{abi}. A function is permitted to use this scratch area (instead of
+allocating extra stack space).
+
+When performing an inferior function call, to ensure that it does not
+modify this area, @value{GDBN} adjusts the innermost-stack-address by
+@var{frame_red_zone_size} bytes before pushing parameters onto the
+stack.
+
+By default, zero bytes are allocated. The value must be aligned
+(@pxref{frame_align}).
+
+The @sc{amd64} (nee x86-64) @sc{abi} documentation refers to the
+@emph{red zone} when describing this scratch area.
+@cindex red zone
+
@item DEPRECATED_FRAME_CHAIN(@var{frame})
@findex DEPRECATED_FRAME_CHAIN
Given @var{frame}, return a pointer to the calling frame.
@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
function's epilogue.
-@item FUNCTION_START_OFFSET
-@findex FUNCTION_START_OFFSET
+@item DEPRECATED_FUNCTION_START_OFFSET
+@findex DEPRECATED_FUNCTION_START_OFFSET
An integer, giving the offset in bytes from a function's address (as
used in the values of symbols, function pointers, etc.), and the
function's first genuine instruction.
This is zero on almost all machines: the function's address is usually
-the address of its first instruction. However, on the VAX, for example,
-each function starts with two bytes containing a bitmask indicating
-which registers to save upon entry to the function. The VAX @code{call}
-instructions check this value, and save the appropriate registers
-automatically. Thus, since the offset from the function's address to
-its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
-be 2 on the VAX.
+the address of its first instruction. However, on the VAX, for
+example, each function starts with two bytes containing a bitmask
+indicating which registers to save upon entry to the function. The
+VAX @code{call} instructions check this value, and save the
+appropriate registers automatically. Thus, since the offset from the
+function's address to its first instruction is two bytes,
+@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
@item GCC_COMPILED_FLAG_SYMBOL
@itemx GCC2_COMPILED_FLAG_SYMBOL
Define this if you need to supply your own definition for the function
@code{DEPRECATED_GET_SAVED_REGISTER}.
-@item IBM6000_TARGET
-@findex IBM6000_TARGET
-Shows that we are configured for an IBM RS/6000 target. This
+@item DEPRECATED_IBM6000_TARGET
+@findex DEPRECATED_IBM6000_TARGET
+Shows that we are configured for an IBM RS/6000 system. This
conditional should be eliminated (FIXME) and replaced by
feature-specific macros. It was introduced in a haste and we are
repenting at leisure.
the stack frame of the function already has been destroyed up to the
final `return from function call' instruction.
-@item SIGTRAMP_START (@var{pc})
-@findex SIGTRAMP_START
-@itemx SIGTRAMP_END (@var{pc})
-@findex SIGTRAMP_END
+@item DEPRECATED_SIGTRAMP_START (@var{pc})
+@findex DEPRECATED_SIGTRAMP_START
+@itemx DEPRECATED_SIGTRAMP_END (@var{pc})
+@findex DEPRECATED_SIGTRAMP_END
Define these to be the start and end address of the @code{sigtramp} for the
given @var{pc}. On machines where the address is just a compile time
constant, the macro expansion will typically just ignore the supplied
@xref{Target Architecture Definition, , Pointers Are Not Always
Addresses}.
-@item NEED_TEXT_START_END
-@findex NEED_TEXT_START_END
-Define this if @value{GDBN} should determine the start and end addresses of the
-text section. (Seems dubious.)
-
@item NO_HIF_SUPPORT
@findex NO_HIF_SUPPORT
(Specific to the a29k.)
@var{type}.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
-@item REGISTER_RAW_SIZE (@var{reg})
-@findex REGISTER_RAW_SIZE
+@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_RAW_SIZE
Return the raw size of @var{reg}; defaults to the size of the register's
virtual type.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
Any register with a valid name.
@end table
-@item REGISTER_VIRTUAL_SIZE (@var{reg})
-@findex REGISTER_VIRTUAL_SIZE
+@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg})
+@findex DEPRECATED_REGISTER_VIRTUAL_SIZE
Return the virtual size of @var{reg}; defaults to the size of the
register's virtual type.
Return the virtual size of @var{reg}.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
-@item REGISTER_VIRTUAL_TYPE (@var{reg})
+@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})
@findex REGISTER_VIRTUAL_TYPE
Return the virtual type of @var{reg}.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item struct type *register_type (@var{gdbarch}, @var{reg})
@findex register_type
If defined, return the type of register @var{reg}. This function
-superseeds @code{REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture
+superseeds @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture
Definition, , Raw and Virtual Register Representations}.
@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
form.
@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
-@item RETURN_VALUE_ON_STACK(@var{type})
-@findex RETURN_VALUE_ON_STACK
-@cindex returning structures by value
-@cindex structures, returning by value
-
-Return non-zero if values of type TYPE are returned on the stack, using
-the ``struct convention'' (i.e., the caller provides a pointer to a
-buffer in which the callee should store the return value). This
-controls how the @samp{finish} command finds a function's return value,
-and whether an inferior function call reserves space on the stack for
-the return value.
-
-The full logic @value{GDBN} uses here is kind of odd.
-
-@itemize @bullet
-@item
-If the type being returned by value is not a structure, union, or array,
-and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
-concludes the value is not returned using the struct convention.
-
-@item
-Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
-If that returns non-zero, @value{GDBN} assumes the struct convention is
-in use.
-@end itemize
-
-In other words, to indicate that a given type is returned by value using
-the struct convention, that type must be either a struct, union, array,
-or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
-that @code{USE_STRUCT_CONVENTION} likes.
-
-Note that, in C and C@t{++}, arrays are never returned by value. In those
-languages, these predicates will always see a pointer type, never an
-array type. All the references above to arrays being returned by value
-apply only to other languages.
+@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size})
+@findex regset_from_core_section
+Return the appropriate register set for a core file section with name
+@var{sect_name} and size @var{sect_size}.
@item SOFTWARE_SINGLE_STEP_P()
@findex SOFTWARE_SINGLE_STEP_P
them.
@end itemize
-@item PCC_SOL_BROKEN
-@findex PCC_SOL_BROKEN
-(Used only in the Convex target.)
-
-@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
-@findex PC_IN_SIGTRAMP
-@cindex sigtramp
-The @dfn{sigtramp} is a routine that the kernel calls (which then calls
-the signal handler). On most machines it is a library routine that is
-linked into the executable.
-
-This function, given a program counter value in @var{pc} and the
-(possibly NULL) name of the function in which that @var{pc} resides,
-returns nonzero if the @var{pc} and/or @var{name} show that we are in
-sigtramp.
-
@item PC_LOAD_SEGMENT
@findex PC_LOAD_SEGMENT
If defined, print information about the load segment for the program
This should only need to be defined if @code{TARGET_READ_PC} and
@code{TARGET_WRITE_PC} are not defined.
-@item NPC_REGNUM
-@findex NPC_REGNUM
-The number of the ``next program counter'' register, if defined.
-
@item PARM_BOUNDARY
@findex PARM_BOUNDARY
If non-zero, round arguments to a boundary of this many bits before
pushing them on the stack.
+@item stabs_argument_has_addr (@var{gdbarch}, @var{type})
+@findex stabs_argument_has_addr
+@findex DEPRECATED_REG_STRUCT_HAS_ADDR
+@anchor{stabs_argument_has_addr} Define this to return nonzero if a
+function argument of type @var{type} is passed by reference instead of
+value.
+
+This method replaces @code{DEPRECATED_REG_STRUCT_HAS_ADDR}
+(@pxref{DEPRECATED_REG_STRUCT_HAS_ADDR}).
+
@item PROCESS_LINENUMBER_HOOK
@findex PROCESS_LINENUMBER_HOOK
A hook defined for XCOFF reading.
If defined, used by @code{frame_pop} to remove a stack frame. This
method has been superseeded by generic code.
-@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@item push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
@findex push_dummy_call
@findex DEPRECATED_PUSH_ARGUMENTS.
@anchor{push_dummy_call} Define this to push the dummy frame's call to
@var{nargs}, the code should push @var{struct_addr} (when
@var{struct_return}), and the return address (@var{bp_addr}).
+@var{function} is a pointer to a @code{struct value}; on architectures that use
+function descriptors, this contains the function descriptor value.
+
Returns the updated top-of-stack pointer.
This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
@item CORE_ADDR push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr})
@findex push_dummy_code
-@findex DEPRECATED_FIX_CALL_DUMMY
@anchor{push_dummy_code} Given a stack based call dummy, push the
instruction sequence (including space for a breakpoint) to which the
called function should return.
(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address
reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.
-This method replaces @code{DEPRECATED_CALL_DUMMY_WORDS},
-@code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY},
-@code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE},
-@code{GDB_TARGET_IS_HPPA},
-@code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and
-@code{DEPRECATED_FIX_CALL_DUMMY}.
-
-@item DEPRECATED_PUSH_DUMMY_FRAME
-@findex DEPRECATED_PUSH_DUMMY_FRAME
-Used in @samp{call_function_by_hand} to create an artificial stack frame.
-
-@item DEPRECATED_REGISTER_BYTES
-@findex DEPRECATED_REGISTER_BYTES
-The total amount of space needed to store @value{GDBN}'s copy of the
-machine's register state.
-
-This is no longer needed. @value{GDBN} instead computes the size of the
-register buffer at run-time.
+This method replaces @code{CALL_DUMMY_LOCATION},
+@code{DEPRECATED_REGISTER_SIZE}.
@item REGISTER_NAME(@var{i})
@findex REGISTER_NAME
Return the name of register @var{i} as a string. May return @code{NULL}
or @code{NUL} to indicate that register @var{i} is not valid.
-@item REGISTER_NAMES
-@findex REGISTER_NAMES
-Deprecated in favor of @code{REGISTER_NAME}.
+@item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
+@findex DEPRECATED_REG_STRUCT_HAS_ADDR
+@anchor{DEPRECATED_REG_STRUCT_HAS_ADDR}Define this to return 1 if the
+given type will be passed by pointer rather than directly.
-@item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
-@findex REG_STRUCT_HAS_ADDR
-Define this to return 1 if the given type will be passed by pointer
-rather than directly.
+This method has been replaced by @code{stabs_argument_has_addr}
+(@pxref{stabs_argument_has_addr}).
@item SAVE_DUMMY_FRAME_TOS (@var{sp})
@findex SAVE_DUMMY_FRAME_TOS
Define this to convert sdb register numbers into @value{GDBN} regnums. If not
defined, no conversion will be done.
+@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf})
+@findex gdbarch_return_value
+@anchor{gdbarch_return_value} Given a function with a return-value of
+type @var{rettype}, return which return-value convention that function
+would use.
+
+@value{GDBN} currently recognizes two function return-value conventions:
+@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found
+in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return
+value is found in memory and the address of that memory location is
+passed in as the function's first parameter.
+
+If the register convention is being used, and @var{writebuf} is
+non-@code{NULL}, also copy the return-value in @var{writebuf} into
+@var{regcache}.
+
+If the register convention is being used, and @var{readbuf} is
+non-@code{NULL}, also copy the return value from @var{regcache} into
+@var{readbuf} (@var{regcache} contains a copy of the registers from the
+just returned function).
+
+@xref{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}, for a description of how
+return-values that use the struct convention are handled.
+
+@emph{Maintainer note: This method replaces separate predicate, extract,
+store methods. By having only one method, the logic needed to determine
+the return-value convention need only be implemented in one place. If
+@value{GDBN} were written in an @sc{oo} language, this method would
+instead return an object that knew how to perform the register
+return-value extract and store.}
+
+@emph{Maintainer note: This method does not take a @var{gcc_p}
+parameter, and such a parameter should not be added. If an architecture
+that requires per-compiler or per-function information be identified,
+then the replacement of @var{rettype} with @code{struct value}
+@var{function} should be persued.}
+
+@emph{Maintainer note: The @var{regcache} parameter limits this methods
+to the inner most frame. While replacing @var{regcache} with a
+@code{struct frame_info} @var{frame} parameter would remove that
+limitation there has yet to be a demonstrated need for such a change.}
+
@item SKIP_PERMANENT_BREAKPOINT
@findex SKIP_PERMANENT_BREAKPOINT
Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
declarations) into @value{GDBN} regnums. If not defined, no conversion will be
done.
-@item STACK_ALIGN (@var{addr})
-@anchor{STACK_ALIGN}
-@findex STACK_ALIGN
+@item DEPRECATED_STACK_ALIGN (@var{addr})
+@anchor{DEPRECATED_STACK_ALIGN}
+@findex DEPRECATED_STACK_ALIGN
Define this to increase @var{addr} so that it meets the alignment
requirements for the processor's stack.
@var{valbuf}, into the @var{regcache}. @var{type} is the type of the
value that is to be returned.
-@item SUN_FIXED_LBRAC_BUG
-@findex SUN_FIXED_LBRAC_BUG
-(Used only for Sun-3 and Sun-4 targets.)
+This method has been deprecated in favour of @code{gdbarch_return_value}
+(@pxref{gdbarch_return_value}).
@item SYMBOL_RELOADING_DEFAULT
@findex SYMBOL_RELOADING_DEFAULT
@findex TARGET_READ_PC
@itemx TARGET_WRITE_PC (@var{val}, @var{pid})
@findex TARGET_WRITE_PC
+@anchor{TARGET_WRITE_PC}
@itemx TARGET_READ_SP
@findex TARGET_READ_SP
@itemx TARGET_READ_FP
@findex read_sp
@findex read_fp
@anchor{TARGET_READ_SP} These change the behavior of @code{read_pc},
-@code{write_pc}, @code{read_sp} and @code{deprecated_read_fp}. For most
-targets, these may be left undefined. @value{GDBN} will call the read
-and write register functions with the relevant @code{_REGNUM} argument.
+@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
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
machine uses to define the struct of registers that is accessible
(possibly in the u-area) in a core file (rather than
@file{machine/reg.h}), and an include file that defines whatever header
-exists on a core file (e.g. the u-area or a @code{struct core}). Then
+exists on a core file (e.g., the u-area or a @code{struct core}). Then
modify @code{trad_unix_core_file_p} to use these values to set up the
section information for the data segment, stack segment, any other
segments in the core file (perhaps shared library contents or control
information), ``registers'' segment, and if there are two discontiguous
-sets of registers (e.g. integer and float), the ``reg2'' segment. This
+sets of registers (e.g., integer and float), the ``reg2'' segment. This
section information basically delimits areas in the core file in a
standard way, which the section-reading routines in BFD know how to seek
around in.
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
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
return file;
@end smallexample
-Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
+Some functions, e.g., @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
means that any actions you need to reverse in the case of an error or
interruption must be on the cleanup chain before you call these
@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
+A module can on-demand create architecture dependant data structures
+using @code{post_init}.
-This function is used by modules that require a mechanism for explicitly
-setting the per-architecture data-pointer during architecture creation:
+In the below, the nozel's total is computed on-demand by
+@code{nozel_post_init} using information obtained from the
+architecture.
@smallexample
-/* Called during architecture creation. */
-extern void
-set_gdbarch_nozel (struct gdbarch *gdbarch,
- int total)
-@{
- struct nozel *data = XMALLOC (struct nozel);
- @dots{}
- set_gdbarch_data (gdbarch, nozel_handle, nozel);
-@}
-@end smallexample
-
-@smallexample
-/* Default, called when nozel not set by set_gdbarch_nozel(). */
static void *
-nozel_init (struct gdbarch *gdbarch)
+nozel_post_init (struct gdbarch *gdbarch)
@{
- struct nozel *default_nozel = XMALLOC (struc nozel);
- @dots{}
- return default_nozel;
+ struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
+ nozel->total = gdbarch@dots{} (gdbarch);
+ return data;
@}
@end smallexample
@smallexample
-void
-_initialize_nozel (void)
+extern int
+nozel_total (struct gdbarch *gdbarch)
@{
- nozel_handle = register_gdbarch_data (nozel_init, NULL);
- @dots{}
+ struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+ return data->total;
+@}
@end smallexample
-@noindent
-Note that an @code{init} function still needs to be registered. It is
-used to initialize the data-pointer when the architecture creation phase
-fail to set an initial value.
-
-
@section Wrapping Output Lines
@cindex line wrap in output
restrict the memory being allocated to no more than a few kilobytes.}
@value{GDBN} uses the string function @code{xstrdup} and the print
-function @code{xasprintf}.
+function @code{xstrprintf}.
@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
functions such as @code{sprintf} are very prone to buffer overflow
@item -Wpointer-arith
@item -Wuninitialized
+
+@item -Wunused-label
+This warning has the additional benefit of detecting the absence of the
+@code{case} reserved word in a switch statement:
+@smallexample
+enum @{ FD_SCHEDULED, NOTHING_SCHEDULED @} sched;
+@dots{}
+switch (sched)
+ @{
+ case FD_SCHEDULED:
+ @dots{};
+ break;
+ NOTHING_SCHEDULED:
+ @dots{};
+ break;
+ @}
+@end smallexample
+
+@item -Wunused-function
+
+@item -Wno-pointer-sign
+In version 4.0, GCC began warning about pointer argument passing or
+assignment even when the source and destination differed only in
+signedness. However, most @value{GDBN} code doesn't distinguish
+carefully between @code{char} and @code{unsigned char}. In early 2006
+the @value{GDBN} developers decided correcting these warnings wasn't
+worth the time it would take.
+
@end table
@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
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
-@subsection Branches
+@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.
-@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).
+The following are a set of guidelines for creating such branches:
-Releases 5.0 and 5.1 used branch and release tags of the form:
+@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).
+
+@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.
+
+@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.
+
+@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
+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.
+@end table
+
+@noindent
+For further information on @sc{cvs}, see
+@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
+
+@node Start of New Year Procedure
+@chapter Start of New Year Procedure
+@cindex new year procedure
+
+At the start of each new year, the following actions should be performed:
+
+@itemize @bullet
+@item
+Rotate the ChangeLog file
+
+The current @file{ChangeLog} file should be renamed into
+@file{ChangeLog-YYYY} where YYYY is the year that has just passed.
+A new @file{ChangeLog} file should be created, and its contents should
+contain a reference to the previous ChangeLog. The following should
+also be preserved at the end of the new ChangeLog, in order to provide
+the appropriate settings when editing this file with Emacs:
@smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-branch
-gdb_M_N-YYYY-MM-DD-release
+Local Variables:
+mode: change-log
+left-margin: 8
+fill-column: 74
+version-control: never
+End:
@end smallexample
-@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.}
+@item
+Update the copyright year in the startup message
+
+Update the copyright year in file @file{top.c}, function
+@code{print_gdb_version}.
+@end itemize
+
+@node Releasing GDB
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
@section Branch Commit Policy
$ echo $u $V $D
5.1 5_2 2002-03-03
$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
--D $D-gmt gdb_$V-$D-branchpoint insight+dejagnu
+-D $D-gmt gdb_$V-$D-branchpoint insight
cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
--D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu
+-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
$ ^echo ^^
...
$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
--b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu
+-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
--b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight+dejagnu
+-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
$ ^echo ^^
...
$
@itemize @bullet
@item
-by using @kbd{-D YYYY-MM-DD-gmt} the branch is forced to an exact
+By using @kbd{-D YYYY-MM-DD-gmt}, the branch is forced to an exact
date/time.
@item
-the trunk is first taged so that the branch point can easily be found
+The trunk is first tagged so that the branch point can easily be found.
@item
-Insight (which includes GDB) and dejagnu are all tagged at the same time
+Insight, which includes @value{GDBN}, is tagged at the same time.
@item
-@file{version.in} gets bumped to avoid version number conflicts
+@file{version.in} gets bumped to avoid version number conflicts.
@item
-the reading of @file{.cvsrc} is disabled using @file{-f}
+The reading of @file{.cvsrc} is disabled using @file{-f}.
@end itemize
@subheading Update @file{version.in}
@itemize @bullet
@item
@file{0000-00-00} is used as a date to pump prime the version.in update
-mechanism
+mechanism.
@item
@file{.90} and the previous branch version are used as fairly arbitrary
-initial branch version number
+initial branch version number.
@end itemize
@itemize @bullet
@item
-a daily timestamp is added to the file @file{version.in}
+A daily timestamp is added to the file @file{version.in}.
@item
-the new branch is included in the snapshot process
+The new branch is included in the snapshot process.
@end itemize
@noindent
@itemize @bullet
@item
-the branch tag
+The branch tag.
@item
-how to check out the branch using CVS
+How to check out the branch using CVS.
@item
-the date/number of weeks until the release
+The date/number of weeks until the release.
@item
-the branch commit policy
-still holds.
+The branch commit policy still holds.
@end itemize
@section Stabilize the branch
@subsubheading Check out the relevant modules:
@smallexample
-$ for m in gdb insight dejagnu
+$ for m in gdb insight
do
( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
done
@itemize @bullet
@item
-the version
+The version.
@item
-the update date
+The update date.
@item
-who did it
+Who did it.
@end itemize
@smallexample
$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
@end smallexample
-@item dejagnu/src/dejagnu/configure.in
-
-Dejagnu is more complicated. The version number is a parameter to
-@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
-
-Don't forget to re-generate @file{configure}.
-
-Don't forget to include a @file{ChangeLog} entry.
-
-@smallexample
-$ emacs dejagnu/src/dejagnu/configure.in
-...
-c-x 4 a
-...
-c-x c-s c-x c-c
-$ ( cd dejagnu/src/dejagnu && autoconf )
-@end smallexample
-
@end table
@subsubheading Do the dirty work
do
( cd $m/src && gmake -f src-release $m.tar )
done
-$ ( m=dejagnu; cd $m/src && gmake -f src-release $m.tar.bz2 )
@end smallexample
If the top level source directory does not have @file{src-release}
do
( cd $m/src && gmake -f Makefile.in $m.tar )
done
-$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
@end smallexample
@subsubheading Check the source files
$ cp */src/*.tar .
$ cp */src/*.bz2 .
$ ls -F
-dejagnu/ dejagnu-gdb-5.2.tar.bz2 gdb/ gdb-5.2.tar insight/ insight-5.2.tar
+gdb/ gdb-5.2.tar insight/ insight-5.2.tar
$ for m in gdb insight
do
bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
This file, which is posted as the official announcement, includes:
@itemize @bullet
@item
-General announcement
+General announcement.
@item
News. If making an @var{M}.@var{N}.1 release, retain the news from
earlier @var{M}.@var{N} release.
@item
-Errata
+Errata.
@end itemize
@item htdocs/index.html
These files include:
@itemize @bullet
@item
-announcement of the most recent release
+Announcement of the most recent release.
@item
-news entry (remember to update both the top level and the news directory).
+News entry (remember to update both the top level and the news directory).
@end itemize
These pages also need to be regenerate using @code{index.sh}.
@end smallexample
Insight is used since that contains more of the release than
-@value{GDBN} (@code{dejagnu} doesn't get tagged but I think we can live
-with that).
+@value{GDBN}.
@subsubheading Mention the release on the trunk
the available commands, and it has proven all too common for a change
to cause a significant regression that went unnoticed for some time.
-The @value{GDBN} testsuite uses the DejaGNU testing framework.
-DejaGNU is built using @code{Tcl} and @code{expect}. The tests
-themselves are calls to various @code{Tcl} procs; the framework runs all the
-procs and summarizes the passes and fails.
+The @value{GDBN} testsuite uses the DejaGNU testing framework. The
+tests themselves are calls to various @code{Tcl} procs; the framework
+runs all the procs and summarizes the passes and fails.
@section Using the Testsuite
# of untested testcases 5
@end smallexample
+To run a specific test script, type:
+@example
+make check RUNTESTFLAGS='@var{tests}'
+@end example
+where @var{tests} is a list of test script file names, separated by
+spaces.
+
The ideal test run consists of expected passes only; however, reality
conspires to keep us from this ideal. Unexpected failures indicate
real problems, whether in @value{GDBN} or in the testsuite. Expected
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 / binutils.git / blobdiff