This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
[rfa:doco] Doco problems with level two annotations
- From: Andrew Cagney <ac131313 at redhat dot com>
- To: gdb-patches at sources dot redhat dot com
- Date: Fri, 16 May 2003 20:18:44 -0400
- Subject: [rfa:doco] Doco problems with level two annotations
Hello,
The attached updates the gdb/doc/annotate.texi file (renaming it to
annotate.texinfo) so that it is a standalone document that:
- notes the limitations of level two annotations
- points the user at gdb/mi
- mentions the mi features that have replaced level two annotation
functionality
ok?
Andrew
2003-05-16 Andrew Cagney <cagney@redhat.com>
* Makefile.in (INFO_DEPS): Add annotate.info.
(dvi, ps, html, pdf): Add annotate.
(ANNOTATE_DOC_SOURCE_INCLUDES): New macro.
(ANNOTATE_DOC_BUILD_INCLUDES): New macro.
(ANNOTATE_DOC_FILES): New macro.
(ANNOTATE_TEX_TMPS): New macro.
(annotate.info, annotate_toc.html): Specify dependencies.
(annotate.ps, annotate.pdf, annotate.dvi): Ditto.
* annotate.texinfo: Rename annotate.texi. Get building. Add
"Migrating to GDB/MI" and "Limitations of the Annotation
Interface" chapters.
--- annotate.texi Fri May 16 19:13:15 2003
+++ annotate.texinfo Fri May 16 20:11:24 2003
@@ -1,64 +1,65 @@
-@c \input texinfo @c -*-texinfo-*-
-@c @c %**start of header
-@c @setfilename annotate.info
-@c @settitle GDB Annotations
-@c @setchapternewpage off
-@c @c %**end of header
-
-@c @set EDITION 0.5
-@c @set DATE May 1994
-
-@c @ifinfo
-@c This file documents GDB annotations.
-
-@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
-@c Annotations}. Copyright 1994,1995,2000,2001 Free Software Foundation, Inc.
-
-@c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.1 or
-@c any later version published by the Free Software Foundation; with no
-@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-@c and with the Back-Cover Texts as in (a) below.
-
-@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-@c this GNU Manual, like GNU software. Copies published by the Free
-@c Software Foundation raise funds for GNU development.''
-@c @end ifinfo
-
-@c @titlepage
-@c @title GDB Annotations
-@c @subtitle Edition @value{EDITION}
-@c @subtitle @value{DATE}
-@c @author Cygnus Support
-@c @page
-@c @vskip 0pt plus 1filll
-@c Permission is granted to make and distribute verbatim copies of
-@c this manual provided the copyright notice and this permission notice
-@c are preserved on all copies.
-
-@c Copyright @copyright{} 1994,1995,2000,2001 Free Software Foundation
-@c @end titlepage
-
-@c @ifinfo
-@c @node Top
-@c @top GDB Annotations
-
-@c @syncodeindex fn cp
-
-@node Annotations
-@chapter @value{GDBN} Annotations
-
-This chapter describes annotations in @value{GDBN}. Annotations are
-designed to interface @value{GDBN} to graphical user interfaces or
-other similar programs which want to interact with @value{GDBN} at a
-relatively high level.
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename annotate.info
+@c
+@include gdb-cfg.texi
+@c
+@settitle @value{GDBN}'s Obsolete Annotations
+@setchapternewpage off
+@c %**end of header
+
+@set EDITION 0.5
+@set DATE May 1994
+
+@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 the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
+@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
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
+Foundation
+@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.
@@ -70,14 +71,16 @@
* Annotations for Running::
Whether the program is running, how it stopped, etc.
* Source Annotations:: Annotations describing source code.
-* TODO:: Annotations which might be added in the future.
@end menu
+@contents
+
@node Annotations Overview
-@section What is an Annotation?
+@chapter What is an Annotation?
@cindex annotations
-To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
+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
@@ -122,8 +125,79 @@
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. Unfortunatly, 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 occures 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
-@section The Server Prefix
+@chapter The Server Prefix
@cindex server prefix for annotations
To issue a command to @value{GDBN} without affecting certain aspects of
@@ -137,7 +211,10 @@
use the @code{output} command instead of the @code{print} command.
@node Value Annotations
-@section Values
+@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
@@ -268,7 +345,14 @@
@end smallexample
@node Frame Annotations
-@section Frames
+@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
@@ -403,7 +487,10 @@
@end itemize
@node Displays
-@section Displays
+@chapter Displays
+
+@emph{Display Annotations have been removed. @sc{gdb/mi} instead
+provides Variable Objects.}
@findex display-begin
@findex display-number-end
@@ -442,7 +529,7 @@
and @var{value} is the actual value being displayed.
@node Prompting
-@section Annotation for @value{GDBN} Input
+@chapter Annotation for @value{GDBN} Input
@cindex annotations for prompts
When @value{GDBN} prompts for input, it annotates this fact so it is possible
@@ -502,7 +589,7 @@
@end table
@node Errors
-@section Errors
+@chapter Errors
@cindex annotations for errors, warnings and interrupts
@findex quit
@@ -542,7 +629,10 @@
@c range_error(), and possibly other places.
@node Breakpoint Info
-@section Information on Breakpoints
+@chapter Information on Breakpoints
+
+@emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead
+provides breakpoint commands.}
@cindex annotations for breakpoints
The output from the @code{info breakpoints} command is annotated as follows:
@@ -600,7 +690,7 @@
@end smallexample
@node Invalidation
-@section Invalidation Notices
+@chapter Invalidation Notices
@cindex annotations for invalidation messages
The following annotations say that certain pieces of state may have
@@ -621,7 +711,7 @@
@end table
@node Annotations for Running
-@section Running the Program
+@chapter Running the Program
@cindex annotations for running programs
@findex starting
@@ -692,7 +782,7 @@
@end table
@node Source Annotations
-@section Displaying Source
+@chapter Displaying Source
@cindex annotations for source display
@findex source
@@ -714,23 +804,6 @@
followed by one or more lowercase hex digits (note that this does not
depend on the language).
-@node TODO
-@section Annotations We Might Want in the Future
-
-@format
- - target-invalid
- the target might have changed (registers, heap contents, or
- execution status). For performance, we might eventually want
- to hit `registers-invalid' and `all-registers-invalid' with
- greater precision
-
- - systematic annotation for set/show parameters (including
- invalidation notices).
-
- - similarly, `info' returns a list of candidates for invalidation
- notices.
-@end format
-
@ignore
@node Index
@unnumbered Index
@@ -738,4 +811,4 @@
@printindex fn
@end ignore
-@c @bye
+@bye