1======================================================= 2Kaleidoscope: Extending the Language: Debug Information 3======================================================= 4 5.. contents:: 6 :local: 7 8Chapter 8 Introduction 9====================== 10 11Welcome to Chapter 8 of the "`Implementing a language with 12LLVM <index.html>`_" tutorial. In chapters 1 through 7, we've built a 13decent little programming language with functions and variables. 14What happens if something goes wrong though, how do you debug your 15program? 16 17Source level debugging uses formatted data that helps a debugger 18translate from binary and the state of the machine back to the 19source that the programmer wrote. In LLVM we generally use a format 20called `DWARF <http://dwarfstd.org>`_. DWARF is a compact encoding 21that represents types, source locations, and variable locations. 22 23The short summary of this chapter is that we'll go through the 24various things you have to add to a programming language to 25support debug info, and how you translate that into DWARF. 26 27Caveat: For now we can't debug via the JIT, so we'll need to compile 28our program down to something small and standalone. As part of this 29we'll make a few modifications to the running of the language and 30how programs are compiled. This means that we'll have a source file 31with a simple program written in Kaleidoscope rather than the 32interactive JIT. It does involve a limitation that we can only 33have one "top level" command at a time to reduce the number of 34changes necessary. 35 36Here's the sample program we'll be compiling: 37 38.. code-block:: python 39 40 def fib(x) 41 if x < 3 then 42 1 43 else 44 fib(x-1)+fib(x-2); 45 46 fib(10) 47 48 49Why is this a hard problem? 50=========================== 51 52Debug information is a hard problem for a few different reasons - mostly 53centered around optimized code. First, optimization makes keeping source 54locations more difficult. In LLVM IR we keep the original source location 55for each IR level instruction on the instruction. Optimization passes 56should keep the source locations for newly created instructions, but merged 57instructions only get to keep a single location - this can cause jumping 58around when stepping through optimized programs. Secondly, optimization 59can move variables in ways that are either optimized out, shared in memory 60with other variables, or difficult to track. For the purposes of this 61tutorial we're going to avoid optimization (as you'll see with one of the 62next sets of patches). 63 64Ahead-of-Time Compilation Mode 65============================== 66 67To highlight only the aspects of adding debug information to a source 68language without needing to worry about the complexities of JIT debugging 69we're going to make a few changes to Kaleidoscope to support compiling 70the IR emitted by the front end into a simple standalone program that 71you can execute, debug, and see results. 72 73First we make our anonymous function that contains our top level 74statement be our "main": 75 76.. code-block:: udiff 77 78 - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); 79 + PrototypeAST *Proto = new PrototypeAST("main", std::vector<std::string>()); 80 81just with the simple change of giving it a name. 82 83Then we're going to remove the command line code wherever it exists: 84 85.. code-block:: udiff 86 87 @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() { 88 /// top ::= definition | external | expression | ';' 89 static void MainLoop() { 90 while (1) { 91 - fprintf(stderr, "ready> "); 92 switch (CurTok) { 93 case tok_eof: 94 return; 95 @@ -1184,7 +1183,6 @@ int main() { 96 BinopPrecedence['*'] = 40; // highest. 97 98 // Prime the first token. 99 - fprintf(stderr, "ready> "); 100 getNextToken(); 101 102Lastly we're going to disable all of the optimization passes and the JIT so 103that the only thing that happens after we're done parsing and generating 104code is that the llvm IR goes to standard error: 105 106.. code-block:: udiff 107 108 @@ -1108,17 +1108,8 @@ static void HandleExtern() { 109 static void HandleTopLevelExpression() { 110 // Evaluate a top-level expression into an anonymous function. 111 if (FunctionAST *F = ParseTopLevelExpr()) { 112 - if (Function *LF = F->Codegen()) { 113 - // We're just doing this to make sure it executes. 114 - TheExecutionEngine->finalizeObject(); 115 - // JIT the function, returning a function pointer. 116 - void *FPtr = TheExecutionEngine->getPointerToFunction(LF); 117 - 118 - // Cast it to the right type (takes no arguments, returns a double) so we 119 - // can call it as a native function. 120 - double (*FP)() = (double (*)())(intptr_t)FPtr; 121 - // Ignore the return value for this. 122 - (void)FP; 123 + if (!F->Codegen()) { 124 + fprintf(stderr, "Error generating code for top level expr"); 125 } 126 } else { 127 // Skip token for error recovery. 128 @@ -1439,11 +1459,11 @@ int main() { 129 // target lays out data structures. 130 TheModule->setDataLayout(TheExecutionEngine->getDataLayout()); 131 OurFPM.add(new DataLayoutPass()); 132 +#if 0 133 OurFPM.add(createBasicAliasAnalysisPass()); 134 // Promote allocas to registers. 135 OurFPM.add(createPromoteMemoryToRegisterPass()); 136 @@ -1218,7 +1210,7 @@ int main() { 137 OurFPM.add(createGVNPass()); 138 // Simplify the control flow graph (deleting unreachable blocks, etc). 139 OurFPM.add(createCFGSimplificationPass()); 140 - 141 + #endif 142 OurFPM.doInitialization(); 143 144 // Set the global so the code gen can use this. 145 146This relatively small set of changes get us to the point that we can compile 147our piece of Kaleidoscope language down to an executable program via this 148command line: 149 150.. code-block:: bash 151 152 Kaleidoscope-Ch8 < fib.ks | & clang -x ir - 153 154which gives an a.out/a.exe in the current working directory. 155 156Compile Unit 157============ 158 159The top level container for a section of code in DWARF is a compile unit. 160This contains the type and function data for an individual translation unit 161(read: one file of source code). So the first thing we need to do is 162construct one for our fib.ks file. 163 164DWARF Emission Setup 165==================== 166 167Similar to the ``IRBuilder`` class we have a 168```DIBuilder`` <http://llvm.org/doxygen/classllvm_1_1DIBuilder.html>`_ class 169that helps in constructing debug metadata for an llvm IR file. It 170corresponds 1:1 similarly to ``IRBuilder`` and llvm IR, but with nicer names. 171Using it does require that you be more familiar with DWARF terminology than 172you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you 173read through the general documentation on the 174```Metadata Format`` <http://llvm.org/docs/SourceLevelDebugging.html>`_ it 175should be a little more clear. We'll be using this class to construct all 176of our IR level descriptions. Construction for it takes a module so we 177need to construct it shortly after we construct our module. We've left it 178as a global static variable to make it a bit easier to use. 179 180Next we're going to create a small container to cache some of our frequent 181data. The first will be our compile unit, but we'll also write a bit of 182code for our one type since we won't have to worry about multiple typed 183expressions: 184 185.. code-block:: c++ 186 187 static DIBuilder *DBuilder; 188 189 struct DebugInfo { 190 DICompileUnit TheCU; 191 DIType DblTy; 192 193 DIType getDoubleTy(); 194 } KSDbgInfo; 195 196 DIType DebugInfo::getDoubleTy() { 197 if (DblTy.isValid()) 198 return DblTy; 199 200 DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float); 201 return DblTy; 202 } 203 204And then later on in ``main`` when we're constructing our module: 205 206.. code-block:: c++ 207 208 DBuilder = new DIBuilder(*TheModule); 209 210 KSDbgInfo.TheCU = DBuilder->createCompileUnit( 211 dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0); 212 213There are a couple of things to note here. First, while we're producing a 214compile unit for a language called Kaleidoscope we used the language 215constant for C. This is because a debugger wouldn't necessarily understand 216the calling conventions or default ABI for a language it doesn't recognize 217and we follow the C ABI in our llvm code generation so it's the closest 218thing to accurate. This ensures we can actually call functions from the 219debugger and have them execute. Secondly, you'll see the "fib.ks" in the 220call to ``createCompileUnit``. This is a default hard coded value since 221we're using shell redirection to put our source into the Kaleidoscope 222compiler. In a usual front end you'd have an input file name and it would 223go there. 224 225One last thing as part of emitting debug information via DIBuilder is that 226we need to "finalize" the debug information. The reasons are part of the 227underlying API for DIBuilder, but make sure you do this near the end of 228main: 229 230.. code-block:: c++ 231 232 DBuilder->finalize(); 233 234before you dump out the module. 235 236Functions 237========= 238 239Now that we have our ``Compile Unit`` and our source locations, we can add 240function definitions to the debug info. So in ``PrototypeAST::Codegen`` we 241add a few lines of code to describe a context for our subprogram, in this 242case the "File", and the actual definition of the function itself. 243 244So the context: 245 246.. code-block:: c++ 247 248 DIFile Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(), 249 KSDbgInfo.TheCU.getDirectory()); 250 251giving us a DIFile and asking the ``Compile Unit`` we created above for the 252directory and filename where we are currently. Then, for now, we use some 253source locations of 0 (since our AST doesn't currently have source location 254information) and construct our function definition: 255 256.. code-block:: c++ 257 258 DIDescriptor FContext(Unit); 259 unsigned LineNo = 0; 260 unsigned ScopeLine = 0; 261 DISubprogram SP = DBuilder->createFunction( 262 FContext, Name, StringRef(), Unit, LineNo, 263 CreateFunctionType(Args.size(), Unit), false /* internal linkage */, 264 true /* definition */, ScopeLine, DIDescriptor::FlagPrototyped, false, F); 265 266and we now have a DISubprogram that contains a reference to all of our metadata 267for the function. 268 269Source Locations 270================ 271 272The most important thing for debug information is accurate source location - 273this makes it possible to map your source code back. We have a problem though, 274Kaleidoscope really doesn't have any source location information in the lexer 275or parser so we'll need to add it. 276 277.. code-block:: c++ 278 279 struct SourceLocation { 280 int Line; 281 int Col; 282 }; 283 static SourceLocation CurLoc; 284 static SourceLocation LexLoc = {1, 0}; 285 286 static int advance() { 287 int LastChar = getchar(); 288 289 if (LastChar == '\n' || LastChar == '\r') { 290 LexLoc.Line++; 291 LexLoc.Col = 0; 292 } else 293 LexLoc.Col++; 294 return LastChar; 295 } 296 297In this set of code we've added some functionality on how to keep track of the 298line and column of the "source file". As we lex every token we set our current 299current "lexical location" to the assorted line and column for the beginning 300of the token. We do this by overriding all of the previous calls to 301``getchar()`` with our new ``advance()`` that keeps track of the information 302and then we have added to all of our AST classes a source location: 303 304.. code-block:: c++ 305 306 class ExprAST { 307 SourceLocation Loc; 308 309 public: 310 int getLine() const { return Loc.Line; } 311 int getCol() const { return Loc.Col; } 312 ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {} 313 virtual std::ostream &dump(std::ostream &out, int ind) { 314 return out << ':' << getLine() << ':' << getCol() << '\n'; 315 } 316 317that we pass down through when we create a new expression: 318 319.. code-block:: c++ 320 321 LHS = new BinaryExprAST(BinLoc, BinOp, LHS, RHS); 322 323giving us locations for each of our expressions and variables. 324 325From this we can make sure to tell ``DIBuilder`` when we're at a new source 326location so it can use that when we generate the rest of our code and make 327sure that each instruction has source location information. We do this 328by constructing another small function: 329 330.. code-block:: c++ 331 332 void DebugInfo::emitLocation(ExprAST *AST) { 333 DIScope *Scope; 334 if (LexicalBlocks.empty()) 335 Scope = &TheCU; 336 else 337 Scope = LexicalBlocks.back(); 338 Builder.SetCurrentDebugLocation( 339 DebugLoc::get(AST->getLine(), AST->getCol(), DIScope(*Scope))); 340 } 341 342that both tells the main ``IRBuilder`` where we are, but also what scope 343we're in. Since we've just created a function above we can either be in 344the main file scope (like when we created our function), or now we can be 345in the function scope we just created. To represent this we create a stack 346of scopes: 347 348.. code-block:: c++ 349 350 std::vector<DIScope *> LexicalBlocks; 351 std::map<const PrototypeAST *, DIScope> FnScopeMap; 352 353and keep a map of each function to the scope that it represents (a DISubprogram 354is also a DIScope). 355 356Then we make sure to: 357 358.. code-block:: c++ 359 360 KSDbgInfo.emitLocation(this); 361 362emit the location every time we start to generate code for a new AST, and 363also: 364 365.. code-block:: c++ 366 367 KSDbgInfo.FnScopeMap[this] = SP; 368 369store the scope (function) when we create it and use it: 370 371 KSDbgInfo.LexicalBlocks.push_back(&KSDbgInfo.FnScopeMap[Proto]); 372 373when we start generating the code for each function. 374 375also, don't forget to pop the scope back off of your scope stack at the 376end of the code generation for the function: 377 378.. code-block:: c++ 379 380 // Pop off the lexical block for the function since we added it 381 // unconditionally. 382 KSDbgInfo.LexicalBlocks.pop_back(); 383 384Variables 385========= 386 387Now that we have functions, we need to be able to print out the variables 388we have in scope. Let's get our function arguments set up so we can get 389decent backtraces and see how our functions are being called. It isn't 390a lot of code, and we generally handle it when we're creating the 391argument allocas in ``PrototypeAST::CreateArgumentAllocas``. 392 393.. code-block:: c++ 394 395 DIScope *Scope = KSDbgInfo.LexicalBlocks.back(); 396 DIFile Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(), 397 KSDbgInfo.TheCU.getDirectory()); 398 DIVariable D = DBuilder->createLocalVariable(dwarf::DW_TAG_arg_variable, 399 *Scope, Args[Idx], Unit, Line, 400 KSDbgInfo.getDoubleTy(), Idx); 401 402 Instruction *Call = DBuilder->insertDeclare( 403 Alloca, D, DBuilder->createExpression(), Builder.GetInsertBlock()); 404 Call->setDebugLoc(DebugLoc::get(Line, 0, *Scope)); 405 406Here we're doing a few things. First, we're grabbing our current scope 407for the variable so we can say what range of code our variable is valid 408through. Second, we're creating the variable, giving it the scope, 409the name, source location, type, and since it's an argument, the argument 410index. Third, we create an ``lvm.dbg.declare`` call to indicate at the IR 411level that we've got a variable in an alloca (and it gives a starting 412location for the variable). Lastly, we set a source location for the 413beginning of the scope on the declare. 414 415One interesting thing to note at this point is that various debuggers have 416assumptions based on how code and debug information was generated for them 417in the past. In this case we need to do a little bit of a hack to avoid 418generating line information for the function prologue so that the debugger 419knows to skip over those instructions when setting a breakpoint. So in 420``FunctionAST::CodeGen`` we add a couple of lines: 421 422.. code-block:: c++ 423 424 // Unset the location for the prologue emission (leading instructions with no 425 // location in a function are considered part of the prologue and the debugger 426 // will run past them when breaking on a function) 427 KSDbgInfo.emitLocation(nullptr); 428 429and then emit a new location when we actually start generating code for the 430body of the function: 431 432.. code-block:: c++ 433 434 KSDbgInfo.emitLocation(Body); 435 436With this we have enough debug information to set breakpoints in functions, 437print out argument variables, and call functions. Not too bad for just a 438few simple lines of code! 439 440Full Code Listing 441================= 442 443Here is the complete code listing for our running example, enhanced with 444debug information. To build this example, use: 445 446.. code-block:: bash 447 448 # Compile 449 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy 450 # Run 451 ./toy 452 453Here is the code: 454 455.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp 456 :language: c++ 457 458`Next: Conclusion and other useful LLVM tidbits <LangImpl9.html>`_ 459 460