[rfa/doc] Add section on interrupts to remote protocol documentation

[rfa/doc] Add section on interrupts to remote protocol documentation

[Kevin Buettner]

The patch below adds a new section about interrupts to the remote protocol
documentation.  A discussion on gdb@ may be found starting here:

    http://sources.redhat.com/ml/gdb/2005-11/msg00347.html

Okay?

	* gdb.texinfo (set remotebreak): Add anchor.
	(Remote Protocol): Add new section `Interrupts'.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.293
diff -u -p -r1.293 gdb.texinfo
--- gdb.texinfo	17 Nov 2005 19:08:38 -0000	1.293
+++ gdb.texinfo	18 Nov 2005 02:44:52 -0000
@@ -12147,6 +12147,7 @@ Show the current speed of the remote con
 @item set remotebreak
 @cindex interrupt remote programs
 @cindex BREAK signal instead of Ctrl-C
+@anchor{set remotebreak}
 If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
 when you press the @key{Ctrl-C} key to interrupt the program running
 on the remote.  If set to off, @value{GDBN} sends the @samp{Ctrl-C}
@@ -22016,6 +22017,7 @@ Show the current setting of the target w
 * Stop Reply Packets::
 * General Query Packets::
 * Register Packet Format::
+* Interrupts::
 * Examples::
 * File-I/O remote protocol extension::
 @end menu
@@ -23063,6 +23065,27 @@ as @code{MIPS32}.
 
 @end table
 
+@node Interrupts
+@section Interrupts
+
+When a program on the remote target is running, @value{GDBN} may
+attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
+control of which is specified via @value{GDBN}'s @samp{remotebreak}
+setting.  @xref{set remotebreak}.  The precise meaning of @code{BREAK}
+is defined by the transport mechanism and may, in fact, be undefined. 
+@samp{Ctrl-C}, on the other hand, is defined and implemented for all
+transport mechanisms and is represented by sending the single byte
+@code{0x03}.  @samp{Ctrl-C} must not be sent as part of a packet as
+defined in the Overview section.  @xref{Overview}.
+
+Stubs are not required to recognize these interrupt mechanisms and the
+precise meaning associated with receipt of the interrupt is
+implementation defined.  If the stub is successful at interrupting the
+running program, it is expected that it will send one of the Stop
+Reply Packets (@xref{Stop Reply Packets}) to @value{GDBN} as a result
+of successfully stopping the program.  Interrupts received while the
+program is stopped will be discarded.
+
 @node Examples
 @section Examples
 

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Jim Blandy]

Interesting.  The documentation on the 'X' binary download packet
doesn't mention C-c as one of the characters that gets quoted.  And,
in fact, remote.c:remote_write_bytes doesn't quote it.  Who's right
here?

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Steven Johnson]

I thought that ^C only was relevant after the `C', `c', `S', `s' packets 
and before a Stop Reply Packet.

None of the stubs ive implemented treat "^C" exceptionally, except when 
they are running code.

Otherwise, ^C is ignored as a special character.  What does "interrupt" 
mean when you are not doing anything that can be interrupted?

If you are executing code, then you are in the "Dead space" between the 
packet from GDB to the target to get the target to execute code, and the 
reply from that packet.  I would have thought during this time, and this 
time only ^C has any relevance?  If so then, it doesnt need to be 
quoted, As you cant send a packet during this time.

I think it would be better to say that during this time, and this time 
only is when ^C is relevant, and if received at any other time it is 
processed like that character would be in the message stream.

Steven


Jim Blandy wrote:

>Interesting.  The documentation on the 'X' binary download packet
>doesn't mention C-c as one of the characters that gets quoted.  And,
>in fact, remote.c:remote_write_bytes doesn't quote it.  Who's right
>here?
>
>
>  
>

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Jim Blandy]

On 11/17/05, Steven Johnson <sjohnson@sakuraindustries.com> wrote:
> I thought that ^C only was relevant after the `C', `c', `S', `s' packets
> and before a Stop Reply Packet.

That was my understanding too, but the documentation Kevin posted says:

@samp{Ctrl-C} must not be sent as part of a packet as
+defined in the Overview section.  @xref{Overview}.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Kevin Buettner]

On Thu, 17 Nov 2005 21:59:33 -0800
Jim Blandy <jimb@red-bean.com> wrote:

> On 11/17/05, Steven Johnson <sjohnson@sakuraindustries.com> wrote:
> > I thought that ^C only was relevant after the `C', `c', `S', `s' packets
> > and before a Stop Reply Packet.
> 
> That was my understanding too, but the documentation Kevin posted says:
> 
> @samp{Ctrl-C} must not be sent as part of a packet as
> +defined in the Overview section.  @xref{Overview}.

My intent was to say that Ctrl-C, the interrupt message, is sent by
itself and does not include any other packet markup.  I'll try to
clarify this in the doc before committing anything.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Jim Blandy]

On 11/18/05, Kevin Buettner <kevinb@redhat.com> wrote:
> > @samp{Ctrl-C} must not be sent as part of a packet as
> > +defined in the Overview section.  @xref{Overview}.
>
> My intent was to say that Ctrl-C, the interrupt message, is sent by
> itself and does not include any other packet markup.  I'll try to
> clarify this in the doc before committing anything.

Oh, I see it now.  Yeah, that passage can be read two very different ways.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Eli Zaretskii]

> Date: Fri, 18 Nov 2005 16:04:58 +1100
> From: Steven Johnson <sjohnson@sakuraindustries.com>
> 
> Otherwise, ^C is ignored as a special character.  What does "interrupt" 
> mean when you are not doing anything that can be interrupted?
> 
> If you are executing code, then you are in the "Dead space" between the 
> packet from GDB to the target to get the target to execute code, and the 
> reply from that packet.  I would have thought during this time, and this 
> time only ^C has any relevance?  If so then, it doesnt need to be 
> quoted, As you cant send a packet during this time.
> 
> I think it would be better to say that during this time, and this time 
> only is when ^C is relevant, and if received at any other time it is 
> processed like that character would be in the message stream.

Isn't this what Kevin's text says?  Here's the relevant fragment:

   Interrupts received while the program is stopped will be discarded.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Steven Johnson]

Eli Zaretskii wrote:

>>Date: Fri, 18 Nov 2005 16:04:58 +1100
>>From: Steven Johnson <sjohnson@sakuraindustries.com>
>>
>>Otherwise, ^C is ignored as a special character.  What does "interrupt" 
>>mean when you are not doing anything that can be interrupted?
>>    
>>
>Isn't this what Kevin's text says?  Here's the relevant fragment:
>
>   Interrupts received while the program is stopped will be discarded.
>
>
>  
>
I think we are talking at cross purposes.  I dont think anyone disputes 
Interrupting when the target is stopped means nothing (to either GDB or 
the target), and it makes sense to discard them if they are not within a 
packet, because ^C is not a valid start of packet character. 

What both Jim Blandy and I seem to be talking about is the apparent 
"new" requirement to escape ^C when its in a packet.  I fail to see why 
it requires to be escaped.  It is only valid at a very specific point in 
time, so why does it need to be escaped? 

It hasnt been escaped in the past, and im not aware of any problems that 
not escaping it introduces.

As Jim points out, the X packet never used to document ^C as requiring 
escaping, and he says it isnt escaped in the GDB code.  So if it is now 
going to be escaped, that will break stubs, that rely on the old 
behavior.  The old manual said that the only character escaped in the 
'X' packet was $, # and 0x7d.  But now we have added ^C to that list, 
and have broken backward compatibility by doing so.

If thats what you want to do, thats fine, but it is no longer compatible 
with any stub that supported the old behavior of the X packet.

At least thats how ive interpreted "{Ctrl-C} must not be sent as part of 
a packet as defined in the Overview section.".

Steven

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Eli Zaretskii]

> Date: Thu, 17 Nov 2005 19:52:24 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> The patch below adds a new section about interrupts to the remote protocol
> documentation.  A discussion on gdb@ may be found starting here:
> 
>     http://sources.redhat.com/ml/gdb/2005-11/msg00347.html
> 
> Okay?

Thanks.  This is approved, but please fix the following minor gotchas
before committing:

> +When a program on the remote target is running, @value{GDBN} may
> +attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
> +control of which is specified via @value{GDBN}'s @samp{remotebreak}
> +setting.  @xref{set remotebreak}.

It is better to use @pxref here, like this:

  control of which is specified via @value{GDBN}'s @samp{remotebreak}
  setting (@pxref{set remotebreak}).

> +@code{0x03}.  @samp{Ctrl-C} must not be sent as part of a packet as
> +defined in the Overview section.  @xref{Overview}.

Same here: use @pxref.

> +running program, it is expected that it will send one of the Stop
> +Reply Packets (@xref{Stop Reply Packets}) to @value{GDBN} as a result

@pxref is precisely the markup for the situations when you want a
cross-reference in parentheses.  @pxref does 2 things that are
appropriate in parens: (1) it produces a phrase that begins with a
lower-case letter, since this is not a beginning of a sentence; and
(2) it doesn't require a period or a command after the closing brace,
like @xref does.  So please replace the above @xref with @pxref.

Also, I'd like us to have an index entry pointing to this section.
Could you please add one?

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Kevin Buettner]

My earlier patch has changed just enough that I'd like feedback prior
to committing it.  I believe I have incorporated all of the changes
requested by Eli.  I've also tried to address the issue raised by Jim;
I believe the new text is less ambiguous regarding the use of Ctrl-C
within packets.

Comments? Okay?

	* gdb.texinfo (set remotebreak): Add anchor.
	(X packet): Likewise.
	(Remote Protocol): Add new section `Interrupts' and new index
	entry `interrupts (remote protocol)'.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.293
diff -u -p -r1.293 gdb.texinfo
--- gdb.texinfo	17 Nov 2005 19:08:38 -0000	1.293
+++ gdb.texinfo	18 Nov 2005 21:20:50 -0000
@@ -12147,6 +12147,7 @@ Show the current speed of the remote con
 @item set remotebreak
 @cindex interrupt remote programs
 @cindex BREAK signal instead of Ctrl-C
+@anchor{set remotebreak}
 If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
 when you press the @key{Ctrl-C} key to interrupt the program running
 on the remote.  If set to off, @value{GDBN} sends the @samp{Ctrl-C}
@@ -22016,6 +22017,7 @@ Show the current setting of the target w
 * Stop Reply Packets::
 * General Query Packets::
 * Register Packet Format::
+* Interrupts::
 * Examples::
 * File-I/O remote protocol extension::
 @end menu
@@ -22514,6 +22516,7 @@ The @samp{vCont} packet is not supported
 @end table
 
 @item X @var{addr},@var{length}:@var{XX@dots{}}
+@anchor{X packet}
 @cindex @samp{X} packet
 Write data to memory, where the data is transmitted in binary.
 @var{addr} is address, @var{length} is number of bytes,
@@ -23063,6 +23066,37 @@ as @code{MIPS32}.
 
 @end table
 
+@node Interrupts
+@section Interrupts
+@cindex interrupts (remote protocol)
+
+When a program on the remote target is running, @value{GDBN} may
+attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
+control of which is specified via @value{GDBN}'s @samp{remotebreak}
+setting (@pxref{set remotebreak}).
+
+The precise meaning of @code{BREAK} is defined by the transport
+mechanism and may, in fact, be undefined.  @value{GDBN} does
+not currently define a @code{BREAK} mechanism for any of the network
+interfaces.
+
+@samp{Ctrl-C}, on the other hand, is defined and implemented for all
+transport mechanisms.  It is represented by sending the single byte
+@code{0x03} without any of the usual packet overhead described in in
+the Overview section (@pxref{Overview}).  When a @code{0x03} byte is
+transmitted as part of a packet, it is considered to be packet data
+and does @emph{not} represent an interrupt.  E.g., an @samp{X} packet
+(@pxref{X packet}, used for binary downloads, may include an unescaped
+@code{0x03} as part of its packet.
+
+Stubs are not required to recognize these interrupt mechanisms and the
+precise meaning associated with receipt of the interrupt is
+implementation defined.  If the stub is successful at interrupting the
+running program, it is expected that it will send one of the Stop
+Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
+of successfully stopping the program.  Interrupts received while the
+program is stopped will be discarded.
+
 @node Examples
 @section Examples
 

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Daniel Jacobowitz]

On Fri, Nov 18, 2005 at 02:33:09PM -0700, Kevin Buettner wrote:
> My earlier patch has changed just enough that I'd like feedback prior
> to committing it.  I believe I have incorporated all of the changes
> requested by Eli.  I've also tried to address the issue raised by Jim;
> I believe the new text is less ambiguous regarding the use of Ctrl-C
> within packets.
> 
> Comments? Okay?

Looks right to me.  Thanks!

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Jim Blandy]

On 11/18/05, Kevin Buettner <kevinb@redhat.com> wrote:
> +@samp{Ctrl-C}, on the other hand, is defined and implemented for all
> +transport mechanisms.  It is represented by sending the single byte
> +@code{0x03} without any of the usual packet overhead described in in
> +the Overview section (@pxref{Overview}).  When a @code{0x03} byte is
> +transmitted as part of a packet, it is considered to be packet data
> +and does @emph{not} represent an interrupt.  E.g., an @samp{X} packet
> +(@pxref{X packet}, used for binary downloads, may include an unescaped
> +@code{0x03} as part of its packet.

Yep, that's pretty explicit.  Fine with me.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Steven Johnson]

Jim Blandy wrote:

>On 11/18/05, Kevin Buettner <kevinb@redhat.com> wrote:
>  
>
>>+@samp{Ctrl-C}, on the other hand, is defined and implemented for all
>>+transport mechanisms.  It is represented by sending the single byte
>>+@code{0x03} without any of the usual packet overhead described in in
>>+the Overview section (@pxref{Overview}).  When a @code{0x03} byte is
>>+transmitted as part of a packet, it is considered to be packet data
>>+and does @emph{not} represent an interrupt.  E.g., an @samp{X} packet
>>+(@pxref{X packet}, used for binary downloads, may include an unescaped
>>+@code{0x03} as part of its packet.
>>    
>>
>
>Yep, that's pretty explicit.  Fine with me.
>
>
>  
>
Ditto.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Kevin Buettner]

On Fri, 18 Nov 2005 14:33:09 -0700
Kevin Buettner <kevinb@redhat.com> wrote:

> +@code{0x03} without any of the usual packet overhead described in in

I just noticed the double "in".  Fixed in my local copy...

Kevin

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Michael Snyder]

Kevin Buettner wrote:
> My earlier patch has changed just enough that I'd like feedback prior
> to committing it.  I believe I have incorporated all of the changes
> requested by Eli.  I've also tried to address the issue raised by Jim;
> I believe the new text is less ambiguous regarding the use of Ctrl-C
> within packets.
> 
> Comments? Okay?

Sounds good to me.


> 	* gdb.texinfo (set remotebreak): Add anchor.
> 	(X packet): Likewise.
> 	(Remote Protocol): Add new section `Interrupts' and new index
> 	entry `interrupts (remote protocol)'.
> 
> Index: gdb.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> retrieving revision 1.293
> diff -u -p -r1.293 gdb.texinfo
> --- gdb.texinfo	17 Nov 2005 19:08:38 -0000	1.293
> +++ gdb.texinfo	18 Nov 2005 21:20:50 -0000
> @@ -12147,6 +12147,7 @@ Show the current speed of the remote con
>  @item set remotebreak
>  @cindex interrupt remote programs
>  @cindex BREAK signal instead of Ctrl-C
> +@anchor{set remotebreak}
>  If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
>  when you press the @key{Ctrl-C} key to interrupt the program running
>  on the remote.  If set to off, @value{GDBN} sends the @samp{Ctrl-C}
> @@ -22016,6 +22017,7 @@ Show the current setting of the target w
>  * Stop Reply Packets::
>  * General Query Packets::
>  * Register Packet Format::
> +* Interrupts::
>  * Examples::
>  * File-I/O remote protocol extension::
>  @end menu
> @@ -22514,6 +22516,7 @@ The @samp{vCont} packet is not supported
>  @end table
>  
>  @item X @var{addr},@var{length}:@var{XX@dots{}}
> +@anchor{X packet}
>  @cindex @samp{X} packet
>  Write data to memory, where the data is transmitted in binary.
>  @var{addr} is address, @var{length} is number of bytes,
> @@ -23063,6 +23066,37 @@ as @code{MIPS32}.
>  
>  @end table
>  
> +@node Interrupts
> +@section Interrupts
> +@cindex interrupts (remote protocol)
> +
> +When a program on the remote target is running, @value{GDBN} may
> +attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
> +control of which is specified via @value{GDBN}'s @samp{remotebreak}
> +setting (@pxref{set remotebreak}).
> +
> +The precise meaning of @code{BREAK} is defined by the transport
> +mechanism and may, in fact, be undefined.  @value{GDBN} does
> +not currently define a @code{BREAK} mechanism for any of the network
> +interfaces.
> +
> +@samp{Ctrl-C}, on the other hand, is defined and implemented for all
> +transport mechanisms.  It is represented by sending the single byte
> +@code{0x03} without any of the usual packet overhead described in in
> +the Overview section (@pxref{Overview}).  When a @code{0x03} byte is
> +transmitted as part of a packet, it is considered to be packet data
> +and does @emph{not} represent an interrupt.  E.g., an @samp{X} packet
> +(@pxref{X packet}, used for binary downloads, may include an unescaped
> +@code{0x03} as part of its packet.
> +
> +Stubs are not required to recognize these interrupt mechanisms and the
> +precise meaning associated with receipt of the interrupt is
> +implementation defined.  If the stub is successful at interrupting the
> +running program, it is expected that it will send one of the Stop
> +Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
> +of successfully stopping the program.  Interrupts received while the
> +program is stopped will be discarded.
> +
>  @node Examples
>  @section Examples
>  
> 
> 

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Eli Zaretskii]

> Date: Fri, 18 Nov 2005 14:33:09 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> My earlier patch has changed just enough that I'd like feedback prior
> to committing it.  I believe I have incorporated all of the changes
> requested by Eli.  I've also tried to address the issue raised by Jim;
> I believe the new text is less ambiguous regarding the use of Ctrl-C
> within packets.
> 
> Comments? Okay?

Yes, thanks.

Re: [rfa/doc] Add section on interrupts to remote protocol documentation

[Kevin Buettner]

On Fri, 18 Nov 2005 14:33:09 -0700
Kevin Buettner <kevinb@redhat.com> wrote:

> 	* gdb.texinfo (set remotebreak): Add anchor.
> 	(X packet): Likewise.
> 	(Remote Protocol): Add new section `Interrupts' and new index
> 	entry `interrupts (remote protocol)'.

Committed.

Thanks to everyone who provided feedback on this patch.

Kevin