annotate.texinfo

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

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename annotate.info

@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
@dircategory Software development
@direntry
* Annotate: (annotate).                 The obsolete annotation interface.
@end direntry

@c
@include gdb-cfg.texi
@c
@settitle @value{GDBN}'s Obsolete Annotations
@setchapternewpage off
@c %**end of header

@set EDITION 1.0
@set DATE July 2003

@c NOTE: cagney/2003-07-28:
@c Don't make this migration doccument an appendix of GDB's user guide.
@c By keeping this separate, the size of the user guide is contained. If
@c the user guide to get much bigger it would need to switch to a larger,
@c more expensive, form factor and would drive up the manuals publication
@c cost.  Having a smaller cheaper manual helps the GNU Press with its sales.

@ifinfo
This file documents @value{GDBN}'s obsolete annotations.

Copyright 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.

@end ifinfo

@titlepage
@title @value{GDBN}'s Obsolete Annotations
@subtitle Edition @value{EDITION}
@subtitle @value{DATE}
@author Free Software Foundation
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end titlepage

@ifinfo
@node Top
@top GDB Annotations

This document describes the obsolete level two annotation interface
implemented in older @value{GDBN} versions.

@ignore
This is Edition @value{EDITION}, @value{DATE}.
@end ignore
@end ifinfo

@menu
* Annotations Overview::  What annotations are; the general syntax.
* Limitations::           Limitations of the annotation interface.
* Migrating to GDB/MI::   Migrating to GDB/MI
* Server Prefix::       Issuing a command without affecting user state.
* Value Annotations::   Values are marked as such.
* Frame Annotations::   Stack frames are annotated.
* Displays::            @value{GDBN} can be told to display something periodically.
* Prompting::           Annotations marking @value{GDBN}'s need for input.
* Errors::              Annotations for error messages.
* Breakpoint Info::     Information on breakpoints.
* Invalidation::        Some annotations describe things now invalid.
* Annotations for Running::
                        Whether the program is running, how it stopped, etc.
* Source Annotations::  Annotations describing source code.

* GNU Free Documentation License::
@end menu

@contents

@node Annotations Overview
@chapter What is an Annotation?
@cindex annotations

To produce obsolete level two annotations, start @value{GDBN} with the
@code{--annotate=2} option.

Annotations start with a newline character, two @samp{control-z}
characters, and the name of the annotation.  If there is no additional
information associated with this annotation, the name of the annotation
is followed immediately by a newline.  If there is additional
information, the name of the annotation is followed by a space, the
additional information, and a newline.  The additional information
cannot contain newline characters.

Any output not beginning with a newline and two @samp{control-z}
characters denotes literal output from @value{GDBN}.  Currently there is
no need for @value{GDBN} to output a newline followed by two
@samp{control-z} characters, but if there was such a need, the
annotations could be extended with an @samp{escape} annotation which
means those three characters as output.

A simple example of starting up @value{GDBN} with annotations is:

@smallexample
$ gdb --annotate=2
GNU GDB 5.0
Copyright 2000 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License,
and you are welcome to change it and/or distribute copies of it
under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty"
for details.
This GDB was configured as "sparc-sun-sunos4.1.3"

^Z^Zpre-prompt
(gdb) 
^Z^Zprompt
quit

^Z^Zpost-prompt
$ 
@end smallexample

Here @samp{quit} is input to @value{GDBN}; the rest is output from
@value{GDBN}.  The three lines beginning @samp{^Z^Z} (where @samp{^Z}
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.

@node Limitations
@chapter Limitations of the Annotation Interface

The level two annotations mechanism is known to have a number of
technical and architectural limitations.  As a consequence, in 2001,
with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
the annotation interface was marked as deprecated.

This chapter discusses the known problems.

@section Dependant on @sc{cli} output

The annotation interface works by interspersing markups with
@value{GDBN} normal command-line interpreter output.  Unfortunately, this
makes the annotation client dependant on not just the annotations, but
also the @sc{cli} output.  This is because the client is forced to
assume that specific @value{GDBN} commands provide specific information.
Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
information and, consequently, likely breaks the client.

Since the @sc{gdb/mi} output is independant of the @sc{cli}, it does not
have this problem.

@section Scalability

The annotation interface relies on value annotations (@pxref{Value
Annotations}) and the display mechanism as a way of obtaining up-to-date
value information.  These mechanisms are not scalable.

In a graphical environment, where many values can be displayed
simultaneously, a serious performance problem occurs when the client
tries to first extract from @value{GDBN}, and then re-display, all those
values.  The client should instead only request and update the values
that changed.

The @sc{gdb/mi} Variable Objects provide just that mechanism.

@section Correctness

The annotation interface assumes that a variable's value can only be
changed when the target is running.  This assumption is not correct.  A
single assignment to a single variable can result in the entire target,
and all displayed values, needing an update.

The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
reporting such changes.

@section Reliability

The @sc{gdb/mi} interface includes a dedicated test directory
(@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
testsuite changes.

@section Maintainability

The annotation mechanism was implemented by interspersing @sc{cli} print
statements with various annotations.  As a consequence, any @sc{cli}
output change can alter the annotation output.

Since the @sc{gdb/mi} output is independant of the @sc{cli}, and the
@sc{gdb/mi} is increasingly implemented independant of the @sc{cli}
code, its long term maintenance is much easier.

@node Migrating to GDB/MI
@chapter Migrating to @sc{gdb/mi}

By using the @samp{interp mi} command, it is possible for annotation
clients to invoke @sc{gdb/mi} commands, and hence access the
@sc{gdb/mi}.  By doing this, existing annotation clients have a
migration path from this obsolete interface to @sc{gdb/mi}.

@node Server Prefix
@chapter The Server Prefix
@cindex server prefix for annotations

To issue a command to @value{GDBN} without affecting certain aspects of
the state which is seen by users, prefix it with @samp{server }.  This
means that this command will not affect the command history, nor will it
affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
pressed on a line by itself.

The server prefix does not affect the recording of values into the value
history; to print a value without recording it into the value history,
use the @code{output} command instead of the @code{print} command.

@node Value Annotations
@chapter Values

@emph{Value Annotations have been removed.  @sc{gdb/mi} instead provides
Variable Objects.}

@cindex annotations for values
When a value is printed in various contexts, @value{GDBN} uses
annotations to delimit the value from the surrounding text.

@findex value-history-begin
@findex value-history-value
@findex value-history-end
If a value is printed using @code{print} and added to the value history,
the annotation looks like

@smallexample
^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
@var{history-string}
^Z^Zvalue-history-value
@var{the-value}
^Z^Zvalue-history-end
@end smallexample

@noindent
where @var{history-number} is the number it is getting in the value
history, @var{history-string} is a string, such as @samp{$5 = }, which
introduces the value to the user, @var{the-value} is the output
corresponding to the value itself, and @var{value-flags} is @samp{*} for
a value which can be dereferenced and @samp{-} for a value which cannot.

@findex value-begin
@findex value-end
If the value is not added to the value history (it is an invalid float
or it is printed with the @code{output} command), the annotation is similar:

@smallexample
^Z^Zvalue-begin @var{value-flags}
@var{the-value}
^Z^Zvalue-end
@end smallexample

@findex arg-begin
@findex arg-name-end
@findex arg-value
@findex arg-end
When @value{GDBN} prints an argument to a function (for example, in the output
from the @code{backtrace} command), it annotates it as follows:

@smallexample
^Z^Zarg-begin
@var{argument-name}
^Z^Zarg-name-end
@var{separator-string}
^Z^Zarg-value @var{value-flags}
@var{the-value}
^Z^Zarg-end
@end smallexample

@noindent
where @var{argument-name} is the name of the argument,
@var{separator-string} is text which separates the name from the value
for the user's benefit (such as @samp{=}), and @var{value-flags} and
@var{the-value} have the same meanings as in a
@code{value-history-begin} annotation.

@findex field-begin
@findex field-name-end
@findex field-value
@findex field-end
When printing a structure, @value{GDBN} annotates it as follows:

@smallexample
^Z^Zfield-begin @var{value-flags}
@var{field-name}
^Z^Zfield-name-end
@var{separator-string}
^Z^Zfield-value
@var{the-value}
^Z^Zfield-end
@end smallexample

@noindent
where @var{field-name} is the name of the field, @var{separator-string}
is text which separates the name from the value for the user's benefit
(such as @samp{=}), and @var{value-flags} and @var{the-value} have the
same meanings as in a @code{value-history-begin} annotation.

When printing an array, @value{GDBN} annotates it as follows:

@smallexample
^Z^Zarray-section-begin @var{array-index} @var{value-flags}
@end smallexample

@noindent
where @var{array-index} is the index of the first element being
annotated and @var{value-flags} has the same meaning as in a
@code{value-history-begin} annotation.  This is followed by any number
of elements, where is element can be either a single element:

@findex elt
@smallexample
@samp{,} @var{whitespace}         ; @r{omitted for the first element}
@var{the-value}
^Z^Zelt
@end smallexample

or a repeated element

@findex elt-rep
@findex elt-rep-end
@smallexample
@samp{,} @var{whitespace}         ; @r{omitted for the first element}
@var{the-value}
^Z^Zelt-rep @var{number-of-repetitions}
@var{repetition-string}
^Z^Zelt-rep-end
@end smallexample

In both cases, @var{the-value} is the output for the value of the
element and @var{whitespace} can contain spaces, tabs, and newlines.  In
the repeated case, @var{number-of-repetitions} is the number of
consecutive array elements which contain that value, and
@var{repetition-string} is a string which is designed to convey to the
user that repetition is being depicted.

@findex array-section-end
Once all the array elements have been output, the array annotation is
ended with

@smallexample
^Z^Zarray-section-end
@end smallexample

@node Frame Annotations
@chapter Frames

@emph{Value Annotations have been removed.  @sc{gdb/mi} instead provides
a number of frame commands.}

@emph{Frame annotations are no longer available.  The @sc{gdb/mi}
provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
@samp{-stack-list-frames} commands.}

@cindex annotations for frames
Whenever @value{GDBN} prints a frame, it annotates it.  For example, this applies
to frames printed when @value{GDBN} stops, output from commands such as
@code{backtrace} or @code{up}, etc.

@findex frame-begin
The frame annotation begins with

@smallexample
^Z^Zframe-begin @var{level} @var{address}
@var{level-string}
@end smallexample

@noindent
where @var{level} is the number of the frame (0 is the innermost frame,
and other frames have positive numbers), @var{address} is the address of
the code executing in that frame, and @var{level-string} is a string
designed to convey the level to the user.  @var{address} is in the form
@samp{0x} followed by one or more lowercase hex digits (note that this
does not depend on the language).  The frame ends with

@findex frame-end
@smallexample
^Z^Zframe-end
@end smallexample

Between these annotations is the main body of the frame, which can
consist of

@itemize @bullet
@item
@findex function-call
@smallexample
^Z^Zfunction-call
@var{function-call-string}
@end smallexample

where @var{function-call-string} is text designed to convey to the user
that this frame is associated with a function call made by @value{GDBN} to a
function in the program being debugged.

@item
@findex signal-handler-caller
@smallexample
^Z^Zsignal-handler-caller
@var{signal-handler-caller-string}