[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
>  
> 
>