This is an archive of the discontinued LLVM Phabricator instance.

Add documentation about remote debugging to the website
ClosedPublic

Authored by labath on Apr 7 2015, 7:52 AM.

Download Raw Diff

Details

Reviewers

clayborg
tberghammer

Commits

rG34ec863b1cef: Add documentation about remote debugging to the website
rLLDB234395: Add documentation about remote debugging to the website
rL234395: Add documentation about remote debugging to the website

Diff Detail

Repository: rL LLVM

Event Timeline

labath updated this revision to Diff 23339.Apr 7 2015, 7:52 AM

labath retitled this revision from to Add documentation about remote debugging to the website.

labath updated this object.

labath edited the test plan for this revision. (Show Details)

labath added reviewers: tberghammer, clayborg.

labath added a subscriber: Unknown Object (MLST).

Herald added a subscriber: tberghammer. · View Herald TranscriptApr 7 2015, 7:52 AM

Looks great.

This revision is now accepted and ready to land.Apr 7 2015, 10:27 AM

Looks good

www/remote.html
43–44 ↗	(On Diff #23339)	AFAIK only OSX and Linux do it.

Closed by commit rL234395: Add documentation about remote debugging to the website (authored by labath). · Explain WhyApr 8 2015, 12:57 AM

This revision was automatically updated to reflect the committed changes.

Revision Contents

Path

Size

lldb/

trunk/

www/

build.html

2 lines

remote.html

145 lines

sidebar.incl

1 line

Diff 23405

lldb/trunk/www/build.html

Show First 20 Lines • Show All 420 Lines • ▼ Show 20 Lines	<div id="content">
<code>> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`</code>		<code>> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`</code>
<p>		<p>
If you used a different build directory or made a release build, you may need to adjust the		If you used a different build directory or made a release build, you may need to adjust the
above to suit your needs. To test that the lldb Python module		above to suit your needs. To test that the lldb Python module
is built correctly and is available to the default Python interpreter, run:		is built correctly and is available to the default Python interpreter, run:
</p>		</p>
<code>> python -c 'import lldb'</code></p>		<code>> python -c 'import lldb'</code></p>

<h2>Cross-compiling LLDB</h2>		<h2 id="cross-compilation">Cross-compiling LLDB</h2>
<p>		<p>
In order to debug remote targets running different architectures than your host, you		In order to debug remote targets running different architectures than your host, you
will need to compile LLDB (or at least the server component) for the target. While		will need to compile LLDB (or at least the server component) for the target. While
the easiest solution is to just compile it locally on the target, this is often not		the easiest solution is to just compile it locally on the target, this is often not
feasable, and in these cases you will need to cross-compile LLDB on your host.		feasable, and in these cases you will need to cross-compile LLDB on your host.
</p>		</p>

<p>		<p>
▲ Show 20 Lines • Show All 170 Lines • Show Last 20 Lines

lldb/trunk/www/remote.html

				<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
				<html xmlns="http://www.w3.org/1999/xhtml">
				<head>
				<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
				<link href="style.css" rel="stylesheet" type="text/css" />
				<title>Remote debugging with LLDB</title>
				</head>
				<body>
				<div class="www_title">
				The <strong>LLDB</strong> Debugger
				</div>

				<div id="container">
				<div id="content">

				<!--#include virtual="sidebar.incl"-->

				<div id="middle">
				<h1 class="postheader">Remote debugging</h1>
				<div class="postcontent">
				<p>
				Remote debugging refers to the act of debugging a process which is running on a
				different system, than the debugger itself. We shall refer to the system running
				the debugger as the <em>local</em> system, while the system running the debugged
				process will be the <em>remote</em> system.
				</p>

				<p>
				To enable remote debugging, LLDB employs a client-server architecture. The client
				part runs on the local system and the remote system runs the server. The client and
				server communicate using the gdb-remote protocol, usually transported over TCP/IP.
				More information on the protocol can be found
				<a href="https://sourceware.org/gdb/current/onlinedocs/gdb/Remote-Protocol.html">here</a>
				and the LLDB-specific extensions are documented in
				<code>docs/lldb-gdb-remote.txt</code> file inside LLDB source repository. Besides the
				gdb-remote stub, the server part of LLDB also consists of a <em>platform</em> binary,
				which is responsible for performing advanced debugging operations, like copying files
				from/to the remote system and can be used to execute arbitrary shell commands on the
				remote system.
				</p>

				<p>
				In order to reduce code complexity and improve remote debugging experience LLDB on
				Linux and OSX uses the remote debugging stub even when debugging a process locally.
				This is achieved by spawning a remote stub process locally and communicating with it
				over the loopback interface. In the case of local debugging this whole process is
				transparent to the user. The platform binary is not used in this case, since no file
				transfers are needed.
				</p>
				</div>
				<div class="postfooter"></div>
				<div class="post">
				<h1 class="postheader">Preparation for remote debugging</h1>
				<div class="postcontent">
				<p>
				While the process of actual debugging (stepping, backtraces, evaluating
				expressions) is same as in the local case, in the case of remote debugging, more
				preparation is needed as the required binaries cannot started on the remote system
				automatically. Also, if the remote system runs a different OS or architecture, the
				server component needs to be compiled separately.
				</p>

				<h2>Remote system</h2>
				<p>
				On Linux and Android, all required remote functionality is contained in the
				<code>lldb-server</code> binary. This binary combines the functionality of the
				platform and gdb-remote stub. A single binary fascilitates deployment and reduces
				code size, since the two functions share a lot of code. The
				<code>lldb-server</code> binary is also statically linked with the rest of LLDB
				(unlike <code>lldb</code>, which dynamically links to <code>liblldb.so</code> by
				default), so it does not have any dependencies on the rest of lldb. On Mac OSX and
				iOS, the remote-gdb functionality is implemented by the <code>debugserver</code>
				binary, which you will need to deploy alongside <code>lldb-server</code>.
				</p>

				<p>
				The binaries mentioned above need to be present on the remote system to enable
				remote debugging. You can either compile on the remote system directly or copy them
				from the local machine. If compiling locally and the remote architecture differs
				from the local one, you will need to cross-compile the correct version of the binaries.
				More information on cross-compiling LLDB can be found on the
				<a href="build.html#cross-compilation">build</a> page.
				</p>

				<p>
				Once the binaries are in place, you just need to run the <code>lldb-server</code>
				in platform mode and specify the port it should listen on. For example, the command
				</p>
				<code>lldb-server platform --listen *:1234</code>
				<p>
				will start the LLDB platform and wait for incoming connections from any address to
				port 1234. Specifying an address instead of <code>*</code> will only allow
				connections originating from that address. Adding a <code>--server</code> parameter
				to the command line will fork off a new process for every incoming connection,
				allowing multiple parallel debug sessions.
				</p>

				<h2>Local system</h2>

				<p>
				On the local system, you need to let LLDB know that you intend to do remote
				debugging. This is achieved through the <code>platform</code> command and its
				sub-commands. As a first step you need to choose the correct platform plug-in for
				your remote system. A list of available plug-ins can be obtained through
				<code>platform list</code>.
				</p>

				<p>
				The default platform is the platform <code>host</code> which is used for local
				debugging. Apart from this, the list should contain a number of plug-ins, for
				debugging different kinds of systems. The remote plug-ins are prefixed with
				"<code>remote-</code>". For example, to debug a remote Linux application, you should
				run <code>platform select remote-linux</code>.
				</p>

				<p>
				After selecting the platform plug-in, you should receive a prompt which confirms
				the selected platform, and states that you are not connected. This is because
				remote plug-ins need to be connected to their remote platform counterpart to
				operate. This is achieved using the <code>platform connect</code> command. This
				command takes a number of arguments (as always, use the <code>help</code> command
				to find out more), but normally you only need to specify the address to connect to,
				e.g.:
				</p>
				<code>platform connect connect://host:port</code>

				<p>
				After this, you should be able to debug normally. You can use the
				<code>process attach</code> to attach to an existing remote process or
				<code>target create</code>, <code>process launch</code> to start a new one. The
				platform plugin will transparently take care of uploading or downloading the
				executable in order to be able to debug. If your application needs additional
				files, you can transfer them using the platform commands: <code>get-file</code>,
				<code>put-file</code>, <code>mkdir</code>, etc. The environment can be prepared
				further using the <code>platform shell</code> command.
				</p>

				</div>
				<div class="postfooter"></div>
				</div>
				</div>
				</div>
				</div>
				</body>
				</html>

lldb/trunk/www/sidebar.incl

Show All 16 Lines	<div class="urbangreymenu">
<li><a href="/tutorial.html">Tutorial</a></li>		<li><a href="/tutorial.html">Tutorial</a></li>
<li><a href="/lldb-gdb.html">GDB and LLDB command examples</a></li>		<li><a href="/lldb-gdb.html">GDB and LLDB command examples</a></li>
<li><a href="/formats.html">Frame and Thread Formatting</a></li>		<li><a href="/formats.html">Frame and Thread Formatting</a></li>
<li><a href="/symbolication.html">Symbolication</a></li>		<li><a href="/symbolication.html">Symbolication</a></li>
<li><a href="/varformats.html">Variable Formatting</a></li>		<li><a href="/varformats.html">Variable Formatting</a></li>
<li><a href="/python-reference.html">Python Reference</a></li>		<li><a href="/python-reference.html">Python Reference</a></li>
<li><a href="/scripting.html">Python Example</a></li>		<li><a href="/scripting.html">Python Example</a></li>
<li><a href="/symbols.html">Symbols on Mac OS X</a></li>		<li><a href="/symbols.html">Symbols on Mac OS X</a></li>
		<li><a href="/remote.html">Remote debugging</a></li>
<li><a href="/troubleshooting.html">Troubleshooting</a></li>		<li><a href="/troubleshooting.html">Troubleshooting</a></li>
<li><a href="/architecture/index.html">Architecture</a></li>		<li><a href="/architecture/index.html">Architecture</a></li>
</ul>		</ul>
</div>		</div>
</div>		</div>
<div class="menu">		<div class="menu">
<div class="urbangreymenu">		<div class="urbangreymenu">
<h1 class="headerbar">Mailing Lists</h1>		<h1 class="headerbar">Mailing Lists</h1>
Show All 24 Lines