RFA: Document conventions for terminating query/set packet names

RFA: Document conventions for terminating query/set packet names

[Jim Blandy]

2006-05-03  Jim Blandy  <jimb@codesourcery.com>

	* gdb.texinfo (General Query Packets): Document conventions for
	terminating packet names, and their violations.

*** gdb.texinfo	23 Apr 2006 00:42:10 -0700	1.324
--- gdb.texinfo	03 May 2006 12:00:15 -0700	
***************
*** 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,23115 ----
  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.
  
  Like the descriptions of the other packets, each description here
  has a template showing the packet's overall syntax, followed by an
***************
*** 23252,23257 ****
--- 23253,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.
  
+ Since this packet's name (@code{qP}) is not separated from its first
+ argument (@var{mode}) by any kind of punctuation, it is ambiguous with
+ the @code{qPart} packet.  Stubs should recognize this packet by the
+ twenty-four hex digits that follow.  New stubs should implement the
+ @code{qThreadExtraInfo} packet instead.
+ 
  Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
  
  @item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length}
***************
*** 23354,23359 ****
--- 23361,23371 ----
  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,23419 ****
--- 23426,23436 ----
  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     

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

[Daniel Jacobowitz]

On Wed, May 03, 2006 at 12:50:59PM -0700, Jim Blandy wrote:
> 
> 2006-05-03  Jim Blandy  <jimb@codesourcery.com>
> 
> 	* gdb.texinfo (General Query Packets): Document conventions for
> 	terminating packet names, and their violations.

Sorry, forgot to mention something when we talked about this earlier. 
I'm generally in favor of the newly documented conventions, except for
this:

> + Since this packet's name (@code{qP}) is not separated from its first
> + argument (@var{mode}) by any kind of punctuation, it is ambiguous with
> + the @code{qPart} packet.  Stubs should recognize this packet by the
> + twenty-four hex digits that follow.  New stubs should implement the
> + @code{qThreadExtraInfo} packet instead.
> + 

Background for the list: we discovered by accident yesterday that
RedBoot interprets any other query packet starting with qP as a
malformed thread info request.  Not surprising, since the format of qP
doesn't have any separators in it.  So what's a "malformed qP packet"
versus "some other packet that happens to start with qP"?

I think the best solution would be to document that new packets should
not start with "qP" or "qL", and rename the relatively new qPart packet
to something else, like qXfer.  I don't really care whether GDB
continues to try the old qPart name; I think it may be recent enough
that we can drop it, but maybe not.  I believe the only thing it's used
for on HEAD is the ELF Auxv vector; I have other uses on various
branches, but none of them have been merged yet.

Interested in any comments...


-- 
Daniel Jacobowitz
CodeSourcery

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

[Jim Blandy]

Daniel Jacobowitz <drow@false.org> writes:
> On Wed, May 03, 2006 at 12:50:59PM -0700, Jim Blandy wrote:
>> 
>> 2006-05-03  Jim Blandy  <jimb@codesourcery.com>
>> 
>> 	* gdb.texinfo (General Query Packets): Document conventions for
>> 	terminating packet names, and their violations.
>
> Sorry, forgot to mention something when we talked about this earlier. 
> I'm generally in favor of the newly documented conventions, except for
> this:
>
>> + Since this packet's name (@code{qP}) is not separated from its first
>> + argument (@var{mode}) by any kind of punctuation, it is ambiguous with
>> + the @code{qPart} packet.  Stubs should recognize this packet by the
>> + twenty-four hex digits that follow.  New stubs should implement the
>> + @code{qThreadExtraInfo} packet instead.
>> + 
>
> Background for the list: we discovered by accident yesterday that
> RedBoot interprets any other query packet starting with qP as a
> malformed thread info request.  Not surprising, since the format of qP
> doesn't have any separators in it.  So what's a "malformed qP packet"
> versus "some other packet that happens to start with qP"?
>
> I think the best solution would be to document that new packets should
> not start with "qP" or "qL", and rename the relatively new qPart packet
> to something else, like qXfer.  I don't really care whether GDB
> continues to try the old qPart name; I think it may be recent enough
> that we can drop it, but maybe not.  I believe the only thing it's used
> for on HEAD is the ELF Auxv vector; I have other uses on various
> branches, but none of them have been merged yet.
>
> Interested in any comments...

The protocol as currently documented is ambiguous.  Whatever we do in
the long run, I think the manual ought to make some recommendation now
to guide new implementations.  The 'count the hex digits' is one
approach; another would be to deprecate qP altogether, in favor of
qThreadExtraInfo.  That's what GDB prefers at the moment; it's been
around since 2000.  qP dates to GDB's prehistory, but I'm pretty sure
it's from around 1998; I was at Cygnus when it was discussed.

I looked around a bit; neither gdbserver nor RDA nor the stub we've
been working with recently within CodeSourcery implement qP.  RedBoot
does.  We might break less by explicitly deprecating qP, since we
already have a preferred alternative.

Gratuitous chart:

                              qP     qPart    qThreadExtraInfo
gdbserver                            x
RDA                                           x
internal CodeSourcery stub                    x
RedBoot                       x

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

[Daniel Jacobowitz]

On Wed, May 03, 2006 at 03:54:17PM -0700, Jim Blandy wrote:
> > I think the best solution would be to document that new packets should
> > not start with "qP" or "qL", and rename the relatively new qPart packet
> > to something else, like qXfer.  I don't really care whether GDB
> > continues to try the old qPart name; I think it may be recent enough
> > that we can drop it, but maybe not.  I believe the only thing it's used
> > for on HEAD is the ELF Auxv vector; I have other uses on various
> > branches, but none of them have been merged yet.
> >
> > Interested in any comments...
> 
> The protocol as currently documented is ambiguous.  Whatever we do in
> the long run, I think the manual ought to make some recommendation now
> to guide new implementations.  The 'count the hex digits' is one
> approach; another would be to deprecate qP altogether, in favor of
> qThreadExtraInfo.  That's what GDB prefers at the moment; it's been
> around since 2000.  qP dates to GDB's prehistory, but I'm pretty sure
> it's from around 1998; I was at Cygnus when it was discussed.

Could you explain why you prefer either of these changes - both of
which affect existing stubs - to my suggestion of renaming qPart and
the proposed qPacketInfo?

I might be missing something - but it seems virtually certain that
there are deployed stubs using qP that are going to live for a long
time - especially since RedBoot uses it and that tends to get flashed
into things!

-- 
Daniel Jacobowitz
CodeSourcery

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

[Jim Blandy]

On 5/3/06, Daniel Jacobowitz <drow@false.org> wrote:
> On Wed, May 03, 2006 at 03:54:17PM -0700, Jim Blandy wrote:
> > > I think the best solution would be to document that new packets should
> > > not start with "qP" or "qL", and rename the relatively new qPart packet
> > > to something else, like qXfer.  I don't really care whether GDB
> > > continues to try the old qPart name; I think it may be recent enough
> > > that we can drop it, but maybe not.  I believe the only thing it's used
> > > for on HEAD is the ELF Auxv vector; I have other uses on various
> > > branches, but none of them have been merged yet.
> > >
> > > Interested in any comments...
> >
> > The protocol as currently documented is ambiguous.  Whatever we do in
> > the long run, I think the manual ought to make some recommendation now
> > to guide new implementations.  The 'count the hex digits' is one
> > approach; another would be to deprecate qP altogether, in favor of
> > qThreadExtraInfo.  That's what GDB prefers at the moment; it's been
> > around since 2000.  qP dates to GDB's prehistory, but I'm pretty sure
> > it's from around 1998; I was at Cygnus when it was discussed.
>
> Could you explain why you prefer either of these changes - both of
> which affect existing stubs - to my suggestion of renaming qPart and
> the proposed qPacketInfo?
>
> I might be missing something - but it seems virtually certain that
> there are deployed stubs using qP that are going to live for a long
> time - especially since RedBoot uses it and that tends to get flashed
> into things!

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.

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

[Daniel Jacobowitz]

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.

-- 
Daniel Jacobowitz
CodeSourcery

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

[Eli Zaretskii]

> From: Jim Blandy <jimb@codesourcery.com>
> Date: Wed, 03 May 2006 12:50:59 -0700
> 
> 
> 2006-05-03  Jim Blandy  <jimb@codesourcery.com>
> 
> 	* gdb.texinfo (General Query Packets): Document conventions for
> 	terminating packet names, and their violations.

Fine with me, documentation-wise.  (I don't have anything useful to
add to the more general discussion of which packets to
prefer/deprecate.)

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

[Jim Blandy]

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

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

[Eli Zaretskii]

> Date: Thu, 4 May 2006 10:24:22 -0700
> From: "Jim Blandy" <jimb@red-bean.com>
> 
> 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.

Fine with me, but...

> ! 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}.

...perhaps the last sentence will be better placed in a footnote.
WDYT?

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

[Daniel Jacobowitz]

On Thu, May 04, 2006 at 10:24:22AM -0700, Jim Blandy wrote:
> 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.

Thanks.  Aside from Eli's question I'm fine with this.

I'm wondering if we should mark the qC prefix "bad" too.  I realize
there's already qCRC: and I'm not suggesting we rename that.  But of
the two other stubs I checked today, both supported qC and neither
checked that the C was at the end of the packet.

Amusingly enough, one of them also supported qCRC:, and had a hack to
check for that first.

-- 
Daniel Jacobowitz
CodeSourcery

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

[Jim Blandy]

Eli Zaretskii <eliz@gnu.org> writes:
>> Date: Thu, 4 May 2006 10:24:22 -0700
>> From: "Jim Blandy" <jimb@red-bean.com>
>> 
>> 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.
>
> Fine with me, but...
>
>> ! 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}.
>
> ...perhaps the last sentence will be better placed in a footnote.
> WDYT?

Well, it does supply a rule that people adding new packets should
follow.  It's not something that one need read only if interested.

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

[Jim Blandy]

Eli Zaretskii <eliz@gnu.org> writes:
>> Date: Thu, 4 May 2006 10:24:22 -0700
>> From: "Jim Blandy" <jimb@red-bean.com>
>> 
>> 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.
>
> Fine with me, but...
>
>> ! 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}.
>
> ...perhaps the last sentence will be better placed in a footnote.
> WDYT?

We could replace the last sentence with: 

New packets should not have names beginning with 
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}.

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

[Jim Blandy]

Eli Zaretskii <eliz@gnu.org> writes:
>> Date: Thu, 4 May 2006 10:24:22 -0700
>> From: "Jim Blandy" <jimb@red-bean.com>
>> 
>> 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.
>
> Fine with me, but...
>
>> ! 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}.
>
> ...perhaps the last sentence will be better placed in a footnote.
> WDYT?

(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'...)

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.

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

[Eli Zaretskii]

> 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.

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

[Jim Blandy]

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     

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

[Eli Zaretskii]

> Cc: gdb-patches@sourceware.org
> From: Jim Blandy <jimb@codesourcery.com>
> Date: Fri, 05 May 2006 14:59:07 -0700
> 
> 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.

Great, thanks.

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

[Daniel Jacobowitz]

On Fri, May 05, 2006 at 12:25:44PM -0400, Daniel Jacobowitz wrote:
> On Thu, May 04, 2006 at 10:24:22AM -0700, Jim Blandy wrote:
> > 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.
> 
> Thanks.  Aside from Eli's question I'm fine with this.
> 
> I'm wondering if we should mark the qC prefix "bad" too.  I realize
> there's already qCRC: and I'm not suggesting we rename that.  But of
> the two other stubs I checked today, both supported qC and neither
> checked that the C was at the end of the packet.
> 
> Amusingly enough, one of them also supported qCRC:, and had a hack to
> check for that first.

Jim, did you have any opinion on this?  Otherwise, here's a proposed
patch.  It recommends not starting new packets with qC, and clarifies
that stubs should check for the end of a packet even for packets
without a separator.

-- 
Daniel Jacobowitz
CodeSourcery

2006-05-09  Daniel Jacobowitz  <dan@codesourcery.com>

	* gdb.texinfo (General Query Packets): Recommend not starting
	new packets with qC and clarify.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.328
diff -u -p -r1.328 gdb.texinfo
--- gdb.texinfo	5 May 2006 22:48:14 -0000	1.328
+++ gdb.texinfo	9 May 2006 20:40:01 -0000
@@ -23101,11 +23101,14 @@ foos) or @samp{Qacme.bar} (for setting b
 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.}.
+full packet name, and check for a separator or the end of the packet,
+in case two packet names share a common prefix.  New packets should not begin
+with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
+packets predate these conventions, and have arguments without any terminator
+for the packet name; we suspect they are in widespread use in places that
+are difficult to upgrade.  The @samp{qC} packet has no arguments, but some
+existing stubs (e.g.@: RedBoot) are known to not check for the end of the
+packet.}.
 
 Like the descriptions of the other packets, each description here
 has a template showing the packet's overall syntax, followed by an

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

[Andrew Cagney]

Daniel Jacobowitz wrote:
> Otherwise, here's a proposed
> patch.  It recommends not starting new packets with qC, and clarifies
> that stubs should check for the end of a packet even for packets
> without a separator.

That was always the intent.  Your wording is much improved.
>  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, and check for a separator or the end of the packet,
> +in case two packet names share a common prefix.  New packets should not begin
> +with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
> +packets predate these conventions, and have arguments without any terminator
> +for the packet name; we suspect they are in widespread use in places that
> +are difficult to upgrade.  The @samp{qC} packet has no arguments, but some
> +existing stubs (e.g.@: RedBoot) are known to not check for the end of the
> +packet.}.

The qC vs qCRC botch also pre-dates this convention; and was one of its 
motivators.

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

[Eli Zaretskii]

> Date: Tue, 9 May 2006 16:41:51 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> Jim, did you have any opinion on this?  Otherwise, here's a proposed
> patch.  It recommends not starting new packets with qC, and clarifies
> that stubs should check for the end of a packet even for packets
> without a separator.

Fine with me, but see Andrew's comments.

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

[Jim Blandy]

Daniel Jacobowitz <drow@false.org> writes:
> On Fri, May 05, 2006 at 12:25:44PM -0400, Daniel Jacobowitz wrote:
>> On Thu, May 04, 2006 at 10:24:22AM -0700, Jim Blandy wrote:
>> > 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.
>> 
>> Thanks.  Aside from Eli's question I'm fine with this.
>> 
>> I'm wondering if we should mark the qC prefix "bad" too.  I realize
>> there's already qCRC: and I'm not suggesting we rename that.  But of
>> the two other stubs I checked today, both supported qC and neither
>> checked that the C was at the end of the packet.
>> 
>> Amusingly enough, one of them also supported qCRC:, and had a hack to
>> check for that first.
>
> Jim, did you have any opinion on this?  Otherwise, here's a proposed
> patch.  It recommends not starting new packets with qC, and clarifies
> that stubs should check for the end of a packet even for packets
> without a separator.

No --- it looks good.

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

[Daniel Jacobowitz]

On Wed, May 10, 2006 at 06:18:51AM +0300, Eli Zaretskii wrote:
> > Date: Tue, 9 May 2006 16:41:51 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > 
> > Jim, did you have any opinion on this?  Otherwise, here's a proposed
> > patch.  It recommends not starting new packets with qC, and clarifies
> > that stubs should check for the end of a packet even for packets
> > without a separator.
> 
> Fine with me, but see Andrew's comments.

He was in favor; so, thanks to everyone who responded, and I've
committed it.

-- 
Daniel Jacobowitz
CodeSourcery