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

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

[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
 

Reply | Threaded
Open this post in threaded view
|

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

jimb (Bugzilla)
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?
Reply | Threaded
Open this post in threaded view
|

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

Steven Johnson-2
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?
>
>
>  
>

Reply | Threaded
Open this post in threaded view
|

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

jimb (Bugzilla)
On 11/17/05, Steven Johnson <[hidden email]> 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}.
Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Steven Johnson-2
> Date: Fri, 18 Nov 2005 16:04:58 +1100
> From: Steven Johnson <[hidden email]>
>
> 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.
Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Kevin Buettner
> Date: Thu, 17 Nov 2005 19:52:24 -0700
> From: Kevin Buettner <[hidden email]>
>
> 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?
Reply | Threaded
Open this post in threaded view
|

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

Steven Johnson-2
In reply to this post by Eli Zaretskii
Eli Zaretskii wrote:

>>Date: Fri, 18 Nov 2005 16:04:58 +1100
>>From: Steven Johnson <[hidden email]>
>>
>>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
Reply | Threaded
Open this post in threaded view
|

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

Kevin Buettner
In reply to this post by jimb (Bugzilla)
On Thu, 17 Nov 2005 21:59:33 -0800
Jim Blandy <[hidden email]> wrote:

> On 11/17/05, Steven Johnson <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

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

jimb (Bugzilla)
On 11/18/05, Kevin Buettner <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

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

Kevin Buettner
In reply to this post by Eli Zaretskii
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
 

Reply | Threaded
Open this post in threaded view
|

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

Daniel Jacobowitz-2
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
Reply | Threaded
Open this post in threaded view
|

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

jimb (Bugzilla)
In reply to this post by Kevin Buettner
On 11/18/05, Kevin Buettner <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

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

Kevin Buettner
In reply to this post by Kevin Buettner
On Fri, 18 Nov 2005 14:33:09 -0700
Kevin Buettner <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

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

Michael Snyder
In reply to this post by Kevin Buettner
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
>  
>
>

Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Kevin Buettner
> Date: Fri, 18 Nov 2005 14:33:09 -0700
> From: Kevin Buettner <[hidden email]>
>
> 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.
Reply | Threaded
Open this post in threaded view
|

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

Kevin Buettner
In reply to this post by Kevin Buettner
On Fri, 18 Nov 2005 14:33:09 -0700
Kevin Buettner <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

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

Steven Johnson-2
In reply to this post by jimb (Bugzilla)
Jim Blandy wrote:

>On 11/18/05, Kevin Buettner <[hidden email]> 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.