From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 29026 invoked by alias); 18 Nov 2005 21:33:20 -0000 Received: (qmail 29004 invoked by uid 22791); 18 Nov 2005 21:33:18 -0000 Received: from mx1.redhat.com (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Fri, 18 Nov 2005 21:33:18 +0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.12.11/8.12.11) with ESMTP id jAILXGmD014767 for ; Fri, 18 Nov 2005 16:33:16 -0500 Received: from pobox.corp.redhat.com (pobox.corp.redhat.com [172.16.52.156]) by int-mx1.corp.redhat.com (8.11.6/8.11.6) with ESMTP id jAILXGV06925 for ; Fri, 18 Nov 2005 16:33:16 -0500 Received: from localhost.localdomain (vpn50-163.rdu.redhat.com [172.16.50.163]) by pobox.corp.redhat.com (8.12.8/8.12.8) with ESMTP id jAILXFFM008637 for ; Fri, 18 Nov 2005 16:33:15 -0500 Received: from ironwood.lan (ironwood.lan [192.168.64.8]) by localhost.localdomain (8.12.11/8.12.10) with ESMTP id jAILXAh7019797 for ; Fri, 18 Nov 2005 14:33:10 -0700 Date: Fri, 18 Nov 2005 21:45:00 -0000 From: Kevin Buettner To: gdb-patches@sources.redhat.com Subject: Re: [rfa/doc] Add section on interrupts to remote protocol documentation Message-ID: <20051118143309.73c45545@ironwood.lan> In-Reply-To: References: <20051117195224.32094bd5@ironwood.lan> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2005-11/txt/msg00346.txt.bz2 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? * 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