@include gdb-cfg.texi
@dircategory Programming & development tools.
@direntry
-START-INFO-DIR-ENTRY
* Gdb-Internals: (gdbint). The GNU debugger's internals.
-END-INFO-DIR-ENTRY
@end direntry
@ifinfo
This file documents the internals of the GNU debugger @value{GDBN}.
-Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
+Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003
Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
-Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
-Texts as in (a) below.
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
- Free Software Foundation, Inc.
+Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,
+ 2002, 2003 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
-Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
-Texts as in (a) below.
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end titlepage
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@iftex
@contents
-@end iftex
@node Top
@c Perhaps this should be the title of the document (but only for info,
* Overall Structure::
* Algorithms::
* User Interface::
+* libgdb::
* Symbol Handling::
* Language Support::
* Host Definition::
* Support Libraries::
* Coding::
* Porting GDB::
+* Releasing GDB::
* Testsuite::
* Hints::
+
+* GNU Free Documentation License:: The license for this documentation
* Index::
@end menu
@value{GDBN} should be relatively permissive, such as for expressions.
While the compiler should be picky (or have the option to be made
-picky), since source code lives for a long time usuazlly, the
+picky), since source code lives for a long time usually, the
programmer doing debugging shouldn't be spending time figuring out to
mollify the debugger.
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
imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
any value that is convenient for the code that creates new frames.
-(@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
-defined; that is where you should use the @code{FP_REGNUM} value, if
-your frames are nonstandard.)
+(@code{create_new_frame} calls @code{DEPRECATED_INIT_EXTRA_FRAME_INFO}
+if it is defined; that is where you should use the @code{FP_REGNUM}
+value, if your frames are nonstandard.)
@cindex frame chain
Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the
-address of the calling function's frame. This will be used to create
-a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO}
-and @code{INIT_FRAME_PC} will be called for the new frame.
+address of the calling function's frame. This will be used to create a
+new @value{GDBN} frame struct, and then
+@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} and
+@code{DEPRECATED_INIT_FRAME_PC} will be called for the new frame.
@section Breakpoint Handling
Since they depend on hardware resources, hardware breakpoints may be
limited in number; when the user asks for more, @value{GDBN} will
start trying to set software breakpoints. (On some architectures,
-notably the 32-bit x86 platforms, @value{GDBN} cannot alsways know
+notably the 32-bit x86 platforms, @value{GDBN} cannot always know
whether there's enough hardware resources to insert all the hardware
breakpoints and watchpoints. On those platforms, @value{GDBN} prints
an error message only when the program being debugged is continued.)
instruction, single-step, re-insert the trap, and continue on.
Since it literally overwrites the program being tested, the program area
-must be writeable, so this technique won't work on programs in ROM. It
+must be writable, so this technique won't work on programs in ROM. It
can also distort the behavior of programs that examine themselves,
although such a situation would be highly unusual.
the page-level memory protection that implements hardware watchpoints
on that platform.
-@findex TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT
-@item TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (@var{pid},@var{start},@var{len})
-Some addresses may not be profitable to use hardware to watch, or may
-be difficult to understand when the addressed object is out of scope,
-and hence should not be watched with hardware watchpoints. On some
-targets, this may have severe performance penalties, such that we
-might as well use regular watchpoints, and save (possibly precious)
-hardware watchpoints for other locations.
-
@findex target_insert_watchpoint
@findex target_remove_watchpoint
@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
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.
region for the same access types; if found, it just increments the
reference count of that debug register, thus implementing debug
register sharing between watchpoints. If no such register is found,
-the function looks for a vacant debug register, sets its mirrorred
-value to @var{addr}, sets the mirrorred value of DR7 Debug Control
+the function looks for a vacant debug register, sets its mirrored
+value to @var{addr}, sets the mirrored value of DR7 Debug Control
register as appropriate for the @var{len} and @var{type} parameters,
and then passes the new values of the debug register and DR7 to the
inferior by calling @code{I386_DR_LOW_SET_ADDR} and
each debug register.
@code{i386_remove_watchpoint} does the opposite: it resets the address
-in the mirrorred value of the debug register and its read/write and
-length bits in the mirrorred value of DR7, then passes these new
+in the mirrored value of the debug register and its read/write and
+length bits in the mirrored value of DR7, then passes these new
values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several
watchpoints, each time a @code{i386_remove_watchpoint} is called, it
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
return value from @code{add_com} or @code{add_cmd} to deprecate the
command immediately after it is created.
-The first time a comamnd is used the user will be warned and offered a
+The first time a command is used the user will be warned and offered a
replacement (if one exists). Note that the replacement string passed to
@code{deprecate_cmd} should be the full name of the command, i.e. the
entire string the user should type at the command line.
parsing by programs which read @value{GDBN}'s output
@item
-annotation, whose purpose is to help a GUI (such as GDBTK or Emacs) to
-identify interesting parts in the output
+annotation, whose purpose is to help legacy GUIs to identify interesting
+parts in the output
@end itemize
The @code{ui_out} routines take care of the first three aspects.
-Annotations are provided by separate annotation routines. Note that
-use of annotations for an interface between a GUI and @value{GDBN} is
+Annotations are provided by separate annotation routines. Note that use
+of annotations for an interface between a GUI and @value{GDBN} is
deprecated.
-Output can be in the form of a single item, which we call a
-@dfn{field}; a @dfn{list} of fields; or a @dfn{table}, which is a list
-of fields with a header. In a BNF-like form:
+Output can be in the form of a single item, which we call a @dfn{field};
+a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
+non-identical fields; or a @dfn{table}, which is a tuple consisting of a
+header and a body. In a BNF-like form:
-@example
-<field> ::= any single item of data kept by gdb ;;
-
-<list> ::= @{ <field> @} ;;
-
-<table> ::= <header> @{ <list> @} ;;
-
-<header> ::= @{ <column> @} ;;
-
-<column> ::= <width> <alignment> <title> ;;
-@end example
+@table @code
+@item <table> @expansion{}
+@code{<header> <body>}
+@item <header> @expansion{}
+@code{@{ <column> @}}
+@item <column> @expansion{}
+@code{<width> <alignment> <title>}
+@item <body> @expansion{}
+@code{@{<row>@}}
+@end table
@subsection General Conventions
-All @code{ui_out} routines currently are of type @code{void}, except
-for @code{ui_out_stream_new} which returns a pointer to the newly
-created object.
+Most @code{ui_out} routines are of type @code{void}, the exceptions are
+@code{ui_out_stream_new} (which returns a pointer to the newly created
+object) and the @code{make_cleanup} routines.
-The first parameter is always the @code{ui_out} vector object, a
-pointer to a @code{struct ui_out}.
+The first parameter is always the @code{ui_out} vector object, a pointer
+to a @code{struct ui_out}.
-The @var{format} parameter is like in @code{printf} family of
-functions. When it is present, there is usually also a variable list
-of arguments used to satisfy the @code{%} specifiers in the supplied
+The @var{format} parameter is like in @code{printf} family of functions.
+When it is present, there must also be a variable list of arguments
+sufficient used to satisfy the @code{%} specifiers in the supplied
format.
-When a character string argument is not used in a @code{ui_out}
-function call, a @code{NULL} pointer has to be supplied instead.
+When a character string argument is not used in a @code{ui_out} function
+call, a @code{NULL} pointer has to be supplied instead.
-@subsection Table and List Functions
+@subsection Table, Tuple and List Functions
@cindex list output functions
@cindex table output functions
-This section introduces @code{ui_out} routines for building lists and
-tables. The routines to output the actual data items (fields) are
-presented in the next section.
-
-To recap: A @dfn{list} is a sequence of @dfn{fields} with information
-about an object; a @dfn{table} is a list of lists, each on a separate
-line, prefixed by a @dfn{header} line with the column @dfn{titles}.
-
-Use the table functions if your output is composed of a list of fields
-for several objects and the console output should have a header. Use
-this even when you are listing just one object but you still want the
-header.
+@cindex tuple output functions
+This section introduces @code{ui_out} routines for building lists,
+tuples and tables. The routines to output the actual data items
+(fields) are presented in the next section.
-Use the list functions for the output of each object of a table or if
-your output consists of a single list of fields.
+To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
+containing information about an object; a @dfn{list} is a sequence of
+fields where each field describes an identical object.
-You can nest a list into a table, but not the other way around.
+Use the @dfn{table} functions when your output consists of a list of
+rows (tuples) and the console output should include a heading. Use this
+even when you are listing just one object but you still want the header.
@cindex nesting level in @code{ui_out} functions
-Lists can also be nested: some of your fields may be lists or
-@dfn{tuples}--@code{@{@var{name},@var{value}@}} pairs. The maximum
-nesting level is currently 4.
+Tables can not be nested. Tuples and lists can be nested up to a
+maximum of five levels.
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_table_body
- ui_out_list_begin
+ ui_out_tuple_begin
ui_out_field_*
- ...
- ui_out_list_end
- ...
+ @dots{}
+ ui_out_tuple_end
+ @dots{}
ui_out_table_end
-@end example
+@end smallexample
-Here's the description of table- and list-related @code{ui_out}
+Here is the description of table-, tuple- and list-related @code{ui_out}
functions:
-@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, char *@var{tblid})
-The function @code{ui_out_table_begin} marks the beginning of the
-output of a table. It should always be called before any other
-@code{ui_out} function for a given table. @var{nbrofcols} is the
-number of columns in the table, and @var{tblid} is an optional string
-identifying the table. The string pointed to by @var{tblid} is copied
-by the implementation of @code{ui_out_table_begin}, so the application
-can free the string if it was @code{malloc}ed.
+@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
+The function @code{ui_out_table_begin} marks the beginning of the output
+of a table. It should always be called before any other @code{ui_out}
+function for a given table. @var{nbrofcols} is the number of columns in
+the table. @var{nr_rows} is the number of rows in the table.
+@var{tblid} is an optional string identifying the table. The string
+pointed to by @var{tblid} is copied by the implementation of
+@code{ui_out_table_begin}, so the application can free the string if it
+was @code{malloc}ed.
The companion function @code{ui_out_table_end}, described below, marks
the end of the table's output.
@end deftypefun
-@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, char *@var{colhdr})
-@code{ui_out_table_header} provides the header information for a
-single table column. You call this function several times, one each
-for every column of the table, after @code{ui_out_table_begin}, but
-before @code{ui_out_table_body}.
+@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
+@code{ui_out_table_header} provides the header information for a single
+table column. You call this function several times, one each for every
+column of the table, after @code{ui_out_table_begin}, but before
+@code{ui_out_table_body}.
The value of @var{width} gives the column width in characters. The
value of @var{alignment} is one of @code{left}, @code{center}, and
@code{right}, and it specifies how to align the header: left-justify,
center, or right-justify it. @var{colhdr} points to a string that
specifies the column header; the implementation copies that string, so
-column header strings in @code{malloc}ed storage can be freed after
-the call.
+column header strings in @code{malloc}ed storage can be freed after the
+call.
@end deftypefun
@deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
-This function marks the end of header information and the beginning of
-table body output. It doesn't by itself produce any data output; that
-is done by the list and field output functions described below.
+This function delimits the table header from the table body.
@end deftypefun
@deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
-This function signals the end of a table's output. It should be
-called after the table body has been produced by the list and field
-output functions.
+This function signals the end of a table's output. It should be called
+after the table body has been produced by the list and field output
+functions.
There should be exactly one call to @code{ui_out_table_end} for each
-call to @code{ui_out_table_begin}, otherwise the @code{ui_out}
-functions will signal an internal error.
+call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
+will signal an internal error.
@end deftypefun
-The output of the lists that represent the table rows must follow the
+The output of the tuples that represent the table rows must follow the
call to @code{ui_out_table_body} and precede the call to
-@code{ui_out_table_end}. You produce the lists by calling
-@code{ui_out_list_begin} and @code{ui_out_list_end}, with suitable
+@code{ui_out_table_end}. You build a tuple by calling
+@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
calls to functions which actually output fields between them.
-@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, char *@var{lstid})
-This function marks the beginning or a list output. @var{lstid}
-points to an optional string that identifies the list; it is copied by
-the implementation, and so strings in @code{malloc}ed storage can be
-freed after the call.
+@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
+This function marks the beginning of a tuple output. @var{id} points
+to an optional string that identifies the tuple; it is copied by the
+implementation, and so strings in @code{malloc}ed storage can be freed
+after the call.
+@end deftypefun
+
+@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
+This function signals an end of a tuple output. There should be exactly
+one call to @code{ui_out_tuple_end} for each call to
+@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
+be signaled.
+@end deftypefun
+
+@deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
+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:
+@smallexample
+struct cleanup *old_cleanup;
+ui_out_tuple_begin (uiout, "...");
+old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
+ uiout);
+@end smallexample
+@end deftypefun
+
+@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
+This function marks the beginning of a list output. @var{id} points to
+an optional string that identifies the list; it is copied by the
+implementation, and so strings in @code{malloc}ed storage can be freed
+after the call.
@end deftypefun
@deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
-This function signals an end of a list output. There should be
-exactly one call to @code{ui_out_list_end} for each call to
-@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error
-will be signaled.
+This function signals an end of a list output. There should be exactly
+one call to @code{ui_out_list_end} for each call to
+@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
+be signaled.
+@end deftypefun
+
+@deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
+Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
+opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
+that will close the list.list.
@end deftypefun
@subsection Item Output Functions
use one of the specialized versions (see below).
@end deftypefun
-@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, char *@var{fldname}, int @var{value})
+@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
This function outputs a value of an @code{int} variable. It uses the
@code{"%d"} output conversion specification. @var{fldname} specifies
the name of the field.
@end deftypefun
-@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, char *@var{fldname}, CORE_ADDR @var{address})
+@deftypefun void ui_out_field_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value})
+This function outputs a value of an @code{int} variable. It differs from
+@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output.
+@var{fldname} specifies
+the name of the field.
+@end deftypefun
+
+@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
This function outputs an address.
@end deftypefun
-@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, char *@var{fldname}, const char *@var{string})
+@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
This function outputs a string using the @code{"%s"} conversion
specification.
@end deftypefun
@var{streambuf}.
@end deftypefun
-@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, char *@var{fieldname}, struct ui_stream *@var{streambuf})
+@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
This function consumes all the data accumulated in
@code{streambuf->stream} and outputs it like
@code{ui_out_field_string} does. After a call to
@subsection Utility Output Functions
-@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, char *@var{fldname})
+@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
This function skips a field in a table. Use it if you have to leave
an empty field without disrupting the table alignment. The argument
@var{fldname} specifies a name for the (missing) filed.
@end deftypefun
-@deftypefun void ui_out_text (struct ui_out *@var{uiout}, char *@var{string})
+@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
This function outputs the text in @var{string} in a way that makes it
easy to be read by humans. For example, the console implementation of
this method filters the text through a built-in pager, to prevent it
list.
@end deftypefun
-@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, char *@var{format}, ...)
+@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
This function produces a formatted message, provided that the current
verbosity level is at least as large as given by @var{verbosity}. The
current verbosity level is specified by the user with the @samp{set
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
- if (!found_a_breakpoint++)
- @{
- annotate_breakpoints_headers ();
- if (addressprint)
- ui_out_table_begin (ui, 6);
- else
- ui_out_table_begin (ui, 5);
-
- annotate_field (0);
- ui_out_table_header (ui, 4, left, "Num");
- annotate_field (1);
- ui_out_table_header (ui, 15, left, "Type");
- annotate_field (2);
- ui_out_table_header (ui, 5, left, "Disp");
- annotate_field (3);
- ui_out_table_header (ui, 4, left, "Enb");
- if (addressprint)
- @{
- annotate_field (4);
- ui_out_table_header (ui, 11, left, "Address");
- @}
- annotate_field (5);
- ui_out_table_header (ui, 40, left, "What");
+@smallexample
+ nr_printable_breakpoints = @dots{};
- ui_out_table_body (ui);
- annotate_breakpoints_table ();
- @}
-@end example
+ if (addressprint)
+ ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
+ else
+ ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
+
+ if (nr_printable_breakpoints > 0)
+ annotate_breakpoints_headers ();
+ if (nr_printable_breakpoints > 0)
+ annotate_field (0);
+ ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
+ if (nr_printable_breakpoints > 0)
+ annotate_field (1);
+ ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
+ if (nr_printable_breakpoints > 0)
+ annotate_field (2);
+ ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
+ if (nr_printable_breakpoints > 0)
+ annotate_field (3);
+ ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
+ if (addressprint)
+ @{
+ if (nr_printable_breakpoints > 0)
+ annotate_field (4);
+ if (TARGET_ADDR_BIT <= 32)
+ ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
+ else
+ ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
+ @}
+ if (nr_printable_breakpoints > 0)
+ annotate_field (5);
+ ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
+ ui_out_table_body (uiout);
+ if (nr_printable_breakpoints > 0)
+ annotate_breakpoints_table ();
+@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);
printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
-@end example
+ @dots{}
+@end smallexample
This is the new version:
-@example
+@smallexample
annotate_record ();
- ui_out_list_begin (uiout, "bkpt");
+ ui_out_tuple_begin (uiout, "bkpt");
annotate_field (0);
ui_out_field_int (uiout, "number", b->number);
annotate_field (1);
ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
annotate_field (3);
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
-@end example
+ @dots{}
+@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
@section TUI
-@section libgdb
+@node libgdb
+
+@chapter libgdb
+@section libgdb 1.0
@cindex @code{libgdb}
-@code{libgdb} was an abortive project of years ago. The theory was to
-provide an API to @value{GDBN}'s functionality.
+@code{libgdb} 1.0 was an abortive project of years ago. The theory was
+to provide an API to @value{GDBN}'s functionality.
+
+@section libgdb 2.0
+@cindex @code{libgdb}
+@code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is
+better able to support graphical and other environments.
+
+Since @code{libgdb} development is on-going, its architecture is still
+evolving. The following components have so far been identified:
+
+@itemize @bullet
+@item
+Observer - @file{gdb-events.h}.
+@item
+Builder - @file{ui-out.h}
+@item
+Event Loop - @file{event-loop.h}
+@item
+Library - @file{gdb.h}
+@end itemize
+
+The model that ties these components together is described below.
+
+@section The @code{libgdb} Model
+
+A client of @code{libgdb} interacts with the library in two ways.
+
+@itemize @bullet
+@item
+As an observer (using @file{gdb-events}) receiving notifications from
+@code{libgdb} of any internal state changes (break point changes, run
+state, etc).
+@item
+As a client querying @code{libgdb} (using the @file{ui-out} builder) to
+obtain various status values from @value{GDBN}.
+@end itemize
+
+Since @code{libgdb} could have multiple clients (e.g. a GUI supporting
+the existing @value{GDBN} CLI), those clients must co-operate when
+controlling @code{libgdb}. In particular, a client must ensure that
+@code{libgdb} is idle (i.e. no other client is using @code{libgdb})
+before responding to a @file{gdb-event} by making a query.
+
+@section CLI support
+
+At present @value{GDBN}'s CLI is very much entangled in with the core of
+@code{libgdb}. Consequently, a client wishing to include the CLI in
+their interface needs to carefully co-ordinate its own and the CLI's
+requirements.
+
+It is suggested that the client set @code{libgdb} up to be bi-modal
+(alternate between CLI and client query modes). The notes below sketch
+out the theory:
+
+@itemize @bullet
+@item
+The client registers itself as an observer of @code{libgdb}.
+@item
+The client create and install @code{cli-out} builder using its own
+versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and
+@code{gdb_stdout} streams.
+@item
+The client creates a separate custom @code{ui-out} builder that is only
+used while making direct queries to @code{libgdb}.
+@end itemize
+
+When the client receives input intended for the CLI, it simply passes it
+along. Since the @code{cli-out} builder is installed by default, all
+the CLI output in response to that command is routed (pronounced rooted)
+through to the client controlled @code{gdb_stdout} et.@: al.@: streams.
+At the same time, the client is kept abreast of internal changes by
+virtue of being a @code{libgdb} observer.
+
+The only restriction on the client is that it must wait until
+@code{libgdb} becomes idle before initiating any queries (using the
+client's custom builder).
+
+@section @code{libgdb} components
+
+@subheading Observer - @file{gdb-events.h}
+@file{gdb-events} provides the client with a very raw mechanism that can
+be used to implement an observer. At present it only allows for one
+observer and that observer must, internally, handle the need to delay
+the processing of any event notifications until after @code{libgdb} has
+finished the current command.
+
+@subheading Builder - @file{ui-out.h}
+@file{ui-out} provides the infrastructure necessary for a client to
+create a builder. That builder is then passed down to @code{libgdb}
+when doing any queries.
+
+@subheading Event Loop - @file{event-loop.h}
+@c There could be an entire section on the event-loop
+@file{event-loop}, currently non-re-entrant, provides a simple event
+loop. A client would need to either plug its self into this loop or,
+implement a new event-loop that GDB would use.
+
+The event-loop will eventually be made re-entrant. This is so that
+@value{GDB} can better handle the problem of some commands blocking
+instead of returning.
+
+@subheading Library - @file{gdb.h}
+@file{libgdb} is the most obvious component of this system. It provides
+the query interface. Each function is parameterized by a @code{ui-out}
+builder. The result of the query is constructed using that builder
+before the query function returns.
@node Symbol Handling
DWARF 1 is a debugging format that was originally designed to be
used with ELF in SVR4 systems.
-@c 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
@chapter Host Definition
With the advent of Autoconf, it's rarely necessary to have host
-definition machinery anymore.
+definition machinery anymore. The following information is provided,
+mainly, as an historical reference.
@section Adding a New Host
@cindex adding a new host
@cindex host, adding
-Most of @value{GDBN}'s host configuration support happens via
-Autoconf. New host-specific definitions should be rarely needed.
-@value{GDBN} still uses the host-specific definitions and files listed
-below, but these mostly exist for historical reasons, and should
+@value{GDBN}'s host configuration support normally happens via Autoconf.
+New host-specific definitions should not be needed. Older hosts
+@value{GDBN} still use the host-specific definitions and files listed
+below, but these mostly exist for historical reasons, and will
eventually disappear.
-Several files control @value{GDBN}'s configuration for host systems:
-
@table @file
-@vindex XDEPFILES
@item gdb/config/@var{arch}/@var{xyz}.mh
-Specifies Makefile fragments needed when hosting on machine @var{xyz}.
-In particular, this lists the required machine-dependent object files,
-by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
-which describes host @var{xyz}, by defining @code{XM_FILE=
-xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
-@code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
-etc.; see @file{Makefile.in}.
+This file once contained both host and native configuration information
+(@pxref{Native Debugging}) for the machine @var{xyz}. The host
+configuration information is now handed by Autoconf.
+
+Host configuration information included a definition of
+@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC},
+@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
+@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
+
+New host only configurations do not need this file.
@item gdb/config/@var{arch}/xm-@var{xyz}.h
-(@file{xm.h} is a link to this file, created by @code{configure}). Contains C
-macro definitions describing the host system environment, such as byte
-order, host C compiler and library.
-
-@item gdb/@var{xyz}-xdep.c
-Contains any miscellaneous C code required for this machine as a host.
-On most machines it doesn't exist at all. If it does exist, put
-@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
-@file{gdb/config/@var{arch}/@var{xyz}.mh}.
+This file once contained definitions and includes required when hosting
+gdb on machine @var{xyz}. Those definitions and includes are now
+handled by Autoconf.
+
+New host and native configurations do not need this file.
+
+@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h}
+file to define the macros @var{HOST_FLOAT_FORMAT},
+@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code
+also needs to be replaced with either an Autoconf or run-time test.}
+
@end table
@subheading Generic Host Support Files
The default name of @value{GDBN}'s initialization file (normally
@file{.gdbinit}).
-@item MEM_FNS_DECLARED
-Your host config file defines this if it includes declarations of
-@code{memcpy} and @code{memset}. Define this to avoid conflicts between
-the native include files and the declarations in @file{defs.h}.
-
@item NO_STD_REGS
This macro is deprecated.
In some cases, use the system call @code{mmap} for reading symbol
tables. For some machines this allows for sharing and quick updates.
-@item HAVE_SIGSETMASK
-@findex sigsetmask
-Define this if the host system has job control, but does not define
-@code{sigsetmask}. Currently, this is only true of the RS/6000.
-
@item HAVE_TERMIO
Define this if the host system has @code{termio.h}.
-@item HOST_BYTE_ORDER
-@cindex byte order
-The ordering of bytes in the host. This must be defined to be either
-@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
-
@item INT_MAX
@itemx INT_MIN
@itemx LONG_MAX
@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
which is the POSIX equivalent.
-@item MALLOC_INCOMPATIBLE
-Define this if the system's prototype for @code{malloc} differs from the
-@sc{ansi} definition.
-
@item MMAP_BASE_ADDRESS
When using HAVE_MMAP, the first mapping should go at this address.
@item MMAP_INCREMENT
when using HAVE_MMAP, this is the increment between mappings.
-@item NEED_POSIX_SETPGID
-@findex setpgid
-Define this to use the POSIX version of @code{setpgid} to determine
-whether job control is available.
-
@item NORETURN
If defined, this should be one or more tokens, such as @code{volatile},
that can be used in both the declaration and definition of functions to
set correctly if compiling with GCC. This will almost never need to be
defined.
-@item USE_GENERIC_DUMMY_FRAMES
-@cindex generic dummy frames
-Define this to 1 if the target is using the generic inferior function
-call code. See @code{blockframe.c} for more information.
-
@item USE_MMALLOC
@findex mmalloc
@value{GDBN} will use the @code{mmalloc} library for memory allocation
@findex siginterrupt
Define this to indicate that @code{siginterrupt} is not available.
-@item R_OK
-Define if this is not in a system header file (typically, @file{unistd.h}).
-
@item SEEK_CUR
@itemx SEEK_SET
Define these to appropriate value for the system @code{lseek}, if not already
@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},
-@file{remote-nindy.c}, and @file{utils.c} for other things, at the
-moment.)
+This symbol is abused in @file{infrun.c}, @file{regex.c}, and
+@file{utils.c} for other things, at the moment.)
@item lint
Define this to help placate @code{lint} in some situations.
machine-language programs @value{GDBN} can work with, and how it works
with them.
-At present, the target architecture definition consists of a number of C
-macros.
+The target architecture object is implemented as the C structure
+@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}, unsigned long @var{machine}, 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, machine type and OS ABI specified by @var{arch},
+@var{machine} and @var{osabi}. In most cases, a value of zero for the
+machine type, which implies the architecture's default machine type,
+will suffice.
+@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
will signal an internal error.
@end deftypefun
-@deftypefun CORE_ADDR value_as_pointer (value_ptr @var{val})
+@deftypefun CORE_ADDR value_as_address (struct value *@var{val})
Assuming that @var{val} is a pointer, return the address it represents,
as appropriate for the current architecture.
Here are some macros which architectures can define to indicate the
relationship between pointers and addresses. These have default
definitions, appropriate for architectures on which all pointers are
-simple byte addresses.
+simple unsigned byte addresses.
@deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf})
Assume that @var{buf} holds a pointer of type @var{type}, in the
C@t{++} reference type.
@end deftypefn
+@section Address Classes
+@cindex address classes
+@cindex DW_AT_byte_size
+@cindex DW_AT_address_class
+
+Sometimes information about different kinds of addresses is available
+via the debug information. For example, some programming environments
+define addresses of several different sizes. If the debug information
+distinguishes these kinds of address classes through either the size
+info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit
+address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the
+following macros should be defined in order to disambiguate these
+types within @value{GDBN} as well as provide the added information to
+a @value{GDBN} user when printing type expressions.
+
+@deftypefn {Target Macro} int ADDRESS_CLASS_TYPE_FLAGS (int @var{byte_size}, int @var{dwarf2_addr_class})
+Returns the type flags needed to construct a pointer type whose size
+is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.
+This function is normally called from within a symbol reader. See
+@file{dwarf2read.c}.
+@end deftypefn
+
+@deftypefn {Target Macro} char *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (int @var{type_flags})
+Given the type flags representing an address class qualifier, return
+its name.
+@end deftypefn
+@deftypefn {Target Macro} int ADDRESS_CLASS_NAME_to_TYPE_FLAGS (int @var{name}, int *var{type_flags_ptr})
+Given an address qualifier name, set the @code{int} refererenced by @var{type_flags_ptr} to the type flags
+for that address class qualifier.
+@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
+Since the need for address classes is rather rare, none of
+the address class macros defined by default. Predicate
+macros are provided to detect when they are defined.
+
+Consider a hypothetical architecture in which addresses are normally
+32-bits wide, but 16-bit addresses are also supported. Furthermore,
+suppose that the @w{DWARF 2} information for this architecture simply
+uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one
+of these "short" pointers. The following functions could be defined
+to implement the address class macros:
+
+@smallexample
+somearch_address_class_type_flags (int byte_size,
+ int dwarf2_addr_class)
+@{
+ if (byte_size == 2)
+ return TYPE_FLAG_ADDRESS_CLASS_1;
+ else
+ return 0;
+@}
+
+static char *
+somearch_address_class_type_flags_to_name (int type_flags)
+@{
+ if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
+ return "short";
+ else
+ return NULL;
+@}
+
+int
+somearch_address_class_name_to_type_flags (char *name,
+ int *type_flags_ptr)
+@{
+ if (strcmp (name, "short") == 0)
+ @{
+ *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
+ return 1;
+ @}
+ else
+ return 0;
+@}
+@end smallexample
+
+The qualifier @code{@@short} is used in @value{GDBN}'s type expressions
+to indicate the presence of one of these "short" pointers. E.g, if
+the debug information indicates that @code{short_ptr_var} is one of these
+short pointers, @value{GDBN} might show the following behavior:
+
+@smallexample
+(gdb) ptype short_ptr_var
+type = int * @@short
+@end smallexample
+
+
+@section Raw and Virtual Register Representations
+@cindex raw register representation
+@cindex virtual register representation
+@cindex representations, raw and virtual registers
+
+@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
@table @code
-@item ADDITIONAL_OPTIONS
-@itemx ADDITIONAL_OPTION_CASES
-@itemx ADDITIONAL_OPTION_HANDLER
-@itemx ADDITIONAL_OPTION_HELP
-@findex ADDITIONAL_OPTION_HELP
-@findex ADDITIONAL_OPTION_HANDLER
-@findex ADDITIONAL_OPTION_CASES
-@findex ADDITIONAL_OPTIONS
-These are a set of macros that allow the addition of additional command
-line options to @value{GDBN}. They are currently used only for the unsupported
-i960 Nindy target, and should not be used in any other configuration.
-
@item ADDR_BITS_REMOVE (addr)
@findex ADDR_BITS_REMOVE
If a raw machine instruction address includes any bits that are not
address of the instruction. ADDR_BITS_REMOVE should filter out these
bits with an expression such as @code{((addr) & ~3)}.
+@item ADDRESS_CLASS_NAME_TO_TYPE_FLAGS (@var{name}, @var{type_flags_ptr})
+@findex ADDRESS_CLASS_NAME_TO_TYPE_FLAGS
+If @var{name} is a valid address class qualifier name, set the @code{int}
+referenced by @var{type_flags_ptr} to the mask representing the qualifier
+and return 1. If @var{name} is not a valid address class qualifier name,
+return 0.
+
+The value for @var{type_flags_ptr} should be one of
+@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or
+possibly some combination of these values or'd together.
+@xref{Target Architecture Definition, , Address Classes}.
+
+@item ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P ()
+@findex ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P
+Predicate which indicates whether @code{ADDRESS_CLASS_NAME_TO_TYPE_FLAGS}
+has been defined.
+
+@item ADDRESS_CLASS_TYPE_FLAGS (@var{byte_size}, @var{dwarf2_addr_class})
+@findex ADDRESS_CLASS_TYPE_FLAGS (@var{byte_size}, @var{dwarf2_addr_class})
+Given a pointers byte size (as described by the debug information) and
+the possible @code{DW_AT_address_class} value, return the type flags
+used by @value{GDBN} to represent this address class. The value
+returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1},
+@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these
+values or'd together.
+@xref{Target Architecture Definition, , Address Classes}.
+
+@item ADDRESS_CLASS_TYPE_FLAGS_P ()
+@findex ADDRESS_CLASS_TYPE_FLAGS_P
+Predicate which indicates whether @code{ADDRESS_CLASS_TYPE_FLAGS} has
+been defined.
+
+@item ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (@var{type_flags})
+@findex ADDRESS_CLASS_TYPE_FLAGS_TO_NAME
+Return the name of the address class qualifier associated with the type
+flags given by @var{type_flags}.
+
+@item ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P ()
+@findex ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P
+Predicate which indicates whether @code{ADDRESS_CLASS_TYPE_FLAGS_TO_NAME} has
+been defined.
+@xref{Target Architecture Definition, , Address Classes}.
+
@item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
@findex ADDRESS_TO_POINTER
Store in @var{buf} a pointer of type @var{type} representing the address
C@t{++} reference type.
@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
-@item BEFORE_MAIN_LOOP_HOOK
-@findex BEFORE_MAIN_LOOP_HOOK
-Define this to expand into any code that you want to execute before the
-main loop starts. Although this is not, strictly speaking, a target
-conditional, that is how it is currently being used. Note that if a
-configuration were to define it one way for a host and a different way
-for the target, @value{GDBN} will probably not compile, let alone run
-correctly. This macro is currently used only for the unsupported i960 Nindy
-target, and should not be used in any other configuration.
-
@item BELIEVE_PCC_PROMOTION
@findex BELIEVE_PCC_PROMOTION
Define if the compiler promotes a @code{short} or @code{char}
@item CALL_DUMMY_P
@findex CALL_DUMMY_P
-A C expresson that is non-zero when the target suports inferior function
+A C expression that is non-zero when the target supports inferior function
calls.
@item CALL_DUMMY_WORDS
@value{GDBN} will assume that all registers may be written.
@item DO_DEFERRED_STORES
-@itemx CLEAR_DEFERRED_STORES@item
+@itemx CLEAR_DEFERRED_STORES
@findex CLEAR_DEFERRED_STORES
@findex DO_DEFERRED_STORES
Define this to execute any deferred stores of registers into the inferior,
Currently only implemented correctly for native Sparc configurations?
-@item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
-@findex COERCE_FLOAT_TO_DOUBLE
-@cindex promotion to @code{double}
-If we are calling a function by hand, and the function was declared
-(according to the debug info) without a prototype, should we
-automatically promote @code{float}s to @code{double}s? This macro
-must evaluate to non-zero if we should, or zero if we should leave the
-value alone.
-
-The argument @var{actual} is the type of the value we want to pass to
-the function. The argument @var{formal} is the type of this argument,
-as it appears in the function's definition. Note that @var{formal} may
-be zero if we have no debugging information for the function, or if
-we're passing more arguments than are officially declared (for example,
-varargs). This macro is never invoked if the function definitely has a
-prototype.
-
-@findex set_gdbarch_coerce_float_to_double
-@findex standard_coerce_float_to_double
-The default behavior is to promote only when we have no type information
-for the formal parameter. This is different from the obvious behavior,
-which would be to promote whenever we have no prototype, just as the
-compiler does. It's annoying, but some older targets rely on this. If
-you want @value{GDBN} to follow the typical compiler behavior---to always
-promote when there is no prototype in scope---your gdbarch @code{init}
-function can call @code{set_gdbarch_coerce_float_to_double} and select
-the @code{standard_coerce_float_to_double} function.
-
-@item CPLUS_MARKER
-@findex CPLUS_MARKERz
-Define this to expand into the character that G@t{++} uses to distinguish
-compiler-generated identifiers from programmer-specified identifiers.
-By default, this expands into @code{'$'}. Most System V targets should
-define this to @code{'.'}.
-
-@item DBX_PARM_SYMBOL_CLASS
-@findex DBX_PARM_SYMBOL_CLASS
-Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
-information. In the i960, parameters can be stored as locals or as
-args, depending on the type of the debug record.
+@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 DECR_PC_AFTER_BREAK
@findex DECR_PC_AFTER_BREAK
If defined, this should evaluate to 1 if @var{addr} is in a shared
library in which breakpoints cannot be set and so should be disabled.
-@item DO_REGISTERS_INFO
-@findex DO_REGISTERS_INFO
-If defined, use this to print the value of a register or all registers.
+@item 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
@item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
@findex EXTRACT_STRUCT_VALUE_ADDRESS
-When @code{EXTRACT_STRUCT_VALUE_ADDRESS_P} is non-zero, this is used to extract
-from an array @var{regbuf} (containing the raw register state) the
-address in which a function should return its structure value, as a
-@code{CORE_ADDR} (or an expression that can be used as one).
+When defined, extract from the array @var{regbuf} (containing the raw
+register state) the @code{CORE_ADDR} at which a function should return
+its structure value.
+
+If not defined, @code{EXTRACT_RETURN_VALUE} is used.
-@item EXTRACT_STRUCT_VALUE_ADDRESS_P
+@item EXTRACT_STRUCT_VALUE_ADDRESS_P()
@findex EXTRACT_STRUCT_VALUE_ADDRESS_P
Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
-@item FLOAT_INFO
-@findex FLOAT_INFO
-If defined, then the @samp{info float} command will print information about
-the processor's floating point unit.
-
@item FP_REGNUM
@findex FP_REGNUM
If the virtual frame pointer is kept in a register, then define this
macro to be the number (greater than or equal to zero) of that register.
-This should only need to be defined if @code{TARGET_READ_FP} 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
represented by @var{fi} does not have a stack frame associated with it.
Otherwise return 0.
-@item FRAME_ARGS_ADDRESS_CORRECT@item
+@item frame_align (@var{address})
+@anchor{frame_align}
+@findex frame_align
+Define this to adjust @var{address} so that it meets the alignment
+requirements for the start of a new stack frame. A stack frame's
+alignment requirements are typically stronger than a target processors
+stack alignment requirements (@pxref{STACK_ALIGN}).
+
+This function is used to ensure that, when creating a dummy frame, both
+the initial stack pointer and (if needed) the address of the return
+value are correctly aligned.
+
+Unlike @code{STACK_ALIGN}, this function always adjusts the address in
+the direction of stack growth.
+
+By default, no frame based stack alignment is performed.
+
+@item FRAME_ARGS_ADDRESS_CORRECT
@findex FRAME_ARGS_ADDRESS_CORRECT
See @file{stack.c}.
@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
-an outermost frame, with no caller, and nonzero otherwise. Several
-common definitions are available:
-
-@itemize @bullet
-@item
-@code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
-and given frame's PC is not inside the startup file (such as
-@file{crt0.o}).
-
-@item
-@code{func_frame_chain_valid} is nonzero if the chain
-pointer is nonzero and the given frame's PC is not in @code{main} or a
-known entry point function (such as @code{_start}).
-
-@item
-@code{generic_file_frame_chain_valid} and
-@code{generic_func_frame_chain_valid} are equivalent implementations for
-targets using generic dummy frames.
-@end itemize
-
-@item FRAME_INIT_SAVED_REGS(@var{frame})
-@findex FRAME_INIT_SAVED_REGS
+Define this to be an expression that returns zero if the given frame is an
+outermost frame, with no caller, and nonzero otherwise. Most normal
+situations can be handled without defining this macro, including @code{NULL}
+chain pointers, dummy frames, and frames whose PC values are inside the
+startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside
+@code{_start}.
+
+@item DEPRECATED_FRAME_INIT_SAVED_REGS(@var{frame})
+@findex DEPRECATED_FRAME_INIT_SAVED_REGS
See @file{frame.h}. Determines the address of all registers in the
current stack frame storing each in @code{frame->saved_regs}. Space for
@code{frame->saved_regs} shall be allocated by
-@code{FRAME_INIT_SAVED_REGS} using either
-@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
+@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using
+@code{frame_saved_regs_zalloc}.
@code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
@item FRAME_SAVED_PC(@var{frame})
@findex FRAME_SAVED_PC
-Given @var{frame}, return the pc saved there. This is the return
-address.
+@anchor{FRAME_SAVED_PC} Given @var{frame}, return the pc saved there.
+This is the return address.
+
+This method is deprecated. @xref{unwind_pc}.
+
+@item CORE_ADDR unwind_pc (struct frame_info *@var{this_frame})
+@findex unwind_pc
+@anchor{unwind_pc} Return the instruction address, in @var{this_frame}'s
+caller, at which execution will resume after @var{this_frame} returns.
+This is commonly refered to as the return address.
+
+The implementation, which must be frame agnostic (work with any frame),
+is typically no more than:
+
+@smallexample
+ULONGEST pc;
+frame_unwind_unsigned_register (this_frame, D10V_PC_REGNUM, &pc);
+return d10v_make_iaddr (pc);
+@end smallexample
+
+@noindent
+@xref{FRAME_SAVED_PC}, which this method replaces.
@item FUNCTION_EPILOGUE_SIZE
@findex FUNCTION_EPILOGUE_SIZE
@item @value{GDBN}_MULTI_ARCH
@findex @value{GDBN}_MULTI_ARCH
-If defined and non-zero, enables suport for multiple architectures
+If defined and non-zero, enables support for multiple architectures
within @value{GDBN}.
This support can be enabled at two levels. At level one, only
definitions for previously undefined macros are provided; at level two,
-a multi-arch definition of all architecture dependant macros will be
+a multi-arch definition of all architecture dependent macros will be
defined.
@item @value{GDBN}_TARGET_IS_HPPA
@findex GET_LONGJMP_TARGET
For most machines, this is a target-dependent parameter. On the
DECstation and the Iris, this is a native-dependent parameter, since
-trhe header file @file{setjmp.h} is needed to define it.
+the header file @file{setjmp.h} is needed to define it.
This macro determines the target PC address that @code{longjmp} will jump to,
assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
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
@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
routine that handles inter-space procedure calls on PA-RISC.
-@item IEEE_FLOAT
-@findex IEEE_FLOAT
-Define this if the target system uses IEEE-format floating point numbers.
-
-@item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
-@findex INIT_EXTRA_FRAME_INFO
+@item DEPRECATED_INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
+@findex DEPRECATED_INIT_EXTRA_FRAME_INFO
If additional information about the frame is required this should be
stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
-is allocated using @code{frame_obstack_alloc}.
+is allocated using @code{frame_extra_info_zalloc}.
-@item INIT_FRAME_PC (@var{fromleaf}, @var{prev})
-@findex INIT_FRAME_PC
+@item DEPRECATED_INIT_FRAME_PC (@var{fromleaf}, @var{prev})
+@findex DEPRECATED_INIT_FRAME_PC
This is a C statement that sets the pc of the frame pointed to by
@var{prev}. [By default...]
the target's stack grows downward in memory, or @code{lhs > rsh} if the
stack grows upward.
-@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 gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc})
+@findex gdbarch_in_function_epilogue_p
+Returns non-zero if the given @var{pc} is in the epilogue of a function.
+The epilogue of a function is defined as the part of a function where
+the stack frame of the function already has been destroyed up to the
+final `return from function call' instruction.
@item SIGTRAMP_START (@var{pc})
@findex SIGTRAMP_START
to set a breakpoint to get through the dynamic linker and that single
stepping will suffice.
-@item IS_TRAPPED_INTERNALVAR (@var{name})
-@findex IS_TRAPPED_INTERNALVAR
-This is an ugly hook to allow the specification of special actions that
-should occur as a side-effect of setting the value of a variable
-internal to @value{GDBN}. Currently only used by the h8500. Note that this
-could be either a host or target conditional.
+@item INTEGER_TO_ADDRESS (@var{type}, @var{buf})
+@findex INTEGER_TO_ADDRESS
+@cindex converting integers to addresses
+Define this when the architecture needs to handle non-pointer to address
+conversions specially. Converts that value to an address according to
+the current architectures conventions.
+
+@emph{Pragmatics: When the user copies a well defined expression from
+their source code and passes it, as a parameter, to @value{GDBN}'s
+@code{print} command, they should get the same value as would have been
+computed by the target program. Any deviation from this rule can cause
+major confusion and annoyance, and needs to be justified carefully. In
+other words, @value{GDBN} doesn't really have the freedom to do these
+conversions in clever and useful ways. It has, however, been pointed
+out that users aren't complaining about how @value{GDBN} casts integers
+to pointers; they are complaining that they can't take an address from a
+disassembly listing and give it to @code{x/i}. Adding an architecture
+method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for
+@value{GDBN} to ``get it right'' in all circumstances.}
+
+@xref{Target Architecture Definition, , Pointers Are Not Always
+Addresses}.
@item NEED_TEXT_START_END
@findex NEED_TEXT_START_END
@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_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup})
+@findex register_reggroup_p
+@cindex register groups
+Return non-zero if register @var{regnum} is a member of the register
+group @var{reggroup}.
+
+By default, registers are grouped as follows:
+
+@table @code
+@item float_reggroup
+Any register with a valid name and a floating-point type.
+@item vector_reggroup
+Any register with a valid name and a vector type.
+@item general_reggroup
+Any register with a valid name and a type other than vector or
+floating-point. @samp{float_reggroup}.
+@item save_reggroup
+@itemx restore_reggroup
+@itemx all_reggroup
+Any register with a valid name.
+@end table
@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 struct type *register_type (@var{gdbarch}, @var{reg})
+@findex register_type
+If defined, return the type of register @var{reg}. This function
+superseeds @code{REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture
+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 PCC_SOL_BROKEN
(Used only in the Convex target.)
-@item PC_IN_CALL_DUMMY
-@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
@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
pushing them on the stack.
-@item PRINT_REGISTER_HOOK (@var{regno})
-@findex PRINT_REGISTER_HOOK
-If defined, this must be a function that prints the contents of the
-given register to standard output.
-
@item PRINT_TYPELESS_INTEGER
@findex PRINT_TYPELESS_INTEGER
This is an obscure substitute for @code{print_longest} that seems to
@item SAVE_DUMMY_FRAME_TOS (@var{sp})
@findex SAVE_DUMMY_FRAME_TOS
-Used in @samp{call_function_by_hand} to notify the target dependent code
-of the top-of-stack value that will be passed to the the inferior code.
-This is the value of the @code{SP} after both the dummy frame and space
-for parameters/results have been allocated on the stack.
+@anchor{SAVE_DUMMY_FRAME_TOS} Used in @samp{call_function_by_hand} to
+notify the target dependent code of the top-of-stack value that will be
+passed to the the inferior code. This is the value of the @code{SP}
+after both the dummy frame and space for parameters/results have been
+allocated on the stack. @xref{unwind_dummy_id}.
@item SDB_REG_TO_REGNUM
@findex SDB_REG_TO_REGNUM
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.)
-
@item SKIP_PERMANENT_BREAKPOINT
@findex SKIP_PERMANENT_BREAKPOINT
Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
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
done.
@item STACK_ALIGN (@var{addr})
+@anchor{STACK_ALIGN}
@findex STACK_ALIGN
-Define this to adjust the address to the alignment required for the
-processor's stack.
+Define this to increase @var{addr} so that it meets the alignment
+requirements for the processor's stack.
+
+Unlike @ref{frame_align}, this function always adjusts @var{addr}
+upwards.
+
+By default, no stack alignment is performed.
@item STEP_SKIPS_DELAY (@var{addr})
@findex STEP_SKIPS_DELAY
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
The default value of the ``symbol-reloading'' variable. (Never defined in
current sources.)
-@item TARGET_BYTE_ORDER_DEFAULT
-@findex TARGET_BYTE_ORDER_DEFAULT
-The ordering of bytes in the target. This must be either
-@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
-@code{TARGET_BYTE_ORDER} which is deprecated.
-
-@item TARGET_BYTE_ORDER_SELECTABLE_P
-@findex TARGET_BYTE_ORDER_SELECTABLE_P
-Non-zero if the target has both @code{BIG_ENDIAN} and
-@code{LITTLE_ENDIAN} variants. This macro replaces
-@code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
-
@item TARGET_CHAR_BIT
@findex TARGET_CHAR_BIT
Number of bits in a char; defaults to 8.
+@item TARGET_CHAR_SIGNED
+@findex TARGET_CHAR_SIGNED
+Non-zero if @code{char} is normally signed on this architecture; zero if
+it should be unsigned.
+
+The ISO C standard requires the compiler to treat @code{char} as
+equivalent to either @code{signed char} or @code{unsigned char}; any
+character in the standard execution set is supposed to be positive.
+Most compilers treat @code{char} as signed, but @code{char} is unsigned
+on the IBM S/390, RS6000, and PowerPC targets.
+
@item TARGET_COMPLEX_BIT
@findex TARGET_COMPLEX_BIT
Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
@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
watchpoints. @xref{Algorithms, watchpoints}, for more details and
other related macros.
+@item TARGET_PRINT_INSN (@var{addr}, @var{info})
+@findex TARGET_PRINT_INSN
+This is the function used by @value{GDBN} to print an assembly
+instruction. It prints the instruction at address @var{addr} in
+debugged memory and returns the length of the instruction, in bytes. If
+a target doesn't define its own printing routine, it defaults to an
+accessor function for the global pointer @code{tm_print_insn}. This
+usually points to a function in the @code{opcodes} library (@pxref{Support
+Libraries, ,Opcodes}). @var{info} is a structure (of type
+@code{disassemble_info}) defined in @file{include/dis-asm.h} used to
+pass information to the instruction decoding routine.
+
+@item struct frame_id unwind_dummy_id (struct frame_info *@var{frame})
+@findex unwind_dummy_id
+@anchor{unwind_dummy_id} Given @var{frame} return a @code{struct
+frame_id} that uniquely identifies an inferior function call's dummy
+frame. The value returned must match the dummy frame stack value
+previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
+@xref{SAVE_DUMMY_FRAME_TOS}.
+
@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
@findex USE_STRUCT_CONVENTION
If defined, this must be an expression that is nonzero if a value of the
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
@item REMOTE_BPT_VECTOR
Defaults to @code{1}.
+
+@item NAME_OF_MALLOC
+@findex NAME_OF_MALLOC
+A string containing the name of the function to call in order to
+allocate some memory in the inferior. The default value is "malloc".
+
@end ftable
@section Adding a New Target
@cindex adding a target
-The following files define a target to @value{GDBN}:
+The following files add a target to @value{GDBN}:
@table @file
@vindex TDEPFILES
but these are now deprecated, replaced by autoconf, and may go away in
future versions of @value{GDBN}.
-@item gdb/config/@var{arch}/tm-@var{ttt}.h
-(@file{tm.h} is a link to this file, created by @code{configure}). Contains
-macro definitions about the target machine's registers, stack frame
-format and instructions.
-
@item gdb/@var{ttt}-tdep.c
Contains any miscellaneous code required for this target machine. On
some machines it doesn't exist at all. Sometimes the macros in
function. This is vastly preferable, since it is easier to understand
and debug.
+@item gdb/@var{arch}-tdep.c
+@itemx gdb/@var{arch}-tdep.h
+This often exists to describe the basic layout of the target machine's
+processor chip (registers, stack, etc.). If used, it is included by
+@file{@var{ttt}-tdep.h}. It can be shared among many targets that use
+the same processor.
+
+@item gdb/config/@var{arch}/tm-@var{ttt}.h
+(@file{tm.h} is a link to this file, created by @code{configure}). Contains
+macro definitions about the target machine's registers, stack frame
+format and instructions.
+
+New targets do not need this file and should not create it.
+
@item gdb/config/@var{arch}/tm-@var{arch}.h
This often exists to describe the basic layout of the target machine's
processor chip (registers, stack, etc.). If used, it is included by
@file{tm-@var{ttt}.h}. It can be shared among many targets that use the
same processor.
-@item gdb/@var{arch}-tdep.c
-Similarly, there are often common subroutines that are shared by all
-target machines that use this particular architecture.
+New targets do not need this file and should not create it.
+
@end table
If you are adding a new operating system for an existing CPU chip, add a
@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{DEPRECATED_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
@table @file
@vindex NATDEPFILES
@item gdb/config/@var{arch}/@var{xyz}.mh
-Specifies Makefile fragments needed when hosting @emph{or native} on
+Specifies Makefile fragments needed by a @emph{native} configuration on
machine @var{xyz}. In particular, this lists the required
native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
Also specifies the header file which describes native support on
define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+@emph{Maintainer's note: The @file{.mh} suffix is because this file
+originally contained @file{Makefile} fragments for hosting @value{GDBN}
+on machine @var{xyz}. While the file is no longer used for this
+purpose, the @file{.mh} suffix remains. Perhaps someone will
+eventually rename these fragments so that they have a @file{.mn}
+suffix.}
+
@item gdb/config/@var{arch}/nm-@var{xyz}.h
(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
macro definitions describing the native system environment, such as
If defined, this is the name of the shell to use to run the inferior.
Defaults to @code{"/bin/sh"}.
-@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ})
+@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
@findex SOLIB_ADD
Define this to expand into an expression that will cause the symbols in
-@var{filename} to be added to @value{GDBN}'s symbol table.
+@var{filename} to be added to @value{GDBN}'s symbol table. If
+@var{readsyms} is zero symbols are not read but any necessary low level
+processing for @var{filename} is still done.
@item SOLIB_CREATE_INFERIOR_HOOK
@findex SOLIB_CREATE_INFERIOR_HOOK
@cindex cleanups
Cleanups are a structured way to deal with things that need to be done
-later. When your code does something (like @code{malloc} some memory,
-or open a file) that needs to be undone later (e.g., free the memory or
-close the file), it can make a cleanup. The cleanup will be done at
-some future point: when the command is finished, when an error occurs,
-or when your code decides it's time to do cleanups.
+later.
-You can also discard cleanups, that is, throw them away without doing
-what they say. This is only done if you ask that it be done.
+When your code does something (e.g., @code{xmalloc} some memory, or
+@code{open} a file) that needs to be undone later (e.g., @code{xfree}
+the memory or @code{close} the file), it can make a cleanup. The
+cleanup will be done at some future point: when the command is finished
+and control returns to the top level; when an error occurs and the stack
+is unwound; or when your code decides it's time to explicitly perform
+cleanups. Alternatively you can elect to discard the cleanups you
+created.
Syntax:
@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
Make a cleanup which will cause @var{function} to be called with
@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
-handle that can be passed to @code{do_cleanups} or
-@code{discard_cleanups} later. Unless you are going to call
-@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
-the result from @code{make_cleanup}.
+handle that can later be passed to @code{do_cleanups} or
+@code{discard_cleanups}. Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
+from @code{make_cleanup}.
@findex do_cleanups
@item do_cleanups (@var{old_chain});
-Perform all cleanups done since @code{make_cleanup} returned
-@var{old_chain}. E.g.:
-
-@example
-make_cleanup (a, 0);
-old = make_cleanup (b, 0);
-do_cleanups (old);
-@end example
-
-@noindent
-will call @code{b()} but will not call @code{a()}. The cleanup that
-calls @code{a()} will remain in the cleanup chain, and will be done
-later unless otherwise discarded.@refill
+Do all cleanups added to the chain since the corresponding
+@code{make_cleanup} call was made.
@findex discard_cleanups
@item discard_cleanups (@var{old_chain});
the chain and does not call the specified functions.
@end table
+Cleanups are implemented as a chain. The handle returned by
+@code{make_cleanups} includes the cleanup passed to the call and any
+later cleanups appended to the chain (but not yet discarded or
+performed). E.g.:
+
+@smallexample
+make_cleanup (a, 0);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 0)
+ ...
+ do_cleanups (old);
+@}
+@end smallexample
+
+@noindent
+will call @code{c()} and @code{b()} but will not call @code{a()}. The
+cleanup that calls @code{a()} will remain in the cleanup chain, and will
+be done later unless otherwise discarded.@refill
+
+Your function should explicitly do or discard the cleanups it creates.
+Failing to do this leads to non-deterministic behavior since the caller
+will arbitrarily do or discard your functions cleanups. This need leads
+to two common cleanup styles.
+
+The first style is try/finally. Before it exits, your code-block calls
+@code{do_cleanups} with the old cleanup chain and thus ensures that your
+code-block's cleanups are always performed. For instance, the following
+code-segment avoids a memory leak problem (even when @code{error} is
+called and a forced stack unwind occurs) by ensuring that the
+@code{xfree} will always be called:
+
+@smallexample
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@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
+any created cleanups are not performed. For instance, the following
+code segment, ensures that the file will be closed but only if there is
+an error:
+
+@smallexample
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@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
means that any actions you need to reverse in the case of an error or
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} follows the GNU coding standards, as described in
@file{etc/standards.texi}. This file is also available for anonymous
-FTP from GNU archive sites. @value{GDBN} takes a strict interpretation of the
-standard; in general, when the GNU standard recommends a practice but
-does not require it, @value{GDBN} requires it.
+FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
+of the standard; in general, when the GNU standard recommends a practice
+but does not require it, @value{GDBN} requires it.
@value{GDBN} follows an additional set of coding standards specific to
@value{GDBN}, as described in the following sections.
+
+@subsection ISO C
+
+@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.
+
+
+@subsection Memory Management
+
+@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
+@code{calloc}, @code{free} and @code{asprintf}.
+
+@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
+@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
+these functions do not return when the memory pool is empty. Instead,
+they unwind the stack using cleanups. These functions return
+@code{NULL} when requested to allocate a chunk of memory of size zero.
+
+@emph{Pragmatics: By using these functions, the need to check every
+memory allocation is removed. These functions provide portable
+behavior.}
+
+@value{GDBN} does not use the function @code{free}.
+
+@value{GDBN} uses the function @code{xfree} to return memory to the
+memory pool. Consistent with ISO-C, this function ignores a request to
+free a @code{NULL} pointer.
+
+@emph{Pragmatics: On some systems @code{free} fails when passed a
+@code{NULL} pointer.}
+
+@value{GDBN} can use the non-portable function @code{alloca} for the
+allocation of small temporary values (such as strings).
+
+@emph{Pragmatics: This function is very non-portable. Some systems
+restrict the memory being allocated to no more than a few kilobytes.}
+
+@value{GDBN} uses the string function @code{xstrdup} and the print
+function @code{xasprintf}.
+
+@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
+functions such as @code{sprintf} are very prone to buffer overflow
+errors.}
+
+
+@subsection Compiler Warnings
@cindex compiler warnings
-You can configure with @samp{--enable-build-warnings} or
-@samp{--enable-gdb-build-warnings} to get GCC to check on a number of
-these rules. @value{GDBN} sources ought not to engender any complaints,
-unless they are caused by bogus host systems. (The exact set of enabled
-warnings is currently @samp{-Wimplicit -Wreturn-type -Wcomment
--Wtrigraphs -Wformat -Wparentheses -Wpointer-arith -Wuninitialized}.
+
+With few exceptions, developers should include the configuration option
+@samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}.
+The exceptions are listed in the file @file{gdb/MAINTAINERS}.
+
+This option causes @value{GDBN} (when built using GCC) to be compiled
+with a carefully selected list of compiler warning flags. Any warnings
+from those flags being treated as errors.
+
+The current list of warning flags includes:
+
+@table @samp
+@item -Wimplicit
+Since @value{GDBN} coding standard requires all functions to be declared
+using a prototype, the flag has the side effect of ensuring that
+prototyped functions are always visible with out resorting to
+@samp{-Wstrict-prototypes}.
+
+@item -Wreturn-type
+Such code often appears to work except on instruction set architectures
+that use register windows.
+
+@item -Wcomment
+
+@item -Wtrigraphs
+
+@item -Wformat
+Since @value{GDBN} uses the @code{format printf} attribute on all
+@code{printf} like functions this checks not just @code{printf} calls
+but also calls to functions such as @code{fprintf_unfiltered}.
+
+@item -Wparentheses
+This warning includes uses of the assignment operator within an
+@code{if} statement.
+
+@item -Wpointer-arith
+
+@item -Wuninitialized
+@end table
+
+@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
+functions have unused parameters. Consequently the warning
+@samp{-Wunused-parameter} is precluded from the list. The macro
+@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
+it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
+is being used. The options @samp{-Wall} and @samp{-Wunused} are also
+precluded because they both include @samp{-Wunused-parameter}.}
+
+@emph{Pragmatics: @value{GDBN} has not simply accepted the warnings
+enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings
+when and where their benefits can be demonstrated.}
@subsection Formatting
The standard GNU recommendations for formatting must be followed
strictly.
-Note that while in a definition, the function's name must be in column
-zero; in a function declaration, the name must be on the same line as
-the return type.
+A function declaration should not have its name in column zero. A
+function definition should have its name in column zero.
+
+@smallexample
+/* Declaration */
+static void foo (void);
+/* Definition */
+void
+foo (void)
+@{
+@}
+@end smallexample
-In addition, there must be a space between a function or macro name and
-the opening parenthesis of its argument list (except for macro
-definitions, as required by C). There must not be a space after an open
-paren/bracket or before a close paren/bracket.
+@emph{Pragmatics: This simplifies scripting. Function definitions can
+be found using @samp{^function-name}.}
+
+There must be a space between a function or macro name and the opening
+parenthesis of its argument list (except for macro definitions, as
+required by C). There must not be a space after an open paren/bracket
+or before a close paren/bracket.
While additional whitespace is generally helpful for reading, do not use
more than one blank line to separate blocks, and avoid adding whitespace
-after the end of a program line (as of 1/99, some 600 lines had whitespace
-after the semicolon). Excess whitespace causes difficulties for
-@code{diff} and @code{patch} utilities.
+after the end of a program line (as of 1/99, some 600 lines had
+whitespace after the semicolon). Excess whitespace causes difficulties
+for @code{diff} and @code{patch} utilities.
+
+Pointers are declared using the traditional K&R C style:
+
+@smallexample
+void *foo;
+@end smallexample
+
+@noindent
+and not:
+
+@smallexample
+void * foo;
+void* foo;
+@end smallexample
@subsection Comments
@cindex comment formatting
The standard GNU requirements on comments must be followed strictly.
-Block comments must appear in the following form, with no @samp{/*}- or
-@samp{*/}-only lines, and no leading @samp{*}:
+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.)
However, use functions with moderation. A thousand one-line functions
are just as hard to understand as a single thousand-line function.
-@subsection Function Prototypes
+@emph{Macros are bad, M'kay.}
+(But if you have to use a macro, make sure that the macro arguments are
+protected with parentheses.)
+
+@cindex types
+Declarations like @samp{struct foo *} should be used in preference to
+declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
+
+
+@subsection Function Prototypes
@cindex function prototypes
-Prototypes must be used to @emph{declare} functions, and may be used
-to @emph{define} them. Prototypes for @value{GDBN} functions must
-include both the argument type and name, with the name matching that
-used in the actual function definition.
+
+Prototypes must be used when both @emph{declaring} and @emph{defining}
+a function. Prototypes for @value{GDBN} functions must include both the
+argument type and name, with the name matching that used in the actual
+function definition.
All external functions should have a declaration in a header file that
callers include, except for @code{_initialize_*} functions, which must
be external so that @file{init.c} construction works, but shouldn't be
visible to random source files.
-All static functions must be declared in a block near the top of the
-source file.
+Where a source file needs a forward declaration of a static function,
+that declaration must appear in a block near the top of the source file.
+
+
+@subsection Internal Error Recovery
+
+During its execution, @value{GDBN} can encounter two types of errors.
+User errors and internal errors. User errors include not only a user
+entering an incorrect command but also problems arising from corrupt
+object files and system errors when interacting with the target.
+Internal errors include situations where @value{GDBN} has detected, at
+run time, a corrupt or erroneous situation.
+
+When reporting an internal error, @value{GDBN} uses
+@code{internal_error} and @code{gdb_assert}.
+
+@value{GDBN} must not call @code{abort} or @code{assert}.
+
+@emph{Pragmatics: There is no @code{internal_warning} function. Either
+the code detected a user error, recovered from it and issued a
+@code{warning} or the code failed to correctly recover from the user
+error and issued an @code{internal_error}.}
+
+@subsection File Names
+
+Any file used when building the core of @value{GDBN} must be in lower
+case. Any file used when building the core of @value{GDBN} must be 8.3
+unique. These requirements apply to both source and generated files.
+
+@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
+platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
+is introduced to the build process both @file{Makefile.in} and
+@file{configure.in} need to be modified accordingly. Compare the
+convoluted conversion process needed to transform @file{COPYING} into
+@file{copying.c} with the conversion needed to transform
+@file{version.in} into @file{version.c}.}
+
+Any file non 8.3 compliant file (that is not used when building the core
+of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
+
+@emph{Pragmatics: This is clearly a compromise.}
+
+When @value{GDBN} has a local version of a system header file (ex
+@file{string.h}) the file name based on the POSIX header prefixed with
+@file{gdb_} (@file{gdb_string.h}).
+
+For other files @samp{-} is used as the separator.
+
+
+@subsection Include Files
+
+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.
+
+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.
+
+An external declaration should only appear in one include file.
+
+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
+#define INCLUDE_FILE_NAME_H
+header body
+#endif
+@end smallexample
+
@subsection Clean Design and Portable Implementation
with regard to this feature.
Adding code that handles specific architectures, operating systems,
-target interfaces, or hosts, is not acceptable in generic code. If a
-hook is needed at that point, invent a generic hook and define it for
-your configuration, with something like:
-
-@example
-#ifdef WRANGLE_SIGNALS
- WRANGLE_SIGNALS (signo);
-#endif
-@end example
-
-In your host, target, or native configuration file, as appropriate,
-define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take a
-bit of care in defining the hook, so that it can be used by other ports
-in the future, if they need a hook in the same place.
-
-If the hook is not defined, the code should do whatever ``most'' machines
-want. Using @code{#ifdef}, as above, is the preferred way to do this,
-but sometimes that gets convoluted, in which case use
-
-@example
-#ifndef SPECIAL_FOO_HANDLING
-#define SPECIAL_FOO_HANDLING(pc, sp) (0)
-#endif
-@end example
-
-@noindent
-where the macro is used or in an appropriate header file.
-
-Whether to include a @dfn{small} hook, a hook around the exact pieces of
-code which are system-dependent, or whether to replace a whole function
-with a hook, depends on the case. A good example of this dilemma can be
-found in @code{get_saved_register}. All machines that @value{GDBN} 2.8 ran on
-just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
-registers. Then the SPARC and Pyramid came along, and
-@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
-introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
-hook. The first three are examples of small hooks; the latter replaces
-a whole function. In this specific case, it is useful to have both
-kinds; it would be a bad idea to replace all the uses of the small hooks
-with @code{GET_SAVED_REGISTER}, since that would result in much
-duplicated code. Other times, duplicating a few lines of code here or
-there is much cleaner than introducing a large number of small hooks.
+target interfaces, or hosts, is not acceptable in generic code.
@cindex portable file name handling
@cindex file names, portability
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
file would (hooks, @code{#if defined}, etc.), and machines which are
radically different don't need to use @file{infptrace.c} at all.
-Don't put debugging @code{printf}s in the code.
+All debugging code must be controllable using the @samp{set debug
+@var{module}} command. Do not use @code{printf} to print trace
+messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
+@code{#ifdef DEBUG}.
+
@node Porting GDB
@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}}
setting @code{gdb_target} to something appropriate (for instance,
@var{xyz}).
+@emph{Maintainer's note: Work in progress. The file
+@file{gdb/configure.host} originally needed to be modified when either a
+new native target or a new host machine was being added to @value{GDBN}.
+Recent changes have removed this requirement. The file now only needs
+to be modified when adding a new native configuration. This will likely
+changed again in the future.}
+
@item
Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
target-dependent @file{.h} and @file{.c} files used for your
configuration.
@end itemize
-@section Configuring @value{GDBN} for Release
+@node Releasing GDB
+
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
+
+@section Versions and Branches
+
+@subsection Version Identifiers
+
+@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
+
+@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 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).
+
+Using 5.1 (previous) and 5.2 (current), the example below illustrates a
+typical sequence of version identifiers:
+
+@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
+@end table
+
+Notes:
+
+@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
+
+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).
+
+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.
+
+
+@subsection Branches
+
+@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).
+
+Releases 5.0 and 5.1 used branch and release tags of the form:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-YYYY-MM-DD-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+Release 5.2 is trialing the branch and release tags:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+@emph{Pragmatics: The branchpoint and release tags need to identify when
+a branch and release are made. The branch tag, denoting the head of the
+branch, does not have this criteria.}
+
+
+@section Branch Commit Policy
+
+The branch commit policy is pretty slack. @value{GDBN} releases 5.0,
+5.1 and 5.2 all used the below:
+
+@itemize @bullet
+@item
+The @file{gdb/MAINTAINERS} file still holds.
+@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.
+@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}
+when debugging a static binary?
+@item
+The further a change is from the core of @value{GDBN}, the less likely
+the change will worry anyone (e.g., target specific code).
+@item
+Only post a proposal to change the core of @value{GDBN} after you've
+sent individual bribes to all the people listed in the
+@file{MAINTAINERS} file @t{;-)}
+@end itemize
+
+@emph{Pragmatics: Provided updates are restricted to non-core
+functionality there is little chance that a broken change will be fatal.
+This means that changes such as adding a new architectures or (within
+reason) support for a new host are considered acceptable.}
+
+
+@section Obsoleting code
-@cindex preparing a release
-@cindex making a distribution tarball
-From the top level directory (containing @file{gdb}, @file{bfd},
-@file{libiberty}, and so on):
+Before anything else, poke the other developers (and around the source
+code) to see if there is anything that can be removed from @value{GDBN}
+(an old target, an unused file).
-@example
-make -f Makefile.in gdb.tar.gz
-@end example
+Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
+line. Doing this means that it is easy to identify something that has
+been obsoleted when greping through the sources.
+
+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.
+
+@enumerate
+@item
+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.
+@item
+Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
+Announcement mailing list}.
+@item
+Wait a week or so.
+@item
+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
-This will properly configure, clean, rebuild any files that are
-distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
-and will then make a tarfile. (If the top level directory has already
-been configured, you can just do @code{make gdb.tar.gz} instead.)
+@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.}
+
+
+
+@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
+instance, configuration problems that stop @value{GDBN} from even
+building. If you can't get the problem fixed, document it in the
+@file{gdb/PROBLEMS} file.
-This procedure requires:
+@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.
+
+@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
+@file{texinfo/texinfo.tex}
+@item
+@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
+file)
+@item
+@file{etc/standards.texi}, @file{etc/make-stds.texi}
+@end itemize
+
+@subheading Check the ARI
-@item
-symbolic links;
+@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
+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
+Insight (which includes GDB) and dejagnu are all tagged at the same time
+@item
+@file{version.in} gets bumped to avoid version number conflicts
@item
-@code{makeinfo} (texinfo2 level);
+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
-@TeX{};
+@file{.90} and the previous branch version are used as fairly arbitrary
+initial branch version number
+@end itemize
+
+
+@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
-@code{dvips};
+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
-@code{yacc} or @code{bison}.
+@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.
+
+@section Create a Release
+
+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).
+
+@subsubheading Freeze the branch
+
+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_2-branch/5.2
+$ which autoconf
+/home/gdbadmin/bin/autoconf
+$
+@end smallexample
+
@noindent
-@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
+Notes:
-@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
+@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
-@file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
-which are not yet a default for anything (but we have to start using
-them sometime).
+@subsubheading Check out the relevant modules:
-For making paper, the only thing this implies is the right generation of
-@file{texinfo.tex} needs to be included in the distribution.
+@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 smallexample
-For making info files, however, rather than duplicating the texinfo2
-distribution, generate @file{gdb-all.texinfo} locally, and include the
-files @file{gdb.info*} in the distribution. Note the plural;
-@code{makeinfo} will split the document into one overall file and five
-or so included files.
+@noindent
+Note:
+
+@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 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 include the @file{ChangeLog} entry.
+
+@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 smallexample
+
+@item gdb/README
+
+You'll need to update:
+
+@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 smallexample
+
+@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.}
+
+@item gdb/version.in
+
+@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 smallexample
+
+@item dejagnu/src/dejagnu/configure.in
+
+Dejagnu is more complicated. The version number is a parameter to
+@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
+
+Don't forget to re-generate @file{configure}.
+
+Don't forget to include a @file{ChangeLog} entry.
+
+@smallexample
+$ emacs dejagnu/src/dejagnu/configure.in
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ ( cd dejagnu/src/dejagnu && autoconf )
+@end smallexample
+
+@end table
+
+@subsubheading Do the dirty work
+
+This is identical to the process used to create the daily snapshot.
+
+@smallexample
+$ for m in gdb insight
+do
+( cd $m/src && gmake -f src-release $m.tar )
+done
+$ ( m=dejagnu; cd $m/src && gmake -f src-release $m.tar.bz2 )
+@end smallexample
+
+If the top level source directory does not have @file{src-release}
+(@value{GDBN} version 5.3.1 or earlier), try these commands instead:
+
+@smallexample
+$ for m in gdb insight
+do
+( cd $m/src && gmake -f Makefile.in $m.tar )
+done
+$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+@end smallexample
+
+@subsubheading Check the source files
+
+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}.
+
+@smallexample
+$ ( cd gdb/src && cvs -f -q -n update )
+M djunpack.bat
+? gdb-5.1.91.tar
+? proto-toplev
+@dots{} lots of generated files @dots{}
+M gdb/ChangeLog
+M gdb/NEWS
+M gdb/README
+M gdb/version.in
+@dots{} lots of generated files @dots{}
+$
+@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.}
+
+@subsubheading Create compressed versions of the release
+
+@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
+
+@noindent
+Note:
+
+@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
+
+@subsection Sanity check the tar ball
+
+Pick a popular machine (Solaris/PPC?) and try the build on that.
+
+@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
+
+@subsection Make a release candidate available
+
+If this is a release candidate then the only remaining steps are:
+
+@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
+
+(And you thought all that was required was to post an e-mail.)
+
+@subsubheading Install on sware
+
+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 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
+
+@subsubheading Update the web pages.
+
+@table @file
+
+@item htdocs/download/ANNOUNCEMENT
+This file, which is posted as the official announcement, includes:
+@itemize @bullet
+@item
+General announcement
+@item
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
+@item
+Errata
+@end itemize
+
+@item htdocs/index.html
+@itemx htdocs/news/index.html
+@itemx htdocs/download/index.html
+These files include:
+@itemize @bullet
+@item
+announcement of the most recent release
+@item
+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}.
+
+@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 @code{cron} jobs and then just edit accordingly.
+Something like:
+
+@smallexample
+$ ~/ss/update-web-docs \
+ ~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/download/ari \
+ gdb
+@end smallexample
+
+@end table
+
+@subsubheading Shadow the pages onto gnu
+
+Something goes here.
+
+
+@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
+@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
+
+@subsection Cleanup
+
+The release is out but you're still not finished.
+
+@subsubheading Commit outstanding changes
+
+In particular you'll need to commit any changes to:
+
+@itemize @bullet
+@item
+@file{gdb/ChangeLog}
+@item
+@file{gdb/version.in}
+@item
+@file{gdb/NEWS}
+@item
+@file{gdb/README}
+@end itemize
+
+@subsubheading Tag the release
+
+Something like:
+
+@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_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).
+
+@subsubheading Mention the release on the trunk
+
+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.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}.
+
+@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.
@node Testsuite
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
changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
etc) can be
contributed with only one piece of legalese pushed through the
-bureacracy and filed with the FSF. We can't start merging changes until
+bureaucracy and filed with the FSF. We can't start merging changes until
this paperwork is received by the FSF (their rules, which we follow
since we maintain it for them).
be for quite some time.
Please send patches directly to
-@email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}.
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
@section Obsolete Conditionals
@cindex obsolete code
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
+
@node Index
@unnumbered Index
@printindex cp
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@ifinfo
-@contents
-@end ifinfo
-@ifhtml
-@contents
-@end ifhtml
-
@bye
projects / deliverable / binutils-gdb.git / blobdiff