From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8345 invoked by alias); 17 May 2003 00:19:04 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 7766 invoked from network); 17 May 2003 00:18:50 -0000 Received: from unknown (HELO localhost.redhat.com) (24.157.166.107) by sources.redhat.com with SMTP; 17 May 2003 00:18:50 -0000 Received: from redhat.com (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id 19AFF2B2F for ; Fri, 16 May 2003 20:18:44 -0400 (EDT) Message-ID: <3EC57FE4.1000704@redhat.com> Date: Sat, 17 May 2003 00:19:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-US; rv:1.0.2) Gecko/20030223 X-Accept-Language: en-us, en MIME-Version: 1.0 To: gdb-patches@sources.redhat.com Subject: [rfa:doco] Doco problems with level two annotations Content-Type: multipart/mixed; boundary="------------070807080706090809040300" X-SW-Source: 2003-05/txt/msg00298.txt.bz2 This is a multi-part message in MIME format. --------------070807080706090809040300 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Content-length: 310 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 --------------070807080706090809040300 Content-Type: text/plain; name="diffs" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="diffs" Content-length: 11764 2003-05-16 Andrew Cagney * 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 --------------070807080706090809040300--