blob: 2ed3eb1d822b20cff5aae9c413d203a4de2ecf4e [file] [log] [blame]
Reid Kleckner22884dd2009-09-21 02:34:59 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
NAKAMURA Takumi5c6e4df2011-10-31 11:21:59 +00005 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Reid Kleckner22884dd2009-09-21 02:34:59 +00006 <title>Debugging JITed Code With GDB</title>
7 <link rel="stylesheet" href="llvm.css" type="text/css">
8</head>
9<body>
10
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000011<h1>Debugging JITed Code With GDB</h1>
Reid Kleckner22884dd2009-09-21 02:34:59 +000012<ol>
Reid Kleckner89472822010-07-07 20:16:45 +000013 <li><a href="#example">Example usage</a></li>
14 <li><a href="#background">Background</a></li>
Reid Kleckner22884dd2009-09-21 02:34:59 +000015</ol>
16<div class="doc_author">Written by Reid Kleckner</div>
17
18<!--=========================================================================-->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000019<h2><a name="example">Example usage</a></h2>
Reid Kleckner22884dd2009-09-21 02:34:59 +000020<!--=========================================================================-->
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +000021<div>
Reid Kleckner22884dd2009-09-21 02:34:59 +000022
Reid Kleckner89472822010-07-07 20:16:45 +000023<p>In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is
24available on most modern distributions of Linux. The version of GDB that Apple
25ships with XCode has been frozen at 6.3 for a while. LLDB may be a better
26option for debugging JITed code on Mac OS X.
Reid Kleckner22884dd2009-09-21 02:34:59 +000027</p>
28
Reid Kleckner89472822010-07-07 20:16:45 +000029<p>Consider debugging the following code compiled with clang and run through
30lli:
Reid Kleckner22884dd2009-09-21 02:34:59 +000031</p>
32
33<pre class="doc_code">
34#include &lt;stdio.h&gt;
35
36void foo() {
37 printf("%d\n", *(int*)NULL); // Crash here
38}
39
40void bar() {
41 foo();
42}
43
44void baz() {
45 bar();
46}
47
48int main(int argc, char **argv) {
49 baz();
50}
51</pre>
52
53<p>Here are the commands to run that application under GDB and print the stack
54trace at the crash:
55</p>
56
57<pre class="doc_code">
58# Compile foo.c to bitcode. You can use either clang or llvm-gcc with this
59# command line. Both require -fexceptions, or the calls are all marked
Reid Kleckner89472822010-07-07 20:16:45 +000060# 'nounwind' which disables DWARF exception handling info. Custom frontends
61# should avoid adding this attribute to JITed code, since it interferes with
62# DWARF CFA generation at the moment.
Reid Kleckner22884dd2009-09-21 02:34:59 +000063$ clang foo.c -fexceptions -emit-llvm -c -o foo.bc
64
65# Run foo.bc under lli with -jit-emit-debug. If you built lli in debug mode,
66# -jit-emit-debug defaults to true.
67$ $GDB_INSTALL/gdb --args lli -jit-emit-debug foo.bc
68...
69
70# Run the code.
71(gdb) run
72Starting program: /tmp/gdb/lli -jit-emit-debug foo.bc
73[Thread debugging using libthread_db enabled]
74
75Program received signal SIGSEGV, Segmentation fault.
760x00007ffff7f55164 in foo ()
77
78# Print the backtrace, this time with symbols instead of ??.
79(gdb) bt
80#0 0x00007ffff7f55164 in foo ()
81#1 0x00007ffff7f550f9 in bar ()
82#2 0x00007ffff7f55099 in baz ()
83#3 0x00007ffff7f5502a in main ()
84#4 0x00000000007c0225 in llvm::JIT::runFunction(llvm::Function*,
85 std::vector&lt;llvm::GenericValue,
Reid Kleckner89472822010-07-07 20:16:45 +000086 std::allocator&lt;llvm::GenericValue&gt; &gt; const&amp;) ()
Reid Kleckner22884dd2009-09-21 02:34:59 +000087#5 0x00000000007d6d98 in
88 llvm::ExecutionEngine::runFunctionAsMain(llvm::Function*,
89 std::vector&lt;std::string,
Reid Kleckner89472822010-07-07 20:16:45 +000090 std::allocator&lt;std::string&gt; &gt; const&amp;, char const* const*) ()
Reid Kleckner22884dd2009-09-21 02:34:59 +000091#6 0x00000000004dab76 in main ()
92</pre>
Reid Kleckner22884dd2009-09-21 02:34:59 +000093
94<p>As you can see, GDB can correctly unwind the stack and has the appropriate
95function names.
96</p>
Reid Kleckner89472822010-07-07 20:16:45 +000097</div>
98
99<!--=========================================================================-->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000100<h2><a name="background">Background</a></h2>
Reid Kleckner89472822010-07-07 20:16:45 +0000101<!--=========================================================================-->
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000102<div>
Reid Kleckner89472822010-07-07 20:16:45 +0000103
104<p>Without special runtime support, debugging dynamically generated code with
105GDB (as well as most debuggers) can be quite painful. Debuggers generally read
106debug information from the object file of the code, but for JITed code, there is
107no such file to look for.
108</p>
109
110<p>Depending on the architecture, this can impact the debugging experience in
111different ways. For example, on most 32-bit x86 architectures, you can simply
112compile with -fno-omit-frame-pointer for GCC and -disable-fp-elim for LLVM.
113When GDB creates a backtrace, it can properly unwind the stack, but the stack
114frames owned by JITed code have ??'s instead of the appropriate symbol name.
115However, on Linux x86_64 in particular, GDB relies on the DWARF call frame
116address (CFA) debug information to unwind the stack, so even if you compile
117your program to leave the frame pointer untouched, GDB will usually be unable
118to unwind the stack past any JITed code stack frames.
119</p>
120
121<p>In order to communicate the necessary debug info to GDB, an interface for
122registering JITed code with debuggers has been designed and implemented for
123GDB and LLVM. At a high level, whenever LLVM generates new machine code, it
124also generates an object file in memory containing the debug information. LLVM
125then adds the object file to the global list of object files and calls a special
126function (__jit_debug_register_code) marked noinline that GDB knows about. When
127GDB attaches to a process, it puts a breakpoint in this function and loads all
128of the object files in the global list. When LLVM calls the registration
129function, GDB catches the breakpoint signal, loads the new object file from
130LLVM's memory, and resumes the execution. In this way, GDB can get the
131necessary debug information.
132</p>
133
134<p>At the time of this writing, LLVM only supports architectures that use ELF
135object files and it only generates symbols and DWARF CFA information. However,
136it would be easy to add more information to the object file, so we don't need to
137coordinate with GDB to get better debug information.
138</p>
139</div>
Reid Kleckner22884dd2009-09-21 02:34:59 +0000140
141<!-- *********************************************************************** -->
142<hr>
143<address>
144 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
145 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
146 <a href="http://validator.w3.org/check/referer"><img
147 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
148 <a href="mailto:reid.kleckner@gmail.com">Reid Kleckner</a><br>
NAKAMURA Takumib9a33632011-04-09 02:13:37 +0000149 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Reid Kleckner89472822010-07-07 20:16:45 +0000150 Last modified: $Date$
Reid Kleckner22884dd2009-09-21 02:34:59 +0000151</address>
152</body>
153</html>