llvm.org GIT mirror llvm / 35295ff
Chapter 5, 6, and 7 of the ocaml/kaleidoscope tutorial and fix some tabs in chapter 3 and 4. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@48978 91177308-0d34-0410-b5e6-96231b3b80d8 Erick Tryzelaar 11 years ago
5 changed file(s) with 5051 addition(s) and 6 deletion(s). Raw diff Collapse all Expand all
182182 let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
183183 build_uitofp i double_type "booltmp" builder
184184 | _ -> raise (Error "invalid binary operator")
185 end
185 end
186186
187187
188188
279279 (* Make the function type: double(double,double) etc. *)
280280 let doubles = Array.make (Array.length args) double_type in
281281 let ft = function_type double_type doubles in
282 let f =
282 let f =
283283 match lookup_function name the_module with
284284
285285
236236
237237

                  
                
238238 let codegen_func the_fpm = function
239 ...
239 ...
240240 try
241241 let ret_val = codegen_expr body in
242242
315315 ...
316316 let main () =
317317 ...
318
319 (* Create the JIT. *)
318 (* Create the JIT. *)
320319 let the_module_provider = ModuleProvider.create Codegen.the_module in
321 let the_execution_engine = ExecutionEngine.create the_module_provider in
320 let the_execution_engine = ExecutionEngine.create the_module_provider in
322321 ...
323322
324323
506505 Here is the complete code listing for our running example, enhanced with the
507506 LLVM JIT and optimizer. To build this example, use:
508507

508
509
510

                  
                
511 # Compile
512 ocamlbuild toy.byte
513 # Run
514 ./toy.byte
515
516
517
518

Here is the code:

509519
510520
511521
_tags:
0
1 "http://www.w3.org/TR/html4/strict.dtd">
2
3
4
5 Kaleidoscope: Extending the Language: Control Flow
6
7
8
9
10
11
12
13
14
Kaleidoscope: Extending the Language: Control Flow
15
16
17
  • Up to Tutorial Index
  • 18
  • Chapter 5
  • 19
    20
  • Chapter 5 Introduction
  • 21
  • If/Then/Else
  • 22
    23
  • Lexer Extensions
  • 24
  • AST Extensions
  • 25
  • Parser Extensions
  • 26
  • LLVM IR
  • 27
  • Code Generation
  • 28
    29
    30
  • 'for' Loop Expression
  • 31
    32
  • Lexer Extensions
  • 33
  • AST Extensions
  • 34
  • Parser Extensions
  • 35
  • LLVM IR
  • 36
  • Code Generation
  • 37
    38
    39
  • Full Code Listing
  • 40
    41
    42
  • Chapter 6: Extending the Language:
  • 43 User-defined Operators
    44
    45
    46
    47

    48 Written by Chris Lattner
    49 and Erick Tryzelaar
    50

    51
    52
    53
    54
    55
    56
    57
    58
    59

    Welcome to Chapter 5 of the "Implementing a language

    60 with LLVM" tutorial. Parts 1-4 described the implementation of the simple
    61 Kaleidoscope language and included support for generating LLVM IR, followed by
    62 optimizations and a JIT compiler. Unfortunately, as presented, Kaleidoscope is
    63 mostly useless: it has no control flow other than call and return. This means
    64 that you can't have conditional branches in the code, significantly limiting its
    65 power. In this episode of "build that compiler", we'll extend Kaleidoscope to
    66 have an if/then/else expression plus a simple 'for' loop.

    67
    68
    69
    70
    71
    72
    73
    74
    75
    76

    77 Extending Kaleidoscope to support if/then/else is quite straightforward. It
    78 basically requires adding lexer support for this "new" concept to the lexer,
    79 parser, AST, and LLVM code emitter. This example is nice, because it shows how
    80 easy it is to "grow" a language over time, incrementally extending it as new
    81 ideas are discovered.

    82
    83

    Before we get going on "how" we add this extension, lets talk about "what" we

    84 want. The basic idea is that we want to be able to write this sort of thing:
    85

    86
    87
    88
    
                      
                    
    89 def fib(x)
    90 if x < 3 then
    91 1
    92 else
    93 fib(x-1)+fib(x-2);
    94
    95
    96
    97

    In Kaleidoscope, every construct is an expression: there are no statements.

    98 As such, the if/then/else expression needs to return a value like any other.
    99 Since we're using a mostly functional form, we'll have it evaluate its
    100 conditional, then return the 'then' or 'else' value based on how the condition
    101 was resolved. This is very similar to the C "?:" expression.

    102
    103

    The semantics of the if/then/else expression is that it evaluates the

    104 condition to a boolean equality value: 0.0 is considered to be false and
    105 everything else is considered to be true.
    106 If the condition is true, the first subexpression is evaluated and returned, if
    107 the condition is false, the second subexpression is evaluated and returned.
    108 Since Kaleidoscope allows side-effects, this behavior is important to nail down.
    109

    110
    111

    Now that we know what we "want", lets break this down into its constituent

    112 pieces.

    113
    114
    115
    116
    117
    118 If/Then/Else
    119
    120
    121
    122
    123
    124

    The lexer extensions are straightforward. First we add new variants

    125 for the relevant tokens:

    126
    127
    128
    
                      
                    
    129 (* control *)
    130 | If | Then | Else | For | In
    131
    132
    133
    134

    Once we have that, we recognize the new keywords in the lexer. This is pretty simple

    135 stuff:

    136
    137
    138
    
                      
                    
    139 ...
    140 match Buffer.contents buffer with
    141 | "def" -> [< 'Token.Def; stream >]
    142 | "extern" -> [< 'Token.Extern; stream >]
    143 | "if" -> [< 'Token.If; stream >]
    144 | "then" -> [< 'Token.Then; stream >]
    145 | "else" -> [< 'Token.Else; stream >]
    146 | "for" -> [< 'Token.For; stream >]
    147 | "in" -> [< 'Token.In; stream >]
    148 | id -> [< 'Token.Ident id; stream >]
    149
    150
    151
    152
    153
    154
    155
    156 If/Then/Else
    157
    158
    159
    160
    161

    To represent the new expression we add a new AST variant for it:

    162
    163
    164
    
                      
                    
    165 type expr =
    166 ...
    167 (* variant for if/then/else. *)
    168 | If of expr * expr * expr
    169
    170
    171
    172

    The AST variant just has pointers to the various subexpressions.

    173
    174
    175
    176
    177
    178 If/Then/Else
    179
    180
    181
    182
    183

    Now that we have the relevant tokens coming from the lexer and we have the

    184 AST node to build, our parsing logic is relatively straightforward. First we
    185 define a new parsing function:

    186
    187
    188
    
                      
                    
    189 let rec parse_primary = parser
    190 ...
    191 (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
    192 | [< 'Token.If; c=parse_expr;
    193 'Token.Then ?? "expected 'then'"; t=parse_expr;
    194 'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
    195 Ast.If (c, t, e)
    196
    197
    198
    199

    Next we hook it up as a primary expression:

    200
    201
    202
    
                      
                    
    203 let rec parse_primary = parser
    204 ...
    205 (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
    206 | [< 'Token.If; c=parse_expr;
    207 'Token.Then ?? "expected 'then'"; t=parse_expr;
    208 'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
    209 Ast.If (c, t, e)
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221

    Now that we have it parsing and building the AST, the final piece is adding

    222 LLVM code generation support. This is the most interesting part of the
    223 if/then/else example, because this is where it starts to introduce new concepts.
    224 All of the code above has been thoroughly described in previous chapters.
    225

    226
    227

    To motivate the code we want to produce, lets take a look at a simple

    228 example. Consider:

    229
    230
    231
    
                      
                    
    232 extern foo();
    233 extern bar();
    234 def baz(x) if x then foo() else bar();
    235
    236
    237
    238

    If you disable optimizations, the code you'll (soon) get from Kaleidoscope

    239 looks like this:

    240
    241
    242
    
                      
                    
    243 declare double @foo()
    244
    245 declare double @bar()
    246
    247 define double @baz(double %x) {
    248 entry:
    249 %ifcond = fcmp one double %x, 0.000000e+00
    250 br i1 %ifcond, label %then, label %else
    251
    252 then: ; preds = %entry
    253 %calltmp = call double @foo()
    254 br label %ifcont
    255
    256 else: ; preds = %entry
    257 %calltmp1 = call double @bar()
    258 br label %ifcont
    259
    260 ifcont: ; preds = %else, %then
    261 %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
    262 ret double %iftmp
    263 }
    264
    265
    266
    267

    To visualize the control flow graph, you can use a nifty feature of the LLVM

    268 'opt' tool. If you put this LLVM IR
    269 into "t.ll" and run "llvm-as < t.ll | opt -analyze -view-cfg",
    270 href="../ProgrammersManual.html#ViewGraph">a window will pop up and you'll
    271 see this graph:

    272
    273
    Example CFG
    274 height="315">
    275
    276

    Another way to get this is to call "Llvm_analysis.view_function_cfg

    277 f" or "Llvm_analysis.view_function_cfg_only f" (where f
    278 is a "Function") either by inserting actual calls into the code and
    279 recompiling or by calling these in the debugger. LLVM has many nice features
    280 for visualizing various graphs.

    281
    282

    Getting back to the generated code, it is fairly simple: the entry block

    283 evaluates the conditional expression ("x" in our case here) and compares the
    284 result to 0.0 with the "fcmp one"
    285 instruction ('one' is "Ordered and Not Equal"). Based on the result of this
    286 expression, the code jumps to either the "then" or "else" blocks, which contain
    287 the expressions for the true/false cases.

    288
    289

    Once the then/else blocks are finished executing, they both branch back to the

    290 'ifcont' block to execute the code that happens after the if/then/else. In this
    291 case the only thing left to do is to return to the caller of the function. The
    292 question then becomes: how does the code know which expression to return?

    293
    294

    The answer to this question involves an important SSA operation: the

    295 Phi
    296 operation. If you're not familiar with SSA,
    297 href="http://en.wikipedia.org/wiki/Static_single_assignment_form">the wikipedia
    298 article is a good introduction and there are various other introductions to
    299 it available on your favorite search engine. The short version is that
    300 "execution" of the Phi operation requires "remembering" which block control came
    301 from. The Phi operation takes on the value corresponding to the input control
    302 block. In this case, if control comes in from the "then" block, it gets the
    303 value of "calltmp". If control comes from the "else" block, it gets the value
    304 of "calltmp1".

    305
    306

    At this point, you are probably starting to think "Oh no! This means my

    307 simple and elegant front-end will have to start generating SSA form in order to
    308 use LLVM!". Fortunately, this is not the case, and we strongly advise
    309 not implementing an SSA construction algorithm in your front-end
    310 unless there is an amazingly good reason to do so. In practice, there are two
    311 sorts of values that float around in code written for your average imperative
    312 programming language that might need Phi nodes:

    313
    314
    315
  • Code that involves user variables: x = 1; x = x + 1;
  • 316
  • Values that are implicit in the structure of your AST, such as the Phi node
  • 317 in this case.
    318
    319
    320

    In Chapter 7 of this tutorial ("mutable

    321 variables"), we'll talk about #1
    322 in depth. For now, just believe me that you don't need SSA construction to
    323 handle this case. For #2, you have the choice of using the techniques that we will
    324 describe for #1, or you can insert Phi nodes directly, if convenient. In this
    325 case, it is really really easy to generate the Phi node, so we choose to do it
    326 directly.

    327
    328

    Okay, enough of the motivation and overview, lets generate code!

    329
    330
    331
    332
    333
    334 If/Then/Else
    335
    336
    337
    338
    339

    In order to generate code for this, we implement the Codegen method

    340 for IfExprAST:

    341
    342
    343
    
                      
                    
    344 let rec codegen_expr = function
    345 ...
    346 | Ast.If (cond, then_, else_) ->
    347 let cond = codegen_expr cond in
    348
    349 (* Convert condition to a bool by comparing equal to 0.0 *)
    350 let zero = const_float double_type 0.0 in
    351 let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
    352
    353
    354
    355

    This code is straightforward and similar to what we saw before. We emit the

    356 expression for the condition, then compare that value to zero to get a truth
    357 value as a 1-bit (bool) value.

    358
    359
    360
    
                      
                    
    361 (* Grab the first block so that we might later add the conditional branch
    362 * to it at the end of the function. *)
    363 let start_bb = insertion_block builder in
    364 let the_function = block_parent start_bb in
    365
    366 let then_bb = append_block "then" the_function in
    367 position_at_end then_bb builder;
    368
    369
    370
    371

    372 As opposed to the C++ tutorial, we have to build
    373 our basic blocks bottom up since we can't have dangling BasicBlocks. We start
    374 off by saving a pointer to the first block (which might not be the entry
    375 block), which we'll need to build a conditional branch later. We do this by
    376 asking the builder for the current BasicBlock. The fourth line
    377 gets the current Function object that is being built. It gets this by the
    378 start_bb for its "parent" (the function it is currently embedded
    379 into).

    380
    381

    Once it has that, it creates one block. It is automatically appended into

    382 the function's list of blocks.

    383
    384
    385
    
                      
                    
    386 (* Emit 'then' value. *)
    387 position_at_end then_bb builder;
    388 let then_val = codegen_expr then_ in
    389
    390 (* Codegen of 'then' can change the current block, update then_bb for the
    391 * phi. We create a new name because one is used for the phi node, and the
    392 * other is used for the conditional branch. *)
    393 let new_then_bb = insertion_block builder in
    394
    395
    396
    397

    We move the builder to start inserting into the "then" block. Strictly

    398 speaking, this call moves the insertion point to be at the end of the specified
    399 block. However, since the "then" block is empty, it also starts out by
    400 inserting at the beginning of the block. :)

    401
    402

    Once the insertion point is set, we recursively codegen the "then" expression

    403 from the AST.

    404
    405

    The final line here is quite subtle, but is very important. The basic issue

    406 is that when we create the Phi node in the merge block, we need to set up the
    407 block/value pairs that indicate how the Phi will work. Importantly, the Phi
    408 node expects to have an entry for each predecessor of the block in the CFG. Why
    409 then, are we getting the current block when we just set it to ThenBB 5 lines
    410 above? The problem is that the "Then" expression may actually itself change the
    411 block that the Builder is emitting into if, for example, it contains a nested
    412 "if/then/else" expression. Because calling Codegen recursively could
    413 arbitrarily change the notion of the current block, we are required to get an
    414 up-to-date value for code that will set up the Phi node.

    415
    416
    417
    
                      
                    
    418 (* Emit 'else' value. *)
    419 let else_bb = append_block "else" the_function in
    420 position_at_end else_bb builder;
    421 let else_val = codegen_expr else_ in
    422
    423 (* Codegen of 'else' can change the current block, update else_bb for the
    424 * phi. *)
    425 let new_else_bb = insertion_block builder in
    426
    427
    428
    429

    Code generation for the 'else' block is basically identical to codegen for

    430 the 'then' block.

    431
    432
    433
    
                      
                    
    434 (* Emit merge block. *)
    435 let merge_bb = append_block "ifcont" the_function in
    436 position_at_end merge_bb builder;
    437 let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
    438 let phi = build_phi incoming "iftmp" builder in
    439
    440
    441
    442

    The first two lines here are now familiar: the first adds the "merge" block

    443 to the Function object. The second block changes the insertion point so that
    444 newly created code will go into the "merge" block. Once that is done, we need
    445 to create the PHI node and set up the block/value pairs for the PHI.

    446
    447
    448
    
                      
                    
    449 (* Return to the start block to add the conditional branch. *)
    450 position_at_end start_bb builder;
    451 ignore (build_cond_br cond_val then_bb else_bb builder);
    452
    453
    454
    455

    Once the blocks are created, we can emit the conditional branch that chooses

    456 between them. Note that creating new blocks does not implicitly affect the
    457 LLVMBuilder, so it is still inserting into the block that the condition
    458 went into. This is why we needed to save the "start" block.

    459
    460
    461
    
                      
                    
    462 (* Set a unconditional branch at the end of the 'then' block and the
    463 * 'else' block to the 'merge' block. *)
    464 position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
    465 position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
    466
    467 (* Finally, set the builder to the end of the merge block. *)
    468 position_at_end merge_bb builder;
    469
    470 phi
    471
    472
    473
    474

    To finish off the blocks, we create an unconditional branch

    475 to the merge block. One interesting (and very important) aspect of the LLVM IR
    476 is that it requires all basic blocks
    477 to be "terminated" with a control flow
    478 instruction such as return or branch. This means that all control flow,
    479 including fall throughs must be made explicit in the LLVM IR. If you
    480 violate this rule, the verifier will emit an error.
    481
    482

    Finally, the CodeGen function returns the phi node as the value computed by

    483 the if/then/else expression. In our example above, this returned value will
    484 feed into the code for the top-level function, which will create the return
    485 instruction.

    486
    487

    Overall, we now have the ability to execute conditional code in

    488 Kaleidoscope. With this extension, Kaleidoscope is a fairly complete language
    489 that can calculate a wide variety of numeric functions. Next up we'll add
    490 another useful expression that is familiar from non-functional languages...

    491
    492
    493
    494
    495
    496
    497
    498
    499
    500

    Now that we know how to add basic control flow constructs to the language,

    501 we have the tools to add more powerful things. Lets add something more
    502 aggressive, a 'for' expression:

    503
    504
    505
    
                      
                    
    506 extern putchard(char);
    507 def printstar(n)
    508 for i = 1, i < n, 1.0 in
    509 putchard(42); # ascii 42 = '*'
    510
    511 # print 100 '*' characters
    512 printstar(100);
    513
    514
    515
    516

    This expression defines a new variable ("i" in this case) which iterates from

    517 a starting value, while the condition ("i < n" in this case) is true,
    518 incrementing by an optional step value ("1.0" in this case). If the step value
    519 is omitted, it defaults to 1.0. While the loop is true, it executes its
    520 body expression. Because we don't have anything better to return, we'll just
    521 define the loop as always returning 0.0. In the future when we have mutable
    522 variables, it will get more useful.

    523
    524

    As before, lets talk about the changes that we need to Kaleidoscope to

    525 support this.

    526
    527
    528
    529
    530
    531 the 'for' Loop
    532
    533
    534
    535
    536

    The lexer extensions are the same sort of thing as for if/then/else:

    537
    538
    539
    
                      
                    
    540 ... in Token.token ...
    541 (* control *)
    542 | If | Then | Else
    543 | For | In
    544
    545 ... in Lexer.lex_ident...
    546 match Buffer.contents buffer with
    547 | "def" -> [< 'Token.Def; stream >]
    548 | "extern" -> [< 'Token.Extern; stream >]
    549 | "if" -> [< 'Token.If; stream >]
    550 | "then" -> [< 'Token.Then; stream >]
    551 | "else" -> [< 'Token.Else; stream >]
    552 | "for" -> [< 'Token.For; stream >]
    553 | "in" -> [< 'Token.In; stream >]
    554 | id -> [< 'Token.Ident id; stream >]
    555
    556
    557
    558
    559
    560
    561
    562 the 'for' Loop
    563
    564
    565
    566
    567

    The AST variant is just as simple. It basically boils down to capturing

    568 the variable name and the constituent expressions in the node.

    569
    570
    571
    
                      
                    
    572 type expr =
    573 ...
    574 (* variant for for/in. *)
    575 | For of string * expr * expr * expr option * expr
    576
    577
    578
    579
    580
    581
    582
    583 the 'for' Loop
    584
    585
    586
    587
    588

    The parser code is also fairly standard. The only interesting thing here is

    589 handling of the optional step value. The parser code handles it by checking to
    590 see if the second comma is present. If not, it sets the step value to null in
    591 the AST node:

    592
    593
    594
    
                      
                    
    595 let rec parse_primary = parser
    596 ...
    597 (* forexpr
    598 ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
    599 | [< 'Token.For;
    600 'Token.Ident id ?? "expected identifier after for";
    601 'Token.Kwd '=' ?? "expected '=' after for";
    602 stream >] ->
    603 begin parser
    604 | [<
    605 start=parse_expr;
    606 'Token.Kwd ',' ?? "expected ',' after for";
    607 end_=parse_expr;
    608 stream >] ->
    609 let step =
    610 begin parser
    611 | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
    612 | [< >] -> None
    613 end stream
    614 in
    615 begin parser
    616 | [< 'Token.In; body=parse_expr >] ->
    617 Ast.For (id, start, end_, step, body)
    618 | [< >] ->
    619 raise (Stream.Error "expected 'in' after for")
    620 end stream
    621 | [< >] ->
    622 raise (Stream.Error "expected '=' after for")
    623 end stream
    624
    625
    626
    627
    628
    629
    630
    631 the 'for' Loop
    632
    633
    634
    635
    636

    Now we get to the good part: the LLVM IR we want to generate for this thing.

    637 With the simple example above, we get this LLVM IR (note that this dump is
    638 generated with optimizations disabled for clarity):
    639

    640
    641
    642
    
                      
                    
    643 declare double @putchard(double)
    644
    645 define double @printstar(double %n) {
    646 entry:
    647 ; initial value = 1.0 (inlined into phi)
    648 br label %loop
    649
    650 loop: ; preds = %loop, %entry
    651 %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
    652 ; body
    653 %calltmp = call double @putchard( double 4.200000e+01 )
    654 ; increment
    655 %nextvar = add double %i, 1.000000e+00
    656
    657 ; termination test
    658 %cmptmp = fcmp ult double %i, %n
    659 %booltmp = uitofp i1 %cmptmp to double
    660 %loopcond = fcmp one double %booltmp, 0.000000e+00
    661 br i1 %loopcond, label %loop, label %afterloop
    662
    663 afterloop: ; preds = %loop
    664 ; loop always returns 0.0
    665 ret double 0.000000e+00
    666 }
    667
    668
    669
    670

    This loop contains all the same constructs we saw before: a phi node, several

    671 expressions, and some basic blocks. Lets see how this fits together.

    672
    673
    674
    675
    676
    677 the 'for' Loop
    678
    679
    680
    681
    682

    The first part of Codegen is very simple: we just output the start expression

    683 for the loop value:

    684
    685
    686
    
                      
                    
    687 let rec codegen_expr = function
    688 ...
    689 | Ast.For (var_name, start, end_, step, body) ->
    690 (* Emit the start code first, without 'variable' in scope. *)
    691 let start_val = codegen_expr start in
    692
    693
    694
    695

    With this out of the way, the next step is to set up the LLVM basic block

    696 for the start of the loop body. In the case above, the whole loop body is one
    697 block, but remember that the body code itself could consist of multiple blocks
    698 (e.g. if it contains an if/then/else or a for/in expression).

    699
    700
    701
    
                      
                    
    702 (* Make the new basic block for the loop header, inserting after current
    703 * block. *)
    704 let preheader_bb = insertion_block builder in
    705 let the_function = block_parent preheader_bb in
    706 let loop_bb = append_block "loop" the_function in
    707
    708 (* Insert an explicit fall through from the current block to the
    709 * loop_bb. *)
    710 ignore (build_br loop_bb builder);
    711
    712
    713
    714

    This code is similar to what we saw for if/then/else. Because we will need

    715 it to create the Phi node, we remember the block that falls through into the
    716 loop. Once we have that, we create the actual block that starts the loop and
    717 create an unconditional branch for the fall-through between the two blocks.

    718
    719
    720
    
                      
                    
    721 (* Start insertion in loop_bb. *)
    722 position_at_end loop_bb builder;
    723
    724 (* Start the PHI node with an entry for start. *)
    725 let variable = build_phi [(start_val, preheader_bb)] var_name builder in
    726
    727
    728
    729

    Now that the "preheader" for the loop is set up, we switch to emitting code

    730 for the loop body. To begin with, we move the insertion point and create the
    731 PHI node for the loop induction variable. Since we already know the incoming
    732 value for the starting value, we add it to the Phi node. Note that the Phi will
    733 eventually get a second value for the backedge, but we can't set it up yet
    734 (because it doesn't exist!).

    735
    736
    737
    
                      
                    
    738 (* Within the loop, the variable is defined equal to the PHI node. If it
    739 * shadows an existing variable, we have to restore it, so save it
    740 * now. *)
    741 let old_val =
    742 try Some (Hashtbl.find named_values var_name) with Not_found -> None
    743 in
    744 Hashtbl.add named_values var_name variable;
    745
    746 (* Emit the body of the loop. This, like any other expr, can change the
    747 * current BB. Note that we ignore the value computed by the body, but
    748 * don't allow an error *)
    749 ignore (codegen_expr body);
    750
    751
    752
    753

    Now the code starts to get more interesting. Our 'for' loop introduces a new

    754 variable to the symbol table. This means that our symbol table can now contain
    755 either function arguments or loop variables. To handle this, before we codegen
    756 the body of the loop, we add the loop variable as the current value for its
    757 name. Note that it is possible that there is a variable of the same name in the
    758 outer scope. It would be easy to make this an error (emit an error and return
    759 null if there is already an entry for VarName) but we choose to allow shadowing
    760 of variables. In order to handle this correctly, we remember the Value that
    761 we are potentially shadowing in old_val (which will be None if there is
    762 no shadowed variable).

    763
    764

    Once the loop variable is set into the symbol table, the code recursively

    765 codegen's the body. This allows the body to use the loop variable: any
    766 references to it will naturally find it in the symbol table.

    767
    768
    769
    
                      
                    
    770 (* Emit the step value. *)
    771 let step_val =
    772 match step with
    773 | Some step -> codegen_expr step
    774 (* If not specified, use 1.0. *)
    775 | None -> const_float double_type 1.0
    776 in
    777
    778 let next_var = build_add variable step_val "nextvar" builder in
    779
    780
    781
    782

    Now that the body is emitted, we compute the next value of the iteration

    783 variable by adding the step value, or 1.0 if it isn't present.
    784 'next_var' will be the value of the loop variable on the next iteration
    785 of the loop.

    786
    787
    788
    
                      
                    
    789 (* Compute the end condition. *)
    790 let end_cond = codegen_expr end_ in
    791
    792 (* Convert condition to a bool by comparing equal to 0.0. *)
    793 let zero = const_float double_type 0.0 in
    794 let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
    795
    796
    797
    798

    Finally, we evaluate the exit value of the loop, to determine whether the

    799 loop should exit. This mirrors the condition evaluation for the if/then/else
    800 statement.

    801
    802
    803
    
                      
                    
    804 (* Create the "after loop" block and insert it. *)
    805 let loop_end_bb = insertion_block builder in
    806 let after_bb = append_block "afterloop" the_function in
    807
    808 (* Insert the conditional branch into the end of loop_end_bb. *)
    809 ignore (build_cond_br end_cond loop_bb after_bb builder);
    810
    811 (* Any new code will be inserted in after_bb. *)
    812 position_at_end after_bb builder;
    813
    814
    815
    816

    With the code for the body of the loop complete, we just need to finish up

    817 the control flow for it. This code remembers the end block (for the phi node), then creates the block for the loop exit ("afterloop"). Based on the value of the
    818 exit condition, it creates a conditional branch that chooses between executing
    819 the loop again and exiting the loop. Any future code is emitted in the
    820 "afterloop" block, so it sets the insertion position to it.

    821
    822
    823
    
                      
                    
    824 (* Add a new entry to the PHI node for the backedge. *)
    825 add_incoming (next_var, loop_end_bb) variable;
    826
    827 (* Restore the unshadowed variable. *)
    828 begin match old_val with
    829 | Some old_val -> Hashtbl.add named_values var_name old_val
    830 | None -> ()
    831 end;
    832
    833 (* for expr always returns 0.0. *)
    834 const_null double_type
    835
    836
    837
    838

    The final code handles various cleanups: now that we have the

    839 "next_var" value, we can add the incoming value to the loop PHI node.
    840 After that, we remove the loop variable from the symbol table, so that it isn't
    841 in scope after the for loop. Finally, code generation of the for loop always
    842 returns 0.0, so that is what we return from Codegen.codegen_expr.

    843
    844

    With this, we conclude the "adding control flow to Kaleidoscope" chapter of

    845 the tutorial. In this chapter we added two control flow constructs, and used
    846 them to motivate a couple of aspects of the LLVM IR that are important for
    847 front-end implementors to know. In the next chapter of our saga, we will get
    848 a bit crazier and add user-defined operators
    849 to our poor innocent language.

    850
    851
    852
    853
    854
    855
    856
    857
    858
    859

    860 Here is the complete code listing for our running example, enhanced with the
    861 if/then/else and for expressions.. To build this example, use:
    862

    863
    864
    865
    
                      
                    
    866 # Compile
    867 ocamlbuild toy.byte
    868 # Run
    869 ./toy.byte
    870
    871
    872
    873

    Here is the code:

    874
    875
    876
    _tags:
    877
    878
    
                      
                    
    879 <{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
    880 <*.{byte,native}>: g++, use_llvm, use_llvm_analysis
    881 <*.{byte,native}>: use_llvm_executionengine, use_llvm_target
    882 <*.{byte,native}>: use_llvm_scalar_opts, use_bindings
    883
    884
    885
    886
    myocamlbuild.ml:
    887
    888
    
                      
                    
    889 open Ocamlbuild_plugin;;
    890
    891 ocaml_lib ~extern:true "llvm";;
    892 ocaml_lib ~extern:true "llvm_analysis";;
    893 ocaml_lib ~extern:true "llvm_executionengine";;
    894 ocaml_lib ~extern:true "llvm_target";;
    895 ocaml_lib ~extern:true "llvm_scalar_opts";;
    896
    897 flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
    898 dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
    899
    900
    901
    902
    token.ml:
    903
    904
    
                      
                    
    905 (*===----------------------------------------------------------------------===
    906 * Lexer Tokens
    907 *===----------------------------------------------------------------------===*)
    908
    909 (* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
    910 * these others for known things. *)
    911 type token =
    912 (* commands *)
    913 | Def | Extern
    914
    915 (* primary *)
    916 | Ident of string | Number of float
    917
    918 (* unknown *)
    919 | Kwd of char
    920
    921 (* control *)
    922 | If | Then | Else
    923 | For | In
    924
    925
    926
    927
    lexer.ml:
    928
    929
    
                      
                    
    930 (*===----------------------------------------------------------------------===
    931 * Lexer
    932 *===----------------------------------------------------------------------===*)
    933
    934 let rec lex = parser
    935 (* Skip any whitespace. *)
    936 | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
    937
    938 (* identifier: [a-zA-Z][a-zA-Z0-9] *)
    939 | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
    940 let buffer = Buffer.create 1 in
    941 Buffer.add_char buffer c;
    942 lex_ident buffer stream
    943
    944 (* number: [0-9.]+ *)
    945 | [< ' ('0' .. '9' as c); stream >] ->
    946 let buffer = Buffer.create 1 in
    947 Buffer.add_char buffer c;
    948 lex_number buffer stream
    949
    950 (* Comment until end of line. *)
    951 | [< ' ('#'); stream >] ->
    952 lex_comment stream
    953
    954 (* Otherwise, just return the character as its ascii value. *)
    955 | [< 'c; stream >] ->
    956 [< 'Token.Kwd c; lex stream >]
    957
    958 (* end of stream. *)
    959 | [< >] -> [< >]
    960
    961 and lex_number buffer = parser
    962 | [< ' ('0' .. '9' | '.' as c); stream >] ->
    963 Buffer.add_char buffer c;
    964 lex_number buffer stream
    965 | [< stream=lex >] ->
    966 [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
    967
    968 and lex_ident buffer = parser
    969 | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
    970 Buffer.add_char buffer c;
    971 lex_ident buffer stream
    972 | [< stream=lex >] ->
    973 match Buffer.contents buffer with
    974 | "def" -> [< 'Token.Def; stream >]
    975 | "extern" -> [< 'Token.Extern; stream >]
    976 | "if" -> [< 'Token.If; stream >]
    977 | "then" -> [< 'Token.Then; stream >]
    978 | "else" -> [< 'Token.Else; stream >]
    979 | "for" -> [< 'Token.For; stream >]
    980 | "in" -> [< 'Token.In; stream >]
    981 | id -> [< 'Token.Ident id; stream >]
    982
    983 and lex_comment = parser
    984 | [< ' ('\n'); stream=lex >] -> stream
    985 | [< 'c; e=lex_comment >] -> e
    986 | [< >] -> [< >]
    987
    988
    989
    990
    ast.ml:
    991
    992
    
                      
                    
    993 (*===----------------------------------------------------------------------===
    994 * Abstract Syntax Tree (aka Parse Tree)
    995 *===----------------------------------------------------------------------===*)
    996
    997 (* expr - Base type for all expression nodes. *)
    998 type expr =
    999 (* variant for numeric literals like "1.0". *)
    1000 | Number of float
    1001
    1002 (* variant for referencing a variable, like "a". *)
    1003 | Variable of string
    1004
    1005 (* variant for a binary operator. *)
    1006 | Binary of char * expr * expr
    1007
    1008 (* variant for function calls. *)
    1009 | Call of string * expr array
    1010
    1011 (* variant for if/then/else. *)
    1012 | If of expr * expr * expr
    1013
    1014 (* variant for for/in. *)
    1015 | For of string * expr * expr * expr option * expr
    1016
    1017 (* proto - This type represents the "prototype" for a function, which captures
    1018 * its name, and its argument names (thus implicitly the number of arguments the
    1019 * function takes). *)
    1020 type proto = Prototype of string * string array
    1021
    1022 (* func - This type represents a function definition itself. *)
    1023 type func = Function of proto * expr
    1024
    1025
    1026
    1027
    parser.ml:
    1028
    1029
    
                      
                    
    1030 (*===---------------------------------------------------------------------===
    1031 * Parser
    1032 *===---------------------------------------------------------------------===*)
    1033
    1034 (* binop_precedence - This holds the precedence for each binary operator that is
    1035 * defined *)
    1036 let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
    1037
    1038 (* precedence - Get the precedence of the pending binary operator token. *)
    1039 let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
    1040
    1041 (* primary
    1042 * ::= identifier
    1043 * ::= numberexpr
    1044 * ::= parenexpr
    1045 * ::= ifexpr
    1046 * ::= forexpr *)
    1047 let rec parse_primary = parser
    1048 (* numberexpr ::= number *)
    1049 | [< 'Token.Number n >] -> Ast.Number n
    1050
    1051 (* parenexpr ::= '(' expression ')' *)
    1052 | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
    1053
    1054 (* identifierexpr
    1055 * ::= identifier
    1056 * ::= identifier '(' argumentexpr ')' *)
    1057 | [< 'Token.Ident id; stream >] ->
    1058 let rec parse_args accumulator = parser
    1059 | [< e=parse_expr; stream >] ->
    1060 begin parser
    1061 | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
    1062 | [< >] -> e :: accumulator
    1063 end stream
    1064 | [< >] -> accumulator
    1065 in
    1066 let rec parse_ident id = parser
    1067 (* Call. *)
    1068 | [< 'Token.Kwd '(';
    1069 args=parse_args [];
    1070 'Token.Kwd ')' ?? "expected ')'">] ->
    1071 Ast.Call (id, Array.of_list (List.rev args))
    1072
    1073 (* Simple variable ref. *)
    1074 | [< >] -> Ast.Variable id
    1075 in
    1076 parse_ident id stream
    1077
    1078 (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
    1079 | [< 'Token.If; c=parse_expr;
    1080 'Token.Then ?? "expected 'then'"; t=parse_expr;
    1081 'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
    1082 Ast.If (c, t, e)
    1083
    1084 (* forexpr
    1085 ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
    1086 | [< 'Token.For;
    1087 'Token.Ident id ?? "expected identifier after for";
    1088 'Token.Kwd '=' ?? "expected '=' after for";
    1089 stream >] ->
    1090 begin parser
    1091 | [<
    1092 start=parse_expr;
    1093 'Token.Kwd ',' ?? "expected ',' after for";
    1094 end_=parse_expr;
    1095 stream >] ->
    1096 let step =
    1097 begin parser
    1098 | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
    1099 | [< >] -> None
    1100 end stream
    1101 in
    1102 begin parser
    1103 | [< 'Token.In; body=parse_expr >] ->
    1104 Ast.For (id, start, end_, step, body)
    1105 | [< >] ->
    1106 raise (Stream.Error "expected 'in' after for")
    1107 end stream
    1108 | [< >] ->
    1109 raise (Stream.Error "expected '=' after for")
    1110 end stream
    1111
    1112 | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
    1113
    1114 (* binoprhs
    1115 * ::= ('+' primary)* *)
    1116 and parse_bin_rhs expr_prec lhs stream =
    1117 match Stream.peek stream with
    1118 (* If this is a binop, find its precedence. *)
    1119 | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
    1120 let token_prec = precedence c in
    1121
    1122 (* If this is a binop that binds at least as tightly as the current binop,
    1123 * consume it, otherwise we are done. *)
    1124 if token_prec < expr_prec then lhs else begin
    1125 (* Eat the binop. *)
    1126 Stream.junk stream;
    1127
    1128 (* Parse the primary expression after the binary operator. *)
    1129 let rhs = parse_primary stream in
    1130
    1131 (* Okay, we know this is a binop. *)
    1132 let rhs =
    1133 match Stream.peek stream with
    1134 | Some (Token.Kwd c2) ->
    1135 (* If BinOp binds less tightly with rhs than the operator after
    1136 * rhs, let the pending operator take rhs as its lhs. *)
    1137 let next_prec = precedence c2 in
    1138 if token_prec < next_prec
    1139 then parse_bin_rhs (token_prec + 1) rhs stream
    1140 else rhs
    1141 | _ -> rhs
    1142 in
    1143
    1144 (* Merge lhs/rhs. *)
    1145 let lhs = Ast.Binary (c, lhs, rhs) in
    1146 parse_bin_rhs expr_prec lhs stream
    1147 end
    1148 | _ -> lhs
    1149
    1150 (* expression
    1151 * ::= primary binoprhs *)
    1152 and parse_expr = parser
    1153 | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
    1154
    1155 (* prototype
    1156 * ::= id '(' id* ')' *)
    1157 let parse_prototype =
    1158 let rec parse_args accumulator = parser
    1159 | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
    1160 | [< >] -> accumulator
    1161 in
    1162
    1163 parser
    1164 | [< 'Token.Ident id;
    1165 'Token.Kwd '(' ?? "expected '(' in prototype";
    1166 args=parse_args [];
    1167 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    1168 (* success. *)
    1169 Ast.Prototype (id, Array.of_list (List.rev args))
    1170
    1171 | [< >] ->
    1172 raise (Stream.Error "expected function name in prototype")
    1173
    1174 (* definition ::= 'def' prototype expression *)
    1175 let parse_definition = parser
    1176 | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
    1177 Ast.Function (p, e)
    1178
    1179 (* toplevelexpr ::= expression *)
    1180 let parse_toplevel = parser
    1181 | [< e=parse_expr >] ->
    1182 (* Make an anonymous proto. *)
    1183 Ast.Function (Ast.Prototype ("", [||]), e)
    1184
    1185 (* external ::= 'extern' prototype *)
    1186 let parse_extern = parser
    1187 | [< 'Token.Extern; e=parse_prototype >] -> e
    1188
    1189
    1190
    1191
    codegen.ml:
    1192
    1193
    
                      
                    
    1194 (*===----------------------------------------------------------------------===
    1195 * Code Generation
    1196 *===----------------------------------------------------------------------===*)
    1197
    1198 open Llvm
    1199
    1200 exception Error of string
    1201
    1202 let the_module = create_module "my cool jit"
    1203 let builder = builder ()
    1204 let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
    1205
    1206 let rec codegen_expr = function
    1207 | Ast.Number n -> const_float double_type n
    1208 | Ast.Variable name ->
    1209 (try Hashtbl.find named_values name with
    1210 | Not_found -> raise (Error "unknown variable name"))
    1211 | Ast.Binary (op, lhs, rhs) ->
    1212 let lhs_val = codegen_expr lhs in
    1213 let rhs_val = codegen_expr rhs in
    1214 begin
    1215 match op with
    1216 | '+' -> build_add lhs_val rhs_val "addtmp" builder
    1217 | '-' -> build_sub lhs_val rhs_val "subtmp" builder
    1218 | '*' -> build_mul lhs_val rhs_val "multmp" builder
    1219 | '<' ->
    1220 (* Convert bool 0/1 to double 0.0 or 1.0 *)
    1221 let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
    1222 build_uitofp i double_type "booltmp" builder
    1223 | _ -> raise (Error "invalid binary operator")
    1224 end
    1225 | Ast.Call (callee, args) ->
    1226 (* Look up the name in the module table. *)
    1227 let callee =
    1228 match lookup_function callee the_module with
    1229 | Some callee -> callee
    1230 | None -> raise (Error "unknown function referenced")
    1231 in
    1232 let params = params callee in
    1233
    1234 (* If argument mismatch error. *)
    1235 if Array.length params == Array.length args then () else
    1236 raise (Error "incorrect # arguments passed");
    1237 let args = Array.map codegen_expr args in
    1238 build_call callee args "calltmp" builder
    1239 | Ast.If (cond, then_, else_) ->
    1240 let cond = codegen_expr cond in
    1241
    1242 (* Convert condition to a bool by comparing equal to 0.0 *)
    1243 let zero = const_float double_type 0.0 in
    1244 let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
    1245
    1246 (* Grab the first block so that we might later add the conditional branch
    1247 * to it at the end of the function. *)
    1248 let start_bb = insertion_block builder in
    1249 let the_function = block_parent start_bb in
    1250
    1251 let then_bb = append_block "then" the_function in
    1252
    1253 (* Emit 'then' value. *)
    1254 position_at_end then_bb builder;
    1255 let then_val = codegen_expr then_ in
    1256
    1257 (* Codegen of 'then' can change the current block, update then_bb for the
    1258 * phi. We create a new name because one is used for the phi node, and the
    1259 * other is used for the conditional branch. *)
    1260 let new_then_bb = insertion_block builder in
    1261
    1262 (* Emit 'else' value. *)
    1263 let else_bb = append_block "else" the_function in
    1264 position_at_end else_bb builder;
    1265 let else_val = codegen_expr else_ in
    1266
    1267 (* Codegen of 'else' can change the current block, update else_bb for the
    1268 * phi. *)
    1269 let new_else_bb = insertion_block builder in
    1270
    1271 (* Emit merge block. *)
    1272 let merge_bb = append_block "ifcont" the_function in
    1273 position_at_end merge_bb builder;
    1274 let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
    1275 let phi = build_phi incoming "iftmp" builder in
    1276
    1277 (* Return to the start block to add the conditional branch. *)
    1278 position_at_end start_bb builder;
    1279 ignore (build_cond_br cond_val then_bb else_bb builder);
    1280
    1281 (* Set a unconditional branch at the end of the 'then' block and the
    1282 * 'else' block to the 'merge' block. *)
    1283 position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
    1284 position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
    1285
    1286 (* Finally, set the builder to the end of the merge block. *)
    1287 position_at_end merge_bb builder;
    1288
    1289 phi
    1290 | Ast.For (var_name, start, end_, step, body) ->
    1291 (* Emit the start code first, without 'variable' in scope. *)
    1292 let start_val = codegen_expr start in
    1293
    1294 (* Make the new basic block for the loop header, inserting after current
    1295 * block. *)
    1296 let preheader_bb = insertion_block builder in
    1297 let the_function = block_parent preheader_bb in
    1298 let loop_bb = append_block "loop" the_function in
    1299
    1300 (* Insert an explicit fall through from the current block to the
    1301 * loop_bb. *)
    1302 ignore (build_br loop_bb builder);
    1303
    1304 (* Start insertion in loop_bb. *)
    1305 position_at_end loop_bb builder;
    1306
    1307 (* Start the PHI node with an entry for start. *)
    1308 let variable = build_phi [(start_val, preheader_bb)] var_name builder in
    1309
    1310 (* Within the loop, the variable is defined equal to the PHI node. If it
    1311 * shadows an existing variable, we have to restore it, so save it
    1312 * now. *)
    1313 let old_val =
    1314 try Some (Hashtbl.find named_values var_name) with Not_found -> None
    1315 in
    1316 Hashtbl.add named_values var_name variable;
    1317
    1318 (* Emit the body of the loop. This, like any other expr, can change the
    1319 * current BB. Note that we ignore the value computed by the body, but
    1320 * don't allow an error *)
    1321 ignore (codegen_expr body);
    1322
    1323 (* Emit the step value. *)
    1324 let step_val =
    1325 match step with
    1326 | Some step -> codegen_expr step
    1327 (* If not specified, use 1.0. *)
    1328 | None -> const_float double_type 1.0
    1329 in
    1330
    1331 let next_var = build_add variable step_val "nextvar" builder in
    1332
    1333 (* Compute the end condition. *)
    1334 let end_cond = codegen_expr end_ in
    1335
    1336 (* Convert condition to a bool by comparing equal to 0.0. *)
    1337 let zero = const_float double_type 0.0 in
    1338 let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
    1339
    1340 (* Create the "after loop" block and insert it. *)
    1341 let loop_end_bb = insertion_block builder in
    1342 let after_bb = append_block "afterloop" the_function in
    1343
    1344 (* Insert the conditional branch into the end of loop_end_bb. *)
    1345 ignore (build_cond_br end_cond loop_bb after_bb builder);
    1346
    1347 (* Any new code will be inserted in after_bb. *)
    1348 position_at_end after_bb builder;
    1349
    1350 (* Add a new entry to the PHI node for the backedge. *)
    1351 add_incoming (next_var, loop_end_bb) variable;
    1352
    1353 (* Restore the unshadowed variable. *)
    1354 begin match old_val with
    1355 | Some old_val -> Hashtbl.add named_values var_name old_val
    1356 | None -> ()
    1357 end;
    1358
    1359 (* for expr always returns 0.0. *)
    1360 const_null double_type
    1361
    1362 let codegen_proto = function
    1363 | Ast.Prototype (name, args) ->
    1364 (* Make the function type: double(double,double) etc. *)
    1365 let doubles = Array.make (Array.length args) double_type in
    1366 let ft = function_type double_type doubles in
    1367 let f =
    1368 match lookup_function name the_module with
    1369 | None -> declare_function name ft the_module
    1370
    1371 (* If 'f' conflicted, there was already something named 'name'. If it
    1372 * has a body, don't allow redefinition or reextern. *)
    1373 | Some f ->
    1374 (* If 'f' already has a body, reject this. *)
    1375 if block_begin f <> At_end f then
    1376 raise (Error "redefinition of function");
    1377
    1378 (* If 'f' took a different number of arguments, reject. *)
    1379 if element_type (type_of f) <> ft then
    1380 raise (Error "redefinition of function with different # args");
    1381 f
    1382 in
    1383
    1384 (* Set names for all arguments. *)
    1385 Array.iteri (fun i a ->
    1386 let n = args.(i) in
    1387 set_value_name n a;
    1388 Hashtbl.add named_values n a;
    1389 ) (params f);
    1390 f
    1391
    1392 let codegen_func the_fpm = function
    1393 | Ast.Function (proto, body) ->
    1394 Hashtbl.clear named_values;
    1395 let the_function = codegen_proto proto in
    1396
    1397 (* Create a new basic block to start insertion into. *)
    1398 let bb = append_block "entry" the_function in
    1399 position_at_end bb builder;
    1400
    1401 try
    1402 let ret_val = codegen_expr body in
    1403
    1404 (* Finish off the function. *)
    1405 let _ = build_ret ret_val builder in
    1406
    1407 (* Validate the generated code, checking for consistency. *)
    1408 Llvm_analysis.assert_valid_function the_function;
    1409
    1410 (* Optimize the function. *)
    1411 let _ = PassManager.run_function the_function the_fpm in
    1412
    1413 the_function
    1414 with e ->
    1415 delete_function the_function;
    1416 raise e
    1417
    1418
    1419
    1420
    toplevel.ml:
    1421
    1422
    
                      
                    
    1423 (*===----------------------------------------------------------------------===
    1424 * Top-Level parsing and JIT Driver
    1425 *===----------------------------------------------------------------------===*)
    1426
    1427 open Llvm
    1428 open Llvm_executionengine
    1429
    1430 (* top ::= definition | external | expression | ';' *)
    1431 let rec main_loop the_fpm the_execution_engine stream =
    1432 match Stream.peek stream with
    1433 | None -> ()
    1434
    1435 (* ignore top-level semicolons. *)
    1436 | Some (Token.Kwd ';') ->
    1437 Stream.junk stream;
    1438 main_loop the_fpm the_execution_engine stream
    1439
    1440 | Some token ->
    1441 begin
    1442 try match token with
    1443 | Token.Def ->
    1444 let e = Parser.parse_definition stream in
    1445 print_endline "parsed a function definition.";
    1446 dump_value (Codegen.codegen_func the_fpm e);
    1447 | Token.Extern ->
    1448 let e = Parser.parse_extern stream in
    1449 print_endline "parsed an extern.";
    1450 dump_value (Codegen.codegen_proto e);
    1451 | _ ->
    1452 (* Evaluate a top-level expression into an anonymous function. *)
    1453 let e = Parser.parse_toplevel stream in
    1454 print_endline "parsed a top-level expr";
    1455 let the_function = Codegen.codegen_func the_fpm e in
    1456 dump_value the_function;
    1457
    1458 (* JIT the function, returning a function pointer. *)
    1459 let result = ExecutionEngine.run_function the_function [||]
    1460 the_execution_engine in
    1461
    1462 print_string "Evaluated to ";
    1463 print_float (GenericValue.as_float double_type result);
    1464 print_newline ();
    1465 with Stream.Error s | Codegen.Error s ->
    1466 (* Skip token for error recovery. *)
    1467 Stream.junk stream;
    1468 print_endline s;
    1469 end;
    1470 print_string "ready> "; flush stdout;
    1471 main_loop the_fpm the_execution_engine stream
    1472
    1473
    1474
    1475
    toy.ml:
    1476
    1477
    
                      
                    
    1478 (*===----------------------------------------------------------------------===
    1479 * Main driver code.
    1480 *===----------------------------------------------------------------------===*)
    1481
    1482 open Llvm
    1483 open Llvm_executionengine
    1484 open Llvm_target
    1485 open Llvm_scalar_opts
    1486
    1487 let main () =
    1488 (* Install standard binary operators.
    1489 * 1 is the lowest precedence. *)
    1490 Hashtbl.add Parser.binop_precedence '<' 10;
    1491 Hashtbl.add Parser.binop_precedence '+' 20;
    1492 Hashtbl.add Parser.binop_precedence '-' 20;
    1493 Hashtbl.add Parser.binop_precedence '*' 40; (* highest. *)
    1494
    1495 (* Prime the first token. *)
    1496 print_string "ready> "; flush stdout;
    1497 let stream = Lexer.lex (Stream.of_channel stdin) in
    1498
    1499 (* Create the JIT. *)
    1500 let the_module_provider = ModuleProvider.create Codegen.the_module in
    1501 let the_execution_engine = ExecutionEngine.create the_module_provider in
    1502 let the_fpm = PassManager.create_function the_module_provider in
    1503
    1504 (* Set up the optimizer pipeline. Start with registering info about how the
    1505 * target lays out data structures. *)
    1506 TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
    1507
    1508 (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
    1509 add_instruction_combining the_fpm;
    1510
    1511 (* reassociate expressions. *)
    1512 add_reassociation the_fpm;
    1513
    1514 (* Eliminate Common SubExpressions. *)
    1515 add_gvn the_fpm;
    1516
    1517 (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
    1518 add_cfg_simplification the_fpm;
    1519
    1520 (* Run the main "interpreter loop" now. *)
    1521 Toplevel.main_loop the_fpm the_execution_engine stream;
    1522
    1523 (* Print out all the generated code. *)
    1524 dump_module Codegen.the_module
    1525 ;;
    1526
    1527 main ()
    1528
    1529
    1530
    1531
    bindings.c
    1532
    1533
    
                      
                    
    1534 #include <stdio.h>
    1535
    1536 /* putchard - putchar that takes a double and returns 0. */
    1537 extern double putchard(double X) {
    1538 putchar((char)X);
    1539 return 0;
    1540 }
    1541
    1542
    1543
    1544
    1545 Next: Extending the language: user-defined
    1546 operators
    1547
    1548
    1549
    1550
    1551
    1552
    1553 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!">
    1554
    1555 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!">
    1556
    1557 Chris Lattner
    1558 Erick Tryzelaar
    1559 The LLVM Compiler Infrastructure
    1560 Last modified: $Date: 2007-10-17 11:05:13 -0700 (Wed, 17 Oct 2007) $
    1561
    1562
    1563
    0
    1 "http://www.w3.org/TR/html4/strict.dtd">
    2
    3
    4
    5 Kaleidoscope: Extending the Language: User-defined Operators
    6
    7
    8
    9
    10
    11
    12
    13
    14
    Kaleidoscope: Extending the Language: User-defined Operators
    15
    16
    17
  • Up to Tutorial Index
  • 18
  • Chapter 6
  • 19
    20
  • Chapter 6 Introduction
  • 21
  • User-defined Operators: the Idea
  • 22
  • User-defined Binary Operators
  • 23
  • User-defined Unary Operators
  • 24
  • Kicking the Tires
  • 25
  • Full Code Listing
  • 26
    27
    28
  • Chapter 7: Extending the Language: Mutable
  • 29 Variables / SSA Construction
    30
    31
    32
    33

    34 Written by Chris Lattner
    35 and Erick Tryzelaar
    36

    37
    38
    39
    40
    41
    42
    43
    44
    45

    Welcome to Chapter 6 of the "Implementing a language

    46 with LLVM" tutorial. At this point in our tutorial, we now have a fully
    47 functional language that is fairly minimal, but also useful. There
    48 is still one big problem with it, however. Our language doesn't have many
    49 useful operators (like division, logical negation, or even any comparisons
    50 besides less-than).

    51
    52

    This chapter of the tutorial takes a wild digression into adding user-defined

    53 operators to the simple and beautiful Kaleidoscope language. This digression now
    54 gives us a simple and ugly language in some ways, but also a powerful one at the
    55 same time. One of the great things about creating your own language is that you
    56 get to decide what is good or bad. In this tutorial we'll assume that it is
    57 okay to use this as a way to show some interesting parsing techniques.

    58
    59

    At the end of this tutorial, we'll run through an example Kaleidoscope

    60 application that renders the Mandelbrot set. This gives
    61 an example of what you can build with Kaleidoscope and its feature set.

    62
    63
    64
    65
    66
    67
    68
    69
    70
    71

    72 The "operator overloading" that we will add to Kaleidoscope is more general than
    73 languages like C++. In C++, you are only allowed to redefine existing
    74 operators: you can't programatically change the grammar, introduce new
    75 operators, change precedence levels, etc. In this chapter, we will add this
    76 capability to Kaleidoscope, which will let the user round out the set of
    77 operators that are supported.

    78
    79

    The point of going into user-defined operators in a tutorial like this is to

    80 show the power and flexibility of using a hand-written parser. Thus far, the parser
    81 we have been implementing uses recursive descent for most parts of the grammar and
    82 operator precedence parsing for the expressions. See
    83 href="OCamlLangImpl2.html">Chapter 2 for details. Without using operator
    84 precedence parsing, it would be very difficult to allow the programmer to
    85 introduce new operators into the grammar: the grammar is dynamically extensible
    86 as the JIT runs.

    87
    88

    The two specific features we'll add are programmable unary operators (right

    89 now, Kaleidoscope has no unary operators at all) as well as binary operators.
    90 An example of this is:

    91
    92
    93
    
                      
                    
    94 # Logical unary not.
    95 def unary!(v)
    96 if v then
    97 0
    98 else
    99 1;
    100
    101 # Define > with the same precedence as <.
    102 def binary> 10 (LHS RHS)
    103 RHS < LHS;
    104
    105 # Binary "logical or", (note that it does not "short circuit")
    106 def binary| 5 (LHS RHS)
    107 if LHS then
    108 1
    109 else if RHS then
    110 1
    111 else
    112 0;
    113
    114 # Define = with slightly lower precedence than relationals.
    115 def binary= 9 (LHS RHS)
    116 !(LHS < RHS | LHS > RHS);
    117
    118
    119
    120

    Many languages aspire to being able to implement their standard runtime

    121 library in the language itself. In Kaleidoscope, we can implement significant
    122 parts of the language in the library!

    123
    124

    We will break down implementation of these features into two parts:

    125 implementing support for user-defined binary operators and adding unary
    126 operators.

    127
    128
    129
    130
    131
    132
    133
    134
    135
    136

    Adding support for user-defined binary operators is pretty simple with our

    137 current framework. We'll first add support for the unary/binary keywords:

    138
    139
    140
    
                      
                    
    141 type token =
    142 ...
    143 (* operators *)
    144 | Binary | Unary
    145
    146 ...
    147
    148 and lex_ident buffer = parser
    149 ...
    150 | "for" -> [< 'Token.For; stream >]
    151 | "in" -> [< 'Token.In; stream >]
    152 | "binary" -> [< 'Token.Binary; stream >]
    153 | "unary" -> [< 'Token.Unary; stream >]
    154
    155
    156
    157

    This just adds lexer support for the unary and binary keywords, like we

    158 did in previous chapters. One nice
    159 thing about our current AST, is that we represent binary operators with full
    160 generalisation by using their ASCII code as the opcode. For our extended
    161 operators, we'll use this same representation, so we don't need any new AST or
    162 parser support.

    163
    164

    On the other hand, we have to be able to represent the definitions of these

    165 new operators, in the "def binary| 5" part of the function definition. In our
    166 grammar so far, the "name" for the function definition is parsed as the
    167 "prototype" production and into the Ast.Prototype AST node. To
    168 represent our new user-defined operators as prototypes, we have to extend
    169 the Ast.Prototype AST node like this:

    170
    171
    172
    
                      
                    
    173 (* proto - This type represents the "prototype" for a function, which captures
    174 * its name, and its argument names (thus implicitly the number of arguments the
    175 * function takes). *)
    176 type proto =
    177 | Prototype of string * string array
    178 | BinOpPrototype of string * string array * int
    179
    180
    181
    182

    Basically, in addition to knowing a name for the prototype, we now keep track

    183 of whether it was an operator, and if it was, what precedence level the operator
    184 is at. The precedence is only used for binary operators (as you'll see below,
    185 it just doesn't apply for unary operators). Now that we have a way to represent
    186 the prototype for a user-defined operator, we need to parse it:

    187
    188
    189
    
                      
                    
    190 (* prototype
    191 * ::= id '(' id* ')'
    192 * ::= binary LETTER number? (id, id)
    193 * ::= unary LETTER number? (id) *)
    194 let parse_prototype =
    195 let rec parse_args accumulator = parser
    196 | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
    197 | [< >] -> accumulator
    198 in
    199 let parse_operator = parser
    200 | [< 'Token.Unary >] -> "unary", 1
    201 | [< 'Token.Binary >] -> "binary", 2
    202 in
    203 let parse_binary_precedence = parser
    204 | [< 'Token.Number n >] -> int_of_float n
    205 | [< >] -> 30
    206 in
    207 parser
    208 | [< 'Token.Ident id;
    209 'Token.Kwd '(' ?? "expected '(' in prototype";
    210 args=parse_args [];
    211 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    212 (* success. *)
    213 Ast.Prototype (id, Array.of_list (List.rev args))
    214 | [< (prefix, kind)=parse_operator;
    215 'Token.Kwd op ?? "expected an operator";
    216 (* Read the precedence if present. *)
    217 binary_precedence=parse_binary_precedence;
    218 'Token.Kwd '(' ?? "expected '(' in prototype";
    219 args=parse_args [];
    220 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    221 let name = prefix ^ (String.make 1 op) in
    222 let args = Array.of_list (List.rev args) in
    223
    224 (* Verify right number of arguments for operator. *)
    225 if Array.length args != kind
    226 then raise (Stream.Error "invalid number of operands for operator")
    227 else
    228 if kind == 1 then
    229 Ast.Prototype (name, args)
    230 else
    231 Ast.BinOpPrototype (name, args, binary_precedence)
    232 | [< >] ->
    233 raise (Stream.Error "expected function name in prototype")
    234
    235
    236
    237

    This is all fairly straightforward parsing code, and we have already seen

    238 a lot of similar code in the past. One interesting part about the code above is
    239 the couple lines that set up name for binary operators. This builds
    240 names like "binary@" for a newly defined "@" operator. This then takes
    241 advantage of the fact that symbol names in the LLVM symbol table are allowed to
    242 have any character in them, including embedded nul characters.

    243
    244

    The next interesting thing to add, is codegen support for these binary

    245 operators. Given our current structure, this is a simple addition of a default
    246 case for our existing binary operator node:

    247
    248
    249
    
                      
                    
    250 let codegen_expr = function
    251 ...
    252 | Ast.Binary (op, lhs, rhs) ->
    253 let lhs_val = codegen_expr lhs in
    254 let rhs_val = codegen_expr rhs in
    255 begin
    256 match op with
    257 | '+' -> build_add lhs_val rhs_val "addtmp" builder
    258 | '-' -> build_sub lhs_val rhs_val "subtmp" builder
    259 | '*' -> build_mul lhs_val rhs_val "multmp" builder
    260 | '<' ->
    261 (* Convert bool 0/1 to double 0.0 or 1.0 *)
    262 let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
    263 build_uitofp i double_type "booltmp" builder
    264 | _ ->
    265 (* If it wasn't a builtin binary operator, it must be a user defined
    266 * one. Emit a call to it. *)
    267 let callee = "binary" ^ (String.make 1 op) in
    268 let callee =
    269 match lookup_function callee the_module with
    270 | Some callee -> callee
    271 | None -> raise (Error "binary operator not found!")
    272 in
    273 build_call callee [|lhs_val; rhs_val|] "binop" builder
    274 end
    275
    276
    277
    278

    As you can see above, the new code is actually really simple. It just does

    279 a lookup for the appropriate operator in the symbol table and generates a
    280 function call to it. Since user-defined operators are just built as normal
    281 functions (because the "prototype" boils down to a function with the right
    282 name) everything falls into place.

    283
    284

    The final piece of code we are missing, is a bit of top level magic:

    285
    286
    287
    
                      
                    
    288 let codegen_func the_fpm = function
    289 | Ast.Function (proto, body) ->
    290 Hashtbl.clear named_values;
    291 let the_function = codegen_proto proto in
    292
    293 (* If this is an operator, install it. *)
    294 begin match proto with
    295 | Ast.BinOpPrototype (name, args, prec) ->
    296 let op = name.[String.length name - 1] in
    297 Hashtbl.add Parser.binop_precedence op prec;
    298 | _ -> ()
    299 end;
    300
    301 (* Create a new basic block to start insertion into. *)
    302 let bb = append_block "entry" the_function in
    303 position_at_end bb builder;
    304 ...
    305
    306
    307
    308

    Basically, before codegening a function, if it is a user-defined operator, we

    309 register it in the precedence table. This allows the binary operator parsing
    310 logic we already have in place to handle it. Since we are working on a
    311 fully-general operator precedence parser, this is all we need to do to "extend
    312 the grammar".

    313
    314

    Now we have useful user-defined binary operators. This builds a lot

    315 on the previous framework we built for other operators. Adding unary operators
    316 is a bit more challenging, because we don't have any framework for it yet - lets
    317 see what it takes.

    318
    319
    320
    321
    322
    323
    324
    325
    326
    327

    Since we don't currently support unary operators in the Kaleidoscope

    328 language, we'll need to add everything to support them. Above, we added simple
    329 support for the 'unary' keyword to the lexer. In addition to that, we need an
    330 AST node:

    331
    332
    333
    
                      
                    
    334 type expr =
    335 ...
    336 (* variant for a unary operator. *)
    337 | Unary of char * expr
    338 ...
    339
    340
    341
    342

    This AST node is very simple and obvious by now. It directly mirrors the

    343 binary operator AST node, except that it only has one child. With this, we
    344 need to add the parsing logic. Parsing a unary operator is pretty simple: we'll
    345 add a new function to do it:

    346
    347
    348
    
                      
                    
    349 (* unary
    350 * ::= primary
    351 * ::= '!' unary *)
    352 and parse_unary = parser
    353 (* If this is a unary operator, read it. *)
    354 | [< 'Token.Kwd op when op != '(' && op != ')'; operand=parse_expr >] ->
    355 Ast.Unary (op, operand)
    356
    357 (* If the current token is not an operator, it must be a primary expr. *)
    358 | [< stream >] -> parse_primary stream
    359
    360
    361
    362

    The grammar we add is pretty straightforward here. If we see a unary

    363 operator when parsing a primary operator, we eat the operator as a prefix and
    364 parse the remaining piece as another unary operator. This allows us to handle
    365 multiple unary operators (e.g. "!!x"). Note that unary operators can't have
    366 ambiguous parses like binary operators can, so there is no need for precedence
    367 information.

    368
    369

    The problem with this function, is that we need to call ParseUnary from

    370 somewhere. To do this, we change previous callers of ParsePrimary to call
    371 parse_unary instead:

    372
    373
    374
    
                      
                    
    375 (* binoprhs
    376 * ::= ('+' primary)* *)
    377 and parse_bin_rhs expr_prec lhs stream =
    378 ...
    379 (* Parse the unary expression after the binary operator. *)
    380 let rhs = parse_unary stream in
    381 ...
    382
    383 ...
    384
    385 (* expression
    386 * ::= primary binoprhs *)
    387 and parse_expr = parser
    388 | [< lhs=parse_unary; stream >] -> parse_bin_rhs 0 lhs stream
    389
    390
    391
    392

    With these two simple changes, we are now able to parse unary operators and build the

    393 AST for them. Next up, we need to add parser support for prototypes, to parse
    394 the unary operator prototype. We extend the binary operator code above
    395 with:

    396
    397
    398
    
                      
                    
    399 (* prototype
    400 * ::= id '(' id* ')'
    401 * ::= binary LETTER number? (id, id)
    402 * ::= unary LETTER number? (id) *)
    403 let parse_prototype =
    404 let rec parse_args accumulator = parser
    405 | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
    406 | [< >] -> accumulator
    407 in
    408 let parse_operator = parser
    409 | [< 'Token.Unary >] -> "unary", 1
    410 | [< 'Token.Binary >] -> "binary", 2
    411 in
    412 let parse_binary_precedence = parser
    413 | [< 'Token.Number n >] -> int_of_float n
    414 | [< >] -> 30
    415 in
    416 parser
    417 | [< 'Token.Ident id;
    418 'Token.Kwd '(' ?? "expected '(' in prototype";
    419 args=parse_args [];
    420 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    421 (* success. *)
    422 Ast.Prototype (id, Array.of_list (List.rev args))
    423 | [< (prefix, kind)=parse_operator;
    424 'Token.Kwd op ?? "expected an operator";
    425 (* Read the precedence if present. *)
    426 binary_precedence=parse_binary_precedence;
    427 'Token.Kwd '(' ?? "expected '(' in prototype";
    428 args=parse_args [];
    429 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    430 let name = prefix ^ (String.make 1 op) in
    431 let args = Array.of_list (List.rev args) in
    432
    433 (* Verify right number of arguments for operator. *)
    434 if Array.length args != kind
    435 then raise (Stream.Error "invalid number of operands for operator")
    436 else
    437 if kind == 1 then
    438 Ast.Prototype (name, args)
    439 else
    440 Ast.BinOpPrototype (name, args, binary_precedence)
    441 | [< >] ->
    442 raise (Stream.Error "expected function name in prototype")
    443
    444
    445
    446

    As with binary operators, we name unary operators with a name that includes

    447 the operator character. This assists us at code generation time. Speaking of,
    448 the final piece we need to add is codegen support for unary operators. It looks
    449 like this:

    450
    451
    452
    
                      
                    
    453 let rec codegen_expr = function
    454 ...
    455 | Ast.Unary (op, operand) ->
    456 let operand = codegen_expr operand in
    457 let callee = "unary" ^ (String.make 1 op) in
    458 let callee =
    459 match lookup_function callee the_module with
    460 | Some callee -> callee
    461 | None -> raise (Error "unknown unary operator")
    462 in
    463 build_call callee [|operand|] "unop" builder
    464
    465
    466
    467

    This code is similar to, but simpler than, the code for binary operators. It

    468 is simpler primarily because it doesn't need to handle any predefined operators.
    469

    470
    471
    472
    473
    474
    475
    476
    477
    478
    479

    It is somewhat hard to believe, but with a few simple extensions we've

    480 covered in the last chapters, we have grown a real-ish language. With this, we
    481 can do a lot of interesting things, including I/O, math, and a bunch of other
    482 things. For example, we can now add a nice sequencing operator (printd is
    483 defined to print out the specified value and a newline):

    484
    485
    486
    
                      
                    
    487 ready> extern printd(x);
    488 Read extern: declare double @printd(double)
    489 ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
    490 ..
    491 ready> printd(123) : printd(456) : printd(789);
    492 123.000000
    493 456.000000
    494 789.000000
    495 Evaluated to 0.000000
    496
    497
    498
    499

    We can also define a bunch of other "primitive" operations, such as:

    500
    501
    502
    
                      
                    
    503 # Logical unary not.
    504 def unary!(v)
    505 if v then
    506 0
    507 else
    508 1;
    509
    510 # Unary negate.
    511 def unary-(v)
    512 0-v;
    513
    514 # Define > with the same precedence as >.
    515 def binary> 10 (LHS RHS)
    516 RHS < LHS;
    517
    518 # Binary logical or, which does not short circuit.
    519 def binary| 5 (LHS RHS)
    520 if LHS then
    521 1
    522 else if RHS then
    523 1
    524 else
    525 0;
    526
    527 # Binary logical and, which does not short circuit.
    528 def binary& 6 (LHS RHS)
    529 if !LHS then
    530 0
    531 else
    532 !!RHS;
    533
    534 # Define = with slightly lower precedence than relationals.
    535 def binary = 9 (LHS RHS)
    536 !(LHS < RHS | LHS > RHS);
    537
    538
    539
    540
    541
    542

    Given the previous if/then/else support, we can also define interesting

    543 functions for I/O. For example, the following prints out a character whose
    544 "density" reflects the value passed in: the lower the value, the denser the
    545 character:

    546
    547
    548
    
                      
                    
    549 ready>
    550
    551 extern putchard(char)
    552 def printdensity(d)
    553 if d > 8 then
    554 putchard(32) # ' '
    555 else if d > 4 then
    556 putchard(46) # '.'
    557 else if d > 2 then
    558 putchard(43) # '+'
    559 else
    560 putchard(42); # '*'
    561 ...
    562 ready> printdensity(1): printdensity(2): printdensity(3) :
    563 printdensity(4): printdensity(5): printdensity(9): putchard(10);
    564 *++..
    565 Evaluated to 0.000000
    566
    567
    568
    569

    Based on these simple primitive operations, we can start to define more

    570 interesting things. For example, here's a little function that solves for the
    571 number of iterations it takes a function in the complex plane to
    572 converge:

    573
    574
    575
    
                      
                    
    576 # determine whether the specific location diverges.
    577 # Solve for z = z^2 + c in the complex plane.
    578 def mandleconverger(real imag iters creal cimag)
    579 if iters > 255 | (real*real + imag*imag > 4) then
    580 iters
    581 else
    582 mandleconverger(real*real - imag*imag + creal,
    583 2*real*imag + cimag,
    584 iters+1, creal, cimag);
    585
    586 # return the number of iterations required for the iteration to escape
    587 def mandleconverge(real imag)
    588 mandleconverger(real, imag, 0, real, imag);
    589
    590
    591
    592

    This "z = z2 + c" function is a beautiful little creature that is the basis

    593 for computation of the
    594 href="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot Set. Our
    595 mandelconverge function returns the number of iterations that it takes
    596 for a complex orbit to escape, saturating to 255. This is not a very useful
    597 function by itself, but if you plot its value over a two-dimensional plane,
    598 you can see the Mandelbrot set. Given that we are limited to using putchard
    599 here, our amazing graphical output is limited, but we can whip together
    600 something using the density plotter above:

    601
    602
    603
    
                      
                    
    604 # compute and plot the mandlebrot set with the specified 2 dimensional range
    605 # info.
    606 def mandelhelp(xmin xmax xstep ymin ymax ystep)
    607 for y = ymin, y < ymax, ystep in (
    608 (for x = xmin, x < xmax, xstep in
    609 printdensity(mandleconverge(x,y)))
    610 : putchard(10)
    611 )
    612
    613 # mandel - This is a convenient helper function for ploting the mandelbrot set
    614 # from the specified position with the specified Magnification.
    615 def mandel(realstart imagstart realmag imagmag)
    616 mandelhelp(realstart, realstart+realmag*78, realmag,
    617 imagstart, imagstart+imagmag*40, imagmag);
    618
    619
    620
    621

    Given this, we can try plotting out the mandlebrot set! Lets try it out:

    622
    623
    624
    
                      
                    
    625 ready> mandel(-2.3, -1.3, 0.05, 0.07);
    626 *******************************+++++++++++*************************************
    627 *************************+++++++++++++++++++++++*******************************
    628 **********************+++++++++++++++++++++++++++++****************************
    629 *******************+++++++++++++++++++++.. ...++++++++*************************
    630 *****************++++++++++++++++++++++.... ...+++++++++***********************
    631 ***************+++++++++++++++++++++++..... ...+++++++++*********************
    632 **************+++++++++++++++++++++++.... ....+++++++++********************
    633 *************++++++++++++++++++++++...... .....++++++++*******************
    634 ************+++++++++++++++++++++....... .......+++++++******************
    635 ***********+++++++++++++++++++.... ... .+++++++*****************
    636 **********+++++++++++++++++....... .+++++++****************
    637 *********++++++++++++++........... ...+++++++***************
    638 ********++++++++++++............ ...++++++++**************
    639 ********++++++++++... .......... .++++++++**************
    640 *******+++++++++..... .+++++++++*************
    641 *******++++++++...... ..+++++++++*************
    642 *******++++++....... ..+++++++++*************
    643 *******+++++...... ..+++++++++*************
    644 *******.... .... ...+++++++++*************
    645 *******.... . ...+++++++++*************
    646 *******+++++...... ...+++++++++*************
    647 *******++++++....... ..+++++++++*************
    648 *******++++++++...... .+++++++++*************
    649 *******+++++++++..... ..+++++++++*************
    650 ********++++++++++... .......... .++++++++**************
    651 ********++++++++++++............ ...++++++++**************
    652 *********++++++++++++++.......... ...+++++++***************
    653 **********++++++++++++++++........ .+++++++****************
    654 **********++++++++++++++++++++.... ... ..+++++++****************
    655 ***********++++++++++++++++++++++....... .......++++++++*****************
    656 ************+++++++++++++++++++++++...... ......++++++++******************
    657 **************+++++++++++++++++++++++.... ....++++++++********************
    658 ***************+++++++++++++++++++++++..... ...+++++++++*********************
    659 *****************++++++++++++++++++++++.... ...++++++++***********************
    660 *******************+++++++++++++++++++++......++++++++*************************
    661 *********************++++++++++++++++++++++.++++++++***************************
    662 *************************+++++++++++++++++++++++*******************************
    663 ******************************+++++++++++++************************************
    664 *******************************************************************************
    665 *******************************************************************************
    666 *******************************************************************************
    667 Evaluated to 0.000000
    668 ready> mandel(-2, -1, 0.02, 0.04);
    669 **************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
    670 ***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    671 *********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
    672 *******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
    673 *****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
    674 ***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
    675 **************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
    676 ************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
    677 ***********++++++++++++++++++++++++++++++++++++++++++++++++++........ .
    678 **********++++++++++++++++++++++++++++++++++++++++++++++.............
    679 ********+++++++++++++++++++++++++++++++++++++++++++..................
    680 *******+++++++++++++++++++++++++++++++++++++++.......................
    681 ******+++++++++++++++++++++++++++++++++++...........................
    682 *****++++++++++++++++++++++++++++++++............................
    683 *****++++++++++++++++++++++++++++...............................
    684 ****++++++++++++++++++++++++++...... .........................
    685 ***++++++++++++++++++++++++......... ...... ...........
    686 ***++++++++++++++++++++++............
    687 **+++++++++++++++++++++..............
    688 **+++++++++++++++++++................
    689 *++++++++++++++++++.................
    690 *++++++++++++++++............ ...
    691 *++++++++++++++..............
    692 *+++....++++................
    693 *.......... ...........
    694 *
    695 *.......... ...........
    696 *+++....++++................
    697 *++++++++++++++..............
    698 *++++++++++++++++............ ...
    699 *++++++++++++++++++.................
    700 **+++++++++++++++++++................
    701 **+++++++++++++++++++++..............
    702 ***++++++++++++++++++++++............
    703 ***++++++++++++++++++++++++......... ...... ...........
    704 ****++++++++++++++++++++++++++...... .........................
    705 *****++++++++++++++++++++++++++++...............................
    706 *****++++++++++++++++++++++++++++++++............................
    707 ******+++++++++++++++++++++++++++++++++++...........................
    708 *******+++++++++++++++++++++++++++++++++++++++.......................
    709 ********+++++++++++++++++++++++++++++++++++++++++++..................
    710 Evaluated to 0.000000
    711 ready> mandel(-0.9, -1.4, 0.02, 0.03);
    712 *******************************************************************************
    713 *******************************************************************************
    714 *******************************************************************************
    715 **********+++++++++++++++++++++************************************************
    716 *+++++++++++++++++++++++++++++++++++++++***************************************
    717 +++++++++++++++++++++++++++++++++++++++++++++**********************************
    718 ++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
    719 ++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
    720 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
    721 +++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
    722 +++++++++++++++++++++++++++++++.... ......+++++++++++++++++++****************
    723 +++++++++++++++++++++++++++++....... ........+++++++++++++++++++**************
    724 ++++++++++++++++++++++++++++........ ........++++++++++++++++++++************
    725 +++++++++++++++++++++++++++......... .. ...+++++++++++++++++++++**********
    726 ++++++++++++++++++++++++++........... ....++++++++++++++++++++++********
    727 ++++++++++++++++++++++++............. .......++++++++++++++++++++++******
    728 +++++++++++++++++++++++............. ........+++++++++++++++++++++++****
    729 ++++++++++++++++++++++........... ..........++++++++++++++++++++++***
    730 ++++++++++++++++++++........... .........++++++++++++++++++++++*
    731 ++++++++++++++++++............ ...........++++++++++++++++++++
    732 ++++++++++++++++............... .............++++++++++++++++++
    733 ++++++++++++++................. ...............++++++++++++++++
    734 ++++++++++++.................. .................++++++++++++++
    735 +++++++++.................. .................+++++++++++++
    736 ++++++........ . ......... ..++++++++++++
    737 ++............ ...... ....++++++++++
    738 .............. ...++++++++++
    739 .............. ....+++++++++
    740 .............. .....++++++++
    741 ............. ......++++++++
    742 ........... .......++++++++
    743 ......... ........+++++++
    744 ......... ........+++++++
    745 ......... ....+++++++
    746 ........ ...+++++++
    747 ....... ...+++++++
    748 ....+++++++
    749 .....+++++++
    750 ....+++++++
    751 ....+++++++
    752 ....+++++++
    753 Evaluated to 0.000000
    754 ready> ^D
    755
    756
    757
    758

    At this point, you may be starting to realize that Kaleidoscope is a real

    759 and powerful language. It may not be self-similar :), but it can be used to
    760 plot things that are!

    761
    762

    With this, we conclude the "adding user-defined operators" chapter of the

    763 tutorial. We have successfully augmented our language, adding the ability to
    764 extend the language in the library, and we have shown how this can be used to
    765 build a simple but interesting end-user application in Kaleidoscope. At this
    766 point, Kaleidoscope can build a variety of applications that are functional and
    767 can call functions with side-effects, but it can't actually define and mutate a
    768 variable itself.

    769
    770

    Strikingly, variable mutation is an important feature of some

    771 languages, and it is not at all obvious how to add
    772 support for mutable variables without having to add an "SSA construction"
    773 phase to your front-end. In the next chapter, we will describe how you can
    774 add variable mutation without building SSA in your front-end.

    775
    776
    777
    778
    779
    780
    781
    782
    783
    784
    785

    786 Here is the complete code listing for our running example, enhanced with the
    787 if/then/else and for expressions.. To build this example, use:
    788

    789
    790
    791
    
                      
                    
    792 # Compile
    793 ocamlbuild toy.byte
    794 # Run
    795 ./toy.byte
    796
    797
    798
    799

    Here is the code:

    800
    801
    802
    _tags:
    803
    804
    
                      
                    
    805 <{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
    806 <*.{byte,native}>: g++, use_llvm, use_llvm_analysis
    807 <*.{byte,native}>: use_llvm_executionengine, use_llvm_target
    808 <*.{byte,native}>: use_llvm_scalar_opts, use_bindings
    809
    810
    811
    812
    myocamlbuild.ml:
    813
    814
    
                      
                    
    815 open Ocamlbuild_plugin;;
    816
    817 ocaml_lib ~extern:true "llvm";;
    818 ocaml_lib ~extern:true "llvm_analysis";;
    819 ocaml_lib ~extern:true "llvm_executionengine";;
    820 ocaml_lib ~extern:true "llvm_target";;
    821 ocaml_lib ~extern:true "llvm_scalar_opts";;
    822
    823 flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
    824 dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
    825
    826
    827
    828
    token.ml:
    829
    830
    
                      
                    
    831 (*===----------------------------------------------------------------------===
    832 * Lexer Tokens
    833 *===----------------------------------------------------------------------===*)
    834
    835 (* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
    836 * these others for known things. *)
    837 type token =
    838 (* commands *)
    839 | Def | Extern
    840
    841 (* primary *)
    842 | Ident of string | Number of float
    843
    844 (* unknown *)
    845 | Kwd of char
    846
    847 (* control *)
    848 | If | Then | Else
    849 | For | In
    850
    851 (* operators *)
    852 | Binary | Unary
    853
    854
    855
    856
    lexer.ml:
    857
    858
    
                      
                    
    859 (*===----------------------------------------------------------------------===
    860 * Lexer
    861 *===----------------------------------------------------------------------===*)
    862
    863 let rec lex = parser
    864 (* Skip any whitespace. *)
    865 | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
    866
    867 (* identifier: [a-zA-Z][a-zA-Z0-9] *)
    868 | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
    869 let buffer = Buffer.create 1 in
    870 Buffer.add_char buffer c;
    871 lex_ident buffer stream
    872
    873 (* number: [0-9.]+ *)
    874 | [< ' ('0' .. '9' as c); stream >] ->
    875 let buffer = Buffer.create 1 in
    876 Buffer.add_char buffer c;
    877 lex_number buffer stream
    878
    879 (* Comment until end of line. *)
    880 | [< ' ('#'); stream >] ->
    881 lex_comment stream
    882
    883 (* Otherwise, just return the character as its ascii value. *)
    884 | [< 'c; stream >] ->
    885 [< 'Token.Kwd c; lex stream >]
    886
    887 (* end of stream. *)
    888 | [< >] -> [< >]
    889
    890 and lex_number buffer = parser
    891 | [< ' ('0' .. '9' | '.' as c); stream >] ->
    892 Buffer.add_char buffer c;
    893 lex_number buffer stream
    894 | [< stream=lex >] ->
    895 [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
    896
    897 and lex_ident buffer = parser
    898 | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
    899 Buffer.add_char buffer c;
    900 lex_ident buffer stream
    901 | [< stream=lex >] ->
    902 match Buffer.contents buffer with
    903 | "def" -> [< 'Token.Def; stream >]
    904 | "extern" -> [< 'Token.Extern; stream >]
    905 | "if" -> [< 'Token.If; stream >]
    906 | "then" -> [< 'Token.Then; stream >]
    907 | "else" -> [< 'Token.Else; stream >]
    908 | "for" -> [< 'Token.For; stream >]
    909 | "in" -> [< 'Token.In; stream >]
    910 | "binary" -> [< 'Token.Binary; stream >]
    911 | "unary" -> [< 'Token.Unary; stream >]
    912 | id -> [< 'Token.Ident id; stream >]
    913
    914 and lex_comment = parser
    915 | [< ' ('\n'); stream=lex >] -> stream
    916 | [< 'c; e=lex_comment >] -> e
    917 | [< >] -> [< >]
    918
    919
    920
    921
    ast.ml:
    922
    923
    
                      
                    
    924 (*===----------------------------------------------------------------------===
    925 * Abstract Syntax Tree (aka Parse Tree)
    926 *===----------------------------------------------------------------------===*)
    927
    928 (* expr - Base type for all expression nodes. *)
    929 type expr =
    930 (* variant for numeric literals like "1.0". *)
    931 | Number of float
    932
    933 (* variant for referencing a variable, like "a". *)
    934 | Variable of string
    935
    936 (* variant for a unary operator. *)
    937 | Unary of char * expr
    938
    939 (* variant for a binary operator. *)
    940 | Binary of char * expr * expr
    941
    942 (* variant for function calls. *)
    943 | Call of string * expr array
    944
    945 (* variant for if/then/else. *)
    946 | If of expr * expr * expr
    947
    948 (* variant for for/in. *)
    949 | For of string * expr * expr * expr option * expr
    950
    951 (* proto - This type represents the "prototype" for a function, which captures
    952 * its name, and its argument names (thus implicitly the number of arguments the
    953 * function takes). *)
    954 type proto =
    955 | Prototype of string * string array
    956 | BinOpPrototype of string * string array * int
    957
    958 (* func - This type represents a function definition itself. *)
    959 type func = Function of proto * expr
    960
    961
    962
    963
    parser.ml:
    964
    965
    
                      
                    
    966 (*===---------------------------------------------------------------------===
    967 * Parser
    968 *===---------------------------------------------------------------------===*)
    969
    970 (* binop_precedence - This holds the precedence for each binary operator that is
    971 * defined *)
    972 let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
    973
    974 (* precedence - Get the precedence of the pending binary operator token. *)
    975 let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
    976
    977 (* primary
    978 * ::= identifier
    979 * ::= numberexpr
    980 * ::= parenexpr
    981 * ::= ifexpr
    982 * ::= forexpr *)
    983 let rec parse_primary = parser
    984 (* numberexpr ::= number *)
    985 | [< 'Token.Number n >] -> Ast.Number n
    986
    987 (* parenexpr ::= '(' expression ')' *)
    988 | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
    989
    990 (* identifierexpr
    991 * ::= identifier
    992 * ::= identifier '(' argumentexpr ')' *)
    993 | [< 'Token.Ident id; stream >] ->
    994 let rec parse_args accumulator = parser
    995 | [< e=parse_expr; stream >] ->
    996 begin parser
    997 | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
    998 | [< >] -> e :: accumulator
    999 end stream
    1000 | [< >] -> accumulator
    1001 in
    1002 let rec parse_ident id = parser
    1003 (* Call. *)
    1004 | [< 'Token.Kwd '(';
    1005 args=parse_args [];
    1006 'Token.Kwd ')' ?? "expected ')'">] ->
    1007 Ast.Call (id, Array.of_list (List.rev args))
    1008
    1009 (* Simple variable ref. *)
    1010 | [< >] -> Ast.Variable id
    1011 in
    1012 parse_ident id stream
    1013
    1014 (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
    1015 | [< 'Token.If; c=parse_expr;
    1016 'Token.Then ?? "expected 'then'"; t=parse_expr;
    1017 'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
    1018 Ast.If (c, t, e)
    1019
    1020 (* forexpr
    1021 ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
    1022 | [< 'Token.For;
    1023 'Token.Ident id ?? "expected identifier after for";
    1024 'Token.Kwd '=' ?? "expected '=' after for";
    1025 stream >] ->
    1026 begin parser
    1027 | [<
    1028 start=parse_expr;
    1029 'Token.Kwd ',' ?? "expected ',' after for";
    1030 end_=parse_expr;
    1031 stream >] ->
    1032 let step =
    1033 begin parser
    1034 | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
    1035 | [< >] -> None
    1036 end stream
    1037 in
    1038 begin parser
    1039 | [< 'Token.In; body=parse_expr >] ->
    1040 Ast.For (id, start, end_, step, body)
    1041 | [< >] ->
    1042 raise (Stream.Error "expected 'in' after for")
    1043 end stream
    1044 | [< >] ->
    1045 raise (Stream.Error "expected '=' after for")
    1046 end stream
    1047
    1048 | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
    1049
    1050 (* unary
    1051 * ::= primary
    1052 * ::= '!' unary *)
    1053 and parse_unary = parser
    1054 (* If this is a unary operator, read it. *)
    1055 | [< 'Token.Kwd op when op != '(' && op != ')'; operand=parse_expr >] ->
    1056 Ast.Unary (op, operand)
    1057
    1058 (* If the current token is not an operator, it must be a primary expr. *)
    1059 | [< stream >] -> parse_primary stream
    1060
    1061 (* binoprhs
    1062 * ::= ('+' primary)* *)
    1063 and parse_bin_rhs expr_prec lhs stream =
    1064 match Stream.peek stream with
    1065 (* If this is a binop, find its precedence. *)
    1066 | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
    1067 let token_prec = precedence c in
    1068
    1069 (* If this is a binop that binds at least as tightly as the current binop,
    1070 * consume it, otherwise we are done. *)
    1071 if token_prec < expr_prec then lhs else begin
    1072 (* Eat the binop. *)
    1073 Stream.junk stream;
    1074
    1075 (* Parse the unary expression after the binary operator. *)
    1076 let rhs = parse_unary stream in
    1077
    1078 (* Okay, we know this is a binop. *)
    1079 let rhs =
    1080 match Stream.peek stream with
    1081 | Some (Token.Kwd c2) ->
    1082 (* If BinOp binds less tightly with rhs than the operator after
    1083 * rhs, let the pending operator take rhs as its lhs. *)
    1084 let next_prec = precedence c2 in
    1085 if token_prec < next_prec
    1086 then parse_bin_rhs (token_prec + 1) rhs stream
    1087 else rhs
    1088 | _ -> rhs
    1089 in
    1090
    1091 (* Merge lhs/rhs. *)
    1092 let lhs = Ast.Binary (c, lhs, rhs) in
    1093 parse_bin_rhs expr_prec lhs stream
    1094 end
    1095 | _ -> lhs
    1096
    1097 (* expression
    1098 * ::= primary binoprhs *)
    1099 and parse_expr = parser
    1100 | [< lhs=parse_unary; stream >] -> parse_bin_rhs 0 lhs stream
    1101
    1102 (* prototype
    1103 * ::= id '(' id* ')'
    1104 * ::= binary LETTER number? (id, id)
    1105 * ::= unary LETTER number? (id) *)
    1106 let parse_prototype =
    1107 let rec parse_args accumulator = parser
    1108 | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
    1109 | [< >] -> accumulator
    1110 in
    1111 let parse_operator = parser
    1112 | [< 'Token.Unary >] -> "unary", 1
    1113 | [< 'Token.Binary >] -> "binary", 2
    1114 in
    1115 let parse_binary_precedence = parser
    1116 | [< 'Token.Number n >] -> int_of_float n
    1117 | [< >] -> 30
    1118 in
    1119 parser
    1120 | [< 'Token.Ident id;
    1121 'Token.Kwd '(' ?? "expected '(' in prototype";
    1122 args=parse_args [];
    1123 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    1124 (* success. *)
    1125 Ast.Prototype (id, Array.of_list (List.rev args))
    1126 | [< (prefix, kind)=parse_operator;
    1127 'Token.Kwd op ?? "expected an operator";
    1128 (* Read the precedence if present. *)
    1129 binary_precedence=parse_binary_precedence;
    1130 'Token.Kwd '(' ?? "expected '(' in prototype";
    1131 args=parse_args [];
    1132 'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
    1133 let name = prefix ^ (String.make 1 op) in
    1134 let args = Array.of_list (List.rev args) in
    1135
    1136 (* Verify right number of arguments for operator. *)
    1137 if Array.length args != kind
    1138 then raise (Stream.Error "invalid number of operands for operator")
    1139 else
    1140 if kind == 1 then
    1141 Ast.Prototype (name, args)
    1142 else
    1143 Ast.BinOpPrototype (name, args, binary_precedence)
    1144 | [< >] ->
    1145 raise (Stream.Error "expected function name in prototype")
    1146
    1147 (* definition ::= 'def' prototype expression *)
    1148 let parse_definition = parser
    1149 | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
    1150 Ast.Function (p, e)
    1151
    1152 (* toplevelexpr ::= expression *)
    1153 let parse_toplevel = parser
    1154 | [< e=parse_expr >] ->
    1155 (* Make an anonymous proto. *)
    1156 Ast.Function (Ast.Prototype ("", [||]), e)
    1157
    1158 (* external ::= 'extern' prototype *)
    1159 let parse_extern = parser
    1160 | [< 'Token.Extern; e=parse_prototype >] -> e
    1161
    1162
    1163
    1164
    codegen.ml:
    1165
    1166
    
                      
                    
    1167 (*===----------------------------------------------------------------------===
    1168 * Code Generation
    1169 *===----------------------------------------------------------------------===*)
    1170
    1171 open Llvm
    1172
    1173 exception Error of string
    1174
    1175 let the_module = create_module "my cool jit"
    1176 let builder = builder ()
    1177 let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
    1178
    1179 let rec codegen_expr = function
    1180 | Ast.Number n -> const_float double_type n
    1181 | Ast.Variable name ->
    1182 (try Hashtbl.find named_values name with
    1183 | Not_found -> raise (Error "unknown variable name"))
    1184 | Ast.Unary (op, operand) ->
    1185 let operand = codegen_expr operand in
    1186 let callee = "unary" ^ (String.make 1 op) in
    1187 let callee =
    1188 match lookup_function callee the_module with
    1189 | Some callee -> callee
    1190 | None -> raise (Error "unknown unary operator")
    1191 in
    1192 build_call callee [|operand|] "unop" builder
    1193 | Ast.Binary (op, lhs, rhs) ->
    1194 let lhs_val = codegen_expr lhs in
    1195 let rhs_val = codegen_expr rhs in
    1196 begin
    1197 match op with
    1198 | '+' -> build_add lhs_val rhs_val "addtmp" builder
    1199 | '-' -> build_sub lhs_val rhs_val "subtmp" builder
    1200 | '*' -> build_mul lhs_val rhs_val "multmp" builder
    1201 | '<' ->
    1202 (* Convert bool 0/1 to double 0.0 or 1.0 *)
    1203 let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
    1204 build_uitofp i double_type "booltmp" builder
    1205 | _ ->
    1206 (* If it wasn't a builtin binary operator, it must be a user defined
    1207 * one. Emit a call to it. *)
    1208 let callee = "binary" ^ (String.make 1 op) in
    1209 let callee =
    1210 match lookup_function callee the_module with
    1211 | Some callee -> callee
    1212 | None -> raise (Error "binary operator not found!")
    1213 in
    1214 build_call callee [|lhs_val; rhs_val|] "binop" builder
    1215 end
    1216 | Ast.Call (callee, args) ->
    1217 (* Look up the name in the module table. *)
    1218 let callee =
    1219 match lookup_function callee the_module with
    1220 | Some callee -> callee
    1221 | None -> raise (Error "unknown function referenced")
    1222 in
    1223 let params = params callee in
    1224
    1225 (* If argument mismatch error. *)
    1226 if Array.length params == Array.length args then () else
    1227 raise (Error "incorrect # arguments passed");
    1228 let args = Array.map codegen_expr args in
    1229 build_call callee args "calltmp" builder
    1230 | Ast.If (cond, then_, else_) ->
    1231 let cond = codegen_expr cond in
    1232
    1233 (* Convert condition to a bool by comparing equal to 0.0 *)
    1234 let zero = const_float double_type 0.0 in
    1235 let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
    1236
    1237 (* Grab the first block so that we might later add the conditional branch
    1238 * to it at the end of the function. *)
    1239 let start_bb = insertion_block builder in
    1240 let the_function = block_parent start_bb in
    1241
    1242 let then_bb = append_block "then" the_function in
    1243
    1244 (* Emit 'then' value. *)
    1245 position_at_end then_bb builder;
    1246 let then_val = codegen_expr then_ in
    1247
    1248 (* Codegen of 'then' can change the current block, update then_bb for the
    1249 * phi. We create a new name because one is used for the phi node, and the
    1250 * other is used for the conditional branch. *)
    1251 let new_then_bb = insertion_block builder in
    1252
    1253 (* Emit 'else' value. *)
    1254 let else_bb = append_block "else" the_function in
    1255 position_at_end else_bb builder;
    1256 let else_val = codegen_expr else_ in
    1257
    1258 (* Codegen of 'else' can change the current block, update else_bb for the
    1259 * phi. *)
    1260 let new_else_bb = insertion_block builder in
    1261
    1262 (* Emit merge block. *)
    1263 let merge_bb = append_block "ifcont" the_function in
    1264 position_at_end merge_bb builder;
    1265 let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
    1266 let phi = build_phi incoming "iftmp" builder in
    1267
    1268 (* Return to the start block to add the conditional branch. *)
    1269 position_at_end start_bb builder;
    1270 ignore (build_cond_br cond_val then_bb else_bb builder);
    1271
    1272 (* Set a unconditional branch at the end of the 'then' block and the
    1273 * 'else' block to the 'merge' block. *)
    1274 position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
    1275 position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
    1276
    1277 (* Finally, set the builder to the end of the merge block. *)
    1278 position_at_end merge_bb builder;
    1279
    1280 phi
    1281 | Ast.For (var_name, start, end_, step, body) ->
    1282 (* Emit the start code first, without 'variable' in scope. *)
    1283 let start_val = codegen_expr start in
    1284
    1285 (* Make the new basic block for the loop header, inserting after current
    1286 * block. *)
    1287 let preheader_bb = insertion_block builder in
    1288 let the_function = block_parent preheader_bb in
    1289 let loop_bb = append_block "loop" the_function in
    1290
    1291 (* Insert an explicit fall through from the current block to the
    1292 * loop_bb. *)
    1293 ignore (build_br loop_bb builder);
    1294
    1295 (* Start insertion in loop_bb. *)
    1296 position_at_end loop_bb builder;
    1297
    1298 (* Start the PHI node with an entry for start. *)
    1299 let variable = build_phi [(start_val, preheader_bb)] var_name builder in
    1300
    1301 (* Within the loop, the variable is defined equal to the PHI node. If it
    1302 * shadows an existing variable, we have to restore it, so save it
    1303 * now. *)
    1304 let old_val =
    1305 try Some (Hashtbl.find named_values var_name) with Not_found -> None
    1306 in
    1307 Hashtbl.add named_values var_name variable;
    1308
    1309 (* Emit the body of the loop. This, like any other expr, can change the
    1310 * current BB. Note that we ignore the value computed by the body, but
    1311 * don't allow an error *)
    1312 ignore (codegen_expr body);
    1313
    1314 (* Emit the step value. *)
    1315 let step_val =
    1316 match step with
    1317 | Some step -> codegen_expr step
    1318 (* If not specified, use 1.0. *)
    1319 | None -> const_float double_type 1.0
    1320 in
    1321
    1322 let next_var = build_add variable step_val "nextvar" builder in
    1323
    1324 (* Compute the end condition. *)
    1325 let end_cond = codegen_expr end_ in
    1326
    1327 (* Convert condition to a bool by comparing equal to 0.0. *)
    1328 let zero = const_float double_type 0.0 in
    1329 let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
    1330
    1331 (* Create the "after loop" block and insert it. *)
    1332 let loop_end_bb = insertion_block builder in
    1333 let after_bb = append_block "afterloop" the_function in
    1334
    1335 (* Insert the conditional branch into the end of loop_end_bb. *)
    1336 ignore (build_cond_br end_cond loop_bb after_bb builder);
    1337
    1338 (* Any new code will be inserted in after_bb. *)
    1339 position_at_end after_bb builder;
    1340
    1341 (* Add a new entry to the PHI node for the backedge. *)
    1342 add_incoming (next_var, loop_end_bb) variable;
    1343
    1344 (* Restore the unshadowed variable. *)
    1345 begin match old_val with
    1346 | Some old_val -> Hashtbl.add named_values var_name old_val
    1347 | None -> ()
    1348 end;
    1349
    1350 (* for expr always returns 0.0. *)
    1351 const_null double_type
    1352
    1353 let codegen_proto = function
    1354 | Ast.Prototype (name, args) | Ast.BinOpPrototype (name, args, _) ->
    1355 (* Make the function type: double(double,double) etc. *)
    1356 let doubles = Array.make (Array.length args) double_type in
    1357 let ft = function_type double_type doubles in
    1358 let f =
    1359 match lookup_function name the_module with
    1360 | None -> declare_function name ft the_module
    1361
    1362 (* If 'f' conflicted, there was already something named 'name'. If it
    1363 * has a body, don't allow redefinition or reextern. *)
    1364 | Some f ->
    1365 (* If 'f' already has a body, reject this. *)
    1366 if block_begin f <> At_end f then
    1367 raise (Error "redefinition of function");
    1368
    1369 (* If 'f' took a different number of arguments, reject. *)
    1370 if element_type (type_of f) <> ft then
    1371 raise (Error "redefinition of function with different # args");
    1372 f
    1373 in
    1374
    1375 (* Set names for all arguments. *)
    1376 Array.iteri (fun i a ->
    1377 let n = args.(i) in
    1378 set_value_name n a;
    1379 Hashtbl.add named_values n a;
    1380 ) (params f);
    1381 f
    1382
    1383 let codegen_func the_fpm = function
    1384 | Ast.Function (proto, body) ->
    1385 Hashtbl.clear named_values;
    1386 let the_function = codegen_proto proto in
    1387
    1388 (* If this is an operator, install it. *)
    1389 begin match proto with
    1390 | Ast.BinOpPrototype (name, args, prec) ->
    1391 let op = name.[String.length name - 1] in
    1392 Hashtbl.add Parser.binop_precedence op prec;
    1393 | _ -> ()
    1394 end;
    1395
    1396 (* Create a new basic block to start insertion into. *)
    1397 let bb = append_block "entry" the_function in
    1398 position_at_end bb builder;
    1399
    1400 try
    1401 let ret_val = codegen_expr body in
    1402
    1403 (* Finish off the function. *)
    1404 let _ = build_ret ret_val builder in
    1405
    1406 (* Validate the generated code, checking for consistency. *)
    1407 Llvm_analysis.assert_valid_function the_function;
    1408
    1409 (* Optimize the function. *)
    1410 let _ = PassManager.run_function the_function the_fpm in
    1411
    1412 the_function
    1413 with e ->
    1414 delete_function the_function;
    1415 raise e
    1416
    1417
    1418
    1419
    toplevel.ml:
    1420
    1421
    
                      
                    
    1422 (*===----------------------------------------------------------------------===
    1423 * Top-Level parsing and JIT Driver
    1424 *===----------------------------------------------------------------------===*)
    1425
    1426 open Llvm
    1427 open Llvm_executionengine
    1428
    1429 (* top ::= definition | external | expression | ';' *)
    1430 let rec main_loop the_fpm the_execution_engine stream =
    1431 match Stream.peek stream with
    1432 | None -> ()
    1433
    1434 (* ignore top-level semicolons. *)
    1435 | Some (Token.Kwd ';') ->
    1436 Stream.junk stream;
    1437 main_loop the_fpm the_execution_engine stream
    1438
    1439 | Some token ->
    1440 begin
    1441 try match token with
    1442 | Token.Def ->
    1443 let e = Parser.parse_definition stream in
    1444 print_endline "parsed a function definition.";
    1445 dump_value (Codegen.codegen_func the_fpm e);
    1446 | Token.Extern ->
    1447 let e = Parser.parse_extern stream in
    1448 print_endline "parsed an extern.";
    1449 dump_value (Codegen.codegen_proto e);
    1450 | _ ->
    1451 (* Evaluate a top-level expression into an anonymous function. *)
    1452 let e = Parser.parse_toplevel stream in
    1453 print_endline "parsed a top-level expr";
    1454 let the_function = Codegen.codegen_func the_fpm e in
    1455 dump_value the_function;
    1456
    1457 (* JIT the function, returning a function pointer. *)
    1458 let result = ExecutionEngine.run_function the_function [||]
    1459 the_execution_engine in
    1460
    1461 print_string "Evaluated to ";
    1462 print_float (GenericValue.as_float double_type result);
    1463 print_newline ();
    1464 with Stream.Error s | Codegen.Error s ->
    1465 (* Skip token for error recovery. *)
    1466 Stream.junk stream;
    1467 print_endline s;
    1468 end;
    1469 print_string "ready> "; flush stdout;
    1470 main_loop the_fpm the_execution_engine stream
    1471
    1472
    1473
    1474
    toy.ml:
    1475
    1476
    
                      
                    
    1477 (*===----------------------------------------------------------------------===
    1478 * Main driver code.
    1479 *===----------------------------------------------------------------------===*)
    1480
    1481 open Llvm
    1482 open Llvm_executionengine
    1483 open Llvm_target
    1484 open Llvm_scalar_opts
    1485
    1486 let main () =
    1487 (* Install standard binary operators.
    1488 * 1 is the lowest precedence. *)
    1489 Hashtbl.add Parser.binop_precedence '<' 10;
    1490 Hashtbl.add Parser.binop_precedence '+' 20;
    1491 Hashtbl.add Parser.binop_precedence '-' 20;
    1492 Hashtbl.add Parser.binop_precedence '*' 40; (* highest. *)
    1493
    1494 (* Prime the first token. *)
    1495 print_string "ready> "; flush stdout;
    1496 let stream = Lexer.lex (Stream.of_channel stdin) in
    1497
    1498 (* Create the JIT. *)
    1499 let the_module_provider = ModuleProvider.create Codegen.the_module in
    1500 let the_execution_engine = ExecutionEngine.create the_module_provider in
    1501 let the_fpm = PassManager.create_function the_module_provider in
    1502
    1503 (* Set up the optimizer pipeline. Start with registering info about how the
    1504 * target lays out data structures. *)
    1505 TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
    1506
    1507 (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
    1508 add_instruction_combining the_fpm;
    1509
    1510 (* reassociate expressions. *)
    1511 add_reassociation the_fpm;
    1512
    1513 (* Eliminate Common SubExpressions. *)
    1514 add_gvn the_fpm;
    1515
    1516 (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
    1517 add_cfg_simplification the_fpm;
    1518
    1519 (* Run the main "interpreter loop" now. *)
    1520 Toplevel.main_loop the_fpm the_execution_engine stream;
    1521
    1522 (* Print out all the generated code. *)
    1523 dump_module Codegen.the_module
    1524 ;;
    1525
    1526 main ()
    1527
    1528
    1529
    1530
    bindings.c
    1531
    1532
    
                      
                    
    1533 #include <stdio.h>
    1534
    1535 /* putchard - putchar that takes a double and returns 0. */
    1536 extern double putchard(double X) {
    1537 putchar((char)X);
    1538 return 0;
    1539 }
    1540
    1541 /* printd - printf that takes a double prints it as "%f\n", returning 0. */
    1542 extern double printd(double X) {
    1543 printf("%f\n", X);
    1544 return 0;
    1545 }
    1546
    1547
    1548
    1549
    1550 Next: Extending the language: mutable variables /
    1551 SSA construction
    1552
    1553
    1554
    1555
    1556
    1557
    1558 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!">
    1559
    1560 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!">
    1561
    1562 Chris Lattner
    1563 Erick Tryzelaar
    1564 The LLVM Compiler Infrastructure
    1565 Last modified: $Date: 2007-10-17 11:05:13 -0700 (Wed, 17 Oct 2007) $
    1566
    1567
    1568
    0
    1 "http://www.w3.org/TR/html4/strict.dtd">
    2
    3
    4
    5 Kaleidoscope: Extending the Language: Mutable Variables / SSA </span> </span> </td> </tr><tr><td class=linenos></td><td class=linenos><a href="#4-R-6">6</a></td> <td class="add"> <span id="4-R-6"><a name="4-R-6"></a><span class=line> construction
    7
    8
    9
    10
    11
    12
    13
    14
    15
    Kaleidoscope: Extending the Language: Mutable Variables
    16
    17
    18
  • Up to Tutorial Index
  • 19
  • Chapter 7
  • 20
    21
  • Chapter 7 Introduction
  • 22
  • Why is this a hard problem?
  • 23
  • Memory in LLVM
  • 24
  • Mutable Variables in Kaleidoscope
  • 25
  • Adjusting Existing Variables for
  • 26 Mutation
    27
  • New Assignment Operator
  • 28
  • User-defined Local Variables
  • 29
  • Full Code Listing
  • 30
    31
    32
  • Chapter 8: Conclusion and other useful LLVM
  • 33 tidbits
    34
    35
    36
    37

    38 Written by Chris Lattner
    39 and Erick Tryzelaar
    40

    41
    42
    43
    44
    45
    46
    47
    48
    49

    Welcome to Chapter 7 of the "Implementing a language

    50 with LLVM" tutorial. In chapters 1 through 6, we've built a very
    51 respectable, albeit simple,
    52 href="http://en.wikipedia.org/wiki/Functional_programming">functional
    53 programming language. In our journey, we learned some parsing techniques,
    54 how to build and represent an AST, how to build LLVM IR, and how to optimize
    55 the resultant code as well as JIT compile it.

    56
    57

    While Kaleidoscope is interesting as a functional language, the fact that it

    58 is functional makes it "too easy" to generate LLVM IR for it. In particular, a
    59 functional language makes it very easy to build LLVM IR directly in
    60 href="http://en.wikipedia.org/wiki/Static_single_assignment_form">SSA form.
    61 Since LLVM requires that the input code be in SSA form, this is a very nice
    62 property and it is often unclear to newcomers how to generate code for an
    63 imperative language with mutable variables.

    64
    65

    The short (and happy) summary of this chapter is that there is no need for

    66 your front-end to build SSA form: LLVM provides highly tuned and well tested
    67 support for this, though the way it works is a bit unexpected for some.

    68
    69
    70
    71
    72
    73
    74
    75
    76
    77

    78 To understand why mutable variables cause complexities in SSA construction,
    79 consider this extremely simple C example:
    80

    81
    82
    83
    
                      
                    
    84 int G, H;
    85 int test(_Bool Condition) {
    86 int X;
    87 if (Condition)
    88 X = G;
    89 else
    90 X = H;
    91 return X;
    92 }
    93
    94
    95
    96

    In this case, we have the variable "X", whose value depends on the path

    97 executed in the program. Because there are two different possible values for X
    98 before the return instruction, a PHI node is inserted to merge the two values.
    99 The LLVM IR that we want for this example looks like this:

    100
    101
    102
    
                      
                    
    103 @G = weak global i32 0 ; type of @G is i32*
    104 @H = weak global i32 0 ; type of @H is i32*
    105
    106 define i32 @test(i1 %Condition) {
    107 entry:
    108 br i1 %Condition, label %cond_true, label %cond_false
    109
    110 cond_true:
    111 %X.0 = load i32* @G
    112 br label %cond_next
    113
    114 cond_false:
    115 %X.1 = load i32* @H
    116 br label %cond_next
    117
    118 cond_next:
    119 %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
    120 ret i32 %X.2
    121 }
    122
    123
    124
    125

    In this example, the loads from the G and H global variables are explicit in

    126 the LLVM IR, and they live in the then/else branches of the if statement
    127 (cond_true/cond_false). In order to merge the incoming values, the X.2 phi node
    128 in the cond_next block selects the right value to use based on where control
    129 flow is coming from: if control flow comes from the cond_false block, X.2 gets
    130 the value of X.1. Alternatively, if control flow comes from cond_true, it gets
    131 the value of X.0. The intent of this chapter is not to explain the details of
    132 SSA form. For more information, see one of the many
    133 href="http://en.wikipedia.org/wiki/Static_single_assignment_form">online
    134 references.

    135
    136

    The question for this article is "who places the phi nodes when lowering

    137 assignments to mutable variables?". The issue here is that LLVM
    138 requires that its IR be in SSA form: there is no "non-ssa" mode for it.
    139 However, SSA construction requires non-trivial algorithms and data structures,
    140 so it is inconvenient and wasteful for every front-end to have to reproduce this
    141 logic.

    142
    143
    144
    145
    146
    147
    148
    149
    150
    151

    The 'trick' here is that while LLVM does require all register values to be

    152 in SSA form, it does not require (or permit) memory objects to be in SSA form.
    153 In the example above, note that the loads from G and H are direct accesses to
    154 G and H: they are not renamed or versioned. This differs from some other
    155 compiler systems, which do try to version memory objects. In LLVM, instead of
    156 encoding dataflow analysis of memory into the LLVM IR, it is handled with
    157 href="../WritingAnLLVMPass.html">Analysis Passes which are computed on
    158 demand.

    159
    160

    161 With this in mind, the high-level idea is that we want to make a stack variable
    162 (which lives in memory, because it is on the stack) for each mutable object in
    163 a function. To take advantage of this trick, we need to talk about how LLVM
    164 represents stack variables.
    165

    166
    167

    In LLVM, all memory accesses are explicit with load/store instructions, and

    168 it is carefully designed not to have (or need) an "address-of" operator. Notice
    169 how the type of the @G/@H global variables is actually "i32*" even though the
    170 variable is defined as "i32". What this means is that @G defines space
    171 for an i32 in the global data area, but its name actually refers to the
    172 address for that space. Stack variables work the same way, except that instead of
    173 being declared with global variable definitions, they are declared with the
    174 LLVM alloca instruction:

    175
    176
    177
    
                      
                    
    178 define i32 @example() {
    179 entry:
    180 %X = alloca i32 ; type of %X is i32*.
    181 ...
    182 %tmp = load i32* %X ; load the stack value %X from the stack.
    183 %tmp2 = add i32 %tmp, 1 ; increment it
    184 store i32 %tmp2, i32* %X ; store it back
    185 ...
    186
    187
    188
    189

    This code shows an example of how you can declare and manipulate a stack

    190 variable in the LLVM IR. Stack memory allocated with the alloca instruction is
    191 fully general: you can pass the address of the stack slot to functions, you can
    192 store it in other variables, etc. In our example above, we could rewrite the
    193 example to use the alloca technique to avoid using a PHI node:

    194
    195
    196
    
                      
                    
    197 @G = weak global i32 0 ; type of @G is i32*
    198 @H = weak global i32 0 ; type of @H is i32*
    199
    200 define i32 @test(i1 %Condition) {
    201 entry:
    202 %X = alloca i32 ; type of %X is i32*.
    203 br i1 %Condition, label %cond_true, label %cond_false
    204
    205 cond_true:
    206 %X.0 = load i32* @G
    207 store i32 %X.0, i32* %X ; Update X
    208 br label %cond_next
    209
    210 cond_false:
    211 %X.1 = load i32* @H
    212 store i32 %X.1, i32* %X ; Update X
    213 br label %cond_next
    214
    215 cond_next:
    216 %X.2 = load i32* %X ; Read X
    217 ret i32 %X.2
    218 }
    219
    220
    221
    222

    With this, we have discovered a way to handle arbitrary mutable variables

    223 without the need to create Phi nodes at all:

    224
    225
    226
  • Each mutable variable becomes a stack allocation.
  • 227
  • Each read of the variable becomes a load from the stack.
  • 228
  • Each update of the variable becomes a store to the stack.
  • 229
  • Taking the address of a variable just uses the stack address directly.
  • 230
    231
    232

    While this solution has solved our immediate problem, it introduced another

    233 one: we have now apparently introduced a lot of stack traffic for very simple
    234 and common operations, a major performance problem. Fortunately for us, the
    235 LLVM optimizer has a highly-tuned optimization pass named "mem2reg" that handles
    236 this case, promoting allocas like this into SSA registers, inserting Phi nodes
    237 as appropriate. If you run this example through the pass, for example, you'll
    238 get:

    239
    240
    241
    
                      
                    
    242 $ llvm-as < example.ll | opt -mem2reg | llvm-dis
    243 @G = weak global i32 0
    244 @H = weak global i32 0
    245
    246 define i32 @test(i1 %Condition) {
    247 entry:
    248 br i1 %Condition, label %cond_true, label %cond_false
    249
    250 cond_true:
    251 %X.0 = load i32* @G
    252 br label %cond_next
    253
    254 cond_false:
    255 %X.1 = load i32* @H
    256 br label %cond_next
    257
    258 cond_next:
    259 %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
    260 ret i32 %X.01
    261 }
    262
    263
    264
    265

    The mem2reg pass implements the standard "iterated dominance frontier"

    266 algorithm for constructing SSA form and has a number of optimizations that speed
    267 up (very common) degenerate cases. The mem2reg optimization pass is the answer
    268 to dealing with mutable variables, and we highly recommend that you depend on
    269 it. Note that mem2reg only works on variables in certain circumstances:

    270
    271
    272
  • mem2reg is alloca-driven: it looks for allocas and if it can handle them, it
  • 273 promotes them. It does not apply to global variables or heap allocations.
    274
    275
  • mem2reg only looks for alloca instructions in the entry block of the
  • 276 function. Being in the entry block guarantees that the alloca is only executed
    277 once, which makes analysis simpler.
    278
    279
  • mem2reg only promotes allocas whose uses are direct loads and stores. If
  • 280 the address of the stack object is passed to a function, or if any funny pointer
    281 arithmetic is involved, the alloca will not be promoted.
    282
    283
  • mem2reg only works on allocas of
  • 284 href="../LangRef.html#t_classifications">first class
    285 values (such as pointers, scalars and vectors), and only if the array size
    286 of the allocation is 1 (or missing in the .ll file). mem2reg is not capable of
    287 promoting structs or arrays to registers. Note that the "scalarrepl" pass is
    288 more powerful and can promote structs, "unions", and arrays in many cases.
    289
    290
    291
    292