gdbint.texinfo

这个是LINUX下的GDB调度工具的源码

bits in the mirror images of the debug registers.  It doesn't affect
the actual debug registers in the inferior process.
@end table

@noindent
@strong{Notes:}
@enumerate 1
@item
x86 processors support setting watchpoints on I/O reads or writes.
However, since no target supports this (as of March 2001), and since
@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O
watchpoints, this feature is not yet available to @value{GDBN} running
on x86.

@item
x86 processors can enable watchpoints locally, for the current task
only, or globally, for all the tasks.  For each debug register,
there's a bit in the DR7 Debug Control register that determines
whether the associated address is watched locally or globally.  The
current implementation of x86 watchpoint support in @value{GDBN}
always sets watchpoints to be locally enabled, since global
watchpoints might interfere with the underlying OS and are probably
unavailable in many platforms.
@end enumerate

@section Observing changes in @value{GDBN} internals
@cindex observer pattern interface
@cindex notifications about changes in internals

In order to function properly, several modules need to be notified when
some changes occur in the @value{GDBN} internals.  Traditionally, these
modules have relied on several paradigms, the most common ones being
hooks and gdb-events.  Unfortunately, none of these paradigms was
versatile enough to become the standard notification mechanism in
@value{GDBN}.  The fact that they only supported one ``client'' was also
a strong limitation.

A new paradigm, based on the Observer pattern of the @cite{Design
Patterns} book, has therefore been implemented.  The goal was to provide
a new interface overcoming the issues with the notification mechanisms
previously available.  This new interface needed to be strongly typed,
easy to extend, and versatile enough to be used as the standard
interface when adding new notifications.

See @ref{GDB Observers} for a brief description of the observers
currently implemented in GDB. The rationale for the current
implementation is also briefly discussed.

@node User Interface

@chapter User Interface

@value{GDBN} has several user interfaces.  Although the command-line interface
is the most common and most familiar, there are others.

@section Command Interpreter

@cindex command interpreter
@cindex CLI
The command interpreter in @value{GDBN} is fairly simple.  It is designed to
allow for the set of commands to be augmented dynamically, and also
has a recursive subcommand capability, where the first argument to
a command may itself direct a lookup on a different command list.

For instance, the @samp{set} command just starts a lookup on the
@code{setlist} command list, while @samp{set thread} recurses
to the @code{set_thread_cmd_list}.

@findex add_cmd
@findex add_com
To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
the main command list, and should be used for those commands.  The usual
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
deprecate them for some time.  Use @code{deprecate_cmd} on commands or
aliases to set the deprecated flag.  @code{deprecate_cmd} takes a
@code{struct cmd_list_element} as it's first argument.  You can use the
return value from @code{add_com} or @code{add_cmd} to deprecate the
command immediately after it is created.

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.

@section UI-Independent Output---the @code{ui_out} Functions
@c This section is based on the documentation written by Fernando
@c Nasser <[e-mail]>.

@cindex @code{ui_out} functions
The @code{ui_out} functions present an abstraction level for the
@value{GDBN} output code.  They hide the specifics of different user
interfaces supported by @value{GDBN}, and thus free the programmer
from the need to write several versions of the same code, one each for
every UI, to produce output.

@subsection Overview and Terminology

In general, execution of each @value{GDBN} command produces some sort
of output, and can even generate an input request.

Output can be generated for the following purposes:

@itemize @bullet
@item
to display a @emph{result} of an operation;

@item
to convey @emph{info} or produce side-effects of a requested
operation;

@item
to provide a @emph{notification} of an asynchronous event (including
progress indication of a prolonged asynchronous operation);

@item
to display @emph{error messages} (including warnings);

@item
to show @emph{debug data};

@item
to @emph{query} or prompt a user for input (a special case).
@end itemize

@noindent
This section mainly concentrates on how to build result output,
although some of it also applies to other kinds of output.

Generation of output that displays the results of an operation
involves one or more of the following:

@itemize @bullet
@item
output of the actual data

@item
formatting the output as appropriate for console output, to make it
easily readable by humans

@item
machine oriented formatting--a more terse formatting to allow for easy
parsing by programs which read @value{GDBN}'s output

@item
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
deprecated.

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:

@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

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 @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.


@subsection Table, Tuple and List Functions

@cindex list output functions
@cindex table output functions
@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.

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 @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
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:

@smallexample
  ui_out_table_begin
    ui_out_table_header
    @dots{}
    ui_out_table_body
      ui_out_tuple_begin
        ui_out_field_*
        @dots{}
      ui_out_tuple_end
      @dots{}
  ui_out_table_end
@end smallexample

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}, 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}, 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.
@end deftypefun

@deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
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.

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.
@end deftypefun

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 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_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.
@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