From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13583 invoked by alias); 5 Nov 2004 22:12:26 -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 13565 invoked from network); 5 Nov 2004 22:12:23 -0000 Received: from unknown (HELO lakermmtao07.cox.net) (68.230.240.32) by sourceware.org with SMTP; 5 Nov 2004 22:12:23 -0000 Received: from white ([68.9.64.121]) by lakermmtao07.cox.net (InterMail vM.6.01.03.04 201-2131-111-106-20040729) with ESMTP id <20041105221223.ZSWC20686.lakermmtao07.cox.net@white>; Fri, 5 Nov 2004 17:12:23 -0500 Received: from bob by white with local (Exim 3.35 #1 (Debian)) id 1CQCJi-0002Kj-00; Fri, 05 Nov 2004 17:12:22 -0500 Date: Fri, 05 Nov 2004 22:12:00 -0000 From: Bob Rossi To: Eli Zaretskii Cc: gdb-patches@sources.redhat.com Subject: Re: MI handshaking Message-ID: <20041105221222.GC8318@white> Mail-Followup-To: Eli Zaretskii , gdb-patches@sources.redhat.com References: <20041104195701.GA7296@white> <01c4c2b4$Blat.v2.2.2$a21985e0@zahav.net.il> <20041105163933.GB8318@white> <01c4c35f$Blat.v2.2.2$3c749800@zahav.net.il> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <01c4c35f$Blat.v2.2.2$3c749800@zahav.net.il> User-Agent: Mutt/1.3.28i X-SW-Source: 2004-11/txt/msg00098.txt.bz2 On Fri, Nov 05, 2004 at 07:44:18PM +0200, Eli Zaretskii wrote: > > Date: Fri, 5 Nov 2004 11:39:33 -0500 > > From: Bob Rossi > > Cc: gdb-patches@sources.redhat.com > > > > +@node GDB/MI Handshaking Syntax > > +@subsection @sc{gdb/mi} Handshaking Syntax > > + > > +@cindex handshaking syntax for @sc{gdb/mi} > > +@cindex @sc{gdb/mi}, handshaking syntax > > +@table @code > > +@item @var{handshake_output} @expansion{} > > +@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} > > +"@}" @var{nl}} > > I think there's a need here for a cross-reference to the section that > explains the reason and principles of the handshaking (the other > section you wrote), otherwise this table looks awkwardly unexplained. I think i did this correctly. > > +It is possible to start the @sc{gdb/mi} interpreter using -i=mi1, -i=mi2, or > > +simply with -i=mi. > > The command-line options should be in @samp{} or in @option{}, like > this: > > It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi1} done > > Actually, instead of using literal mi1 and mi2, which could confuse > the reader into thinking that only MI1 and MI2 are supported (think > about someone reading this 10 years from now), I'd say > > It is possible to start the @sc{gdb/mi} interpreter using > @samp{-i=mi@var{n}}, where @var{n} is the MI protocol version > (@pxref{Interpreters}). When invoked with a specific version of the > MI interpreter, @value{GDBN} will bypass the handshaking mode and go > directly into... done > > > +then this tells @value{GDBN} to go into it's handshaking mode with the > ^^^^ > This should be "its", without the apostrophe. > done > > +it supports. The term "stable MI protocol" simply means that the protocol > > Please use ``this style'' to quote phrases in Texinfo (the result is > prettier in the printed version). Actually, in this case, since you > are introducing a new term, I'd suggest to say > > The term @dfn{stable MI protocol} simply means... > > Also, a @cindex entry here about stable MI protocol would be useful. > I think I did the cindex part right, but I don't really understand how there used, or why. > > +untested protocols, they could simply try to invoke @value{GDBN} with -i=miN, > > +where N is version they wish to communicate with. > > Please use @var{n} instead of a literal "N" here. > > > +If a specific version of @value{GDBN} speaks only one stable MI protocol than > > The last woprd should be "then", not "than". > done > > +versions of the MI protocol, than it will output a list of these protocols > ^^^^ > Again, "then". > done > Other than these few minor problems, the documentation patch is > approved. Thanks. I hope this resolves all of the issues you brought up. I really am not good at editing info files but am trying to do my best to help out. Bob Rossi Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.222 diff -w -u -r1.222 gdb.texinfo --- gdb.texinfo 23 Oct 2004 15:05:29 -0000 1.222 +++ gdb.texinfo 5 Nov 2004 22:09:54 -0000 @@ -14997,6 +14997,7 @@ @menu * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: +* GDB/MI Handshaking Interface:: * GDB/MI Output Records:: * GDB/MI Command Description Format:: * GDB/MI Breakpoint Table Commands:: @@ -15021,11 +15022,53 @@ @section @sc{gdb/mi} Command Syntax @menu +* GDB/MI Handshaking Syntax:: * GDB/MI Input Syntax:: * GDB/MI Output Syntax:: * GDB/MI Simple Examples:: @end menu +@node GDB/MI Handshaking Syntax +@subsection @sc{gdb/mi} Handshaking Syntax + +@cindex handshaking syntax for @sc{gdb/mi} +@cindex @sc{gdb/mi}, handshaking syntax +@table @code +@item @var{handshake_output} @expansion{} +@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} +"@}" @var{nl}} + +@item @var{mi-protocol-list} @expansion{} +@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} } + +@item @var{mi-protocol} @expansion{} +@code{ "mi" @var{token} } + +@item @var{token} @expansion{} +"any sequence of digits" + +@item @var{nl} @expansion{} +@code{CR | CR-LF} +@end table + +@noindent +Notes: + +@itemize @bullet +@item +If only one stable @sc{mi} protocol is supported by a particular release of +@value{GDBN}, then that release is used and the caller does not have to +do anything. + +@item +If there is more than one stable @sc{mi} protocol supported by a particular +release of @value{GDBN}, then the caller has to specify which version of the +@sc{mi} protocol it wants @value{GDBN} to communicate with. + +@item +For more information on handshaking see @ref{GDB/MI Handshaking Interface} +@end itemize + @node GDB/MI Input Syntax @subsection @sc{gdb/mi} Input Syntax @@ -15111,6 +15154,9 @@ @var{token}. @table @code +@item @var{output-list} @expansion{} +@code{@var{output} | @var{output-list} @var{output}} + @item @var{output} @expansion{} @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}} @@ -15314,6 +15360,51 @@ an un-supported hybrid of @sc{gdb/mi} and CLI output. @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Handshaking Interface +@section @sc{gdb/mi} Handshaking Interface + +@cindex @sc{gdb/mi}, handshaking interface +@value{GDBN} is capable of speaking several MI protocols at a time. This +interface is intended to help developers understand what version of the MI +protocol that a particular @value{GDBN} is going to communicate with. + +It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi@var{n}}, +where @var{n} is the MI protocol version (@pxref{Interpreters}). When invoked +with a specific version of the MI interpreter, @value{GDBN} will bypass the +handshaking mode and go directly into the version of the MI that it requested. +However, if @value{GDBN} is started with the -i=mi flag, then this tells +@value{GDBN} to go into its handshaking mode with the client to determine the +correct MI protocol to communicate with. + +@value{GDBN} will output all of the stable versions of the MI protocol that +it supports. The term @dfn{stable MI protocol} simply means that the protocol +was tested when this particular release was made. Protocols that are no longer +tested in the @value{GDBN} testsuite will not be considered a stable release. +If the caller still wishes to communicate with @value{GDBN} using one of these +untested protocols, they could simply try to invoke @value{GDBN} with +-i=mi@var{N}, where @var{N} is version they wish to communicate with. + +@value{GDBN} will output all of the stable MI versions that it supports. +If a specific version of @value{GDBN} speaks only one stable MI protocol then +it will begin communicating with that version of the protocol. The front end +has no way to change this version. However, if @value{GDBN} speaks several +versions of the MI protocol, then it will output a list of these protocols +and the front end then has to choose the version that it wants @value{GDBN} +to communicate with. + +@cindex @dfn{stable MI protocol} +You could have a @value{GDBN} version that is capable of communicating with +several versions of the @sc{mi} protocol. In general, an official release or +a CVS snapshot will have depricated @sc{mi} protocols, stable @sc{mi} +protocols and development @sc{mi} protocols. The depricated @sc{mi} protocols +are kept around in @value{GDBN} for some period of time and then will +eventually get removed. The @dfn{stable MI protocols} are considered stable +because they were tested when the particular @value{GDBN} program you have was +created. The development @sc{mi} protocols are not ready to be used since +there is a good change there will be incompatible changes made to it before it +can become a stable protocol. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Output Records @section @sc{gdb/mi} Output Records