Interrupting remote targets from GDB

[Kevin Buettner <kevinb at redhat dot com>]

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?