@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
+Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, 2002
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
place to add commands is in the @code{_initialize_@var{xyz}} routines at
the ends of most source files.
+@findex add_setshow_cmd
+@findex add_setshow_cmd_full
+To add paired @samp{set} and @samp{show} commands, use
+@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is
+a slightly simpler interface which is useful when you don't need to
+further modify the new command structures, while the latter returns
+the new command structures for manipulation.
+
@cindex deprecating commands
@findex deprecate_cmd
Before removing commands from the command set it is a good idea to
This function first opens the tuple and then establishes a cleanup
(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient
and correct implementation of the non-portable@footnote{The function
-cast is not portable ISO-C.} code sequence:
+cast is not portable ISO C.} code sequence:
@smallexample
struct cleanup *old_cleanup;
ui_out_tuple_begin (uiout, "...");
DWARF 1 is a debugging format that was originally designed to be
used with ELF in SVR4 systems.
-@c CHILL_PRODUCER
+@c OBSOLETE CHILL_PRODUCER
@c GCC_PRODUCER
@c GPLUS_PRODUCER
@c LCC_PRODUCER
@item GDB_OSABI_WINCE
Windows CE
+@findex GDB_OSABI_GO32
+@item GDB_OSABI_GO32
+DJGPP
+
+@findex GDB_OSABI_NETWARE
+@item GDB_OSABI_NETWARE
+Novell NetWare
+
@findex GDB_OSABI_ARM_EABI_V1
@item GDB_OSABI_ARM_EABI_V1
ARM Embedded ABI version 1
If defined, then the @samp{info float} command will print information about
the processor's floating point unit.
+@item PRINT_VECTOR_INFO()
+@findex PRINT_VECTOR_INFO
+If defined, then the @samp{info vector} command will call this function
+to print information about the processor's vector unit.
+
+By default, the @samp{info vector} command will print all vector
+registers (the register's type having the vector attribute).
+
@item DWARF_REG_TO_REGNUM
@findex DWARF_REG_TO_REGNUM
Convert DWARF register number into @value{GDBN} regnum. If not defined,
Define this to convert sdb register numbers into @value{GDBN} regnums. If not
defined, no conversion will be done.
-@item SHIFT_INST_REGS
-@findex SHIFT_INST_REGS
-(Only used for m88k targets.)
+@c OBSOLETE @item SHIFT_INST_REGS
+@c OBSOLETE @findex SHIFT_INST_REGS
+@c OBSOLETE (Only used for m88k targets.)
@item SKIP_PERMANENT_BREAKPOINT
@findex SKIP_PERMANENT_BREAKPOINT
functions, since they might never return to your code (they
@samp{longjmp} instead).
+@section Per-architecture module data
+@cindex per-architecture module data
+@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.
+
+A module registers one or more per-architecture data-pointers using the
+function @code{register_gdbarch_data}:
+
+@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+
+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}.
+
+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.
+
+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.
+
+@end deftypefun
+
+A typical module has @code{init} and @code{free} functions of the form:
+
+@smallexample
+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.
+
+The data-pointer is registered with the call:
+
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
+@dots{}
+@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)
+@{
+ int total;
+ struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+ @dots{}
+ return total;
+@}
+@end smallexample
+
+It is also possible to directly initialize the data-pointer using:
+
+@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
+Update the data-pointer corresponding to @var{handle} with the value of
+@var{pointer}. If the previous data-pointer value is non-NULL, then it
+is freed using data-pointers @var{free} function.
+@end deftypefun
+
+This function is used by modules that require a mechanism for explicitly
+setting the per-architecture data-pointer during architecture creation:
+
+@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)
+@{
+ struct nozel *default_nozel = XMALLOC (struc nozel);
+ @dots{}
+ return default_nozel;
+@}
+@end smallexample
+
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, NULL);
+ @dots{}
+@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
@value{GDBN}, as described in the following sections.
-@subsection ISO-C
+@subsection ISO C
-@value{GDBN} assumes an ISO-C compliant compiler.
+@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
+compiler.
-@value{GDBN} does not assume an ISO-C or POSIX compliant C library.
+@value{GDBN} does not assume an ISO C or POSIX compliant C library.
@subsection Memory Management
@subsection Include Files
-All @file{.c} files should include @file{defs.h} first.
+A @file{.c} file should include @file{defs.h} first.
-All @file{.c} files should explicitly include the headers for any
-declarations they refer to. They should not rely on files being
-included indirectly.
+A @file{.c} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion.
-With the exception of the global definitions supplied by @file{defs.h},
-a header file should explicitly include the header declaring any
-@code{typedefs} et.al.@: it refers to.
+A @file{.h} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion. Exception: The file @file{defs.h} does not need to
+be directly included.
-@code{extern} declarations should never appear in @code{.c} files.
+An external declaration should only appear in one include file.
-All include files should be wrapped in:
+An external declaration should never appear in a @code{.c} file.
+Exception: a declaration for the @code{_initialize} function that
+pacifies @option{-Wmissing-declaration}.
+
+A @code{typedef} definition should only appear in one include file.
+
+An opaque @code{struct} declaration can appear in multiple @file{.h}
+files. Where possible, a @file{.h} file should use an opaque
+@code{struct} declaration instead of an include.
+
+All @file{.h} files should be wrapped in:
@smallexample
#ifndef INCLUDE_FILE_NAME_H
The targets are listed in @file{gdb/MAINTAINERS}.
-@section Cut the branch
-
-@subheading The dirty work
+@section Cut the Branch
-I think something like the below was used:
+@subheading Create the branch
@smallexample
-$ d=`date -u +%Y-%m-%d`
-$ echo $d
-2002-01-24
-$ cvs -f -d /cvs/src rtag -D $d-gmt \
-gdb_5_1-$d-branchpoint insight+dejagnu
-$ cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \
-gdb_5_1-$d-branch insight+dejagnu
+$ u=5.1
+$ v=5.2
+$ V=`echo $v | sed 's/\./_/g'`
+$ D=`date -u +%Y-%m-%d`
+$ 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
+cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
+-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu
+$ ^echo ^^
+...
+$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
+-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu
+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
+$ ^echo ^^
+...
$
@end smallexample
@itemize @bullet
@item
-the @kbd{-D YYYY-MM-DD-gmt} forces the branch to an exact date/time.
+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
@item
-the trunk is first tagged so that the branch point can easily be found
+Insight (which includes GDB) and dejagnu are all tagged at the same time
@item
-Insight (which includes GDB) and dejagnu are tagged at the same time
+@file{version.in} gets bumped to avoid version number conflicts
+@item
+the reading of @file{.cvsrc} is disabled using @file{-f}
+@end itemize
+
+@subheading Update @file{version.in}
+
+@smallexample
+$ u=5.1
+$ v=5.2
+$ V=`echo $v | sed 's/\./_/g'`
+$ echo $u $v$V
+5.1 5_2
+$ cd /tmp
+$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \
+-r gdb_$V-branch src/gdb/version.in
+cvs -f -d :ext:sources.redhat.com:/cvs/src co
+ -r gdb_5_2-branch src/gdb/version.in
+$ ^echo ^^
+U src/gdb/version.in
+$ cd src/gdb
+$ echo $u.90-0000-00-00-cvs > version.in
+$ cat version.in
+5.1.90-0000-00-00-cvs
+$ cvs -f commit version.in
+@end smallexample
+
+@itemize @bullet
+@item
+@file{0000-00-00} is used as a date to pump prime the version.in update
+mechanism
+@item
+@file{.90} and the previous branch version are used as fairly arbitrary
+initial branch version number
@end itemize
-@subheading Post the branch info
@subheading Update the web and news pages
+Something?
+
@subheading Tweak cron to track the new branch
+The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.
+This file needs to be updated so that:
+
+@itemize @bullet
+@item
+a daily timestamp is added to the file @file{version.in}
+@item
+the new branch is included in the snapshot process
+@end itemize
+
+@noindent
+See the file @file{gdbadmin/cron/README} for how to install the updated
+cron table.
+
+The file @file{gdbadmin/ss/README} should also be reviewed to reflect
+any changes. That file is copied to both the branch/ and current/
+snapshot directories.
+
+
+@subheading Update the NEWS and README files
+
+The @file{NEWS} file needs to be updated so that on the branch it refers
+to @emph{changes in the current release} while on the trunk it also
+refers to @emph{changes since the current release}.
+
+The @file{README} file needs to be updated so that it refers to the
+current release.
+
+@subheading Post the branch info
+
+Send an announcement to the mailing lists:
+
+@itemize @bullet
+@item
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
+@item
+@email{gdb@@sources.redhat.com, GDB Discsussion mailing list} and
+@email{gdb-testers@@sources.redhat.com, GDB Discsussion mailing list}
+@end itemize
+
+@emph{Pragmatics: The branch creation is sent to the announce list to
+ensure that people people not subscribed to the higher volume discussion
+list are alerted.}
+
+The announcement should include:
+
+@itemize @bullet
+@item
+the branch tag
+@item
+how to check out the branch using CVS
+@item
+the date/number of weeks until the release
+@item
+the branch commit policy
+still holds.
+@end itemize
+
@section Stabilize the branch
Something goes here.
@itemize @bullet
@item
Check the @code{autoconf} version carefully. You want to be using the
-version taken from the @file{binutils} snapshot directory. It is very
+version taken from the @file{binutils} snapshot directory, which can be
+found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very
unlikely that a system installed version of @code{autoconf} (e.g.,
@file{/usr/bin/autoconf}) is correct.
@end itemize
projects / deliverable / binutils-gdb.git / blobdiff