This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: RFA: Document conventions for terminating query/set packet names
Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: gdb-patches@sourceware.org
>> From: Jim Blandy <jimb@codesourcery.com>
>> Date: Fri, 05 May 2006 12:18:23 -0700
>>
>> (Argh. In Emacs, the command to insert '@code{}' in a texinfo-mode
>> buffer is C-c C-c c. But in a mail-mode buffer, C-c C-c is 'send
>> message'...)
>
> Yeah, was bitten by that one, too.
>
>> We could replace that last sentence with:
>>
>> New packets should not begin with @samp{qP} or @samp{qL}.@footnote{The
>> @samp{qP} and @samp{qL} packets predate these conventions, and don't
>> have any terminator for the packet name; we suspect they are in
>> widespread use in places that are difficult to upgrade.}
>>
>> if you prefer.
>
> Yes, that's what I had in mind, sorry it wasn't immediately clear.
>
> But please start the footnote _before_ the period, and add the period
> after the right brace that ends the footnote.
All right. Here's what I've committed.
gdb/doc/ChangeLog:
2006-05-05 Jim Blandy <jimb@codesourcery.com>
* gdb.texinfo (General Query Packets): Document conventions for
terminating packet names, and their violations.
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.325
diff -u -p -r1.325 gdb.texinfo
--- gdb/doc/gdb.texinfo 27 Apr 2006 23:03:42 -0000 1.325
+++ gdb/doc/gdb.texinfo 5 May 2006 21:57:13 -0000
@@ -23106,9 +23106,14 @@ the Acme Corporation might begin with @s
foos) or @samp{Qacme.bar} (for setting bars).
@end itemize
-A query or set packet may optionally be followed by a @samp{,} or
-@samp{;} separated list. Stubs must be careful to match the full
-packet name, in case packet names have common prefixes.
+The name of a query or set packet should be separated from any
+parameters by a @samp{:}; the parameters themselves should be
+separated by @samp{,} or @samp{;}. Stubs must be careful to match the
+full packet name, in case packet names have common prefixes. New
+packets should not begin with @samp{qP} or @samp{qL}@footnote{The
+@samp{qP} and @samp{qL} packets predate these conventions, and don't
+have any terminator for the packet name; we suspect they are in
+widespread use in places that are difficult to upgrade.}.
Like the descriptions of the other packets, each description here
has a template showing the packet's overall syntax, followed by an
@@ -23252,6 +23257,9 @@ Reply:
Returns information on @var{threadid}. Where: @var{mode} is a hex
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
+Don't use this packet; use the @samp{qThreadExtraInfo} query instead
+(see below).
+
Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
@item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
@@ -23263,6 +23271,9 @@ starting at @var{offset} bytes into the
encoding of @var{annex} is specific to the object; it can supply
additional details about what data to access.
+Since this packet is ambiguous with the older @code{qP} packet, we
+plan to rename it.
+
Here are the specific requests of this form defined so far. All
@samp{qPart:@var{object}:read:@dots{}} requests use the same reply
formats, listed below.
@@ -23354,6 +23365,11 @@ Indicate a badly formed request.
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
+(Note that the @code{qRcmd} packet's name is separated from the
+command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
@item qSymbol::
@cindex symbol lookup, remote request
@cindex @samp{qSymbol} packet
@@ -23414,6 +23430,11 @@ comprising the printable string containi
the thread's attributes.
@end table
+(Note that the @code{qThreadExtraInfo} packet's name is separated from
+the command by a @samp{,}, not a @samp{:}, contrary to the naming
+conventions above. Please don't use this packet as a model for new
+packets.)
+
@item QTStart
@itemx QTStop
@itemx QTinit