libGDB doco (for gdbint.texinfo)

libGDB doco (for gdbint.texinfo)

[Andrew Cagney]

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.

Re: libGDB doco (for gdbint.texinfo)

[Eli Zaretskii]

> Date: Wed, 18 Jul 2001 01:30:14 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> Below is a quick update to``libgdb''.

Thanks!

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

Ack.  See below.

> @chapter libgdb
> 
> @section libgdb 1.0

We need a few @node's here and there, to make cross-references work
better in the on-line version.

> 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

I'm confused: this seems to say that libgdb is part of itself?

> @itemize @bullet
> @item
> The client registers itself as an observer of @code{libgdb}

There should be a period at the end of this sentence.

> through to the client controlled @code{gdb_stdout} et.al. streams.  At

"et.al." should be written "et.@: al.@:" in Texinfo.

> @subheading Event Loop - @file{event-loop}
> @file{event-loop}, currently non- re-entrant

That should be "non-reentrant" or "non-re-entrant", I think.

Re: libGDB doco (for gdbint.texinfo)

[Andrew Cagney]

>> Query Library - @file{libgdb}
>> @end itemize
> 
> 
> I'm confused: this seems to say that libgdb is part of itself?


Yes, I can't say I blame you.  The comment:

/* FIXME: cagney/1999-12-13: The following will be moved to gdb.h /
   libgdb.h or gdblib.h. */


from near the bottom of defs.h should explain my quandary.

I didn't know what to call it back then, I still don't now ....  Given 
your comment, I guess I should cross ``libgdb'' and ``gdblib'' off the 
list - that leaves just``gdb.h'' :-)

	Andrew

Re: libGDB doco (for gdbint.texinfo)

[Andrew Cagney]

>> Date: Thu, 19 Jul 2001 12:41:31 -0400
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> I didn't know what to call it back then, I still don't now ....  Given 
>> your comment, I guess I should cross ``libgdb'' and ``gdblib'' off the 
>> list - that leaves just``gdb.h'' :-)
> 
> 
> How about gdb_engine?


Like "gdb-engine.h" and:

	gdb_engine_do_this();
	gdb_engine_do_that();

I suspect that just "gdb.h" and:

	gdb_do_this();
	gdb_do_that();

will keep people amused.

	Andrew