Home | History | Annotate | Download | only in docs
      1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
      2                       "http://www.w3.org/TR/html4/strict.dtd">
      3 <html>
      4 <head>
      5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
      6   <title>Debugging JITed Code With GDB</title>
      7   <link rel="stylesheet" href="llvm.css" type="text/css">
      8 </head>
      9 <body>
     10 
     11 <h1>Debugging JITed Code With GDB</h1>
     12 <ol>
     13   <li><a href="#example">Example usage</a></li>
     14   <li><a href="#background">Background</a></li>
     15 </ol>
     16 <div class="doc_author">Written by Reid Kleckner</div>
     17 
     18 <!--=========================================================================-->
     19 <h2><a name="example">Example usage</a></h2>
     20 <!--=========================================================================-->
     21 <div>
     22 
     23 <p>In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is
     24 available on most modern distributions of Linux.  The version of GDB that Apple
     25 ships with XCode has been frozen at 6.3 for a while.  LLDB may be a better
     26 option for debugging JITed code on Mac OS X.
     27 </p>
     28 
     29 <p>Consider debugging the following code compiled with clang and run through
     30 lli:
     31 </p>
     32 
     33 <pre class="doc_code">
     34 #include &lt;stdio.h&gt;
     35 
     36 void foo() {
     37     printf("%d\n", *(int*)NULL);  // Crash here
     38 }
     39 
     40 void bar() {
     41     foo();
     42 }
     43 
     44 void baz() {
     45     bar();
     46 }
     47 
     48 int 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
     54 trace 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
     60 # '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.
     63 $ 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
     72 Starting program: /tmp/gdb/lli -jit-emit-debug foo.bc
     73 [Thread debugging using libthread_db enabled]
     74 
     75 Program received signal SIGSEGV, Segmentation fault.
     76 0x00007ffff7f55164 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,
     86     std::allocator&lt;llvm::GenericValue&gt; &gt; const&amp;) ()
     87 #5  0x00000000007d6d98 in
     88     llvm::ExecutionEngine::runFunctionAsMain(llvm::Function*,
     89     std::vector&lt;std::string,
     90     std::allocator&lt;std::string&gt; &gt; const&amp;, char const* const*) ()
     91 #6  0x00000000004dab76 in main ()
     92 </pre>
     93 
     94 <p>As you can see, GDB can correctly unwind the stack and has the appropriate
     95 function names.
     96 </p>
     97 </div>
     98 
     99 <!--=========================================================================-->
    100 <h2><a name="background">Background</a></h2>
    101 <!--=========================================================================-->
    102 <div>
    103 
    104 <p>Without special runtime support, debugging dynamically generated code with
    105 GDB (as well as most debuggers) can be quite painful.  Debuggers generally read
    106 debug information from the object file of the code, but for JITed code, there is
    107 no such file to look for.
    108 </p>
    109 
    110 <p>Depending on the architecture, this can impact the debugging experience in
    111 different ways.  For example, on most 32-bit x86 architectures, you can simply
    112 compile with -fno-omit-frame-pointer for GCC and -disable-fp-elim for LLVM.
    113 When GDB creates a backtrace, it can properly unwind the stack, but the stack
    114 frames owned by JITed code have ??'s instead of the appropriate symbol name.
    115 However, on Linux x86_64 in particular, GDB relies on the DWARF call frame
    116 address (CFA) debug information to unwind the stack, so even if you compile
    117 your program to leave the frame pointer untouched, GDB will usually be unable
    118 to 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
    122 registering JITed code with debuggers has been designed and implemented for
    123 GDB and LLVM.  At a high level, whenever LLVM generates new machine code, it
    124 also generates an object file in memory containing the debug information.  LLVM
    125 then adds the object file to the global list of object files and calls a special
    126 function (__jit_debug_register_code) marked noinline that GDB knows about.  When
    127 GDB attaches to a process, it puts a breakpoint in this function and loads all
    128 of the object files in the global list.  When LLVM calls the registration
    129 function, GDB catches the breakpoint signal, loads the new object file from
    130 LLVM's memory, and resumes the execution.  In this way, GDB can get the
    131 necessary debug information.
    132 </p>
    133 
    134 <p>At the time of this writing, LLVM only supports architectures that use ELF
    135 object files and it only generates symbols and DWARF CFA information.  However,
    136 it would be easy to add more information to the object file, so we don't need to
    137 coordinate with GDB to get better debug information.
    138 </p>
    139 </div>
    140 
    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 (a] gmail.com">Reid Kleckner</a><br>
    149   <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
    150   Last modified: $Date$
    151 </address>
    152 </body>
    153 </html>
    154