Interrupting remote targets from GDB

Kevin Buettner
2005-11-17T18:20:54Z

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?