302 lines
20 KiB
HTML
302 lines
20 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Connecting - Debugging with GDB</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Debugging with GDB">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Remote-Debugging.html#Remote-Debugging" title="Remote Debugging">
|
|
<link rel="next" href="File-Transfer.html#File-Transfer" title="File Transfer">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2019 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``Free Software'' and ``Free Software Needs
|
|
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
|
|
and with the Back-Cover Texts as in (a) below.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
|
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
|
developing GNU and promoting software freedom.''
|
|
-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Connecting"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="File-Transfer.html#File-Transfer">File Transfer</a>,
|
|
Up: <a rel="up" accesskey="u" href="Remote-Debugging.html#Remote-Debugging">Remote Debugging</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">20.1 Connecting to a Remote Target</h3>
|
|
|
|
<p><a name="index-remote-debugging_002c-connecting-1332"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-connecting-1333"></a><a name="index-remote-debugging_002c-types-of-connections-1334"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-types-of-connections-1335"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-_0040code_007btarget-remote_007d-mode-1336"></a><a name="index-g_t_0040code_007bgdbserver_007d_002c-_0040code_007btarget-extended_002dremote_007d-mode-1337"></a>
|
|
This section describes how to connect to a remote target, including the
|
|
types of connections and their differences, how to set up executable and
|
|
symbol files on the host and target, and the commands used for
|
|
connecting to and disconnecting from the remote target.
|
|
|
|
<h4 class="subsection">20.1.1 Types of Remote Connections</h4>
|
|
|
|
<p><span class="sc">gdb</span> supports two types of remote connections, <code>target remote</code>
|
|
mode and <code>target extended-remote</code> mode. Note that many remote targets
|
|
support only <code>target remote</code> mode. There are several major
|
|
differences between the two types of connections, enumerated here:
|
|
|
|
|
|
<a name="index-remote-debugging_002c-detach-and-program-exit-1338"></a>
|
|
<dl><dt>Result of detach or program exit<dd><strong>With target remote mode:</strong> When the debugged program exits or you
|
|
detach from it, <span class="sc">gdb</span> disconnects from the target. When using
|
|
<code>gdbserver</code>, <code>gdbserver</code> will exit.
|
|
|
|
<p><strong>With target extended-remote mode:</strong> When the debugged program exits or
|
|
you detach from it, <span class="sc">gdb</span> remains connected to the target, even
|
|
though no program is running. You can rerun the program, attach to a
|
|
running program, or use <code>monitor</code> commands specific to the target.
|
|
|
|
<p>When using <code>gdbserver</code> in this case, it does not exit unless it was
|
|
invoked using the <samp><span class="option">--once</span></samp> option. If the <samp><span class="option">--once</span></samp> option
|
|
was not used, you can ask <code>gdbserver</code> to exit using the
|
|
<code>monitor exit</code> command (see <a href="Monitor-Commands-for-gdbserver.html#Monitor-Commands-for-gdbserver">Monitor Commands for gdbserver</a>).
|
|
|
|
<br><dt>Specifying the program to debug<dd>For both connection types you use the <code>file</code> command to specify the
|
|
program on the host system. If you are using <code>gdbserver</code> there are
|
|
some differences in how to specify the location of the program on the
|
|
target.
|
|
|
|
<p><strong>With target remote mode:</strong> You must either specify the program to debug
|
|
on the <code>gdbserver</code> command line or use the <samp><span class="option">--attach</span></samp> option
|
|
(see <a href="Attaching-to-a-program.html#Attaching-to-a-program">Attaching to a Running Program</a>).
|
|
|
|
<p><a name="index-g_t_0040option_007b_002d_002dmulti_007d_002c-_0040code_007bgdbserver_007d-option-1339"></a><strong>With target extended-remote mode:</strong> You may specify the program to debug
|
|
on the <code>gdbserver</code> command line, or you can load the program or attach
|
|
to it using <span class="sc">gdb</span> commands after connecting to <code>gdbserver</code>.
|
|
|
|
<p><a name="g_t_002d_002dmulti-Option-in-Types-of-Remote-Connnections"></a>You can start <code>gdbserver</code> without supplying an initial command to run
|
|
or process ID to attach. To do this, use the <samp><span class="option">--multi</span></samp> command line
|
|
option. Then you can connect using <code>target extended-remote</code> and start
|
|
the program you want to debug (see below for details on using the
|
|
<code>run</code> command in this scenario). Note that the conditions under which
|
|
<code>gdbserver</code> terminates depend on how <span class="sc">gdb</span> connects to it
|
|
(<code>target remote</code> or <code>target extended-remote</code>). The
|
|
<samp><span class="option">--multi</span></samp> option to <code>gdbserver</code> has no influence on that.
|
|
|
|
<br><dt>The <code>run</code> command<dd><strong>With target remote mode:</strong> The <code>run</code> command is not
|
|
supported. Once a connection has been established, you can use all
|
|
the usual <span class="sc">gdb</span> commands to examine and change data. The
|
|
remote program is already running, so you can use commands like
|
|
<kbd>step</kbd> and <kbd>continue</kbd>.
|
|
|
|
<p><strong>With target extended-remote mode:</strong> The <code>run</code> command is
|
|
supported. The <code>run</code> command uses the value set by
|
|
<code>set remote exec-file</code> (see <a href="set-remote-exec_002dfile.html#set-remote-exec_002dfile">set remote exec-file</a>) to select
|
|
the program to run. Command line arguments are supported, except for
|
|
wildcard expansion and I/O redirection (see <a href="Arguments.html#Arguments">Arguments</a>).
|
|
|
|
<p>If you specify the program to debug on the command line, then the
|
|
<code>run</code> command is not required to start execution, and you can
|
|
resume using commands like <kbd>step</kbd> and <kbd>continue</kbd> as with
|
|
<code>target remote</code> mode.
|
|
|
|
<p><a name="Attaching-in-Types-of-Remote-Connections"></a><br><dt>Attaching<dd><strong>With target remote mode:</strong> The <span class="sc">gdb</span> command <code>attach</code> is
|
|
not supported. To attach to a running program using <code>gdbserver</code>, you
|
|
must use the <samp><span class="option">--attach</span></samp> option (see <a href="Running-gdbserver.html#Running-gdbserver">Running gdbserver</a>).
|
|
|
|
<p><strong>With target extended-remote mode:</strong> To attach to a running program,
|
|
you may use the <code>attach</code> command after the connection has been
|
|
established. If you are using <code>gdbserver</code>, you may also invoke
|
|
<code>gdbserver</code> using the <samp><span class="option">--attach</span></samp> option
|
|
(see <a href="Running-gdbserver.html#Running-gdbserver">Running gdbserver</a>).
|
|
|
|
</dl>
|
|
|
|
<p><a name="Host-and-target-files"></a>
|
|
|
|
<h4 class="subsection">20.1.2 Host and Target Files</h4>
|
|
|
|
<p><a name="index-remote-debugging_002c-symbol-files-1340"></a><a name="index-symbol-files_002c-remote-debugging-1341"></a>
|
|
<span class="sc">gdb</span>, running on the host, needs access to symbol and debugging
|
|
information for your program running on the target. This requires
|
|
access to an unstripped copy of your program, and possibly any associated
|
|
symbol files. Note that this section applies equally to both <code>target
|
|
remote</code> mode and <code>target extended-remote</code> mode.
|
|
|
|
<p>Some remote targets (see <a href="qXfer-executable-filename-read.html#qXfer-executable-filename-read">qXfer executable filename read</a>, and
|
|
see <a href="Host-I_002fO-Packets.html#Host-I_002fO-Packets">Host I/O Packets</a>) allow <span class="sc">gdb</span> to access program files over
|
|
the same connection used to communicate with <span class="sc">gdb</span>. With such a
|
|
target, if the remote program is unstripped, the only command you need is
|
|
<code>target remote</code> (or <code>target extended-remote</code>).
|
|
|
|
<p>If the remote program is stripped, or the target does not support remote
|
|
program file access, start up <span class="sc">gdb</span> using the name of the local
|
|
unstripped copy of your program as the first argument, or use the
|
|
<code>file</code> command. Use <code>set sysroot</code> to specify the location (on
|
|
the host) of target libraries (unless your <span class="sc">gdb</span> was compiled with
|
|
the correct sysroot using <code>--with-sysroot</code>). Alternatively, you
|
|
may use <code>set solib-search-path</code> to specify how <span class="sc">gdb</span> locates
|
|
target libraries.
|
|
|
|
<p>The symbol file and target libraries must exactly match the executable
|
|
and libraries on the target, with one exception: the files on the host
|
|
system should not be stripped, even if the files on the target system
|
|
are. Mismatched or missing files will lead to confusing results
|
|
during debugging. On <span class="sc">gnu</span>/Linux targets, mismatched or missing
|
|
files may also prevent <code>gdbserver</code> from debugging multi-threaded
|
|
programs.
|
|
|
|
<h4 class="subsection">20.1.3 Remote Connection Commands</h4>
|
|
|
|
<p><a name="index-remote-connection-commands-1342"></a><span class="sc">gdb</span> can communicate with the target over a serial line, a
|
|
local Unix domain socket, or
|
|
over an <acronym>IP</acronym> network using <acronym>TCP</acronym> or <acronym>UDP</acronym>. In
|
|
each case, <span class="sc">gdb</span> uses the same protocol for debugging your
|
|
program; only the medium carrying the debugging packets varies. The
|
|
<code>target remote</code> and <code>target extended-remote</code> commands
|
|
establish a connection to the target. Both commands accept the same
|
|
arguments, which indicate the medium to use:
|
|
|
|
<dl>
|
|
<dt><code>target remote </code><var>serial-device</var><dt><code>target extended-remote </code><var>serial-device</var><dd><a name="index-serial-line_002c-_0040code_007btarget-remote_007d-1343"></a>Use <var>serial-device</var> to communicate with the target. For example,
|
|
to use a serial line connected to the device named <samp><span class="file">/dev/ttyb</span></samp>:
|
|
|
|
<pre class="smallexample"> target remote /dev/ttyb
|
|
</pre>
|
|
<p>If you're using a serial line, you may want to give <span class="sc">gdb</span> the
|
|
‘<samp><span class="samp">--baud</span></samp>’ option, or use the <code>set serial baud</code> command
|
|
(see <a href="Remote-Configuration.html#Remote-Configuration">set serial baud</a>) before the
|
|
<code>target</code> command.
|
|
|
|
<br><dt><code>target remote </code><var>local-socket</var><dt><code>target extended-remote </code><var>local-socket</var><dd><a name="index-local-socket_002c-_0040code_007btarget-remote_007d-1344"></a><a name="index-Unix-domain-socket-1345"></a>Use <var>local-socket</var> to communicate with the target. For example,
|
|
to use a local Unix domain socket bound to the file system entry <samp><span class="file">/tmp/gdb-socket0</span></samp>:
|
|
|
|
<pre class="smallexample"> target remote /tmp/gdb-socket0
|
|
</pre>
|
|
<p>Note that this command has the same form as the command to connect
|
|
to a serial line. <span class="sc">gdb</span> will automatically determine which
|
|
kind of file you have specified and will make the appropriate kind
|
|
of connection.
|
|
This feature is not available if the host system does not support
|
|
Unix domain sockets.
|
|
|
|
<br><dt><code>target remote </code><var>host</var><code>:</code><var>port</var><dt><code>target remote </code><var>[host]</var><code>:</code><var>port</var><dt><code>target remote tcp:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target remote tcp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote tcp6:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote </code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote </code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote tcp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote tcp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote tcp6:</code><var>[host]</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bTCP_007d-port_002c-_0040code_007btarget-remote_007d-1346"></a>Debug using a <acronym>TCP</acronym> connection to <var>port</var> on <var>host</var>.
|
|
The <var>host</var> may be either a host name, a numeric <acronym>IPv4</acronym>
|
|
address, or a numeric <acronym>IPv6</acronym> address (with or without the
|
|
square brackets to separate the address from the port); <var>port</var>
|
|
must be a decimal number. The <var>host</var> could be the target machine
|
|
itself, if it is directly connected to the net, or it might be a
|
|
terminal server which in turn has a serial line to the target.
|
|
|
|
<p>For example, to connect to port 2828 on a terminal server named
|
|
<code>manyfarms</code>:
|
|
|
|
<pre class="smallexample"> target remote manyfarms:2828
|
|
</pre>
|
|
<p>To connect to port 2828 on a terminal server whose address is
|
|
<code>2001:0db8:85a3:0000:0000:8a2e:0370:7334</code>, you can either use the
|
|
square bracket syntax:
|
|
|
|
<pre class="smallexample"> target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828
|
|
</pre>
|
|
<p class="noindent">or explicitly specify the <acronym>IPv6</acronym> protocol:
|
|
|
|
<pre class="smallexample"> target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828
|
|
</pre>
|
|
<p>This last example may be confusing to the reader, because there is no
|
|
visible separation between the hostname and the port number.
|
|
Therefore, we recommend the user to provide <acronym>IPv6</acronym> addresses
|
|
using square brackets for clarity. However, it is important to
|
|
mention that for <span class="sc">gdb</span> there is no ambiguity: the number after
|
|
the last colon is considered to be the port number.
|
|
|
|
<p>If your remote target is actually running on the same machine as your
|
|
debugger session (e.g. a simulator for your target running on the
|
|
same host), you can omit the hostname. For example, to connect to
|
|
port 1234 on your local machine:
|
|
|
|
<pre class="smallexample"> target remote :1234
|
|
</pre>
|
|
<p class="noindent">Note that the colon is still required here.
|
|
|
|
<br><dt><code>target remote udp:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote udp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target remote udp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target remote udp6:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp:</code><var>[host]</var><code>:</code><var>port</var><dt><code>target extended-remote udp4:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp6:</code><var>host</var><code>:</code><var>port</var><dt><code>target extended-remote udp6:</code><var>[host]</var><code>:</code><var>port</var><dd><a name="index-g_t_0040acronym_007bUDP_007d-port_002c-_0040code_007btarget-remote_007d-1347"></a>Debug using <acronym>UDP</acronym> packets to <var>port</var> on <var>host</var>. For example, to
|
|
connect to <acronym>UDP</acronym> port 2828 on a terminal server named <code>manyfarms</code>:
|
|
|
|
<pre class="smallexample"> target remote udp:manyfarms:2828
|
|
</pre>
|
|
<p>When using a <acronym>UDP</acronym> connection for remote debugging, you should
|
|
keep in mind that the `U' stands for “Unreliable”. <acronym>UDP</acronym>
|
|
can silently drop packets on busy or unreliable networks, which will
|
|
cause havoc with your debugging session.
|
|
|
|
<br><dt><code>target remote | </code><var>command</var><dt><code>target extended-remote | </code><var>command</var><dd><a name="index-pipe_002c-_0040code_007btarget-remote_007d-to-1348"></a>Run <var>command</var> in the background and communicate with it using a
|
|
pipe. The <var>command</var> is a shell command, to be parsed and expanded
|
|
by the system's command shell, <code>/bin/sh</code>; it should expect remote
|
|
protocol packets on its standard input, and send replies on its
|
|
standard output. You could use this to run a stand-alone simulator
|
|
that speaks the remote debugging protocol, to make net connections
|
|
using programs like <code>ssh</code>, or for other similar tricks.
|
|
|
|
<p>If <var>command</var> closes its standard output (perhaps by exiting),
|
|
<span class="sc">gdb</span> will try to send it a <code>SIGTERM</code> signal. (If the
|
|
program has already exited, this will have no effect.)
|
|
|
|
</dl>
|
|
|
|
<p><a name="index-interrupting-remote-programs-1349"></a><a name="index-remote-programs_002c-interrupting-1350"></a>Whenever <span class="sc">gdb</span> is waiting for the remote program, if you type the
|
|
interrupt character (often <kbd>Ctrl-c</kbd>), <span class="sc">gdb</span> 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, <span class="sc">gdb</span> displays this prompt:
|
|
|
|
<pre class="smallexample"> Interrupted while waiting for the program.
|
|
Give up (and stop debugging it)? (y or n)
|
|
</pre>
|
|
<p>In <code>target remote</code> mode, if you type <kbd>y</kbd>, <span class="sc">gdb</span> abandons
|
|
the remote debugging session. (If you decide you want to try again later,
|
|
you can use <kbd>target remote</kbd> again to connect once more.) If you type
|
|
<kbd>n</kbd>, <span class="sc">gdb</span> goes back to waiting.
|
|
|
|
<p>In <code>target extended-remote</code> mode, typing <kbd>n</kbd> will leave
|
|
<span class="sc">gdb</span> connected to the target.
|
|
|
|
|
|
<a name="index-detach-_0028remote_0029-1351"></a>
|
|
<dl><dt><code>detach</code><dd>When you have finished debugging the remote program, you can use the
|
|
<code>detach</code> command to release it from <span class="sc">gdb</span> control.
|
|
Detaching from the target normally resumes its execution, but the results
|
|
will depend on your particular remote stub. After the <code>detach</code>
|
|
command in <code>target remote</code> mode, <span class="sc">gdb</span> is free to connect to
|
|
another target. In <code>target extended-remote</code> mode, <span class="sc">gdb</span> is
|
|
still connected to the target.
|
|
|
|
<p><a name="index-disconnect-1352"></a><br><dt><code>disconnect</code><dd>The <code>disconnect</code> command closes the connection to the target, and
|
|
the target is generally not resumed. It will wait for <span class="sc">gdb</span>
|
|
(this instance or another one) to connect and continue debugging. After
|
|
the <code>disconnect</code> command, <span class="sc">gdb</span> is again free to connect to
|
|
another target.
|
|
|
|
<p><a name="index-send-command-to-remote-monitor-1353"></a><a name="index-extend-_0040value_007bGDBN_007d-for-remote-targets-1354"></a><a name="index-add-new-commands-for-external-monitor-1355"></a><a name="index-monitor-1356"></a><br><dt><code>monitor </code><var>cmd</var><dd>This command allows you to send arbitrary commands directly to the
|
|
remote monitor. Since <span class="sc">gdb</span> doesn't care about the commands it
|
|
sends like this, this command is the way to extend <span class="sc">gdb</span>—you
|
|
can add new commands that only the external monitor will understand
|
|
and implement.
|
|
</dl>
|
|
|
|
</body></html>
|
|
|