From: Andrew Cagney Date: Thu, 26 Jul 2001 18:38:29 +0000 (+0000) Subject: * gdbint.texinfo (libgdb): Rewrite. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=89437448ae911e81e6b2c171eee0cf6e5ad42c5c;p=binutils-gdb.git * gdbint.texinfo (libgdb): Rewrite. --- diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 793885c520d..5d434dfa3a2 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +2001-07-25 Andrew Cagney + + * gdbint.texinfo (libgdb): Rewrite. + 2001-07-26 Eli Zaretskii * Makefile.in (gdbgui.dvi, gdb-gui, gdbgui.info): Targets deleted. diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 0287034b4c1..dae206021a4 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -87,6 +87,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Overall Structure:: * Algorithms:: * User Interface:: +* libgdb:: * Symbol Handling:: * Language Support:: * Host Definition:: @@ -1371,11 +1372,119 @@ It became: @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