Kaleidoscope: Adding Debug Information

Welcome to Chapter 9 of the "Implementing a language with
LLVM" tutorial. In chapters 1 through 8, we've built a
decent little programming language with functions and variables.
What happens if something goes wrong though, how do you debug your
program?

Source level debugging uses formatted data that helps a debugger
translate from binary and the state of the machine back to the
source that the programmer wrote. In LLVM we generally use a format
called DWARF. DWARF is a compact encoding
that represents types, source locations, and variable locations.

The short summary of this chapter is that we'll go through the
various things you have to add to a programming language to
support debug info, and how you translate that into DWARF.

Caveat: For now we can't debug via the JIT, so we'll need to compile
our program down to something small and standalone. As part of this
we'll make a few modifications to the running of the language and
how programs are compiled. This means that we'll have a source file
with a simple program written in Kaleidoscope rather than the
interactive JIT. It does involve a limitation that we can only
have one "top level" command at a time to reduce the number of
changes necessary.

Debug information is a hard problem for a few different reasons - mostly
centered around optimized code. First, optimization makes keeping source
locations more difficult. In LLVM IR we keep the original source location
for each IR level instruction on the instruction. Optimization passes
should keep the source locations for newly created instructions, but merged
instructions only get to keep a single location - this can cause jumping
around when stepping through optimized programs. Secondly, optimization
can move variables in ways that are either optimized out, shared in memory
with other variables, or difficult to track. For the purposes of this
tutorial we're going to avoid optimization (as you'll see with one of the
next sets of patches).

To highlight only the aspects of adding debug information to a source
language without needing to worry about the complexities of JIT debugging
we're going to make a few changes to Kaleidoscope to support compiling
the IR emitted by the front end into a simple standalone program that
you can execute, debug, and see results.

First we make our anonymous function that contains our top level
statement be our "main":

The top level container for a section of code in DWARF is a compile unit.
This contains the type and function data for an individual translation unit
(read: one file of source code). So the first thing we need to do is
construct one for our fib.ks file.

Similar to the IRBuilder class we have a
DIBuilder class
that helps in constructing debug metadata for an LLVM IR file. It
corresponds 1:1 similarly to IRBuilder and LLVM IR, but with nicer names.
Using it does require that you be more familiar with DWARF terminology than
you needed to be with IRBuilder and Instruction names, but if you
read through the general documentation on the
Metadata Format it
should be a little more clear. We'll be using this class to construct all
of our IR level descriptions. Construction for it takes a module so we
need to construct it shortly after we construct our module. We've left it
as a global static variable to make it a bit easier to use.

Next we're going to create a small container to cache some of our frequent
data. The first will be our compile unit, but we'll also write a bit of
code for our one type since we won't have to worry about multiple typed
expressions:

There are a couple of things to note here. First, while we're producing a
compile unit for a language called Kaleidoscope we used the language
constant for C. This is because a debugger wouldn't necessarily understand
the calling conventions or default ABI for a language it doesn't recognize
and we follow the C ABI in our LLVM code generation so it's the closest
thing to accurate. This ensures we can actually call functions from the
debugger and have them execute. Secondly, you'll see the "fib.ks" in the
call to createCompileUnit. This is a default hard coded value since
we're using shell redirection to put our source into the Kaleidoscope
compiler. In a usual front end you'd have an input file name and it would
go there.

One last thing as part of emitting debug information via DIBuilder is that
we need to "finalize" the debug information. The reasons are part of the
underlying API for DIBuilder, but make sure you do this near the end of
main:

Now that we have our Compile Unit and our source locations, we can add
function definitions to the debug info. So in PrototypeAST::codegen() we
add a few lines of code to describe a context for our subprogram, in this
case the "File", and the actual definition of the function itself.

giving us an DIFile and asking the Compile Unit we created above for the
directory and filename where we are currently. Then, for now, we use some
source locations of 0 (since our AST doesn't currently have source location
information) and construct our function definition:

The most important thing for debug information is accurate source location -
this makes it possible to map your source code back. We have a problem though,
Kaleidoscope really doesn't have any source location information in the lexer
or parser so we'll need to add it.

In this set of code we've added some functionality on how to keep track of the
line and column of the "source file". As we lex every token we set our current
current "lexical location" to the assorted line and column for the beginning
of the token. We do this by overriding all of the previous calls to
getchar() with our new advance() that keeps track of the information
and then we have added to all of our AST classes a source location:

This both tells the main IRBuilder where we are, but also what scope
we're in. The scope can either be on compile-unit level or be the nearest
enclosing lexical block like the current function.
To represent this we create a stack of scopes:

std::vector<DIScope*>LexicalBlocks;

and push the scope (function) to the top of the stack when we start
generating the code for each function:

KSDbgInfo.LexicalBlocks.push_back(SP);

Also, we may not forget to pop the scope back off of the scope stack at the
end of the code generation for the function:

// Pop off the lexical block for the function since we added it
// unconditionally.
KSDbgInfo.LexicalBlocks.pop_back();

Then we make sure to emit the location every time we start to generate code
for a new AST object:

Now that we have functions, we need to be able to print out the variables
we have in scope. Let's get our function arguments set up so we can get
decent backtraces and see how our functions are being called. It isn't
a lot of code, and we generally handle it when we're creating the
argument allocas in FunctionAST::codegen.

// Record the function arguments in the NamedValues map.
NamedValues.clear();unsignedArgIdx=0;for(auto&Arg:TheFunction->args()){// Create an alloca for this variable.
AllocaInst*Alloca=CreateEntryBlockAlloca(TheFunction,Arg.getName());// Create a debug descriptor for the variable.
DILocalVariable*D=DBuilder->createParameterVariable(SP,Arg.getName(),++ArgIdx,Unit,LineNo,KSDbgInfo.getDoubleTy(),true);DBuilder->insertDeclare(Alloca,D,DBuilder->createExpression(),DebugLoc::get(LineNo,0,SP),Builder.GetInsertBlock());// Store the initial value into the alloca.
Builder.CreateStore(&Arg,Alloca);// Add arguments to variable symbol table.
NamedValues[Arg.getName()]=Alloca;}

Here we're first creating the variable, giving it the scope (SP),
the name, source location, type, and since it's an argument, the argument
index. Next, we create an lvm.dbg.declare call to indicate at the IR
level that we've got a variable in an alloca (and it gives a starting
location for the variable), and setting a source location for the
beginning of the scope on the declare.

One interesting thing to note at this point is that various debuggers have
assumptions based on how code and debug information was generated for them
in the past. In this case we need to do a little bit of a hack to avoid
generating line information for the function prologue so that the debugger
knows to skip over those instructions when setting a breakpoint. So in
FunctionAST::CodeGen we add some more lines:

// Unset the location for the prologue emission (leading instructions with no
// location in a function are considered part of the prologue and the debugger
// will run past them when breaking on a function)
KSDbgInfo.emitLocation(nullptr);

and then emit a new location when we actually start generating code for the
body of the function:

KSDbgInfo.emitLocation(Body.get());

With this we have enough debug information to set breakpoints in functions,
print out argument variables, and call functions. Not too bad for just a
few simple lines of code!