This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]