From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7793 invoked by alias); 17 Jun 2003 22:00:13 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 7736 invoked from network); 17 Jun 2003 22:00:10 -0000 Received: from unknown (HELO crack.them.org) (146.82.138.56) by sources.redhat.com with SMTP; 17 Jun 2003 22:00:10 -0000 Received: from dsl093-172-017.pit1.dsl.speakeasy.net ([66.93.172.17] helo=nevyn.them.org ident=mail) by crack.them.org with asmtp (Exim 3.12 #1 (Debian)) id 19SOVQ-00063A-00; Tue, 17 Jun 2003 17:00:45 -0500 Received: from drow by nevyn.them.org with local (Exim 3.36 #1 (Debian)) id 19SOUa-00067k-00; Tue, 17 Jun 2003 17:59:52 -0400 Date: Tue, 17 Jun 2003 22:00:00 -0000 From: Daniel Jacobowitz To: Andrew Cagney , eliz@gnu.org Cc: gdb-patches@sources.redhat.com Subject: Re: RFA: "disconnect" command Message-ID: <20030617215951.GA23468@nevyn.them.org> Mail-Followup-To: Andrew Cagney , eliz@gnu.org, gdb-patches@sources.redhat.com References: <20030614042642.GA28231@nevyn.them.org> <3EEF2CCF.7020708@redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3EEF2CCF.7020708@redhat.com> User-Agent: Mutt/1.5.1i X-SW-Source: 2003-06/txt/msg00585.txt.bz2 On Tue, Jun 17, 2003 at 10:59:27AM -0400, Andrew Cagney wrote: > >This patch got tabled shortly before 5.3, due to bad timing on my part. > >Now here we are coming up on 6.0 and my timing's no better... this is > >the first of several old patches that I would like to see included in > >6.0, assuming I get the time to revisit them all. > > > >Refresher on this one: the patch adds a "disconnect" commad, and > >implements it for remote targets. "disconnect" leaves the target > >stopped, while "detach" usually resumes it. Useful with kgdb, > >gdbserver, et cetera. > > > >I've included the gdbserver portion of the patch this time, too. > > > >There was a consensus on this patch the last time I posted it, but it's > >been so long that I'd like a thumbs-up from another maintainer first. > >I've corrected the doc problems; Andrew, there's still no MI testcase, > >because I could not figure out a reasonable way to write one without > >leaving a dangling process around. Re-attaching to it to kill it > >properly, from within the testsuite, ranges from hard to really hard. > > > >Thoughts? OK? > > The code, yea. Just check that part in. > > The doco, though, does not belong in ``Implementing a remote stub'' :-( > (the existing doco is scrambled). Yeah, it is. I was trying to avoid rewriting it, but since you asked... Is this better? Eli, I think I got the Texinfo and general structure right, but I'd appreciate it if you'd look over this anyway. -- Daniel Jacobowitz MontaVista Software Debian GNU/Linux Developer 2003-06-14 Daniel Jacobowitz * gdb.texinfo (Remote Debugging): New section "Connecting to a remote target". Document the "detach" and "disconnect" commands. (Server, Netware, Debug Session): Reference "Connecting to a remote target". (GDB/MI Target Manipulation): Document "-target-disconnect". Index: doc/gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.164 diff -u -p -r1.164 gdb.texinfo --- doc/gdb.texinfo 9 Jun 2003 21:12:19 -0000 1.164 +++ doc/gdb.texinfo 17 Jun 2003 21:55:22 -0000 @@ -10513,12 +10513,113 @@ is supported other than to try it. @chapter Debugging remote programs @menu +* Connecting:: Connecting to a remote target * Server:: Using the gdbserver program * NetWare:: Using the gdbserve.nlm program * Remote configuration:: Remote configuration * remote stub:: Implementing a remote stub @end menu +@node Connecting +@section Connecting to a remote target + +On the @value{GDBN} host machine, you will need an unstripped copy of +your program, since @value{GDBN} needs symobl and debugging information. +Start up @value{GDBN} as usual, using the name of the local copy of your +program as the first argument. + +@cindex serial line, @code{target remote} +If you're using a serial line, you may want to give @value{GDBN} the +@w{@samp{--baud}} option, or use the @code{set remotebaud} command +before the @code{target} command. + +After that, use @code{target remote} to establish communications with +the target machine. Its argument specifies how to communicate---either +via a devicename attached to a direct serial line, or a TCP or UDP port +(possibly to a terminal server which in turn has a serial line to the +target). For example, to use a serial line connected to the device +named @file{/dev/ttyb}: + +@smallexample +target remote /dev/ttyb +@end smallexample + +@cindex TCP port, @code{target remote} +To use a TCP connection, use an argument of the form +@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. +For example, to connect to port 2828 on a +terminal server named @code{manyfarms}: + +@smallexample +target remote manyfarms:2828 +@end smallexample + +If your remote target is actually running on the same machine as +your debugger session (e.g.@: a simulator of your target running on +the same host), you can omit the hostname. For example, to connect +to port 1234 on your local machine: + +@smallexample +target remote :1234 +@end smallexample +@noindent + +Note that the colon is still required here. + +@cindex UDP port, @code{target remote} +To use a UDP connection, use an argument of the form +@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 +on a terminal server named @code{manyfarms}: + +@smallexample +target remote udp:manyfarms:2828 +@end smallexample + +When using a UDP connection for remote debugging, you should keep in mind +that the `U' stands for ``Unreliable''. UDP can silently drop packets on +busy or unreliable networks, which will cause havoc with your debugging +session. + +Now you can use all the usual commands to examine and change data and to +step and continue the remote program. + +@cindex interrupting remote programs +@cindex remote programs, interrupting +Whenever @value{GDBN} is waiting for the remote program, if you type the +interrupt character (often @key{C-C}), @value{GDBN} 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, @value{GDBN} displays this prompt: + +@smallexample +Interrupted while waiting for the program. +Give up (and stop debugging it)? (y or n) +@end smallexample + +If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. +(If you decide you want to try again later, you can use @samp{target +remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} +goes back to waiting. + +@table @code +@kindex detach (remote) +@item detach +When you have finished debugging the remote program, you can use the +@code{detach} command to release it from @value{GDBN} control. +Detaching from the target normally resumes its execution, but the results +will depend on your particular remote stub. After the @code{detach} +command, @value{GDBN} is free to connect to another target. + +@kindex disconnect +@item disconnect +The @code{disconnect} command behaves like @code{detach}, except that +the target is generally not resumed. It will wait for @value{GDBN} +(this instance or another one) to connect and continue debugging. When +you have finished debugging the remote program, you can use the After +the @code{disconnect} command, @value{GDBN} is again free to connect to +another target. +@end table + @node Server @section Using the @code{gdbserver} program @@ -10601,34 +10702,15 @@ target> gdbserver @var{comm} --attach @v @var{pid} is the process ID of a currently running process. It isn't necessary to point @code{gdbserver} at a binary for the running process. -@item On the @value{GDBN} host machine, -you need an unstripped copy of your program, since @value{GDBN} needs -symbols and debugging information. Start up @value{GDBN} as usual, -using the name of the local copy of your program as the first argument. -(You may also need the @w{@samp{--baud}} option if the serial line is -running at anything other than 9600@dmn{bps}.) After that, use @code{target -remote} to establish communications with @code{gdbserver}. Its argument -is either a device name (usually a serial device, like -@file{/dev/ttyb}), or a TCP port descriptor in the form -@code{@var{host}:@var{PORT}}. For example: - -@smallexample -(@value{GDBP}) target remote /dev/ttyb -@end smallexample - -@noindent -communicates with the server via serial line @file{/dev/ttyb}, and - -@smallexample -(@value{GDBP}) target remote the-target:2345 -@end smallexample - -@noindent -communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. +@item On the host machine, +connect to your target (@pxref{Connecting,,Connecting to a remote target}). For TCP connections, you must start up @code{gdbserver} prior to using the @code{target remote} command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like -@samp{Connection refused}. +@samp{Connection refused}. You don't need to use the @code{load} +command in @value{GDBN} when using gdbserver, since the program is +already on the target. + @end table @node NetWare @@ -10670,22 +10752,10 @@ using a 19200@dmn{bps} connection: load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt @end smallexample -@item On the @value{GDBN} host machine, -you need an unstripped copy of your program, since @value{GDBN} needs -symbols and debugging information. Start up @value{GDBN} as usual, -using the name of the local copy of your program as the first argument. -(You may also need the @w{@samp{--baud}} option if the serial line is -running at anything other than 9600@dmn{bps}. After that, use @code{target -remote} to establish communications with @code{gdbserve.nlm}. Its -argument is a device name (usually a serial device, like -@file{/dev/ttyb}). For example: - -@smallexample -(@value{GDBP}) target remote /dev/ttyb -@end smallexample +@item +On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,, +Connecting to a remote target}). -@noindent -communications with the server via serial line @file{/dev/ttyb}. @end table @node Remote configuration @@ -11007,87 +11077,11 @@ Download your program to your target mac whatever means the manufacturer provides), and start it. @item -To start remote debugging, run @value{GDBN} on the host machine, and specify -as an executable file the program that is running in the remote machine. -This tells @value{GDBN} how to find your program's symbols and the contents -of its pure text. - -@item -@cindex serial line, @code{target remote} -Establish communication using the @code{target remote} command. -Its argument specifies how to communicate with the target -machine---either via a devicename attached to a direct serial line, or a -TCP or UDP port (usually to a terminal server which in turn has a serial line -to the target). For example, to use a serial line connected to the -device named @file{/dev/ttyb}: - -@smallexample -target remote /dev/ttyb -@end smallexample - -@cindex TCP port, @code{target remote} -To use a TCP connection, use an argument of the form -@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. -For example, to connect to port 2828 on a -terminal server named @code{manyfarms}: - -@smallexample -target remote manyfarms:2828 -@end smallexample - -If your remote target is actually running on the same machine as -your debugger session (e.g.@: a simulator of your target running on -the same host), you can omit the hostname. For example, to connect -to port 1234 on your local machine: - -@smallexample -target remote :1234 -@end smallexample -@noindent - -Note that the colon is still required here. - -@cindex UDP port, @code{target remote} -To use a UDP connection, use an argument of the form -@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 -on a terminal server named @code{manyfarms}: - -@smallexample -target remote udp:manyfarms:2828 -@end smallexample - -When using a UDP connection for remote debugging, you should keep in mind -that the `U' stands for ``Unreliable''. UDP can silently drop packets on -busy or unreliable networks, which will cause havoc with your debugging -session. +Start @value{GDBN} on the host, and connect to the target +(@pxref{Connecting,,Connecting to a remote target}). @end enumerate -Now you can use all the usual commands to examine and change data and to -step and continue the remote program. - -To resume the remote program and stop debugging it, use the @code{detach} -command. - -@cindex interrupting remote programs -@cindex remote programs, interrupting -Whenever @value{GDBN} is waiting for the remote program, if you type the -interrupt character (often @key{C-C}), @value{GDBN} 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, @value{GDBN} displays this prompt: - -@smallexample -Interrupted while waiting for the program. -Give up (and stop debugging it)? (y or n) -@end smallexample - -If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. -(If you decide you want to try again later, you can use @samp{target -remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} -goes back to waiting. - - @node Configurations @chapter Configuration-Specific Information @@ -17392,6 +17386,31 @@ The corresponding @value{GDBN} command i @end smallexample +@subheading The @code{-target-disconnect} Command +@findex -target-disconnect + +@subsubheading Synopsis + +@example + -target-disconnect +@end example + +Disconnect from the remote target. There's no output. + +@subsubheading @value{GDBN} command + +The corresponding @value{GDBN} command is @samp{disconnect}. + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-target-disconnect +^done +(@value{GDBP}) +@end smallexample + + @subheading The @code{-target-download} Command @findex -target-download @@ -19775,7 +19794,7 @@ Toggle debug flag. @cindex @code{D} packet Detach @value{GDBN} from the remote system. Sent to the remote target -before @value{GDBN} disconnects. +before @value{GDBN} disconnects via the @code{detach} command. Reply: @table @samp