Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / c500566d9fb70472a17f62b4cf1689062c52e095 / . / docs / DebuggingJITedCode.html
blob: 92570f454c9298884322b5b74608cc9ba608700e [file] [log] [blame]
Reid Kleckner22884dd2009-09-21 02:34:59 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>Debugging JITed Code With GDB</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
10<div class="doc_title">Debugging JITed Code With GDB</div>
11<ol>
12 <li><a href="#introduction">Introduction</a></li>
13 <li><a href="#quickstart">Quickstart</a></li>
14 <li><a href="#example">Example with clang and lli</a></li>
15</ol>
16<div class="doc_author">Written by Reid Kleckner</div>
17
18<!--=========================================================================-->
19<div class="doc_section"><a name="introduction">Introduction</a></div>
20<!--=========================================================================-->
21<div class="doc_text">
22
23<p>Without special runtime support, debugging dynamically generated code with
24GDB (as well as most debuggers) can be quite painful. Debuggers generally read
25debug information from the object file of the code, but for JITed code, there is
26no such file to look for.
27</p>
28
29<p>Depending on the architecture, this can impact the debugging experience in
30different ways. For example, on most 32-bit x86 architectures, you can simply
31compile with -fno-omit-framepointer for GCC and -fdisable-fp-elim for LLVM.
32When GDB creates a backtrace, it can properly unwind the stack, but the stack
33frames owned by JITed code have ??'s instead of the appropriate symbol name.
34However, on Linux x86_64 in particular, GDB relies on the DWARF CFA debug
35information to unwind the stack, so even if you compile your program to leave
36the frame pointer untouched, GDB will usually be unable to unwind the stack past
37any JITed code stack frames.
38</p>
39
40<p>In order to communicate the necessary debug info to GDB, an interface for
41registering JITed code with debuggers has been designed and implemented for
42GDB and LLVM. At a high level, whenever LLVM generates new machine code, it
43also generates an object file in memory containing the debug information. LLVM
44then adds the object file to the global list of object files and calls a special
45function (__jit_debug_register_code) marked noinline that GDB knows about. When
46GDB attaches to a process, it puts a breakpoint in this function and loads all
47of the object files in the global list. When LLVM calls the registration
48function, GDB catches the breakpoint signal, loads the new object file from
49LLVM's memory, and resumes the execution. In this way, GDB can get the
50necessary debug information.
51</p>
52
53<p>At the time of this writing, LLVM only supports architectures that use ELF
54object files and it only generates symbols and DWARF CFA information. However,
55it would be easy to add more information to the object file, so we don't need to
56coordinate with GDB to get better debug information.
57</p>
58</div>
59
60<!--=========================================================================-->
61<div class="doc_section"><a name="quickstart">Quickstart</a></div>
62<!--=========================================================================-->
63<div class="doc_text">
64
65<p>In order to debug code JITed by LLVM, you need to install a recent version
66of GDB. The interface was added on 2009-08-19, so you need a snapshot of GDB
67more recent than that. Either download a snapshot of GDB or checkout CVS as
68instructed <a href="http://www.gnu.org/software/gdb/current/">here</a>. Here
69are the commands for doing a checkout and building the code:
70</p>
71
72<pre class="doc_code">
73$ cvs -z 3 -d :pserver:anoncvs@sourceware.org:/cvs/src co gdb
74$ mv src gdb # You probably don't want this checkout called "src".
75$ cd gdb
76$ ./configure --prefix="$GDB_INSTALL"
77$ make
78$ make install
79</pre>
80
81<p>You can then use -jit-emit-debug in the LLVM command line arguments to enable
82the interface.
83</p>
84</div>
85
86<!--=========================================================================-->
87<div class="doc_section"><a name="example">Example with clang and lli</a></div>
88<!--=========================================================================-->
89<div class="doc_text">
90
91<p>For example, consider debugging running lli on the following C code in
92foo.c:
93</p>
94
95<pre class="doc_code">
96#include &lt;stdio.h&gt;
97
98void foo() {
99 printf("%d\n", *(int*)NULL); // Crash here
100}
101
102void bar() {
103 foo();
104}
105
106void baz() {
107 bar();
108}
109
110int main(int argc, char **argv) {
111 baz();
112}
113</pre>
114
115<p>Here are the commands to run that application under GDB and print the stack
116trace at the crash:
117</p>
118
119<pre class="doc_code">
120# Compile foo.c to bitcode. You can use either clang or llvm-gcc with this
121# command line. Both require -fexceptions, or the calls are all marked
122# 'nounwind' which disables DWARF CFA info.
123$ clang foo.c -fexceptions -emit-llvm -c -o foo.bc
124
125# Run foo.bc under lli with -jit-emit-debug. If you built lli in debug mode,
126# -jit-emit-debug defaults to true.
127$ $GDB_INSTALL/gdb --args lli -jit-emit-debug foo.bc
128...
129
130# Run the code.
131(gdb) run
132Starting program: /tmp/gdb/lli -jit-emit-debug foo.bc
133[Thread debugging using libthread_db enabled]
134
135Program received signal SIGSEGV, Segmentation fault.
1360x00007ffff7f55164 in foo ()
137
138# Print the backtrace, this time with symbols instead of ??.
139(gdb) bt
140#0 0x00007ffff7f55164 in foo ()
141#1 0x00007ffff7f550f9 in bar ()
142#2 0x00007ffff7f55099 in baz ()
143#3 0x00007ffff7f5502a in main ()
144#4 0x00000000007c0225 in llvm::JIT::runFunction(llvm::Function*,
145 std::vector&lt;llvm::GenericValue,
146 std::allocator&lt;llvm::GenericValue&gt; &gt; const&) ()
147#5 0x00000000007d6d98 in
148 llvm::ExecutionEngine::runFunctionAsMain(llvm::Function*,
149 std::vector&lt;std::string,
150 std::allocator&lt;std::string&gt; &gt; const&, char const* const*) ()
151#6 0x00000000004dab76 in main ()
152</pre>
153</div>
154
155<p>As you can see, GDB can correctly unwind the stack and has the appropriate
156function names.
157</p>
158
159<!-- *********************************************************************** -->
160<hr>
161<address>
162 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
163 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
164 <a href="http://validator.w3.org/check/referer"><img
165 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
166 <a href="mailto:reid.kleckner@gmail.com">Reid Kleckner</a><br>
167 <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
168 Last modified: $Date: 2009-01-01 23:10:51 -0800 (Thu, 01 Jan 2009) $
169</address>
170</body>
171</html>