Author: labath Date: Wed Apr 8 02:54:31 2015 New Revision: 234395 URL: http://llvm.org/viewvc/llvm-project?rev=234395&view=rev Log: Add documentation about remote debugging to the website
Reviewers: tberghammer, clayborg Subscribers: tberghammer, lldb-commits Differential Revision: http://reviews.llvm.org/D8871 Added: lldb/trunk/www/remote.html Modified: lldb/trunk/www/build.html lldb/trunk/www/sidebar.incl Modified: lldb/trunk/www/build.html URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/build.html?rev=234395&r1=234394&r2=234395&view=diff ============================================================================== --- lldb/trunk/www/build.html (original) +++ lldb/trunk/www/build.html Wed Apr 8 02:54:31 2015 @@ -426,7 +426,7 @@ </p> <code>> python -c 'import lldb'</code></p> - <h2>Cross-compiling LLDB</h2> + <h2 id="cross-compilation">Cross-compiling LLDB</h2> <p> 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 Added: lldb/trunk/www/remote.html URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/remote.html?rev=234395&view=auto ============================================================================== --- lldb/trunk/www/remote.html (added) +++ lldb/trunk/www/remote.html Wed Apr 8 02:54:31 2015 @@ -0,0 +1,145 @@ +<!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> Modified: lldb/trunk/www/sidebar.incl URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=234395&r1=234394&r2=234395&view=diff ============================================================================== --- lldb/trunk/www/sidebar.incl (original) +++ lldb/trunk/www/sidebar.incl Wed Apr 8 02:54:31 2015 @@ -22,6 +22,7 @@ <li><a href="/python-reference.html">Python Reference</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="/remote.html">Remote debugging</a></li> <li><a href="/troubleshooting.html">Troubleshooting</a></li> <li><a href="/architecture/index.html">Architecture</a></li> </ul> _______________________________________________ lldb-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits
