* Support Libraries::
* Coding::
* Porting GDB::
+* Versions and Branches::
* Releasing GDB::
* Testsuite::
* Hints::
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.
+@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:
@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
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
@findex read_sp
@findex read_fp
@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
+@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.
@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
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
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)}.
+
+@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).
+
+@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}.
-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.
+@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 Branches
+@subsection Tags
+@anchor{Tags}
-@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).
+To simplify the identification of @value{GDBN} branches, the following
+branch tagging convention is strongly recommended:
-Releases 5.0 and 5.1 used branch and release tags of the form:
+@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
projects / deliverable / binutils-gdb.git / blobdiff