gdbint.texinfo

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

It became:

@smallexample
  annotate_field (5);
  if (b->forked_inferior_pid != 0)
    @{
      ui_out_text (uiout, "process ");
      ui_out_field_int (uiout, "what", b->forked_inferior_pid);
      ui_out_spaces (uiout, 1);
    @}
@end smallexample

Here's an example of using @code{ui_out_field_string}.  The original
code was:

@smallexample
  annotate_field (5);
  if (b->exec_pathname != NULL)
    printf_filtered ("program \"%s\" ", b->exec_pathname);
@end smallexample

It became:

@smallexample
  annotate_field (5);
  if (b->exec_pathname != NULL)
    @{
      ui_out_text (uiout, "program \"");
      ui_out_field_string (uiout, "what", b->exec_pathname);
      ui_out_text (uiout, "\" ");
    @}
@end smallexample

Finally, here's an example of printing an address.  The original code:

@smallexample
  annotate_field (4);
  printf_filtered ("%s ",
        hex_string_custom ((unsigned long) b->address, 8));
@end smallexample

It became:

@smallexample
  annotate_field (4);
  ui_out_field_core_addr (uiout, "Address", b->address);
@end smallexample


@section Console Printing

@section TUI

@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} 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{GDBN} 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 Symbol Handling

Symbols are a key part of @value{GDBN}'s operation.  Symbols include variables,
functions, and types.

@section Symbol Reading

@cindex symbol reading
@cindex reading of symbols
@cindex symbol files
@value{GDBN} reads symbols from @dfn{symbol files}.  The usual symbol
file is the file containing the program which @value{GDBN} is
debugging.  @value{GDBN} can be directed to use a different file for
symbols (with the @samp{symbol-file} command), and it can also read
more symbols via the @samp{add-file} and @samp{load} commands, or while
reading symbols from shared libraries.

@findex find_sym_fns
Symbol files are initially opened by code in @file{symfile.c} using
the BFD library (@pxref{Support Libraries}).  BFD identifies the type
of the file by examining its header.  @code{find_sym_fns} then uses
this identification to locate a set of symbol-reading functions.

@findex add_symtab_fns
@cindex @code{sym_fns} structure
@cindex adding a symbol-reading module
Symbol-reading modules identify themselves to @value{GDBN} by calling
@code{add_symtab_fns} during their module initialization.  The argument
to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
name (or name prefix) of the symbol format, the length of the prefix,
and pointers to four functions.  These functions are called at various
times to process symbol files whose identification matches the specified
prefix.

The functions supplied by each module are:

@table @code
@item @var{xyz}_symfile_init(struct sym_fns *sf)

@cindex secondary symbol file
Called from @code{symbol_file_add} when we are about to read a new
symbol file.  This function should clean up any internal state (possibly
resulting from half-read previous files, for example) and prepare to
read a new symbol file.  Note that the symbol file which we are reading
might be a new ``main'' symbol file, or might be a secondary symbol file
whose symbols are being added to the existing symbol table.

The argument to @code{@var{xyz}_symfile_init} is a newly allocated
@code{struct sym_fns} whose @code{bfd} field contains the BFD for the
new symbol file being read.  Its @code{private} field has been zeroed,
and can be modified as desired.  Typically, a struct of private
information will be @code{malloc}'d, and a pointer to it will be placed
in the @code{private} field.

There is no result from @code{@var{xyz}_symfile_init}, but it can call
@code{error} if it detects an unavoidable problem.

@item @var{xyz}_new_init()

Called from @code{symbol_file_add} when discarding existing symbols.
This function needs only handle the symbol-reading module's internal
state; the symbol table data structures visible to the rest of
@value{GDBN} will be discarded by @code{symbol_file_add}.  It has no
arguments and no result.  It may be called after
@code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
may be called alone if all symbols are simply being discarded.

@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)

Called from @code{symbol_file_add} to actually read the symbols from a
symbol-file into a set of psymtabs or symtabs.

@code{sf} points to the @code{struct sym_fns} originally passed to
@code{@var{xyz}_sym_init} for possible initialization.  @code{addr} is
the offset between the file's specified start address and its true
address in memory.  @code{mainline} is 1 if this is the main symbol
table being read, and 0 if a secondary symbol file (e.g. shared library
or dynamically loaded file) is being read.@refill
@end table

In addition, if a symbol-reading module creates psymtabs when
@var{xyz}_symfile_read is called, these psymtabs will contain a pointer
to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
from any point in the @value{GDBN} symbol-handling code.

@table @code
@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)

Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
the psymtab has not already been read in and had its @code{pst->symtab}
pointer set.  The argument is the psymtab to be fleshed-out into a
symtab.  Upon return, @code{pst->readin} should have been set to 1, and
@code{pst->symtab} should contain a pointer to the new corresponding symtab, or
zero if there were no symbols in that part of the symbol file.
@end table

@section Partial Symbol Tables

@value{GDBN} has three types of symbol tables:

@itemize @bullet
@cindex full symbol table
@cindex symtabs
@item
Full symbol tables (@dfn{symtabs}).  These contain the main
information about symbols and addresses.

@cindex psymtabs
@item
Partial symbol tables (@dfn{psymtabs}).  These contain enough
information to know when to read the corresponding part of the full
symbol table.

@cindex minimal symbol table
@cindex minsymtabs
@item
Minimal symbol tables (@dfn{msymtabs}).  These contain information
gleaned from non-debugging symbols.
@end itemize

@cindex partial symbol table
This section describes partial symbol tables.

A psymtab is constructed by doing a very quick pass over an executable
file's debugging information.  Small amounts of information are
extracted---enough to identify which parts of the symbol table will
need to be re-read and fully digested later, when the user needs the
information.  The speed of this pass causes @value{GDBN} to start up very
quickly.  Later, as the detailed rereading occurs, it occurs in small
pieces, at various times, and the delay therefrom is mostly invisible to
the user.
@c (@xref{Symbol Reading}.)

The symbols that show up in a file's psymtab should be, roughly, those
visible to the debugger's user when the program is not running code from
that file.  These include external symbols and types, static symbols and
types, and @code{enum} values declared at file scope.

The psymtab also contains the range of instruction addresses that the
full symbol table would represent.

@cindex finding a symbol
@cindex symbol lookup
The idea is that there are only two ways for the user (or much of the
code in the debugger) to reference a symbol:

@itemize @bullet
@findex find_pc_function
@findex find_pc_line
@item
By its address (e.g. execution stops at some address which is inside a
function in this file).  The address will be noticed to be in the
range of this psymtab, and the full symtab will be read in.
@code{find_pc_function}, @code{find_pc_line}, and other
@code{find_pc_@dots{}} functions handle this.

@cindex lookup_symbol
@item
By its name
(e.g. the user asks to print a variable, or set a breakpoint on a
function).  Global names and file-scope names will be found in the
psymtab, which will cause the symtab to be pulled in.  Local names will
have to be qualified by a global name, or a file-scope name, in which
case we will have already read in the symtab as we evaluated the
qualifier.  Or, a local symbol can be referenced when we are ``in'' a
local scope, in which case the first case applies.  @code{lookup_symbol}
does most of the work here.
@end