469 lines · plain
1======================================2Kaleidoscope: Adding Debug Information3======================================4 5.. contents::6 :local:7 8Chapter 9 Introduction9======================10 11Welcome to Chapter 9 of the "`Implementing a language with12LLVM <index.html>`_" tutorial. In chapters 1 through 8, we've built a13decent little programming language with functions and variables.14What happens if something goes wrong though, how do you debug your15program?16 17Source level debugging uses formatted data that helps a debugger18translate from binary and the state of the machine back to the19source that the programmer wrote. In LLVM we generally use a format20called `DWARF <http://dwarfstd.org>`_. DWARF is a compact encoding21that represents types, source locations, and variable locations.22 23The short summary of this chapter is that we'll go through the24various things you have to add to a programming language to25support 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 compile28our program down to something small and standalone. As part of this29we'll make a few modifications to the running of the language and30how programs are compiled. This means that we'll have a source file31with a simple program written in Kaleidoscope rather than the32interactive JIT. It does involve a limitation that we can only33have one "top level" command at a time to reduce the number of34changes necessary.35 36Here's the sample program we'll be compiling:37 38.. code-block:: python39 40 def fib(x)41 if x < 3 then42 143 else44 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 - mostly53centered around optimized code. First, optimization makes keeping source54locations more difficult. In LLVM IR we keep the original source location55for each IR level instruction on the instruction. Optimization passes56should keep the source locations for newly created instructions, but merged57instructions only get to keep a single location - this can cause jumping58around when stepping through optimized programs. Secondly, optimization59can move variables in ways that are either optimized out, shared in memory60with other variables, or difficult to track. For the purposes of this61tutorial we're going to avoid optimization (as you'll see with one of the62next sets of patches).63 64Ahead-of-Time Compilation Mode65==============================66 67To highlight only the aspects of adding debug information to a source68language without needing to worry about the complexities of JIT debugging69we're going to make a few changes to Kaleidoscope to support compiling70the IR emitted by the front end into a simple standalone program that71you can execute, debug, and see results.72 73First we make our anonymous function that contains our top level74statement be our "main":75 76.. code-block:: udiff77 78 - auto Proto = std::make_unique<PrototypeAST>("", std::vector<std::string>());79 + auto Proto = std::make_unique<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:: udiff86 87 @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() {88 /// top ::= definition | external | expression | ';'89 static void MainLoop() {90 while (true) {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 so103that the only thing that happens after we're done parsing and generating104code is that the LLVM IR goes to standard error:105 106.. code-block:: udiff107 108 @@ -1108,17 +1108,8 @@ static void HandleExtern() {109 static void HandleTopLevelExpression() {110 // Evaluate a top-level expression into an anonymous function.111 if (auto FnAST = ParseTopLevelExpr()) {112 - if (auto *FnIR = FnAST->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(FnIR);117 -118 - // Cast it to the right type (takes no arguments, returns a double) so we119 - // 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 (!FnAST->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 0133 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 + #endif142 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 compile147our piece of Kaleidoscope language down to an executable program via this148command line:149 150.. code-block:: bash151 152 Kaleidoscope-Ch9 < fib.ks | & clang -x ir -153 154which gives an a.out/a.exe in the current working directory.155 156Compile Unit157============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 unit161(read: one file of source code). So the first thing we need to do is162construct one for our fib.ks file.163 164DWARF Emission Setup165====================166 167Similar to the ``IRBuilder`` class we have a168`DIBuilder <https://llvm.org/doxygen/classllvm_1_1DIBuilder.html>`_ class169that helps in constructing debug metadata for an LLVM IR file. It170corresponds 1:1 similarly to ``IRBuilder`` and LLVM IR, but with nicer names.171Using it does require that you be more familiar with DWARF terminology than172you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you173read through the general documentation on the174`Metadata Format <https://llvm.org/docs/SourceLevelDebugging.html>`_ it175should be a little more clear. We'll be using this class to construct all176of our IR level descriptions. Construction for it takes a module so we177need to construct it shortly after we construct our module. We've left it178as 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 frequent181data. The first will be our compile unit, but we'll also write a bit of182code for our one type since we won't have to worry about multiple typed183expressions:184 185.. code-block:: c++186 187 static std::unique_ptr<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)198 return DblTy;199 200 DblTy = DBuilder->createBasicType("double", 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 = std::make_unique<DIBuilder>(*TheModule);209 210 KSDbgInfo.TheCU = DBuilder->createCompileUnit(211 dwarf::DW_LANG_C, DBuilder->createFile("fib.ks", "."),212 "Kaleidoscope Compiler", false, "", 0);213 214There are a couple of things to note here. First, while we're producing a215compile unit for a language called Kaleidoscope we used the language216constant for C. This is because a debugger wouldn't necessarily understand217the calling conventions or default ABI for a language it doesn't recognize218and we follow the C ABI in our LLVM code generation so it's the closest219thing to accurate. This ensures we can actually call functions from the220debugger and have them execute. Secondly, you'll see the "fib.ks" in the221call to ``createCompileUnit``. This is a default hard coded value since222we're using shell redirection to put our source into the Kaleidoscope223compiler. In a usual front end you'd have an input file name and it would224go there.225 226One last thing as part of emitting debug information via DIBuilder is that227we need to "finalize" the debug information. The reasons are part of the228underlying API for DIBuilder, but make sure you do this near the end of229main:230 231.. code-block:: c++232 233 DBuilder->finalize();234 235before you dump out the module.236 237Functions238=========239 240Now that we have our ``Compile Unit`` and our source locations, we can add241function definitions to the debug info. So in ``FunctionAST::codegen()`` we242add a few lines of code to describe a context for our subprogram, in this243case the "File", and the actual definition of the function itself.244 245So the context:246 247.. code-block:: c++248 249 DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU->getFilename(),250 KSDbgInfo.TheCU->getDirectory());251 252giving us an DIFile and asking the ``Compile Unit`` we created above for the253directory and filename where we are currently. Then, for now, we use some254source locations of 0 (since our AST doesn't currently have source location255information) and construct our function definition:256 257.. code-block:: c++258 259 DIScope *FContext = Unit;260 unsigned LineNo = 0;261 unsigned ScopeLine = 0;262 DISubprogram *SP = DBuilder->createFunction(263 FContext, P.getName(), StringRef(), Unit, LineNo,264 CreateFunctionType(TheFunction->arg_size()),265 ScopeLine,266 DINode::FlagPrototyped,267 DISubprogram::SPFlagDefinition);268 TheFunction->setSubprogram(SP);269 270and we now have an DISubprogram that contains a reference to all of our271metadata for the function.272 273Source Locations274================275 276The most important thing for debug information is accurate source location -277this makes it possible to map your source code back. We have a problem though,278Kaleidoscope really doesn't have any source location information in the lexer279or parser so we'll need to add it.280 281.. code-block:: c++282 283 struct SourceLocation {284 int Line;285 int Col;286 };287 static SourceLocation CurLoc;288 static SourceLocation LexLoc = {1, 0};289 290 static int advance() {291 int LastChar = getchar();292 293 if (LastChar == '\n' || LastChar == '\r') {294 LexLoc.Line++;295 LexLoc.Col = 0;296 } else297 LexLoc.Col++;298 return LastChar;299 }300 301In this set of code we've added some functionality on how to keep track of the302line and column of the "source file". As we lex every token we set our303current "lexical location" to the assorted line and column for the beginning304of the token. We do this by overriding all of the previous calls to305``getchar()`` with our new ``advance()`` that keeps track of the information306and then we have added to all of our AST classes a source location:307 308.. code-block:: c++309 310 class ExprAST {311 SourceLocation Loc;312 313 public:314 ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}315 virtual ~ExprAST() {}316 virtual Value* codegen() = 0;317 int getLine() const { return Loc.Line; }318 int getCol() const { return Loc.Col; }319 virtual raw_ostream &dump(raw_ostream &out, int ind) {320 return out << ':' << getLine() << ':' << getCol() << '\n';321 }322 323that we pass down through when we create a new expression:324 325.. code-block:: c++326 327 LHS = std::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),328 std::move(RHS));329 330giving us locations for each of our expressions and variables.331 332To make sure that every instruction gets proper source location information,333we have to tell ``Builder`` whenever we're at a new source location.334We use a small helper function for this:335 336.. code-block:: c++337 338 void DebugInfo::emitLocation(ExprAST *AST) {339 if (!AST)340 return Builder->SetCurrentDebugLocation(DebugLoc());341 DIScope *Scope;342 if (LexicalBlocks.empty())343 Scope = TheCU;344 else345 Scope = LexicalBlocks.back();346 Builder->SetCurrentDebugLocation(347 DILocation::get(Scope->getContext(), AST->getLine(), AST->getCol(), Scope));348 }349 350This both tells the main ``IRBuilder`` where we are, but also what scope351we're in. The scope can either be on compile-unit level or be the nearest352enclosing lexical block like the current function.353To represent this we create a stack of scopes in ``DebugInfo``:354 355.. code-block:: c++356 357 std::vector<DIScope *> LexicalBlocks;358 359and push the scope (function) to the top of the stack when we start360generating the code for each function:361 362.. code-block:: c++363 364 KSDbgInfo.LexicalBlocks.push_back(SP);365 366Also, we may not forget to pop the scope back off of the scope stack at the367end of the code generation for the function:368 369.. code-block:: c++370 371 // Pop off the lexical block for the function since we added it372 // unconditionally.373 KSDbgInfo.LexicalBlocks.pop_back();374 375Then we make sure to emit the location every time we start to generate code376for a new AST object:377 378.. code-block:: c++379 380 KSDbgInfo.emitLocation(this);381 382Variables383=========384 385Now that we have functions, we need to be able to print out the variables386we have in scope. Let's get our function arguments set up so we can get387decent backtraces and see how our functions are being called. It isn't388a lot of code, and we generally handle it when we're creating the389argument allocas in ``FunctionAST::codegen``.390 391.. code-block:: c++392 393 // Record the function arguments in the NamedValues map.394 NamedValues.clear();395 unsigned ArgIdx = 0;396 for (auto &Arg : TheFunction->args()) {397 // Create an alloca for this variable.398 AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());399 400 // Create a debug descriptor for the variable.401 DILocalVariable *D = DBuilder->createParameterVariable(402 SP, Arg.getName(), ++ArgIdx, Unit, LineNo, KSDbgInfo.getDoubleTy(),403 true);404 405 DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),406 DILocation::get(SP->getContext(), LineNo, 0, SP),407 Builder->GetInsertBlock());408 409 // Store the initial value into the alloca.410 Builder->CreateStore(&Arg, Alloca);411 412 // Add arguments to variable symbol table.413 NamedValues[std::string(Arg.getName())] = Alloca;414 }415 416 417Here we're first creating the variable, giving it the scope (``SP``),418the name, source location, type, and since it's an argument, the argument419index. Next, we create a ``#dbg_declare`` record to indicate at the IR420level that we've got a variable in an alloca (and it gives a starting421location for the variable), and setting a source location for the422beginning of the scope on the declare.423 424One interesting thing to note at this point is that various debuggers have425assumptions based on how code and debug information was generated for them426in the past. In this case we need to do a little bit of a hack to avoid427generating line information for the function prologue so that the debugger428knows to skip over those instructions when setting a breakpoint. So in429``FunctionAST::CodeGen`` we add some more lines:430 431.. code-block:: c++432 433 // Unset the location for the prologue emission (leading instructions with no434 // location in a function are considered part of the prologue and the debugger435 // will run past them when breaking on a function)436 KSDbgInfo.emitLocation(nullptr);437 438and then emit a new location when we actually start generating code for the439body of the function:440 441.. code-block:: c++442 443 KSDbgInfo.emitLocation(Body.get());444 445With this we have enough debug information to set breakpoints in functions,446print out argument variables, and call functions. Not too bad for just a447few simple lines of code!448 449Full Code Listing450=================451 452Here is the complete code listing for our running example, enhanced with453debug information. To build this example, use:454 455.. code-block:: bash456 457 # Compile458 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core orcjit native` -O3 -o toy459 # Run460 ./toy461 462Here is the code:463 464.. literalinclude:: ../../../examples/Kaleidoscope/Chapter9/toy.cpp465 :language: c++466 467`Next: Conclusion and other useful LLVM tidbits <LangImpl10.html>`_468 469