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