@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
machine-independent part of @value{GDBN}, except that it is used when
setting up a new frame from scratch, as follows:
-@example
- create_new_frame (read_register (FP_REGNUM), read_pc ()));
-@end example
+@smallexample
+create_new_frame (read_register (FP_REGNUM), read_pc ()));
+@end smallexample
@cindex frame pointer register
Other than that, all the meaning imparted to @code{FP_REGNUM} is
possible values of the enumerated data type @code{target_hw_bp_type},
defined by @file{breakpoint.h} as follows:
-@example
+@smallexample
enum target_hw_bp_type
@{
hw_write = 0, /* Common (write) HW watchpoint */
hw_access = 2, /* Access (read or write) HW watchpoint */
hw_execute = 3 /* Execute HW breakpoint */
@};
-@end example
+@end smallexample
@noindent
These two macros should return 0 for success, non-zero for failure.
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
The overall structure of the table output code is something like this:
-@example
+@smallexample
ui_out_table_begin
ui_out_table_header
@dots{}
ui_out_tuple_end
@dots{}
ui_out_table_end
-@end example
+@end smallexample
Here is the description of table-, tuple- and list-related @code{ui_out}
functions:
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, "...");
The original code was:
-@example
+@smallexample
if (!found_a_breakpoint++)
@{
annotate_breakpoints_headers ();
annotate_breakpoints_table ();
@}
-@end example
+@end smallexample
Here's the new version:
-@example
+@smallexample
nr_printable_breakpoints = @dots{};
if (addressprint)
ui_out_table_body (uiout);
if (nr_printable_breakpoints > 0)
annotate_breakpoints_table ();
-@end example
+@end smallexample
This example, from the @code{print_one_breakpoint} function, shows how
to produce the actual data for the table whose structure was defined
in the above example. The original code was:
-@example
+@smallexample
annotate_record ();
annotate_field (0);
printf_filtered ("%-3d ", b->number);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This is the new version:
-@example
+@smallexample
annotate_record ();
ui_out_tuple_begin (uiout, "bkpt");
annotate_field (0);
annotate_field (3);
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to
produce a complicated output field using the @code{print_expression}
functions which requires a stream to be passed. It also shows how to
automate stream destruction with cleanups. The original code was:
-@example
+@smallexample
annotate_field (5);
print_expression (b->exp, gdb_stdout);
-@end example
+@end smallexample
The new version is:
-@example
+@smallexample
struct ui_stream *stb = ui_out_stream_new (uiout);
struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
...
annotate_field (5);
print_expression (b->exp, stb->stream);
ui_out_field_stream (uiout, "what", local_stream);
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to use
@code{ui_out_text} and @code{ui_out_field_string}. The original code
was:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
printf_filtered ("<any library> ");
else
printf_filtered ("library \"%s\" ", b->dll_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
@{
ui_out_field_string (uiout, "what", b->dll_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
The following example from @code{print_one_breakpoint} shows how to
use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
printf_filtered ("process %d ", b->forked_inferior_pid);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
@{
ui_out_field_int (uiout, "what", b->forked_inferior_pid);
ui_out_spaces (uiout, 1);
@}
-@end example
+@end smallexample
Here's an example of using @code{ui_out_field_string}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
printf_filtered ("program \"%s\" ", b->exec_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
@{
ui_out_field_string (uiout, "what", b->exec_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
Finally, here's an example of printing an address. The original code:
-@example
+@smallexample
annotate_field (4);
printf_filtered ("%s ",
local_hex_string_custom ((unsigned long) b->address, "08l"));
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (4);
ui_out_field_core_addr (uiout, "Address", b->address);
-@end example
+@end smallexample
@section Console Printing
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
@strong{must} be included at the top of the YACC parser, to prevent the
various parsers from defining the same global names:
-@example
+@smallexample
#define yyparse @var{lang}_parse
#define yylex @var{lang}_lex
#define yyerror @var{lang}_error
#define yyexca @var{lang}_exca
#define yyerrflag @var{lang}_errflag
#define yynerrs @var{lang}_nerrs
-@end example
+@end smallexample
At the bottom of your parser, define a @code{struct language_defn} and
initialize it with the right values for your language. Define an
@code{struct gdbarch *}. The structure, and its methods, are generated
using the Bourne shell script @file{gdbarch.sh}.
+@section Operating System ABI Variant Handling
+@cindex OS ABI variants
+
+@value{GDBN} provides a mechanism for handling variations in OS
+ABIs. An OS ABI variant may have influence over any number of
+variables in the target architecture definition. There are two major
+components in the OS ABI mechanism: sniffers and handlers.
+
+A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
+(the architecture may be wildcarded) in an attempt to determine the
+OS ABI of that file. Sniffers with a wildcarded architecture are considered
+to be @dfn{generic}, while sniffers for a specific architecture are
+considered to be @dfn{specific}. A match from a specific sniffer
+overrides a match from a generic sniffer. Multiple sniffers for an
+architecture/flavour may exist, in order to differentiate between two
+different operating systems which use the same basic file format. The
+OS ABI framework provides a generic sniffer for ELF-format files which
+examines the @code{EI_OSABI} field of the ELF header, as well as note
+sections known to be used by several operating systems.
+
+@cindex fine-tuning @code{gdbarch} structure
+A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
+selected OS ABI. There may be only one handler for a given OS ABI
+for each BFD architecture.
+
+The following OS ABI variants are defined in @file{osabi.h}:
+
+@table @code
+
+@findex GDB_OSABI_UNKNOWN
+@item GDB_OSABI_UNKNOWN
+The ABI of the inferior is unknown. The default @code{gdbarch}
+settings for the architecture will be used.
+
+@findex GDB_OSABI_SVR4
+@item GDB_OSABI_SVR4
+UNIX System V Release 4
+
+@findex GDB_OSABI_HURD
+@item GDB_OSABI_HURD
+GNU using the Hurd kernel
+
+@findex GDB_OSABI_SOLARIS
+@item GDB_OSABI_SOLARIS
+Sun Solaris
+
+@findex GDB_OSABI_OSF1
+@item GDB_OSABI_OSF1
+OSF/1, including Digital UNIX and Compaq Tru64 UNIX
+
+@findex GDB_OSABI_LINUX
+@item GDB_OSABI_LINUX
+GNU using the Linux kernel
+
+@findex GDB_OSABI_FREEBSD_AOUT
+@item GDB_OSABI_FREEBSD_AOUT
+FreeBSD using the a.out executable format
+
+@findex GDB_OSABI_FREEBSD_ELF
+@item GDB_OSABI_FREEBSD_ELF
+FreeBSD using the ELF executable format
+
+@findex GDB_OSABI_NETBSD_AOUT
+@item GDB_OSABI_NETBSD_AOUT
+NetBSD using the a.out executable format
+
+@findex GDB_OSABI_NETBSD_ELF
+@item GDB_OSABI_NETBSD_ELF
+NetBSD using the ELF executable format
+
+@findex GDB_OSABI_WINCE
+@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
+
+@findex GDB_OSABI_ARM_EABI_V2
+@item GDB_OSABI_ARM_EABI_V2
+ARM Embedded ABI version 2
+
+@findex GDB_OSABI_ARM_APCS
+@item GDB_OSABI_ARM_APCS
+Generic ARM Procedure Call Standard
+
+@end table
+
+Here are the functions that make up the OS ABI framework:
+
+@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi})
+Return the name of the OS ABI corresponding to @var{osabi}.
+@end deftypefun
+
+@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch}))
+Register the OS ABI handler specified by @var{init_osabi} for the
+architecture/OS ABI pair specified by @var{arch} and @var{osabi}.
+@end deftypefun
+
+@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))
+Register the OS ABI file sniffer specified by @var{sniffer} for the
+BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
+If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
+be generic, and is allowed to examine @var{flavour}-flavoured files for
+any architecture.
+@end deftypefun
+
+@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd})
+Examine the file described by @var{abfd} to determine its OS ABI.
+The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
+be determined.
+@end deftypefun
+
+@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})
+Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
+@code{gdbarch} structure specified by @var{gdbarch}. If a handler
+corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
+architecture, a warning will be issued and the debugging session will continue
+with the defaults already established for @var{gdbarch}.
+@end deftypefun
+
@section Registers and Memory
@value{GDBN}'s model of the target machine is rather simple.
@end deftypefn
-@section Using Different Register and Memory Data Representations
-@cindex raw representation
-@cindex virtual representation
-@cindex representations, raw and virtual
-@cindex register data formats, converting
-@cindex @code{struct value}, converting register contents to
+@section Raw and Virtual Register Representations
+@cindex raw register representation
+@cindex virtual register representation
+@cindex representations, raw and virtual registers
-@emph{Maintainer's note: The way GDB manipulates registers is undergoing
-significant change. Many of the macros and functions refered to in the
-sections below are likely to be made obsolete. See the file @file{TODO}
-for more up-to-date information.}
+@emph{Maintainer note: This section is pretty much obsolete. The
+functionality described here has largely been replaced by
+pseudo-registers and the mechanisms described in @ref{Target
+Architecture Definition, , Using Different Register and Memory Data
+Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/,
+Bug Tracking Database} and
+@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more
+up-to-date information.}
Some architectures use one representation for a value when it lives in a
register, but use a different representation when it lives in memory.
the target registers, and the @dfn{virtual} representation is the one
used in memory, and within @value{GDBN} @code{struct value} objects.
+@emph{Maintainer note: Notice that the same mechanism is being used to
+both convert a register to a @code{struct value} and alternative
+register forms.}
+
For almost all data types on almost all architectures, the virtual and
raw representations are identical, and no special handling is needed.
However, they do occasionally differ. For example:
@end deftypefn
+@section Using Different Register and Memory Data Representations
+@cindex register representation
+@cindex memory representation
+@cindex representations, register and memory
+@cindex register data formats, converting
+@cindex @code{struct value}, converting register contents to
+
+@emph{Maintainer's note: The way GDB manipulates registers is undergoing
+significant change. Many of the macros and functions refered to in this
+section are likely to be subject to further revision. See
+@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and
+@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for
+further information. cagney/2002-05-06.}
+
+Some architectures can represent a data object in a register using a
+form that is different to the objects more normal memory representation.
+For example:
+
+@itemize @bullet
+
+@item
+The Alpha architecture can represent 32 bit integer values in
+floating-point registers.
+
+@item
+The x86 architecture supports 80-bit floating-point registers. The
+@code{long double} data type occupies 96 bits in memory but only 80 bits
+when stored in a register.
+
+@end itemize
+
+In general, the register representation of a data type is determined by
+the architecture, or @value{GDBN}'s interface to the architecture, while
+the memory representation is determined by the Application Binary
+Interface.
+
+For almost all data types on almost all architectures, the two
+representations are identical, and no special handling is needed.
+However, they do occasionally differ. Your architecture may define the
+following macros to request conversions between the register and memory
+representations of a data type:
+
+@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{reg})
+Return non-zero if the representation of a data value stored in this
+register may be different to the representation of that same data value
+when stored in memory.
+
+When non-zero, the macros @code{REGISTER_TO_VALUE} and
+@code{VALUE_TO_REGISTER} are used to perform any necessary conversion.
+@end deftypefn
+
+@deftypefn {Target Macro} void REGISTER_TO_VALUE (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
+Convert the value of register number @var{reg} to a data object of type
+@var{type}. The buffer at @var{from} holds the register's value in raw
+format; the converted value should be placed in the buffer at @var{to}.
+
+Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
+their @var{reg} and @var{type} arguments in different orders.
+
+You should only use @code{REGISTER_TO_VALUE} with registers for which
+the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
+@end deftypefn
+
+@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
+Convert a data value of type @var{type} to register number @var{reg}'
+raw format.
+
+Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
+their @var{reg} and @var{type} arguments in different orders.
+
+You should only use @code{VALUE_TO_REGISTER} with registers for which
+the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
+@end deftypefn
+
+@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
+See @file{mips-tdep.c}. It does not do what you want.
+@end deftypefn
+
+
@section Frame Interpretation
@section Inferior Call Setup
@code{default_coerce_float_to_double} provides this behavior; it is the
default value, for compatibility with older 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
+non-standard form.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
@item CPLUS_MARKER
@findex CPLUS_MARKERz
Define this to expand into the character that G@t{++} uses to distinguish
@findex DO_REGISTERS_INFO
If defined, use this to print the value of a register or all registers.
+This method is deprecated.
+
@item PRINT_FLOAT_INFO()
-#findex PRINT_FLOAT_INFO
+@findex PRINT_FLOAT_INFO
If defined, then the @samp{info float} command will print information about
the processor's floating point unit.
+@item print_registers_info (@var{gdbarch}, @var{frame}, @var{regnum}, @var{all})
+@findex print_registers_info
+If defined, pretty print the value of the register @var{regnum} for the
+specified @var{frame}. If the value of @var{regnum} is -1, pretty print
+either all registers (@var{all} is non zero) or a select subset of
+registers (@var{all} is zero).
+
+The default method prints one register per line, and if @var{all} is
+zero omits floating-point registers.
+
+@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,
If the virtual frame pointer is kept in a register, then define this
macro to be the number (greater than or equal to zero) of that register.
-This should only need to be defined if @code{TARGET_READ_FP} and
-@code{TARGET_WRITE_FP} are not defined.
+This should only need to be defined if @code{TARGET_READ_FP} is not
+defined.
@item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
@findex FRAMELESS_FUNCTION_INVOCATION
@findex FRAME_CHAIN
Given @var{frame}, return a pointer to the calling frame.
-@item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame})
-@findex FRAME_CHAIN_COMBINE
-Define this to take the frame chain pointer and the frame's nominal
-address and produce the nominal address of the caller's frame.
-Presently only defined for HP PA.
-
@item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
@findex FRAME_CHAIN_VALID
Define this to be an expression that returns zero if the given frame is
Define this if you need to supply your own definition for the function
@code{get_saved_register}.
-@item HAVE_REGISTER_WINDOWS
-@findex HAVE_REGISTER_WINDOWS
-Define this if the target has register windows.
-
-@item REGISTER_IN_WINDOW_P (@var{regnum})
-@findex REGISTER_IN_WINDOW_P
-Define this to be an expression that is 1 if the given register is in
-the window.
-
@item IBM6000_TARGET
@findex IBM6000_TARGET
Shows that we are configured for an IBM RS/6000 target. This
the stack frame of the function already has been destroyed up to the
final `return from function call' instruction.
-@item IN_SIGTRAMP (@var{pc}, @var{name})
-@findex IN_SIGTRAMP
-Define this to return non-zero if the given @var{pc} and/or @var{name}
-indicates that the current function is a @code{sigtramp}.
-
@item SIGTRAMP_START (@var{pc})
@findex SIGTRAMP_START
@itemx SIGTRAMP_END (@var{pc})
@item REGISTER_CONVERTIBLE (@var{reg})
@findex REGISTER_CONVERTIBLE
Return non-zero if @var{reg} uses different raw and virtual formats.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to})
+@findex REGISTER_TO_VALUE
+Convert the raw contents of register @var{regnum} into a value of type
+@var{type}.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
@item REGISTER_RAW_SIZE (@var{reg})
@findex REGISTER_RAW_SIZE
-Return the raw size of @var{reg}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+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}.
@item REGISTER_VIRTUAL_SIZE (@var{reg})
@findex 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, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_VIRTUAL_TYPE (@var{reg})
@findex REGISTER_VIRTUAL_TYPE
Return the virtual type of @var{reg}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
@findex REGISTER_CONVERT_TO_VIRTUAL
Convert the value of register @var{reg} from its raw form to its virtual
form.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
@findex REGISTER_CONVERT_TO_RAW
Convert the value of register @var{reg} from its virtual form to its raw
form.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item RETURN_VALUE_ON_STACK(@var{type})
@findex RETURN_VALUE_ON_STACK
@findex PC_IN_CALL_DUMMY
See @file{inferior.h}.
+@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
@findex NPC_REGNUM
The number of the ``next program counter'' register, if defined.
-@item NNPC_REGNUM
-@findex NNPC_REGNUM
-The number of the ``next next program counter'' register, if defined.
-Currently, this is only defined for the Motorola 88K.
-
@item PARM_BOUNDARY
@findex PARM_BOUNDARY
If non-zero, round arguments to a boundary of this many bits before
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
A C expression that returns the address of the ``real'' code beyond the
function entry prologue found at @var{pc}.
-@item SKIP_PROLOGUE_FRAMELESS_P
-@findex SKIP_PROLOGUE_FRAMELESS_P
-A C expression that should behave similarly, but that can stop as soon
-as the function is known to have a frame. If not defined,
-@code{SKIP_PROLOGUE} will be used instead.
-
@item SKIP_TRAMPOLINE_CODE (@var{pc})
@findex SKIP_TRAMPOLINE_CODE
If the target machine has trampoline code that sits between callers and
slot, @value{GDBN} will single-step over that instruction before resuming
normally. Currently only defined for the Mips.
-@item STORE_RETURN_VALUE (@var{type}, @var{valbuf})
+@item STORE_RETURN_VALUE (@var{type}, @var{regcache}, @var{valbuf})
@findex STORE_RETURN_VALUE
-A C expression that stores a function return value of type @var{type},
-where @var{valbuf} is the address of the value to be stored.
+A C expression that writes the function return value, found in
+@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
@findex TARGET_WRITE_SP
@itemx TARGET_READ_FP
@findex TARGET_READ_FP
-@itemx TARGET_WRITE_FP
-@findex TARGET_WRITE_FP
@findex read_pc
@findex write_pc
@findex read_sp
@findex write_sp
@findex read_fp
-@findex write_fp
These change the behavior of @code{read_pc}, @code{write_pc},
-@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_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{read_sp}, @code{write_sp} and @code{read_fp}. For most targets,
+these may be left undefined. @value{GDBN} will call the read and write
+register functions with the relevant @code{_REGNUM} argument.
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
for systems where GCC is known to use different calling convention than
other compilers.
+@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
+@var{regnum}'s.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
@item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
@findex VARIABLES_INSIDE_BLOCK
For dbx-style debugging information, if the compiler puts variable
@file{config/tm-@var{os}.h}.
+@section Converting an existing Target Architecture to Multi-arch
+@cindex converting targets to multi-arch
+
+This section describes the current accepted best practice for converting
+an existing target architecture to the multi-arch framework.
+
+The process consists of generating, testing, posting and committing a
+sequence of patches. Each patch must contain a single change, for
+instance:
+
+@itemize @bullet
+
+@item
+Directly convert a group of functions into macros (the conversion does
+not change the behavior of any of the functions).
+
+@item
+Replace a non-multi-arch with a multi-arch mechanism (e.g.,
+@code{FRAME_INFO}).
+
+@item
+Enable multi-arch level one.
+
+@item
+Delete one or more files.
+
+@end itemize
+
+@noindent
+There isn't a size limit on a patch, however, a developer is strongly
+encouraged to keep the patch size down.
+
+Since each patch is well defined, and since each change has been tested
+and shows no regressions, the patches are considered @emph{fairly}
+obvious. Such patches, when submitted by developers listed in the
+@file{MAINTAINERS} file, do not need approval. Occasional steps in the
+process may be more complicated and less clear. The developer is
+expected to use their judgment and is encouraged to seek advice as
+needed.
+
+@subsection Preparation
+
+The first step is to establish control. Build (with @option{-Werror}
+enabled) and test the target so that there is a baseline against which
+the debugger can be compared.
+
+At no stage can the test results regress or @value{GDBN} stop compiling
+with @option{-Werror}.
+
+@subsection Add the multi-arch initialization code
+
+The objective of this step is to establish the basic multi-arch
+framework. It involves
+
+@itemize @bullet
+
+@item
+The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The
+above is from the original example and uses K&R C. @value{GDBN}
+has since converted to ISO C but lets ignore that.} that creates
+the architecture:
+@smallexample
+static struct gdbarch *
+d10v_gdbarch_init (info, arches)
+ struct gdbarch_info info;
+ struct gdbarch_list *arches;
+@{
+ struct gdbarch *gdbarch;
+ /* there is only one d10v architecture */
+ if (arches != NULL)
+ return arches->gdbarch;
+ gdbarch = gdbarch_alloc (&info, NULL);
+ return gdbarch;
+@}
+@end smallexample
+@noindent
+@emph{}
+
+@item
+A per-architecture dump function to print any architecture specific
+information:
+@smallexample
+static void
+mips_dump_tdep (struct gdbarch *current_gdbarch,
+ struct ui_file *file)
+@{
+ @dots{} code to print architecture specific info @dots{}
+@}
+@end smallexample
+
+@item
+A change to @code{_initialize_@var{arch}_tdep} to register this new
+architecture:
+@smallexample
+void
+_initialize_mips_tdep (void)
+@{
+ gdbarch_register (bfd_arch_mips, mips_gdbarch_init,
+ mips_dump_tdep);
+@end smallexample
+
+@item
+Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@*
+@file{config/@var{arch}/tm-@var{arch}.h}.
+
+@end itemize
+
+@subsection Update multi-arch incompatible mechanisms
+
+Some mechanisms do not work with multi-arch. They include:
+
+@table @code
+@item EXTRA_FRAME_INFO
+Delete.
+@item FRAME_FIND_SAVED_REGS
+Replaced with @code{FRAME_INIT_SAVED_REGS}
+@end table
+
+@noindent
+At this stage you could also consider converting the macros into
+functions.
+
+@subsection Prepare for multi-arch level to one
+
+Temporally set @code{GDB_MULTI_ARCH} to @code{GDB_MULTI_ARCH_PARTIAL}
+and then build and start @value{GDBN} (the change should not be
+committed). @value{GDBN} may not build, and once built, it may die with
+an internal error listing the architecture methods that must be
+provided.
+
+Fix any build problems (patch(es)).
+
+Convert all the architecture methods listed, which are only macros, into
+functions (patch(es)).
+
+Update @code{@var{arch}_gdbarch_init} to set all the missing
+architecture methods and wrap the corresponding macros in @code{#if
+!GDB_MULTI_ARCH} (patch(es)).
+
+@subsection Set multi-arch level one
+
+Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a
+single patch).
+
+Any problems with throwing ``the switch'' should have been fixed
+already.
+
+@subsection Convert remaining macros
+
+Suggest converting macros into functions (and setting the corresponding
+architecture method) in small batches.
+
+@subsection Set multi-arch level to two
+
+This should go smoothly.
+
+@subsection Delete the TM file
+
+The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and
+@file{configure.in} updated.
+
+
@node Target Vector Definition
@chapter Target Vector Definition
later cleanups appended to the chain (but not yet discarded or
performed). E.g.:
-@example
+@smallexample
make_cleanup (a, 0);
@{
struct cleanup *old = make_cleanup (b, 0);
...
do_cleanups (old);
@}
-@end example
+@end smallexample
@noindent
will call @code{c()} and @code{b()} but will not call @code{a()}. The
called and a forced stack unwind occurs) by ensuring that the
@code{xfree} will always be called:
-@example
+@smallexample
struct cleanup *old = make_cleanup (null_cleanup, 0);
data = xmalloc (sizeof blah);
make_cleanup (xfree, data);
... blah blah ...
do_cleanups (old);
-@end example
+@end smallexample
The second style is try/except. Before it exits, your code-block calls
@code{discard_cleanups} with the old cleanup chain and thus ensures that
code segment, ensures that the file will be closed but only if there is
an error:
-@example
+@smallexample
FILE *file = fopen ("afile", "r");
struct cleanup *old = make_cleanup (close_file, file);
... blah blah ...
discard_cleanups (old);
return file;
-@end example
+@end smallexample
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
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
A function declaration should not have its name in column zero. A
function definition should have its name in column zero.
-@example
+@smallexample
/* Declaration */
static void foo (void);
/* Definition */
foo (void)
@{
@}
-@end example
+@end smallexample
@emph{Pragmatics: This simplifies scripting. Function definitions can
be found using @samp{^function-name}.}
Pointers are declared using the traditional K&R C style:
-@example
+@smallexample
void *foo;
-@end example
+@end smallexample
@noindent
and not:
-@example
+@smallexample
void * foo;
void* foo;
-@end example
+@end smallexample
@subsection Comments
Block comments must appear in the following form, with no @code{/*}- or
@code{*/}-only lines, and no leading @code{*}:
-@example
+@smallexample
/* Wait for control to return from inferior to debugger. If inferior
gets a signal, we may decide to start it up again instead of
returning. That is why there is a loop in this function. When
this function actually returns it means the inferior should be left
stopped and @value{GDBN} should read more commands. */
-@end example
+@end smallexample
(Note that this format is encouraged by Emacs; tabbing for a multi-line
comment works correctly, and @kbd{M-q} fills the block consistently.)
@subsection Include Files
-All @file{.c} files should include @file{defs.h} first.
+A @file{.c} file should include @file{defs.h} first.
+
+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.
-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{.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.
-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.
+An external declaration should only appear in one include file.
-@code{extern} declarations should never appear in @code{.c} files.
+An external declaration should never appear in a @code{.c} file.
+Exception: a declaration for the @code{_initialize} function that
+pacifies @option{-Wmissing-declaration}.
-All include files should be wrapped in:
+A @code{typedef} definition should only appear in one include file.
-@example
+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
#define INCLUDE_FILE_NAME_H
header body
#endif
-@end example
+@end smallexample
@subsection Clean Design and Portable Implementation
such hosts.
@findex IS_DIR_SEPARATOR
-@item IS_DIR_SEPARATOR (@var{c}
+@item IS_DIR_SEPARATOR (@var{c})
Evaluates to a non-zero value if @var{c} is a directory separator
character. On Unix and GNU/Linux systems, only a slash @file{/} is
such a character, but on Windows, both @file{/} and @file{\} will
@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
running
-@example
+@smallexample
./config.sub @var{xyz}
-@end example
+@end smallexample
@noindent
and
-@example
+@smallexample
./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
-@end example
+@end smallexample
@noindent
which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
From the top level directory (containing @file{gdb}, @file{bfd},
@file{libiberty}, and so on):
-@example
+@smallexample
make -f Makefile.in gdb.tar.gz
-@end example
+@end smallexample
@noindent
This will properly configure, clean, rebuild any files that are
Releases 5.0 and 5.1 used branch and release tags of the form:
-@example
+@smallexample
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-YYYY-MM-DD-branch
gdb_M_N-YYYY-MM-DD-release
-@end example
+@end smallexample
Release 5.2 is trialing the branch and release tags:
-@example
+@smallexample
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-branch
gdb_M_N-YYYY-MM-DD-release
-@end example
+@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
@item
Don't fix something on the branch unless/until it is also fixed in the
trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
-file is better than committing a hack
+file is better than committing a hack.
@item
When considering a patch for the branch, suggested criteria include:
Does it fix a build? Does it fix the sequence @kbd{break main; run}
reason) support for a new host are considered acceptable.}
-@section Obsolete any code
+@section Obsoleting code
Before anything else, poke the other developers (and around the source
-code) to see there is anything that can be removed from @value{GDBN} (an
-old target, an unused file).
+code) to see if there is anything that can be removed from @value{GDBN}
+(an old target, an unused file).
Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
-line. Doing this means that it is easy to identify obsolete code when
-grepping through the sources.
+line. Doing this means that it is easy to identify something that has
+been obsoleted when greping through the sources.
-The process has a number of steps and is intentionally slow --- this is
-to mainly ensure that people have had a reasonable chance to respond.
-Remember, everything on the internet takes a week.
+The process is done in stages --- this is mainly to ensure that the
+wider @value{GDBN} community has a reasonable opportunity to respond.
+Remember, everything on the Internet takes a week.
-@itemize @bullet
+@enumerate
@item
-announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}
+Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing
+list} Creating a bug report to track the task's state, is also highly
+recommended.
@item
-wait a week or so
+Wait a week or so.
@item
-announce the change on @email{gdb-announce@@sources.redhat.com, GDB
-Announcement mailing list}
+Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
+Announcement mailing list}.
@item
-wait a week or so
+Wait a week or so.
@item
-go through and edit all relevant files and lines (e.g., in
-@file{configure.tgt}) so that they are prefixed with the word
-@code{OBSOLETE}.
-@end itemize
+Go through and edit all relevant files and lines so that they are
+prefixed with the word @code{OBSOLETE}.
+@item
+Wait until the next GDB version, containing this obsolete code, has been
+released.
+@item
+Remove the obsolete code.
+@end enumerate
+
+@noindent
+@emph{Maintainer note: While removing old code is regrettable it is
+hopefully better for @value{GDBN}'s long term development. Firstly it
+helps the developers by removing code that is either no longer relevant
+or simply wrong. Secondly since it removes any history associated with
+the file (effectively clearing the slate) the developer has a much freer
+hand when it comes to fixing broken files.}
-@emph{Maintainer note: Removing old code, while regrettable, is a good
-thing. Firstly it helps the developers by removing code that is either
-no longer relevant or simply wrong. Secondly since it removes any
-history associated with the file (effectively clearing the slate) the
-developer has a much freer hand when it comes to fixing broken files.}
-@section Before the branch
+
+@section Before the Branch
The most important objective at this stage is to find and fix simple
changes that become a pain to track once the branch is created. For
building. If you can't get the problem fixed, document it in the
@file{gdb/PROBLEMS} file.
-@subheading Organize and announce the schedule.
+@subheading Prompt for @file{gdb/NEWS}
+
+People always forget. Send a post reminding them but also if you know
+something interesting happened add it yourself. The @code{schedule}
+script will mention this in its e-mail.
-The following is a possible schedule. It is based on the rule-of-thumb
-that everything on the Internet takes a week. You may want to even
-increase those times further since an analysis of the actual data
-strongly suggests that the below is far to aggressive.
+@subheading Review @file{gdb/README}
+
+Grab one of the nightly snapshots and then walk through the
+@file{gdb/README} looking for anything that can be improved. The
+@code{schedule} script will mention this in its e-mail.
+
+@subheading Refresh any imported files.
+
+A number of files are taken from external repositories. They include:
@itemize @bullet
@item
-announce it
+@file{texinfo/texinfo.tex}
@item
-wait a week
+@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
+file)
@item
-announce branch date
+@file{etc/standards.texi}, @file{etc/make-stds.texi}
+@end itemize
+
+@subheading Check the ARI
+
+@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script
+(Awk Regression Index ;-) that checks for a number of errors and coding
+conventions. The checks include things like using @code{malloc} instead
+of @code{xmalloc} and file naming problems. There shouldn't be any
+regressions.
+
+@subsection Review the bug data base
+
+Close anything obviously fixed.
+
+@subsection Check all cross targets build
+
+The targets are listed in @file{gdb/MAINTAINERS}.
+
+
+@section Cut the Branch
+
+@subheading Create the branch
+
+@smallexample
+$ 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
-wait a week
+by using @kbd{-D YYYY-MM-DD-gmt} the branch is forced to an exact
+date/time.
@item
-Cut the branch
+the trunk is first taged so that the branch point can easily be found
@item
-wait a week
+Insight (which includes GDB) and dejagnu are all tagged at the same time
@item
-start enjoying all the fun
+@file{version.in} gets bumped to avoid version number conflicts
+@item
+the reading of @file{.cvsrc} is disabled using @file{-f}
@end itemize
-As an aside, the branch tag name is probably regrettable vis:
-@example
-gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}
-@end example
-
-@subheading Refresh any imported files.
+@subheading Update @file{version.in}
-A number of files are taken from external repositories. They include:
+@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{texinfo/texinfo.tex}
+@file{0000-00-00} is used as a date to pump prime the version.in update
+mechanism
@item
-@file{config.guess} et.@: al.@:
+@file{.90} and the previous branch version are used as fairly arbitrary
+initial branch version number
@end itemize
-and should be refreshed.
-@subheading Prompt for @file{gdb/NEWS}
+@subheading Update the web and news pages
-People always forget. Send a post reminding them but also if you know
-something interesting happened add it your self.
+Something?
-@subheading Review @file{gdb/README}
+@subheading Tweak cron to track the new branch
-Grab one of the nightly snapshots and then walk through the
-@file{gdb/README} looking for anything that can be improved.
+The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.
+This file needs to be updated so that:
-@subheading Check the ARI
+@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
-ARI is an @code{awk} script (Awk Regression Indicator?) that checks for a
-number of errors and coding conventions. The checks include things like
-using @code{malloc} instead of @code{xmalloc} and file naming problems.
-There shouldn't be any regressions.
+@noindent
+See the file @file{gdbadmin/cron/README} for how to install the updated
+cron table.
-@section Cut the branch
+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 The dirty work
-I think something like the below was used:
+@subheading Update the NEWS and README files
-@example
-$ 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
-$
-@end example
+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
-the @kbd{-D YYYY-MM-DD-gmt} forces the branch to an exact date/time.
-@item
-the trunk is first tagged so that the branch point can easily be found
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
@item
-Insight (which includes GDB) and dejagnu are tagged at the same time
+@email{gdb@@sources.redhat.com, GDB Discsussion mailing list} and
+@email{gdb-testers@@sources.redhat.com, GDB Discsussion mailing list}
@end itemize
-@subheading Post the branch info
+@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.}
-@subheading Update the web and news pages
+The announcement should include:
-@subheading Tweak cron to track the new branch
+@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
@section Create a Release
-This procedure can be followed when creating beta and final final
-releases. With a beta many of the steps can be skipped.
+The process of creating and then making available a release is broken
+down into a number of stages. The first part addresses the technical
+process of creating a releasable tar ball. The later stages address the
+process of releasing that tar ball.
+
+When making a release candidate just the first section is needed.
+
+@subsection Create a release candidate
+
+The objective at this stage is to create a set of tar balls that can be
+made available as a formal release (or as a less formal release
+candidate).
-@subheading Establish a few defaults.
+@subsubheading Freeze the branch
-@example
-$ b=gdb_5_1-2001-07-29-branch
-$ v=5.1.1
+Send out an e-mail notifying everyone that the branch is frozen to
+@email{gdb-patches@@sources.redhat.com}.
+
+@subsubheading Establish a few defaults.
+
+@smallexample
+$ b=gdb_5_2-branch
+$ v=5.2
$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
$ echo $t/$b/$v
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
$ mkdir -p $t/$b/$v
$ cd $t/$b/$v
$ pwd
-/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_1-2001-07-29-branch/5.1.1
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
$ which autoconf
/home/gdbadmin/bin/autoconf
$
-@end example
+@end smallexample
-NB: Check the autoconf version carefully. You want to be using the
-version taken from the binutils snapshot directory. It is most likely
-that your system's installed version (@file{/usr/bin}?) is probably
-correct.
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+Check the @code{autoconf} version carefully. You want to be using the
+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
-@subheading Check out the relevant modules:
+@subsubheading Check out the relevant modules:
-@example
+@smallexample
$ for m in gdb insight dejagnu
do
( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
done
$
-@end example
+@end smallexample
-NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there
-isn't any confusion between what is written here and what your local CVS
-really does.
+@noindent
+Note:
-@subheading Update relevant files.
+@itemize @bullet
+@item
+The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't
+any confusion between what is written here and what your local
+@code{cvs} really does.
+@end itemize
-@subsubheading @file{gdb/NEWS}
+@subsubheading Update relevant files.
+
+@table @file
+
+@item gdb/NEWS
Major releases get their comments added as part of the mainline. Minor
releases should probably mention any significant bugs that were fixed.
-Don't forget to update the ChangeLog.
+Don't forget to include the @file{ChangeLog} entry.
-@example
+@smallexample
$ emacs gdb/src/gdb/NEWS
...
c-x 4 a
c-x c-s c-x c-c
$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-@end example
+@end smallexample
-@subsubheading @file{gdb/README}
+@item gdb/README
-You'll need to update: the version, the update date, and who did it.
+You'll need to update:
-@example
+@itemize @bullet
+@item
+the version
+@item
+the update date
+@item
+who did it
+@end itemize
+
+@smallexample
$ emacs gdb/src/gdb/README
...
c-x 4 a
c-x c-s c-x c-c
$ cp gdb/src/gdb/README insight/src/gdb/README
$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-@end example
+@end smallexample
-@emph{Maintainer note: Hopefully the README file was reviewed before the
-initial branch was cut so just a simple substitute is needed to get it
-updated.}
+@emph{Maintainer note: Hopefully the @file{README} file was reviewed
+before the initial branch was cut so just a simple substitute is needed
+to get it updated.}
@emph{Maintainer note: Other projects generate @file{README} and
@file{INSTALL} from the core documentation. This might be worth
pursuing.}
-@subsubheading @file{gdb/version.in}
+@item gdb/version.in
-@example
+@smallexample
$ echo $v > gdb/src/gdb/version.in
+$ cat gdb/src/gdb/version.in
+5.2
$ emacs gdb/src/gdb/version.in
...
c-x 4 a
-...
+... Bump to version ...
c-x c-s c-x c-c
$ cp gdb/src/gdb/version.in insight/src/gdb/version.in
$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
-@end example
+@end smallexample
-@subsubheading @file{dejagnu/src/dejagnu/configure.in}
+@item dejagnu/src/dejagnu/configure.in
Dejagnu is more complicated. The version number is a parameter to
-@var{AM_INIT_AUTOMAKE}. Tweak it to read something like
-@var{gdb-5.1.1}.
+@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
-Re-generate configure.
+Don't forget to re-generate @file{configure}.
-Add a ChangeLog.
+Don't forget to include a @file{ChangeLog} entry.
-@subheading Do the dirty work
+@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
-This is identical to the process used when creating the daily snapshot.
+@end table
-@example
-$ for m in gdb insight dejagnu
+@subsubheading Do the dirty work
+
+This is identical to the process used to create the daily snapshot.
+
+@smallexample
+$ for m in gdb insight
do
-( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+( cd $m/src && gmake -f Makefile.in $m.tar )
done
-@end example
+$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+@end smallexample
-@subheading Check the source files
+@subsubheading Check the source files
-You're looking for files that have mysteriously disappeared as the
+You're looking for files that have mysteriously disappeared.
@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
for the @file{version.in} update @kbd{cronjob}.
-@example
+@smallexample
$ ( cd gdb/src && cvs -f -q -n update )
M djunpack.bat
+? gdb-5.1.91.tar
? proto-toplev
-? gdb-5.1.1.tar.bz2
+@dots{} lots of generated files @dots{}
M gdb/ChangeLog
M gdb/NEWS
M gdb/README
M gdb/version.in
-? gdb/p-exp.tab.c
-? gdb/doc/gdb.info-11
-? gdb/doc/gdb.info-12
-? gdb/doc/gdb.info-13
-? gdb/doc/gdb.info-14
-? gdb/doc/gdb.info-15
-? gdb/doc/gdbint.info-4
-? gdb/doc/gdbint.info-5
+@dots{} lots of generated files @dots{}
$
-@end example
+@end smallexample
+@noindent
@emph{Don't worry about the @file{gdb.info-??} or
@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1}
was also generated only something strange with CVS means that they
didn't get supressed). Fixing it would be nice though.}
-@subheading Re-pack the release with @code{gzip}
+@subsubheading Create compressed versions of the release
-@example
-$ cp */*/*.bz2 .
-$ bunzip2 -k -v *.bz2
-$ gzip -9 -v *.tar
-@end example
+@smallexample
+$ 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
+$ for m in gdb insight
+do
+bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
+gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
+done
+$
+@end smallexample
-NB: A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} shouldn't
-be used since, in that mode, gzip doesn't know the file name information
-and consequently can't include it. This is also why the release process
-runs @code{tar} and @code{bzip2} as separate passes.
+@noindent
+Note:
-@emph{Maintainer note: The release process could be changed to create
-@file{.tar} rather than @file{.tar.bz2} files.}
+@itemize @bullet
+@item
+A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since,
+in that mode, @code{gzip} does not know the name of the file and, hence,
+can not include it in the compressed file. This is also why the release
+process runs @code{tar} and @code{bzip2} as separate passes.
+@end itemize
-@section Check the release
+@subsection Sanity check the tar ball
-Grab the @file{gdb.tar.bz2}, copy it to your local machine and then try
-a simple build using it.
+Pick a popular machine (Solaris/PPC?) and try the build on that.
-If this is a pre-release just copy the @file{.bz2} files to the snapshot
-directory and skip the remaining steps.
+@smallexample
+$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
+$ cd gdb-5.2
+$ ./configure
+$ make
+@dots{}
+$ ./gdb/gdb ./gdb/gdb
+GNU gdb 5.2
+@dots{}
+(gdb) b main
+Breakpoint 1 at 0x80732bc: file main.c, line 734.
+(gdb) run
+Starting program: /tmp/gdb-5.2/gdb/gdb
+
+Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
+734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
+(gdb) print args
+$1 = @{argc = 136426532, argv = 0x821b7f0@}
+(gdb)
+@end smallexample
-If it is a final release, also make it available under a bogus name so
-that others can download and check it.
+@subsection Make a release candidate available
-@emph{Maintainer note: This adds an extra day to the release process but
-is very much worth it. Other developers are given the opportunity to
-check that things like your @file{NEWS} entries are correct or that
-other changes actually work.}
+If this is a release candidate then the only remaining steps are:
-@section Release the tar ball
+@enumerate
+@item
+Commit @file{version.in} and @file{ChangeLog}
+@item
+Tweak @file{version.in} (and @file{ChangeLog} to read
+@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update
+process can restart.
+@item
+Make the release candidate available in
+@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch}
+@item
+Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and
+@email{gdb-testers@@sources.redhat.com} that the candidate is available.
+@end enumerate
+
+@subsection Make a formal release available
-This is where, unfortunately, the notes just get vague.
+(And you thought all that was required was to post an e-mail.)
-@subheading Install on sware
+@subsubheading Install on sware
-@example
+Copy the new files to both the release and the old release directory:
+
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
-@end example
+@end smallexample
+
+@noindent
+Clean up the releases directory so that only the most recent releases
+are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
+
+@smallexample
+$ cd ~ftp/pub/gdb/releases
+$ rm @dots{}
+@end smallexample
+
+@noindent
+Update the file @file{README} and @file{.message} in the releases
+directory:
+
+@smallexample
+$ vi README
+@dots{}
+$ rm -f .message
+$ ln README .message
+@end smallexample
-@subheading Create and update the web pages.
+@subsubheading Update the web pages.
-Try the following:
+@table @file
+@item htdocs/download/ANNOUNCEMENT
+This file, which is posted as the official announcement, includes:
@itemize @bullet
@item
-create the directory @file{htdocs/@var{version}} (e.g., @file{htdocs/5.1.1}
-@item
-copy @file{index.html} and @file{ANNOUNCE} from the previous release
-into the @file{htdocs/@var{version}} directory and edit for content.
-Things like the MD5 sums, @kbd{ls -l} output, the version number and so
-on will need updating. Add NEWS entries to the @file{ANNOUNCE}. This
-ensures that the previous announcement is kept somewhere handy.
+General announcement
@item
-copy the @file{NEWS} from the distro into the
-@file{htdocs/@var{version}} directory, trim down to just the most recent
-news items
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
@item
-Add a short (identical) announcement to both @file{htdocs/index.html}
-and @file{htdocs/news/index.html}
+Errata
+@end itemize
+
+@item htdocs/index.html
+@itemx htdocs/news/index.html
+@itemx htdocs/download/index.html
+These files include:
+@itemize @bullet
@item
-edit the script @file{htdocs/index.sh} to link in the new release
-number. Run it across all @file{index.html} files vis @kbd{./index.sh
-index.html */index.html}.
+announcement of the most recent release
@item
-grep the @file{htdocs} tree for references to the previous release
-version (@file{htdocs/download/index.html})
+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}.
-@emph{Maintainer note: This step is too fragile --- it is too easy to
-mis one of the entries and forget to update it.}
-
-@subheading Generate online docs
-
+@item download/onlinedocs/
You need to find the magic command that is used to generate the online
docs from the @file{.tar.bz2}. The best way is to look in the output
-from one of the nightly cronjobs and then just edit accordingly.
+from one of the nightly @code{cron} jobs and then just edit accordingly.
Something like:
-@example
+@smallexample
$ ~/ss/update-web-docs \
- ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/download/onlinedocs \
+ gdb
+@end smallexample
+
+@item download/ari/
+Just like the online documentation. Something like:
+
+@smallexample
+$ /bin/sh ~/ss/update-web-ari \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
$PWD/www \
- /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \
+ /www/sourceware/htdocs/gdb/download/ari \
gdb
-@end example
+@end smallexample
+
+@end table
-@subheading Something about @file{ANNOUNCEMENT}
+@subsubheading Shadow the pages onto gnu
+
+Something goes here.
-Send the @file{ANNOUNCEMENT} file you created above to:
+
+@subsubheading Install the @value{GDBN} tar ball on GNU
+
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb}.
+
+@subsubheading Make the @file{ANNOUNCEMENT}
+
+Post the @file{ANNOUNCEMENT} file you created above to:
@itemize @bullet
@item
@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
@item
-The gnu announce list (but delay it a day or so to let things get out).
+@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a
+day or so to let things get out)
+@item
+@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}
@end itemize
-@subheading Install it on GNU
+@subsection Cleanup
-At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
-@file{~ftp/gnu/gdb} (I think, I'm still waiting for it to copy into my
-home directory).
-
-@section Cleanup
+The release is out but you're still not finished.
-@subheading Commit outstanding changes
+@subsubheading Commit outstanding changes
-In particular you'll need to commit the changes to:
+In particular you'll need to commit any changes to:
@itemize @bullet
@item
@file{gdb/README}
@end itemize
-@subheading Tag the release
+@subsubheading Tag the release
Something like:
-@example
+@smallexample
$ d=`date -u +%Y-%m-%d`
$ echo $d
2002-01-24
$ ( cd insight/src/gdb && cvs -f -q update )
-$ ( cd insight/src && cvs -f -q tag gdb_5_1_1-$d-release )
-@end example
+$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
+@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).
-Insight is used since that contains more of the release than GDB (yes
-dejagnu doesn't get tagged but I think we can live with that.).
+@subsubheading Mention the release on the trunk
-@subheading Restart @file{gdb/version.in}
+Just put something in the @file{ChangeLog} so that the trunk also
+indicates when the release was made.
+
+@subsubheading Restart @file{gdb/version.in}
If @file{gdb/version.in} does not contain an ISO date such as
@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
committed all the release changes it can be set to
-@file{5.1.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
+@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
is important - it affects the snapshot process).
Don't forget the @file{ChangeLog}.
-@subheading Merge into trunk
+@subsubheading Merge into trunk
The files committed to the branch may also need changes merged into the
trunk.
+@subsubheading Revise the release schedule
+
+Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB
+Discussion List} with an updated announcement. The schedule can be
+generated by running:
+
+@smallexample
+$ ~/ss/schedule `date +%s` schedule
+@end smallexample
+
+@noindent
+The first parameter is approximate date/time in seconds (from the epoch)
+of the most recent release.
+
+Also update the schedule @code{cronjob}.
+
@section Post release
Remove any @code{OBSOLETE} code.
and a mention of any unexpected passes or fails. When the testsuite is
finished, you'll get a summary that looks like this:
-@example
+@smallexample
=== gdb Summary ===
# of expected passes 6016
# of expected failures 183
# of unresolved testcases 3
# of untested testcases 5
-@end example
+@end smallexample
The ideal test run consists of expected passes only; however, reality
conspires to keep us from this ideal. Unexpected failures indicate
Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
is so old that it has never been converted to use BFD. Now that's old!
-@item PYRAMID_CONTROL_FRAME_DEBUGGING
-pyr-xdep.c
-@item PYRAMID_CORE
-pyr-xdep.c
-@item PYRAMID_PTRACE
-pyr-xdep.c
-
-@item REG_STACK_SEGMENT
-exec.c
-
@end table
@include fdl.texi