Interrupting remote targets from GDB

Interrupting remote targets from GDB

[Kevin Buettner]

A GDB user can request that a remote program be interrupted by typing
the interrupt character.  Then, depending upon the value of
`remotebreak', either a BREAK or Control-C character will be sent to
the remote target.

This behavior is documented in the GDB manual under "Debugging Remote
Programs".  In the subsection entitled "Connecting to a remote
target", the manual says:

    Whenever GDB is waiting for the remote program, if you type the
    interrupt character (often C-C), GDB attempts to stop the program. 
    This may or may not succeed, depending in part on the hardware and
    the serial drivers the remote system uses.  If you type the
    interrupt character once again, GDB displays this prompt:

	Interrupted while waiting for the program.
	Give up (and stop debugging it)?  (y or n)

    If you type y, GDB abandons the remote debugging session.  (If you
    decide you want to try again later, you can use `target remote'
    again to connect once more.) If you type n, GDB goes back to
    waiting. 

Later on, in the subsection entitled "Remote Configuration", it says:

    set remotebreak
	If set to on, GDB sends a BREAK signal to the remote when you
	press the Ctrl-C key to interrupt the program running on the
	remote.  If set to off, GDB sends the `Strl-C' character
	instead.  The default is off, since most remote systems expect
	to see `Ctrl-C' as the interrupt signal.

    show remotebreak
	Show whether GDB sends BREAK or `Ctrl-C' to interrupt the
	remote program.

I think this documentation is fine, but would also like to see some
suitable documentation added to the section describing the GDB remote
protocol.  I suggest that a section called "Interrupts" be added in
between the sections "Register Packet Format" and "Examples".  I propose
that it contain the following text:

    When a program on the remote target is running, GDB may attempt
    to interrupt it by sending a `Ctrl-C' or a BREAK, control of which
    is specified via GDB's `remotebreak' setting.  The precise meaning
    of BREAK is defined by the transport mechanism and may, in fact,
    be undefined.  `Ctrl-C', on the other hand, is defined for all
    transport mechanisms and is represented by sending the single byte
    0x03.  `Ctrl-C' must not be sent as part of a packet as defined in
    the "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' to GDB as a result of successfully stopping
    the program.

Comments?

Re: Interrupting remote targets from GDB

[Daniel Jacobowitz]

On Thu, Nov 17, 2005 at 11:20:43AM -0700, Kevin Buettner wrote:
>     set remotebreak
> 	If set to on, GDB sends a BREAK signal to the remote when you
> 	press the Ctrl-C key to interrupt the program running on the
> 	remote.  If set to off, GDB sends the `Strl-C' character
> 	instead.  The default is off, since most remote systems expect
> 	to see `Ctrl-C' as the interrupt signal.

Mind fixing the Strl-C ? ;-)

> I think this documentation is fine, but would also like to see some
> suitable documentation added to the section describing the GDB remote
> protocol.  I suggest that a section called "Interrupts" be added in
> between the sections "Register Packet Format" and "Examples".  I propose
> that it contain the following text:
> 
>     When a program on the remote target is running, GDB may attempt
>     to interrupt it by sending a `Ctrl-C' or a BREAK, control of which
>     is specified via GDB's `remotebreak' setting.  The precise meaning
>     of BREAK is defined by the transport mechanism and may, in fact,
>     be undefined.  `Ctrl-C', on the other hand, is defined for all
>     transport mechanisms and is represented by sending the single byte
>     0x03.  `Ctrl-C' must not be sent as part of a packet as defined in
>     the "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' to GDB as a result of successfully stopping
>     the program.
> 
> Comments?

Fine by me; can we also add a word about what to do with interrupts
when the target is stopped?  I believe they should be dropped rather
than responded to, per conversation on gdb@ earlier this month.

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: Interrupting remote targets from GDB

[Kevin Buettner]

On Thu, 17 Nov 2005 13:50:56 -0500
Daniel Jacobowitz <drow@false.org> wrote:

> On Thu, Nov 17, 2005 at 11:20:43AM -0700, Kevin Buettner wrote:
> >     set remotebreak
> > 	If set to on, GDB sends a BREAK signal to the remote when you
> > 	press the Ctrl-C key to interrupt the program running on the
> > 	remote.  If set to off, GDB sends the `Strl-C' character
> > 	instead.  The default is off, since most remote systems expect
> > 	to see `Ctrl-C' as the interrupt signal.
> 
> Mind fixing the Strl-C ? ;-)

Done.  Patch and commit message sent to gdb-patches@.

Kevin

Re: Interrupting remote targets from GDB

[Eli Zaretskii]

> Date: Thu, 17 Nov 2005 11:20:43 -0700
> From: Kevin Buettner <kevinb@redhat.com>
> 
> I think this documentation is fine, but would also like to see some
> suitable documentation added to the section describing the GDB remote
> protocol.  I suggest that a section called "Interrupts" be added in
> between the sections "Register Packet Format" and "Examples".  I propose
> that it contain the following text:
> 
>     When a program on the remote target is running, GDB may attempt
>     to interrupt it by sending a `Ctrl-C' or a BREAK, control of which
>     is specified via GDB's `remotebreak' setting.  The precise meaning
>     of BREAK is defined by the transport mechanism and may, in fact,
>     be undefined.  `Ctrl-C', on the other hand, is defined for all
>     transport mechanisms and is represented by sending the single byte
>     0x03.  `Ctrl-C' must not be sent as part of a packet as defined in
>     the "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' to GDB as a result of successfully stopping
>     the program.
> 
> Comments?

Fine with me.  Can you craft a patch and post it on gdb-patches for
review?

Re: Interrupting remote targets from GDB

[Kevin Buettner]

On Thu, 17 Nov 2005 13:50:56 -0500
Daniel Jacobowitz <drow@false.org> wrote:

> Fine by me; can we also add a word about what to do with interrupts
> when the target is stopped?  I believe they should be dropped rather
> than responded to, per conversation on gdb@ earlier this month.

I've added one sentence to the text I posted earlier.

Here's the revised text:

    When a program on the remote target is running, GDB may attempt
    to interrupt it by sending a `Ctrl-C' or a BREAK, control of which
    is specified via GDB's `remotebreak' setting.  The precise meaning
    of BREAK is defined by the transport mechanism and may, in fact,
    be undefined.  `Ctrl-C', on the other hand, is defined for all
    transport mechanisms and is represented by sending the single byte
    0x03.  `Ctrl-C' must not be sent as part of a packet as defined in
    the "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' to GDB as a result of successfully stopping
    the program.  Interrupts received while the program is stopped will
    be discarded.