toolchain/share/doc/gdb/Connecting.html

302 lines
20 KiB
HTML
Raw Normal View History

2024-01-10 05:24:32 +00:00
<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:&nbsp;<a rel="next" accesskey="n" href="File-Transfer.html#File-Transfer">File Transfer</a>,
Up:&nbsp;<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
&lsquo;<samp><span class="samp">--baud</span></samp>&rsquo; 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 &ldquo;Unreliable&rdquo;. <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>&mdash;you
can add new commands that only the external monitor will understand
and implement.
</dl>
</body></html>