libGDB doco (for gdbint.texinfo)

[Andrew Cagney <ac131313 at cygnus dot com>]

Hello,

Below is a quick update to``libgdb''.  The intention is to give the 
reader a high level feel for how the system should hang to gether 
(before they read the code and realize how how far that theory is from 
the truth :-).

I should thank KeithS (Insight) for constantly asking me questions and 
forcing me to get a bit more of the story below straight.  With regard 
to the bi-modal libgdb (alternate between CLI and client) this, in part 
comes from a third-hand description of what Apple did to their GDB branch.

Finally, I should note this is nearer to working as documented (kind of 
mostly :-) than many might think.  Keith identified one big hurdle - the 
way GDB currently processes the target stop - it throws away all the 
information it gathers about why the target stopped :-(.  Fixing it 
involves changes to some pretty nasty WFI code, however, thanks Stan's 
WFI cleanups and Elena MI/WFI changes it isn't too far off :-^

Let the comments, questions, .. begin :-)

	Andrew

@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} 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}.
@item
Builder - @file{ui-out}
@item
Event Loop - @file{event-loop}
@item
Query Library - @file{libgdb}
@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}
@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}
@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}
@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 Query Library - @file{libgdb}
@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.