llvm.org GIT mirror llvm / f9c643b
New Kaleidoscope chapter: Creating object files This new chapter describes compiling LLVM IR to object files. The new chaper is chapter 8, so later chapters have been renumbered. Since this brings us to 10 chapters total, I've also needed to rename the other chapters to use two digit numbering. Differential Revision: http://reviews.llvm.org/D18070 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@274441 91177308-0d34-0410-b5e6-96231b3b80d8 Wilfred Hughes 3 years ago
26 changed file(s) with 7140 addition(s) and 5695 deletion(s). Raw diff Collapse all Expand all
0 =================================================
1 Kaleidoscope: Tutorial Introduction and the Lexer
2 =================================================
3
4 .. contents::
5 :local:
6
7 Tutorial Introduction
8 =====================
9
10 Welcome to the "Implementing a language with LLVM" tutorial. This
11 tutorial runs through the implementation of a simple language, showing
12 how fun and easy it can be. This tutorial will get you up and started as
13 well as help to build a framework you can extend to other languages. The
14 code in this tutorial can also be used as a playground to hack on other
15 LLVM specific things.
16
17 The goal of this tutorial is to progressively unveil our language,
18 describing how it is built up over time. This will let us cover a fairly
19 broad range of language design and LLVM-specific usage issues, showing
20 and explaining the code for it all along the way, without overwhelming
21 you with tons of details up front.
22
23 It is useful to point out ahead of time that this tutorial is really
24 about teaching compiler techniques and LLVM specifically, *not* about
25 teaching modern and sane software engineering principles. In practice,
26 this means that we'll take a number of shortcuts to simplify the
27 exposition. For example, the code uses global variables
28 all over the place, doesn't use nice design patterns like
29 `visitors `_, etc... but
30 it is very simple. If you dig in and use the code as a basis for future
31 projects, fixing these deficiencies shouldn't be hard.
32
33 I've tried to put this tutorial together in a way that makes chapters
34 easy to skip over if you are already familiar with or are uninterested
35 in the various pieces. The structure of the tutorial is:
36
37 - `Chapter #1 <#language>`_: Introduction to the Kaleidoscope
38 language, and the definition of its Lexer - This shows where we are
39 going and the basic functionality that we want it to do. In order to
40 make this tutorial maximally understandable and hackable, we choose
41 to implement everything in C++ instead of using lexer and parser
42 generators. LLVM obviously works just fine with such tools, feel free
43 to use one if you prefer.
44 - `Chapter #2 `_: Implementing a Parser and AST -
45 With the lexer in place, we can talk about parsing techniques and
46 basic AST construction. This tutorial describes recursive descent
47 parsing and operator precedence parsing. Nothing in Chapters 1 or 2
48 is LLVM-specific, the code doesn't even link in LLVM at this point.
49 :)
50 - `Chapter #3 `_: Code generation to LLVM IR - With
51 the AST ready, we can show off how easy generation of LLVM IR really
52 is.
53 - `Chapter #4 `_: Adding JIT and Optimizer Support
54 - Because a lot of people are interested in using LLVM as a JIT,
55 we'll dive right into it and show you the 3 lines it takes to add JIT
56 support. LLVM is also useful in many other ways, but this is one
57 simple and "sexy" way to show off its power. :)
58 - `Chapter #5 `_: Extending the Language: Control
59 Flow - With the language up and running, we show how to extend it
60 with control flow operations (if/then/else and a 'for' loop). This
61 gives us a chance to talk about simple SSA construction and control
62 flow.
63 - `Chapter #6 `_: Extending the Language:
64 User-defined Operators - This is a silly but fun chapter that talks
65 about extending the language to let the user program define their own
66 arbitrary unary and binary operators (with assignable precedence!).
67 This lets us build a significant piece of the "language" as library
68 routines.
69 - `Chapter #7 `_: Extending the Language: Mutable
70 Variables - This chapter talks about adding user-defined local
71 variables along with an assignment operator. The interesting part
72 about this is how easy and trivial it is to construct SSA form in
73 LLVM: no, LLVM does *not* require your front-end to construct SSA
74 form!
75 - `Chapter #8 `_: Compiling to Object Files - This
76 chapter explains how to take LLVM IR and compile it down to object
77 files.
78 - `Chapter #9 `_: Extending the Language: Debug
79 Information - Having built a decent little programming language with
80 control flow, functions and mutable variables, we consider what it
81 takes to add debug information to standalone executables. This debug
82 information will allow you to set breakpoints in Kaleidoscope
83 functions, print out argument variables, and call functions - all
84 from within the debugger!
85 - `Chapter #10 `_: Conclusion and other useful LLVM
86 tidbits - This chapter wraps up the series by talking about
87 potential ways to extend the language, but also includes a bunch of
88 pointers to info about "special topics" like adding garbage
89 collection support, exceptions, debugging, support for "spaghetti
90 stacks", and a bunch of other tips and tricks.
91
92 By the end of the tutorial, we'll have written a bit less than 1000 lines
93 of non-comment, non-blank, lines of code. With this small amount of
94 code, we'll have built up a very reasonable compiler for a non-trivial
95 language including a hand-written lexer, parser, AST, as well as code
96 generation support with a JIT compiler. While other systems may have
97 interesting "hello world" tutorials, I think the breadth of this
98 tutorial is a great testament to the strengths of LLVM and why you
99 should consider it if you're interested in language or compiler design.
100
101 A note about this tutorial: we expect you to extend the language and
102 play with it on your own. Take the code and go crazy hacking away at it,
103 compilers don't need to be scary creatures - it can be a lot of fun to
104 play with languages!
105
106 The Basic Language
107 ==================
108
109 This tutorial will be illustrated with a toy language that we'll call
110 "`Kaleidoscope `_" (derived
111 from "meaning beautiful, form, and view"). Kaleidoscope is a procedural
112 language that allows you to define functions, use conditionals, math,
113 etc. Over the course of the tutorial, we'll extend Kaleidoscope to
114 support the if/then/else construct, a for loop, user defined operators,
115 JIT compilation with a simple command line interface, etc.
116
117 Because we want to keep things simple, the only datatype in Kaleidoscope
118 is a 64-bit floating point type (aka 'double' in C parlance). As such,
119 all values are implicitly double precision and the language doesn't
120 require type declarations. This gives the language a very nice and
121 simple syntax. For example, the following simple example computes
122 `Fibonacci numbers: `_
123
124 ::
125
126 # Compute the x'th fibonacci number.
127 def fib(x)
128 if x < 3 then
129 1
130 else
131 fib(x-1)+fib(x-2)
132
133 # This expression will compute the 40th number.
134 fib(40)
135
136 We also allow Kaleidoscope to call into standard library functions (the
137 LLVM JIT makes this completely trivial). This means that you can use the
138 'extern' keyword to define a function before you use it (this is also
139 useful for mutually recursive functions). For example:
140
141 ::
142
143 extern sin(arg);
144 extern cos(arg);
145 extern atan2(arg1 arg2);
146
147 atan2(sin(.4), cos(42))
148
149 A more interesting example is included in Chapter 6 where we write a
150 little Kaleidoscope application that `displays a Mandelbrot
151 Set `_ at various levels of magnification.
152
153 Lets dive into the implementation of this language!
154
155 The Lexer
156 =========
157
158 When it comes to implementing a language, the first thing needed is the
159 ability to process a text file and recognize what it says. The
160 traditional way to do this is to use a
161 "`lexer `_" (aka
162 'scanner') to break the input up into "tokens". Each token returned by
163 the lexer includes a token code and potentially some metadata (e.g. the
164 numeric value of a number). First, we define the possibilities:
165
166 .. code-block:: c++
167
168 // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
169 // of these for known things.
170 enum Token {
171 tok_eof = -1,
172
173 // commands
174 tok_def = -2,
175 tok_extern = -3,
176
177 // primary
178 tok_identifier = -4,
179 tok_number = -5,
180 };
181
182 static std::string IdentifierStr; // Filled in if tok_identifier
183 static double NumVal; // Filled in if tok_number
184
185 Each token returned by our lexer will either be one of the Token enum
186 values or it will be an 'unknown' character like '+', which is returned
187 as its ASCII value. If the current token is an identifier, the
188 ``IdentifierStr`` global variable holds the name of the identifier. If
189 the current token is a numeric literal (like 1.0), ``NumVal`` holds its
190 value. Note that we use global variables for simplicity, this is not the
191 best choice for a real language implementation :).
192
193 The actual implementation of the lexer is a single function named
194 ``gettok``. The ``gettok`` function is called to return the next token
195 from standard input. Its definition starts as:
196
197 .. code-block:: c++
198
199 /// gettok - Return the next token from standard input.
200 static int gettok() {
201 static int LastChar = ' ';
202
203 // Skip any whitespace.
204 while (isspace(LastChar))
205 LastChar = getchar();
206
207 ``gettok`` works by calling the C ``getchar()`` function to read
208 characters one at a time from standard input. It eats them as it
209 recognizes them and stores the last character read, but not processed,
210 in LastChar. The first thing that it has to do is ignore whitespace
211 between tokens. This is accomplished with the loop above.
212
213 The next thing ``gettok`` needs to do is recognize identifiers and
214 specific keywords like "def". Kaleidoscope does this with this simple
215 loop:
216
217 .. code-block:: c++
218
219 if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
220 IdentifierStr = LastChar;
221 while (isalnum((LastChar = getchar())))
222 IdentifierStr += LastChar;
223
224 if (IdentifierStr == "def")
225 return tok_def;
226 if (IdentifierStr == "extern")
227 return tok_extern;
228 return tok_identifier;
229 }
230
231 Note that this code sets the '``IdentifierStr``' global whenever it
232 lexes an identifier. Also, since language keywords are matched by the
233 same loop, we handle them here inline. Numeric values are similar:
234
235 .. code-block:: c++
236
237 if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
238 std::string NumStr;
239 do {
240 NumStr += LastChar;
241 LastChar = getchar();
242 } while (isdigit(LastChar) || LastChar == '.');
243
244 NumVal = strtod(NumStr.c_str(), 0);
245 return tok_number;
246 }
247
248 This is all pretty straight-forward code for processing input. When
249 reading a numeric value from input, we use the C ``strtod`` function to
250 convert it to a numeric value that we store in ``NumVal``. Note that
251 this isn't doing sufficient error checking: it will incorrectly read
252 "1.23.45.67" and handle it as if you typed in "1.23". Feel free to
253 extend it :). Next we handle comments:
254
255 .. code-block:: c++
256
257 if (LastChar == '#') {
258 // Comment until end of line.
259 do
260 LastChar = getchar();
261 while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
262
263 if (LastChar != EOF)
264 return gettok();
265 }
266
267 We handle comments by skipping to the end of the line and then return
268 the next token. Finally, if the input doesn't match one of the above
269 cases, it is either an operator character like '+' or the end of the
270 file. These are handled with this code:
271
272 .. code-block:: c++
273
274 // Check for end of file. Don't eat the EOF.
275 if (LastChar == EOF)
276 return tok_eof;
277
278 // Otherwise, just return the character as its ascii value.
279 int ThisChar = LastChar;
280 LastChar = getchar();
281 return ThisChar;
282 }
283
284 With this, we have the complete lexer for the basic Kaleidoscope
285 language (the `full code listing `_ for the Lexer
286 is available in the `next chapter `_ of the tutorial).
287 Next we'll `build a simple parser that uses this to build an Abstract
288 Syntax Tree `_. When we have that, we'll include a
289 driver so that you can use the lexer and parser together.
290
291 `Next: Implementing a Parser and AST `_
292
0 ===========================================
1 Kaleidoscope: Implementing a Parser and AST
2 ===========================================
3
4 .. contents::
5 :local:
6
7 Chapter 2 Introduction
8 ======================
9
10 Welcome to Chapter 2 of the "`Implementing a language with
11 LLVM `_" tutorial. This chapter shows you how to use the
12 lexer, built in `Chapter 1 `_, to build a full
13 `parser `_ for our Kaleidoscope
14 language. Once we have a parser, we'll define and build an `Abstract
15 Syntax Tree `_ (AST).
16
17 The parser we will build uses a combination of `Recursive Descent
18 Parsing `_ and
19 `Operator-Precedence
20 Parsing `_ to
21 parse the Kaleidoscope language (the latter for binary expressions and
22 the former for everything else). Before we get to parsing though, lets
23 talk about the output of the parser: the Abstract Syntax Tree.
24
25 The Abstract Syntax Tree (AST)
26 ==============================
27
28 The AST for a program captures its behavior in such a way that it is
29 easy for later stages of the compiler (e.g. code generation) to
30 interpret. We basically want one object for each construct in the
31 language, and the AST should closely model the language. In
32 Kaleidoscope, we have expressions, a prototype, and a function object.
33 We'll start with expressions first:
34
35 .. code-block:: c++
36
37 /// ExprAST - Base class for all expression nodes.
38 class ExprAST {
39 public:
40 virtual ~ExprAST() {}
41 };
42
43 /// NumberExprAST - Expression class for numeric literals like "1.0".
44 class NumberExprAST : public ExprAST {
45 double Val;
46
47 public:
48 NumberExprAST(double Val) : Val(Val) {}
49 };
50
51 The code above shows the definition of the base ExprAST class and one
52 subclass which we use for numeric literals. The important thing to note
53 about this code is that the NumberExprAST class captures the numeric
54 value of the literal as an instance variable. This allows later phases
55 of the compiler to know what the stored numeric value is.
56
57 Right now we only create the AST, so there are no useful accessor
58 methods on them. It would be very easy to add a virtual method to pretty
59 print the code, for example. Here are the other expression AST node
60 definitions that we'll use in the basic form of the Kaleidoscope
61 language:
62
63 .. code-block:: c++
64
65 /// VariableExprAST - Expression class for referencing a variable, like "a".
66 class VariableExprAST : public ExprAST {
67 std::string Name;
68
69 public:
70 VariableExprAST(const std::string &Name) : Name(Name) {}
71 };
72
73 /// BinaryExprAST - Expression class for a binary operator.
74 class BinaryExprAST : public ExprAST {
75 char Op;
76 std::unique_ptr LHS, RHS;
77
78 public:
79 BinaryExprAST(char op, std::unique_ptr LHS,
80 std::unique_ptr RHS)
81 : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
82 };
83
84 /// CallExprAST - Expression class for function calls.
85 class CallExprAST : public ExprAST {
86 std::string Callee;
87 std::vector> Args;
88
89 public:
90 CallExprAST(const std::string &Callee,
91 std::vector> Args)
92 : Callee(Callee), Args(std::move(Args)) {}
93 };
94
95 This is all (intentionally) rather straight-forward: variables capture
96 the variable name, binary operators capture their opcode (e.g. '+'), and
97 calls capture a function name as well as a list of any argument
98 expressions. One thing that is nice about our AST is that it captures
99 the language features without talking about the syntax of the language.
100 Note that there is no discussion about precedence of binary operators,
101 lexical structure, etc.
102
103 For our basic language, these are all of the expression nodes we'll
104 define. Because it doesn't have conditional control flow, it isn't
105 Turing-complete; we'll fix that in a later installment. The two things
106 we need next are a way to talk about the interface to a function, and a
107 way to talk about functions themselves:
108
109 .. code-block:: c++
110
111 /// PrototypeAST - This class represents the "prototype" for a function,
112 /// which captures its name, and its argument names (thus implicitly the number
113 /// of arguments the function takes).
114 class PrototypeAST {
115 std::string Name;
116 std::vector Args;
117
118 public:
119 PrototypeAST(const std::string &name, std::vector Args)
120 : Name(name), Args(std::move(Args)) {}
121 };
122
123 /// FunctionAST - This class represents a function definition itself.
124 class FunctionAST {
125 std::unique_ptr Proto;
126 std::unique_ptr Body;
127
128 public:
129 FunctionAST(std::unique_ptr Proto,
130 std::unique_ptr Body)
131 : Proto(std::move(Proto)), Body(std::move(Body)) {}
132 };
133
134 In Kaleidoscope, functions are typed with just a count of their
135 arguments. Since all values are double precision floating point, the
136 type of each argument doesn't need to be stored anywhere. In a more
137 aggressive and realistic language, the "ExprAST" class would probably
138 have a type field.
139
140 With this scaffolding, we can now talk about parsing expressions and
141 function bodies in Kaleidoscope.
142
143 Parser Basics
144 =============
145
146 Now that we have an AST to build, we need to define the parser code to
147 build it. The idea here is that we want to parse something like "x+y"
148 (which is returned as three tokens by the lexer) into an AST that could
149 be generated with calls like this:
150
151 .. code-block:: c++
152
153 auto LHS = llvm::make_unique("x");
154 auto RHS = llvm::make_unique("y");
155 auto Result = std::make_unique('+', std::move(LHS),
156 std::move(RHS));
157
158 In order to do this, we'll start by defining some basic helper routines:
159
160 .. code-block:: c++
161
162 /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
163 /// token the parser is looking at. getNextToken reads another token from the
164 /// lexer and updates CurTok with its results.
165 static int CurTok;
166 static int getNextToken() {
167 return CurTok = gettok();
168 }
169
170 This implements a simple token buffer around the lexer. This allows us
171 to look one token ahead at what the lexer is returning. Every function
172 in our parser will assume that CurTok is the current token that needs to
173 be parsed.
174
175 .. code-block:: c++
176
177
178 /// LogError* - These are little helper functions for error handling.
179 std::unique_ptr LogError(const char *Str) {
180 fprintf(stderr, "LogError: %s\n", Str);
181 return nullptr;
182 }
183 std::unique_ptr LogErrorP(const char *Str) {
184 LogError(Str);
185 return nullptr;
186 }
187
188 The ``LogError`` routines are simple helper routines that our parser will
189 use to handle errors. The error recovery in our parser will not be the
190 best and is not particular user-friendly, but it will be enough for our
191 tutorial. These routines make it easier to handle errors in routines
192 that have various return types: they always return null.
193
194 With these basic helper functions, we can implement the first piece of
195 our grammar: numeric literals.
196
197 Basic Expression Parsing
198 ========================
199
200 We start with numeric literals, because they are the simplest to
201 process. For each production in our grammar, we'll define a function
202 which parses that production. For numeric literals, we have:
203
204 .. code-block:: c++
205
206 /// numberexpr ::= number
207 static std::unique_ptr ParseNumberExpr() {
208 auto Result = llvm::make_unique(NumVal);
209 getNextToken(); // consume the number
210 return std::move(Result);
211 }
212
213 This routine is very simple: it expects to be called when the current
214 token is a ``tok_number`` token. It takes the current number value,
215 creates a ``NumberExprAST`` node, advances the lexer to the next token,
216 and finally returns.
217
218 There are some interesting aspects to this. The most important one is
219 that this routine eats all of the tokens that correspond to the
220 production and returns the lexer buffer with the next token (which is
221 not part of the grammar production) ready to go. This is a fairly
222 standard way to go for recursive descent parsers. For a better example,
223 the parenthesis operator is defined like this:
224
225 .. code-block:: c++
226
227 /// parenexpr ::= '(' expression ')'
228 static std::unique_ptr ParseParenExpr() {
229 getNextToken(); // eat (.
230 auto V = ParseExpression();
231 if (!V)
232 return nullptr;
233
234 if (CurTok != ')')
235 return LogError("expected ')'");
236 getNextToken(); // eat ).
237 return V;
238 }
239
240 This function illustrates a number of interesting things about the
241 parser:
242
243 1) It shows how we use the LogError routines. When called, this function
244 expects that the current token is a '(' token, but after parsing the
245 subexpression, it is possible that there is no ')' waiting. For example,
246 if the user types in "(4 x" instead of "(4)", the parser should emit an
247 error. Because errors can occur, the parser needs a way to indicate that
248 they happened: in our parser, we return null on an error.
249
250 2) Another interesting aspect of this function is that it uses recursion
251 by calling ``ParseExpression`` (we will soon see that
252 ``ParseExpression`` can call ``ParseParenExpr``). This is powerful
253 because it allows us to handle recursive grammars, and keeps each
254 production very simple. Note that parentheses do not cause construction
255 of AST nodes themselves. While we could do it this way, the most
256 important role of parentheses are to guide the parser and provide
257 grouping. Once the parser constructs the AST, parentheses are not
258 needed.
259
260 The next simple production is for handling variable references and
261 function calls:
262
263 .. code-block:: c++
264
265 /// identifierexpr
266 /// ::= identifier
267 /// ::= identifier '(' expression* ')'
268 static std::unique_ptr ParseIdentifierExpr() {
269 std::string IdName = IdentifierStr;
270
271 getNextToken(); // eat identifier.
272
273 if (CurTok != '(') // Simple variable ref.
274 return llvm::make_unique(IdName);
275
276 // Call.
277 getNextToken(); // eat (
278 std::vector> Args;
279 if (CurTok != ')') {
280 while (1) {
281 if (auto Arg = ParseExpression())
282 Args.push_back(std::move(Arg));
283 else
284 return nullptr;
285
286 if (CurTok == ')')
287 break;
288
289 if (CurTok != ',')
290 return LogError("Expected ')' or ',' in argument list");
291 getNextToken();
292 }
293 }
294
295 // Eat the ')'.
296 getNextToken();
297
298 return llvm::make_unique(IdName, std::move(Args));
299 }
300
301 This routine follows the same style as the other routines. (It expects
302 to be called if the current token is a ``tok_identifier`` token). It
303 also has recursion and error handling. One interesting aspect of this is
304 that it uses *look-ahead* to determine if the current identifier is a
305 stand alone variable reference or if it is a function call expression.
306 It handles this by checking to see if the token after the identifier is
307 a '(' token, constructing either a ``VariableExprAST`` or
308 ``CallExprAST`` node as appropriate.
309
310 Now that we have all of our simple expression-parsing logic in place, we
311 can define a helper function to wrap it together into one entry point.
312 We call this class of expressions "primary" expressions, for reasons
313 that will become more clear `later in the
314 tutorial `_. In order to parse an arbitrary
315 primary expression, we need to determine what sort of expression it is:
316
317 .. code-block:: c++
318
319 /// primary
320 /// ::= identifierexpr
321 /// ::= numberexpr
322 /// ::= parenexpr
323 static std::unique_ptr ParsePrimary() {
324 switch (CurTok) {
325 default:
326 return LogError("unknown token when expecting an expression");
327 case tok_identifier:
328 return ParseIdentifierExpr();
329 case tok_number:
330 return ParseNumberExpr();
331 case '(':
332 return ParseParenExpr();
333 }
334 }
335
336 Now that you see the definition of this function, it is more obvious why
337 we can assume the state of CurTok in the various functions. This uses
338 look-ahead to determine which sort of expression is being inspected, and
339 then parses it with a function call.
340
341 Now that basic expressions are handled, we need to handle binary
342 expressions. They are a bit more complex.
343
344 Binary Expression Parsing
345 =========================
346
347 Binary expressions are significantly harder to parse because they are
348 often ambiguous. For example, when given the string "x+y\*z", the parser
349 can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
350 definitions from mathematics, we expect the later parse, because "\*"
351 (multiplication) has higher *precedence* than "+" (addition).
352
353 There are many ways to handle this, but an elegant and efficient way is
354 to use `Operator-Precedence
355 Parsing `_.
356 This parsing technique uses the precedence of binary operators to guide
357 recursion. To start with, we need a table of precedences:
358
359 .. code-block:: c++
360
361 /// BinopPrecedence - This holds the precedence for each binary operator that is
362 /// defined.
363 static std::map BinopPrecedence;
364
365 /// GetTokPrecedence - Get the precedence of the pending binary operator token.
366 static int GetTokPrecedence() {
367 if (!isascii(CurTok))
368 return -1;
369
370 // Make sure it's a declared binop.
371 int TokPrec = BinopPrecedence[CurTok];
372 if (TokPrec <= 0) return -1;
373 return TokPrec;
374 }
375
376 int main() {
377 // Install standard binary operators.
378 // 1 is lowest precedence.
379 BinopPrecedence['<'] = 10;
380 BinopPrecedence['+'] = 20;
381 BinopPrecedence['-'] = 20;
382 BinopPrecedence['*'] = 40; // highest.
383 ...
384 }
385
386 For the basic form of Kaleidoscope, we will only support 4 binary
387 operators (this can obviously be extended by you, our brave and intrepid
388 reader). The ``GetTokPrecedence`` function returns the precedence for
389 the current token, or -1 if the token is not a binary operator. Having a
390 map makes it easy to add new operators and makes it clear that the
391 algorithm doesn't depend on the specific operators involved, but it
392 would be easy enough to eliminate the map and do the comparisons in the
393 ``GetTokPrecedence`` function. (Or just use a fixed-size array).
394
395 With the helper above defined, we can now start parsing binary
396 expressions. The basic idea of operator precedence parsing is to break
397 down an expression with potentially ambiguous binary operators into
398 pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
399 Operator precedence parsing considers this as a stream of primary
400 expressions separated by binary operators. As such, it will first parse
401 the leading primary expression "a", then it will see the pairs [+, b]
402 [+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
403 primary expressions, the binary expression parser doesn't need to worry
404 about nested subexpressions like (c+d) at all.
405
406 To start, an expression is a primary expression potentially followed by
407 a sequence of [binop,primaryexpr] pairs:
408
409 .. code-block:: c++
410
411 /// expression
412 /// ::= primary binoprhs
413 ///
414 static std::unique_ptr ParseExpression() {
415 auto LHS = ParsePrimary();
416 if (!LHS)
417 return nullptr;
418
419 return ParseBinOpRHS(0, std::move(LHS));
420 }
421
422 ``ParseBinOpRHS`` is the function that parses the sequence of pairs for
423 us. It takes a precedence and a pointer to an expression for the part
424 that has been parsed so far. Note that "x" is a perfectly valid
425 expression: As such, "binoprhs" is allowed to be empty, in which case it
426 returns the expression that is passed into it. In our example above, the
427 code passes the expression for "a" into ``ParseBinOpRHS`` and the
428 current token is "+".
429
430 The precedence value passed into ``ParseBinOpRHS`` indicates the
431 *minimal operator precedence* that the function is allowed to eat. For
432 example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
433 passed in a precedence of 40, it will not consume any tokens (because
434 the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
435 starts with:
436
437 .. code-block:: c++
438
439 /// binoprhs
440 /// ::= ('+' primary)*
441 static std::unique_ptr ParseBinOpRHS(int ExprPrec,
442 std::unique_ptr LHS) {
443 // If this is a binop, find its precedence.
444 while (1) {
445 int TokPrec = GetTokPrecedence();
446
447 // If this is a binop that binds at least as tightly as the current binop,
448 // consume it, otherwise we are done.
449 if (TokPrec < ExprPrec)
450 return LHS;
451
452 This code gets the precedence of the current token and checks to see if
453 if is too low. Because we defined invalid tokens to have a precedence of
454 -1, this check implicitly knows that the pair-stream ends when the token
455 stream runs out of binary operators. If this check succeeds, we know
456 that the token is a binary operator and that it will be included in this
457 expression:
458
459 .. code-block:: c++
460
461 // Okay, we know this is a binop.
462 int BinOp = CurTok;
463 getNextToken(); // eat binop
464
465 // Parse the primary expression after the binary operator.
466 auto RHS = ParsePrimary();
467 if (!RHS)
468 return nullptr;
469
470 As such, this code eats (and remembers) the binary operator and then
471 parses the primary expression that follows. This builds up the whole
472 pair, the first of which is [+, b] for the running example.
473
474 Now that we parsed the left-hand side of an expression and one pair of
475 the RHS sequence, we have to decide which way the expression associates.
476 In particular, we could have "(a+b) binop unparsed" or "a + (b binop
477 unparsed)". To determine this, we look ahead at "binop" to determine its
478 precedence and compare it to BinOp's precedence (which is '+' in this
479 case):
480
481 .. code-block:: c++
482
483 // If BinOp binds less tightly with RHS than the operator after RHS, let
484 // the pending operator take RHS as its LHS.
485 int NextPrec = GetTokPrecedence();
486 if (TokPrec < NextPrec) {
487
488 If the precedence of the binop to the right of "RHS" is lower or equal
489 to the precedence of our current operator, then we know that the
490 parentheses associate as "(a+b) binop ...". In our example, the current
491 operator is "+" and the next operator is "+", we know that they have the
492 same precedence. In this case we'll create the AST node for "a+b", and
493 then continue parsing:
494
495 .. code-block:: c++
496
497 ... if body omitted ...
498 }
499
500 // Merge LHS/RHS.
501 LHS = llvm::make_unique(BinOp, std::move(LHS),
502 std::move(RHS));
503 } // loop around to the top of the while loop.
504 }
505
506 In our example above, this will turn "a+b+" into "(a+b)" and execute the
507 next iteration of the loop, with "+" as the current token. The code
508 above will eat, remember, and parse "(c+d)" as the primary expression,
509 which makes the current pair equal to [+, (c+d)]. It will then evaluate
510 the 'if' conditional above with "\*" as the binop to the right of the
511 primary. In this case, the precedence of "\*" is higher than the
512 precedence of "+" so the if condition will be entered.
513
514 The critical question left here is "how can the if condition parse the
515 right hand side in full"? In particular, to build the AST correctly for
516 our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
517 variable. The code to do this is surprisingly simple (code from the
518 above two blocks duplicated for context):
519
520 .. code-block:: c++
521
522 // If BinOp binds less tightly with RHS than the operator after RHS, let
523 // the pending operator take RHS as its LHS.
524 int NextPrec = GetTokPrecedence();
525 if (TokPrec < NextPrec) {
526 RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
527 if (!RHS)
528 return nullptr;
529 }
530 // Merge LHS/RHS.
531 LHS = llvm::make_unique(BinOp, std::move(LHS),
532 std::move(RHS));
533 } // loop around to the top of the while loop.
534 }
535
536 At this point, we know that the binary operator to the RHS of our
537 primary has higher precedence than the binop we are currently parsing.
538 As such, we know that any sequence of pairs whose operators are all
539 higher precedence than "+" should be parsed together and returned as
540 "RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
541 specifying "TokPrec+1" as the minimum precedence required for it to
542 continue. In our example above, this will cause it to return the AST
543 node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'
544 expression.
545
546 Finally, on the next iteration of the while loop, the "+g" piece is
547 parsed and added to the AST. With this little bit of code (14
548 non-trivial lines), we correctly handle fully general binary expression
549 parsing in a very elegant way. This was a whirlwind tour of this code,
550 and it is somewhat subtle. I recommend running through it with a few
551 tough examples to see how it works.
552
553 This wraps up handling of expressions. At this point, we can point the
554 parser at an arbitrary token stream and build an expression from it,
555 stopping at the first token that is not part of the expression. Next up
556 we need to handle function definitions, etc.
557
558 Parsing the Rest
559 ================
560
561 The next thing missing is handling of function prototypes. In
562 Kaleidoscope, these are used both for 'extern' function declarations as
563 well as function body definitions. The code to do this is
564 straight-forward and not very interesting (once you've survived
565 expressions):
566
567 .. code-block:: c++
568
569 /// prototype
570 /// ::= id '(' id* ')'
571 static std::unique_ptr ParsePrototype() {
572 if (CurTok != tok_identifier)
573 return LogErrorP("Expected function name in prototype");
574
575 std::string FnName = IdentifierStr;
576 getNextToken();
577
578 if (CurTok != '(')
579 return LogErrorP("Expected '(' in prototype");
580
581 // Read the list of argument names.
582 std::vector ArgNames;
583 while (getNextToken() == tok_identifier)
584 ArgNames.push_back(IdentifierStr);
585 if (CurTok != ')')
586 return LogErrorP("Expected ')' in prototype");
587
588 // success.
589 getNextToken(); // eat ')'.
590
591 return llvm::make_unique(FnName, std::move(ArgNames));
592 }
593
594 Given this, a function definition is very simple, just a prototype plus
595 an expression to implement the body:
596
597 .. code-block:: c++
598
599 /// definition ::= 'def' prototype expression
600 static std::unique_ptr ParseDefinition() {
601 getNextToken(); // eat def.
602 auto Proto = ParsePrototype();
603 if (!Proto) return nullptr;
604
605 if (auto E = ParseExpression())
606 return llvm::make_unique(std::move(Proto), std::move(E));
607 return nullptr;
608 }
609
610 In addition, we support 'extern' to declare functions like 'sin' and
611 'cos' as well as to support forward declaration of user functions. These
612 'extern's are just prototypes with no body:
613
614 .. code-block:: c++
615
616 /// external ::= 'extern' prototype
617 static std::unique_ptr ParseExtern() {
618 getNextToken(); // eat extern.
619 return ParsePrototype();
620 }
621
622 Finally, we'll also let the user type in arbitrary top-level expressions
623 and evaluate them on the fly. We will handle this by defining anonymous
624 nullary (zero argument) functions for them:
625
626 .. code-block:: c++
627
628 /// toplevelexpr ::= expression
629 static std::unique_ptr ParseTopLevelExpr() {
630 if (auto E = ParseExpression()) {
631 // Make an anonymous proto.
632 auto Proto = llvm::make_unique("", std::vector());
633 return llvm::make_unique(std::move(Proto), std::move(E));
634 }
635 return nullptr;
636 }
637
638 Now that we have all the pieces, let's build a little driver that will
639 let us actually *execute* this code we've built!
640
641 The Driver
642 ==========
643
644 The driver for this simply invokes all of the parsing pieces with a
645 top-level dispatch loop. There isn't much interesting here, so I'll just
646 include the top-level loop. See `below <#full-code-listing>`_ for full code in the
647 "Top-Level Parsing" section.
648
649 .. code-block:: c++
650
651 /// top ::= definition | external | expression | ';'
652 static void MainLoop() {
653 while (1) {
654 fprintf(stderr, "ready> ");
655 switch (CurTok) {
656 case tok_eof:
657 return;
658 case ';': // ignore top-level semicolons.
659 getNextToken();
660 break;
661 case tok_def:
662 HandleDefinition();
663 break;
664 case tok_extern:
665 HandleExtern();
666 break;
667 default:
668 HandleTopLevelExpression();
669 break;
670 }
671 }
672 }
673
674 The most interesting part of this is that we ignore top-level
675 semicolons. Why is this, you ask? The basic reason is that if you type
676 "4 + 5" at the command line, the parser doesn't know whether that is the
677 end of what you will type or not. For example, on the next line you
678 could type "def foo..." in which case 4+5 is the end of a top-level
679 expression. Alternatively you could type "\* 6", which would continue
680 the expression. Having top-level semicolons allows you to type "4+5;",
681 and the parser will know you are done.
682
683 Conclusions
684 ===========
685
686 With just under 400 lines of commented code (240 lines of non-comment,
687 non-blank code), we fully defined our minimal language, including a
688 lexer, parser, and AST builder. With this done, the executable will
689 validate Kaleidoscope code and tell us if it is grammatically invalid.
690 For example, here is a sample interaction:
691
692 .. code-block:: bash
693
694 $ ./a.out
695 ready> def foo(x y) x+foo(y, 4.0);
696 Parsed a function definition.
697 ready> def foo(x y) x+y y;
698 Parsed a function definition.
699 Parsed a top-level expr
700 ready> def foo(x y) x+y );
701 Parsed a function definition.
702 Error: unknown token when expecting an expression
703 ready> extern sin(a);
704 ready> Parsed an extern
705 ready> ^D
706 $
707
708 There is a lot of room for extension here. You can define new AST nodes,
709 extend the language in many ways, etc. In the `next
710 installment `_, we will describe how to generate LLVM
711 Intermediate Representation (IR) from the AST.
712
713 Full Code Listing
714 =================
715
716 Here is the complete code listing for this and the previous chapter.
717 Note that it is fully self-contained: you don't need LLVM or any
718 external libraries at all for this. (Besides the C and C++ standard
719 libraries, of course.) To build this, just compile with:
720
721 .. code-block:: bash
722
723 # Compile
724 clang++ -g -O3 toy.cpp
725 # Run
726 ./a.out
727
728 Here is the code:
729
730 .. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp
731 :language: c++
732
733 `Next: Implementing Code Generation to LLVM IR `_
734
0 ========================================
1 Kaleidoscope: Code generation to LLVM IR
2 ========================================
3
4 .. contents::
5 :local:
6
7 Chapter 3 Introduction
8 ======================
9
10 Welcome to Chapter 3 of the "`Implementing a language with
11 LLVM `_" tutorial. This chapter shows you how to transform
12 the `Abstract Syntax Tree `_, built in Chapter 2, into
13 LLVM IR. This will teach you a little bit about how LLVM does things, as
14 well as demonstrate how easy it is to use. It's much more work to build
15 a lexer and parser than it is to generate LLVM IR code. :)
16
17 **Please note**: the code in this chapter and later require LLVM 3.7 or
18 later. LLVM 3.6 and before will not work with it. Also note that you
19 need to use a version of this tutorial that matches your LLVM release:
20 If you are using an official LLVM release, use the version of the
21 documentation included with your release or on the `llvm.org releases
22 page `_.
23
24 Code Generation Setup
25 =====================
26
27 In order to generate LLVM IR, we want some simple setup to get started.
28 First we define virtual code generation (codegen) methods in each AST
29 class:
30
31 .. code-block:: c++
32
33 /// ExprAST - Base class for all expression nodes.
34 class ExprAST {
35 public:
36 virtual ~ExprAST() {}
37 virtual Value *codegen() = 0;
38 };
39
40 /// NumberExprAST - Expression class for numeric literals like "1.0".
41 class NumberExprAST : public ExprAST {
42 double Val;
43
44 public:
45 NumberExprAST(double Val) : Val(Val) {}
46 virtual Value *codegen();
47 };
48 ...
49
50 The codegen() method says to emit IR for that AST node along with all
51 the things it depends on, and they all return an LLVM Value object.
52 "Value" is the class used to represent a "`Static Single Assignment
53 (SSA) `_
54 register" or "SSA value" in LLVM. The most distinct aspect of SSA values
55 is that their value is computed as the related instruction executes, and
56 it does not get a new value until (and if) the instruction re-executes.
57 In other words, there is no way to "change" an SSA value. For more
58 information, please read up on `Static Single
59 Assignment `_
60 - the concepts are really quite natural once you grok them.
61
62 Note that instead of adding virtual methods to the ExprAST class
63 hierarchy, it could also make sense to use a `visitor
64 pattern `_ or some other
65 way to model this. Again, this tutorial won't dwell on good software
66 engineering practices: for our purposes, adding a virtual method is
67 simplest.
68
69 The second thing we want is an "LogError" method like we used for the
70 parser, which will be used to report errors found during code generation
71 (for example, use of an undeclared parameter):
72
73 .. code-block:: c++
74
75 static LLVMContext TheContext;
76 static IRBuilder<> Builder(TheContext);
77 static std::unique_ptr TheModule;
78 static std::map NamedValues;
79
80 Value *LogErrorV(const char *Str) {
81 LogError(Str);
82 return nullptr;
83 }
84
85 The static variables will be used during code generation. ``TheContext``
86 is an opaque object that owns a lot of core LLVM data structures, such as
87 the type and constant value tables. We don't need to understand it in
88 detail, we just need a single instance to pass into APIs that require it.
89
90 The ``Builder`` object is a helper object that makes it easy to generate
91 LLVM instructions. Instances of the
92 `IRBuilder `_
93 class template keep track of the current place to insert instructions
94 and has methods to create new instructions.
95
96 ``TheModule`` is an LLVM construct that contains functions and global
97 variables. In many ways, it is the top-level structure that the LLVM IR
98 uses to contain code. It will own the memory for all of the IR that we
99 generate, which is why the codegen() method returns a raw Value\*,
100 rather than a unique_ptr.
101
102 The ``NamedValues`` map keeps track of which values are defined in the
103 current scope and what their LLVM representation is. (In other words, it
104 is a symbol table for the code). In this form of Kaleidoscope, the only
105 things that can be referenced are function parameters. As such, function
106 parameters will be in this map when generating code for their function
107 body.
108
109 With these basics in place, we can start talking about how to generate
110 code for each expression. Note that this assumes that the ``Builder``
111 has been set up to generate code *into* something. For now, we'll assume
112 that this has already been done, and we'll just use it to emit code.
113
114 Expression Code Generation
115 ==========================
116
117 Generating LLVM code for expression nodes is very straightforward: less
118 than 45 lines of commented code for all four of our expression nodes.
119 First we'll do numeric literals:
120
121 .. code-block:: c++
122
123 Value *NumberExprAST::codegen() {
124 return ConstantFP::get(LLVMContext, APFloat(Val));
125 }
126
127 In the LLVM IR, numeric constants are represented with the
128 ``ConstantFP`` class, which holds the numeric value in an ``APFloat``
129 internally (``APFloat`` has the capability of holding floating point
130 constants of Arbitrary Precision). This code basically just creates
131 and returns a ``ConstantFP``. Note that in the LLVM IR that constants
132 are all uniqued together and shared. For this reason, the API uses the
133 "foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
134
135 .. code-block:: c++
136
137 Value *VariableExprAST::codegen() {
138 // Look this variable up in the function.
139 Value *V = NamedValues[Name];
140 if (!V)
141 LogErrorV("Unknown variable name");
142 return V;
143 }
144
145 References to variables are also quite simple using LLVM. In the simple
146 version of Kaleidoscope, we assume that the variable has already been
147 emitted somewhere and its value is available. In practice, the only
148 values that can be in the ``NamedValues`` map are function arguments.
149 This code simply checks to see that the specified name is in the map (if
150 not, an unknown variable is being referenced) and returns the value for
151 it. In future chapters, we'll add support for `loop induction
152 variables `_ in the symbol table, and for `local
153 variables `_.
154
155 .. code-block:: c++
156
157 Value *BinaryExprAST::codegen() {
158 Value *L = LHS->codegen();
159 Value *R = RHS->codegen();
160 if (!L || !R)
161 return nullptr;
162
163 switch (Op) {
164 case '+':
165 return Builder.CreateFAdd(L, R, "addtmp");
166 case '-':
167 return Builder.CreateFSub(L, R, "subtmp");
168 case '*':
169 return Builder.CreateFMul(L, R, "multmp");
170 case '<':
171 L = Builder.CreateFCmpULT(L, R, "cmptmp");
172 // Convert bool 0/1 to double 0.0 or 1.0
173 return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
174 "booltmp");
175 default:
176 return LogErrorV("invalid binary operator");
177 }
178 }
179
180 Binary operators start to get more interesting. The basic idea here is
181 that we recursively emit code for the left-hand side of the expression,
182 then the right-hand side, then we compute the result of the binary
183 expression. In this code, we do a simple switch on the opcode to create
184 the right LLVM instruction.
185
186 In the example above, the LLVM builder class is starting to show its
187 value. IRBuilder knows where to insert the newly created instruction,
188 all you have to do is specify what instruction to create (e.g. with
189 ``CreateFAdd``), which operands to use (``L`` and ``R`` here) and
190 optionally provide a name for the generated instruction.
191
192 One nice thing about LLVM is that the name is just a hint. For instance,
193 if the code above emits multiple "addtmp" variables, LLVM will
194 automatically provide each one with an increasing, unique numeric
195 suffix. Local value names for instructions are purely optional, but it
196 makes it much easier to read the IR dumps.
197
198 `LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict
199 rules: for example, the Left and Right operators of an `add
200 instruction <../LangRef.html#add-instruction>`_ must have the same type, and the
201 result type of the add must match the operand types. Because all values
202 in Kaleidoscope are doubles, this makes for very simple code for add,
203 sub and mul.
204
205 On the other hand, LLVM specifies that the `fcmp
206 instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a
207 one bit integer). The problem with this is that Kaleidoscope wants the
208 value to be a 0.0 or 1.0 value. In order to get these semantics, we
209 combine the fcmp instruction with a `uitofp
210 instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its
211 input integer into a floating point value by treating the input as an
212 unsigned value. In contrast, if we used the `sitofp
213 instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
214 would return 0.0 and -1.0, depending on the input value.
215
216 .. code-block:: c++
217
218 Value *CallExprAST::codegen() {
219 // Look up the name in the global module table.
220 Function *CalleeF = TheModule->getFunction(Callee);
221 if (!CalleeF)
222 return LogErrorV("Unknown function referenced");
223
224 // If argument mismatch error.
225 if (CalleeF->arg_size() != Args.size())
226 return LogErrorV("Incorrect # arguments passed");
227
228 std::vector ArgsV;
229 for (unsigned i = 0, e = Args.size(); i != e; ++i) {
230 ArgsV.push_back(Args[i]->codegen());
231 if (!ArgsV.back())
232 return nullptr;
233 }
234
235 return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
236 }
237
238 Code generation for function calls is quite straightforward with LLVM. The code
239 above initially does a function name lookup in the LLVM Module's symbol table.
240 Recall that the LLVM Module is the container that holds the functions we are
241 JIT'ing. By giving each function the same name as what the user specifies, we
242 can use the LLVM symbol table to resolve function names for us.
243
244 Once we have the function to call, we recursively codegen each argument
245 that is to be passed in, and create an LLVM `call
246 instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C
247 calling conventions by default, allowing these calls to also call into
248 standard library functions like "sin" and "cos", with no additional
249 effort.
250
251 This wraps up our handling of the four basic expressions that we have so
252 far in Kaleidoscope. Feel free to go in and add some more. For example,
253 by browsing the `LLVM language reference <../LangRef.html>`_ you'll find
254 several other interesting instructions that are really easy to plug into
255 our basic framework.
256
257 Function Code Generation
258 ========================
259
260 Code generation for prototypes and functions must handle a number of
261 details, which make their code less beautiful than expression code
262 generation, but allows us to illustrate some important points. First,
263 lets talk about code generation for prototypes: they are used both for
264 function bodies and external function declarations. The code starts
265 with:
266
267 .. code-block:: c++
268
269 Function *PrototypeAST::codegen() {
270 // Make the function type: double(double,double) etc.
271 std::vector Doubles(Args.size(),
272 Type::getDoubleTy(LLVMContext));
273 FunctionType *FT =
274 FunctionType::get(Type::getDoubleTy(LLVMContext), Doubles, false);
275
276 Function *F =
277 Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
278
279 This code packs a lot of power into a few lines. Note first that this
280 function returns a "Function\*" instead of a "Value\*". Because a
281 "prototype" really talks about the external interface for a function
282 (not the value computed by an expression), it makes sense for it to
283 return the LLVM Function it corresponds to when codegen'd.
284
285 The call to ``FunctionType::get`` creates the ``FunctionType`` that
286 should be used for a given Prototype. Since all function arguments in
287 Kaleidoscope are of type double, the first line creates a vector of "N"
288 LLVM double types. It then uses the ``Functiontype::get`` method to
289 create a function type that takes "N" doubles as arguments, returns one
290 double as a result, and that is not vararg (the false parameter
291 indicates this). Note that Types in LLVM are uniqued just like Constants
292 are, so you don't "new" a type, you "get" it.
293
294 The final line above actually creates the IR Function corresponding to
295 the Prototype. This indicates the type, linkage and name to use, as
296 well as which module to insert into. "`external
297 linkage <../LangRef.html#linkage>`_" means that the function may be
298 defined outside the current module and/or that it is callable by
299 functions outside the module. The Name passed in is the name the user
300 specified: since "``TheModule``" is specified, this name is registered
301 in "``TheModule``"s symbol table.
302
303 .. code-block:: c++
304
305 // Set names for all arguments.
306 unsigned Idx = 0;
307 for (auto &Arg : F->args())
308 Arg.setName(Args[Idx++]);
309
310 return F;
311
312 Finally, we set the name of each of the function's arguments according to the
313 names given in the Prototype. This step isn't strictly necessary, but keeping
314 the names consistent makes the IR more readable, and allows subsequent code to
315 refer directly to the arguments for their names, rather than having to look up
316 them up in the Prototype AST.
317
318 At this point we have a function prototype with no body. This is how LLVM IR
319 represents function declarations. For extern statements in Kaleidoscope, this
320 is as far as we need to go. For function definitions however, we need to
321 codegen and attach a function body.
322
323 .. code-block:: c++
324
325 Function *FunctionAST::codegen() {
326 // First, check for an existing function from a previous 'extern' declaration.
327 Function *TheFunction = TheModule->getFunction(Proto->getName());
328
329 if (!TheFunction)
330 TheFunction = Proto->codegen();
331
332 if (!TheFunction)
333 return nullptr;
334
335 if (!TheFunction->empty())
336 return (Function*)LogErrorV("Function cannot be redefined.");
337
338
339 For function definitions, we start by searching TheModule's symbol table for an
340 existing version of this function, in case one has already been created using an
341 'extern' statement. If Module::getFunction returns null then no previous version
342 exists, so we'll codegen one from the Prototype. In either case, we want to
343 assert that the function is empty (i.e. has no body yet) before we start.
344
345 .. code-block:: c++
346
347 // Create a new basic block to start insertion into.
348 BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
349 Builder.SetInsertPoint(BB);
350
351 // Record the function arguments in the NamedValues map.
352 NamedValues.clear();
353 for (auto &Arg : TheFunction->args())
354 NamedValues[Arg.getName()] = &Arg;
355
356 Now we get to the point where the ``Builder`` is set up. The first line
357 creates a new `basic block `_
358 (named "entry"), which is inserted into ``TheFunction``. The second line
359 then tells the builder that new instructions should be inserted into the
360 end of the new basic block. Basic blocks in LLVM are an important part
361 of functions that define the `Control Flow
362 Graph `_. Since we
363 don't have any control flow, our functions will only contain one block
364 at this point. We'll fix this in `Chapter 5 `_ :).
365
366 Next we add the function arguments to the NamedValues map (after first clearing
367 it out) so that they're accessible to ``VariableExprAST`` nodes.
368
369 .. code-block:: c++
370
371 if (Value *RetVal = Body->codegen()) {
372 // Finish off the function.
373 Builder.CreateRet(RetVal);
374
375 // Validate the generated code, checking for consistency.
376 verifyFunction(*TheFunction);
377
378 return TheFunction;
379 }
380
381 Once the insertion point has been set up and the NamedValues map populated,
382 we call the ``codegen()`` method for the root expression of the function. If no
383 error happens, this emits code to compute the expression into the entry block
384 and returns the value that was computed. Assuming no error, we then create an
385 LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.
386 Once the function is built, we call ``verifyFunction``, which is
387 provided by LLVM. This function does a variety of consistency checks on
388 the generated code, to determine if our compiler is doing everything
389 right. Using this is important: it can catch a lot of bugs. Once the
390 function is finished and validated, we return it.
391
392 .. code-block:: c++
393
394 // Error reading body, remove function.
395 TheFunction->eraseFromParent();
396 return nullptr;
397 }
398
399 The only piece left here is handling of the error case. For simplicity,
400 we handle this by merely deleting the function we produced with the
401 ``eraseFromParent`` method. This allows the user to redefine a function
402 that they incorrectly typed in before: if we didn't delete it, it would
403 live in the symbol table, with a body, preventing future redefinition.
404
405 This code does have a bug, though: If the ``FunctionAST::codegen()`` method
406 finds an existing IR Function, it does not validate its signature against the
407 definition's own prototype. This means that an earlier 'extern' declaration will
408 take precedence over the function definition's signature, which can cause
409 codegen to fail, for instance if the function arguments are named differently.
410 There are a number of ways to fix this bug, see what you can come up with! Here
411 is a testcase:
412
413 ::
414
415 extern foo(a); # ok, defines foo.
416 def foo(b) b; # Error: Unknown variable name. (decl using 'a' takes precedence).
417
418 Driver Changes and Closing Thoughts
419 ===================================
420
421 For now, code generation to LLVM doesn't really get us much, except that
422 we can look at the pretty IR calls. The sample code inserts calls to
423 codegen into the "``HandleDefinition``", "``HandleExtern``" etc
424 functions, and then dumps out the LLVM IR. This gives a nice way to look
425 at the LLVM IR for simple functions. For example:
426
427 ::
428
429 ready> 4+5;
430 Read top-level expression:
431 define double @0() {
432 entry:
433 ret double 9.000000e+00
434 }
435
436 Note how the parser turns the top-level expression into anonymous
437 functions for us. This will be handy when we add `JIT
438 support `_ in the next chapter. Also note that the
439 code is very literally transcribed, no optimizations are being performed
440 except simple constant folding done by IRBuilder. We will `add
441 optimizations `_ explicitly in the next
442 chapter.
443
444 ::
445
446 ready> def foo(a b) a*a + 2*a*b + b*b;
447 Read function definition:
448 define double @foo(double %a, double %b) {
449 entry:
450 %multmp = fmul double %a, %a
451 %multmp1 = fmul double 2.000000e+00, %a
452 %multmp2 = fmul double %multmp1, %b
453 %addtmp = fadd double %multmp, %multmp2
454 %multmp3 = fmul double %b, %b
455 %addtmp4 = fadd double %addtmp, %multmp3
456 ret double %addtmp4
457 }
458
459 This shows some simple arithmetic. Notice the striking similarity to the
460 LLVM builder calls that we use to create the instructions.
461
462 ::
463
464 ready> def bar(a) foo(a, 4.0) + bar(31337);
465 Read function definition:
466 define double @bar(double %a) {
467 entry:
468 %calltmp = call double @foo(double %a, double 4.000000e+00)
469 %calltmp1 = call double @bar(double 3.133700e+04)
470 %addtmp = fadd double %calltmp, %calltmp1
471 ret double %addtmp
472 }
473
474 This shows some function calls. Note that this function will take a long
475 time to execute if you call it. In the future we'll add conditional
476 control flow to actually make recursion useful :).
477
478 ::
479
480 ready> extern cos(x);
481 Read extern:
482 declare double @cos(double)
483
484 ready> cos(1.234);
485 Read top-level expression:
486 define double @1() {
487 entry:
488 %calltmp = call double @cos(double 1.234000e+00)
489 ret double %calltmp
490 }
491
492 This shows an extern for the libm "cos" function, and a call to it.
493
494 .. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up
495 on highlighting this due to the first line.
496
497 ::
498
499 ready> ^D
500 ; ModuleID = 'my cool jit'
501
502 define double @0() {
503 entry:
504 %addtmp = fadd double 4.000000e+00, 5.000000e+00
505 ret double %addtmp
506 }
507
508 define double @foo(double %a, double %b) {
509 entry:
510 %multmp = fmul double %a, %a
511 %multmp1 = fmul double 2.000000e+00, %a
512 %multmp2 = fmul double %multmp1, %b
513 %addtmp = fadd double %multmp, %multmp2
514 %multmp3 = fmul double %b, %b
515 %addtmp4 = fadd double %addtmp, %multmp3
516 ret double %addtmp4
517 }
518
519 define double @bar(double %a) {
520 entry:
521 %calltmp = call double @foo(double %a, double 4.000000e+00)
522 %calltmp1 = call double @bar(double 3.133700e+04)
523 %addtmp = fadd double %calltmp, %calltmp1
524 ret double %addtmp
525 }
526
527 declare double @cos(double)
528
529 define double @1() {
530 entry:
531 %calltmp = call double @cos(double 1.234000e+00)
532 ret double %calltmp
533 }
534
535 When you quit the current demo, it dumps out the IR for the entire
536 module generated. Here you can see the big picture with all the
537 functions referencing each other.
538
539 This wraps up the third chapter of the Kaleidoscope tutorial. Up next,
540 we'll describe how to `add JIT codegen and optimizer
541 support `_ to this so we can actually start running
542 code!
543
544 Full Code Listing
545 =================
546
547 Here is the complete code listing for our running example, enhanced with
548 the LLVM code generator. Because this uses the LLVM libraries, we need
549 to link them in. To do this, we use the
550 `llvm-config `_ tool to inform
551 our makefile/command line about which options to use:
552
553 .. code-block:: bash
554
555 # Compile
556 clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy
557 # Run
558 ./toy
559
560 Here is the code:
561
562 .. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp
563 :language: c++
564
565 `Next: Adding JIT and Optimizer Support `_
566
0 ==============================================
1 Kaleidoscope: Adding JIT and Optimizer Support
2 ==============================================
3
4 .. contents::
5 :local:
6
7 Chapter 4 Introduction
8 ======================
9
10 Welcome to Chapter 4 of the "`Implementing a language with
11 LLVM `_" tutorial. Chapters 1-3 described the implementation
12 of a simple language and added support for generating LLVM IR. This
13 chapter describes two new techniques: adding optimizer support to your
14 language, and adding JIT compiler support. These additions will
15 demonstrate how to get nice, efficient code for the Kaleidoscope
16 language.
17
18 Trivial Constant Folding
19 ========================
20
21 Our demonstration for Chapter 3 is elegant and easy to extend.
22 Unfortunately, it does not produce wonderful code. The IRBuilder,
23 however, does give us obvious optimizations when compiling simple code:
24
25 ::
26
27 ready> def test(x) 1+2+x;
28 Read function definition:
29 define double @test(double %x) {
30 entry:
31 %addtmp = fadd double 3.000000e+00, %x
32 ret double %addtmp
33 }
34
35 This code is not a literal transcription of the AST built by parsing the
36 input. That would be:
37
38 ::
39
40 ready> def test(x) 1+2+x;
41 Read function definition:
42 define double @test(double %x) {
43 entry:
44 %addtmp = fadd double 2.000000e+00, 1.000000e+00
45 %addtmp1 = fadd double %addtmp, %x
46 ret double %addtmp1
47 }
48
49 Constant folding, as seen above, in particular, is a very common and
50 very important optimization: so much so that many language implementors
51 implement constant folding support in their AST representation.
52
53 With LLVM, you don't need this support in the AST. Since all calls to
54 build LLVM IR go through the LLVM IR builder, the builder itself checked
55 to see if there was a constant folding opportunity when you call it. If
56 so, it just does the constant fold and return the constant instead of
57 creating an instruction.
58
59 Well, that was easy :). In practice, we recommend always using
60 ``IRBuilder`` when generating code like this. It has no "syntactic
61 overhead" for its use (you don't have to uglify your compiler with
62 constant checks everywhere) and it can dramatically reduce the amount of
63 LLVM IR that is generated in some cases (particular for languages with a
64 macro preprocessor or that use a lot of constants).
65
66 On the other hand, the ``IRBuilder`` is limited by the fact that it does
67 all of its analysis inline with the code as it is built. If you take a
68 slightly more complex example:
69
70 ::
71
72 ready> def test(x) (1+2+x)*(x+(1+2));
73 ready> Read function definition:
74 define double @test(double %x) {
75 entry:
76 %addtmp = fadd double 3.000000e+00, %x
77 %addtmp1 = fadd double %x, 3.000000e+00
78 %multmp = fmul double %addtmp, %addtmp1
79 ret double %multmp
80 }
81
82 In this case, the LHS and RHS of the multiplication are the same value.
83 We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"
84 instead of computing "``x+3``" twice.
85
86 Unfortunately, no amount of local analysis will be able to detect and
87 correct this. This requires two transformations: reassociation of
88 expressions (to make the add's lexically identical) and Common
89 Subexpression Elimination (CSE) to delete the redundant add instruction.
90 Fortunately, LLVM provides a broad range of optimizations that you can
91 use, in the form of "passes".
92
93 LLVM Optimization Passes
94 ========================
95
96 LLVM provides many optimization passes, which do many different sorts of
97 things and have different tradeoffs. Unlike other systems, LLVM doesn't
98 hold to the mistaken notion that one set of optimizations is right for
99 all languages and for all situations. LLVM allows a compiler implementor
100 to make complete decisions about what optimizations to use, in which
101 order, and in what situation.
102
103 As a concrete example, LLVM supports both "whole module" passes, which
104 look across as large of body of code as they can (often a whole file,
105 but if run at link time, this can be a substantial portion of the whole
106 program). It also supports and includes "per-function" passes which just
107 operate on a single function at a time, without looking at other
108 functions. For more information on passes and how they are run, see the
109 `How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the
110 `List of LLVM Passes <../Passes.html>`_.
111
112 For Kaleidoscope, we are currently generating functions on the fly, one
113 at a time, as the user types them in. We aren't shooting for the
114 ultimate optimization experience in this setting, but we also want to
115 catch the easy and quick stuff where possible. As such, we will choose
116 to run a few per-function optimizations as the user types the function
117 in. If we wanted to make a "static Kaleidoscope compiler", we would use
118 exactly the code we have now, except that we would defer running the
119 optimizer until the entire file has been parsed.
120
121 In order to get per-function optimizations going, we need to set up a
122 `FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
123 and organize the LLVM optimizations that we want to run. Once we have
124 that, we can add a set of optimizations to run. We'll need a new
125 FunctionPassManager for each module that we want to optimize, so we'll
126 write a function to create and initialize both the module and pass manager
127 for us:
128
129 .. code-block:: c++
130
131 void InitializeModuleAndPassManager(void) {
132 // Open a new module.
133 Context LLVMContext;
134 TheModule = llvm::make_unique("my cool jit", LLVMContext);
135 TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
136
137 // Create a new pass manager attached to it.
138 TheFPM = llvm::make_unique(TheModule.get());
139
140 // Provide basic AliasAnalysis support for GVN.
141 TheFPM.add(createBasicAliasAnalysisPass());
142 // Do simple "peephole" optimizations and bit-twiddling optzns.
143 TheFPM.add(createInstructionCombiningPass());
144 // Reassociate expressions.
145 TheFPM.add(createReassociatePass());
146 // Eliminate Common SubExpressions.
147 TheFPM.add(createGVNPass());
148 // Simplify the control flow graph (deleting unreachable blocks, etc).
149 TheFPM.add(createCFGSimplificationPass());
150
151 TheFPM.doInitialization();
152 }
153
154 This code initializes the global module ``TheModule``, and the function pass
155 manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
156 set up, we use a series of "add" calls to add a bunch of LLVM passes.
157
158 In this case, we choose to add five passes: one analysis pass (alias analysis),
159 and four optimization passes. The passes we choose here are a pretty standard set
160 of "cleanup" optimizations that are useful for a wide variety of code. I won't
161 delve into what they do but, believe me, they are a good starting place :).
162
163 Once the PassManager is set up, we need to make use of it. We do this by
164 running it after our newly created function is constructed (in
165 ``FunctionAST::codegen()``), but before it is returned to the client:
166
167 .. code-block:: c++
168
169 if (Value *RetVal = Body->codegen()) {
170 // Finish off the function.
171 Builder.CreateRet(RetVal);
172
173 // Validate the generated code, checking for consistency.
174 verifyFunction(*TheFunction);
175
176 // Optimize the function.
177 TheFPM->run(*TheFunction);
178
179 return TheFunction;
180 }
181
182 As you can see, this is pretty straightforward. The
183 ``FunctionPassManager`` optimizes and updates the LLVM Function\* in
184 place, improving (hopefully) its body. With this in place, we can try
185 our test above again:
186
187 ::
188
189 ready> def test(x) (1+2+x)*(x+(1+2));
190 ready> Read function definition:
191 define double @test(double %x) {
192 entry:
193 %addtmp = fadd double %x, 3.000000e+00
194 %multmp = fmul double %addtmp, %addtmp
195 ret double %multmp
196 }
197
198 As expected, we now get our nicely optimized code, saving a floating
199 point add instruction from every execution of this function.
200
201 LLVM provides a wide variety of optimizations that can be used in
202 certain circumstances. Some `documentation about the various
203 passes <../Passes.html>`_ is available, but it isn't very complete.
204 Another good source of ideas can come from looking at the passes that
205 ``Clang`` runs to get started. The "``opt``" tool allows you to
206 experiment with passes from the command line, so you can see if they do
207 anything.
208
209 Now that we have reasonable code coming out of our front-end, lets talk
210 about executing it!
211
212 Adding a JIT Compiler
213 =====================
214
215 Code that is available in LLVM IR can have a wide variety of tools
216 applied to it. For example, you can run optimizations on it (as we did
217 above), you can dump it out in textual or binary forms, you can compile
218 the code to an assembly file (.s) for some target, or you can JIT
219 compile it. The nice thing about the LLVM IR representation is that it
220 is the "common currency" between many different parts of the compiler.
221
222 In this section, we'll add JIT compiler support to our interpreter. The
223 basic idea that we want for Kaleidoscope is to have the user enter
224 function bodies as they do now, but immediately evaluate the top-level
225 expressions they type in. For example, if they type in "1 + 2;", we
226 should evaluate and print out 3. If they define a function, they should
227 be able to call it from the command line.
228
229 In order to do this, we first declare and initialize the JIT. This is
230 done by adding a global variable ``TheJIT``, and initializing it in
231 ``main``:
232
233 .. code-block:: c++
234
235 static std::unique_ptr TheJIT;
236 ...
237 int main() {
238 ..
239 TheJIT = llvm::make_unique();
240
241 // Run the main "interpreter loop" now.
242 MainLoop();
243
244 return 0;
245 }
246
247 The KaleidoscopeJIT class is a simple JIT built specifically for these
248 tutorials. In later chapters we will look at how it works and extend it with
249 new features, but for now we will take it as given. Its API is very simple::
250 ``addModule`` adds an LLVM IR module to the JIT, making its functions
251 available for execution; ``removeModule`` removes a module, freeing any
252 memory associated with the code in that module; and ``findSymbol`` allows us
253 to look up pointers to the compiled code.
254
255 We can take this simple API and change our code that parses top-level expressions to
256 look like this:
257
258 .. code-block:: c++
259
260 static void HandleTopLevelExpression() {
261 // Evaluate a top-level expression into an anonymous function.
262 if (auto FnAST = ParseTopLevelExpr()) {
263 if (FnAST->codegen()) {
264
265 // JIT the module containing the anonymous expression, keeping a handle so
266 // we can free it later.
267 auto H = TheJIT->addModule(std::move(TheModule));
268 InitializeModuleAndPassManager();
269
270 // Search the JIT for the __anon_expr symbol.
271 auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
272 assert(ExprSymbol && "Function not found");
273
274 // Get the symbol's address and cast it to the right type (takes no
275 // arguments, returns a double) so we can call it as a native function.
276 double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
277 fprintf(stderr, "Evaluated to %f\n", FP());
278
279 // Delete the anonymous expression module from the JIT.
280 TheJIT->removeModule(H);
281 }
282
283 If parsing and codegen succeeed, the next step is to add the module containing
284 the top-level expression to the JIT. We do this by calling addModule, which
285 triggers code generation for all the functions in the module, and returns a
286 handle that can be used to remove the module from the JIT later. Once the module
287 has been added to the JIT it can no longer be modified, so we also open a new
288 module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.
289
290 Once we've added the module to the JIT we need to get a pointer to the final
291 generated code. We do this by calling the JIT's findSymbol method, and passing
292 the name of the top-level expression function: ``__anon_expr``. Since we just
293 added this function, we assert that findSymbol returned a result.
294
295 Next, we get the in-memory address of the ``__anon_expr`` function by calling
296 ``getAddress()`` on the symbol. Recall that we compile top-level expressions
297 into a self-contained LLVM function that takes no arguments and returns the
298 computed double. Because the LLVM JIT compiler matches the native platform ABI,
299 this means that you can just cast the result pointer to a function pointer of
300 that type and call it directly. This means, there is no difference between JIT
301 compiled code and native machine code that is statically linked into your
302 application.
303
304 Finally, since we don't support re-evaluation of top-level expressions, we
305 remove the module from the JIT when we're done to free the associated memory.
306 Recall, however, that the module we created a few lines earlier (via
307 ``InitializeModuleAndPassManager``) is still open and waiting for new code to be
308 added.
309
310 With just these two changes, lets see how Kaleidoscope works now!
311
312 ::
313
314 ready> 4+5;
315 Read top-level expression:
316 define double @0() {
317 entry:
318 ret double 9.000000e+00
319 }
320
321 Evaluated to 9.000000
322
323 Well this looks like it is basically working. The dump of the function
324 shows the "no argument function that always returns double" that we
325 synthesize for each top-level expression that is typed in. This
326 demonstrates very basic functionality, but can we do more?
327
328 ::
329
330 ready> def testfunc(x y) x + y*2;
331 Read function definition:
332 define double @testfunc(double %x, double %y) {
333 entry:
334 %multmp = fmul double %y, 2.000000e+00
335 %addtmp = fadd double %multmp, %x
336 ret double %addtmp
337 }
338
339 ready> testfunc(4, 10);
340 Read top-level expression:
341 define double @1() {
342 entry:
343 %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
344 ret double %calltmp
345 }
346
347 Evaluated to 24.000000
348
349 ready> testfunc(5, 10);
350 ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!
351
352
353 Function definitions and calls also work, but something went very wrong on that
354 last line. The call looks valid, so what happened? As you may have guessed from
355 the the API a Module is a unit of allocation for the JIT, and testfunc was part
356 of the same module that contained anonymous expression. When we removed that
357 module from the JIT to free the memory for the anonymous expression, we deleted
358 the definition of ``testfunc`` along with it. Then, when we tried to call
359 testfunc a second time, the JIT could no longer find it.
360
361 The easiest way to fix this is to put the anonymous expression in a separate
362 module from the rest of the function definitions. The JIT will happily resolve
363 function calls across module boundaries, as long as each of the functions called
364 has a prototype, and is added to the JIT before it is called. By putting the
365 anonymous expression in a different module we can delete it without affecting
366 the rest of the functions.
367
368 In fact, we're going to go a step further and put every function in its own
369 module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT
370 that will make our environment more REPL-like: Functions can be added to the
371 JIT more than once (unlike a module where every function must have a unique
372 definition). When you look up a symbol in KaleidoscopeJIT it will always return
373 the most recent definition:
374
375 ::
376
377 ready> def foo(x) x + 1;
378 Read function definition:
379 define double @foo(double %x) {
380 entry:
381 %addtmp = fadd double %x, 1.000000e+00
382 ret double %addtmp
383 }
384
385 ready> foo(2);
386 Evaluated to 3.000000
387
388 ready> def foo(x) x + 2;
389 define double @foo(double %x) {
390 entry:
391 %addtmp = fadd double %x, 2.000000e+00
392 ret double %addtmp
393 }
394
395 ready> foo(2);
396 Evaluated to 4.000000
397
398
399 To allow each function to live in its own module we'll need a way to
400 re-generate previous function declarations into each new module we open:
401
402 .. code-block:: c++
403
404 static std::unique_ptr TheJIT;
405
406 ...
407
408 Function *getFunction(std::string Name) {
409 // First, see if the function has already been added to the current module.
410 if (auto *F = TheModule->getFunction(Name))
411 return F;
412
413 // If not, check whether we can codegen the declaration from some existing
414 // prototype.
415 auto FI = FunctionProtos.find(Name);
416 if (FI != FunctionProtos.end())
417 return FI->second->codegen();
418
419 // If no existing prototype exists, return null.
420 return nullptr;
421 }
422
423 ...
424
425 Value *CallExprAST::codegen() {
426 // Look up the name in the global module table.
427 Function *CalleeF = getFunction(Callee);
428
429 ...
430
431 Function *FunctionAST::codegen() {
432 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
433 // reference to it for use below.
434 auto &P = *Proto;
435 FunctionProtos[Proto->getName()] = std::move(Proto);
436 Function *TheFunction = getFunction(P.getName());
437 if (!TheFunction)
438 return nullptr;
439
440
441 To enable this, we'll start by adding a new global, ``FunctionProtos``, that
442 holds the most recent prototype for each function. We'll also add a convenience
443 method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.
444 Our convenience method searches ``TheModule`` for an existing function
445 declaration, falling back to generating a new declaration from FunctionProtos if
446 it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the
447 call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to
448 update the FunctionProtos map first, then call ``getFunction()``. With this
449 done, we can always obtain a function declaration in the current module for any
450 previously declared function.
451
452 We also need to update HandleDefinition and HandleExtern:
453
454 .. code-block:: c++
455
456 static void HandleDefinition() {
457 if (auto FnAST = ParseDefinition()) {
458 if (auto *FnIR = FnAST->codegen()) {
459 fprintf(stderr, "Read function definition:");
460 FnIR->dump();
461 TheJIT->addModule(std::move(TheModule));
462 InitializeModuleAndPassManager();
463 }
464 } else {
465 // Skip token for error recovery.
466 getNextToken();
467 }
468 }
469
470 static void HandleExtern() {
471 if (auto ProtoAST = ParseExtern()) {
472 if (auto *FnIR = ProtoAST->codegen()) {
473 fprintf(stderr, "Read extern: ");
474 FnIR->dump();
475 FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
476 }
477 } else {
478 // Skip token for error recovery.
479 getNextToken();
480 }
481 }
482
483 In HandleDefinition, we add two lines to transfer the newly defined function to
484 the JIT and open a new module. In HandleExtern, we just need to add one line to
485 add the prototype to FunctionProtos.
486
487 With these changes made, lets try our REPL again (I removed the dump of the
488 anonymous functions this time, you should get the idea by now :) :
489
490 ::
491
492 ready> def foo(x) x + 1;
493 ready> foo(2);
494 Evaluated to 3.000000
495
496 ready> def foo(x) x + 2;
497 ready> foo(2);
498 Evaluated to 4.000000
499
500 It works!
501
502 Even with this simple code, we get some surprisingly powerful capabilities -
503 check this out:
504
505 ::
506
507 ready> extern sin(x);
508 Read extern:
509 declare double @sin(double)
510
511 ready> extern cos(x);
512 Read extern:
513 declare double @cos(double)
514
515 ready> sin(1.0);
516 Read top-level expression:
517 define double @2() {
518 entry:
519 ret double 0x3FEAED548F090CEE
520 }
521
522 Evaluated to 0.841471
523
524 ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
525 Read function definition:
526 define double @foo(double %x) {
527 entry:
528 %calltmp = call double @sin(double %x)
529 %multmp = fmul double %calltmp, %calltmp
530 %calltmp2 = call double @cos(double %x)
531 %multmp4 = fmul double %calltmp2, %calltmp2
532 %addtmp = fadd double %multmp, %multmp4
533 ret double %addtmp
534 }
535
536 ready> foo(4.0);
537 Read top-level expression:
538 define double @3() {
539 entry:
540 %calltmp = call double @foo(double 4.000000e+00)
541 ret double %calltmp
542 }
543
544 Evaluated to 1.000000
545
546 Whoa, how does the JIT know about sin and cos? The answer is surprisingly
547 simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that
548 it uses to find symbols that aren't available in any given module: First
549 it searches all the modules that have already been added to the JIT, from the
550 most recent to the oldest, to find the newest definition. If no definition is
551 found inside the JIT, it falls back to calling "``dlsym("sin")``" on the
552 Kaleidoscope process itself. Since "``sin``" is defined within the JIT's
553 address space, it simply patches up calls in the module to call the libm
554 version of ``sin`` directly.
555
556 In the future we'll see how tweaking this symbol resolution rule can be used to
557 enable all sorts of useful features, from security (restricting the set of
558 symbols available to JIT'd code), to dynamic code generation based on symbol
559 names, and even lazy compilation.
560
561 One immediate benefit of the symbol resolution rule is that we can now extend
562 the language by writing arbitrary C++ code to implement operations. For example,
563 if we add:
564
565 .. code-block:: c++
566
567 /// putchard - putchar that takes a double and returns 0.
568 extern "C" double putchard(double X) {
569 fputc((char)X, stderr);
570 return 0;
571 }
572
573 Now we can produce simple output to the console by using things like:
574 "``extern putchard(x); putchard(120);``", which prints a lowercase 'x'
575 on the console (120 is the ASCII code for 'x'). Similar code could be
576 used to implement file I/O, console input, and many other capabilities
577 in Kaleidoscope.
578
579 This completes the JIT and optimizer chapter of the Kaleidoscope
580 tutorial. At this point, we can compile a non-Turing-complete
581 programming language, optimize and JIT compile it in a user-driven way.
582 Next up we'll look into `extending the language with control flow
583 constructs `_, tackling some interesting LLVM IR issues
584 along the way.
585
586 Full Code Listing
587 =================
588
589 Here is the complete code listing for our running example, enhanced with
590 the LLVM JIT and optimizer. To build this example, use:
591
592 .. code-block:: bash
593
594 # Compile
595 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
596 # Run
597 ./toy
598
599 If you are compiling this on Linux, make sure to add the "-rdynamic"
600 option as well. This makes sure that the external functions are resolved
601 properly at runtime.
602
603 Here is the code:
604
605 .. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp
606 :language: c++
607
608 `Next: Extending the language: control flow `_
609
0 ==================================================
1 Kaleidoscope: Extending the Language: Control Flow
2 ==================================================
3
4 .. contents::
5 :local:
6
7 Chapter 5 Introduction
8 ======================
9
10 Welcome to Chapter 5 of the "`Implementing a language with
11 LLVM `_" tutorial. Parts 1-4 described the implementation of
12 the simple Kaleidoscope language and included support for generating
13 LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as
14 presented, Kaleidoscope is mostly useless: it has no control flow other
15 than call and return. This means that you can't have conditional
16 branches in the code, significantly limiting its power. In this episode
17 of "build that compiler", we'll extend Kaleidoscope to have an
18 if/then/else expression plus a simple 'for' loop.
19
20 If/Then/Else
21 ============
22
23 Extending Kaleidoscope to support if/then/else is quite straightforward.
24 It basically requires adding support for this "new" concept to the
25 lexer, parser, AST, and LLVM code emitter. This example is nice, because
26 it shows how easy it is to "grow" a language over time, incrementally
27 extending it as new ideas are discovered.
28
29 Before we get going on "how" we add this extension, lets talk about
30 "what" we want. The basic idea is that we want to be able to write this
31 sort of thing:
32
33 ::
34
35 def fib(x)
36 if x < 3 then
37 1
38 else
39 fib(x-1)+fib(x-2);
40
41 In Kaleidoscope, every construct is an expression: there are no
42 statements. As such, the if/then/else expression needs to return a value
43 like any other. Since we're using a mostly functional form, we'll have
44 it evaluate its conditional, then return the 'then' or 'else' value
45 based on how the condition was resolved. This is very similar to the C
46 "?:" expression.
47
48 The semantics of the if/then/else expression is that it evaluates the
49 condition to a boolean equality value: 0.0 is considered to be false and
50 everything else is considered to be true. If the condition is true, the
51 first subexpression is evaluated and returned, if the condition is
52 false, the second subexpression is evaluated and returned. Since
53 Kaleidoscope allows side-effects, this behavior is important to nail
54 down.
55
56 Now that we know what we "want", lets break this down into its
57 constituent pieces.
58
59 Lexer Extensions for If/Then/Else
60 ---------------------------------
61
62 The lexer extensions are straightforward. First we add new enum values
63 for the relevant tokens:
64
65 .. code-block:: c++
66
67 // control
68 tok_if = -6,
69 tok_then = -7,
70 tok_else = -8,
71
72 Once we have that, we recognize the new keywords in the lexer. This is
73 pretty simple stuff:
74
75 .. code-block:: c++
76
77 ...
78 if (IdentifierStr == "def")
79 return tok_def;
80 if (IdentifierStr == "extern")
81 return tok_extern;
82 if (IdentifierStr == "if")
83 return tok_if;
84 if (IdentifierStr == "then")
85 return tok_then;
86 if (IdentifierStr == "else")
87 return tok_else;
88 return tok_identifier;
89
90 AST Extensions for If/Then/Else
91 -------------------------------
92
93 To represent the new expression we add a new AST node for it:
94
95 .. code-block:: c++
96
97 /// IfExprAST - Expression class for if/then/else.
98 class IfExprAST : public ExprAST {
99 std::unique_ptr Cond, Then, Else;
100
101 public:
102 IfExprAST(std::unique_ptr Cond, std::unique_ptr Then,
103 std::unique_ptr Else)
104 : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
105 virtual Value *codegen();
106 };
107
108 The AST node just has pointers to the various subexpressions.
109
110 Parser Extensions for If/Then/Else
111 ----------------------------------
112
113 Now that we have the relevant tokens coming from the lexer and we have
114 the AST node to build, our parsing logic is relatively straightforward.
115 First we define a new parsing function:
116
117 .. code-block:: c++
118
119 /// ifexpr ::= 'if' expression 'then' expression 'else' expression
120 static std::unique_ptr ParseIfExpr() {
121 getNextToken(); // eat the if.
122
123 // condition.
124 auto Cond = ParseExpression();
125 if (!Cond)
126 return nullptr;
127
128 if (CurTok != tok_then)
129 return LogError("expected then");
130 getNextToken(); // eat the then
131
132 auto Then = ParseExpression();
133 if (!Then)
134 return nullptr;
135
136 if (CurTok != tok_else)
137 return LogError("expected else");
138
139 getNextToken();
140
141 auto Else = ParseExpression();
142 if (!Else)
143 return nullptr;
144
145 return llvm::make_unique(std::move(Cond), std::move(Then),
146 std::move(Else));
147 }
148
149 Next we hook it up as a primary expression:
150
151 .. code-block:: c++
152
153 static std::unique_ptr ParsePrimary() {
154 switch (CurTok) {
155 default:
156 return LogError("unknown token when expecting an expression");
157 case tok_identifier:
158 return ParseIdentifierExpr();
159 case tok_number:
160 return ParseNumberExpr();
161 case '(':
162 return ParseParenExpr();
163 case tok_if:
164 return ParseIfExpr();
165 }
166 }
167
168 LLVM IR for If/Then/Else
169 ------------------------
170
171 Now that we have it parsing and building the AST, the final piece is
172 adding LLVM code generation support. This is the most interesting part
173 of the if/then/else example, because this is where it starts to
174 introduce new concepts. All of the code above has been thoroughly
175 described in previous chapters.
176
177 To motivate the code we want to produce, lets take a look at a simple
178 example. Consider:
179
180 ::
181
182 extern foo();
183 extern bar();
184 def baz(x) if x then foo() else bar();
185
186 If you disable optimizations, the code you'll (soon) get from
187 Kaleidoscope looks like this:
188
189 .. code-block:: llvm
190
191 declare double @foo()
192
193 declare double @bar()
194
195 define double @baz(double %x) {
196 entry:
197 %ifcond = fcmp one double %x, 0.000000e+00
198 br i1 %ifcond, label %then, label %else
199
200 then: ; preds = %entry
201 %calltmp = call double @foo()
202 br label %ifcont
203
204 else: ; preds = %entry
205 %calltmp1 = call double @bar()
206 br label %ifcont
207
208 ifcont: ; preds = %else, %then
209 %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
210 ret double %iftmp
211 }
212
213 To visualize the control flow graph, you can use a nifty feature of the
214 LLVM '`opt `_' tool. If you put this LLVM
215 IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
216 window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
217 see this graph:
218
219 .. figure:: LangImpl05-cfg.png
220 :align: center
221 :alt: Example CFG
222
223 Example CFG
224
225 Another way to get this is to call "``F->viewCFG()``" or
226 "``F->viewCFGOnly()``" (where F is a "``Function*``") either by
227 inserting actual calls into the code and recompiling or by calling these
228 in the debugger. LLVM has many nice features for visualizing various
229 graphs.
230
231 Getting back to the generated code, it is fairly simple: the entry block
232 evaluates the conditional expression ("x" in our case here) and compares
233 the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered
234 and Not Equal"). Based on the result of this expression, the code jumps
235 to either the "then" or "else" blocks, which contain the expressions for
236 the true/false cases.
237
238 Once the then/else blocks are finished executing, they both branch back
239 to the 'ifcont' block to execute the code that happens after the
240 if/then/else. In this case the only thing left to do is to return to the
241 caller of the function. The question then becomes: how does the code
242 know which expression to return?
243
244 The answer to this question involves an important SSA operation: the
245 `Phi
246 operation `_.
247 If you're not familiar with SSA, `the wikipedia
248 article `_
249 is a good introduction and there are various other introductions to it
250 available on your favorite search engine. The short version is that
251 "execution" of the Phi operation requires "remembering" which block
252 control came from. The Phi operation takes on the value corresponding to
253 the input control block. In this case, if control comes in from the
254 "then" block, it gets the value of "calltmp". If control comes from the
255 "else" block, it gets the value of "calltmp1".
256
257 At this point, you are probably starting to think "Oh no! This means my
258 simple and elegant front-end will have to start generating SSA form in
259 order to use LLVM!". Fortunately, this is not the case, and we strongly
260 advise *not* implementing an SSA construction algorithm in your
261 front-end unless there is an amazingly good reason to do so. In
262 practice, there are two sorts of values that float around in code
263 written for your average imperative programming language that might need
264 Phi nodes:
265
266 #. Code that involves user variables: ``x = 1; x = x + 1;``
267 #. Values that are implicit in the structure of your AST, such as the
268 Phi node in this case.
269
270 In `Chapter 7 `_ of this tutorial ("mutable variables"),
271 we'll talk about #1 in depth. For now, just believe me that you don't
272 need SSA construction to handle this case. For #2, you have the choice
273 of using the techniques that we will describe for #1, or you can insert
274 Phi nodes directly, if convenient. In this case, it is really
275 easy to generate the Phi node, so we choose to do it directly.
276
277 Okay, enough of the motivation and overview, lets generate code!
278
279 Code Generation for If/Then/Else
280 --------------------------------
281
282 In order to generate code for this, we implement the ``codegen`` method
283 for ``IfExprAST``:
284
285 .. code-block:: c++
286
287 Value *IfExprAST::codegen() {
288 Value *CondV = Cond->codegen();
289 if (!CondV)
290 return nullptr;
291
292 // Convert condition to a bool by comparing equal to 0.0.
293 CondV = Builder.CreateFCmpONE(
294 CondV, ConstantFP::get(LLVMContext, APFloat(0.0)), "ifcond");
295
296 This code is straightforward and similar to what we saw before. We emit
297 the expression for the condition, then compare that value to zero to get
298 a truth value as a 1-bit (bool) value.
299
300 .. code-block:: c++
301
302 Function *TheFunction = Builder.GetInsertBlock()->getParent();
303
304 // Create blocks for the then and else cases. Insert the 'then' block at the
305 // end of the function.
306 BasicBlock *ThenBB =
307 BasicBlock::Create(LLVMContext, "then", TheFunction);
308 BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");
309 BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");
310
311 Builder.CreateCondBr(CondV, ThenBB, ElseBB);
312
313 This code creates the basic blocks that are related to the if/then/else
314 statement, and correspond directly to the blocks in the example above.
315 The first line gets the current Function object that is being built. It
316 gets this by asking the builder for the current BasicBlock, and asking
317 that block for its "parent" (the function it is currently embedded
318 into).
319
320 Once it has that, it creates three blocks. Note that it passes
321 "TheFunction" into the constructor for the "then" block. This causes the
322 constructor to automatically insert the new block into the end of the
323 specified function. The other two blocks are created, but aren't yet
324 inserted into the function.
325
326 Once the blocks are created, we can emit the conditional branch that
327 chooses between them. Note that creating new blocks does not implicitly
328 affect the IRBuilder, so it is still inserting into the block that the
329 condition went into. Also note that it is creating a branch to the
330 "then" block and the "else" block, even though the "else" block isn't
331 inserted into the function yet. This is all ok: it is the standard way
332 that LLVM supports forward references.
333
334 .. code-block:: c++
335
336 // Emit then value.
337 Builder.SetInsertPoint(ThenBB);
338
339 Value *ThenV = Then->codegen();
340 if (!ThenV)
341 return nullptr;
342
343 Builder.CreateBr(MergeBB);
344 // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
345 ThenBB = Builder.GetInsertBlock();
346
347 After the conditional branch is inserted, we move the builder to start
348 inserting into the "then" block. Strictly speaking, this call moves the
349 insertion point to be at the end of the specified block. However, since
350 the "then" block is empty, it also starts out by inserting at the
351 beginning of the block. :)
352
353 Once the insertion point is set, we recursively codegen the "then"
354 expression from the AST. To finish off the "then" block, we create an
355 unconditional branch to the merge block. One interesting (and very
356 important) aspect of the LLVM IR is that it `requires all basic blocks
357 to be "terminated" <../LangRef.html#functionstructure>`_ with a `control
358 flow instruction <../LangRef.html#terminators>`_ such as return or
359 branch. This means that all control flow, *including fall throughs* must
360 be made explicit in the LLVM IR. If you violate this rule, the verifier
361 will emit an error.
362
363 The final line here is quite subtle, but is very important. The basic
364 issue is that when we create the Phi node in the merge block, we need to
365 set up the block/value pairs that indicate how the Phi will work.
366 Importantly, the Phi node expects to have an entry for each predecessor
367 of the block in the CFG. Why then, are we getting the current block when
368 we just set it to ThenBB 5 lines above? The problem is that the "Then"
369 expression may actually itself change the block that the Builder is
370 emitting into if, for example, it contains a nested "if/then/else"
371 expression. Because calling ``codegen()`` recursively could arbitrarily change
372 the notion of the current block, we are required to get an up-to-date
373 value for code that will set up the Phi node.
374
375 .. code-block:: c++
376
377 // Emit else block.
378 TheFunction->getBasicBlockList().push_back(ElseBB);
379 Builder.SetInsertPoint(ElseBB);
380
381 Value *ElseV = Else->codegen();
382 if (!ElseV)
383 return nullptr;
384
385 Builder.CreateBr(MergeBB);
386 // codegen of 'Else' can change the current block, update ElseBB for the PHI.
387 ElseBB = Builder.GetInsertBlock();
388
389 Code generation for the 'else' block is basically identical to codegen
390 for the 'then' block. The only significant difference is the first line,
391 which adds the 'else' block to the function. Recall previously that the
392 'else' block was created, but not added to the function. Now that the
393 'then' and 'else' blocks are emitted, we can finish up with the merge
394 code:
395
396 .. code-block:: c++
397
398 // Emit merge block.
399 TheFunction->getBasicBlockList().push_back(MergeBB);
400 Builder.SetInsertPoint(MergeBB);
401 PHINode *PN =
402 Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");
403
404 PN->addIncoming(ThenV, ThenBB);
405 PN->addIncoming(ElseV, ElseBB);
406 return PN;
407 }
408
409 The first two lines here are now familiar: the first adds the "merge"
410 block to the Function object (it was previously floating, like the else
411 block above). The second changes the insertion point so that newly
412 created code will go into the "merge" block. Once that is done, we need
413 to create the PHI node and set up the block/value pairs for the PHI.
414
415 Finally, the CodeGen function returns the phi node as the value computed
416 by the if/then/else expression. In our example above, this returned
417 value will feed into the code for the top-level function, which will
418 create the return instruction.
419
420 Overall, we now have the ability to execute conditional code in
421 Kaleidoscope. With this extension, Kaleidoscope is a fairly complete
422 language that can calculate a wide variety of numeric functions. Next up
423 we'll add another useful expression that is familiar from non-functional
424 languages...
425
426 'for' Loop Expression
427 =====================
428
429 Now that we know how to add basic control flow constructs to the
430 language, we have the tools to add more powerful things. Lets add
431 something more aggressive, a 'for' expression:
432
433 ::
434
435 extern putchard(char)
436 def printstar(n)
437 for i = 1, i < n, 1.0 in
438 putchard(42); # ascii 42 = '*'
439
440 # print 100 '*' characters
441 printstar(100);
442
443 This expression defines a new variable ("i" in this case) which iterates
444 from a starting value, while the condition ("i < n" in this case) is
445 true, incrementing by an optional step value ("1.0" in this case). If
446 the step value is omitted, it defaults to 1.0. While the loop is true,
447 it executes its body expression. Because we don't have anything better
448 to return, we'll just define the loop as always returning 0.0. In the
449 future when we have mutable variables, it will get more useful.
450
451 As before, lets talk about the changes that we need to Kaleidoscope to
452 support this.
453
454 Lexer Extensions for the 'for' Loop
455 -----------------------------------
456
457 The lexer extensions are the same sort of thing as for if/then/else:
458
459 .. code-block:: c++
460
461 ... in enum Token ...
462 // control
463 tok_if = -6, tok_then = -7, tok_else = -8,
464 tok_for = -9, tok_in = -10
465
466 ... in gettok ...
467 if (IdentifierStr == "def")
468 return tok_def;
469 if (IdentifierStr == "extern")
470 return tok_extern;
471 if (IdentifierStr == "if")
472 return tok_if;
473 if (IdentifierStr == "then")
474 return tok_then;
475 if (IdentifierStr == "else")
476 return tok_else;
477 if (IdentifierStr == "for")
478 return tok_for;
479 if (IdentifierStr == "in")
480 return tok_in;
481 return tok_identifier;
482
483 AST Extensions for the 'for' Loop
484 ---------------------------------
485
486 The AST node is just as simple. It basically boils down to capturing the
487 variable name and the constituent expressions in the node.
488
489 .. code-block:: c++
490
491 /// ForExprAST - Expression class for for/in.
492 class ForExprAST : public ExprAST {
493 std::string VarName;
494 std::unique_ptr Start, End, Step, Body;
495
496 public:
497 ForExprAST(const std::string &VarName, std::unique_ptr Start,
498 std::unique_ptr End, std::unique_ptr Step,
499 std::unique_ptr Body)
500 : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
501 Step(std::move(Step)), Body(std::move(Body)) {}
502 virtual Value *codegen();
503 };
504
505 Parser Extensions for the 'for' Loop
506 ------------------------------------
507
508 The parser code is also fairly standard. The only interesting thing here
509 is handling of the optional step value. The parser code handles it by
510 checking to see if the second comma is present. If not, it sets the step
511 value to null in the AST node:
512
513 .. code-block:: c++
514
515 /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
516 static std::unique_ptr ParseForExpr() {
517 getNextToken(); // eat the for.
518
519 if (CurTok != tok_identifier)
520 return LogError("expected identifier after for");
521
522 std::string IdName = IdentifierStr;
523 getNextToken(); // eat identifier.
524
525 if (CurTok != '=')
526 return LogError("expected '=' after for");
527 getNextToken(); // eat '='.
528
529
530 auto Start = ParseExpression();
531 if (!Start)
532 return nullptr;
533 if (CurTok != ',')
534 return LogError("expected ',' after for start value");
535 getNextToken();
536
537 auto End = ParseExpression();
538 if (!End)
539 return nullptr;
540
541 // The step value is optional.
542 std::unique_ptr Step;
543 if (CurTok == ',') {
544 getNextToken();
545 Step = ParseExpression();
546 if (!Step)
547 return nullptr;
548 }
549
550 if (CurTok != tok_in)
551 return LogError("expected 'in' after for");
552 getNextToken(); // eat 'in'.
553
554 auto Body = ParseExpression();
555 if (!Body)
556 return nullptr;
557
558 return llvm::make_unique(IdName, std::move(Start),
559 std::move(End), std::move(Step),
560 std::move(Body));
561 }
562
563 LLVM IR for the 'for' Loop
564 --------------------------
565
566 Now we get to the good part: the LLVM IR we want to generate for this
567 thing. With the simple example above, we get this LLVM IR (note that
568 this dump is generated with optimizations disabled for clarity):
569
570 .. code-block:: llvm
571
572 declare double @putchard(double)
573
574 define double @printstar(double %n) {
575 entry:
576 ; initial value = 1.0 (inlined into phi)
577 br label %loop
578
579 loop: ; preds = %loop, %entry
580 %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
581 ; body
582 %calltmp = call double @putchard(double 4.200000e+01)
583 ; increment
584 %nextvar = fadd double %i, 1.000000e+00
585
586 ; termination test
587 %cmptmp = fcmp ult double %i, %n
588 %booltmp = uitofp i1 %cmptmp to double
589 %loopcond = fcmp one double %booltmp, 0.000000e+00
590 br i1 %loopcond, label %loop, label %afterloop
591
592 afterloop: ; preds = %loop
593 ; loop always returns 0.0
594 ret double 0.000000e+00
595 }
596
597 This loop contains all the same constructs we saw before: a phi node,
598 several expressions, and some basic blocks. Lets see how this fits
599 together.
600
601 Code Generation for the 'for' Loop
602 ----------------------------------
603
604 The first part of codegen is very simple: we just output the start
605 expression for the loop value:
606
607 .. code-block:: c++
608
609 Value *ForExprAST::codegen() {
610 // Emit the start code first, without 'variable' in scope.
611 Value *StartVal = Start->codegen();
612 if (StartVal == 0) return 0;
613
614 With this out of the way, the next step is to set up the LLVM basic
615 block for the start of the loop body. In the case above, the whole loop
616 body is one block, but remember that the body code itself could consist
617 of multiple blocks (e.g. if it contains an if/then/else or a for/in
618 expression).
619
620 .. code-block:: c++
621
622 // Make the new basic block for the loop header, inserting after current
623 // block.
624 Function *TheFunction = Builder.GetInsertBlock()->getParent();
625 BasicBlock *PreheaderBB = Builder.GetInsertBlock();
626 BasicBlock *LoopBB =
627 BasicBlock::Create(LLVMContext, "loop", TheFunction);
628
629 // Insert an explicit fall through from the current block to the LoopBB.
630 Builder.CreateBr(LoopBB);
631
632 This code is similar to what we saw for if/then/else. Because we will
633 need it to create the Phi node, we remember the block that falls through
634 into the loop. Once we have that, we create the actual block that starts
635 the loop and create an unconditional branch for the fall-through between
636 the two blocks.
637
638 .. code-block:: c++
639
640 // Start insertion in LoopBB.
641 Builder.SetInsertPoint(LoopBB);
642
643 // Start the PHI node with an entry for Start.
644 PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(LLVMContext),
645 2, VarName.c_str());
646 Variable->addIncoming(StartVal, PreheaderBB);
647
648 Now that the "preheader" for the loop is set up, we switch to emitting
649 code for the loop body. To begin with, we move the insertion point and
650 create the PHI node for the loop induction variable. Since we already
651 know the incoming value for the starting value, we add it to the Phi
652 node. Note that the Phi will eventually get a second value for the
653 backedge, but we can't set it up yet (because it doesn't exist!).
654
655 .. code-block:: c++
656
657 // Within the loop, the variable is defined equal to the PHI node. If it
658 // shadows an existing variable, we have to restore it, so save it now.
659 Value *OldVal = NamedValues[VarName];
660 NamedValues[VarName] = Variable;
661
662 // Emit the body of the loop. This, like any other expr, can change the
663 // current BB. Note that we ignore the value computed by the body, but don't
664 // allow an error.
665 if (!Body->codegen())
666 return nullptr;
667
668 Now the code starts to get more interesting. Our 'for' loop introduces a
669 new variable to the symbol table. This means that our symbol table can
670 now contain either function arguments or loop variables. To handle this,
671 before we codegen the body of the loop, we add the loop variable as the
672 current value for its name. Note that it is possible that there is a
673 variable of the same name in the outer scope. It would be easy to make
674 this an error (emit an error and return null if there is already an
675 entry for VarName) but we choose to allow shadowing of variables. In
676 order to handle this correctly, we remember the Value that we are
677 potentially shadowing in ``OldVal`` (which will be null if there is no
678 shadowed variable).
679
680 Once the loop variable is set into the symbol table, the code
681 recursively codegen's the body. This allows the body to use the loop
682 variable: any references to it will naturally find it in the symbol
683 table.
684
685 .. code-block:: c++
686
687 // Emit the step value.
688 Value *StepVal = nullptr;
689 if (Step) {
690 StepVal = Step->codegen();
691 if (!StepVal)
692 return nullptr;
693 } else {
694 // If not specified, use 1.0.
695 StepVal = ConstantFP::get(LLVMContext, APFloat(1.0));
696 }
697
698 Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
699
700 Now that the body is emitted, we compute the next value of the iteration
701 variable by adding the step value, or 1.0 if it isn't present.
702 '``NextVar``' will be the value of the loop variable on the next
703 iteration of the loop.
704
705 .. code-block:: c++
706
707 // Compute the end condition.
708 Value *EndCond = End->codegen();
709 if (!EndCond)
710 return nullptr;
711
712 // Convert condition to a bool by comparing equal to 0.0.
713 EndCond = Builder.CreateFCmpONE(
714 EndCond, ConstantFP::get(LLVMContext, APFloat(0.0)), "loopcond");
715
716 Finally, we evaluate the exit value of the loop, to determine whether
717 the loop should exit. This mirrors the condition evaluation for the
718 if/then/else statement.
719
720 .. code-block:: c++
721
722 // Create the "after loop" block and insert it.
723 BasicBlock *LoopEndBB = Builder.GetInsertBlock();
724 BasicBlock *AfterBB =
725 BasicBlock::Create(LLVMContext, "afterloop", TheFunction);
726
727 // Insert the conditional branch into the end of LoopEndBB.
728 Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
729
730 // Any new code will be inserted in AfterBB.
731 Builder.SetInsertPoint(AfterBB);
732
733 With the code for the body of the loop complete, we just need to finish
734 up the control flow for it. This code remembers the end block (for the
735 phi node), then creates the block for the loop exit ("afterloop"). Based
736 on the value of the exit condition, it creates a conditional branch that
737 chooses between executing the loop again and exiting the loop. Any
738 future code is emitted in the "afterloop" block, so it sets the
739 insertion position to it.
740
741 .. code-block:: c++
742
743 // Add a new entry to the PHI node for the backedge.
744 Variable->addIncoming(NextVar, LoopEndBB);
745
746 // Restore the unshadowed variable.
747 if (OldVal)
748 NamedValues[VarName] = OldVal;
749 else
750 NamedValues.erase(VarName);
751
752 // for expr always returns 0.0.
753 return Constant::getNullValue(Type::getDoubleTy(LLVMContext));
754 }
755
756 The final code handles various cleanups: now that we have the "NextVar"
757 value, we can add the incoming value to the loop PHI node. After that,
758 we remove the loop variable from the symbol table, so that it isn't in
759 scope after the for loop. Finally, code generation of the for loop
760 always returns 0.0, so that is what we return from
761 ``ForExprAST::codegen()``.
762
763 With this, we conclude the "adding control flow to Kaleidoscope" chapter
764 of the tutorial. In this chapter we added two control flow constructs,
765 and used them to motivate a couple of aspects of the LLVM IR that are
766 important for front-end implementors to know. In the next chapter of our
767 saga, we will get a bit crazier and add `user-defined
768 operators `_ to our poor innocent language.
769
770 Full Code Listing
771 =================
772
773 Here is the complete code listing for our running example, enhanced with
774 the if/then/else and for expressions.. To build this example, use:
775
776 .. code-block:: bash
777
778 # Compile
779 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
780 # Run
781 ./toy
782
783 Here is the code:
784
785 .. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp
786 :language: c++
787
788 `Next: Extending the language: user-defined operators `_
789
0 ============================================================
1 Kaleidoscope: Extending the Language: User-defined Operators
2 ============================================================
3
4 .. contents::
5 :local:
6
7 Chapter 6 Introduction
8 ======================
9
10 Welcome to Chapter 6 of the "`Implementing a language with
11 LLVM `_" tutorial. At this point in our tutorial, we now
12 have a fully functional language that is fairly minimal, but also
13 useful. There is still one big problem with it, however. Our language
14 doesn't have many useful operators (like division, logical negation, or
15 even any comparisons besides less-than).
16
17 This chapter of the tutorial takes a wild digression into adding
18 user-defined operators to the simple and beautiful Kaleidoscope
19 language. This digression now gives us a simple and ugly language in
20 some ways, but also a powerful one at the same time. One of the great
21 things about creating your own language is that you get to decide what
22 is good or bad. In this tutorial we'll assume that it is okay to use
23 this as a way to show some interesting parsing techniques.
24
25 At the end of this tutorial, we'll run through an example Kaleidoscope
26 application that `renders the Mandelbrot set <#kicking-the-tires>`_. This gives an
27 example of what you can build with Kaleidoscope and its feature set.
28
29 User-defined Operators: the Idea
30 ================================
31
32 The "operator overloading" that we will add to Kaleidoscope is more
33 general than languages like C++. In C++, you are only allowed to
34 redefine existing operators: you can't programatically change the
35 grammar, introduce new operators, change precedence levels, etc. In this
36 chapter, we will add this capability to Kaleidoscope, which will let the
37 user round out the set of operators that are supported.
38
39 The point of going into user-defined operators in a tutorial like this
40 is to show the power and flexibility of using a hand-written parser.
41 Thus far, the parser we have been implementing uses recursive descent
42 for most parts of the grammar and operator precedence parsing for the
43 expressions. See `Chapter 2 `_ for details. Without
44 using operator precedence parsing, it would be very difficult to allow
45 the programmer to introduce new operators into the grammar: the grammar
46 is dynamically extensible as the JIT runs.
47
48 The two specific features we'll add are programmable unary operators
49 (right now, Kaleidoscope has no unary operators at all) as well as
50 binary operators. An example of this is:
51
52 ::
53
54 # Logical unary not.
55 def unary!(v)
56 if v then
57 0
58 else
59 1;
60
61 # Define > with the same precedence as <.
62 def binary> 10 (LHS RHS)
63 RHS < LHS;
64
65 # Binary "logical or", (note that it does not "short circuit")
66 def binary| 5 (LHS RHS)
67 if LHS then
68 1
69 else if RHS then
70 1
71 else
72 0;
73
74 # Define = with slightly lower precedence than relationals.
75 def binary= 9 (LHS RHS)
76 !(LHS < RHS | LHS > RHS);
77
78 Many languages aspire to being able to implement their standard runtime
79 library in the language itself. In Kaleidoscope, we can implement
80 significant parts of the language in the library!
81
82 We will break down implementation of these features into two parts:
83 implementing support for user-defined binary operators and adding unary
84 operators.
85
86 User-defined Binary Operators
87 =============================
88
89 Adding support for user-defined binary operators is pretty simple with
90 our current framework. We'll first add support for the unary/binary
91 keywords:
92
93 .. code-block:: c++
94
95 enum Token {
96 ...
97 // operators
98 tok_binary = -11,
99 tok_unary = -12
100 };
101 ...
102 static int gettok() {
103 ...
104 if (IdentifierStr == "for")
105 return tok_for;
106 if (IdentifierStr == "in")
107 return tok_in;
108 if (IdentifierStr == "binary")
109 return tok_binary;
110 if (IdentifierStr == "unary")
111 return tok_unary;
112 return tok_identifier;
113
114 This just adds lexer support for the unary and binary keywords, like we
115 did in `previous chapters `_. One nice thing
116 about our current AST, is that we represent binary operators with full
117 generalisation by using their ASCII code as the opcode. For our extended
118 operators, we'll use this same representation, so we don't need any new
119 AST or parser support.
120
121 On the other hand, we have to be able to represent the definitions of
122 these new operators, in the "def binary\| 5" part of the function
123 definition. In our grammar so far, the "name" for the function
124 definition is parsed as the "prototype" production and into the
125 ``PrototypeAST`` AST node. To represent our new user-defined operators
126 as prototypes, we have to extend the ``PrototypeAST`` AST node like
127 this:
128
129 .. code-block:: c++
130
131 /// PrototypeAST - This class represents the "prototype" for a function,
132 /// which captures its argument names as well as if it is an operator.
133 class PrototypeAST {
134 std::string Name;
135 std::vector Args;
136 bool IsOperator;
137 unsigned Precedence; // Precedence if a binary op.
138
139 public:
140 PrototypeAST(const std::string &name, std::vector Args,
141 bool IsOperator = false, unsigned Prec = 0)
142 : Name(name), Args(std::move(Args)), IsOperator(IsOperator),
143 Precedence(Prec) {}
144
145 bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
146 bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
147
148 char getOperatorName() const {
149 assert(isUnaryOp() || isBinaryOp());
150 return Name[Name.size()-1];
151 }
152
153 unsigned getBinaryPrecedence() const { return Precedence; }
154
155 Function *codegen();
156 };
157
158 Basically, in addition to knowing a name for the prototype, we now keep
159 track of whether it was an operator, and if it was, what precedence
160 level the operator is at. The precedence is only used for binary
161 operators (as you'll see below, it just doesn't apply for unary
162 operators). Now that we have a way to represent the prototype for a
163 user-defined operator, we need to parse it:
164
165 .. code-block:: c++
166
167 /// prototype
168 /// ::= id '(' id* ')'
169 /// ::= binary LETTER number? (id, id)
170 static std::unique_ptr ParsePrototype() {
171 std::string FnName;
172
173 unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
174 unsigned BinaryPrecedence = 30;
175
176 switch (CurTok) {
177 default:
178 return LogErrorP("Expected function name in prototype");
179 case tok_identifier:
180 FnName = IdentifierStr;
181 Kind = 0;
182 getNextToken();
183 break;
184 case tok_binary:
185 getNextToken();
186 if (!isascii(CurTok))
187 return LogErrorP("Expected binary operator");
188 FnName = "binary";
189 FnName += (char)CurTok;
190 Kind = 2;
191 getNextToken();
192
193 // Read the precedence if present.
194 if (CurTok == tok_number) {
195 if (NumVal < 1 || NumVal > 100)
196 return LogErrorP("Invalid precedecnce: must be 1..100");
197 BinaryPrecedence = (unsigned)NumVal;
198 getNextToken();
199 }
200 break;
201 }
202
203 if (CurTok != '(')
204 return LogErrorP("Expected '(' in prototype");
205
206 std::vector ArgNames;
207 while (getNextToken() == tok_identifier)
208 ArgNames.push_back(IdentifierStr);
209 if (CurTok != ')')
210 return LogErrorP("Expected ')' in prototype");
211
212 // success.
213 getNextToken(); // eat ')'.
214
215 // Verify right number of names for operator.
216 if (Kind && ArgNames.size() != Kind)
217 return LogErrorP("Invalid number of operands for operator");
218
219 return llvm::make_unique(FnName, std::move(ArgNames), Kind != 0,
220 BinaryPrecedence);
221 }
222
223 This is all fairly straightforward parsing code, and we have already
224 seen a lot of similar code in the past. One interesting part about the
225 code above is the couple lines that set up ``FnName`` for binary
226 operators. This builds names like "binary@" for a newly defined "@"
227 operator. This then takes advantage of the fact that symbol names in the
228 LLVM symbol table are allowed to have any character in them, including
229 embedded nul characters.
230
231 The next interesting thing to add, is codegen support for these binary
232 operators. Given our current structure, this is a simple addition of a
233 default case for our existing binary operator node:
234
235 .. code-block:: c++
236
237 Value *BinaryExprAST::codegen() {
238 Value *L = LHS->codegen();
239 Value *R = RHS->codegen();
240 if (!L || !R)
241 return nullptr;
242
243 switch (Op) {
244 case '+':
245 return Builder.CreateFAdd(L, R, "addtmp");
246 case '-':
247 return Builder.CreateFSub(L, R, "subtmp");
248 case '*':
249 return Builder.CreateFMul(L, R, "multmp");
250 case '<':
251 L = Builder.CreateFCmpULT(L, R, "cmptmp");
252 // Convert bool 0/1 to double 0.0 or 1.0
253 return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
254 "booltmp");
255 default:
256 break;
257 }
258
259 // If it wasn't a builtin binary operator, it must be a user defined one. Emit
260 // a call to it.
261 Function *F = TheModule->getFunction(std::string("binary") + Op);
262 assert(F && "binary operator not found!");
263
264 Value *Ops[2] = { L, R };
265 return Builder.CreateCall(F, Ops, "binop");
266 }
267
268 As you can see above, the new code is actually really simple. It just
269 does a lookup for the appropriate operator in the symbol table and
270 generates a function call to it. Since user-defined operators are just
271 built as normal functions (because the "prototype" boils down to a
272 function with the right name) everything falls into place.
273
274 The final piece of code we are missing, is a bit of top-level magic:
275
276 .. code-block:: c++
277
278 Function *FunctionAST::codegen() {
279 NamedValues.clear();
280
281 Function *TheFunction = Proto->codegen();
282 if (!TheFunction)
283 return nullptr;
284
285 // If this is an operator, install it.
286 if (Proto->isBinaryOp())
287 BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
288
289 // Create a new basic block to start insertion into.
290 BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
291 Builder.SetInsertPoint(BB);
292
293 if (Value *RetVal = Body->codegen()) {
294 ...
295
296 Basically, before codegening a function, if it is a user-defined
297 operator, we register it in the precedence table. This allows the binary
298 operator parsing logic we already have in place to handle it. Since we
299 are working on a fully-general operator precedence parser, this is all
300 we need to do to "extend the grammar".
301
302 Now we have useful user-defined binary operators. This builds a lot on
303 the previous framework we built for other operators. Adding unary
304 operators is a bit more challenging, because we don't have any framework
305 for it yet - lets see what it takes.
306
307 User-defined Unary Operators
308 ============================
309
310 Since we don't currently support unary operators in the Kaleidoscope
311 language, we'll need to add everything to support them. Above, we added
312 simple support for the 'unary' keyword to the lexer. In addition to
313 that, we need an AST node:
314
315 .. code-block:: c++
316
317 /// UnaryExprAST - Expression class for a unary operator.
318 class UnaryExprAST : public ExprAST {
319 char Opcode;
320 std::unique_ptr Operand;
321
322 public:
323 UnaryExprAST(char Opcode, std::unique_ptr Operand)
324 : Opcode(Opcode), Operand(std::move(Operand)) {}
325 virtual Value *codegen();
326 };
327
328 This AST node is very simple and obvious by now. It directly mirrors the
329 binary operator AST node, except that it only has one child. With this,
330 we need to add the parsing logic. Parsing a unary operator is pretty
331 simple: we'll add a new function to do it:
332
333 .. code-block:: c++
334
335 /// unary
336 /// ::= primary
337 /// ::= '!' unary
338 static std::unique_ptr ParseUnary() {
339 // If the current token is not an operator, it must be a primary expr.
340 if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
341 return ParsePrimary();
342
343 // If this is a unary operator, read it.
344 int Opc = CurTok;
345 getNextToken();
346 if (auto Operand = ParseUnary())
347 return llvm::unique_ptr(Opc, std::move(Operand));
348 return nullptr;
349 }
350
351 The grammar we add is pretty straightforward here. If we see a unary
352 operator when parsing a primary operator, we eat the operator as a
353 prefix and parse the remaining piece as another unary operator. This
354 allows us to handle multiple unary operators (e.g. "!!x"). Note that
355 unary operators can't have ambiguous parses like binary operators can,
356 so there is no need for precedence information.
357
358 The problem with this function, is that we need to call ParseUnary from
359 somewhere. To do this, we change previous callers of ParsePrimary to
360 call ParseUnary instead:
361
362 .. code-block:: c++
363
364 /// binoprhs
365 /// ::= ('+' unary)*
366 static std::unique_ptr ParseBinOpRHS(int ExprPrec,
367 std::unique_ptr LHS) {
368 ...
369 // Parse the unary expression after the binary operator.
370 auto RHS = ParseUnary();
371 if (!RHS)
372 return nullptr;
373 ...
374 }
375 /// expression
376 /// ::= unary binoprhs
377 ///
378 static std::unique_ptr ParseExpression() {
379 auto LHS = ParseUnary();
380 if (!LHS)
381 return nullptr;
382
383 return ParseBinOpRHS(0, std::move(LHS));
384 }
385
386 With these two simple changes, we are now able to parse unary operators
387 and build the AST for them. Next up, we need to add parser support for
388 prototypes, to parse the unary operator prototype. We extend the binary
389 operator code above with:
390
391 .. code-block:: c++
392
393 /// prototype
394 /// ::= id '(' id* ')'
395 /// ::= binary LETTER number? (id, id)
396 /// ::= unary LETTER (id)
397 static std::unique_ptr ParsePrototype() {
398 std::string FnName;
399
400 unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
401 unsigned BinaryPrecedence = 30;
402
403 switch (CurTok) {
404 default:
405 return LogErrorP("Expected function name in prototype");
406 case tok_identifier:
407 FnName = IdentifierStr;
408 Kind = 0;
409 getNextToken();
410 break;
411 case tok_unary:
412 getNextToken();
413 if (!isascii(CurTok))
414 return LogErrorP("Expected unary operator");
415 FnName = "unary";
416 FnName += (char)CurTok;
417 Kind = 1;
418 getNextToken();
419 break;
420 case tok_binary:
421 ...
422
423 As with binary operators, we name unary operators with a name that
424 includes the operator character. This assists us at code generation
425 time. Speaking of, the final piece we need to add is codegen support for
426 unary operators. It looks like this:
427
428 .. code-block:: c++
429
430 Value *UnaryExprAST::codegen() {
431 Value *OperandV = Operand->codegen();
432 if (!OperandV)
433 return nullptr;
434
435 Function *F = TheModule->getFunction(std::string("unary")+Opcode);
436 if (!F)
437 return LogErrorV("Unknown unary operator");
438
439 return Builder.CreateCall(F, OperandV, "unop");
440 }
441
442 This code is similar to, but simpler than, the code for binary
443 operators. It is simpler primarily because it doesn't need to handle any
444 predefined operators.
445
446 Kicking the Tires
447 =================
448
449 It is somewhat hard to believe, but with a few simple extensions we've
450 covered in the last chapters, we have grown a real-ish language. With
451 this, we can do a lot of interesting things, including I/O, math, and a
452 bunch of other things. For example, we can now add a nice sequencing
453 operator (printd is defined to print out the specified value and a
454 newline):
455
456 ::
457
458 ready> extern printd(x);
459 Read extern:
460 declare double @printd(double)
461
462 ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
463 ..
464 ready> printd(123) : printd(456) : printd(789);
465 123.000000
466 456.000000
467 789.000000
468 Evaluated to 0.000000
469
470 We can also define a bunch of other "primitive" operations, such as:
471
472 ::
473
474 # Logical unary not.
475 def unary!(v)
476 if v then
477 0
478 else
479 1;
480
481 # Unary negate.
482 def unary-(v)
483 0-v;
484
485 # Define > with the same precedence as <.
486 def binary> 10 (LHS RHS)
487 RHS < LHS;
488
489 # Binary logical or, which does not short circuit.
490 def binary| 5 (LHS RHS)