@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
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
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::
* Index::
@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.
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})
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:
-
-@example
-<field> ::= any single item of data kept by gdb ;;
-
-<list> ::= @{ <field> @} ;;
-
-<table> ::= <header> @{ <list> @} ;;
+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:
-<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}.
+@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 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.
+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.
-Use the list functions for the output of each object of a table or if
-your output consists of a single list of fields.
-
-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
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
-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_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
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");
+ nr_printable_breakpoints = @dots{};
- ui_out_table_body (ui);
- annotate_breakpoints_table ();
- @}
+ 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 example
This example, from the @code{print_one_breakpoint} function, shows how
printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
+ @dots{}
@end example
This is the new version:
@example
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]);
+ @dots{}
@end example
This example, also from @code{print_one_breakpoint}, shows how to
@section TUI
-@section libgdb
+@node libgdb
+@chapter libgdb
+
+@section libgdb 1.0
+@cindex @code{libgdb}
+@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} was an abortive project of years ago. The theory was to
-provide an API to @value{GDBN}'s functionality.
+@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
@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
@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
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 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
@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 the
+sections below are likely to be made obsolete. See the file @file{TODO}
+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.
In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
@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,
@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
+@cindex @code{float} arguments
+@cindex prototyped functions, passing arguments to
+@cindex passing arguments to prototyped functions
+Return non-zero if GDB should promote @code{float} values to
+@code{double} when calling a non-prototyped function. 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.
+
+How you should pass arguments to a function depends on whether it was
+defined in K&R style or prototype style. If you define a function using
+the K&R syntax that takes a @code{float} argument, then callers must
+pass that argument as a @code{double}. If you define the function using
+the prototype syntax, then you must pass the argument as a @code{float},
+with no promotion.
+
+Unfortunately, on certain older platforms, the debug info doesn't
+indicate reliably how each function was defined. A function type's
+@code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was
+defined in prototype style. When calling a function whose
+@code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the
+@code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do.
+
@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.
+For modern targets, it is proper to assume that, if the prototype flag
+is unset, that can be trusted: @code{float} arguments should be promoted
+to @code{double}. You should use the function
+@code{standard_coerce_float_to_double} to get this behavior.
+
+@findex default_coerce_float_to_double
+For some older targets, if the prototype flag is unset, that doesn't
+tell us anything. So we guess that, if we don't have a type for the
+formal parameter (@i{i.e.}, the first argument to
+@code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it;
+otherwise, we should leave it alone. The function
+@code{default_coerce_float_to_double} provides this behavior; it is the
+default value, for compatibility with older configurations.
@item CPLUS_MARKER
@findex CPLUS_MARKERz
@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}.
represented by @var{fi} does not have a stack frame associated with it.
Otherwise return 0.
-@item FRAME_ARGS_ADDRESS_CORRECT@item
+@item FRAME_ARGS_ADDRESS_CORRECT
@findex FRAME_ARGS_ADDRESS_CORRECT
See @file{stack.c}.
@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
If additional information about the frame is required this should be
the target's stack grows downward in memory, or @code{lhs > rsh} if the
stack grows upward.
+@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 IN_SIGTRAMP (@var{pc}, @var{name})
@findex IN_SIGTRAMP
Define this to return non-zero if the given @var{pc} and/or @var{name}
to set a breakpoint to get through the dynamic linker and that single
stepping will suffice.
+@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 IS_TRAPPED_INTERNALVAR (@var{name})
@findex IS_TRAPPED_INTERNALVAR
This is an ugly hook to allow the specification of special actions that
@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{BFD_ENDIAN_BIG} or @code{BFD_ENDIAN_LITTLE}. 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}.
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 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
@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
@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. Perhaphs 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.:
+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});
+Same as @code{do_cleanups} except that it just removes the cleanups from
+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.:
@example
make_cleanup (a, 0);
-old = make_cleanup (b, 0);
-do_cleanups (old);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 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
+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:
-@findex discard_cleanups
-@item discard_cleanups (@var{old_chain});
-Same as @code{do_cleanups} except that it just removes the cleanups from
-the chain and does not call the specified functions.
-@end table
+@example
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@end example
+
+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:
+
+@example
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@end example
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
@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-C 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.
+
+@example
+/* Declaration */
+static void foo (void);
+/* Definition */
+void
+foo (void)
+@{
+@}
+@end example
+
+@emph{Pragmatics: This simplifies scripting. Function definitions can
+be found using @samp{^function-name}.}
-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.
+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:
+
+@example
+void *foo;
+@end example
+
+@noindent
+and not:
+
+@example
+void * foo;
+void* foo;
+@end example
@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
/* Wait for control to return from inferior to debugger. If inferior
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 situtations where @value{GDBN} has detected, at
+run time, a corrupt or erroneous situtation.
+
+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 Clean Design
+@subsection Include Files
+
+All @file{.c} files should include @file{defs.h} first.
+
+All @file{.c} files should explicitly include the headers for any
+declarations they refer to. They should not rely on files being
+included indirectly.
+
+With the exception of the global definitions supplied by @file{defs.h},
+a header file should explictily include the header declaring any
+@code{typedefs} et.al.@: it refers to.
+
+@code{extern} declarations should never appear in @code{.c} files.
+
+All include files should be wrapped in:
+
+@example
+#ifndef INCLUDE_FILE_NAME_H
+#define INCLUDE_FILE_NAME_H
+header body
+#endif
+@end example
+
+
+@subsection Clean Design and Portable Implementation
@cindex design
In addition to getting the syntax right, there's the little question of
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
+target interfaces, or hosts, is not acceptable in generic code.
+
+@cindex portable file name handling
+@cindex file names, portability
+One particularly notorious area where system dependencies tend to
+creep in is handling of file names. The mainline @value{GDBN} code
+assumes Posix semantics of file names: absolute file names begin with
+a forward slash @file{/}, slashes are used to separate leading
+directories, case-sensitive file names. These assumptions are not
+necessarily true on non-Posix systems such as MS-Windows. To avoid
+system-dependent code where you need to take apart or construct a file
+name, use the following portable macros:
-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
+@table @code
+@findex HAVE_DOS_BASED_FILE_SYSTEM
+@item HAVE_DOS_BASED_FILE_SYSTEM
+This preprocessing symbol is defined to a non-zero value on hosts
+whose filesystems belong to the MS-DOS/MS-Windows family. Use this
+symbol to write conditional code which should only be compiled for
+such hosts.
+
+@findex IS_DIR_SEPARATOR
+@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
+pass.
+
+@findex IS_ABSOLUTE_PATH
+@item IS_ABSOLUTE_PATH (@var{file})
+Evaluates to a non-zero value if @var{file} is an absolute file name.
+For Unix and GNU/Linux hosts, a name which begins with a slash
+@file{/} is absolute. On DOS and Windows, @file{d:/foo} and
+@file{x:\bar} are also absolute file names.
+
+@findex FILENAME_CMP
+@item FILENAME_CMP (@var{f1}, @var{f2})
+Calls a function which compares file names @var{f1} and @var{f2} as
+appropriate for the underlying host filesystem. For Posix systems,
+this simply calls @code{strcmp}; on case-insensitive filesystems it
+will call @code{strcasecmp} instead.
+
+@findex DIRNAME_SEPARATOR
+@item DIRNAME_SEPARATOR
+Evaluates to a character which separates directories in
+@code{PATH}-style lists, typically held in environment variables.
+This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
+
+@findex SLASH_STRING
+@item SLASH_STRING
+This evaluates to a constant string you should use to produce an
+absolute filename from leading directories and the file's basename.
+@code{SLASH_STRING} is @code{"/"} on most systems, but might be
+@code{"\\"} for some Windows-based ports.
+@end table
-@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.
+In addition to using these macros, be sure to use portable library
+functions whenever possible. For example, to extract a directory or a
+basename part from a file name, use the @code{dirname} and
+@code{basename} library functions (available in @code{libiberty} for
+platforms which don't provide them), instead of searching for a slash
+with @code{strrchr}.
Another way to generalize @value{GDBN} along a particular interface is with an
attribute struct. For example, @value{GDBN} has been generalized to handle
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
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
@code{makeinfo} will split the document into one overall file and five
or so included files.
+@node Releasing GDB
+
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
+
+@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{PROBLEMS} file.
+
+@subheading Obsolete any code
+
+Mark as @kbd{OBSOLETE} any uninteresting targets or code files. This
+has a number of steps and is slow --- mainly to ensure that people have
+had a reasonable chance to respond. Remember, everything on the
+internet takes a week.
+
+@itemize @bullet
+@item
+announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}
+@item
+wait a week
+@item
+announce the change on @email{gdb-announce@@sources.redhat.com, GDB
+Announcement mailing list}
+@item
+wait a week or so
+@item
+post / commit the change
+@end itemize
+
+@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.@:
+@end itemize
+
+and should be refreshed.
+
+@subheading Organize and announce the schedule.
+
+The following is a possible schedule. It is based on the rule-of-thumb
+that everything on the Internet takes a week. You may want to even
+increase those times further since an analysis of the actual data
+strongly suggests that the below is far to aggressive.
+
+@itemize @bullet
+@item
+announce it
+@item
+wait a week
+@item
+announce branch date
+@item
+wait a week
+@item
+Cut the branch
+@item
+wait a week
+@item
+start enjoying all the fun
+@end itemize
+
+As an aside, the branch tag name is probably regrettable vis:
+@file{gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}}.
+
+
+@section Building a Release
+
+@subheading Establish a few defaults.
+
+@example
+$ b=gdb_5_1_0_1-2002-01-03-branch
+$ v=5.1.0.1
+$ cd /sourceware/snapshot-tmp/gdbadmin-tmp/$b
+$ which autoconf
+/home/gdbadmin/bin/autoconf
+@end example
+
+NB: Check the autoconf version carefully. You want to be using
+@file{gdbadmin}'s version (which is really the version taken from the
+binutils snapshot). SWARE may have a different version installed.
+
+@subheading Check out the relevant modules:
+
+@example
+$ for m in gdb insight dejagnu; do
+( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
+done
+@end example
+
+NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there
+isn't any confusion between what is written here and what CVS really
+does.
+
+@subheading Update the file @file{gdb/version.in} where applicable.
+
+@example
+$ for m in gdb insight; do echo $v > $m/src/gdb/version.in ; done
+@end example
+
+
+@subheading Mutter something about creating a @file{ChangeLog} entry. (both trunk and branch).
+
+@example
+$ emacs gdb/src/gdb/version.in
+c-x 4 a
+Bump version to 5.1.0.1.
+c-x c-s c-x c-c
+@end example
+
+ditto for @file{insight/src/gdb/version.in}
+
+@subheading Mutter something about updating @file{README}
+
+For dejagnu, edit @file{dejagnu/src/dejagnu/configure.in} and set it to
+gdb-$v and then regenerate configure. Mention this in the dejagnu
+@file{ChangeLog}.
+
+@example
+$ emacs dejagnu/src/dejagnu/configure.in
+...
+c-x 4 a
+Bump version to 5.1.0.1.
+* configure: Re-generate.
+c-x c-s c-x c-c
+$ ( cd dejagnu/src/dejagnu && autoconf )
+@end example
+
+@subheading Build the snapshot:
+
+@example
+$ for m in gdb insight dejagnu; do
+( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+done
+@end example
+
+@subheading Do another @kbd{CVS update} to see what the damage is.
+
+@example
+$ ( cd gdb/src && cvs -q update )
+@end example
+
+You're looking for files that have mysteriously disappeared as the
+@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
+for the @file{version.in} update cronjob.
+
+@subheading Copy all the @file{.bz2} files to the ftp directory:
+
+@example
+cp */src/*.bz2 ~ftp/.....
+@end example
+
+@subheading Something about @kbd{gzip}'ing them.
+
+@subheading Something about web pages?
+
+@subheading Something about documentation?
+
+@subheading Cleanup the release tree
+
+In particular you'll need to:
+
+@itemize @bullet
+@item
+Commit the changes to @file{ChangeLog} and @file{version.in}
+@item
+Tag the repository.
+@end itemize
+
+
+@section After the release
+
+Remove any @kbd{OBSOLETE} code.
+
+
@node Testsuite
@chapter Testsuite
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).
@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