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.

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 7607ada..6887b65 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2006-05-05  Jim Blandy  <jimb@codesourcery.com>
+
+       * gdb.texinfo (General Query Packets): Document conventions for
+       terminating packet names, and their violations.
+
 2006-05-05  Daniel Jacobowitz  <dan@codesourcery.com>
 
        * Makefile.in (GDB_DOC_SOURCE_INCLUDES): Update for readline 5.1.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 737b86d..e2b986a 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23098,9 +23098,14 @@ the Acme Corporation might begin with @samp{qacme.foo} (for querying
 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
@@ -23244,6 +23249,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}
@@ -23255,6 +23263,9 @@ starting at @var{offset} bytes into the data.  The content and
 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.
@@ -23346,6 +23357,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
@@ -23406,6 +23422,11 @@ comprising the printable string containing the extra information about
 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