RFA/RFC: vCont for the remote protocol [doco]

RFA/RFC: vCont for the remote protocol [doco]

[Daniel Jacobowitz]

Documentation, as promised.  Reserves the `v' letter for multi-letter
packets.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

2003-09-29  Daniel Jacobowitz  <drow@mvista.com>

	* gdb.texinfo (Remote Protocol): Document v and vCont.

Index: doc/gdb.texinfo
===================================================================
RCS file: /big/fsf/rsync/src-cvs/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.175
diff -u -p -r1.175 gdb.texinfo
--- doc/gdb.texinfo	9 Aug 2003 15:10:09 -0000	1.175
+++ doc/gdb.texinfo	29 Sep 2003 14:32:55 -0000
@@ -19781,9 +19781,33 @@ Reserved for future use.
 
 Reserved for future use.
 
-@item @code{v} --- reserved
+@item @code{v} --- verbose packet prefix
 
-Reserved for future use.
+Packets starting with @code{v} are identified by a multi-letter name,
+up to the first @code{:} if any.
+
+@item @code{vCont:}[@var{action}@code{:}@var{tid}@code{;}]...[@var{action}] --- extended resume
+@cindex @code{vCont} packet
+
+Resume the inferior.  Different actions may be specified for each thread.
+If a final action is specified, then it is applied to all threads not
+explicitly mentioned; if no final action is specified, all other threads
+should remain stopped.  Possible actions are @code{s}, @code{S}@var{sig},
+@code{c}, and @code{C}@var{sig}, with the same meanings as those packets.
+The final @var{addr} associated with those packets is not supported in
+@code{vCont}.  Thread IDs are specified in hexadecimal.
+
+First reply:
+@table @samp
+@item OK
+for success
+@item E@var{NN}
+for an error
+@end table
+
+If the first reply is @samp{OK}, then the inferior will be resumed, and
+another reply sent when it stops.  @xref{Stop Reply Packets}, for the reply
+specifications.
 
 @item @code{V} --- reserved
 

Re: RFA/RFC: vCont for the remote protocol [doco]

[Andrew Cagney]

> -@item @code{v} --- reserved
> +@item @code{v} --- verbose packet prefix
>  
> -Reserved for future use.
> +Packets starting with @code{v} are identified by a multi-letter name,
> +up to the first @code{:} if any.

... first non-alpabetic character, if any.  Unless you want to pin down 
the terminator?

I think ";" will work better as, in the below, it better separates out 
the separate actions.

> +@item @code{vCont:}[@var{action}@code{:}@var{tid}@code{;}]...[@var{action}] --- extended resume
> +@cindex @code{vCont} packet
> +
> +Resume the inferior.  Different actions may be specified for each thread.
> +If a final action is specified, then it is applied to all threads not
> +explicitly mentioned; if no final action is specified, all other threads
> +should remain stopped.  Possible actions are @code{s}, @code{S}@var{sig},
> +@code{c}, and @code{C}@var{sig}, with the same meanings as those packets.
> +The final @var{addr} associated with those packets is not supported in
> +@code{vCont}.  Thread IDs are specified in hexadecimal.
> +
> +First reply:
> +@table @samp
> +@item OK

No.

The behavior shall be identical to the other continuation packets.  If 
it isn't recognized, "" is returned.

You may find it useful to clarify the spec so that a separate probe is 
possible vis

	-> vCont
	<- Enn or OK or Tnn?

||	-> vCont
	<-

speaking of which.  What happens if vCont specifies nothing?  Return a 
dummy Tnn packet?  Return OK?

> +for success
> +@item E@var{NN}
> +for an error
> +@end table
> +
> +If the first reply is @samp{OK}, then the inferior will be resumed, and
> +another reply sent when it stops.  @xref{Stop Reply Packets}, for the reply
> +specifications.

Andrew

Re: RFA/RFC: vCont for the remote protocol [doco]

[Daniel Jacobowitz]

On Mon, Sep 29, 2003 at 05:17:44PM -0400, Andrew Cagney wrote:
> >-@item @code{v} --- reserved
> >+@item @code{v} --- verbose packet prefix
> > 
> >-Reserved for future use.
> >+Packets starting with @code{v} are identified by a multi-letter name,
> >+up to the first @code{:} if any.
> 
> ... first non-alpabetic character, if any.  Unless you want to pin down 
> the terminator?
> 
> I think ";" will work better as, in the below, it better separates out 
> the separate actions.

I meant to pin down the terminator.  If you want a ';' then that's OK
by me, I can update the patch to use a semicolon.  Makes sense, but the
colon felt more natural.

> >+@item 
> >@code{vCont:}[@var{action}@code{:}@var{tid}@code{;}]...[@var{action}] --- 
> >extended resume
> >+@cindex @code{vCont} packet
> >+
> >+Resume the inferior.  Different actions may be specified for each thread.
> >+If a final action is specified, then it is applied to all threads not
> >+explicitly mentioned; if no final action is specified, all other threads
> >+should remain stopped.  Possible actions are @code{s}, @code{S}@var{sig},
> >+@code{c}, and @code{C}@var{sig}, with the same meanings as those packets.
> >+The final @var{addr} associated with those packets is not supported in
> >+@code{vCont}.  Thread IDs are specified in hexadecimal.
> >+
> >+First reply:
> >+@table @samp
> >+@item OK
> 
> No.
> 
> The behavior shall be identical to the other continuation packets.  If 
> it isn't recognized, "" is returned.

I did this in parallel to 'E'.  Yes, I realize that 'E' has problems,
but I really think this isn't one of them; it keeps the client code a
whole lot simpler, since we don't have to detect and handle a failed
vcont in the main loop.  We can fall back immediately to sending a 'c'
packet or whatever.  It also lets us retry using 'C' for free.

Also, the ability to differentiate between "stub does not support
vcont" and "this vcont was illegal" seems useful to me - for debugging
purposes if nothing else.  Or if some stub supports step-out-of-range
in a vcont packet (I think that would be a bad idea; call it vCont2
instead and avoid the issue).

Why do you prefer not doing this?

> You may find it useful to clarify the spec so that a separate probe is 
> possible vis
> 
> 	-> vCont
> 	<- Enn or OK or Tnn?
> 
> ||	-> vCont
> 	<-
> 
> speaking of which.  What happens if vCont specifies nothing?  Return a 
> dummy Tnn packet?  Return OK?

Implementation currently returns ""; it only recognizes vCont with the
colon.

> 
> >+for success
> >+@item E@var{NN}
> >+for an error
> >+@end table
> >+
> >+If the first reply is @samp{OK}, then the inferior will be resumed, and
> >+another reply sent when it stops.  @xref{Stop Reply Packets}, for the 
> >reply
> >+specifications.
> 
> Andrew
> 
> 
> 

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: RFA/RFC: vCont for the remote protocol [doco]

[Andrew Cagney]

> On Mon, Sep 29, 2003 at 05:17:44PM -0400, Andrew Cagney wrote:
> 
>> >-@item @code{v} --- reserved
>> >+@item @code{v} --- verbose packet prefix
>> > 
>> >-Reserved for future use.
>> >+Packets starting with @code{v} are identified by a multi-letter name,
>> >+up to the first @code{:} if any.
> 
>> 
>> ... first non-alpabetic character, if any.  Unless you want to pin down 
>> the terminator?
>> 
>> I think ";" will work better as, in the below, it better separates out 
>> the separate actions.
> 
> 
> I meant to pin down the terminator.  If you want a ';' then that's OK
> by me, I can update the patch to use a semicolon.  Makes sense, but the
> colon felt more natural.

I agree that ":" _feels_ more natural, it just goes against the rest of 
the packet where ";", and not ":" is the separator.  It lets the packet 
be specified as:

packet ->> "vCont" { field }+
field ->> ";" action [ ":" tid ]

which is very easy to parse.  BTW, intro has this to say, so there 
aren't any guidelines :-(

> Fields within the packet should be separated using @samp{,} @samp{;} or
> @cindex remote protocol, field separator
> @samp{:}.  Except where otherwise noted all numbers are represented in
> @sc{hex} with leading zeros suppressed.
> 
> Implementors should note that prior to @value{GDBN} 5.0, the character
> @samp{:} could not appear as the third character in a packet (as it
> would potentially conflict with the @var{sequence-id}).



>> >+@item 
>> >@code{vCont:}[@var{action}@code{:}@var{tid}@code{;}]...[@var{action}] --- 
>> >extended resume
>> >+@cindex @code{vCont} packet
>> >+
>> >+Resume the inferior.  Different actions may be specified for each thread.
>> >+If a final action is specified, then it is applied to all threads not
>> >+explicitly mentioned; if no final action is specified, all other threads
>> >+should remain stopped.  Possible actions are @code{s}, @code{S}@var{sig},
>> >+@code{c}, and @code{C}@var{sig}, with the same meanings as those packets.
>> >+The final @var{addr} associated with those packets is not supported in
>> >+@code{vCont}.  Thread IDs are specified in hexadecimal.

Suggest a table.

>> >+First reply:
>> >+@table @samp
>> >+@item OK
> 
>> 
>> No.
>> 
>> The behavior shall be identical to the other continuation packets.  If 
>> it isn't recognized, "" is returned.
> 
> 
> I did this in parallel to 'E'.  Yes, I realize that 'E' has problems,
> but I really think this isn't one of them; it keeps the client code a
> whole lot simpler, since we don't have to detect and handle a failed
> vcont in the main loop.  We can fall back immediately to sending a 'c'
> packet or whatever.  It also lets us retry using 'C' for free.

> Also, the ability to differentiate between "stub does not support
> vcont" and "this vcont was illegal" seems useful to me - for debugging
> purposes if nothing else.  Or if some stub supports step-out-of-range
> in a vcont packet (I think that would be a bad idea; call it vCont2
> instead and avoid the issue).
> 
> Why do you prefer not doing this?

It runs completly against the remote protocol's RPC model: one request, 
one response.

The transaction contains extra states, while those states add to the 
transactions complexity, they do it without adding any real value:

It adds unnecessary latency (due to additional round trips) to the 
transaction.  Remember this really involves:
	-> vCont;....
	<- +
	<- OK
	-> +
	<- T00....
	-> +
when just:
	-> vCont;...
	<- +
	<- T00
	-> +
is all that is needed.

When async, having fewer states makes the state machine logic easier.

>> You may find it useful to clarify the spec so that a separate probe is 
>> possible vis
>> 
>> 	-> vCont
>> 	<- Enn or OK or Tnn?
>> 
>> ||	-> vCont
>> 	<-
>> 
>> speaking of which.  What happens if vCont specifies nothing?  Return a 
>> dummy Tnn packet?  Return OK?
> 
> 
> Implementation currently returns ""; it only recognizes vCont with the
> colon.

What does:

	vCont;

return then then?  I think "T00" would make sense - target stopped, 
nothing interesting happened.  The other would be "E..".

Here's something out of left field:

	-> vCont?
	<- { "s" | "c" | "P" | "E" | ... }  OR  ""

that is,  it returns a list of supported letters.

Andrew

Re: RFA/RFC: vCont for the remote protocol [doco]

[Daniel Jacobowitz]

On Tue, Sep 30, 2003 at 10:37:53AM -0400, Andrew Cagney wrote:
> >On Mon, Sep 29, 2003 at 05:17:44PM -0400, Andrew Cagney wrote:
> >
> >>>-@item @code{v} --- reserved
> >>>+@item @code{v} --- verbose packet prefix
> >>> 
> >>>-Reserved for future use.
> >>>+Packets starting with @code{v} are identified by a multi-letter name,
> >>>+up to the first @code{:} if any.
> >
> >>
> >>... first non-alpabetic character, if any.  Unless you want to pin down 
> >>the terminator?
> >>
> >>I think ";" will work better as, in the below, it better separates out 
> >>the separate actions.
> >
> >
> >I meant to pin down the terminator.  If you want a ';' then that's OK
> >by me, I can update the patch to use a semicolon.  Makes sense, but the
> >colon felt more natural.
> 
> I agree that ":" _feels_ more natural, it just goes against the rest of 
> the packet where ";", and not ":" is the separator.  It lets the packet 
> be specified as:
> 
> packet ->> "vCont" { field }+
> field ->> ";" action [ ":" tid ]
> 
> which is very easy to parse.  BTW, intro has this to say, so there 
> aren't any guidelines :-(

That loses the requirement that the default action be last, which I'd
like to hold on to - OK?

I dislike the ';' because vCont is not an item in the list of actions
that the semicolons are separating; that turns ';' from a separator
into a prefix.  But hey, prefixes are people too.

> >Fields within the packet should be separated using @samp{,} @samp{;} or
> >@cindex remote protocol, field separator
> >@samp{:}.  Except where otherwise noted all numbers are represented in
> >@sc{hex} with leading zeros suppressed.
> >
> >Implementors should note that prior to @value{GDBN} 5.0, the character
> >@samp{:} could not appear as the third character in a packet (as it
> >would potentially conflict with the @var{sequence-id}).
> 
> 
> 
> >>>+@item 
> >>>@code{vCont:}[@var{action}@code{:}@var{tid}@code{;}]...[@var{action}] 
> >>--- >extended resume
> >>>+@cindex @code{vCont} packet
> >>>+
> >>>+Resume the inferior.  Different actions may be specified for each 
> >>thread.
> >>>+If a final action is specified, then it is applied to all threads not
> >>>+explicitly mentioned; if no final action is specified, all other threads
> >>>+should remain stopped.  Possible actions are @code{s}, 
> >>@code{S}@var{sig},
> >>>+@code{c}, and @code{C}@var{sig}, with the same meanings as those 
> >>packets.
> >>>+The final @var{addr} associated with those packets is not supported in
> >>>+@code{vCont}.  Thread IDs are specified in hexadecimal.
> 
> Suggest a table.

OK.

> >>>+First reply:
> >>>+@table @samp
> >>>+@item OK
> >
> >>
> >>No.
> >>
> >>The behavior shall be identical to the other continuation packets.  If 
> >>it isn't recognized, "" is returned.
> >
> >
> >I did this in parallel to 'E'.  Yes, I realize that 'E' has problems,
> >but I really think this isn't one of them; it keeps the client code a
> >whole lot simpler, since we don't have to detect and handle a failed
> >vcont in the main loop.  We can fall back immediately to sending a 'c'
> >packet or whatever.  It also lets us retry using 'C' for free.
> 
> >Also, the ability to differentiate between "stub does not support
> >vcont" and "this vcont was illegal" seems useful to me - for debugging
> >purposes if nothing else.  Or if some stub supports step-out-of-range
> >in a vcont packet (I think that would be a bad idea; call it vCont2
> >instead and avoid the issue).
> >
> >Why do you prefer not doing this?
> 
> It runs completly against the remote protocol's RPC model: one request, 
> one response.
> 
> The transaction contains extra states, while those states add to the 
> transactions complexity, they do it without adding any real value:
> 
> It adds unnecessary latency (due to additional round trips) to the 
> transaction.  Remember this really involves:
> 	-> vCont;....
> 	<- +
> 	<- OK
> 	-> +
> 	<- T00....
> 	-> +
> when just:
> 	-> vCont;...
> 	<- +
> 	<- T00
> 	-> +
> is all that is needed.
> 
> When async, having fewer states makes the state machine logic easier.

All right.  I now remember having this conversation before; witness the
other half of the original thread, with new-thread notifications.  I
don't really see the problem but I'm fine simplifying it.

> >>You may find it useful to clarify the spec so that a separate probe is 
> >>possible vis
> >>
> >>	-> vCont
> >>	<- Enn or OK or Tnn?
> >>
> >>||	-> vCont
> >>	<-
> >>
> >>speaking of which.  What happens if vCont specifies nothing?  Return a 
> >>dummy Tnn packet?  Return OK?
> >
> >
> >Implementation currently returns ""; it only recognizes vCont with the
> >colon.
> 
> What does:
> 
> 	vCont;
> 
> return then then?  I think "T00" would make sense - target stopped, 
> nothing interesting happened.  The other would be "E..".

I'd prefer E..; vCont; resumes nothing, and generates no new stops.

> Here's something out of left field:
> 
> 	-> vCont?
> 	<- { "s" | "c" | "P" | "E" | ... }  OR  ""
> 
> that is,  it returns a list of supported letters.

Ooh, I like it, I like it.  Allow both ? and ; as terminators, require
any stub which implements vCont; to also implement vCont?, and there
goes the probing problem.  Then the rest of it falls out.

Let me polish that up and test it and I'll send out an update.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: RFA/RFC: vCont for the remote protocol [doco]

[Andrew Cagney]

> packet ->> "vCont" { field }+
>> field ->> ";" action [ ":" tid ]
>> 
>> which is very easy to parse.  BTW, intro has this to say, so there 
>> aren't any guidelines :-(
> 
> 
> That loses the requirement that the default action be last, which I'd
> like to hold on to - OK?

Was that to ensure that there wasn't more than one default action?  I 
think its better to instead clarify that in the text part of the spec vis:

"By default all unspecified threads remain stopped.  An action with no 
corresponding {tdid} shall be applied to all threads with out an 
explicitly specified action.  A packet specifying multiple default 
actions is erreneous."

Looking at the new gdbserver code it's pratically doing this now.  BTW, 
I think it gets confused by the incorrect "...;cccccccccc", simplifying 
to be strictly LL1 will fix that.

> I dislike the ';' because vCont is not an item in the list of actions
> that the semicolons are separating; that turns ';' from a separator
> into a prefix.  But hey, prefixes are people too.

Seperator or terminator?

Andrew

[v2] Re: RFA/RFC: vCont for the remote protocol [doco]

[Daniel Jacobowitz]

On Tue, Sep 30, 2003 at 11:37:00AM -0400, Andrew Cagney wrote:
> >packet ->> "vCont" { field }+
> >>field ->> ";" action [ ":" tid ]
> >>
> >>which is very easy to parse.  BTW, intro has this to say, so there 
> >>aren't any guidelines :-(
> >
> >
> >That loses the requirement that the default action be last, which I'd
> >like to hold on to - OK?
> 
> Was that to ensure that there wasn't more than one default action?  I 
> think its better to instead clarify that in the text part of the spec vis:
> 
> "By default all unspecified threads remain stopped.  An action with no 
> corresponding {tdid} shall be applied to all threads with out an 
> explicitly specified action.  A packet specifying multiple default 
> actions is erreneous."
> 
> Looking at the new gdbserver code it's pratically doing this now.  BTW, 
> I think it gets confused by the incorrect "...;cccccccccc", simplifying 
> to be strictly LL1 will fix that.

This makes the stub parsing a little trickier, but not much.  I don't
think it does get confused by ";cccccccc"; if whatever you saw is still
there in the revised version I'm about to post, please holler.

> >I dislike the ';' because vCont is not an item in the list of actions
> >that the semicolons are separating; that turns ';' from a separator
> >into a prefix.  But hey, prefixes are people too.
> 
> Seperator or terminator?

If it were a terminator we wouldn't need one at the beginning of the
list.

Here's updated docs.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

2003-09-30  Daniel Jacobowitz  <drow@mvista.com>

	* gdb.texinfo (Remote Protocol): Document v and vCont.

Index: doc/gdb.texinfo
===================================================================
RCS file: /big/fsf/rsync/src-cvs/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.175
diff -u -p -r1.175 gdb.texinfo
--- doc/gdb.texinfo	9 Aug 2003 15:10:09 -0000	1.175
+++ doc/gdb.texinfo	30 Sep 2003 19:42:01 -0000
@@ -19781,9 +19781,51 @@ Reserved for future use.
 
 Reserved for future use.
 
-@item @code{v} --- reserved
+@item @code{v} --- verbose packet prefix
 
-Reserved for future use.
+Packets starting with @code{v} are identified by a multi-letter name,
+up to the first @code{;} or @code{?} (or the end of the packet).
+
+@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
+@cindex @code{vCont} packet
+
+Resume the inferior.  Different actions may be specified for each thread.
+If an action is specified with no @var{tid}, then it is applied to any
+threads that don't have a specific action specified; if no default action is
+specified than other threads should remain stopped.  Multiple default
+actions are an error.  Thread IDs are specified in hexadecimal.
+Currently supported actions are:
+
+@table @code
+@item c
+Continue
+@item C@var{sig}
+Continue with signal @var{sig}
+@item s
+Step
+@item S@var{sig}
+Step with signal @var{sig}
+@end table
+
+The optional @var{addr} argument normally associated with these packets is
+not supported in @code{vCont}.
+
+Reply:
+@xref{Stop Reply Packets}, for the reply specifications.
+
+@item @code{vCont?} --- extended resume query
+@cindex @code{vCont?} packet
+
+Query support for the @code{vCont} packet.
+
+Reply:
+@table @samp
+@item @code{vCont}[;@var{action}]...
+The @code{vCont} packet is supported.  Each @var{action} is a supported
+command in the @code{vCont} packet.
+@item empty
+The @code{vCont} packet is not supported.
+@end table
 
 @item @code{V} --- reserved
 

Re: [v2] Re: RFA/RFC: vCont for the remote protocol [doco]

[Andrew Cagney]

Looks good.  Can you send it as a formal proposal (as a protocol change) 
to gdb@, then give it a week?

Andrew

> -@item @code{v} --- reserved
> +@item @code{v} --- verbose packet prefix
>  
> -Reserved for future use.
> +Packets starting with @code{v} are identified by a multi-letter name,
> +up to the first @code{;} or @code{?} (or the end of the packet).

> +@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
> +@cindex @code{vCont} packet
> +
> +Resume the inferior.  Different actions may be specified for each thread.
> +If an action is specified with no @var{tid}, then it is applied to any
> +threads that don't have a specific action specified; if no default action is
> +specified than other threads should remain stopped.  Multiple default
> +actions are an error.  Thread IDs are specified in hexadecimal.
> +Currently supported actions are:

Should it specify that no action is also an error?

> +@table @code
> +@item c
> +Continue
> +@item C@var{sig}
> +Continue with signal @var{sig}
> +@item s
> +Step
> +@item S@var{sig}
> +Step with signal @var{sig}
> +@end table
> +
> +The optional @var{addr} argument normally associated with these packets is
> +not supported in @code{vCont}.
> +
> +Reply:
> +@xref{Stop Reply Packets}, for the reply specifications.
> +
> +@item @code{vCont?} --- extended resume query
> +@cindex @code{vCont?} packet
> +
> +Query support for the @code{vCont} packet.
> +
> +Reply:
> +@table @samp
> +@item @code{vCont}[;@var{action}]...
> +The @code{vCont} packet is supported.  Each @var{action} is a supported
> +command in the @code{vCont} packet.

Hmm, yes good catch remembering to include ";".

> +@item empty

The convention:

	@item

is currently used for an empty packet.

> +The @code{vCont} packet is not supported.
> +@end table

Re: [v2] Re: RFA/RFC: vCont for the remote protocol [doco]

[Andrew Cagney]

> Looks good.  Can you send it as a formal proposal (as a protocol change) to gdb@, then give it a week?

(Sigh of relief, didn't raise an eyebrow! :-)
I'm ok with this doco, but check with Eli for the texinfo side of things 
(my be easier to just post the final texinfo).

Andrew