llvm.org GIT mirror llvm / 76091f1
replace the old kaleidoscope tutorial files with orphaned pages that forward to the new copy. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@366529 91177308-0d34-0410-b5e6-96231b3b80d8 Chris Lattner a month ago
13 changed file(s) with 47 addition(s) and 5638 deletion(s). Raw diff Collapse all Expand all
None =================================================
1 Kaleidoscope: Tutorial Introduction and the Lexer
2 =================================================
0 :orphan:
31
4 .. contents::
5 :local:
6
7 Tutorial Introduction
2 =====================
3 Kaleidoscope Tutorial
84 =====================
95
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
6 The Kaleidoscope Tutorial has `moved to another location `_ .
None ===========================================
1 Kaleidoscope: Implementing a Parser and AST
2 ===========================================
0 :orphan:
31
4 .. contents::
5 :local:
2 =====================
3 Kaleidoscope Tutorial
4 =====================
65
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, let's
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 const std::string &getName() const { return Name; }
123 };
124
125 /// FunctionAST - This class represents a function definition itself.
126 class FunctionAST {
127 std::unique_ptr Proto;
128 std::unique_ptr Body;
129
130 public:
131 FunctionAST(std::unique_ptr Proto,
132 std::unique_ptr Body)
133 : Proto(std::move(Proto)), Body(std::move(Body)) {}
134 };
135
136 In Kaleidoscope, functions are typed with just a count of their
137 arguments. Since all values are double precision floating point, the
138 type of each argument doesn't need to be stored anywhere. In a more
139 aggressive and realistic language, the "ExprAST" class would probably
140 have a type field.
141
142 With this scaffolding, we can now talk about parsing expressions and
143 function bodies in Kaleidoscope.
144
145 Parser Basics
146 =============
147
148 Now that we have an AST to build, we need to define the parser code to
149 build it. The idea here is that we want to parse something like "x+y"
150 (which is returned as three tokens by the lexer) into an AST that could
151 be generated with calls like this:
152
153 .. code-block:: c++
154
155 auto LHS = llvm::make_unique("x");
156 auto RHS = llvm::make_unique("y");
157 auto Result = std::make_unique('+', std::move(LHS),
158 std::move(RHS));
159
160 In order to do this, we'll start by defining some basic helper routines:
161
162 .. code-block:: c++
163
164 /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
165 /// token the parser is looking at. getNextToken reads another token from the
166 /// lexer and updates CurTok with its results.
167 static int CurTok;
168 static int getNextToken() {
169 return CurTok = gettok();
170 }
171
172 This implements a simple token buffer around the lexer. This allows us
173 to look one token ahead at what the lexer is returning. Every function
174 in our parser will assume that CurTok is the current token that needs to
175 be parsed.
176
177 .. code-block:: c++
178
179
180 /// LogError* - These are little helper functions for error handling.
181 std::unique_ptr LogError(const char *Str) {
182 fprintf(stderr, "LogError: %s\n", Str);
183 return nullptr;
184 }
185 std::unique_ptr LogErrorP(const char *Str) {
186 LogError(Str);
187 return nullptr;
188 }
189
190 The ``LogError`` routines are simple helper routines that our parser will
191 use to handle errors. The error recovery in our parser will not be the
192 best and is not particular user-friendly, but it will be enough for our
193 tutorial. These routines make it easier to handle errors in routines
194 that have various return types: they always return null.
195
196 With these basic helper functions, we can implement the first piece of
197 our grammar: numeric literals.
198
199 Basic Expression Parsing
200 ========================
201
202 We start with numeric literals, because they are the simplest to
203 process. For each production in our grammar, we'll define a function
204 which parses that production. For numeric literals, we have:
205
206 .. code-block:: c++
207
208 /// numberexpr ::= number
209 static std::unique_ptr ParseNumberExpr() {
210 auto Result = llvm::make_unique(NumVal);
211 getNextToken(); // consume the number
212 return std::move(Result);
213 }
214
215 This routine is very simple: it expects to be called when the current
216 token is a ``tok_number`` token. It takes the current number value,
217 creates a ``NumberExprAST`` node, advances the lexer to the next token,
218 and finally returns.
219
220 There are some interesting aspects to this. The most important one is
221 that this routine eats all of the tokens that correspond to the
222 production and returns the lexer buffer with the next token (which is
223 not part of the grammar production) ready to go. This is a fairly
224 standard way to go for recursive descent parsers. For a better example,
225 the parenthesis operator is defined like this:
226
227 .. code-block:: c++
228
229 /// parenexpr ::= '(' expression ')'
230 static std::unique_ptr ParseParenExpr() {
231 getNextToken(); // eat (.
232 auto V = ParseExpression();
233 if (!V)
234 return nullptr;
235
236 if (CurTok != ')')
237 return LogError("expected ')'");
238 getNextToken(); // eat ).
239 return V;
240 }
241
242 This function illustrates a number of interesting things about the
243 parser:
244
245 1) It shows how we use the LogError routines. When called, this function
246 expects that the current token is a '(' token, but after parsing the
247 subexpression, it is possible that there is no ')' waiting. For example,
248 if the user types in "(4 x" instead of "(4)", the parser should emit an
249 error. Because errors can occur, the parser needs a way to indicate that
250 they happened: in our parser, we return null on an error.
251
252 2) Another interesting aspect of this function is that it uses recursion
253 by calling ``ParseExpression`` (we will soon see that
254 ``ParseExpression`` can call ``ParseParenExpr``). This is powerful
255 because it allows us to handle recursive grammars, and keeps each
256 production very simple. Note that parentheses do not cause construction
257 of AST nodes themselves. While we could do it this way, the most
258 important role of parentheses are to guide the parser and provide
259 grouping. Once the parser constructs the AST, parentheses are not
260 needed.
261
262 The next simple production is for handling variable references and
263 function calls:
264
265 .. code-block:: c++
266
267 /// identifierexpr
268 /// ::= identifier
269 /// ::= identifier '(' expression* ')'
270 static std::unique_ptr ParseIdentifierExpr() {
271 std::string IdName = IdentifierStr;
272
273 getNextToken(); // eat identifier.
274
275 if (CurTok != '(') // Simple variable ref.
276 return llvm::make_unique(IdName);
277
278 // Call.
279 getNextToken(); // eat (
280 std::vector> Args;
281 if (CurTok != ')') {
282 while (1) {
283 if (auto Arg = ParseExpression())
284 Args.push_back(std::move(Arg));
285 else
286 return nullptr;
287
288 if (CurTok == ')')
289 break;
290
291 if (CurTok != ',')
292 return LogError("Expected ')' or ',' in argument list");
293 getNextToken();
294 }
295 }
296
297 // Eat the ')'.
298 getNextToken();
299
300 return llvm::make_unique(IdName, std::move(Args));
301 }
302
303 This routine follows the same style as the other routines. (It expects
304 to be called if the current token is a ``tok_identifier`` token). It
305 also has recursion and error handling. One interesting aspect of this is
306 that it uses *look-ahead* to determine if the current identifier is a
307 stand alone variable reference or if it is a function call expression.
308 It handles this by checking to see if the token after the identifier is
309 a '(' token, constructing either a ``VariableExprAST`` or
310 ``CallExprAST`` node as appropriate.
311
312 Now that we have all of our simple expression-parsing logic in place, we
313 can define a helper function to wrap it together into one entry point.
314 We call this class of expressions "primary" expressions, for reasons
315 that will become more clear `later in the
316 tutorial `_. In order to parse an arbitrary
317 primary expression, we need to determine what sort of expression it is:
318
319 .. code-block:: c++
320
321 /// primary
322 /// ::= identifierexpr
323 /// ::= numberexpr
324 /// ::= parenexpr
325 static std::unique_ptr ParsePrimary() {
326 switch (CurTok) {
327 default:
328 return LogError("unknown token when expecting an expression");
329 case tok_identifier:
330 return ParseIdentifierExpr();
331 case tok_number:
332 return ParseNumberExpr();
333 case '(':
334 return ParseParenExpr();
335 }
336 }
337
338 Now that you see the definition of this function, it is more obvious why
339 we can assume the state of CurTok in the various functions. This uses
340 look-ahead to determine which sort of expression is being inspected, and
341 then parses it with a function call.
342
343 Now that basic expressions are handled, we need to handle binary
344 expressions. They are a bit more complex.
345
346 Binary Expression Parsing
347 =========================
348
349 Binary expressions are significantly harder to parse because they are
350 often ambiguous. For example, when given the string "x+y\*z", the parser
351 can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
352 definitions from mathematics, we expect the later parse, because "\*"
353 (multiplication) has higher *precedence* than "+" (addition).
354
355 There are many ways to handle this, but an elegant and efficient way is
356 to use `Operator-Precedence
357 Parsing `_.
358 This parsing technique uses the precedence of binary operators to guide
359 recursion. To start with, we need a table of precedences:
360
361 .. code-block:: c++
362
363 /// BinopPrecedence - This holds the precedence for each binary operator that is
364 /// defined.
365 static std::map BinopPrecedence;
366
367 /// GetTokPrecedence - Get the precedence of the pending binary operator token.
368 static int GetTokPrecedence() {
369 if (!isascii(CurTok))
370 return -1;
371
372 // Make sure it's a declared binop.
373 int TokPrec = BinopPrecedence[CurTok];
374 if (TokPrec <= 0) return -1;
375 return TokPrec;
376 }
377
378 int main() {
379 // Install standard binary operators.
380 // 1 is lowest precedence.
381 BinopPrecedence['<'] = 10;
382 BinopPrecedence['+'] = 20;
383 BinopPrecedence['-'] = 20;
384 BinopPrecedence['*'] = 40; // highest.
385 ...
386 }
387
388 For the basic form of Kaleidoscope, we will only support 4 binary
389 operators (this can obviously be extended by you, our brave and intrepid
390 reader). The ``GetTokPrecedence`` function returns the precedence for
391 the current token, or -1 if the token is not a binary operator. Having a
392 map makes it easy to add new operators and makes it clear that the
393 algorithm doesn't depend on the specific operators involved, but it
394 would be easy enough to eliminate the map and do the comparisons in the
395 ``GetTokPrecedence`` function. (Or just use a fixed-size array).
396
397 With the helper above defined, we can now start parsing binary
398 expressions. The basic idea of operator precedence parsing is to break
399 down an expression with potentially ambiguous binary operators into
400 pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
401 Operator precedence parsing considers this as a stream of primary
402 expressions separated by binary operators. As such, it will first parse
403 the leading primary expression "a", then it will see the pairs [+, b]
404 [+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
405 primary expressions, the binary expression parser doesn't need to worry
406 about nested subexpressions like (c+d) at all.
407
408 To start, an expression is a primary expression potentially followed by
409 a sequence of [binop,primaryexpr] pairs:
410
411 .. code-block:: c++
412
413 /// expression
414 /// ::= primary binoprhs
415 ///
416 static std::unique_ptr ParseExpression() {
417 auto LHS = ParsePrimary();
418 if (!LHS)
419 return nullptr;
420
421 return ParseBinOpRHS(0, std::move(LHS));
422 }
423
424 ``ParseBinOpRHS`` is the function that parses the sequence of pairs for
425 us. It takes a precedence and a pointer to an expression for the part
426 that has been parsed so far. Note that "x" is a perfectly valid
427 expression: As such, "binoprhs" is allowed to be empty, in which case it
428 returns the expression that is passed into it. In our example above, the
429 code passes the expression for "a" into ``ParseBinOpRHS`` and the
430 current token is "+".
431
432 The precedence value passed into ``ParseBinOpRHS`` indicates the
433 *minimal operator precedence* that the function is allowed to eat. For
434 example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
435 passed in a precedence of 40, it will not consume any tokens (because
436 the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
437 starts with:
438
439 .. code-block:: c++
440
441 /// binoprhs
442 /// ::= ('+' primary)*
443 static std::unique_ptr ParseBinOpRHS(int ExprPrec,
444 std::unique_ptr LHS) {
445 // If this is a binop, find its precedence.
446 while (1) {
447 int TokPrec = GetTokPrecedence();
448
449 // If this is a binop that binds at least as tightly as the current binop,
450 // consume it, otherwise we are done.
451 if (TokPrec < ExprPrec)
452 return LHS;
453
454 This code gets the precedence of the current token and checks to see if
455 if is too low. Because we defined invalid tokens to have a precedence of
456 -1, this check implicitly knows that the pair-stream ends when the token
457 stream runs out of binary operators. If this check succeeds, we know
458 that the token is a binary operator and that it will be included in this
459 expression:
460
461 .. code-block:: c++
462
463 // Okay, we know this is a binop.
464 int BinOp = CurTok;
465 getNextToken(); // eat binop
466
467 // Parse the primary expression after the binary operator.
468 auto RHS = ParsePrimary();
469 if (!RHS)
470 return nullptr;
471
472 As such, this code eats (and remembers) the binary operator and then
473 parses the primary expression that follows. This builds up the whole
474 pair, the first of which is [+, b] for the running example.
475
476 Now that we parsed the left-hand side of an expression and one pair of
477 the RHS sequence, we have to decide which way the expression associates.
478 In particular, we could have "(a+b) binop unparsed" or "a + (b binop
479 unparsed)". To determine this, we look ahead at "binop" to determine its
480 precedence and compare it to BinOp's precedence (which is '+' in this
481 case):
482
483 .. code-block:: c++
484
485 // If BinOp binds less tightly with RHS than the operator after RHS, let
486 // the pending operator take RHS as its LHS.
487 int NextPrec = GetTokPrecedence();
488 if (TokPrec < NextPrec) {
489
490 If the precedence of the binop to the right of "RHS" is lower or equal
491 to the precedence of our current operator, then we know that the
492 parentheses associate as "(a+b) binop ...". In our example, the current
493 operator is "+" and the next operator is "+", we know that they have the
494 same precedence. In this case we'll create the AST node for "a+b", and
495 then continue parsing:
496
497 .. code-block:: c++
498
499 ... if body omitted ...
500 }
501
502 // Merge LHS/RHS.
503 LHS = llvm::make_unique(BinOp, std::move(LHS),
504 std::move(RHS));
505 } // loop around to the top of the while loop.
506 }
507
508 In our example above, this will turn "a+b+" into "(a+b)" and execute the
509 next iteration of the loop, with "+" as the current token. The code
510 above will eat, remember, and parse "(c+d)" as the primary expression,
511 which makes the current pair equal to [+, (c+d)]. It will then evaluate
512 the 'if' conditional above with "\*" as the binop to the right of the
513 primary. In this case, the precedence of "\*" is higher than the
514 precedence of "+" so the if condition will be entered.
515
516 The critical question left here is "how can the if condition parse the
517 right hand side in full"? In particular, to build the AST correctly for
518 our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
519 variable. The code to do this is surprisingly simple (code from the
520 above two blocks duplicated for context):
521
522 .. code-block:: c++
523
524 // If BinOp binds less tightly with RHS than the operator after RHS, let
525 // the pending operator take RHS as its LHS.
526 int NextPrec = GetTokPrecedence();
527 if (TokPrec < NextPrec) {
528 RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
529 if (!RHS)
530 return nullptr;
531 }
532 // Merge LHS/RHS.
533 LHS = llvm::make_unique(BinOp, std::move(LHS),
534 std::move(RHS));
535 } // loop around to the top of the while loop.
536 }
537
538 At this point, we know that the binary operator to the RHS of our
539 primary has higher precedence than the binop we are currently parsing.
540 As such, we know that any sequence of pairs whose operators are all
541 higher precedence than "+" should be parsed together and returned as
542 "RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
543 specifying "TokPrec+1" as the minimum precedence required for it to
544 continue. In our example above, this will cause it to return the AST
545 node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'
546 expression.
547
548 Finally, on the next iteration of the while loop, the "+g" piece is
549 parsed and added to the AST. With this little bit of code (14
550 non-trivial lines), we correctly handle fully general binary expression
551 parsing in a very elegant way. This was a whirlwind tour of this code,
552 and it is somewhat subtle. I recommend running through it with a few
553 tough examples to see how it works.
554
555 This wraps up handling of expressions. At this point, we can point the
556 parser at an arbitrary token stream and build an expression from it,
557 stopping at the first token that is not part of the expression. Next up
558 we need to handle function definitions, etc.
559
560 Parsing the Rest
561 ================
562
563 The next thing missing is handling of function prototypes. In
564 Kaleidoscope, these are used both for 'extern' function declarations as
565 well as function body definitions. The code to do this is
566 straight-forward and not very interesting (once you've survived
567 expressions):
568
569 .. code-block:: c++
570
571 /// prototype
572 /// ::= id '(' id* ')'
573 static std::unique_ptr ParsePrototype() {
574 if (CurTok != tok_identifier)
575 return LogErrorP("Expected function name in prototype");
576
577 std::string FnName = IdentifierStr;
578 getNextToken();
579
580 if (CurTok != '(')
581 return LogErrorP("Expected '(' in prototype");
582
583 // Read the list of argument names.
584 std::vector ArgNames;
585 while (getNextToken() == tok_identifier)
586 ArgNames.push_back(IdentifierStr);
587 if (CurTok != ')')
588 return LogErrorP("Expected ')' in prototype");
589
590 // success.
591 getNextToken(); // eat ')'.
592
593 return llvm::make_unique(FnName, std::move(ArgNames));
594 }
595
596 Given this, a function definition is very simple, just a prototype plus
597 an expression to implement the body:
598
599 .. code-block:: c++
600
601 /// definition ::= 'def' prototype expression
602 static std::unique_ptr ParseDefinition() {
603 getNextToken(); // eat def.
604 auto Proto = ParsePrototype();
605 if (!Proto) return nullptr;
606
607 if (auto E = ParseExpression())
608 return llvm::make_unique(std::move(Proto), std::move(E));
609 return nullptr;
610 }
611
612 In addition, we support 'extern' to declare functions like 'sin' and
613 'cos' as well as to support forward declaration of user functions. These
614 'extern's are just prototypes with no body:
615
616 .. code-block:: c++
617
618 /// external ::= 'extern' prototype
619 static std::unique_ptr ParseExtern() {
620 getNextToken(); // eat extern.
621 return ParsePrototype();
622 }
623
624 Finally, we'll also let the user type in arbitrary top-level expressions
625 and evaluate them on the fly. We will handle this by defining anonymous
626 nullary (zero argument) functions for them:
627
628 .. code-block:: c++
629
630 /// toplevelexpr ::= expression
631 static std::unique_ptr ParseTopLevelExpr() {
632 if (auto E = ParseExpression()) {
633 // Make an anonymous proto.
634 auto Proto = llvm::make_unique("", std::vector());
635 return llvm::make_unique(std::move(Proto), std::move(E));
636 }
637 return nullptr;
638 }
639
640 Now that we have all the pieces, let's build a little driver that will
641 let us actually *execute* this code we've built!
642
643 The Driver
644 ==========
645
646 The driver for this simply invokes all of the parsing pieces with a
647 top-level dispatch loop. There isn't much interesting here, so I'll just
648 include the top-level loop. See `below <#full-code-listing>`_ for full code in the
649 "Top-Level Parsing" section.
650
651 .. code-block:: c++
652
653 /// top ::= definition | external | expression | ';'
654 static void MainLoop() {
655 while (1) {
656 fprintf(stderr, "ready> ");
657 switch (CurTok) {
658 case tok_eof:
659 return;
660 case ';': // ignore top-level semicolons.
661 getNextToken();
662 break;
663 case tok_def:
664 HandleDefinition();
665 break;
666 case tok_extern:
667 HandleExtern();
668 break;
669 default:
670 HandleTopLevelExpression();
671 break;
672 }
673 }
674 }
675
676 The most interesting part of this is that we ignore top-level
677 semicolons. Why is this, you ask? The basic reason is that if you type
678 "4 + 5" at the command line, the parser doesn't know whether that is the
679 end of what you will type or not. For example, on the next line you
680 could type "def foo..." in which case 4+5 is the end of a top-level
681 expression. Alternatively you could type "\* 6", which would continue
682 the expression. Having top-level semicolons allows you to type "4+5;",
683 and the parser will know you are done.
684
685 Conclusions
686 ===========
687
688 With just under 400 lines of commented code (240 lines of non-comment,
689 non-blank code), we fully defined our minimal language, including a
690 lexer, parser, and AST builder. With this done, the executable will
691 validate Kaleidoscope code and tell us if it is grammatically invalid.
692 For example, here is a sample interaction:
693
694 .. code-block:: bash
695
696 $ ./a.out
697 ready> def foo(x y) x+foo(y, 4.0);
698 Parsed a function definition.
699 ready> def foo(x y) x+y y;
700 Parsed a function definition.
701 Parsed a top-level expr
702 ready> def foo(x y) x+y );
703 Parsed a function definition.
704 Error: unknown token when expecting an expression
705 ready> extern sin(a);
706 ready> Parsed an extern
707 ready> ^D
708 $
709
710 There is a lot of room for extension here. You can define new AST nodes,
711 extend the language in many ways, etc. In the `next
712 installment `_, we will describe how to generate LLVM
713 Intermediate Representation (IR) from the AST.
714
715 Full Code Listing
716 =================
717
718 Here is the complete code listing for our running example. Because this
719 uses the LLVM libraries, we need to link them in. To do this, we use the
720 `llvm-config `_ tool to inform
721 our makefile/command line about which options to use:
722
723 .. code-block:: bash
724
725 # Compile
726 clang++ -g -O3 toy.cpp `llvm-config --cxxflags`
727 # Run
728 ./a.out
729
730 Here is the code:
731
732 .. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp
733 :language: c++
734
735 `Next: Implementing Code Generation to LLVM IR `_
736
6 The Kaleidoscope Tutorial has `moved to another location `_ .
None ========================================
1 Kaleidoscope: Code generation to LLVM IR
2 ========================================
0 :orphan:
31
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
2 =====================
3 Kaleidoscope Tutorial
254 =====================
265
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(TheContext, 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(TheContext),
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 let's 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(TheContext));
273 FunctionType *FT =
274 FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
275
276 Function *F =
277 Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
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(TheContext, "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 (by sending an EOF via CTRL+D on Linux
536 or CTRL+Z and ENTER on Windows), it dumps out the IR for the entire
537 module generated. Here you can see the big picture with all the
538 functions referencing each other.
539
540 This wraps up the third chapter of the Kaleidoscope tutorial. Up next,
541 we'll describe how to `add JIT codegen and optimizer
542 support `_ to this so we can actually start running
543 code!
544
545 Full Code Listing
546 =================
547
548 Here is the complete code listing for our running example, enhanced with
549 the LLVM code generator. Because this uses the LLVM libraries, we need
550 to link them in. To do this, we use the
551 `llvm-config `_ tool to inform
552 our makefile/command line about which options to use:
553
554 .. code-block:: bash
555
556 # Compile
557 clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy
558 # Run
559 ./toy
560
561 Here is the code:
562
563 .. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp
564 :language: c++
565
566 `Next: Adding JIT and Optimizer Support `_
567
6 The Kaleidoscope Tutorial has `moved to another location `_ .
None ==============================================
1 Kaleidoscope: Adding JIT and Optimizer Support
2 ==============================================
0 :orphan:
31
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 .. warning::
97
98 Due to the transition to the new PassManager infrastructure this tutorial
99 is based on ``llvm::legacy::FunctionPassManager`` which can be found in
100 `LegacyPassManager.h `_.
101 For the purpose of the this tutorial the above should be used until
102 the pass manager transition is complete.
103
104 LLVM provides many optimization passes, which do many different sorts of
105 things and have different tradeoffs. Unlike other systems, LLVM doesn't
106 hold to the mistaken notion that one set of optimizations is right for
107 all languages and for all situations. LLVM allows a compiler implementor
108 to make complete decisions about what optimizations to use, in which
109 order, and in what situation.
110
111 As a concrete example, LLVM supports both "whole module" passes, which
112 look across as large of body of code as they can (often a whole file,
113 but if run at link time, this can be a substantial portion of the whole
114 program). It also supports and includes "per-function" passes which just
115 operate on a single function at a time, without looking at other
116 functions. For more information on passes and how they are run, see the
117 `How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the
118 `List of LLVM Passes <../Passes.html>`_.
119
120 For Kaleidoscope, we are currently generating functions on the fly, one
121 at a time, as the user types them in. We aren't shooting for the
122 ultimate optimization experience in this setting, but we also want to
123 catch the easy and quick stuff where possible. As such, we will choose
124 to run a few per-function optimizations as the user types the function
125 in. If we wanted to make a "static Kaleidoscope compiler", we would use
126 exactly the code we have now, except that we would defer running the
127 optimizer until the entire file has been parsed.
128
129 In order to get per-function optimizations going, we need to set up a
130 `FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
131 and organize the LLVM optimizations that we want to run. Once we have
132 that, we can add a set of optimizations to run. We'll need a new
133 FunctionPassManager for each module that we want to optimize, so we'll
134 write a function to create and initialize both the module and pass manager
135 for us:
136
137 .. code-block:: c++
138
139 void InitializeModuleAndPassManager(void) {
140 // Open a new module.
141 TheModule = llvm::make_unique("my cool jit", TheContext);
142
143 // Create a new pass manager attached to it.
144 TheFPM = llvm::make_unique(TheModule.get());
145
146 // Do simple "peephole" optimizations and bit-twiddling optzns.
147 TheFPM->add(createInstructionCombiningPass());
148 // Reassociate expressions.
149 TheFPM->add(createReassociatePass());
150 // Eliminate Common SubExpressions.
151 TheFPM->add(createGVNPass());
152 // Simplify the control flow graph (deleting unreachable blocks, etc).
153 TheFPM->add(createCFGSimplificationPass());
154
155 TheFPM->doInitialization();
156 }
157
158 This code initializes the global module ``TheModule``, and the function pass
159 manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
160 set up, we use a series of "add" calls to add a bunch of LLVM passes.
161
162 In this case, we choose to add four optimization passes.
163 The passes we choose here are a pretty standard set
164 of "cleanup" optimizations that are useful for a wide variety of code. I won't
165 delve into what they do but, believe me, they are a good starting place :).
166
167 Once the PassManager is set up, we need to make use of it. We do this by
168 running it after our newly created function is constructed (in
169 ``FunctionAST::codegen()``), but before it is returned to the client:
170
171 .. code-block:: c++
172
173 if (Value *RetVal = Body->codegen()) {
174 // Finish off the function.
175 Builder.CreateRet(RetVal);
176
177 // Validate the generated code, checking for consistency.
178 verifyFunction(*TheFunction);
179
180 // Optimize the function.
181 TheFPM->run(*TheFunction);
182
183 return TheFunction;
184 }
185
186 As you can see, this is pretty straightforward. The
187 ``FunctionPassManager`` optimizes and updates the LLVM Function\* in
188 place, improving (hopefully) its body. With this in place, we can try
189 our test above again:
190
191 ::
192
193 ready> def test(x) (1+2+x)*(x+(1+2));
194 ready> Read function definition:
195 define double @test(double %x) {
196 entry:
197 %addtmp = fadd double %x, 3.000000e+00
198 %multmp = fmul double %addtmp, %addtmp
199 ret double %multmp
200 }
201
202 As expected, we now get our nicely optimized code, saving a floating
203 point add instruction from every execution of this function.
204
205 LLVM provides a wide variety of optimizations that can be used in
206 certain circumstances. Some `documentation about the various
207 passes <../Passes.html>`_ is available, but it isn't very complete.
208 Another good source of ideas can come from looking at the passes that
209 ``Clang`` runs to get started. The "``opt``" tool allows you to
210 experiment with passes from the command line, so you can see if they do
211 anything.
212
213 Now that we have reasonable code coming out of our front-end, let's talk
214 about executing it!
215
216 Adding a JIT Compiler
2 =====================
3 Kaleidoscope Tutorial
2174 =====================
2185
219 Code that is available in LLVM IR can have a wide variety of tools
220 applied to it. For example, you can run optimizations on it (as we did
221 above), you can dump it out in textual or binary forms, you can compile
222 the code to an assembly file (.s) for some target, or you can JIT
223 compile it. The nice thing about the LLVM IR representation is that it
224 is the "common currency" between many different parts of the compiler.
225
226 In this section, we'll add JIT compiler support to our interpreter. The
227 basic idea that we want for Kaleidoscope is to have the user enter
228 function bodies as they do now, but immediately evaluate the top-level
229 expressions they type in. For example, if they type in "1 + 2;", we
230 should evaluate and print out 3. If they define a function, they should
231 be able to call it from the command line.
232
233 In order to do this, we first prepare the environment to create code for
234 the current native target and declare and initialize the JIT. This is
235 done by calling some ``InitializeNativeTarget\*`` functions and
236 adding a global variable ``TheJIT``, and initializing it in
237 ``main``:
238
239 .. code-block:: c++
240
241 static std::unique_ptr TheJIT;
242 ...
243 int main() {
244 InitializeNativeTarget();
245 InitializeNativeTargetAsmPrinter();
246 InitializeNativeTargetAsmParser();
247
248 // Install standard binary operators.
249 // 1 is lowest precedence.
250 BinopPrecedence['<'] = 10;
251 BinopPrecedence['+'] = 20;
252 BinopPrecedence['-'] = 20;
253 BinopPrecedence['*'] = 40; // highest.
254
255 // Prime the first token.
256 fprintf(stderr, "ready> ");
257 getNextToken();
258
259 TheJIT = llvm::make_unique();
260
261 // Run the main "interpreter loop" now.
262 MainLoop();
263
264 return 0;
265 }
266
267 We also need to setup the data layout for the JIT:
268
269 .. code-block:: c++
270
271 void InitializeModuleAndPassManager(void) {
272 // Open a new module.
273 TheModule = llvm::make_unique("my cool jit", TheContext);
274 TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
275
276 // Create a new pass manager attached to it.
277 TheFPM = llvm::make_unique(TheModule.get());
278 ...
279
280 The KaleidoscopeJIT class is a simple JIT built specifically for these
281 tutorials, available inside the LLVM source code
282 at llvm-src/examples/Kaleidoscope/include/KaleidoscopeJIT.h.
283 In later chapters we will look at how it works and extend it with
284 new features, but for now we will take it as given. Its API is very simple:
285 ``addModule`` adds an LLVM IR module to the JIT, making its functions
286 available for execution; ``removeModule`` removes a module, freeing any
287 memory associated with the code in that module; and ``findSymbol`` allows us
288 to look up pointers to the compiled code.
289
290 We can take this simple API and change our code that parses top-level expressions to
291 look like this:
292
293 .. code-block:: c++
294
295 static void HandleTopLevelExpression() {
296 // Evaluate a top-level expression into an anonymous function.
297 if (auto FnAST = ParseTopLevelExpr()) {
298 if (FnAST->codegen()) {
299
300 // JIT the module containing the anonymous expression, keeping a handle so
301 // we can free it later.
302 auto H = TheJIT->addModule(std::move(TheModule));
303 InitializeModuleAndPassManager();
304
305 // Search the JIT for the __anon_expr symbol.
306 auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
307 assert(ExprSymbol && "Function not found");
308
309 // Get the symbol's address and cast it to the right type (takes no
310 // arguments, returns a double) so we can call it as a native function.
311 double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
312 fprintf(stderr, "Evaluated to %f\n", FP());
313
314 // Delete the anonymous expression module from the JIT.
315 TheJIT->removeModule(H);
316 }
317
318 If parsing and codegen succeeed, the next step is to add the module containing
319 the top-level expression to the JIT. We do this by calling addModule, which
320 triggers code generation for all the functions in the module, and returns a
321 handle that can be used to remove the module from the JIT later. Once the module
322 has been added to the JIT it can no longer be modified, so we also open a new
323 module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.
324
325 Once we've added the module to the JIT we need to get a pointer to the final
326 generated code. We do this by calling the JIT's findSymbol method, and passing
327 the name of the top-level expression function: ``__anon_expr``. Since we just
328 added this function, we assert that findSymbol returned a result.
329
330 Next, we get the in-memory address of the ``__anon_expr`` function by calling
331 ``getAddress()`` on the symbol. Recall that we compile top-level expressions
332 into a self-contained LLVM function that takes no arguments and returns the
333 computed double. Because the LLVM JIT compiler matches the native platform ABI,
334 this means that you can just cast the result pointer to a function pointer of
335 that type and call it directly. This means, there is no difference between JIT
336 compiled code and native machine code that is statically linked into your
337 application.
338
339 Finally, since we don't support re-evaluation of top-level expressions, we
340 remove the module from the JIT when we're done to free the associated memory.
341 Recall, however, that the module we created a few lines earlier (via
342 ``InitializeModuleAndPassManager``) is still open and waiting for new code to be
343 added.
344
345 With just these two changes, let's see how Kaleidoscope works now!
346
347 ::
348
349 ready> 4+5;
350 Read top-level expression:
351 define double @0() {
352 entry:
353 ret double 9.000000e+00
354 }
355
356 Evaluated to 9.000000
357
358 Well this looks like it is basically working. The dump of the function
359 shows the "no argument function that always returns double" that we
360 synthesize for each top-level expression that is typed in. This
361 demonstrates very basic functionality, but can we do more?
362
363 ::
364
365 ready> def testfunc(x y) x + y*2;
366 Read function definition:
367 define double @testfunc(double %x, double %y) {
368 entry:
369 %multmp = fmul double %y, 2.000000e+00
370 %addtmp = fadd double %multmp, %x
371 ret double %addtmp
372 }
373
374 ready> testfunc(4, 10);
375 Read top-level expression:
376 define double @1() {
377 entry:
378 %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
379 ret double %calltmp
380 }
381
382 Evaluated to 24.000000
383
384 ready> testfunc(5, 10);
385 ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!
386
387
388 Function definitions and calls also work, but something went very wrong on that
389 last line. The call looks valid, so what happened? As you may have guessed from
390 the API a Module is a unit of allocation for the JIT, and testfunc was part
391 of the same module that contained anonymous expression. When we removed that
392 module from the JIT to free the memory for the anonymous expression, we deleted
393 the definition of ``testfunc`` along with it. Then, when we tried to call
394 testfunc a second time, the JIT could no longer find it.
395
396 The easiest way to fix this is to put the anonymous expression in a separate
397 module from the rest of the function definitions. The JIT will happily resolve
398 function calls across module boundaries, as long as each of the functions called
399 has a prototype, and is added to the JIT before it is called. By putting the
400 anonymous expression in a different module we can delete it without affecting
401 the rest of the functions.
402
403 In fact, we're going to go a step further and put every function in its own
404 module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT
405 that will make our environment more REPL-like: Functions can be added to the
406 JIT more than once (unlike a module where every function must have a unique
407 definition). When you look up a symbol in KaleidoscopeJIT it will always return
408 the most recent definition:
409
410 ::
411
412 ready> def foo(x) x + 1;
413 Read function definition:
414 define double @foo(double %x) {
415 entry:
416 %addtmp = fadd double %x, 1.000000e+00
417 ret double %addtmp
418 }
419
420 ready> foo(2);
421 Evaluated to 3.000000
422
423 ready> def foo(x) x + 2;
424 define double @foo(double %x) {
425 entry:
426 %addtmp = fadd double %x, 2.000000e+00
427 ret double %addtmp
428 }
429
430 ready> foo(2);
431 Evaluated to 4.000000
432
433
434 To allow each function to live in its own module we'll need a way to
435 re-generate previous function declarations into each new module we open:
436
437 .. code-block:: c++
438
439 static std::unique_ptr TheJIT;
440
441 ...
442
443 Function *getFunction(std::string Name) {
444 // First, see if the function has already been added to the current module.
445 if (auto *F = TheModule->getFunction(Name))
446 return F;
447
448 // If not, check whether we can codegen the declaration from some existing
449 // prototype.
450 auto FI = FunctionProtos.find(Name);
451 if (FI != FunctionProtos.end())
452 return FI->second->codegen();
453
454 // If no existing prototype exists, return null.
455 return nullptr;
456 }
457
458 ...
459
460 Value *CallExprAST::codegen() {
461 // Look up the name in the global module table.
462 Function *CalleeF = getFunction(Callee);
463
464 ...
465
466 Function *FunctionAST::codegen() {
467 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
468 // reference to it for use below.
469 auto &P = *Proto;
470 FunctionProtos[Proto->getName()] = std::move(Proto);
471 Function *TheFunction = getFunction(P.getName());
472 if (!TheFunction)
473 return nullptr;
474
475
476 To enable this, we'll start by adding a new global, ``FunctionProtos``, that
477 holds the most recent prototype for each function. We'll also add a convenience
478 method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.
479 Our convenience method searches ``TheModule`` for an existing function
480 declaration, falling back to generating a new declaration from FunctionProtos if
481 it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the
482 call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to
483 update the FunctionProtos map first, then call ``getFunction()``. With this
484 done, we can always obtain a function declaration in the current module for any
485 previously declared function.
486
487 We also need to update HandleDefinition and HandleExtern:
488
489 .. code-block:: c++
490
491 static void HandleDefinition() {
492 if (auto FnAST = ParseDefinition()) {
493 if (auto *FnIR = FnAST->codegen()) {
494 fprintf(stderr, "Read function definition:");
495 FnIR->print(errs());
496 fprintf(stderr, "\n");
497 TheJIT->addModule(std::move(TheModule));
498 InitializeModuleAndPassManager();
499 }
500 } else {
501 // Skip token for error recovery.
502 getNextToken();
503 }
504 }
505
506 static void HandleExtern() {
507 if (auto ProtoAST = ParseExtern()) {
508 if (auto *FnIR = ProtoAST->codegen()) {
509 fprintf(stderr, "Read extern: ");
510 FnIR->print(errs());
511 fprintf(stderr, "\n");
512 FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
513 }
514 } else {
515 // Skip token for error recovery.
516 getNextToken();
517 }
518 }
519
520 In HandleDefinition, we add two lines to transfer the newly defined function to
521 the JIT and open a new module. In HandleExtern, we just need to add one line to
522 add the prototype to FunctionProtos.
523
524 With these changes made, let's try our REPL again (I removed the dump of the
525 anonymous functions this time, you should get the idea by now :) :
526
527 ::
528
529 ready> def foo(x) x + 1;
530 ready> foo(2);
531 Evaluated to 3.000000
532
533 ready> def foo(x) x + 2;
534 ready> foo(2);
535 Evaluated to 4.000000
536
537 It works!
538
539 Even with this simple code, we get some surprisingly powerful capabilities -
540 check this out:
541
542 ::
543
544 ready> extern sin(x);
545 Read extern:
546 declare double @sin(double)
547
548 ready> extern cos(x);
549 Read extern:
550 declare double @cos(double)
551
552 ready> sin(1.0);
553 Read top-level expression:
554 define double @2() {
555 entry:
556 ret double 0x3FEAED548F090CEE
557 }
558
559 Evaluated to 0.841471
560
561 ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
562 Read function definition:
563 define double @foo(double %x) {
564 entry:
565 %calltmp = call double @sin(double %x)
566 %multmp = fmul double %calltmp, %calltmp
567 %calltmp2 = call double @cos(double %x)
568 %multmp4 = fmul double %calltmp2, %calltmp2
569 %addtmp = fadd double %multmp, %multmp4
570 ret double %addtmp
571 }
572
573 ready> foo(4.0);
574 Read top-level expression:
575 define double @3() {
576 entry:
577 %calltmp = call double @foo(double 4.000000e+00)
578 ret double %calltmp
579 }
580
581 Evaluated to 1.000000
582
583 Whoa, how does the JIT know about sin and cos? The answer is surprisingly
584 simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that
585 it uses to find symbols that aren't available in any given module: First
586 it searches all the modules that have already been added to the JIT, from the
587 most recent to the oldest, to find the newest definition. If no definition is
588 found inside the JIT, it falls back to calling "``dlsym("sin")``" on the
589 Kaleidoscope process itself. Since "``sin``" is defined within the JIT's
590 address space, it simply patches up calls in the module to call the libm
591 version of ``sin`` directly. But in some cases this even goes further:
592 as sin and cos are names of standard math functions, the constant folder
593 will directly evaluate the function calls to the correct result when called
594 with constants like in the "``sin(1.0)``" above.
595
596 In the future we'll see how tweaking this symbol resolution rule can be used to
597 enable all sorts of useful features, from security (restricting the set of
598 symbols available to JIT'd code), to dynamic code generation based on symbol
599 names, and even lazy compilation.
600
601 One immediate benefit of the symbol resolution rule is that we can now extend
602 the language by writing arbitrary C++ code to implement operations. For example,
603 if we add:
604
605 .. code-block:: c++
606
607 #ifdef _WIN32
608 #define DLLEXPORT __declspec(dllexport)
609 #else
610 #define DLLEXPORT
611 #endif
612
613 /// putchard - putchar that takes a double and returns 0.
614 extern "C" DLLEXPORT double putchard(double X) {
615 fputc((char)X, stderr);
616 return 0;
617 }
618
619 Note, that for Windows we need to actually export the functions because
620 the dynamic symbol loader will use GetProcAddress to find the symbols.
621
622 Now we can produce simple output to the console by using things like:
623 "``extern putchard(x); putchard(120);``", which prints a lowercase 'x'
624 on the console (120 is the ASCII code for 'x'). Similar code could be
625 used to implement file I/O, console input, and many other capabilities
626 in Kaleidoscope.
627
628 This completes the JIT and optimizer chapter of the Kaleidoscope
629 tutorial. At this point, we can compile a non-Turing-complete
630 programming language, optimize and JIT compile it in a user-driven way.
631 Next up we'll look into `extending the language with control flow
632 constructs `_, tackling some interesting LLVM IR issues
633 along the way.
634
635 Full Code Listing
636 =================
637
638 Here is the complete code listing for our running example, enhanced with
639 the LLVM JIT and optimizer. To build this example, use:
640
641 .. code-block:: bash
642
643 # Compile
644 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
645 # Run
646 ./toy
647
648 If you are compiling this on Linux, make sure to add the "-rdynamic"
649 option as well. This makes sure that the external functions are resolved
650 properly at runtime.
651
652 Here is the code:
653
654 .. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp
655 :language: c++
656
657 `Next: Extending the language: control flow `_
658
6 The Kaleidoscope Tutorial has `moved to another location `_ .
docs/tutorial/LangImpl05-cfg.png less more
Binary diff not shown
None ==================================================
1 Kaleidoscope: Extending the Language: Control Flow
2 ==================================================
0 :orphan:
31
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, let's 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", let's 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
106 Value *codegen() override;
107 };
108
109 The AST node just has pointers to the various subexpressions.
110
111 Parser Extensions for If/Then/Else
112 ----------------------------------
113
114 Now that we have the relevant tokens coming from the lexer and we have
115 the AST node to build, our parsing logic is relatively straightforward.
116 First we define a new parsing function:
117
118 .. code-block:: c++
119
120 /// ifexpr ::= 'if' expression 'then' expression 'else' expression
121 static std::unique_ptr ParseIfExpr() {
122 getNextToken(); // eat the if.
123
124 // condition.
125 auto Cond = ParseExpression();
126 if (!Cond)
127 return nullptr;
128
129 if (CurTok != tok_then)
130 return LogError("expected then");
131 getNextToken(); // eat the then
132
133 auto Then = ParseExpression();
134 if (!Then)
135 return nullptr;
136
137 if (CurTok != tok_else)
138 return LogError("expected else");
139
140 getNextToken();
141
142 auto Else = ParseExpression();
143 if (!Else)
144 return nullptr;
145
146 return llvm::make_unique(std::move(Cond), std::move(Then),
147 std::move(Else));
148 }
149
150 Next we hook it up as a primary expression:
151
152 .. code-block:: c++
153
154 static std::unique_ptr ParsePrimary() {
155 switch (CurTok) {
156 default:
157 return LogError("unknown token when expecting an expression");
158 case tok_identifier:
159 return ParseIdentifierExpr();
160 case tok_number:
161 return ParseNumberExpr();
162 case '(':
163 return ParseParenExpr();
164 case tok_if:
165 return ParseIfExpr();
166 }
167 }
168
169 LLVM IR for If/Then/Else
170 ------------------------
171
172 Now that we have it parsing and building the AST, the final piece is
173 adding LLVM code generation support. This is the most interesting part
174 of the if/then/else example, because this is where it starts to
175 introduce new concepts. All of the code above has been thoroughly
176 described in previous chapters.
177
178 To motivate the code we want to produce, let's take a look at a simple
179 example. Consider:
180
181 ::
182
183 extern foo();
184 extern bar();
185 def baz(x) if x then foo() else bar();
186
187 If you disable optimizations, the code you'll (soon) get from
188 Kaleidoscope looks like this:
189
190 .. code-block:: llvm
191
192 declare double @foo()
193
194 declare double @bar()
195
196 define double @baz(double %x) {
197 entry:
198 %ifcond = fcmp one double %x, 0.000000e+00
199 br i1 %ifcond, label %then, label %else
200
201 then: ; preds = %entry
202 %calltmp = call double @foo()
203 br label %ifcont
204
205 else: ; preds = %entry
206 %calltmp1 = call double @bar()
207 br label %ifcont
208
209 ifcont: ; preds = %else, %then
210 %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
211 ret double %iftmp
212 }
213
214 To visualize the control flow graph, you can use a nifty feature of the
215 LLVM '`opt `_' tool. If you put this LLVM
216 IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
217 window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
218 see this graph:
219
220 .. figure:: LangImpl05-cfg.png
221 :align: center
222 :alt: Example CFG
223
224 Example CFG
225
226 Another way to get this is to call "``F->viewCFG()``" or
227 "``F->viewCFGOnly()``" (where F is a "``Function*``") either by
228 inserting actual calls into the code and recompiling or by calling these
229 in the debugger. LLVM has many nice features for visualizing various
230 graphs.
231
232 Getting back to the generated code, it is fairly simple: the entry block
233 evaluates the conditional expression ("x" in our case here) and compares
234 the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered
235 and Not Equal"). Based on the result of this expression, the code jumps
236 to either the "then" or "else" blocks, which contain the expressions for
237 the true/false cases.
238
239 Once the then/else blocks are finished executing, they both branch back
240 to the 'ifcont' block to execute the code that happens after the
241 if/then/else. In this case the only thing left to do is to return to the
242 caller of the function. The question then becomes: how does the code
243 know which expression to return?
244
245 The answer to this question involves an important SSA operation: the
246 `Phi
247 operation `_.
248 If you're not familiar with SSA, `the wikipedia
249 article `_
250 is a good introduction and there are various other introductions to it
251 available on your favorite search engine. The short version is that
252 "execution" of the Phi operation requires "remembering" which block
253 control came from. The Phi operation takes on the value corresponding to
254 the input control block. In this case, if control comes in from the
255 "then" block, it gets the value of "calltmp". If control comes from the
256 "else" block, it gets the value of "calltmp1".
257
258 At this point, you are probably starting to think "Oh no! This means my
259 simple and elegant front-end will have to start generating SSA form in
260 order to use LLVM!". Fortunately, this is not the case, and we strongly
261 advise *not* implementing an SSA construction algorithm in your
262 front-end unless there is an amazingly good reason to do so. In
263 practice, there are two sorts of values that float around in code
264 written for your average imperative programming language that might need
265 Phi nodes:
266
267 #. Code that involves user variables: ``x = 1; x = x + 1;``
268 #. Values that are implicit in the structure of your AST, such as the
269 Phi node in this case.
270
271 In `Chapter 7 `_ of this tutorial ("mutable variables"),
272 we'll talk about #1 in depth. For now, just believe me that you don't
273 need SSA construction to handle this case. For #2, you have the choice
274 of using the techniques that we will describe for #1, or you can insert
275 Phi nodes directly, if convenient. In this case, it is really
276 easy to generate the Phi node, so we choose to do it directly.
277
278 Okay, enough of the motivation and overview, let's generate code!
279
280 Code Generation for If/Then/Else
281 --------------------------------
282
283 In order to generate code for this, we implement the ``codegen`` method
284 for ``IfExprAST``:
285
286 .. code-block:: c++
287
288 Value *IfExprAST::codegen() {
289 Value *CondV = Cond->codegen();
290 if (!CondV)
291 return nullptr;
292
293 // Convert condition to a bool by comparing non-equal to 0.0.
294 CondV = Builder.CreateFCmpONE(
295 CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
296
297 This code is straightforward and similar to what we saw before. We emit
298 the expression for the condition, then compare that value to zero to get
299 a truth value as a 1-bit (bool) value.
300
301 .. code-block:: c++
302
303 Function *TheFunction = Builder.GetInsertBlock()->getParent();
304
305 // Create blocks for the then and else cases. Insert the 'then' block at the
306 // end of the function.
307 BasicBlock *ThenBB =
308 BasicBlock::Create(TheContext, "then", TheFunction);
309 BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
310 BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
311
312 Builder.CreateCondBr(CondV, ThenBB, ElseBB);
313
314 This code creates the basic blocks that are related to the if/then/else
315 statement, and correspond directly to the blocks in the example above.
316 The first line gets the current Function object that is being built. It
317 gets this by asking the builder for the current BasicBlock, and asking
318 that block for its "parent" (the function it is currently embedded
319 into).
320
321 Once it has that, it creates three blocks. Note that it passes
322 "TheFunction" into the constructor for the "then" block. This causes the
323 constructor to automatically insert the new block into the end of the
324 specified function. The other two blocks are created, but aren't yet
325 inserted into the function.
326
327 Once the blocks are created, we can emit the conditional branch that
328 chooses between them. Note that creating new blocks does not implicitly
329 affect the IRBuilder, so it is still inserting into the block that the
330 condition went into. Also note that it is creating a branch to the
331 "then" block and the "else" block, even though the "else" block isn't
332 inserted into the function yet. This is all ok: it is the standard way
333 that LLVM supports forward references.
334
335 .. code-block:: c++
336
337 // Emit then value.
338 Builder.SetInsertPoint(ThenBB);
339
340 Value *ThenV = Then->codegen();
341 if (!ThenV)
342 return nullptr;
343
344 Builder.CreateBr(MergeBB);
345 // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
346 ThenBB = Builder.GetInsertBlock();
347
348 After the conditional branch is inserted, we move the builder to start
349 inserting into the "then" block. Strictly speaking, this call moves the
350 insertion point to be at the end of the specified block. However, since
351 the "then" block is empty, it also starts out by inserting at the
352 beginning of the block. :)
353
354 Once the insertion point is set, we recursively codegen the "then"
355 expression from the AST. To finish off the "then" block, we create an
356 unconditional branch to the merge block. One interesting (and very
357 important) aspect of the LLVM IR is that it `requires all basic blocks
358 to be "terminated" <../LangRef.html#functionstructure>`_ with a `control
359 flow instruction <../LangRef.html#terminators>`_ such as return or
360 branch. This means that all control flow, *including fall throughs* must
361 be made explicit in the LLVM IR. If you violate this rule, the verifier
362 will emit an error.
363
364 The final line here is quite subtle, but is very important. The basic
365 issue is that when we create the Phi node in the merge block, we need to
366 set up the block/value pairs that indicate how the Phi will work.
367 Importantly, the Phi node expects to have an entry for each predecessor
368 of the block in the CFG. Why then, are we getting the current block when
369 we just set it to ThenBB 5 lines above? The problem is that the "Then"
370 expression may actually itself change the block that the Builder is
371 emitting into if, for example, it contains a nested "if/then/else"
372 expression. Because calling ``codegen()`` recursively could arbitrarily change
373 the notion of the current block, we are required to get an up-to-date
374 value for code that will set up the Phi node.
375
376 .. code-block:: c++
377
378 // Emit else block.
379 TheFunction->getBasicBlockList().push_back(ElseBB);
380 Builder.SetInsertPoint(ElseBB);
381
382 Value *ElseV = Else->codegen();
383 if (!ElseV)
384 return nullptr;
385
386 Builder.CreateBr(MergeBB);
387 // codegen of 'Else' can change the current block, update ElseBB for the PHI.
388 ElseBB = Builder.GetInsertBlock();
389
390 Code generation for the 'else' block is basically identical to codegen
391 for the 'then' block. The only significant difference is the first line,
392 which adds the 'else' block to the function. Recall previously that the
393 'else' block was created, but not added to the function. Now that the
394 'then' and 'else' blocks are emitted, we can finish up with the merge
395 code:
396
397 .. code-block:: c++
398
399 // Emit merge block.
400 TheFunction->getBasicBlockList().push_back(MergeBB);
401 Builder.SetInsertPoint(MergeBB);
402 PHINode *PN =
403 Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
404
405 PN->addIncoming(ThenV, ThenBB);
406 PN->addIncoming(ElseV, ElseBB);
407 return PN;
408 }
409
410 The first two lines here are now familiar: the first adds the "merge"
411 block to the Function object (it was previously floating, like the else
412 block above). The second changes the insertion point so that newly
413 created code will go into the "merge" block. Once that is done, we need
414 to create the PHI node and set up the block/value pairs for the PHI.
415
416 Finally, the CodeGen function returns the phi node as the value computed
417 by the if/then/else expression. In our example above, this returned
418 value will feed into the code for the top-level function, which will
419 create the return instruction.
420
421 Overall, we now have the ability to execute conditional code in
422 Kaleidoscope. With this extension, Kaleidoscope is a fairly complete
423 language that can calculate a wide variety of numeric functions. Next up
424 we'll add another useful expression that is familiar from non-functional
425 languages...
426
427 'for' Loop Expression
2 =====================
3 Kaleidoscope Tutorial
4284 =====================
4295
430 Now that we know how to add basic control flow constructs to the
431 language, we have the tools to add more powerful things. Let's add
432 something more aggressive, a 'for' expression:
433
434 ::
435
436 extern putchard(char);
437 def printstar(n)
438 for i = 1, i < n, 1.0 in
439 putchard(42); # ascii 42 = '*'
440
441 # print 100 '*' characters
442 printstar(100);
443
444 This expression defines a new variable ("i" in this case) which iterates
445 from a starting value, while the condition ("i < n" in this case) is
446 true, incrementing by an optional step value ("1.0" in this case). If
447 the step value is omitted, it defaults to 1.0. While the loop is true,
448 it executes its body expression. Because we don't have anything better
449 to return, we'll just define the loop as always returning 0.0. In the
450 future when we have mutable variables, it will get more useful.
451
452 As before, let's talk about the changes that we need to Kaleidoscope to
453 support this.
454
455 Lexer Extensions for the 'for' Loop
456 -----------------------------------
457
458 The lexer extensions are the same sort of thing as for if/then/else:
459
460 .. code-block:: c++
461
462 ... in enum Token ...
463 // control
464 tok_if = -6, tok_then = -7, tok_else = -8,
465 tok_for = -9, tok_in = -10
466
467 ... in gettok ...
468 if (IdentifierStr == "def")
469 return tok_def;
470 if (IdentifierStr == "extern")
471 return tok_extern;
472 if (IdentifierStr == "if")
473 return tok_if;
474 if (IdentifierStr == "then")
475 return tok_then;
476 if (IdentifierStr == "else")
477 return tok_else;
478 if (IdentifierStr == "for")
479 return tok_for;
480 if (IdentifierStr == "in")
481 return tok_in;
482 return tok_identifier;
483
484 AST Extensions for the 'for' Loop
485 ---------------------------------
486
487 The AST node is just as simple. It basically boils down to capturing the
488 variable name and the constituent expressions in the node.
489
490 .. code-block:: c++
491
492 /// ForExprAST - Expression class for for/in.
493 class ForExprAST : public ExprAST {
494 std::string VarName;
495 std::unique_ptr Start, End, Step, Body;
496
497 public:
498 ForExprAST(const std::string &VarName, std::unique_ptr Start,
499 std::unique_ptr End, std::unique_ptr Step,
500 std::unique_ptr Body)
501 : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
502 Step(std::move(Step)), Body(std::move(Body)) {}
503
504 Value *codegen() override;
505 };
506
507 Parser Extensions for the 'for' Loop
508 ------------------------------------
509
510 The parser code is also fairly standard. The only interesting thing here
511 is handling of the optional step value. The parser code handles it by
512 checking to see if the second comma is present. If not, it sets the step
513 value to null in the AST node:
514
515 .. code-block:: c++
516
517 /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
518 static std::unique_ptr ParseForExpr() {
519 getNextToken(); // eat the for.
520
521 if (CurTok != tok_identifier)
522 return LogError("expected identifier after for");
523
524 std::string IdName = IdentifierStr;
525 getNextToken(); // eat identifier.
526
527 if (CurTok != '=')
528 return LogError("expected '=' after for");
529 getNextToken(); // eat '='.
530
531
532 auto Start = ParseExpression();
533 if (!Start)
534 return nullptr;
535 if (CurTok != ',')
536 return LogError("expected ',' after for start value");
537 getNextToken();
538
539 auto End = ParseExpression();
540 if (!End)
541 return nullptr;
542
543 // The step value is optional.
544 std::unique_ptr Step;
545 if (CurTok == ',') {
546 getNextToken();
547 Step = ParseExpression();
548 if (!Step)
549 return nullptr;
550 }
551
552 if (CurTok != tok_in)
553 return LogError("expected 'in' after for");
554 getNextToken(); // eat 'in'.
555
556 auto Body = ParseExpression();
557 if (!Body)
558 return nullptr;
559
560 return llvm::make_unique(IdName, std::move(Start),
561 std::move(End), std::move(Step),
562 std::move(Body));
563 }
564
565 And again we hook it up as a primary expression:
566
567 .. code-block:: c++
568
569 static std::unique_ptr ParsePrimary() {
570 switch (CurTok) {
571 default:
572 return LogError("unknown token when expecting an expression");
573 case tok_identifier:
574 return ParseIdentifierExpr();
575 case tok_number:
576 return ParseNumberExpr();
577 case '(':
578 return ParseParenExpr();
579 case tok_if:
580 return ParseIfExpr();
581 case tok_for:
582 return ParseForExpr();
583 }
584 }
585
586 LLVM IR for the 'for' Loop
587 --------------------------
588
589 Now we get to the good part: the LLVM IR we want to generate for this
590 thing. With the simple example above, we get this LLVM IR (note that
591 this dump is generated with optimizations disabled for clarity):
592
593 .. code-block:: llvm
594
595 declare double @putchard(double)
596
597 define double @printstar(double %n) {
598 entry:
599 ; initial value = 1.0 (inlined into phi)
600 br label %loop
601
602 loop: ; preds = %loop, %entry
603 %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
604 ; body
605 %calltmp = call double @putchard(double 4.200000e+01)
606 ; increment
607 %nextvar = fadd double %i, 1.000000e+00
608
609 ; termination test
610 %cmptmp = fcmp ult double %i, %n
611 %booltmp = uitofp i1 %cmptmp to double
612 %loopcond = fcmp one double %booltmp, 0.000000e+00
613 br i1 %loopcond, label %loop, label %afterloop
614
615 afterloop: ; preds = %loop
616 ; loop always returns 0.0
617 ret double 0.000000e+00
618 }
619
620 This loop contains all the same constructs we saw before: a phi node,
621 several expressions, and some basic blocks. Let's see how this fits
622 together.
623
624 Code Generation for the 'for' Loop
625 ----------------------------------
626
627 The first part of codegen is very simple: we just output the start
628 expression for the loop value:
629
630 .. code-block:: c++
631
632 Value *ForExprAST::codegen() {
633 // Emit the start code first, without 'variable' in scope.
634 Value *StartVal = Start->codegen();
635 if (!StartVal)
636 return nullptr;
637
638 With this out of the way, the next step is to set up the LLVM basic
639 block for the start of the loop body. In the case above, the whole loop
640 body is one block, but remember that the body code itself could consist
641 of multiple blocks (e.g. if it contains an if/then/else or a for/in
642 expression).
643
644 .. code-block:: c++
645
646 // Make the new basic block for the loop header, inserting after current
647 // block.
648 Function *TheFunction = Builder.GetInsertBlock()->getParent();
649 BasicBlock *PreheaderBB = Builder.GetInsertBlock();
650 BasicBlock *LoopBB =
651 BasicBlock::Create(TheContext, "loop", TheFunction);
652
653 // Insert an explicit fall through from the current block to the LoopBB.
654 Builder.CreateBr(LoopBB);
655
656 This code is similar to what we saw for if/then/else. Because we will
657 need it to create the Phi node, we remember the block that falls through
658 into the loop. Once we have that, we create the actual block that starts
659 the loop and create an unconditional branch for the fall-through between
660 the two blocks.
661
662 .. code-block:: c++
663
664 // Start insertion in LoopBB.
665 Builder.SetInsertPoint(LoopBB);
666
667 // Start the PHI node with an entry for Start.
668 PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(TheContext),
669 2, VarName.c_str());
670 Variable->addIncoming(StartVal, PreheaderBB);
671
672 Now that the "preheader" for the loop is set up, we switch to emitting
673 code for the loop body. To begin with, we move the insertion point and
674 create the PHI node for the loop induction variable. Since we already
675 know the incoming value for the starting value, we add it to the Phi
676 node. Note that the Phi will eventually get a second value for the
677 backedge, but we can't set it up yet (because it doesn't exist!).
678
679 .. code-block:: c++
680
681 // Within the loop, the variable is defined equal to the PHI node. If it
682 // shadows an existing variable, we have to restore it, so save it now.
683 Value *OldVal = NamedValues[VarName];
684 NamedValues[VarName] = Variable;
685
686 // Emit the body of the loop. This, like any other expr, can change the
687 // current BB. Note that we ignore the value computed by the body, but don't
688 // allow an error.
689 if (!Body->codegen())
690 return nullptr;
691
692 Now the code starts to get more interesting. Our 'for' loop introduces a
693 new variable to the symbol table. This means that our symbol table can
694 now contain either function arguments or loop variables. To handle this,
695 before we codegen the body of the loop, we add the loop variable as the
696 current value for its name. Note that it is possible that there is a
697 variable of the same name in the outer scope. It would be easy to make
698 this an error (emit an error and return null if there is already an
699 entry for VarName) but we choose to allow shadowing of variables. In
700 order to handle this correctly, we remember the Value that we are
701 potentially shadowing in ``OldVal`` (which will be null if there is no
702 shadowed variable).
703
704 Once the loop variable is set into the symbol table, the code
705 recursively codegen's the body. This allows the body to use the loop
706 variable: any references to it will naturally find it in the symbol
707 table.
708
709 .. code-block:: c++
710
711 // Emit the step value.
712 Value *StepVal = nullptr;
713 if (Step) {
714 StepVal = Step->codegen();
715 if (!StepVal)
716 return nullptr;
717 } else {
718 // If not specified, use 1.0.
719 StepVal = ConstantFP::get(TheContext, APFloat(1.0));
720 }
721
722 Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
723
724 Now that the body is emitted, we compute the next value of the iteration
725 variable by adding the step value, or 1.0 if it isn't present.
726 '``NextVar``' will be the value of the loop variable on the next
727 iteration of the loop.
728
729 .. code-block:: c++
730
731 // Compute the end condition.
732 Value *EndCond = End->codegen();
733 if (!EndCond)
734 return nullptr;
735
736 // Convert condition to a bool by comparing non-equal to 0.0.
737 EndCond = Builder.CreateFCmpONE(
738 EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
739
740 Finally, we evaluate the exit value of the loop, to determine whether
741 the loop should exit. This mirrors the condition evaluation for the
742 if/then/else statement.
743
744 .. code-block:: c++
745
746 // Create the "after loop" block and insert it.
747 BasicBlock *LoopEndBB = Builder.GetInsertBlock();
748 BasicBlock *AfterBB =
749 BasicBlock::Create(TheContext, "afterloop", TheFunction);
750
751 // Insert the conditional branch into the end of LoopEndBB.
752 Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
753
754 // Any new code will be inserted in AfterBB.
755 Builder.SetInsertPoint(AfterBB);
756
757 With the code for the body of the loop complete, we just need to finish
758 up the control flow for it. This code remembers the end block (for the
759 phi node), then creates the block for the loop exit ("afterloop"). Based
760 on the value of the exit condition, it creates a conditional branch that
761 chooses between executing the loop again and exiting the loop. Any
762 future code is emitted in the "afterloop" block, so it sets the
763 insertion position to it.
764
765 .. code-block:: c++
766
767 // Add a new entry to the PHI node for the backedge.
768 Variable->addIncoming(NextVar, LoopEndBB);
769
770 // Restore the unshadowed variable.
771 if (OldVal)
772 NamedValues[VarName] = OldVal;
773 else
774 NamedValues.erase(VarName);
775
776 // for expr always returns 0.0.
777 return Constant::getNullValue(Type::getDoubleTy(TheContext));
778 }
779
780 The final code handles various cleanups: now that we have the "NextVar"
781 value, we can add the incoming value to the loop PHI node. After that,
782 we remove the loop variable from the symbol table, so that it isn't in
783 scope after the for loop. Finally, code generation of the for loop
784 always returns 0.0, so that is what we return from
785 ``ForExprAST::codegen()``.
786
787 With this, we conclude the "adding control flow to Kaleidoscope" chapter
788 of the tutorial. In this chapter we added two control flow constructs,
789 and used them to motivate a couple of aspects of the LLVM IR that are
790 important for front-end implementors to know. In the next chapter of our
791 saga, we will get a bit crazier and add `user-defined
792 operators `_ to our poor innocent language.
793
794 Full Code Listing
795 =================
796
797 Here is the complete code listing for our running example, enhanced with
798 the if/then/else and for expressions. To build this example, use:
799
800 .. code-block:: bash
801
802 # Compile
803 clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
804 # Run
805 ./toy
806
807 Here is the code:
808
809 .. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp
810 :language: c++
811
812 `Next: Extending the language: user-defined operators `_
813
6 The Kaleidoscope Tutorial has `moved to another location `_ .
None ============================================================
1 Kaleidoscope: Extending the Language: User-defined Operators
2 ============================================================
0 :orphan:
31
4 .. contents::
5 :local:
2 =====================
3 Kaleidoscope Tutorial
4 =====================
65
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 in languages like C++. In C++, you are only allowed to
34 redefine existing operators: you can't programmatically 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. By
44 using operator precedence parsing, it is very easy 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 Function *codegen();
146 const std::string &getName() const { return Name; }
147
148 bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
149 bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
150
151 char getOperatorName() const {
152 assert(isUnaryOp() || isBinaryOp());
153 return Name[Name.size() - 1];
154 }
155
156 unsigned getBinaryPrecedence() const { return Precedence; }
157 };
158
159 Basically, in addition to knowing a name for the prototype, we now keep
160 track of whether it was an operator, and if it was, what precedence
161 level the operator is at. The precedence is only used for binary
162 operators (as you'll see below, it just doesn't apply for unary
163 operators). Now that we have a way to represent the prototype for a
164 user-defined operator, we need to parse it:
165
166 .. code-block:: c++
167
168 /// prototype
169 /// ::= id '(' id* ')'
170 /// ::= binary LETTER number? (id, id)
171 static std::unique_ptr ParsePrototype() {
172 std::string FnName;
173
174 unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
175 unsigned BinaryPrecedence = 30;
176
177 switch (CurTok) {
178 default:
179 return LogErrorP("Expected function name in prototype");
180 case tok_identifier:
181 FnName = IdentifierStr;
182 Kind = 0;
183 getNextToken();
184 break;
185 case tok_binary:
186 getNextToken();
187 if (!isascii(CurTok))
188 return LogErrorP("Expected binary operator");
189 FnName = "binary";
190 FnName += (char)CurTok;
191 Kind = 2;
192 getNextToken();
193
194 // Read the precedence if present.
195 if (CurTok == tok_number) {
196 if (NumVal < 1 || NumVal > 100)
197 return LogErrorP("Invalid precedence: must be 1..100");
198 BinaryPrecedence = (unsigned)NumVal;
199 getNextToken();
200 }
201 break;
202 }
203
204 if (CurTok != '(')
205 return LogErrorP("Expected '(' in prototype");
206
207 std::vector ArgNames;
208 while (getNextToken() == tok_identifier)
209 ArgNames.push_back(IdentifierStr);
210 if (CurTok != ')')
211 return LogErrorP("Expected ')' in prototype");
212
213 // success.
214 getNextToken(); // eat ')'.
215
216 // Verify right number of names for operator.
217 if (Kind && ArgNames.size() != Kind)
218 return LogErrorP("Invalid number of operands for operator");
219
220 return llvm::make_unique(FnName, std::move(ArgNames), Kind != 0,
221 BinaryPrecedence);
222 }
223
224 This is all fairly straightforward parsing code, and we have already
225 seen a lot of similar code in the past. One interesting part about the
226 code above is the couple lines that set up ``FnName`` for binary
227 operators. This builds names like "binary@" for a newly defined "@"
228 operator. It then takes advantage of the fact that symbol names in the
229 LLVM symbol table are allowed to have any character in them, including
230 embedded nul characters.
231
232 The next interesting thing to add, is codegen support for these binary
233 operators. Given our current structure, this is a simple addition of a
234 default case for our existing binary operator node:
235
236 .. code-block:: c++
237
238 Value *BinaryExprAST::codegen() {
239 Value *L = LHS->codegen();
240 Value *R = RHS->codegen();
241 if (!L || !R)
242 return nullptr;
243
244 switch (Op) {
245 case '+':
246 return Builder.CreateFAdd(L, R, "addtmp");
247 case '-':
248 return Builder.CreateFSub(L, R, "subtmp");
249 case '*':
250 return Builder.CreateFMul(L, R, "multmp");
251 case '<':
252 L = Builder.CreateFCmpULT(L, R, "cmptmp");
253 // Convert bool 0/1 to double 0.0 or 1.0
254 return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
255 "booltmp");
256 default:
257 break;
258 }
259
260 // If it wasn't a builtin binary operator, it must be a user defined one. Emit
261 // a call to it.
262 Function *F = getFunction(std::string("binary") + Op);
263 assert(F && "binary operator not found!");
264
265 Value *Ops[2] = { L, R };
266 return Builder.CreateCall(F, Ops, "binop");
267 }
268
269 As you can see above, the new code is actually really simple. It just
270 does a lookup for the appropriate operator in the symbol table and
271 generates a function call to it. Since user-defined operators are just
272 built as normal functions (because the "prototype" boils down to a
273 function with the right name) everything falls into place.
274
275 The final piece of code we are missing, is a bit of top-level magic:
276
277 .. code-block:: c++
278
279 Function *FunctionAST::codegen() {
280 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
281 // reference to it for use below.
282 auto &P = *Proto;
283 FunctionProtos[Proto->getName()] = std::move(Proto);
284 Function *TheFunction = getFunction(P.getName());
285 if (!TheFunction)
286 return nullptr;
287
288 // If this is an operator, install it.
289 if (P.isBinaryOp())
290 BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
291
292 // Create a new basic block to start insertion into.
293 BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
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 - let's 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
326 Value *codegen() override;
327 };
328
329 This AST node is very simple and obvious by now. It directly mirrors the
330 binary operator AST node, except that it only has one child. With this,
331 we need to add the parsing logic. Parsing a unary operator is pretty
332 simple: we'll add a new function to do it:
333
334 .. code-block:: c++
335
336 /// unary
337 /// ::= primary
338 /// ::= '!' unary
339 static std::unique_ptr ParseUnary() {
340 // If the current token is not an operator, it must be a primary expr.
341 if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
342 return ParsePrimary();
343
344 // If this is a unary operator, read it.
345 int Opc = CurTok;
346 getNextToken();
347 if (auto Operand = ParseUnary())
348 return llvm::make_unique(Opc, std::move(Operand));
349 return nullptr;
350 }
351
352 The grammar we add is pretty straightforward here. If we see a unary
353 operator when parsing a primary operator, we eat the operator as a
354 prefix and parse the remaining piece as another unary operator. This
355 allows us to handle multiple unary operators (e.g. "!!x"). Note that
356 unary operators can't have ambiguous parses like binary operators can,
357 so there is no need for precedence information.
358
359 The problem with this function, is that we need to call ParseUnary from
360 somewhere. To do this, we change previous callers of ParsePrimary to
361 call ParseUnary instead:
362
363 .. code-block:: c++
364
365 /// binoprhs
366 /// ::= ('+' unary)*
367 static std::unique_ptr ParseBinOpRHS(int ExprPrec,
368 std::unique_ptr LHS) {
369 ...
370 // Parse the unary expression after the binary operator.
371 auto RHS = ParseUnary();
372 if (!RHS)
373 return nullptr;
374 ...
375 }
376 /// expression
377 /// ::= unary binoprhs
378 ///
379 static std::unique_ptr ParseExpression() {
380 auto LHS = ParseUnary();
381 if (!LHS)
382 return nullptr;
383
384 return ParseBinOpRHS(0, std::move(LHS));
385 }
386
387 With these two simple changes, we are now able to parse unary operators
388 and build the AST for them. Next up, we need to add parser support for
389 prototypes, to parse the unary operator prototype. We extend the binary
390 operator code above with:
391
392 .. code-block:: c++
393
394 /// prototype
395 /// ::= id '(' id* ')'
396 /// ::= binary LETTER number? (id, id)
397 /// ::= unary LETTER (id)
398 static std::unique_ptr ParsePrototype() {
399 std::string FnName;
400
401 unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
402 unsigned BinaryPrecedence = 30;
403
404 switch (CurTok) {
405 default:
406 return LogErrorP("Expected function name in prototype");
407 case tok_identifier:
408 FnName = IdentifierStr;
409 Kind = 0;
410 getNextToken();
411 break;
412 case tok_unary:
413 getNextToken();
414 if (!isascii(CurTok))
415 return LogErrorP("Expected unary operator");
416 FnName = "unary";
417 FnName += (char)CurTok;
418 Kind = 1;
419 getNextToken();
420 break;
421 case tok_binary:
422 ...
423
424 As with binary operators, we name unary operators with a name that
425 includes the operator character. This assists us at code generation
426 time. Speaking of, the final piece we need to add is codegen support for
427 unary operators. It looks like this:
428
429 .. code-block:: c++
430
431 Value *UnaryExprAST::codegen() {
432 Value *OperandV = Operand->codegen();
433 if (!OperandV)
434 return nullptr;
435
436 Function *F = getFunction(std::string("unary") + Opcode);
437 if (!F)
438 return LogErrorV("Unknown unary operator");
439
440 return Builder.CreateCall(F, OperandV, "unop");
441 }
442
443 This code is similar to, but simpler than, the code for binary
444 operators. It is simpler primarily because it doesn't need to handle any
445 predefined operators.
446
447 Kicking the Tires
448 =================
449
450 It is somewhat hard to believe, but with a few simple extensions we've
451 covered in the last chapters, we have grown a real-ish language. With
452 this, we can do a lot of interesting things, including I/O, math, and a
453 bunch of other things. For example, we can now add a nice sequencing
454 operator (printd is defined to print out the specified value and a
455 newline):
456
457 ::
458
459 ready> extern printd(x);
460 Read extern:
461 declare double @printd(double)
462
463 ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
464 ...
465 ready> printd(123) : printd(456) : printd(789);
466 123.000000
467 456.000000
468 789.000000
469 Evaluated to 0.000000
470
471 We can also define a bunch of other "primitive" operations, such as:
472
473 ::
474
475 # Logical unary not.
476 def unary!(v)
477 if v then
478 0
479 else
480 1;
481
482 # Unary negate.
483 def unary-(v)
484 0-v;
485
486 # Define > with the same precedence as <.
487 def binary> 10 (LHS RHS)
488 RHS < LHS;
489
490 # Binary logical or, which does not short circuit.
491 def binary| 5 (LHS RHS)
492 if LHS then
493 1
494 else if RHS then
495 1
496 else
497 0;
498
499 # Binary logical and, which does not short circuit.
500 def binary& 6 (LHS RHS)
501 if !LHS then
502 0
503 else
504 !!RHS;
505
506 # Define = with slightly lower precedence than relationals.
507 def binary = 9 (LHS RHS)
508 !(LHS < RHS | LHS > RHS);
509
510 # Define ':' for sequencing: as a low-precedence operator that ignores operands
511 # and just returns the RHS.
512 def binary : 1 (x y) y;
513
514 Given the previous if/then/else support, we can also define interesting
515 functions for I/O. For example, the following prints out a character
516 whose "density" reflects the value passed in: the lower the value, the
517 denser the character:
518
519 ::
520
521 ready> extern putchard(char);
522 ...
523 ready> def printdensity(d)
524 if d > 8 then
525 putchard(32) # ' '
526 else if d > 4 then
527 putchard(46) # '.'
528 else if d > 2 then
529 putchard(43) # '+'
530 else
531 putchard(42); # '*'
532 ...
533 ready> printdensity(1): printdensity(2): printdensity(3):
534 printdensity(4): printdensity(5): printdensity(9):
535 putchard(10);
536 **++.
537 Evaluated to 0.000000
538
539 Based on these simple primitive operations, we can start to define more
540 interesting things. For example, here's a little function that determines
541 the number of iterations it takes for a certain function in the complex
542 plane to diverge:
543
544 ::
545
546 # Determine whether the specific location diverges.
547 # Solve for z = z^2 + c in the complex plane.
548 def mandelconverger(real imag iters creal cimag)
549 if iters > 255 | (real*real + imag*imag > 4) then
550 iters
551 else
552 mandelconverger(real*real - imag*imag + creal,
553 2*real*imag + cimag,
554 iters+1, creal, cimag);
555
556 # Return the number of iterations required for the iteration to escape
557 def mandelconverge(real imag)
558 mandelconverger(real, imag, 0, real, imag);
559
560 This "``z = z2 + c``" function is a beautiful little creature that is
561 the basis for computation of the `Mandelbrot
562 Set `_. Our
563 ``mandelconverge`` function returns the number of iterations that it
564 takes for a complex orbit to escape, saturating to 255. This is not a
565 very useful function by itself, but if you plot its value over a
566 two-dimensional plane, you can see the Mandelbrot set. Given that we are
567 limited to using putchard here, our amazing graphical output is limited,
568 but we can whip together something using the density plotter above:
569
570 ::
571
572 # Compute and plot the mandelbrot set with the specified 2 dimensional range
573 # info.
574 def mandelhelp(xmin xmax xstep ymin ymax ystep)
575 for y = ymin, y < ymax, ystep in (
576 (for x = xmin, x < xmax, xstep in
577 printdensity(mandelconverge(x,y)))
578 : putchard(10)
579 )
580
581 # mandel - This is a convenient helper function for plotting the mandelbrot set
582 # from the specified position with the specified Magnification.
583 def mandel(realstart imagstart realmag imagmag)
584 mandelhelp(realstart, realstart+realmag*78, realmag,
585 imagstart, imagstart+imagmag*40, imagmag);
586
587 Given this, we can try plotting out the mandelbrot set! Lets try it out:
588
589 ::
590