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

Michael Snyder
2005-11-18T21:47:52Z

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