Re: RFA: Document conventions for terminating query/set packet names

["Jim Blandy" <jimb@red-bean.com>]

On 5/4/06, Daniel Jacobowitz <drow@false.org> wrote:
> On Wed, May 03, 2006 at 11:13:47PM -0700, Jim Blandy wrote:
> > It's my impression that renaming qPart will also affect existing stubs
> > --- isn't that so?  From looking around, it seemed to me that there
> > weren't too many implementations of qP, so I'm presuming that, if
> > something is to be broken, that'd be the one to break.  But if you
> > know that RedBoot is more widely installed in inaccessible places,
> > then that's something I didn't realize.
>
> Well, I don't know it, but I strongly suspect it.  I know we've gotten
> boards from vendors with RedBoot flashed into them; and the life of
> flashed boot monitors can be depressingly long.
>
> Here's the deal with qPart as I see it: there is currently exactly one
> OBJECT value defined, "auxv".  This only applies to hosted programs
> running within an OS with an ELF interpreter, and in practice I think
> it only applies to GNU/Linux and Solaris.  These are cases where the
> stub is fairly easy to upgrade.
>
> Now, once I get the qPart:features support merged, it'll be a different
> story; that's primarily targeted at embedded stubs.  But it hasn't
> happened yet and I only know of a handful of users, none of whom are
> committed to the interface.

All right.  I think one of my subconscious motivations was that I
didn't like breaking a new feature for an older, deprecated feature. 
But this isn't about "fairness" to features; it's about gettings
things working without breaking too much stuff.  So I'll go along with
retiring the qL and qP prefixes.

Here's a revised patch:

2006-05-04  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 -c -r1.325 gdb.texinfo
cvs diff: conflicting specifications of output style
*** gdb/doc/gdb.texinfo	27 Apr 2006 23:03:42 -0000	1.325
--- gdb/doc/gdb.texinfo	4 May 2006 17:21:40 -0000
*************** the Acme Corporation might begin with @s
*** 23106,23114 ****
  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.

  Like the descriptions of the other packets, each description here
  has a template showing the packet's overall syntax, followed by an
--- 23106,23118 ----
  foos) or @samp{Qacme.bar} (for setting bars).
  @end itemize

! 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.  The
! @code{qP} and @code{qL} packets predate these conventions; since we
! suspect they are in widespread use in places that are difficult to
! upgrade, new packets should not begin with @code{qP} or @code{qL}.

  Like the descriptions of the other packets, each description here
  has a template showing the packet's overall syntax, followed by an
*************** Reply:
*** 23252,23257 ****
--- 23256,23264 ----
  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}
*************** starting at @var{offset} bytes into the
*** 23263,23268 ****
--- 23270,23278 ----
  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.
*************** Indicate a badly formed request.
*** 23354,23359 ****
--- 23364,23374 ----
  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
*************** comprising the printable string containi
*** 23414,23419 ****
--- 23429,23439 ----
  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