[llvm] r274441 - New Kaleidoscope chapter: Creating object files
Wilfred Hughes via llvm-commits
llvm-commits at lists.llvm.org
Sat Jul 2 10:02:00 PDT 2016
Author: wilfred
Date: Sat Jul 2 12:01:59 2016
New Revision: 274441
URL: http://llvm.org/viewvc/llvm-project?rev=274441&view=rev
Log:
New Kaleidoscope chapter: Creating object files
This new chapter describes compiling LLVM IR to object files.
The new chaper is chapter 8, so later chapters have been renumbered.
Since this brings us to 10 chapters total, I've also needed to rename
the other chapters to use two digit numbering.
Differential Revision: http://reviews.llvm.org/D18070
Added:
llvm/trunk/docs/tutorial/LangImpl01.rst
llvm/trunk/docs/tutorial/LangImpl02.rst
llvm/trunk/docs/tutorial/LangImpl03.rst
llvm/trunk/docs/tutorial/LangImpl04.rst
llvm/trunk/docs/tutorial/LangImpl05-cfg.png (with props)
llvm/trunk/docs/tutorial/LangImpl05.rst
llvm/trunk/docs/tutorial/LangImpl06.rst
llvm/trunk/docs/tutorial/LangImpl07.rst
llvm/trunk/docs/tutorial/LangImpl08.rst
llvm/trunk/docs/tutorial/LangImpl09.rst
llvm/trunk/docs/tutorial/LangImpl10.rst
llvm/trunk/examples/Kaleidoscope/Chapter9/
llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt
llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp
Removed:
llvm/trunk/docs/tutorial/LangImpl1.rst
llvm/trunk/docs/tutorial/LangImpl2.rst
llvm/trunk/docs/tutorial/LangImpl3.rst
llvm/trunk/docs/tutorial/LangImpl4.rst
llvm/trunk/docs/tutorial/LangImpl5-cfg.png
llvm/trunk/docs/tutorial/LangImpl5.rst
llvm/trunk/docs/tutorial/LangImpl6.rst
llvm/trunk/docs/tutorial/LangImpl7.rst
llvm/trunk/docs/tutorial/LangImpl8.rst
llvm/trunk/docs/tutorial/LangImpl9.rst
Modified:
llvm/trunk/docs/tutorial/OCamlLangImpl5.rst
llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt
llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp
Added: llvm/trunk/docs/tutorial/LangImpl01.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl01.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl01.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl01.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,293 @@
+=================================================
+Kaleidoscope: Tutorial Introduction and the Lexer
+=================================================
+
+.. contents::
+ :local:
+
+Tutorial Introduction
+=====================
+
+Welcome to the "Implementing a language with LLVM" tutorial. This
+tutorial runs through the implementation of a simple language, showing
+how fun and easy it can be. This tutorial will get you up and started as
+well as help to build a framework you can extend to other languages. The
+code in this tutorial can also be used as a playground to hack on other
+LLVM specific things.
+
+The goal of this tutorial is to progressively unveil our language,
+describing how it is built up over time. This will let us cover a fairly
+broad range of language design and LLVM-specific usage issues, showing
+and explaining the code for it all along the way, without overwhelming
+you with tons of details up front.
+
+It is useful to point out ahead of time that this tutorial is really
+about teaching compiler techniques and LLVM specifically, *not* about
+teaching modern and sane software engineering principles. In practice,
+this means that we'll take a number of shortcuts to simplify the
+exposition. For example, the code uses global variables
+all over the place, doesn't use nice design patterns like
+`visitors <http://en.wikipedia.org/wiki/Visitor_pattern>`_, etc... but
+it is very simple. If you dig in and use the code as a basis for future
+projects, fixing these deficiencies shouldn't be hard.
+
+I've tried to put this tutorial together in a way that makes chapters
+easy to skip over if you are already familiar with or are uninterested
+in the various pieces. The structure of the tutorial is:
+
+- `Chapter #1 <#language>`_: Introduction to the Kaleidoscope
+ language, and the definition of its Lexer - This shows where we are
+ going and the basic functionality that we want it to do. In order to
+ make this tutorial maximally understandable and hackable, we choose
+ to implement everything in C++ instead of using lexer and parser
+ generators. LLVM obviously works just fine with such tools, feel free
+ to use one if you prefer.
+- `Chapter #2 <LangImpl02.html>`_: Implementing a Parser and AST -
+ With the lexer in place, we can talk about parsing techniques and
+ basic AST construction. This tutorial describes recursive descent
+ parsing and operator precedence parsing. Nothing in Chapters 1 or 2
+ is LLVM-specific, the code doesn't even link in LLVM at this point.
+ :)
+- `Chapter #3 <LangImpl03.html>`_: Code generation to LLVM IR - With
+ the AST ready, we can show off how easy generation of LLVM IR really
+ is.
+- `Chapter #4 <LangImpl04.html>`_: Adding JIT and Optimizer Support
+ - Because a lot of people are interested in using LLVM as a JIT,
+ we'll dive right into it and show you the 3 lines it takes to add JIT
+ support. LLVM is also useful in many other ways, but this is one
+ simple and "sexy" way to show off its power. :)
+- `Chapter #5 <LangImpl05.html>`_: Extending the Language: Control
+ Flow - With the language up and running, we show how to extend it
+ with control flow operations (if/then/else and a 'for' loop). This
+ gives us a chance to talk about simple SSA construction and control
+ flow.
+- `Chapter #6 <LangImpl06.html>`_: Extending the Language:
+ User-defined Operators - This is a silly but fun chapter that talks
+ about extending the language to let the user program define their own
+ arbitrary unary and binary operators (with assignable precedence!).
+ This lets us build a significant piece of the "language" as library
+ routines.
+- `Chapter #7 <LangImpl07.html>`_: Extending the Language: Mutable
+ Variables - This chapter talks about adding user-defined local
+ variables along with an assignment operator. The interesting part
+ about this is how easy and trivial it is to construct SSA form in
+ LLVM: no, LLVM does *not* require your front-end to construct SSA
+ form!
+- `Chapter #8 <LangImpl08.html>`_: Compiling to Object Files - This
+ chapter explains how to take LLVM IR and compile it down to object
+ files.
+- `Chapter #9 <LangImpl09.html>`_: Extending the Language: Debug
+ Information - Having built a decent little programming language with
+ control flow, functions and mutable variables, we consider what it
+ takes to add debug information to standalone executables. This debug
+ information will allow you to set breakpoints in Kaleidoscope
+ functions, print out argument variables, and call functions - all
+ from within the debugger!
+- `Chapter #10 <LangImpl10.html>`_: Conclusion and other useful LLVM
+ tidbits - This chapter wraps up the series by talking about
+ potential ways to extend the language, but also includes a bunch of
+ pointers to info about "special topics" like adding garbage
+ collection support, exceptions, debugging, support for "spaghetti
+ stacks", and a bunch of other tips and tricks.
+
+By the end of the tutorial, we'll have written a bit less than 1000 lines
+of non-comment, non-blank, lines of code. With this small amount of
+code, we'll have built up a very reasonable compiler for a non-trivial
+language including a hand-written lexer, parser, AST, as well as code
+generation support with a JIT compiler. While other systems may have
+interesting "hello world" tutorials, I think the breadth of this
+tutorial is a great testament to the strengths of LLVM and why you
+should consider it if you're interested in language or compiler design.
+
+A note about this tutorial: we expect you to extend the language and
+play with it on your own. Take the code and go crazy hacking away at it,
+compilers don't need to be scary creatures - it can be a lot of fun to
+play with languages!
+
+The Basic Language
+==================
+
+This tutorial will be illustrated with a toy language that we'll call
+"`Kaleidoscope <http://en.wikipedia.org/wiki/Kaleidoscope>`_" (derived
+from "meaning beautiful, form, and view"). Kaleidoscope is a procedural
+language that allows you to define functions, use conditionals, math,
+etc. Over the course of the tutorial, we'll extend Kaleidoscope to
+support the if/then/else construct, a for loop, user defined operators,
+JIT compilation with a simple command line interface, etc.
+
+Because we want to keep things simple, the only datatype in Kaleidoscope
+is a 64-bit floating point type (aka 'double' in C parlance). As such,
+all values are implicitly double precision and the language doesn't
+require type declarations. This gives the language a very nice and
+simple syntax. For example, the following simple example computes
+`Fibonacci numbers: <http://en.wikipedia.org/wiki/Fibonacci_number>`_
+
+::
+
+ # Compute the x'th fibonacci number.
+ def fib(x)
+ if x < 3 then
+ 1
+ else
+ fib(x-1)+fib(x-2)
+
+ # This expression will compute the 40th number.
+ fib(40)
+
+We also allow Kaleidoscope to call into standard library functions (the
+LLVM JIT makes this completely trivial). This means that you can use the
+'extern' keyword to define a function before you use it (this is also
+useful for mutually recursive functions). For example:
+
+::
+
+ extern sin(arg);
+ extern cos(arg);
+ extern atan2(arg1 arg2);
+
+ atan2(sin(.4), cos(42))
+
+A more interesting example is included in Chapter 6 where we write a
+little Kaleidoscope application that `displays a Mandelbrot
+Set <LangImpl06.html#kicking-the-tires>`_ at various levels of magnification.
+
+Lets dive into the implementation of this language!
+
+The Lexer
+=========
+
+When it comes to implementing a language, the first thing needed is the
+ability to process a text file and recognize what it says. The
+traditional way to do this is to use a
+"`lexer <http://en.wikipedia.org/wiki/Lexical_analysis>`_" (aka
+'scanner') to break the input up into "tokens". Each token returned by
+the lexer includes a token code and potentially some metadata (e.g. the
+numeric value of a number). First, we define the possibilities:
+
+.. code-block:: c++
+
+ // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
+ // of these for known things.
+ enum Token {
+ tok_eof = -1,
+
+ // commands
+ tok_def = -2,
+ tok_extern = -3,
+
+ // primary
+ tok_identifier = -4,
+ tok_number = -5,
+ };
+
+ static std::string IdentifierStr; // Filled in if tok_identifier
+ static double NumVal; // Filled in if tok_number
+
+Each token returned by our lexer will either be one of the Token enum
+values or it will be an 'unknown' character like '+', which is returned
+as its ASCII value. If the current token is an identifier, the
+``IdentifierStr`` global variable holds the name of the identifier. If
+the current token is a numeric literal (like 1.0), ``NumVal`` holds its
+value. Note that we use global variables for simplicity, this is not the
+best choice for a real language implementation :).
+
+The actual implementation of the lexer is a single function named
+``gettok``. The ``gettok`` function is called to return the next token
+from standard input. Its definition starts as:
+
+.. code-block:: c++
+
+ /// gettok - Return the next token from standard input.
+ static int gettok() {
+ static int LastChar = ' ';
+
+ // Skip any whitespace.
+ while (isspace(LastChar))
+ LastChar = getchar();
+
+``gettok`` works by calling the C ``getchar()`` function to read
+characters one at a time from standard input. It eats them as it
+recognizes them and stores the last character read, but not processed,
+in LastChar. The first thing that it has to do is ignore whitespace
+between tokens. This is accomplished with the loop above.
+
+The next thing ``gettok`` needs to do is recognize identifiers and
+specific keywords like "def". Kaleidoscope does this with this simple
+loop:
+
+.. code-block:: c++
+
+ if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
+ IdentifierStr = LastChar;
+ while (isalnum((LastChar = getchar())))
+ IdentifierStr += LastChar;
+
+ if (IdentifierStr == "def")
+ return tok_def;
+ if (IdentifierStr == "extern")
+ return tok_extern;
+ return tok_identifier;
+ }
+
+Note that this code sets the '``IdentifierStr``' global whenever it
+lexes an identifier. Also, since language keywords are matched by the
+same loop, we handle them here inline. Numeric values are similar:
+
+.. code-block:: c++
+
+ if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
+ std::string NumStr;
+ do {
+ NumStr += LastChar;
+ LastChar = getchar();
+ } while (isdigit(LastChar) || LastChar == '.');
+
+ NumVal = strtod(NumStr.c_str(), 0);
+ return tok_number;
+ }
+
+This is all pretty straight-forward code for processing input. When
+reading a numeric value from input, we use the C ``strtod`` function to
+convert it to a numeric value that we store in ``NumVal``. Note that
+this isn't doing sufficient error checking: it will incorrectly read
+"1.23.45.67" and handle it as if you typed in "1.23". Feel free to
+extend it :). Next we handle comments:
+
+.. code-block:: c++
+
+ if (LastChar == '#') {
+ // Comment until end of line.
+ do
+ LastChar = getchar();
+ while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
+
+ if (LastChar != EOF)
+ return gettok();
+ }
+
+We handle comments by skipping to the end of the line and then return
+the next token. Finally, if the input doesn't match one of the above
+cases, it is either an operator character like '+' or the end of the
+file. These are handled with this code:
+
+.. code-block:: c++
+
+ // Check for end of file. Don't eat the EOF.
+ if (LastChar == EOF)
+ return tok_eof;
+
+ // Otherwise, just return the character as its ascii value.
+ int ThisChar = LastChar;
+ LastChar = getchar();
+ return ThisChar;
+ }
+
+With this, we have the complete lexer for the basic Kaleidoscope
+language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer
+is available in the `next chapter <LangImpl02.html>`_ of the tutorial).
+Next we'll `build a simple parser that uses this to build an Abstract
+Syntax Tree <LangImpl02.html>`_. When we have that, we'll include a
+driver so that you can use the lexer and parser together.
+
+`Next: Implementing a Parser and AST <LangImpl02.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl02.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl02.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl02.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl02.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,735 @@
+===========================================
+Kaleidoscope: Implementing a Parser and AST
+===========================================
+
+.. contents::
+ :local:
+
+Chapter 2 Introduction
+======================
+
+Welcome to Chapter 2 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. This chapter shows you how to use the
+lexer, built in `Chapter 1 <LangImpl1.html>`_, to build a full
+`parser <http://en.wikipedia.org/wiki/Parsing>`_ for our Kaleidoscope
+language. Once we have a parser, we'll define and build an `Abstract
+Syntax Tree <http://en.wikipedia.org/wiki/Abstract_syntax_tree>`_ (AST).
+
+The parser we will build uses a combination of `Recursive Descent
+Parsing <http://en.wikipedia.org/wiki/Recursive_descent_parser>`_ and
+`Operator-Precedence
+Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_ to
+parse the Kaleidoscope language (the latter for binary expressions and
+the former for everything else). Before we get to parsing though, lets
+talk about the output of the parser: the Abstract Syntax Tree.
+
+The Abstract Syntax Tree (AST)
+==============================
+
+The AST for a program captures its behavior in such a way that it is
+easy for later stages of the compiler (e.g. code generation) to
+interpret. We basically want one object for each construct in the
+language, and the AST should closely model the language. In
+Kaleidoscope, we have expressions, a prototype, and a function object.
+We'll start with expressions first:
+
+.. code-block:: c++
+
+ /// ExprAST - Base class for all expression nodes.
+ class ExprAST {
+ public:
+ virtual ~ExprAST() {}
+ };
+
+ /// NumberExprAST - Expression class for numeric literals like "1.0".
+ class NumberExprAST : public ExprAST {
+ double Val;
+
+ public:
+ NumberExprAST(double Val) : Val(Val) {}
+ };
+
+The code above shows the definition of the base ExprAST class and one
+subclass which we use for numeric literals. The important thing to note
+about this code is that the NumberExprAST class captures the numeric
+value of the literal as an instance variable. This allows later phases
+of the compiler to know what the stored numeric value is.
+
+Right now we only create the AST, so there are no useful accessor
+methods on them. It would be very easy to add a virtual method to pretty
+print the code, for example. Here are the other expression AST node
+definitions that we'll use in the basic form of the Kaleidoscope
+language:
+
+.. code-block:: c++
+
+ /// VariableExprAST - Expression class for referencing a variable, like "a".
+ class VariableExprAST : public ExprAST {
+ std::string Name;
+
+ public:
+ VariableExprAST(const std::string &Name) : Name(Name) {}
+ };
+
+ /// BinaryExprAST - Expression class for a binary operator.
+ class BinaryExprAST : public ExprAST {
+ char Op;
+ std::unique_ptr<ExprAST> LHS, RHS;
+
+ public:
+ BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,
+ std::unique_ptr<ExprAST> RHS)
+ : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
+ };
+
+ /// CallExprAST - Expression class for function calls.
+ class CallExprAST : public ExprAST {
+ std::string Callee;
+ std::vector<std::unique_ptr<ExprAST>> Args;
+
+ public:
+ CallExprAST(const std::string &Callee,
+ std::vector<std::unique_ptr<ExprAST>> Args)
+ : Callee(Callee), Args(std::move(Args)) {}
+ };
+
+This is all (intentionally) rather straight-forward: variables capture
+the variable name, binary operators capture their opcode (e.g. '+'), and
+calls capture a function name as well as a list of any argument
+expressions. One thing that is nice about our AST is that it captures
+the language features without talking about the syntax of the language.
+Note that there is no discussion about precedence of binary operators,
+lexical structure, etc.
+
+For our basic language, these are all of the expression nodes we'll
+define. Because it doesn't have conditional control flow, it isn't
+Turing-complete; we'll fix that in a later installment. The two things
+we need next are a way to talk about the interface to a function, and a
+way to talk about functions themselves:
+
+.. code-block:: c++
+
+ /// PrototypeAST - This class represents the "prototype" for a function,
+ /// which captures its name, and its argument names (thus implicitly the number
+ /// of arguments the function takes).
+ class PrototypeAST {
+ std::string Name;
+ std::vector<std::string> Args;
+
+ public:
+ PrototypeAST(const std::string &name, std::vector<std::string> Args)
+ : Name(name), Args(std::move(Args)) {}
+ };
+
+ /// FunctionAST - This class represents a function definition itself.
+ class FunctionAST {
+ std::unique_ptr<PrototypeAST> Proto;
+ std::unique_ptr<ExprAST> Body;
+
+ public:
+ FunctionAST(std::unique_ptr<PrototypeAST> Proto,
+ std::unique_ptr<ExprAST> Body)
+ : Proto(std::move(Proto)), Body(std::move(Body)) {}
+ };
+
+In Kaleidoscope, functions are typed with just a count of their
+arguments. Since all values are double precision floating point, the
+type of each argument doesn't need to be stored anywhere. In a more
+aggressive and realistic language, the "ExprAST" class would probably
+have a type field.
+
+With this scaffolding, we can now talk about parsing expressions and
+function bodies in Kaleidoscope.
+
+Parser Basics
+=============
+
+Now that we have an AST to build, we need to define the parser code to
+build it. The idea here is that we want to parse something like "x+y"
+(which is returned as three tokens by the lexer) into an AST that could
+be generated with calls like this:
+
+.. code-block:: c++
+
+ auto LHS = llvm::make_unique<VariableExprAST>("x");
+ auto RHS = llvm::make_unique<VariableExprAST>("y");
+ auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),
+ std::move(RHS));
+
+In order to do this, we'll start by defining some basic helper routines:
+
+.. code-block:: c++
+
+ /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
+ /// token the parser is looking at. getNextToken reads another token from the
+ /// lexer and updates CurTok with its results.
+ static int CurTok;
+ static int getNextToken() {
+ return CurTok = gettok();
+ }
+
+This implements a simple token buffer around the lexer. This allows us
+to look one token ahead at what the lexer is returning. Every function
+in our parser will assume that CurTok is the current token that needs to
+be parsed.
+
+.. code-block:: c++
+
+
+ /// LogError* - These are little helper functions for error handling.
+ std::unique_ptr<ExprAST> LogError(const char *Str) {
+ fprintf(stderr, "LogError: %s\n", Str);
+ return nullptr;
+ }
+ std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
+ LogError(Str);
+ return nullptr;
+ }
+
+The ``LogError`` routines are simple helper routines that our parser will
+use to handle errors. The error recovery in our parser will not be the
+best and is not particular user-friendly, but it will be enough for our
+tutorial. These routines make it easier to handle errors in routines
+that have various return types: they always return null.
+
+With these basic helper functions, we can implement the first piece of
+our grammar: numeric literals.
+
+Basic Expression Parsing
+========================
+
+We start with numeric literals, because they are the simplest to
+process. For each production in our grammar, we'll define a function
+which parses that production. For numeric literals, we have:
+
+.. code-block:: c++
+
+ /// numberexpr ::= number
+ static std::unique_ptr<ExprAST> ParseNumberExpr() {
+ auto Result = llvm::make_unique<NumberExprAST>(NumVal);
+ getNextToken(); // consume the number
+ return std::move(Result);
+ }
+
+This routine is very simple: it expects to be called when the current
+token is a ``tok_number`` token. It takes the current number value,
+creates a ``NumberExprAST`` node, advances the lexer to the next token,
+and finally returns.
+
+There are some interesting aspects to this. The most important one is
+that this routine eats all of the tokens that correspond to the
+production and returns the lexer buffer with the next token (which is
+not part of the grammar production) ready to go. This is a fairly
+standard way to go for recursive descent parsers. For a better example,
+the parenthesis operator is defined like this:
+
+.. code-block:: c++
+
+ /// parenexpr ::= '(' expression ')'
+ static std::unique_ptr<ExprAST> ParseParenExpr() {
+ getNextToken(); // eat (.
+ auto V = ParseExpression();
+ if (!V)
+ return nullptr;
+
+ if (CurTok != ')')
+ return LogError("expected ')'");
+ getNextToken(); // eat ).
+ return V;
+ }
+
+This function illustrates a number of interesting things about the
+parser:
+
+1) It shows how we use the LogError routines. When called, this function
+expects that the current token is a '(' token, but after parsing the
+subexpression, it is possible that there is no ')' waiting. For example,
+if the user types in "(4 x" instead of "(4)", the parser should emit an
+error. Because errors can occur, the parser needs a way to indicate that
+they happened: in our parser, we return null on an error.
+
+2) Another interesting aspect of this function is that it uses recursion
+by calling ``ParseExpression`` (we will soon see that
+``ParseExpression`` can call ``ParseParenExpr``). This is powerful
+because it allows us to handle recursive grammars, and keeps each
+production very simple. Note that parentheses do not cause construction
+of AST nodes themselves. While we could do it this way, the most
+important role of parentheses are to guide the parser and provide
+grouping. Once the parser constructs the AST, parentheses are not
+needed.
+
+The next simple production is for handling variable references and
+function calls:
+
+.. code-block:: c++
+
+ /// identifierexpr
+ /// ::= identifier
+ /// ::= identifier '(' expression* ')'
+ static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
+ std::string IdName = IdentifierStr;
+
+ getNextToken(); // eat identifier.
+
+ if (CurTok != '(') // Simple variable ref.
+ return llvm::make_unique<VariableExprAST>(IdName);
+
+ // Call.
+ getNextToken(); // eat (
+ std::vector<std::unique_ptr<ExprAST>> Args;
+ if (CurTok != ')') {
+ while (1) {
+ if (auto Arg = ParseExpression())
+ Args.push_back(std::move(Arg));
+ else
+ return nullptr;
+
+ if (CurTok == ')')
+ break;
+
+ if (CurTok != ',')
+ return LogError("Expected ')' or ',' in argument list");
+ getNextToken();
+ }
+ }
+
+ // Eat the ')'.
+ getNextToken();
+
+ return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
+ }
+
+This routine follows the same style as the other routines. (It expects
+to be called if the current token is a ``tok_identifier`` token). It
+also has recursion and error handling. One interesting aspect of this is
+that it uses *look-ahead* to determine if the current identifier is a
+stand alone variable reference or if it is a function call expression.
+It handles this by checking to see if the token after the identifier is
+a '(' token, constructing either a ``VariableExprAST`` or
+``CallExprAST`` node as appropriate.
+
+Now that we have all of our simple expression-parsing logic in place, we
+can define a helper function to wrap it together into one entry point.
+We call this class of expressions "primary" expressions, for reasons
+that will become more clear `later in the
+tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary
+primary expression, we need to determine what sort of expression it is:
+
+.. code-block:: c++
+
+ /// primary
+ /// ::= identifierexpr
+ /// ::= numberexpr
+ /// ::= parenexpr
+ static std::unique_ptr<ExprAST> ParsePrimary() {
+ switch (CurTok) {
+ default:
+ return LogError("unknown token when expecting an expression");
+ case tok_identifier:
+ return ParseIdentifierExpr();
+ case tok_number:
+ return ParseNumberExpr();
+ case '(':
+ return ParseParenExpr();
+ }
+ }
+
+Now that you see the definition of this function, it is more obvious why
+we can assume the state of CurTok in the various functions. This uses
+look-ahead to determine which sort of expression is being inspected, and
+then parses it with a function call.
+
+Now that basic expressions are handled, we need to handle binary
+expressions. They are a bit more complex.
+
+Binary Expression Parsing
+=========================
+
+Binary expressions are significantly harder to parse because they are
+often ambiguous. For example, when given the string "x+y\*z", the parser
+can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
+definitions from mathematics, we expect the later parse, because "\*"
+(multiplication) has higher *precedence* than "+" (addition).
+
+There are many ways to handle this, but an elegant and efficient way is
+to use `Operator-Precedence
+Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_.
+This parsing technique uses the precedence of binary operators to guide
+recursion. To start with, we need a table of precedences:
+
+.. code-block:: c++
+
+ /// BinopPrecedence - This holds the precedence for each binary operator that is
+ /// defined.
+ static std::map<char, int> BinopPrecedence;
+
+ /// GetTokPrecedence - Get the precedence of the pending binary operator token.
+ static int GetTokPrecedence() {
+ if (!isascii(CurTok))
+ return -1;
+
+ // Make sure it's a declared binop.
+ int TokPrec = BinopPrecedence[CurTok];
+ if (TokPrec <= 0) return -1;
+ return TokPrec;
+ }
+
+ int main() {
+ // Install standard binary operators.
+ // 1 is lowest precedence.
+ BinopPrecedence['<'] = 10;
+ BinopPrecedence['+'] = 20;
+ BinopPrecedence['-'] = 20;
+ BinopPrecedence['*'] = 40; // highest.
+ ...
+ }
+
+For the basic form of Kaleidoscope, we will only support 4 binary
+operators (this can obviously be extended by you, our brave and intrepid
+reader). The ``GetTokPrecedence`` function returns the precedence for
+the current token, or -1 if the token is not a binary operator. Having a
+map makes it easy to add new operators and makes it clear that the
+algorithm doesn't depend on the specific operators involved, but it
+would be easy enough to eliminate the map and do the comparisons in the
+``GetTokPrecedence`` function. (Or just use a fixed-size array).
+
+With the helper above defined, we can now start parsing binary
+expressions. The basic idea of operator precedence parsing is to break
+down an expression with potentially ambiguous binary operators into
+pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
+Operator precedence parsing considers this as a stream of primary
+expressions separated by binary operators. As such, it will first parse
+the leading primary expression "a", then it will see the pairs [+, b]
+[+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
+primary expressions, the binary expression parser doesn't need to worry
+about nested subexpressions like (c+d) at all.
+
+To start, an expression is a primary expression potentially followed by
+a sequence of [binop,primaryexpr] pairs:
+
+.. code-block:: c++
+
+ /// expression
+ /// ::= primary binoprhs
+ ///
+ static std::unique_ptr<ExprAST> ParseExpression() {
+ auto LHS = ParsePrimary();
+ if (!LHS)
+ return nullptr;
+
+ return ParseBinOpRHS(0, std::move(LHS));
+ }
+
+``ParseBinOpRHS`` is the function that parses the sequence of pairs for
+us. It takes a precedence and a pointer to an expression for the part
+that has been parsed so far. Note that "x" is a perfectly valid
+expression: As such, "binoprhs" is allowed to be empty, in which case it
+returns the expression that is passed into it. In our example above, the
+code passes the expression for "a" into ``ParseBinOpRHS`` and the
+current token is "+".
+
+The precedence value passed into ``ParseBinOpRHS`` indicates the
+*minimal operator precedence* that the function is allowed to eat. For
+example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
+passed in a precedence of 40, it will not consume any tokens (because
+the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
+starts with:
+
+.. code-block:: c++
+
+ /// binoprhs
+ /// ::= ('+' primary)*
+ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
+ std::unique_ptr<ExprAST> LHS) {
+ // If this is a binop, find its precedence.
+ while (1) {
+ int TokPrec = GetTokPrecedence();
+
+ // If this is a binop that binds at least as tightly as the current binop,
+ // consume it, otherwise we are done.
+ if (TokPrec < ExprPrec)
+ return LHS;
+
+This code gets the precedence of the current token and checks to see if
+if is too low. Because we defined invalid tokens to have a precedence of
+-1, this check implicitly knows that the pair-stream ends when the token
+stream runs out of binary operators. If this check succeeds, we know
+that the token is a binary operator and that it will be included in this
+expression:
+
+.. code-block:: c++
+
+ // Okay, we know this is a binop.
+ int BinOp = CurTok;
+ getNextToken(); // eat binop
+
+ // Parse the primary expression after the binary operator.
+ auto RHS = ParsePrimary();
+ if (!RHS)
+ return nullptr;
+
+As such, this code eats (and remembers) the binary operator and then
+parses the primary expression that follows. This builds up the whole
+pair, the first of which is [+, b] for the running example.
+
+Now that we parsed the left-hand side of an expression and one pair of
+the RHS sequence, we have to decide which way the expression associates.
+In particular, we could have "(a+b) binop unparsed" or "a + (b binop
+unparsed)". To determine this, we look ahead at "binop" to determine its
+precedence and compare it to BinOp's precedence (which is '+' in this
+case):
+
+.. code-block:: c++
+
+ // If BinOp binds less tightly with RHS than the operator after RHS, let
+ // the pending operator take RHS as its LHS.
+ int NextPrec = GetTokPrecedence();
+ if (TokPrec < NextPrec) {
+
+If the precedence of the binop to the right of "RHS" is lower or equal
+to the precedence of our current operator, then we know that the
+parentheses associate as "(a+b) binop ...". In our example, the current
+operator is "+" and the next operator is "+", we know that they have the
+same precedence. In this case we'll create the AST node for "a+b", and
+then continue parsing:
+
+.. code-block:: c++
+
+ ... if body omitted ...
+ }
+
+ // Merge LHS/RHS.
+ LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
+ std::move(RHS));
+ } // loop around to the top of the while loop.
+ }
+
+In our example above, this will turn "a+b+" into "(a+b)" and execute the
+next iteration of the loop, with "+" as the current token. The code
+above will eat, remember, and parse "(c+d)" as the primary expression,
+which makes the current pair equal to [+, (c+d)]. It will then evaluate
+the 'if' conditional above with "\*" as the binop to the right of the
+primary. In this case, the precedence of "\*" is higher than the
+precedence of "+" so the if condition will be entered.
+
+The critical question left here is "how can the if condition parse the
+right hand side in full"? In particular, to build the AST correctly for
+our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
+variable. The code to do this is surprisingly simple (code from the
+above two blocks duplicated for context):
+
+.. code-block:: c++
+
+ // If BinOp binds less tightly with RHS than the operator after RHS, let
+ // the pending operator take RHS as its LHS.
+ int NextPrec = GetTokPrecedence();
+ if (TokPrec < NextPrec) {
+ RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
+ if (!RHS)
+ return nullptr;
+ }
+ // Merge LHS/RHS.
+ LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
+ std::move(RHS));
+ } // loop around to the top of the while loop.
+ }
+
+At this point, we know that the binary operator to the RHS of our
+primary has higher precedence than the binop we are currently parsing.
+As such, we know that any sequence of pairs whose operators are all
+higher precedence than "+" should be parsed together and returned as
+"RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
+specifying "TokPrec+1" as the minimum precedence required for it to
+continue. In our example above, this will cause it to return the AST
+node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'
+expression.
+
+Finally, on the next iteration of the while loop, the "+g" piece is
+parsed and added to the AST. With this little bit of code (14
+non-trivial lines), we correctly handle fully general binary expression
+parsing in a very elegant way. This was a whirlwind tour of this code,
+and it is somewhat subtle. I recommend running through it with a few
+tough examples to see how it works.
+
+This wraps up handling of expressions. At this point, we can point the
+parser at an arbitrary token stream and build an expression from it,
+stopping at the first token that is not part of the expression. Next up
+we need to handle function definitions, etc.
+
+Parsing the Rest
+================
+
+The next thing missing is handling of function prototypes. In
+Kaleidoscope, these are used both for 'extern' function declarations as
+well as function body definitions. The code to do this is
+straight-forward and not very interesting (once you've survived
+expressions):
+
+.. code-block:: c++
+
+ /// prototype
+ /// ::= id '(' id* ')'
+ static std::unique_ptr<PrototypeAST> ParsePrototype() {
+ if (CurTok != tok_identifier)
+ return LogErrorP("Expected function name in prototype");
+
+ std::string FnName = IdentifierStr;
+ getNextToken();
+
+ if (CurTok != '(')
+ return LogErrorP("Expected '(' in prototype");
+
+ // Read the list of argument names.
+ std::vector<std::string> ArgNames;
+ while (getNextToken() == tok_identifier)
+ ArgNames.push_back(IdentifierStr);
+ if (CurTok != ')')
+ return LogErrorP("Expected ')' in prototype");
+
+ // success.
+ getNextToken(); // eat ')'.
+
+ return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
+ }
+
+Given this, a function definition is very simple, just a prototype plus
+an expression to implement the body:
+
+.. code-block:: c++
+
+ /// definition ::= 'def' prototype expression
+ static std::unique_ptr<FunctionAST> ParseDefinition() {
+ getNextToken(); // eat def.
+ auto Proto = ParsePrototype();
+ if (!Proto) return nullptr;
+
+ if (auto E = ParseExpression())
+ return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+ return nullptr;
+ }
+
+In addition, we support 'extern' to declare functions like 'sin' and
+'cos' as well as to support forward declaration of user functions. These
+'extern's are just prototypes with no body:
+
+.. code-block:: c++
+
+ /// external ::= 'extern' prototype
+ static std::unique_ptr<PrototypeAST> ParseExtern() {
+ getNextToken(); // eat extern.
+ return ParsePrototype();
+ }
+
+Finally, we'll also let the user type in arbitrary top-level expressions
+and evaluate them on the fly. We will handle this by defining anonymous
+nullary (zero argument) functions for them:
+
+.. code-block:: c++
+
+ /// toplevelexpr ::= expression
+ static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
+ if (auto E = ParseExpression()) {
+ // Make an anonymous proto.
+ auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
+ return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+ }
+ return nullptr;
+ }
+
+Now that we have all the pieces, let's build a little driver that will
+let us actually *execute* this code we've built!
+
+The Driver
+==========
+
+The driver for this simply invokes all of the parsing pieces with a
+top-level dispatch loop. There isn't much interesting here, so I'll just
+include the top-level loop. See `below <#full-code-listing>`_ for full code in the
+"Top-Level Parsing" section.
+
+.. code-block:: c++
+
+ /// top ::= definition | external | expression | ';'
+ static void MainLoop() {
+ while (1) {
+ fprintf(stderr, "ready> ");
+ switch (CurTok) {
+ case tok_eof:
+ return;
+ case ';': // ignore top-level semicolons.
+ getNextToken();
+ break;
+ case tok_def:
+ HandleDefinition();
+ break;
+ case tok_extern:
+ HandleExtern();
+ break;
+ default:
+ HandleTopLevelExpression();
+ break;
+ }
+ }
+ }
+
+The most interesting part of this is that we ignore top-level
+semicolons. Why is this, you ask? The basic reason is that if you type
+"4 + 5" at the command line, the parser doesn't know whether that is the
+end of what you will type or not. For example, on the next line you
+could type "def foo..." in which case 4+5 is the end of a top-level
+expression. Alternatively you could type "\* 6", which would continue
+the expression. Having top-level semicolons allows you to type "4+5;",
+and the parser will know you are done.
+
+Conclusions
+===========
+
+With just under 400 lines of commented code (240 lines of non-comment,
+non-blank code), we fully defined our minimal language, including a
+lexer, parser, and AST builder. With this done, the executable will
+validate Kaleidoscope code and tell us if it is grammatically invalid.
+For example, here is a sample interaction:
+
+.. code-block:: bash
+
+ $ ./a.out
+ ready> def foo(x y) x+foo(y, 4.0);
+ Parsed a function definition.
+ ready> def foo(x y) x+y y;
+ Parsed a function definition.
+ Parsed a top-level expr
+ ready> def foo(x y) x+y );
+ Parsed a function definition.
+ Error: unknown token when expecting an expression
+ ready> extern sin(a);
+ ready> Parsed an extern
+ ready> ^D
+ $
+
+There is a lot of room for extension here. You can define new AST nodes,
+extend the language in many ways, etc. In the `next
+installment <LangImpl3.html>`_, we will describe how to generate LLVM
+Intermediate Representation (IR) from the AST.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for this and the previous chapter.
+Note that it is fully self-contained: you don't need LLVM or any
+external libraries at all for this. (Besides the C and C++ standard
+libraries, of course.) To build this, just compile with:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g -O3 toy.cpp
+ # Run
+ ./a.out
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp
+ :language: c++
+
+`Next: Implementing Code Generation to LLVM IR <LangImpl03.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl03.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl03.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl03.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl03.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,567 @@
+========================================
+Kaleidoscope: Code generation to LLVM IR
+========================================
+
+.. contents::
+ :local:
+
+Chapter 3 Introduction
+======================
+
+Welcome to Chapter 3 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. This chapter shows you how to transform
+the `Abstract Syntax Tree <LangImpl2.html>`_, built in Chapter 2, into
+LLVM IR. This will teach you a little bit about how LLVM does things, as
+well as demonstrate how easy it is to use. It's much more work to build
+a lexer and parser than it is to generate LLVM IR code. :)
+
+**Please note**: the code in this chapter and later require LLVM 3.7 or
+later. LLVM 3.6 and before will not work with it. Also note that you
+need to use a version of this tutorial that matches your LLVM release:
+If you are using an official LLVM release, use the version of the
+documentation included with your release or on the `llvm.org releases
+page <http://llvm.org/releases/>`_.
+
+Code Generation Setup
+=====================
+
+In order to generate LLVM IR, we want some simple setup to get started.
+First we define virtual code generation (codegen) methods in each AST
+class:
+
+.. code-block:: c++
+
+ /// ExprAST - Base class for all expression nodes.
+ class ExprAST {
+ public:
+ virtual ~ExprAST() {}
+ virtual Value *codegen() = 0;
+ };
+
+ /// NumberExprAST - Expression class for numeric literals like "1.0".
+ class NumberExprAST : public ExprAST {
+ double Val;
+
+ public:
+ NumberExprAST(double Val) : Val(Val) {}
+ virtual Value *codegen();
+ };
+ ...
+
+The codegen() method says to emit IR for that AST node along with all
+the things it depends on, and they all return an LLVM Value object.
+"Value" is the class used to represent a "`Static Single Assignment
+(SSA) <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
+register" or "SSA value" in LLVM. The most distinct aspect of SSA values
+is that their value is computed as the related instruction executes, and
+it does not get a new value until (and if) the instruction re-executes.
+In other words, there is no way to "change" an SSA value. For more
+information, please read up on `Static Single
+Assignment <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
+- the concepts are really quite natural once you grok them.
+
+Note that instead of adding virtual methods to the ExprAST class
+hierarchy, it could also make sense to use a `visitor
+pattern <http://en.wikipedia.org/wiki/Visitor_pattern>`_ or some other
+way to model this. Again, this tutorial won't dwell on good software
+engineering practices: for our purposes, adding a virtual method is
+simplest.
+
+The second thing we want is an "LogError" method like we used for the
+parser, which will be used to report errors found during code generation
+(for example, use of an undeclared parameter):
+
+.. code-block:: c++
+
+ static LLVMContext TheContext;
+ static IRBuilder<> Builder(TheContext);
+ static std::unique_ptr<Module> TheModule;
+ static std::map<std::string, Value *> NamedValues;
+
+ Value *LogErrorV(const char *Str) {
+ LogError(Str);
+ return nullptr;
+ }
+
+The static variables will be used during code generation. ``TheContext``
+is an opaque object that owns a lot of core LLVM data structures, such as
+the type and constant value tables. We don't need to understand it in
+detail, we just need a single instance to pass into APIs that require it.
+
+The ``Builder`` object is a helper object that makes it easy to generate
+LLVM instructions. Instances of the
+`IRBuilder <http://llvm.org/doxygen/IRBuilder_8h-source.html>`_
+class template keep track of the current place to insert instructions
+and has methods to create new instructions.
+
+``TheModule`` is an LLVM construct that contains functions and global
+variables. In many ways, it is the top-level structure that the LLVM IR
+uses to contain code. It will own the memory for all of the IR that we
+generate, which is why the codegen() method returns a raw Value\*,
+rather than a unique_ptr<Value>.
+
+The ``NamedValues`` map keeps track of which values are defined in the
+current scope and what their LLVM representation is. (In other words, it
+is a symbol table for the code). In this form of Kaleidoscope, the only
+things that can be referenced are function parameters. As such, function
+parameters will be in this map when generating code for their function
+body.
+
+With these basics in place, we can start talking about how to generate
+code for each expression. Note that this assumes that the ``Builder``
+has been set up to generate code *into* something. For now, we'll assume
+that this has already been done, and we'll just use it to emit code.
+
+Expression Code Generation
+==========================
+
+Generating LLVM code for expression nodes is very straightforward: less
+than 45 lines of commented code for all four of our expression nodes.
+First we'll do numeric literals:
+
+.. code-block:: c++
+
+ Value *NumberExprAST::codegen() {
+ return ConstantFP::get(LLVMContext, APFloat(Val));
+ }
+
+In the LLVM IR, numeric constants are represented with the
+``ConstantFP`` class, which holds the numeric value in an ``APFloat``
+internally (``APFloat`` has the capability of holding floating point
+constants of Arbitrary Precision). This code basically just creates
+and returns a ``ConstantFP``. Note that in the LLVM IR that constants
+are all uniqued together and shared. For this reason, the API uses the
+"foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
+
+.. code-block:: c++
+
+ Value *VariableExprAST::codegen() {
+ // Look this variable up in the function.
+ Value *V = NamedValues[Name];
+ if (!V)
+ LogErrorV("Unknown variable name");
+ return V;
+ }
+
+References to variables are also quite simple using LLVM. In the simple
+version of Kaleidoscope, we assume that the variable has already been
+emitted somewhere and its value is available. In practice, the only
+values that can be in the ``NamedValues`` map are function arguments.
+This code simply checks to see that the specified name is in the map (if
+not, an unknown variable is being referenced) and returns the value for
+it. In future chapters, we'll add support for `loop induction
+variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local
+variables <LangImpl7.html#user-defined-local-variables>`_.
+
+.. code-block:: c++
+
+ Value *BinaryExprAST::codegen() {
+ Value *L = LHS->codegen();
+ Value *R = RHS->codegen();
+ if (!L || !R)
+ return nullptr;
+
+ switch (Op) {
+ case '+':
+ return Builder.CreateFAdd(L, R, "addtmp");
+ case '-':
+ return Builder.CreateFSub(L, R, "subtmp");
+ case '*':
+ return Builder.CreateFMul(L, R, "multmp");
+ case '<':
+ L = Builder.CreateFCmpULT(L, R, "cmptmp");
+ // Convert bool 0/1 to double 0.0 or 1.0
+ return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
+ "booltmp");
+ default:
+ return LogErrorV("invalid binary operator");
+ }
+ }
+
+Binary operators start to get more interesting. The basic idea here is
+that we recursively emit code for the left-hand side of the expression,
+then the right-hand side, then we compute the result of the binary
+expression. In this code, we do a simple switch on the opcode to create
+the right LLVM instruction.
+
+In the example above, the LLVM builder class is starting to show its
+value. IRBuilder knows where to insert the newly created instruction,
+all you have to do is specify what instruction to create (e.g. with
+``CreateFAdd``), which operands to use (``L`` and ``R`` here) and
+optionally provide a name for the generated instruction.
+
+One nice thing about LLVM is that the name is just a hint. For instance,
+if the code above emits multiple "addtmp" variables, LLVM will
+automatically provide each one with an increasing, unique numeric
+suffix. Local value names for instructions are purely optional, but it
+makes it much easier to read the IR dumps.
+
+`LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict
+rules: for example, the Left and Right operators of an `add
+instruction <../LangRef.html#add-instruction>`_ must have the same type, and the
+result type of the add must match the operand types. Because all values
+in Kaleidoscope are doubles, this makes for very simple code for add,
+sub and mul.
+
+On the other hand, LLVM specifies that the `fcmp
+instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a
+one bit integer). The problem with this is that Kaleidoscope wants the
+value to be a 0.0 or 1.0 value. In order to get these semantics, we
+combine the fcmp instruction with a `uitofp
+instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its
+input integer into a floating point value by treating the input as an
+unsigned value. In contrast, if we used the `sitofp
+instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
+would return 0.0 and -1.0, depending on the input value.
+
+.. code-block:: c++
+
+ Value *CallExprAST::codegen() {
+ // Look up the name in the global module table.
+ Function *CalleeF = TheModule->getFunction(Callee);
+ if (!CalleeF)
+ return LogErrorV("Unknown function referenced");
+
+ // If argument mismatch error.
+ if (CalleeF->arg_size() != Args.size())
+ return LogErrorV("Incorrect # arguments passed");
+
+ std::vector<Value *> ArgsV;
+ for (unsigned i = 0, e = Args.size(); i != e; ++i) {
+ ArgsV.push_back(Args[i]->codegen());
+ if (!ArgsV.back())
+ return nullptr;
+ }
+
+ return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
+ }
+
+Code generation for function calls is quite straightforward with LLVM. The code
+above initially does a function name lookup in the LLVM Module's symbol table.
+Recall that the LLVM Module is the container that holds the functions we are
+JIT'ing. By giving each function the same name as what the user specifies, we
+can use the LLVM symbol table to resolve function names for us.
+
+Once we have the function to call, we recursively codegen each argument
+that is to be passed in, and create an LLVM `call
+instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C
+calling conventions by default, allowing these calls to also call into
+standard library functions like "sin" and "cos", with no additional
+effort.
+
+This wraps up our handling of the four basic expressions that we have so
+far in Kaleidoscope. Feel free to go in and add some more. For example,
+by browsing the `LLVM language reference <../LangRef.html>`_ you'll find
+several other interesting instructions that are really easy to plug into
+our basic framework.
+
+Function Code Generation
+========================
+
+Code generation for prototypes and functions must handle a number of
+details, which make their code less beautiful than expression code
+generation, but allows us to illustrate some important points. First,
+lets talk about code generation for prototypes: they are used both for
+function bodies and external function declarations. The code starts
+with:
+
+.. code-block:: c++
+
+ Function *PrototypeAST::codegen() {
+ // Make the function type: double(double,double) etc.
+ std::vector<Type*> Doubles(Args.size(),
+ Type::getDoubleTy(LLVMContext));
+ FunctionType *FT =
+ FunctionType::get(Type::getDoubleTy(LLVMContext), Doubles, false);
+
+ Function *F =
+ Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
+
+This code packs a lot of power into a few lines. Note first that this
+function returns a "Function\*" instead of a "Value\*". Because a
+"prototype" really talks about the external interface for a function
+(not the value computed by an expression), it makes sense for it to
+return the LLVM Function it corresponds to when codegen'd.
+
+The call to ``FunctionType::get`` creates the ``FunctionType`` that
+should be used for a given Prototype. Since all function arguments in
+Kaleidoscope are of type double, the first line creates a vector of "N"
+LLVM double types. It then uses the ``Functiontype::get`` method to
+create a function type that takes "N" doubles as arguments, returns one
+double as a result, and that is not vararg (the false parameter
+indicates this). Note that Types in LLVM are uniqued just like Constants
+are, so you don't "new" a type, you "get" it.
+
+The final line above actually creates the IR Function corresponding to
+the Prototype. This indicates the type, linkage and name to use, as
+well as which module to insert into. "`external
+linkage <../LangRef.html#linkage>`_" means that the function may be
+defined outside the current module and/or that it is callable by
+functions outside the module. The Name passed in is the name the user
+specified: since "``TheModule``" is specified, this name is registered
+in "``TheModule``"s symbol table.
+
+.. code-block:: c++
+
+ // Set names for all arguments.
+ unsigned Idx = 0;
+ for (auto &Arg : F->args())
+ Arg.setName(Args[Idx++]);
+
+ return F;
+
+Finally, we set the name of each of the function's arguments according to the
+names given in the Prototype. This step isn't strictly necessary, but keeping
+the names consistent makes the IR more readable, and allows subsequent code to
+refer directly to the arguments for their names, rather than having to look up
+them up in the Prototype AST.
+
+At this point we have a function prototype with no body. This is how LLVM IR
+represents function declarations. For extern statements in Kaleidoscope, this
+is as far as we need to go. For function definitions however, we need to
+codegen and attach a function body.
+
+.. code-block:: c++
+
+ Function *FunctionAST::codegen() {
+ // First, check for an existing function from a previous 'extern' declaration.
+ Function *TheFunction = TheModule->getFunction(Proto->getName());
+
+ if (!TheFunction)
+ TheFunction = Proto->codegen();
+
+ if (!TheFunction)
+ return nullptr;
+
+ if (!TheFunction->empty())
+ return (Function*)LogErrorV("Function cannot be redefined.");
+
+
+For function definitions, we start by searching TheModule's symbol table for an
+existing version of this function, in case one has already been created using an
+'extern' statement. If Module::getFunction returns null then no previous version
+exists, so we'll codegen one from the Prototype. In either case, we want to
+assert that the function is empty (i.e. has no body yet) before we start.
+
+.. code-block:: c++
+
+ // Create a new basic block to start insertion into.
+ BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
+ Builder.SetInsertPoint(BB);
+
+ // Record the function arguments in the NamedValues map.
+ NamedValues.clear();
+ for (auto &Arg : TheFunction->args())
+ NamedValues[Arg.getName()] = &Arg;
+
+Now we get to the point where the ``Builder`` is set up. The first line
+creates a new `basic block <http://en.wikipedia.org/wiki/Basic_block>`_
+(named "entry"), which is inserted into ``TheFunction``. The second line
+then tells the builder that new instructions should be inserted into the
+end of the new basic block. Basic blocks in LLVM are an important part
+of functions that define the `Control Flow
+Graph <http://en.wikipedia.org/wiki/Control_flow_graph>`_. Since we
+don't have any control flow, our functions will only contain one block
+at this point. We'll fix this in `Chapter 5 <LangImpl5.html>`_ :).
+
+Next we add the function arguments to the NamedValues map (after first clearing
+it out) so that they're accessible to ``VariableExprAST`` nodes.
+
+.. code-block:: c++
+
+ if (Value *RetVal = Body->codegen()) {
+ // Finish off the function.
+ Builder.CreateRet(RetVal);
+
+ // Validate the generated code, checking for consistency.
+ verifyFunction(*TheFunction);
+
+ return TheFunction;
+ }
+
+Once the insertion point has been set up and the NamedValues map populated,
+we call the ``codegen()`` method for the root expression of the function. If no
+error happens, this emits code to compute the expression into the entry block
+and returns the value that was computed. Assuming no error, we then create an
+LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.
+Once the function is built, we call ``verifyFunction``, which is
+provided by LLVM. This function does a variety of consistency checks on
+the generated code, to determine if our compiler is doing everything
+right. Using this is important: it can catch a lot of bugs. Once the
+function is finished and validated, we return it.
+
+.. code-block:: c++
+
+ // Error reading body, remove function.
+ TheFunction->eraseFromParent();
+ return nullptr;
+ }
+
+The only piece left here is handling of the error case. For simplicity,
+we handle this by merely deleting the function we produced with the
+``eraseFromParent`` method. This allows the user to redefine a function
+that they incorrectly typed in before: if we didn't delete it, it would
+live in the symbol table, with a body, preventing future redefinition.
+
+This code does have a bug, though: If the ``FunctionAST::codegen()`` method
+finds an existing IR Function, it does not validate its signature against the
+definition's own prototype. This means that an earlier 'extern' declaration will
+take precedence over the function definition's signature, which can cause
+codegen to fail, for instance if the function arguments are named differently.
+There are a number of ways to fix this bug, see what you can come up with! Here
+is a testcase:
+
+::
+
+ extern foo(a); # ok, defines foo.
+ def foo(b) b; # Error: Unknown variable name. (decl using 'a' takes precedence).
+
+Driver Changes and Closing Thoughts
+===================================
+
+For now, code generation to LLVM doesn't really get us much, except that
+we can look at the pretty IR calls. The sample code inserts calls to
+codegen into the "``HandleDefinition``", "``HandleExtern``" etc
+functions, and then dumps out the LLVM IR. This gives a nice way to look
+at the LLVM IR for simple functions. For example:
+
+::
+
+ ready> 4+5;
+ Read top-level expression:
+ define double @0() {
+ entry:
+ ret double 9.000000e+00
+ }
+
+Note how the parser turns the top-level expression into anonymous
+functions for us. This will be handy when we add `JIT
+support <LangImpl4.html#adding-a-jit-compiler>`_ in the next chapter. Also note that the
+code is very literally transcribed, no optimizations are being performed
+except simple constant folding done by IRBuilder. We will `add
+optimizations <LangImpl4.html#trivial-constant-folding>`_ explicitly in the next
+chapter.
+
+::
+
+ ready> def foo(a b) a*a + 2*a*b + b*b;
+ Read function definition:
+ define double @foo(double %a, double %b) {
+ entry:
+ %multmp = fmul double %a, %a
+ %multmp1 = fmul double 2.000000e+00, %a
+ %multmp2 = fmul double %multmp1, %b
+ %addtmp = fadd double %multmp, %multmp2
+ %multmp3 = fmul double %b, %b
+ %addtmp4 = fadd double %addtmp, %multmp3
+ ret double %addtmp4
+ }
+
+This shows some simple arithmetic. Notice the striking similarity to the
+LLVM builder calls that we use to create the instructions.
+
+::
+
+ ready> def bar(a) foo(a, 4.0) + bar(31337);
+ Read function definition:
+ define double @bar(double %a) {
+ entry:
+ %calltmp = call double @foo(double %a, double 4.000000e+00)
+ %calltmp1 = call double @bar(double 3.133700e+04)
+ %addtmp = fadd double %calltmp, %calltmp1
+ ret double %addtmp
+ }
+
+This shows some function calls. Note that this function will take a long
+time to execute if you call it. In the future we'll add conditional
+control flow to actually make recursion useful :).
+
+::
+
+ ready> extern cos(x);
+ Read extern:
+ declare double @cos(double)
+
+ ready> cos(1.234);
+ Read top-level expression:
+ define double @1() {
+ entry:
+ %calltmp = call double @cos(double 1.234000e+00)
+ ret double %calltmp
+ }
+
+This shows an extern for the libm "cos" function, and a call to it.
+
+.. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up
+ on highlighting this due to the first line.
+
+::
+
+ ready> ^D
+ ; ModuleID = 'my cool jit'
+
+ define double @0() {
+ entry:
+ %addtmp = fadd double 4.000000e+00, 5.000000e+00
+ ret double %addtmp
+ }
+
+ define double @foo(double %a, double %b) {
+ entry:
+ %multmp = fmul double %a, %a
+ %multmp1 = fmul double 2.000000e+00, %a
+ %multmp2 = fmul double %multmp1, %b
+ %addtmp = fadd double %multmp, %multmp2
+ %multmp3 = fmul double %b, %b
+ %addtmp4 = fadd double %addtmp, %multmp3
+ ret double %addtmp4
+ }
+
+ define double @bar(double %a) {
+ entry:
+ %calltmp = call double @foo(double %a, double 4.000000e+00)
+ %calltmp1 = call double @bar(double 3.133700e+04)
+ %addtmp = fadd double %calltmp, %calltmp1
+ ret double %addtmp
+ }
+
+ declare double @cos(double)
+
+ define double @1() {
+ entry:
+ %calltmp = call double @cos(double 1.234000e+00)
+ ret double %calltmp
+ }
+
+When you quit the current demo, it dumps out the IR for the entire
+module generated. Here you can see the big picture with all the
+functions referencing each other.
+
+This wraps up the third chapter of the Kaleidoscope tutorial. Up next,
+we'll describe how to `add JIT codegen and optimizer
+support <LangImpl4.html>`_ to this so we can actually start running
+code!
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+the LLVM code generator. Because this uses the LLVM libraries, we need
+to link them in. To do this, we use the
+`llvm-config <http://llvm.org/cmds/llvm-config.html>`_ tool to inform
+our makefile/command line about which options to use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy
+ # Run
+ ./toy
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp
+ :language: c++
+
+`Next: Adding JIT and Optimizer Support <LangImpl04.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl04.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl04.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl04.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl04.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,610 @@
+==============================================
+Kaleidoscope: Adding JIT and Optimizer Support
+==============================================
+
+.. contents::
+ :local:
+
+Chapter 4 Introduction
+======================
+
+Welcome to Chapter 4 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. Chapters 1-3 described the implementation
+of a simple language and added support for generating LLVM IR. This
+chapter describes two new techniques: adding optimizer support to your
+language, and adding JIT compiler support. These additions will
+demonstrate how to get nice, efficient code for the Kaleidoscope
+language.
+
+Trivial Constant Folding
+========================
+
+Our demonstration for Chapter 3 is elegant and easy to extend.
+Unfortunately, it does not produce wonderful code. The IRBuilder,
+however, does give us obvious optimizations when compiling simple code:
+
+::
+
+ ready> def test(x) 1+2+x;
+ Read function definition:
+ define double @test(double %x) {
+ entry:
+ %addtmp = fadd double 3.000000e+00, %x
+ ret double %addtmp
+ }
+
+This code is not a literal transcription of the AST built by parsing the
+input. That would be:
+
+::
+
+ ready> def test(x) 1+2+x;
+ Read function definition:
+ define double @test(double %x) {
+ entry:
+ %addtmp = fadd double 2.000000e+00, 1.000000e+00
+ %addtmp1 = fadd double %addtmp, %x
+ ret double %addtmp1
+ }
+
+Constant folding, as seen above, in particular, is a very common and
+very important optimization: so much so that many language implementors
+implement constant folding support in their AST representation.
+
+With LLVM, you don't need this support in the AST. Since all calls to
+build LLVM IR go through the LLVM IR builder, the builder itself checked
+to see if there was a constant folding opportunity when you call it. If
+so, it just does the constant fold and return the constant instead of
+creating an instruction.
+
+Well, that was easy :). In practice, we recommend always using
+``IRBuilder`` when generating code like this. It has no "syntactic
+overhead" for its use (you don't have to uglify your compiler with
+constant checks everywhere) and it can dramatically reduce the amount of
+LLVM IR that is generated in some cases (particular for languages with a
+macro preprocessor or that use a lot of constants).
+
+On the other hand, the ``IRBuilder`` is limited by the fact that it does
+all of its analysis inline with the code as it is built. If you take a
+slightly more complex example:
+
+::
+
+ ready> def test(x) (1+2+x)*(x+(1+2));
+ ready> Read function definition:
+ define double @test(double %x) {
+ entry:
+ %addtmp = fadd double 3.000000e+00, %x
+ %addtmp1 = fadd double %x, 3.000000e+00
+ %multmp = fmul double %addtmp, %addtmp1
+ ret double %multmp
+ }
+
+In this case, the LHS and RHS of the multiplication are the same value.
+We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"
+instead of computing "``x+3``" twice.
+
+Unfortunately, no amount of local analysis will be able to detect and
+correct this. This requires two transformations: reassociation of
+expressions (to make the add's lexically identical) and Common
+Subexpression Elimination (CSE) to delete the redundant add instruction.
+Fortunately, LLVM provides a broad range of optimizations that you can
+use, in the form of "passes".
+
+LLVM Optimization Passes
+========================
+
+LLVM provides many optimization passes, which do many different sorts of
+things and have different tradeoffs. Unlike other systems, LLVM doesn't
+hold to the mistaken notion that one set of optimizations is right for
+all languages and for all situations. LLVM allows a compiler implementor
+to make complete decisions about what optimizations to use, in which
+order, and in what situation.
+
+As a concrete example, LLVM supports both "whole module" passes, which
+look across as large of body of code as they can (often a whole file,
+but if run at link time, this can be a substantial portion of the whole
+program). It also supports and includes "per-function" passes which just
+operate on a single function at a time, without looking at other
+functions. For more information on passes and how they are run, see the
+`How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the
+`List of LLVM Passes <../Passes.html>`_.
+
+For Kaleidoscope, we are currently generating functions on the fly, one
+at a time, as the user types them in. We aren't shooting for the
+ultimate optimization experience in this setting, but we also want to
+catch the easy and quick stuff where possible. As such, we will choose
+to run a few per-function optimizations as the user types the function
+in. If we wanted to make a "static Kaleidoscope compiler", we would use
+exactly the code we have now, except that we would defer running the
+optimizer until the entire file has been parsed.
+
+In order to get per-function optimizations going, we need to set up a
+`FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
+and organize the LLVM optimizations that we want to run. Once we have
+that, we can add a set of optimizations to run. We'll need a new
+FunctionPassManager for each module that we want to optimize, so we'll
+write a function to create and initialize both the module and pass manager
+for us:
+
+.. code-block:: c++
+
+ void InitializeModuleAndPassManager(void) {
+ // Open a new module.
+ Context LLVMContext;
+ TheModule = llvm::make_unique<Module>("my cool jit", LLVMContext);
+ TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
+
+ // Create a new pass manager attached to it.
+ TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
+
+ // Provide basic AliasAnalysis support for GVN.
+ TheFPM.add(createBasicAliasAnalysisPass());
+ // Do simple "peephole" optimizations and bit-twiddling optzns.
+ TheFPM.add(createInstructionCombiningPass());
+ // Reassociate expressions.
+ TheFPM.add(createReassociatePass());
+ // Eliminate Common SubExpressions.
+ TheFPM.add(createGVNPass());
+ // Simplify the control flow graph (deleting unreachable blocks, etc).
+ TheFPM.add(createCFGSimplificationPass());
+
+ TheFPM.doInitialization();
+ }
+
+This code initializes the global module ``TheModule``, and the function pass
+manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
+set up, we use a series of "add" calls to add a bunch of LLVM passes.
+
+In this case, we choose to add five passes: one analysis pass (alias analysis),
+and four optimization passes. The passes we choose here are a pretty standard set
+of "cleanup" optimizations that are useful for a wide variety of code. I won't
+delve into what they do but, believe me, they are a good starting place :).
+
+Once the PassManager is set up, we need to make use of it. We do this by
+running it after our newly created function is constructed (in
+``FunctionAST::codegen()``), but before it is returned to the client:
+
+.. code-block:: c++
+
+ if (Value *RetVal = Body->codegen()) {
+ // Finish off the function.
+ Builder.CreateRet(RetVal);
+
+ // Validate the generated code, checking for consistency.
+ verifyFunction(*TheFunction);
+
+ // Optimize the function.
+ TheFPM->run(*TheFunction);
+
+ return TheFunction;
+ }
+
+As you can see, this is pretty straightforward. The
+``FunctionPassManager`` optimizes and updates the LLVM Function\* in
+place, improving (hopefully) its body. With this in place, we can try
+our test above again:
+
+::
+
+ ready> def test(x) (1+2+x)*(x+(1+2));
+ ready> Read function definition:
+ define double @test(double %x) {
+ entry:
+ %addtmp = fadd double %x, 3.000000e+00
+ %multmp = fmul double %addtmp, %addtmp
+ ret double %multmp
+ }
+
+As expected, we now get our nicely optimized code, saving a floating
+point add instruction from every execution of this function.
+
+LLVM provides a wide variety of optimizations that can be used in
+certain circumstances. Some `documentation about the various
+passes <../Passes.html>`_ is available, but it isn't very complete.
+Another good source of ideas can come from looking at the passes that
+``Clang`` runs to get started. The "``opt``" tool allows you to
+experiment with passes from the command line, so you can see if they do
+anything.
+
+Now that we have reasonable code coming out of our front-end, lets talk
+about executing it!
+
+Adding a JIT Compiler
+=====================
+
+Code that is available in LLVM IR can have a wide variety of tools
+applied to it. For example, you can run optimizations on it (as we did
+above), you can dump it out in textual or binary forms, you can compile
+the code to an assembly file (.s) for some target, or you can JIT
+compile it. The nice thing about the LLVM IR representation is that it
+is the "common currency" between many different parts of the compiler.
+
+In this section, we'll add JIT compiler support to our interpreter. The
+basic idea that we want for Kaleidoscope is to have the user enter
+function bodies as they do now, but immediately evaluate the top-level
+expressions they type in. For example, if they type in "1 + 2;", we
+should evaluate and print out 3. If they define a function, they should
+be able to call it from the command line.
+
+In order to do this, we first declare and initialize the JIT. This is
+done by adding a global variable ``TheJIT``, and initializing it in
+``main``:
+
+.. code-block:: c++
+
+ static std::unique_ptr<KaleidoscopeJIT> TheJIT;
+ ...
+ int main() {
+ ..
+ TheJIT = llvm::make_unique<KaleidoscopeJIT>();
+
+ // Run the main "interpreter loop" now.
+ MainLoop();
+
+ return 0;
+ }
+
+The KaleidoscopeJIT class is a simple JIT built specifically for these
+tutorials. In later chapters we will look at how it works and extend it with
+new features, but for now we will take it as given. Its API is very simple::
+``addModule`` adds an LLVM IR module to the JIT, making its functions
+available for execution; ``removeModule`` removes a module, freeing any
+memory associated with the code in that module; and ``findSymbol`` allows us
+to look up pointers to the compiled code.
+
+We can take this simple API and change our code that parses top-level expressions to
+look like this:
+
+.. code-block:: c++
+
+ static void HandleTopLevelExpression() {
+ // Evaluate a top-level expression into an anonymous function.
+ if (auto FnAST = ParseTopLevelExpr()) {
+ if (FnAST->codegen()) {
+
+ // JIT the module containing the anonymous expression, keeping a handle so
+ // we can free it later.
+ auto H = TheJIT->addModule(std::move(TheModule));
+ InitializeModuleAndPassManager();
+
+ // Search the JIT for the __anon_expr symbol.
+ auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
+ assert(ExprSymbol && "Function not found");
+
+ // Get the symbol's address and cast it to the right type (takes no
+ // arguments, returns a double) so we can call it as a native function.
+ double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
+ fprintf(stderr, "Evaluated to %f\n", FP());
+
+ // Delete the anonymous expression module from the JIT.
+ TheJIT->removeModule(H);
+ }
+
+If parsing and codegen succeeed, the next step is to add the module containing
+the top-level expression to the JIT. We do this by calling addModule, which
+triggers code generation for all the functions in the module, and returns a
+handle that can be used to remove the module from the JIT later. Once the module
+has been added to the JIT it can no longer be modified, so we also open a new
+module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.
+
+Once we've added the module to the JIT we need to get a pointer to the final
+generated code. We do this by calling the JIT's findSymbol method, and passing
+the name of the top-level expression function: ``__anon_expr``. Since we just
+added this function, we assert that findSymbol returned a result.
+
+Next, we get the in-memory address of the ``__anon_expr`` function by calling
+``getAddress()`` on the symbol. Recall that we compile top-level expressions
+into a self-contained LLVM function that takes no arguments and returns the
+computed double. Because the LLVM JIT compiler matches the native platform ABI,
+this means that you can just cast the result pointer to a function pointer of
+that type and call it directly. This means, there is no difference between JIT
+compiled code and native machine code that is statically linked into your
+application.
+
+Finally, since we don't support re-evaluation of top-level expressions, we
+remove the module from the JIT when we're done to free the associated memory.
+Recall, however, that the module we created a few lines earlier (via
+``InitializeModuleAndPassManager``) is still open and waiting for new code to be
+added.
+
+With just these two changes, lets see how Kaleidoscope works now!
+
+::
+
+ ready> 4+5;
+ Read top-level expression:
+ define double @0() {
+ entry:
+ ret double 9.000000e+00
+ }
+
+ Evaluated to 9.000000
+
+Well this looks like it is basically working. The dump of the function
+shows the "no argument function that always returns double" that we
+synthesize for each top-level expression that is typed in. This
+demonstrates very basic functionality, but can we do more?
+
+::
+
+ ready> def testfunc(x y) x + y*2;
+ Read function definition:
+ define double @testfunc(double %x, double %y) {
+ entry:
+ %multmp = fmul double %y, 2.000000e+00
+ %addtmp = fadd double %multmp, %x
+ ret double %addtmp
+ }
+
+ ready> testfunc(4, 10);
+ Read top-level expression:
+ define double @1() {
+ entry:
+ %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
+ ret double %calltmp
+ }
+
+ Evaluated to 24.000000
+
+ ready> testfunc(5, 10);
+ ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!
+
+
+Function definitions and calls also work, but something went very wrong on that
+last line. The call looks valid, so what happened? As you may have guessed from
+the the API a Module is a unit of allocation for the JIT, and testfunc was part
+of the same module that contained anonymous expression. When we removed that
+module from the JIT to free the memory for the anonymous expression, we deleted
+the definition of ``testfunc`` along with it. Then, when we tried to call
+testfunc a second time, the JIT could no longer find it.
+
+The easiest way to fix this is to put the anonymous expression in a separate
+module from the rest of the function definitions. The JIT will happily resolve
+function calls across module boundaries, as long as each of the functions called
+has a prototype, and is added to the JIT before it is called. By putting the
+anonymous expression in a different module we can delete it without affecting
+the rest of the functions.
+
+In fact, we're going to go a step further and put every function in its own
+module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT
+that will make our environment more REPL-like: Functions can be added to the
+JIT more than once (unlike a module where every function must have a unique
+definition). When you look up a symbol in KaleidoscopeJIT it will always return
+the most recent definition:
+
+::
+
+ ready> def foo(x) x + 1;
+ Read function definition:
+ define double @foo(double %x) {
+ entry:
+ %addtmp = fadd double %x, 1.000000e+00
+ ret double %addtmp
+ }
+
+ ready> foo(2);
+ Evaluated to 3.000000
+
+ ready> def foo(x) x + 2;
+ define double @foo(double %x) {
+ entry:
+ %addtmp = fadd double %x, 2.000000e+00
+ ret double %addtmp
+ }
+
+ ready> foo(2);
+ Evaluated to 4.000000
+
+
+To allow each function to live in its own module we'll need a way to
+re-generate previous function declarations into each new module we open:
+
+.. code-block:: c++
+
+ static std::unique_ptr<KaleidoscopeJIT> TheJIT;
+
+ ...
+
+ Function *getFunction(std::string Name) {
+ // First, see if the function has already been added to the current module.
+ if (auto *F = TheModule->getFunction(Name))
+ return F;
+
+ // If not, check whether we can codegen the declaration from some existing
+ // prototype.
+ auto FI = FunctionProtos.find(Name);
+ if (FI != FunctionProtos.end())
+ return FI->second->codegen();
+
+ // If no existing prototype exists, return null.
+ return nullptr;
+ }
+
+ ...
+
+ Value *CallExprAST::codegen() {
+ // Look up the name in the global module table.
+ Function *CalleeF = getFunction(Callee);
+
+ ...
+
+ Function *FunctionAST::codegen() {
+ // Transfer ownership of the prototype to the FunctionProtos map, but keep a
+ // reference to it for use below.
+ auto &P = *Proto;
+ FunctionProtos[Proto->getName()] = std::move(Proto);
+ Function *TheFunction = getFunction(P.getName());
+ if (!TheFunction)
+ return nullptr;
+
+
+To enable this, we'll start by adding a new global, ``FunctionProtos``, that
+holds the most recent prototype for each function. We'll also add a convenience
+method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.
+Our convenience method searches ``TheModule`` for an existing function
+declaration, falling back to generating a new declaration from FunctionProtos if
+it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the
+call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to
+update the FunctionProtos map first, then call ``getFunction()``. With this
+done, we can always obtain a function declaration in the current module for any
+previously declared function.
+
+We also need to update HandleDefinition and HandleExtern:
+
+.. code-block:: c++
+
+ static void HandleDefinition() {
+ if (auto FnAST = ParseDefinition()) {
+ if (auto *FnIR = FnAST->codegen()) {
+ fprintf(stderr, "Read function definition:");
+ FnIR->dump();
+ TheJIT->addModule(std::move(TheModule));
+ InitializeModuleAndPassManager();
+ }
+ } else {
+ // Skip token for error recovery.
+ getNextToken();
+ }
+ }
+
+ static void HandleExtern() {
+ if (auto ProtoAST = ParseExtern()) {
+ if (auto *FnIR = ProtoAST->codegen()) {
+ fprintf(stderr, "Read extern: ");
+ FnIR->dump();
+ FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
+ }
+ } else {
+ // Skip token for error recovery.
+ getNextToken();
+ }
+ }
+
+In HandleDefinition, we add two lines to transfer the newly defined function to
+the JIT and open a new module. In HandleExtern, we just need to add one line to
+add the prototype to FunctionProtos.
+
+With these changes made, lets try our REPL again (I removed the dump of the
+anonymous functions this time, you should get the idea by now :) :
+
+::
+
+ ready> def foo(x) x + 1;
+ ready> foo(2);
+ Evaluated to 3.000000
+
+ ready> def foo(x) x + 2;
+ ready> foo(2);
+ Evaluated to 4.000000
+
+It works!
+
+Even with this simple code, we get some surprisingly powerful capabilities -
+check this out:
+
+::
+
+ ready> extern sin(x);
+ Read extern:
+ declare double @sin(double)
+
+ ready> extern cos(x);
+ Read extern:
+ declare double @cos(double)
+
+ ready> sin(1.0);
+ Read top-level expression:
+ define double @2() {
+ entry:
+ ret double 0x3FEAED548F090CEE
+ }
+
+ Evaluated to 0.841471
+
+ ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
+ Read function definition:
+ define double @foo(double %x) {
+ entry:
+ %calltmp = call double @sin(double %x)
+ %multmp = fmul double %calltmp, %calltmp
+ %calltmp2 = call double @cos(double %x)
+ %multmp4 = fmul double %calltmp2, %calltmp2
+ %addtmp = fadd double %multmp, %multmp4
+ ret double %addtmp
+ }
+
+ ready> foo(4.0);
+ Read top-level expression:
+ define double @3() {
+ entry:
+ %calltmp = call double @foo(double 4.000000e+00)
+ ret double %calltmp
+ }
+
+ Evaluated to 1.000000
+
+Whoa, how does the JIT know about sin and cos? The answer is surprisingly
+simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that
+it uses to find symbols that aren't available in any given module: First
+it searches all the modules that have already been added to the JIT, from the
+most recent to the oldest, to find the newest definition. If no definition is
+found inside the JIT, it falls back to calling "``dlsym("sin")``" on the
+Kaleidoscope process itself. Since "``sin``" is defined within the JIT's
+address space, it simply patches up calls in the module to call the libm
+version of ``sin`` directly.
+
+In the future we'll see how tweaking this symbol resolution rule can be used to
+enable all sorts of useful features, from security (restricting the set of
+symbols available to JIT'd code), to dynamic code generation based on symbol
+names, and even lazy compilation.
+
+One immediate benefit of the symbol resolution rule is that we can now extend
+the language by writing arbitrary C++ code to implement operations. For example,
+if we add:
+
+.. code-block:: c++
+
+ /// putchard - putchar that takes a double and returns 0.
+ extern "C" double putchard(double X) {
+ fputc((char)X, stderr);
+ return 0;
+ }
+
+Now we can produce simple output to the console by using things like:
+"``extern putchard(x); putchard(120);``", which prints a lowercase 'x'
+on the console (120 is the ASCII code for 'x'). Similar code could be
+used to implement file I/O, console input, and many other capabilities
+in Kaleidoscope.
+
+This completes the JIT and optimizer chapter of the Kaleidoscope
+tutorial. At this point, we can compile a non-Turing-complete
+programming language, optimize and JIT compile it in a user-driven way.
+Next up we'll look into `extending the language with control flow
+constructs <LangImpl5.html>`_, tackling some interesting LLVM IR issues
+along the way.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+the LLVM JIT and optimizer. To build this example, use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
+ # Run
+ ./toy
+
+If you are compiling this on Linux, make sure to add the "-rdynamic"
+option as well. This makes sure that the external functions are resolved
+properly at runtime.
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp
+ :language: c++
+
+`Next: Extending the language: control flow <LangImpl05.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl05-cfg.png
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05-cfg.png?rev=274441&view=auto
==============================================================================
Binary file - no diff available.
Propchange: llvm/trunk/docs/tutorial/LangImpl05-cfg.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: llvm/trunk/docs/tutorial/LangImpl05.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl05.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl05.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl05.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,790 @@
+==================================================
+Kaleidoscope: Extending the Language: Control Flow
+==================================================
+
+.. contents::
+ :local:
+
+Chapter 5 Introduction
+======================
+
+Welcome to Chapter 5 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. Parts 1-4 described the implementation of
+the simple Kaleidoscope language and included support for generating
+LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as
+presented, Kaleidoscope is mostly useless: it has no control flow other
+than call and return. This means that you can't have conditional
+branches in the code, significantly limiting its power. In this episode
+of "build that compiler", we'll extend Kaleidoscope to have an
+if/then/else expression plus a simple 'for' loop.
+
+If/Then/Else
+============
+
+Extending Kaleidoscope to support if/then/else is quite straightforward.
+It basically requires adding support for this "new" concept to the
+lexer, parser, AST, and LLVM code emitter. This example is nice, because
+it shows how easy it is to "grow" a language over time, incrementally
+extending it as new ideas are discovered.
+
+Before we get going on "how" we add this extension, lets talk about
+"what" we want. The basic idea is that we want to be able to write this
+sort of thing:
+
+::
+
+ def fib(x)
+ if x < 3 then
+ 1
+ else
+ fib(x-1)+fib(x-2);
+
+In Kaleidoscope, every construct is an expression: there are no
+statements. As such, the if/then/else expression needs to return a value
+like any other. Since we're using a mostly functional form, we'll have
+it evaluate its conditional, then return the 'then' or 'else' value
+based on how the condition was resolved. This is very similar to the C
+"?:" expression.
+
+The semantics of the if/then/else expression is that it evaluates the
+condition to a boolean equality value: 0.0 is considered to be false and
+everything else is considered to be true. If the condition is true, the
+first subexpression is evaluated and returned, if the condition is
+false, the second subexpression is evaluated and returned. Since
+Kaleidoscope allows side-effects, this behavior is important to nail
+down.
+
+Now that we know what we "want", lets break this down into its
+constituent pieces.
+
+Lexer Extensions for If/Then/Else
+---------------------------------
+
+The lexer extensions are straightforward. First we add new enum values
+for the relevant tokens:
+
+.. code-block:: c++
+
+ // control
+ tok_if = -6,
+ tok_then = -7,
+ tok_else = -8,
+
+Once we have that, we recognize the new keywords in the lexer. This is
+pretty simple stuff:
+
+.. code-block:: c++
+
+ ...
+ if (IdentifierStr == "def")
+ return tok_def;
+ if (IdentifierStr == "extern")
+ return tok_extern;
+ if (IdentifierStr == "if")
+ return tok_if;
+ if (IdentifierStr == "then")
+ return tok_then;
+ if (IdentifierStr == "else")
+ return tok_else;
+ return tok_identifier;
+
+AST Extensions for If/Then/Else
+-------------------------------
+
+To represent the new expression we add a new AST node for it:
+
+.. code-block:: c++
+
+ /// IfExprAST - Expression class for if/then/else.
+ class IfExprAST : public ExprAST {
+ std::unique_ptr<ExprAST> Cond, Then, Else;
+
+ public:
+ IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
+ std::unique_ptr<ExprAST> Else)
+ : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
+ virtual Value *codegen();
+ };
+
+The AST node just has pointers to the various subexpressions.
+
+Parser Extensions for If/Then/Else
+----------------------------------
+
+Now that we have the relevant tokens coming from the lexer and we have
+the AST node to build, our parsing logic is relatively straightforward.
+First we define a new parsing function:
+
+.. code-block:: c++
+
+ /// ifexpr ::= 'if' expression 'then' expression 'else' expression
+ static std::unique_ptr<ExprAST> ParseIfExpr() {
+ getNextToken(); // eat the if.
+
+ // condition.
+ auto Cond = ParseExpression();
+ if (!Cond)
+ return nullptr;
+
+ if (CurTok != tok_then)
+ return LogError("expected then");
+ getNextToken(); // eat the then
+
+ auto Then = ParseExpression();
+ if (!Then)
+ return nullptr;
+
+ if (CurTok != tok_else)
+ return LogError("expected else");
+
+ getNextToken();
+
+ auto Else = ParseExpression();
+ if (!Else)
+ return nullptr;
+
+ return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
+ std::move(Else));
+ }
+
+Next we hook it up as a primary expression:
+
+.. code-block:: c++
+
+ static std::unique_ptr<ExprAST> ParsePrimary() {
+ switch (CurTok) {
+ default:
+ return LogError("unknown token when expecting an expression");
+ case tok_identifier:
+ return ParseIdentifierExpr();
+ case tok_number:
+ return ParseNumberExpr();
+ case '(':
+ return ParseParenExpr();
+ case tok_if:
+ return ParseIfExpr();
+ }
+ }
+
+LLVM IR for If/Then/Else
+------------------------
+
+Now that we have it parsing and building the AST, the final piece is
+adding LLVM code generation support. This is the most interesting part
+of the if/then/else example, because this is where it starts to
+introduce new concepts. All of the code above has been thoroughly
+described in previous chapters.
+
+To motivate the code we want to produce, lets take a look at a simple
+example. Consider:
+
+::
+
+ extern foo();
+ extern bar();
+ def baz(x) if x then foo() else bar();
+
+If you disable optimizations, the code you'll (soon) get from
+Kaleidoscope looks like this:
+
+.. code-block:: llvm
+
+ declare double @foo()
+
+ declare double @bar()
+
+ define double @baz(double %x) {
+ entry:
+ %ifcond = fcmp one double %x, 0.000000e+00
+ br i1 %ifcond, label %then, label %else
+
+ then: ; preds = %entry
+ %calltmp = call double @foo()
+ br label %ifcont
+
+ else: ; preds = %entry
+ %calltmp1 = call double @bar()
+ br label %ifcont
+
+ ifcont: ; preds = %else, %then
+ %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
+ ret double %iftmp
+ }
+
+To visualize the control flow graph, you can use a nifty feature of the
+LLVM '`opt <http://llvm.org/cmds/opt.html>`_' tool. If you put this LLVM
+IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
+window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
+see this graph:
+
+.. figure:: LangImpl05-cfg.png
+ :align: center
+ :alt: Example CFG
+
+ Example CFG
+
+Another way to get this is to call "``F->viewCFG()``" or
+"``F->viewCFGOnly()``" (where F is a "``Function*``") either by
+inserting actual calls into the code and recompiling or by calling these
+in the debugger. LLVM has many nice features for visualizing various
+graphs.
+
+Getting back to the generated code, it is fairly simple: the entry block
+evaluates the conditional expression ("x" in our case here) and compares
+the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered
+and Not Equal"). Based on the result of this expression, the code jumps
+to either the "then" or "else" blocks, which contain the expressions for
+the true/false cases.
+
+Once the then/else blocks are finished executing, they both branch back
+to the 'ifcont' block to execute the code that happens after the
+if/then/else. In this case the only thing left to do is to return to the
+caller of the function. The question then becomes: how does the code
+know which expression to return?
+
+The answer to this question involves an important SSA operation: the
+`Phi
+operation <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
+If you're not familiar with SSA, `the wikipedia
+article <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
+is a good introduction and there are various other introductions to it
+available on your favorite search engine. The short version is that
+"execution" of the Phi operation requires "remembering" which block
+control came from. The Phi operation takes on the value corresponding to
+the input control block. In this case, if control comes in from the
+"then" block, it gets the value of "calltmp". If control comes from the
+"else" block, it gets the value of "calltmp1".
+
+At this point, you are probably starting to think "Oh no! This means my
+simple and elegant front-end will have to start generating SSA form in
+order to use LLVM!". Fortunately, this is not the case, and we strongly
+advise *not* implementing an SSA construction algorithm in your
+front-end unless there is an amazingly good reason to do so. In
+practice, there are two sorts of values that float around in code
+written for your average imperative programming language that might need
+Phi nodes:
+
+#. Code that involves user variables: ``x = 1; x = x + 1;``
+#. Values that are implicit in the structure of your AST, such as the
+ Phi node in this case.
+
+In `Chapter 7 <LangImpl7.html>`_ of this tutorial ("mutable variables"),
+we'll talk about #1 in depth. For now, just believe me that you don't
+need SSA construction to handle this case. For #2, you have the choice
+of using the techniques that we will describe for #1, or you can insert
+Phi nodes directly, if convenient. In this case, it is really
+easy to generate the Phi node, so we choose to do it directly.
+
+Okay, enough of the motivation and overview, lets generate code!
+
+Code Generation for If/Then/Else
+--------------------------------
+
+In order to generate code for this, we implement the ``codegen`` method
+for ``IfExprAST``:
+
+.. code-block:: c++
+
+ Value *IfExprAST::codegen() {
+ Value *CondV = Cond->codegen();
+ if (!CondV)
+ return nullptr;
+
+ // Convert condition to a bool by comparing equal to 0.0.
+ CondV = Builder.CreateFCmpONE(
+ CondV, ConstantFP::get(LLVMContext, APFloat(0.0)), "ifcond");
+
+This code is straightforward and similar to what we saw before. We emit
+the expression for the condition, then compare that value to zero to get
+a truth value as a 1-bit (bool) value.
+
+.. code-block:: c++
+
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Create blocks for the then and else cases. Insert the 'then' block at the
+ // end of the function.
+ BasicBlock *ThenBB =
+ BasicBlock::Create(LLVMContext, "then", TheFunction);
+ BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");
+ BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");
+
+ Builder.CreateCondBr(CondV, ThenBB, ElseBB);
+
+This code creates the basic blocks that are related to the if/then/else
+statement, and correspond directly to the blocks in the example above.
+The first line gets the current Function object that is being built. It
+gets this by asking the builder for the current BasicBlock, and asking
+that block for its "parent" (the function it is currently embedded
+into).
+
+Once it has that, it creates three blocks. Note that it passes
+"TheFunction" into the constructor for the "then" block. This causes the
+constructor to automatically insert the new block into the end of the
+specified function. The other two blocks are created, but aren't yet
+inserted into the function.
+
+Once the blocks are created, we can emit the conditional branch that
+chooses between them. Note that creating new blocks does not implicitly
+affect the IRBuilder, so it is still inserting into the block that the
+condition went into. Also note that it is creating a branch to the
+"then" block and the "else" block, even though the "else" block isn't
+inserted into the function yet. This is all ok: it is the standard way
+that LLVM supports forward references.
+
+.. code-block:: c++
+
+ // Emit then value.
+ Builder.SetInsertPoint(ThenBB);
+
+ Value *ThenV = Then->codegen();
+ if (!ThenV)
+ return nullptr;
+
+ Builder.CreateBr(MergeBB);
+ // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
+ ThenBB = Builder.GetInsertBlock();
+
+After the conditional branch is inserted, we move the builder to start
+inserting into the "then" block. Strictly speaking, this call moves the
+insertion point to be at the end of the specified block. However, since
+the "then" block is empty, it also starts out by inserting at the
+beginning of the block. :)
+
+Once the insertion point is set, we recursively codegen the "then"
+expression from the AST. To finish off the "then" block, we create an
+unconditional branch to the merge block. One interesting (and very
+important) aspect of the LLVM IR is that it `requires all basic blocks
+to be "terminated" <../LangRef.html#functionstructure>`_ with a `control
+flow instruction <../LangRef.html#terminators>`_ such as return or
+branch. This means that all control flow, *including fall throughs* must
+be made explicit in the LLVM IR. If you violate this rule, the verifier
+will emit an error.
+
+The final line here is quite subtle, but is very important. The basic
+issue is that when we create the Phi node in the merge block, we need to
+set up the block/value pairs that indicate how the Phi will work.
+Importantly, the Phi node expects to have an entry for each predecessor
+of the block in the CFG. Why then, are we getting the current block when
+we just set it to ThenBB 5 lines above? The problem is that the "Then"
+expression may actually itself change the block that the Builder is
+emitting into if, for example, it contains a nested "if/then/else"
+expression. Because calling ``codegen()`` recursively could arbitrarily change
+the notion of the current block, we are required to get an up-to-date
+value for code that will set up the Phi node.
+
+.. code-block:: c++
+
+ // Emit else block.
+ TheFunction->getBasicBlockList().push_back(ElseBB);
+ Builder.SetInsertPoint(ElseBB);
+
+ Value *ElseV = Else->codegen();
+ if (!ElseV)
+ return nullptr;
+
+ Builder.CreateBr(MergeBB);
+ // codegen of 'Else' can change the current block, update ElseBB for the PHI.
+ ElseBB = Builder.GetInsertBlock();
+
+Code generation for the 'else' block is basically identical to codegen
+for the 'then' block. The only significant difference is the first line,
+which adds the 'else' block to the function. Recall previously that the
+'else' block was created, but not added to the function. Now that the
+'then' and 'else' blocks are emitted, we can finish up with the merge
+code:
+
+.. code-block:: c++
+
+ // Emit merge block.
+ TheFunction->getBasicBlockList().push_back(MergeBB);
+ Builder.SetInsertPoint(MergeBB);
+ PHINode *PN =
+ Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");
+
+ PN->addIncoming(ThenV, ThenBB);
+ PN->addIncoming(ElseV, ElseBB);
+ return PN;
+ }
+
+The first two lines here are now familiar: the first adds the "merge"
+block to the Function object (it was previously floating, like the else
+block above). The second changes the insertion point so that newly
+created code will go into the "merge" block. Once that is done, we need
+to create the PHI node and set up the block/value pairs for the PHI.
+
+Finally, the CodeGen function returns the phi node as the value computed
+by the if/then/else expression. In our example above, this returned
+value will feed into the code for the top-level function, which will
+create the return instruction.
+
+Overall, we now have the ability to execute conditional code in
+Kaleidoscope. With this extension, Kaleidoscope is a fairly complete
+language that can calculate a wide variety of numeric functions. Next up
+we'll add another useful expression that is familiar from non-functional
+languages...
+
+'for' Loop Expression
+=====================
+
+Now that we know how to add basic control flow constructs to the
+language, we have the tools to add more powerful things. Lets add
+something more aggressive, a 'for' expression:
+
+::
+
+ extern putchard(char)
+ def printstar(n)
+ for i = 1, i < n, 1.0 in
+ putchard(42); # ascii 42 = '*'
+
+ # print 100 '*' characters
+ printstar(100);
+
+This expression defines a new variable ("i" in this case) which iterates
+from a starting value, while the condition ("i < n" in this case) is
+true, incrementing by an optional step value ("1.0" in this case). If
+the step value is omitted, it defaults to 1.0. While the loop is true,
+it executes its body expression. Because we don't have anything better
+to return, we'll just define the loop as always returning 0.0. In the
+future when we have mutable variables, it will get more useful.
+
+As before, lets talk about the changes that we need to Kaleidoscope to
+support this.
+
+Lexer Extensions for the 'for' Loop
+-----------------------------------
+
+The lexer extensions are the same sort of thing as for if/then/else:
+
+.. code-block:: c++
+
+ ... in enum Token ...
+ // control
+ tok_if = -6, tok_then = -7, tok_else = -8,
+ tok_for = -9, tok_in = -10
+
+ ... in gettok ...
+ if (IdentifierStr == "def")
+ return tok_def;
+ if (IdentifierStr == "extern")
+ return tok_extern;
+ if (IdentifierStr == "if")
+ return tok_if;
+ if (IdentifierStr == "then")
+ return tok_then;
+ if (IdentifierStr == "else")
+ return tok_else;
+ if (IdentifierStr == "for")
+ return tok_for;
+ if (IdentifierStr == "in")
+ return tok_in;
+ return tok_identifier;
+
+AST Extensions for the 'for' Loop
+---------------------------------
+
+The AST node is just as simple. It basically boils down to capturing the
+variable name and the constituent expressions in the node.
+
+.. code-block:: c++
+
+ /// ForExprAST - Expression class for for/in.
+ class ForExprAST : public ExprAST {
+ std::string VarName;
+ std::unique_ptr<ExprAST> Start, End, Step, Body;
+
+ public:
+ ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
+ std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
+ std::unique_ptr<ExprAST> Body)
+ : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
+ Step(std::move(Step)), Body(std::move(Body)) {}
+ virtual Value *codegen();
+ };
+
+Parser Extensions for the 'for' Loop
+------------------------------------
+
+The parser code is also fairly standard. The only interesting thing here
+is handling of the optional step value. The parser code handles it by
+checking to see if the second comma is present. If not, it sets the step
+value to null in the AST node:
+
+.. code-block:: c++
+
+ /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
+ static std::unique_ptr<ExprAST> ParseForExpr() {
+ getNextToken(); // eat the for.
+
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier after for");
+
+ std::string IdName = IdentifierStr;
+ getNextToken(); // eat identifier.
+
+ if (CurTok != '=')
+ return LogError("expected '=' after for");
+ getNextToken(); // eat '='.
+
+
+ auto Start = ParseExpression();
+ if (!Start)
+ return nullptr;
+ if (CurTok != ',')
+ return LogError("expected ',' after for start value");
+ getNextToken();
+
+ auto End = ParseExpression();
+ if (!End)
+ return nullptr;
+
+ // The step value is optional.
+ std::unique_ptr<ExprAST> Step;
+ if (CurTok == ',') {
+ getNextToken();
+ Step = ParseExpression();
+ if (!Step)
+ return nullptr;
+ }
+
+ if (CurTok != tok_in)
+ return LogError("expected 'in' after for");
+ getNextToken(); // eat 'in'.
+
+ auto Body = ParseExpression();
+ if (!Body)
+ return nullptr;
+
+ return llvm::make_unique<ForExprAST>(IdName, std::move(Start),
+ std::move(End), std::move(Step),
+ std::move(Body));
+ }
+
+LLVM IR for the 'for' Loop
+--------------------------
+
+Now we get to the good part: the LLVM IR we want to generate for this
+thing. With the simple example above, we get this LLVM IR (note that
+this dump is generated with optimizations disabled for clarity):
+
+.. code-block:: llvm
+
+ declare double @putchard(double)
+
+ define double @printstar(double %n) {
+ entry:
+ ; initial value = 1.0 (inlined into phi)
+ br label %loop
+
+ loop: ; preds = %loop, %entry
+ %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
+ ; body
+ %calltmp = call double @putchard(double 4.200000e+01)
+ ; increment
+ %nextvar = fadd double %i, 1.000000e+00
+
+ ; termination test
+ %cmptmp = fcmp ult double %i, %n
+ %booltmp = uitofp i1 %cmptmp to double
+ %loopcond = fcmp one double %booltmp, 0.000000e+00
+ br i1 %loopcond, label %loop, label %afterloop
+
+ afterloop: ; preds = %loop
+ ; loop always returns 0.0
+ ret double 0.000000e+00
+ }
+
+This loop contains all the same constructs we saw before: a phi node,
+several expressions, and some basic blocks. Lets see how this fits
+together.
+
+Code Generation for the 'for' Loop
+----------------------------------
+
+The first part of codegen is very simple: we just output the start
+expression for the loop value:
+
+.. code-block:: c++
+
+ Value *ForExprAST::codegen() {
+ // Emit the start code first, without 'variable' in scope.
+ Value *StartVal = Start->codegen();
+ if (StartVal == 0) return 0;
+
+With this out of the way, the next step is to set up the LLVM basic
+block for the start of the loop body. In the case above, the whole loop
+body is one block, but remember that the body code itself could consist
+of multiple blocks (e.g. if it contains an if/then/else or a for/in
+expression).
+
+.. code-block:: c++
+
+ // Make the new basic block for the loop header, inserting after current
+ // block.
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+ BasicBlock *PreheaderBB = Builder.GetInsertBlock();
+ BasicBlock *LoopBB =
+ BasicBlock::Create(LLVMContext, "loop", TheFunction);
+
+ // Insert an explicit fall through from the current block to the LoopBB.
+ Builder.CreateBr(LoopBB);
+
+This code is similar to what we saw for if/then/else. Because we will
+need it to create the Phi node, we remember the block that falls through
+into the loop. Once we have that, we create the actual block that starts
+the loop and create an unconditional branch for the fall-through between
+the two blocks.
+
+.. code-block:: c++
+
+ // Start insertion in LoopBB.
+ Builder.SetInsertPoint(LoopBB);
+
+ // Start the PHI node with an entry for Start.
+ PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(LLVMContext),
+ 2, VarName.c_str());
+ Variable->addIncoming(StartVal, PreheaderBB);
+
+Now that the "preheader" for the loop is set up, we switch to emitting
+code for the loop body. To begin with, we move the insertion point and
+create the PHI node for the loop induction variable. Since we already
+know the incoming value for the starting value, we add it to the Phi
+node. Note that the Phi will eventually get a second value for the
+backedge, but we can't set it up yet (because it doesn't exist!).
+
+.. code-block:: c++
+
+ // Within the loop, the variable is defined equal to the PHI node. If it
+ // shadows an existing variable, we have to restore it, so save it now.
+ Value *OldVal = NamedValues[VarName];
+ NamedValues[VarName] = Variable;
+
+ // Emit the body of the loop. This, like any other expr, can change the
+ // current BB. Note that we ignore the value computed by the body, but don't
+ // allow an error.
+ if (!Body->codegen())
+ return nullptr;
+
+Now the code starts to get more interesting. Our 'for' loop introduces a
+new variable to the symbol table. This means that our symbol table can
+now contain either function arguments or loop variables. To handle this,
+before we codegen the body of the loop, we add the loop variable as the
+current value for its name. Note that it is possible that there is a
+variable of the same name in the outer scope. It would be easy to make
+this an error (emit an error and return null if there is already an
+entry for VarName) but we choose to allow shadowing of variables. In
+order to handle this correctly, we remember the Value that we are
+potentially shadowing in ``OldVal`` (which will be null if there is no
+shadowed variable).
+
+Once the loop variable is set into the symbol table, the code
+recursively codegen's the body. This allows the body to use the loop
+variable: any references to it will naturally find it in the symbol
+table.
+
+.. code-block:: c++
+
+ // Emit the step value.
+ Value *StepVal = nullptr;
+ if (Step) {
+ StepVal = Step->codegen();
+ if (!StepVal)
+ return nullptr;
+ } else {
+ // If not specified, use 1.0.
+ StepVal = ConstantFP::get(LLVMContext, APFloat(1.0));
+ }
+
+ Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
+
+Now that the body is emitted, we compute the next value of the iteration
+variable by adding the step value, or 1.0 if it isn't present.
+'``NextVar``' will be the value of the loop variable on the next
+iteration of the loop.
+
+.. code-block:: c++
+
+ // Compute the end condition.
+ Value *EndCond = End->codegen();
+ if (!EndCond)
+ return nullptr;
+
+ // Convert condition to a bool by comparing equal to 0.0.
+ EndCond = Builder.CreateFCmpONE(
+ EndCond, ConstantFP::get(LLVMContext, APFloat(0.0)), "loopcond");
+
+Finally, we evaluate the exit value of the loop, to determine whether
+the loop should exit. This mirrors the condition evaluation for the
+if/then/else statement.
+
+.. code-block:: c++
+
+ // Create the "after loop" block and insert it.
+ BasicBlock *LoopEndBB = Builder.GetInsertBlock();
+ BasicBlock *AfterBB =
+ BasicBlock::Create(LLVMContext, "afterloop", TheFunction);
+
+ // Insert the conditional branch into the end of LoopEndBB.
+ Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
+
+ // Any new code will be inserted in AfterBB.
+ Builder.SetInsertPoint(AfterBB);
+
+With the code for the body of the loop complete, we just need to finish
+up 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 exit condition, it creates a conditional branch that
+chooses between executing the loop again and exiting the loop. Any
+future code is emitted in the "afterloop" block, so it sets the
+insertion position to it.
+
+.. code-block:: c++
+
+ // Add a new entry to the PHI node for the backedge.
+ Variable->addIncoming(NextVar, LoopEndBB);
+
+ // Restore the unshadowed variable.
+ if (OldVal)
+ NamedValues[VarName] = OldVal;
+ else
+ NamedValues.erase(VarName);
+
+ // for expr always returns 0.0.
+ return Constant::getNullValue(Type::getDoubleTy(LLVMContext));
+ }
+
+The final code handles various cleanups: now that we have the "NextVar"
+value, we can add the incoming value to the loop PHI node. After that,
+we remove the loop variable from the symbol table, so that it isn't in
+scope after the for loop. Finally, code generation of the for loop
+always returns 0.0, so that is what we return from
+``ForExprAST::codegen()``.
+
+With this, we conclude the "adding control flow to Kaleidoscope" chapter
+of the tutorial. In this chapter we added two control flow constructs,
+and used them to motivate a couple of aspects of the LLVM IR that are
+important for front-end implementors to know. In the next chapter of our
+saga, we will get a bit crazier and add `user-defined
+operators <LangImpl6.html>`_ to our poor innocent language.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+the if/then/else and for expressions.. To build this example, use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
+ # Run
+ ./toy
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp
+ :language: c++
+
+`Next: Extending the language: user-defined operators <LangImpl06.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl06.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl06.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl06.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl06.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,768 @@
+============================================================
+Kaleidoscope: Extending the Language: User-defined Operators
+============================================================
+
+.. contents::
+ :local:
+
+Chapter 6 Introduction
+======================
+
+Welcome to Chapter 6 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. At this point in our tutorial, we now
+have a fully functional language that is fairly minimal, but also
+useful. There is still one big problem with it, however. Our language
+doesn't have many useful operators (like division, logical negation, or
+even any comparisons besides less-than).
+
+This chapter of the tutorial takes a wild digression into adding
+user-defined operators to the simple and beautiful Kaleidoscope
+language. This digression now gives us a simple and ugly language in
+some ways, but also a powerful one at the same time. One of the great
+things about creating your own language is that you get to decide what
+is good or bad. In this tutorial we'll assume that it is okay to use
+this as a way to show some interesting parsing techniques.
+
+At the end of this tutorial, we'll run through an example Kaleidoscope
+application that `renders the Mandelbrot set <#kicking-the-tires>`_. This gives an
+example of what you can build with Kaleidoscope and its feature set.
+
+User-defined Operators: the Idea
+================================
+
+The "operator overloading" that we will add to Kaleidoscope is more
+general than languages like C++. In C++, you are only allowed to
+redefine existing operators: you can't programatically change the
+grammar, introduce new operators, change precedence levels, etc. In this
+chapter, we will add this capability to Kaleidoscope, which will let the
+user round out the set of operators that are supported.
+
+The point of going into user-defined operators in a tutorial like this
+is to show the power and flexibility of using a hand-written parser.
+Thus far, the parser we have been implementing uses recursive descent
+for most parts of the grammar and operator precedence parsing for the
+expressions. See `Chapter 2 <LangImpl2.html>`_ for details. Without
+using operator precedence parsing, it would be very difficult to allow
+the programmer to introduce new operators into the grammar: the grammar
+is dynamically extensible as the JIT runs.
+
+The two specific features we'll add are programmable unary operators
+(right now, Kaleidoscope has no unary operators at all) as well as
+binary operators. An example of this is:
+
+::
+
+ # Logical unary not.
+ def unary!(v)
+ if v then
+ 0
+ else
+ 1;
+
+ # Define > with the same precedence as <.
+ def binary> 10 (LHS RHS)
+ RHS < LHS;
+
+ # Binary "logical or", (note that it does not "short circuit")
+ def binary| 5 (LHS RHS)
+ if LHS then
+ 1
+ else if RHS then
+ 1
+ else
+ 0;
+
+ # Define = with slightly lower precedence than relationals.
+ def binary= 9 (LHS RHS)
+ !(LHS < RHS | LHS > RHS);
+
+Many languages aspire to being able to implement their standard runtime
+library in the language itself. In Kaleidoscope, we can implement
+significant parts of the language in the library!
+
+We will break down implementation of these features into two parts:
+implementing support for user-defined binary operators and adding unary
+operators.
+
+User-defined Binary Operators
+=============================
+
+Adding support for user-defined binary operators is pretty simple with
+our current framework. We'll first add support for the unary/binary
+keywords:
+
+.. code-block:: c++
+
+ enum Token {
+ ...
+ // operators
+ tok_binary = -11,
+ tok_unary = -12
+ };
+ ...
+ static int gettok() {
+ ...
+ if (IdentifierStr == "for")
+ return tok_for;
+ if (IdentifierStr == "in")
+ return tok_in;
+ if (IdentifierStr == "binary")
+ return tok_binary;
+ if (IdentifierStr == "unary")
+ return tok_unary;
+ return tok_identifier;
+
+This just adds lexer support for the unary and binary keywords, like we
+did in `previous chapters <LangImpl5.html#lexer-extensions-for-if-then-else>`_. One nice thing
+about our current AST, is that we represent binary operators with full
+generalisation by using their ASCII code as the opcode. For our extended
+operators, we'll use this same representation, so we don't need any new
+AST or parser support.
+
+On the other hand, we have to be able to represent the definitions of
+these new operators, in the "def binary\| 5" part of the function
+definition. In our grammar so far, the "name" for the function
+definition is parsed as the "prototype" production and into the
+``PrototypeAST`` AST node. To represent our new user-defined operators
+as prototypes, we have to extend the ``PrototypeAST`` AST node like
+this:
+
+.. code-block:: c++
+
+ /// PrototypeAST - This class represents the "prototype" for a function,
+ /// which captures its argument names as well as if it is an operator.
+ class PrototypeAST {
+ std::string Name;
+ std::vector<std::string> Args;
+ bool IsOperator;
+ unsigned Precedence; // Precedence if a binary op.
+
+ public:
+ PrototypeAST(const std::string &name, std::vector<std::string> Args,
+ bool IsOperator = false, unsigned Prec = 0)
+ : Name(name), Args(std::move(Args)), IsOperator(IsOperator),
+ Precedence(Prec) {}
+
+ bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
+ bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
+
+ char getOperatorName() const {
+ assert(isUnaryOp() || isBinaryOp());
+ return Name[Name.size()-1];
+ }
+
+ unsigned getBinaryPrecedence() const { return Precedence; }
+
+ Function *codegen();
+ };
+
+Basically, in addition to knowing a name for the prototype, we now keep
+track of whether it was an operator, and if it was, what precedence
+level the operator is at. The precedence is only used for binary
+operators (as you'll see below, it just doesn't apply for unary
+operators). Now that we have a way to represent the prototype for a
+user-defined operator, we need to parse it:
+
+.. code-block:: c++
+
+ /// prototype
+ /// ::= id '(' id* ')'
+ /// ::= binary LETTER number? (id, id)
+ static std::unique_ptr<PrototypeAST> ParsePrototype() {
+ std::string FnName;
+
+ unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
+ unsigned BinaryPrecedence = 30;
+
+ switch (CurTok) {
+ default:
+ return LogErrorP("Expected function name in prototype");
+ case tok_identifier:
+ FnName = IdentifierStr;
+ Kind = 0;
+ getNextToken();
+ break;
+ case tok_binary:
+ getNextToken();
+ if (!isascii(CurTok))
+ return LogErrorP("Expected binary operator");
+ FnName = "binary";
+ FnName += (char)CurTok;
+ Kind = 2;
+ getNextToken();
+
+ // Read the precedence if present.
+ if (CurTok == tok_number) {
+ if (NumVal < 1 || NumVal > 100)
+ return LogErrorP("Invalid precedecnce: must be 1..100");
+ BinaryPrecedence = (unsigned)NumVal;
+ getNextToken();
+ }
+ break;
+ }
+
+ if (CurTok != '(')
+ return LogErrorP("Expected '(' in prototype");
+
+ std::vector<std::string> ArgNames;
+ while (getNextToken() == tok_identifier)
+ ArgNames.push_back(IdentifierStr);
+ if (CurTok != ')')
+ return LogErrorP("Expected ')' in prototype");
+
+ // success.
+ getNextToken(); // eat ')'.
+
+ // Verify right number of names for operator.
+ if (Kind && ArgNames.size() != Kind)
+ return LogErrorP("Invalid number of operands for operator");
+
+ return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,
+ BinaryPrecedence);
+ }
+
+This is all fairly straightforward parsing code, and we have already
+seen a lot of similar code in the past. One interesting part about the
+code above is the couple lines that set up ``FnName`` for binary
+operators. This builds names like "binary@" for a newly defined "@"
+operator. This then takes advantage of the fact that symbol names in the
+LLVM symbol table are allowed to have any character in them, including
+embedded nul characters.
+
+The next interesting thing to add, is codegen support for these binary
+operators. Given our current structure, this is a simple addition of a
+default case for our existing binary operator node:
+
+.. code-block:: c++
+
+ Value *BinaryExprAST::codegen() {
+ Value *L = LHS->codegen();
+ Value *R = RHS->codegen();
+ if (!L || !R)
+ return nullptr;
+
+ switch (Op) {
+ case '+':
+ return Builder.CreateFAdd(L, R, "addtmp");
+ case '-':
+ return Builder.CreateFSub(L, R, "subtmp");
+ case '*':
+ return Builder.CreateFMul(L, R, "multmp");
+ case '<':
+ L = Builder.CreateFCmpULT(L, R, "cmptmp");
+ // Convert bool 0/1 to double 0.0 or 1.0
+ return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
+ "booltmp");
+ default:
+ break;
+ }
+
+ // If it wasn't a builtin binary operator, it must be a user defined one. Emit
+ // a call to it.
+ Function *F = TheModule->getFunction(std::string("binary") + Op);
+ assert(F && "binary operator not found!");
+
+ Value *Ops[2] = { L, R };
+ return Builder.CreateCall(F, Ops, "binop");
+ }
+
+As you can see above, the new code is actually really simple. It just
+does a lookup for the appropriate operator in the symbol table and
+generates a function call to it. Since user-defined operators are just
+built as normal functions (because the "prototype" boils down to a
+function with the right name) everything falls into place.
+
+The final piece of code we are missing, is a bit of top-level magic:
+
+.. code-block:: c++
+
+ Function *FunctionAST::codegen() {
+ NamedValues.clear();
+
+ Function *TheFunction = Proto->codegen();
+ if (!TheFunction)
+ return nullptr;
+
+ // If this is an operator, install it.
+ if (Proto->isBinaryOp())
+ BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
+
+ // Create a new basic block to start insertion into.
+ BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
+ Builder.SetInsertPoint(BB);
+
+ if (Value *RetVal = Body->codegen()) {
+ ...
+
+Basically, before codegening a function, if it is a user-defined
+operator, we register it in the precedence table. This allows the binary
+operator parsing logic we already have in place to handle it. Since we
+are working on a fully-general operator precedence parser, this is all
+we need to do to "extend the grammar".
+
+Now we have useful user-defined binary operators. This builds a lot on
+the previous framework we built for other operators. Adding unary
+operators is a bit more challenging, because we don't have any framework
+for it yet - lets see what it takes.
+
+User-defined Unary Operators
+============================
+
+Since we don't currently support unary operators in the Kaleidoscope
+language, we'll need to add everything to support them. Above, we added
+simple support for the 'unary' keyword to the lexer. In addition to
+that, we need an AST node:
+
+.. code-block:: c++
+
+ /// UnaryExprAST - Expression class for a unary operator.
+ class UnaryExprAST : public ExprAST {
+ char Opcode;
+ std::unique_ptr<ExprAST> Operand;
+
+ public:
+ UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
+ : Opcode(Opcode), Operand(std::move(Operand)) {}
+ virtual Value *codegen();
+ };
+
+This AST node is very simple and obvious by now. It directly mirrors the
+binary operator AST node, except that it only has one child. With this,
+we need to add the parsing logic. Parsing a unary operator is pretty
+simple: we'll add a new function to do it:
+
+.. code-block:: c++
+
+ /// unary
+ /// ::= primary
+ /// ::= '!' unary
+ static std::unique_ptr<ExprAST> ParseUnary() {
+ // If the current token is not an operator, it must be a primary expr.
+ if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
+ return ParsePrimary();
+
+ // If this is a unary operator, read it.
+ int Opc = CurTok;
+ getNextToken();
+ if (auto Operand = ParseUnary())
+ return llvm::unique_ptr<UnaryExprAST>(Opc, std::move(Operand));
+ return nullptr;
+ }
+
+The grammar we add is pretty straightforward here. If we see a unary
+operator when parsing a primary operator, we eat the operator as a
+prefix and parse the remaining piece as another unary operator. This
+allows us to handle multiple unary operators (e.g. "!!x"). Note that
+unary operators can't have ambiguous parses like binary operators can,
+so there is no need for precedence information.
+
+The problem with this function, is that we need to call ParseUnary from
+somewhere. To do this, we change previous callers of ParsePrimary to
+call ParseUnary instead:
+
+.. code-block:: c++
+
+ /// binoprhs
+ /// ::= ('+' unary)*
+ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
+ std::unique_ptr<ExprAST> LHS) {
+ ...
+ // Parse the unary expression after the binary operator.
+ auto RHS = ParseUnary();
+ if (!RHS)
+ return nullptr;
+ ...
+ }
+ /// expression
+ /// ::= unary binoprhs
+ ///
+ static std::unique_ptr<ExprAST> ParseExpression() {
+ auto LHS = ParseUnary();
+ if (!LHS)
+ return nullptr;
+
+ return ParseBinOpRHS(0, std::move(LHS));
+ }
+
+With these two simple changes, we are now able to parse unary operators
+and build the AST for them. Next up, we need to add parser support for
+prototypes, to parse the unary operator prototype. We extend the binary
+operator code above with:
+
+.. code-block:: c++
+
+ /// prototype
+ /// ::= id '(' id* ')'
+ /// ::= binary LETTER number? (id, id)
+ /// ::= unary LETTER (id)
+ static std::unique_ptr<PrototypeAST> ParsePrototype() {
+ std::string FnName;
+
+ unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
+ unsigned BinaryPrecedence = 30;
+
+ switch (CurTok) {
+ default:
+ return LogErrorP("Expected function name in prototype");
+ case tok_identifier:
+ FnName = IdentifierStr;
+ Kind = 0;
+ getNextToken();
+ break;
+ case tok_unary:
+ getNextToken();
+ if (!isascii(CurTok))
+ return LogErrorP("Expected unary operator");
+ FnName = "unary";
+ FnName += (char)CurTok;
+ Kind = 1;
+ getNextToken();
+ break;
+ case tok_binary:
+ ...
+
+As with binary operators, we name unary operators with a name that
+includes the operator character. This assists us at code generation
+time. Speaking of, the final piece we need to add is codegen support for
+unary operators. It looks like this:
+
+.. code-block:: c++
+
+ Value *UnaryExprAST::codegen() {
+ Value *OperandV = Operand->codegen();
+ if (!OperandV)
+ return nullptr;
+
+ Function *F = TheModule->getFunction(std::string("unary")+Opcode);
+ if (!F)
+ return LogErrorV("Unknown unary operator");
+
+ return Builder.CreateCall(F, OperandV, "unop");
+ }
+
+This code is similar to, but simpler than, the code for binary
+operators. It is simpler primarily because it doesn't need to handle any
+predefined operators.
+
+Kicking the Tires
+=================
+
+It is somewhat hard to believe, but with a few simple extensions we've
+covered in the last chapters, we have grown a real-ish language. With
+this, we can do a lot of interesting things, including I/O, math, and a
+bunch of other things. For example, we can now add a nice sequencing
+operator (printd is defined to print out the specified value and a
+newline):
+
+::
+
+ ready> extern printd(x);
+ Read extern:
+ declare double @printd(double)
+
+ ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
+ ..
+ ready> printd(123) : printd(456) : printd(789);
+ 123.000000
+ 456.000000
+ 789.000000
+ Evaluated to 0.000000
+
+We can also define a bunch of other "primitive" operations, such as:
+
+::
+
+ # Logical unary not.
+ def unary!(v)
+ if v then
+ 0
+ else
+ 1;
+
+ # Unary negate.
+ def unary-(v)
+ 0-v;
+
+ # Define > with the same precedence as <.
+ def binary> 10 (LHS RHS)
+ RHS < LHS;
+
+ # Binary logical or, which does not short circuit.
+ def binary| 5 (LHS RHS)
+ if LHS then
+ 1
+ else if RHS then
+ 1
+ else
+ 0;
+
+ # Binary logical and, which does not short circuit.
+ def binary& 6 (LHS RHS)
+ if !LHS then
+ 0
+ else
+ !!RHS;
+
+ # Define = with slightly lower precedence than relationals.
+ def binary = 9 (LHS RHS)
+ !(LHS < RHS | LHS > RHS);
+
+ # Define ':' for sequencing: as a low-precedence operator that ignores operands
+ # and just returns the RHS.
+ def binary : 1 (x y) y;
+
+Given the previous if/then/else support, we can also define interesting
+functions for I/O. For example, the following prints out a character
+whose "density" reflects the value passed in: the lower the value, the
+denser the character:
+
+::
+
+ ready>
+
+ extern putchard(char)
+ def printdensity(d)
+ if d > 8 then
+ putchard(32) # ' '
+ else if d > 4 then
+ putchard(46) # '.'
+ else if d > 2 then
+ putchard(43) # '+'
+ else
+ putchard(42); # '*'
+ ...
+ ready> printdensity(1): printdensity(2): printdensity(3):
+ printdensity(4): printdensity(5): printdensity(9):
+ putchard(10);
+ **++.
+ Evaluated to 0.000000
+
+Based on these simple primitive operations, we can start to define more
+interesting things. For example, here's a little function that solves
+for the number of iterations it takes a function in the complex plane to
+converge:
+
+::
+
+ # Determine whether the specific location diverges.
+ # Solve for z = z^2 + c in the complex plane.
+ def mandelconverger(real imag iters creal cimag)
+ if iters > 255 | (real*real + imag*imag > 4) then
+ iters
+ else
+ mandelconverger(real*real - imag*imag + creal,
+ 2*real*imag + cimag,
+ iters+1, creal, cimag);
+
+ # Return the number of iterations required for the iteration to escape
+ def mandelconverge(real imag)
+ mandelconverger(real, imag, 0, real, imag);
+
+This "``z = z2 + c``" function is a beautiful little creature that is
+the basis for computation of the `Mandelbrot
+Set <http://en.wikipedia.org/wiki/Mandelbrot_set>`_. Our
+``mandelconverge`` function returns the number of iterations that it
+takes for a complex orbit to escape, saturating to 255. This is not a
+very useful function by itself, but if you plot its value over a
+two-dimensional plane, you can see the Mandelbrot set. Given that we are
+limited to using putchard here, our amazing graphical output is limited,
+but we can whip together something using the density plotter above:
+
+::
+
+ # Compute and plot the mandelbrot set with the specified 2 dimensional range
+ # info.
+ def mandelhelp(xmin xmax xstep ymin ymax ystep)
+ for y = ymin, y < ymax, ystep in (
+ (for x = xmin, x < xmax, xstep in
+ printdensity(mandelconverge(x,y)))
+ : putchard(10)
+ )
+
+ # mandel - This is a convenient helper function for plotting the mandelbrot set
+ # from the specified position with the specified Magnification.
+ def mandel(realstart imagstart realmag imagmag)
+ mandelhelp(realstart, realstart+realmag*78, realmag,
+ imagstart, imagstart+imagmag*40, imagmag);
+
+Given this, we can try plotting out the mandelbrot set! Lets try it out:
+
+::
+
+ ready> mandel(-2.3, -1.3, 0.05, 0.07);
+ *******************************+++++++++++*************************************
+ *************************+++++++++++++++++++++++*******************************
+ **********************+++++++++++++++++++++++++++++****************************
+ *******************+++++++++++++++++++++.. ...++++++++*************************
+ *****************++++++++++++++++++++++.... ...+++++++++***********************
+ ***************+++++++++++++++++++++++..... ...+++++++++*********************
+ **************+++++++++++++++++++++++.... ....+++++++++********************
+ *************++++++++++++++++++++++...... .....++++++++*******************
+ ************+++++++++++++++++++++....... .......+++++++******************
+ ***********+++++++++++++++++++.... ... .+++++++*****************
+ **********+++++++++++++++++....... .+++++++****************
+ *********++++++++++++++........... ...+++++++***************
+ ********++++++++++++............ ...++++++++**************
+ ********++++++++++... .......... .++++++++**************
+ *******+++++++++..... .+++++++++*************
+ *******++++++++...... ..+++++++++*************
+ *******++++++....... ..+++++++++*************
+ *******+++++...... ..+++++++++*************
+ *******.... .... ...+++++++++*************
+ *******.... . ...+++++++++*************
+ *******+++++...... ...+++++++++*************
+ *******++++++....... ..+++++++++*************
+ *******++++++++...... .+++++++++*************
+ *******+++++++++..... ..+++++++++*************
+ ********++++++++++... .......... .++++++++**************
+ ********++++++++++++............ ...++++++++**************
+ *********++++++++++++++.......... ...+++++++***************
+ **********++++++++++++++++........ .+++++++****************
+ **********++++++++++++++++++++.... ... ..+++++++****************
+ ***********++++++++++++++++++++++....... .......++++++++*****************
+ ************+++++++++++++++++++++++...... ......++++++++******************
+ **************+++++++++++++++++++++++.... ....++++++++********************
+ ***************+++++++++++++++++++++++..... ...+++++++++*********************
+ *****************++++++++++++++++++++++.... ...++++++++***********************
+ *******************+++++++++++++++++++++......++++++++*************************
+ *********************++++++++++++++++++++++.++++++++***************************
+ *************************+++++++++++++++++++++++*******************************
+ ******************************+++++++++++++************************************
+ *******************************************************************************
+ *******************************************************************************
+ *******************************************************************************
+ Evaluated to 0.000000
+ ready> mandel(-2, -1, 0.02, 0.04);
+ **************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
+ ***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ *********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
+ *******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
+ *****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
+ ***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
+ **************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
+ ************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
+ ***********++++++++++++++++++++++++++++++++++++++++++++++++++........ .
+ **********++++++++++++++++++++++++++++++++++++++++++++++.............
+ ********+++++++++++++++++++++++++++++++++++++++++++..................
+ *******+++++++++++++++++++++++++++++++++++++++.......................
+ ******+++++++++++++++++++++++++++++++++++...........................
+ *****++++++++++++++++++++++++++++++++............................
+ *****++++++++++++++++++++++++++++...............................
+ ****++++++++++++++++++++++++++...... .........................
+ ***++++++++++++++++++++++++......... ...... ...........
+ ***++++++++++++++++++++++............
+ **+++++++++++++++++++++..............
+ **+++++++++++++++++++................
+ *++++++++++++++++++.................
+ *++++++++++++++++............ ...
+ *++++++++++++++..............
+ *+++....++++................
+ *.......... ...........
+ *
+ *.......... ...........
+ *+++....++++................
+ *++++++++++++++..............
+ *++++++++++++++++............ ...
+ *++++++++++++++++++.................
+ **+++++++++++++++++++................
+ **+++++++++++++++++++++..............
+ ***++++++++++++++++++++++............
+ ***++++++++++++++++++++++++......... ...... ...........
+ ****++++++++++++++++++++++++++...... .........................
+ *****++++++++++++++++++++++++++++...............................
+ *****++++++++++++++++++++++++++++++++............................
+ ******+++++++++++++++++++++++++++++++++++...........................
+ *******+++++++++++++++++++++++++++++++++++++++.......................
+ ********+++++++++++++++++++++++++++++++++++++++++++..................
+ Evaluated to 0.000000
+ ready> mandel(-0.9, -1.4, 0.02, 0.03);
+ *******************************************************************************
+ *******************************************************************************
+ *******************************************************************************
+ **********+++++++++++++++++++++************************************************
+ *+++++++++++++++++++++++++++++++++++++++***************************************
+ +++++++++++++++++++++++++++++++++++++++++++++**********************************
+ ++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
+ ++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
+ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
+ +++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
+ +++++++++++++++++++++++++++++++.... ......+++++++++++++++++++****************
+ +++++++++++++++++++++++++++++....... ........+++++++++++++++++++**************
+ ++++++++++++++++++++++++++++........ ........++++++++++++++++++++************
+ +++++++++++++++++++++++++++......... .. ...+++++++++++++++++++++**********
+ ++++++++++++++++++++++++++........... ....++++++++++++++++++++++********
+ ++++++++++++++++++++++++............. .......++++++++++++++++++++++******
+ +++++++++++++++++++++++............. ........+++++++++++++++++++++++****
+ ++++++++++++++++++++++........... ..........++++++++++++++++++++++***
+ ++++++++++++++++++++........... .........++++++++++++++++++++++*
+ ++++++++++++++++++............ ...........++++++++++++++++++++
+ ++++++++++++++++............... .............++++++++++++++++++
+ ++++++++++++++................. ...............++++++++++++++++
+ ++++++++++++.................. .................++++++++++++++
+ +++++++++.................. .................+++++++++++++
+ ++++++........ . ......... ..++++++++++++
+ ++............ ...... ....++++++++++
+ .............. ...++++++++++
+ .............. ....+++++++++
+ .............. .....++++++++
+ ............. ......++++++++
+ ........... .......++++++++
+ ......... ........+++++++
+ ......... ........+++++++
+ ......... ....+++++++
+ ........ ...+++++++
+ ....... ...+++++++
+ ....+++++++
+ .....+++++++
+ ....+++++++
+ ....+++++++
+ ....+++++++
+ Evaluated to 0.000000
+ ready> ^D
+
+At this point, you may be starting to realize that Kaleidoscope is a
+real and powerful language. It may not be self-similar :), but it can be
+used to plot things that are!
+
+With this, we conclude the "adding user-defined operators" chapter of
+the tutorial. We have successfully augmented our language, adding the
+ability to extend the language in the library, and we have shown how
+this can be used to build a simple but interesting end-user application
+in Kaleidoscope. At this point, Kaleidoscope can build a variety of
+applications that are functional and can call functions with
+side-effects, but it can't actually define and mutate a variable itself.
+
+Strikingly, variable mutation is an important feature of some languages,
+and it is not at all obvious how to `add support for mutable
+variables <LangImpl7.html>`_ without having to add an "SSA construction"
+phase to your front-end. In the next chapter, we will describe how you
+can add variable mutation without building SSA in your front-end.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+the if/then/else and for expressions.. To build this example, use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
+ # Run
+ ./toy
+
+On some platforms, you will need to specify -rdynamic or
+-Wl,--export-dynamic when linking. This ensures that symbols defined in
+the main executable are exported to the dynamic linker and so are
+available for symbol resolution at run time. This is not needed if you
+compile your support code into a shared library, although doing that
+will cause problems on Windows.
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter6/toy.cpp
+ :language: c++
+
+`Next: Extending the language: mutable variables / SSA
+construction <LangImpl07.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl07.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl07.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl07.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl07.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,881 @@
+=======================================================
+Kaleidoscope: Extending the Language: Mutable Variables
+=======================================================
+
+.. contents::
+ :local:
+
+Chapter 7 Introduction
+======================
+
+Welcome to Chapter 7 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. In chapters 1 through 6, we've built a
+very respectable, albeit simple, `functional programming
+language <http://en.wikipedia.org/wiki/Functional_programming>`_. In our
+journey, we learned some parsing techniques, how to build and represent
+an AST, how to build LLVM IR, and how to optimize the resultant code as
+well as JIT compile it.
+
+While Kaleidoscope is interesting as a functional language, the fact
+that it is functional makes it "too easy" to generate LLVM IR for it. In
+particular, a functional language makes it very easy to build LLVM IR
+directly in `SSA
+form <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
+Since LLVM requires that the input code be in SSA form, this is a very
+nice property and it is often unclear to newcomers how to generate code
+for an imperative language with mutable variables.
+
+The short (and happy) summary of this chapter is that there is no need
+for your front-end to build SSA form: LLVM provides highly tuned and
+well tested support for this, though the way it works is a bit
+unexpected for some.
+
+Why is this a hard problem?
+===========================
+
+To understand why mutable variables cause complexities in SSA
+construction, consider this extremely simple C example:
+
+.. code-block:: c
+
+ int G, H;
+ int test(_Bool Condition) {
+ int X;
+ if (Condition)
+ X = G;
+ else
+ X = H;
+ return X;
+ }
+
+In this case, we have the variable "X", whose value depends on the path
+executed in the program. Because there are two different possible values
+for X before the return instruction, a PHI node is inserted to merge the
+two values. The LLVM IR that we want for this example looks like this:
+
+.. code-block:: llvm
+
+ @G = weak global i32 0 ; type of @G is i32*
+ @H = weak global i32 0 ; type of @H is i32*
+
+ define i32 @test(i1 %Condition) {
+ entry:
+ br i1 %Condition, label %cond_true, label %cond_false
+
+ cond_true:
+ %X.0 = load i32* @G
+ br label %cond_next
+
+ cond_false:
+ %X.1 = load i32* @H
+ br label %cond_next
+
+ cond_next:
+ %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
+ ret i32 %X.2
+ }
+
+In this example, the loads from the G and H global variables are
+explicit in the LLVM IR, and they live in the then/else branches of the
+if statement (cond\_true/cond\_false). In order to merge the incoming
+values, the X.2 phi node in the cond\_next block selects the right value
+to use based on where control flow is coming from: if control flow comes
+from the cond\_false block, X.2 gets the value of X.1. Alternatively, if
+control flow comes from cond\_true, it gets the value of X.0. The intent
+of this chapter is not to explain the details of SSA form. For more
+information, see one of the many `online
+references <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
+
+The question for this article is "who places the phi nodes when lowering
+assignments to mutable variables?". The issue here is that LLVM
+*requires* that its IR be in SSA form: there is no "non-ssa" mode for
+it. However, SSA construction requires non-trivial algorithms and data
+structures, so it is inconvenient and wasteful for every front-end to
+have to reproduce this logic.
+
+Memory in LLVM
+==============
+
+The 'trick' here is that while LLVM does require all register values to
+be in SSA form, it does not require (or permit) memory objects to be in
+SSA form. In the example above, note that the loads from G and H are
+direct accesses to G and H: they are not renamed or versioned. This
+differs from some other compiler systems, which do try to version memory
+objects. In LLVM, instead of encoding dataflow analysis of memory into
+the LLVM IR, it is handled with `Analysis
+Passes <../WritingAnLLVMPass.html>`_ which are computed on demand.
+
+With this in mind, the high-level idea is that we want to make a stack
+variable (which lives in memory, because it is on the stack) for each
+mutable object in a function. To take advantage of this trick, we need
+to talk about how LLVM represents stack variables.
+
+In LLVM, all memory accesses are explicit with load/store instructions,
+and it is carefully designed not to have (or need) an "address-of"
+operator. Notice how the type of the @G/@H global variables is actually
+"i32\*" even though the variable is defined as "i32". What this means is
+that @G defines *space* for an i32 in the global data area, but its
+*name* actually refers to the address for that space. Stack variables
+work the same way, except that instead of being declared with global
+variable definitions, they are declared with the `LLVM alloca
+instruction <../LangRef.html#alloca-instruction>`_:
+
+.. code-block:: llvm
+
+ define i32 @example() {
+ entry:
+ %X = alloca i32 ; type of %X is i32*.
+ ...
+ %tmp = load i32* %X ; load the stack value %X from the stack.
+ %tmp2 = add i32 %tmp, 1 ; increment it
+ store i32 %tmp2, i32* %X ; store it back
+ ...
+
+This code shows an example of how you can declare and manipulate a stack
+variable in the LLVM IR. Stack memory allocated with the alloca
+instruction is fully general: you can pass the address of the stack slot
+to functions, you can store it in other variables, etc. In our example
+above, we could rewrite the example to use the alloca technique to avoid
+using a PHI node:
+
+.. code-block:: llvm
+
+ @G = weak global i32 0 ; type of @G is i32*
+ @H = weak global i32 0 ; type of @H is i32*
+
+ define i32 @test(i1 %Condition) {
+ entry:
+ %X = alloca i32 ; type of %X is i32*.
+ br i1 %Condition, label %cond_true, label %cond_false
+
+ cond_true:
+ %X.0 = load i32* @G
+ store i32 %X.0, i32* %X ; Update X
+ br label %cond_next
+
+ cond_false:
+ %X.1 = load i32* @H
+ store i32 %X.1, i32* %X ; Update X
+ br label %cond_next
+
+ cond_next:
+ %X.2 = load i32* %X ; Read X
+ ret i32 %X.2
+ }
+
+With this, we have discovered a way to handle arbitrary mutable
+variables without the need to create Phi nodes at all:
+
+#. Each mutable variable becomes a stack allocation.
+#. Each read of the variable becomes a load from the stack.
+#. Each update of the variable becomes a store to the stack.
+#. Taking the address of a variable just uses the stack address
+ directly.
+
+While this solution has solved our immediate problem, it introduced
+another one: we have now apparently introduced a lot of stack traffic
+for very simple and common operations, a major performance problem.
+Fortunately for us, the LLVM optimizer has a highly-tuned optimization
+pass named "mem2reg" that handles this case, promoting allocas like this
+into SSA registers, inserting Phi nodes as appropriate. If you run this
+example through the pass, for example, you'll get:
+
+.. code-block:: bash
+
+ $ llvm-as < example.ll | opt -mem2reg | llvm-dis
+ @G = weak global i32 0
+ @H = weak global i32 0
+
+ define i32 @test(i1 %Condition) {
+ entry:
+ br i1 %Condition, label %cond_true, label %cond_false
+
+ cond_true:
+ %X.0 = load i32* @G
+ br label %cond_next
+
+ cond_false:
+ %X.1 = load i32* @H
+ br label %cond_next
+
+ cond_next:
+ %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
+ ret i32 %X.01
+ }
+
+The mem2reg pass implements the standard "iterated dominance frontier"
+algorithm for constructing SSA form and has a number of optimizations
+that speed up (very common) degenerate cases. The mem2reg optimization
+pass is the answer to dealing with mutable variables, and we highly
+recommend that you depend on it. Note that mem2reg only works on
+variables in certain circumstances:
+
+#. mem2reg is alloca-driven: it looks for allocas and if it can handle
+ them, it promotes them. It does not apply to global variables or heap
+ allocations.
+#. mem2reg only looks for alloca instructions in the entry block of the
+ function. Being in the entry block guarantees that the alloca is only
+ executed once, which makes analysis simpler.
+#. mem2reg only promotes allocas whose uses are direct loads and stores.
+ If the address of the stack object is passed to a function, or if any
+ funny pointer arithmetic is involved, the alloca will not be
+ promoted.
+#. mem2reg only works on allocas of `first
+ class <../LangRef.html#first-class-types>`_ values (such as pointers,
+ scalars and vectors), and only if the array size of the allocation is
+ 1 (or missing in the .ll file). mem2reg is not capable of promoting
+ structs or arrays to registers. Note that the "sroa" pass is
+ more powerful and can promote structs, "unions", and arrays in many
+ cases.
+
+All of these properties are easy to satisfy for most imperative
+languages, and we'll illustrate it below with Kaleidoscope. The final
+question you may be asking is: should I bother with this nonsense for my
+front-end? Wouldn't it be better if I just did SSA construction
+directly, avoiding use of the mem2reg optimization pass? In short, we
+strongly recommend that you use this technique for building SSA form,
+unless there is an extremely good reason not to. Using this technique
+is:
+
+- Proven and well tested: clang uses this technique
+ for local mutable variables. As such, the most common clients of LLVM
+ are using this to handle a bulk of their variables. You can be sure
+ that bugs are found fast and fixed early.
+- Extremely Fast: mem2reg has a number of special cases that make it
+ fast in common cases as well as fully general. For example, it has
+ fast-paths for variables that are only used in a single block,
+ variables that only have one assignment point, good heuristics to
+ avoid insertion of unneeded phi nodes, etc.
+- Needed for debug info generation: `Debug information in
+ LLVM <../SourceLevelDebugging.html>`_ relies on having the address of
+ the variable exposed so that debug info can be attached to it. This
+ technique dovetails very naturally with this style of debug info.
+
+If nothing else, this makes it much easier to get your front-end up and
+running, and is very simple to implement. Let's extend Kaleidoscope with
+mutable variables now!
+
+Mutable Variables in Kaleidoscope
+=================================
+
+Now that we know the sort of problem we want to tackle, let's see what
+this looks like in the context of our little Kaleidoscope language.
+We're going to add two features:
+
+#. The ability to mutate variables with the '=' operator.
+#. The ability to define new variables.
+
+While the first item is really what this is about, we only have
+variables for incoming arguments as well as for induction variables, and
+redefining those only goes so far :). Also, the ability to define new
+variables is a useful thing regardless of whether you will be mutating
+them. Here's a motivating example that shows how we could use these:
+
+::
+
+ # Define ':' for sequencing: as a low-precedence operator that ignores operands
+ # and just returns the RHS.
+ def binary : 1 (x y) y;
+
+ # Recursive fib, we could do this before.
+ def fib(x)
+ if (x < 3) then
+ 1
+ else
+ fib(x-1)+fib(x-2);
+
+ # Iterative fib.
+ def fibi(x)
+ var a = 1, b = 1, c in
+ (for i = 3, i < x in
+ c = a + b :
+ a = b :
+ b = c) :
+ b;
+
+ # Call it.
+ fibi(10);
+
+In order to mutate variables, we have to change our existing variables
+to use the "alloca trick". Once we have that, we'll add our new
+operator, then extend Kaleidoscope to support new variable definitions.
+
+Adjusting Existing Variables for Mutation
+=========================================
+
+The symbol table in Kaleidoscope is managed at code generation time by
+the '``NamedValues``' map. This map currently keeps track of the LLVM
+"Value\*" that holds the double value for the named variable. In order
+to support mutation, we need to change this slightly, so that
+``NamedValues`` holds the *memory location* of the variable in question.
+Note that this change is a refactoring: it changes the structure of the
+code, but does not (by itself) change the behavior of the compiler. All
+of these changes are isolated in the Kaleidoscope code generator.
+
+At this point in Kaleidoscope's development, it only supports variables
+for two things: incoming arguments to functions and the induction
+variable of 'for' loops. For consistency, we'll allow mutation of these
+variables in addition to other user-defined variables. This means that
+these will both need memory locations.
+
+To start our transformation of Kaleidoscope, we'll change the
+NamedValues map so that it maps to AllocaInst\* instead of Value\*. Once
+we do this, the C++ compiler will tell us what parts of the code we need
+to update:
+
+.. code-block:: c++
+
+ static std::map<std::string, AllocaInst*> NamedValues;
+
+Also, since we will need to create these alloca's, we'll use a helper
+function that ensures that the allocas are created in the entry block of
+the function:
+
+.. code-block:: c++
+
+ /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
+ /// the function. This is used for mutable variables etc.
+ static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
+ const std::string &VarName) {
+ IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
+ TheFunction->getEntryBlock().begin());
+ return TmpB.CreateAlloca(Type::getDoubleTy(LLVMContext), 0,
+ VarName.c_str());
+ }
+
+This funny looking code creates an IRBuilder object that is pointing at
+the first instruction (.begin()) of the entry block. It then creates an
+alloca with the expected name and returns it. Because all values in
+Kaleidoscope are doubles, there is no need to pass in a type to use.
+
+With this in place, the first functionality change we want to make is to
+variable references. In our new scheme, variables live on the stack, so
+code generating a reference to them actually needs to produce a load
+from the stack slot:
+
+.. code-block:: c++
+
+ Value *VariableExprAST::codegen() {
+ // Look this variable up in the function.
+ Value *V = NamedValues[Name];
+ if (!V)
+ return LogErrorV("Unknown variable name");
+
+ // Load the value.
+ return Builder.CreateLoad(V, Name.c_str());
+ }
+
+As you can see, this is pretty straightforward. Now we need to update
+the things that define the variables to set up the alloca. We'll start
+with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for
+the unabridged code):
+
+.. code-block:: c++
+
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Create an alloca for the variable in the entry block.
+ AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
+
+ // Emit the start code first, without 'variable' in scope.
+ Value *StartVal = Start->codegen();
+ if (!StartVal)
+ return nullptr;
+
+ // Store the value into the alloca.
+ Builder.CreateStore(StartVal, Alloca);
+ ...
+
+ // Compute the end condition.
+ Value *EndCond = End->codegen();
+ if (!EndCond)
+ return nullptr;
+
+ // Reload, increment, and restore the alloca. This handles the case where
+ // the body of the loop mutates the variable.
+ Value *CurVar = Builder.CreateLoad(Alloca);
+ Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
+ Builder.CreateStore(NextVar, Alloca);
+ ...
+
+This code is virtually identical to the code `before we allowed mutable
+variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we
+no longer have to construct a PHI node, and we use load/store to access
+the variable as needed.
+
+To support mutable argument variables, we need to also make allocas for
+them. The code for this is also pretty simple:
+
+.. code-block:: c++
+
+ /// CreateArgumentAllocas - Create an alloca for each argument and register the
+ /// argument in the symbol table so that references to it will succeed.
+ void PrototypeAST::CreateArgumentAllocas(Function *F) {
+ Function::arg_iterator AI = F->arg_begin();
+ for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {
+ // Create an alloca for this variable.
+ AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);
+
+ // Store the initial value into the alloca.
+ Builder.CreateStore(AI, Alloca);
+
+ // Add arguments to variable symbol table.
+ NamedValues[Args[Idx]] = Alloca;
+ }
+ }
+
+For each argument, we make an alloca, store the input value to the
+function into the alloca, and register the alloca as the memory location
+for the argument. This method gets invoked by ``FunctionAST::codegen()``
+right after it sets up the entry block for the function.
+
+The final missing piece is adding the mem2reg pass, which allows us to
+get good codegen once again:
+
+.. code-block:: c++
+
+ // Set up the optimizer pipeline. Start with registering info about how the
+ // target lays out data structures.
+ OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout()));
+ // Promote allocas to registers.
+ OurFPM.add(createPromoteMemoryToRegisterPass());
+ // Do simple "peephole" optimizations and bit-twiddling optzns.
+ OurFPM.add(createInstructionCombiningPass());
+ // Reassociate expressions.
+ OurFPM.add(createReassociatePass());
+
+It is interesting to see what the code looks like before and after the
+mem2reg optimization runs. For example, this is the before/after code
+for our recursive fib function. Before the optimization:
+
+.. code-block:: llvm
+
+ define double @fib(double %x) {
+ entry:
+ %x1 = alloca double
+ store double %x, double* %x1
+ %x2 = load double* %x1
+ %cmptmp = fcmp ult double %x2, 3.000000e+00
+ %booltmp = uitofp i1 %cmptmp to double
+ %ifcond = fcmp one double %booltmp, 0.000000e+00
+ br i1 %ifcond, label %then, label %else
+
+ then: ; preds = %entry
+ br label %ifcont
+
+ else: ; preds = %entry
+ %x3 = load double* %x1
+ %subtmp = fsub double %x3, 1.000000e+00
+ %calltmp = call double @fib(double %subtmp)
+ %x4 = load double* %x1
+ %subtmp5 = fsub double %x4, 2.000000e+00
+ %calltmp6 = call double @fib(double %subtmp5)
+ %addtmp = fadd double %calltmp, %calltmp6
+ br label %ifcont
+
+ ifcont: ; preds = %else, %then
+ %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
+ ret double %iftmp
+ }
+
+Here there is only one variable (x, the input argument) but you can
+still see the extremely simple-minded code generation strategy we are
+using. In the entry block, an alloca is created, and the initial input
+value is stored into it. Each reference to the variable does a reload
+from the stack. Also, note that we didn't modify the if/then/else
+expression, so it still inserts a PHI node. While we could make an
+alloca for it, it is actually easier to create a PHI node for it, so we
+still just make the PHI.
+
+Here is the code after the mem2reg pass runs:
+
+.. code-block:: llvm
+
+ define double @fib(double %x) {
+ entry:
+ %cmptmp = fcmp ult double %x, 3.000000e+00
+ %booltmp = uitofp i1 %cmptmp to double
+ %ifcond = fcmp one double %booltmp, 0.000000e+00
+ br i1 %ifcond, label %then, label %else
+
+ then:
+ br label %ifcont
+
+ else:
+ %subtmp = fsub double %x, 1.000000e+00
+ %calltmp = call double @fib(double %subtmp)
+ %subtmp5 = fsub double %x, 2.000000e+00
+ %calltmp6 = call double @fib(double %subtmp5)
+ %addtmp = fadd double %calltmp, %calltmp6
+ br label %ifcont
+
+ ifcont: ; preds = %else, %then
+ %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
+ ret double %iftmp
+ }
+
+This is a trivial case for mem2reg, since there are no redefinitions of
+the variable. The point of showing this is to calm your tension about
+inserting such blatent inefficiencies :).
+
+After the rest of the optimizers run, we get:
+
+.. code-block:: llvm
+
+ define double @fib(double %x) {
+ entry:
+ %cmptmp = fcmp ult double %x, 3.000000e+00
+ %booltmp = uitofp i1 %cmptmp to double
+ %ifcond = fcmp ueq double %booltmp, 0.000000e+00
+ br i1 %ifcond, label %else, label %ifcont
+
+ else:
+ %subtmp = fsub double %x, 1.000000e+00
+ %calltmp = call double @fib(double %subtmp)
+ %subtmp5 = fsub double %x, 2.000000e+00
+ %calltmp6 = call double @fib(double %subtmp5)
+ %addtmp = fadd double %calltmp, %calltmp6
+ ret double %addtmp
+
+ ifcont:
+ ret double 1.000000e+00
+ }
+
+Here we see that the simplifycfg pass decided to clone the return
+instruction into the end of the 'else' block. This allowed it to
+eliminate some branches and the PHI node.
+
+Now that all symbol table references are updated to use stack variables,
+we'll add the assignment operator.
+
+New Assignment Operator
+=======================
+
+With our current framework, adding a new assignment operator is really
+simple. We will parse it just like any other binary operator, but handle
+it internally (instead of allowing the user to define it). The first
+step is to set a precedence:
+
+.. code-block:: c++
+
+ int main() {
+ // Install standard binary operators.
+ // 1 is lowest precedence.
+ BinopPrecedence['='] = 2;
+ BinopPrecedence['<'] = 10;
+ BinopPrecedence['+'] = 20;
+ BinopPrecedence['-'] = 20;
+
+Now that the parser knows the precedence of the binary operator, it
+takes care of all the parsing and AST generation. We just need to
+implement codegen for the assignment operator. This looks like:
+
+.. code-block:: c++
+
+ Value *BinaryExprAST::codegen() {
+ // Special case '=' because we don't want to emit the LHS as an expression.
+ if (Op == '=') {
+ // Assignment requires the LHS to be an identifier.
+ VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());
+ if (!LHSE)
+ return LogErrorV("destination of '=' must be a variable");
+
+Unlike the rest of the binary operators, our assignment operator doesn't
+follow the "emit LHS, emit RHS, do computation" model. As such, it is
+handled as a special case before the other binary operators are handled.
+The other strange thing is that it requires the LHS to be a variable. It
+is invalid to have "(x+1) = expr" - only things like "x = expr" are
+allowed.
+
+.. code-block:: c++
+
+ // Codegen the RHS.
+ Value *Val = RHS->codegen();
+ if (!Val)
+ return nullptr;
+
+ // Look up the name.
+ Value *Variable = NamedValues[LHSE->getName()];
+ if (!Variable)
+ return LogErrorV("Unknown variable name");
+
+ Builder.CreateStore(Val, Variable);
+ return Val;
+ }
+ ...
+
+Once we have the variable, codegen'ing the assignment is
+straightforward: we emit the RHS of the assignment, create a store, and
+return the computed value. Returning a value allows for chained
+assignments like "X = (Y = Z)".
+
+Now that we have an assignment operator, we can mutate loop variables
+and arguments. For example, we can now run code like this:
+
+::
+
+ # Function to print a double.
+ extern printd(x);
+
+ # Define ':' for sequencing: as a low-precedence operator that ignores operands
+ # and just returns the RHS.
+ def binary : 1 (x y) y;
+
+ def test(x)
+ printd(x) :
+ x = 4 :
+ printd(x);
+
+ test(123);
+
+When run, this example prints "123" and then "4", showing that we did
+actually mutate the value! Okay, we have now officially implemented our
+goal: getting this to work requires SSA construction in the general
+case. However, to be really useful, we want the ability to define our
+own local variables, let's add this next!
+
+User-defined Local Variables
+============================
+
+Adding var/in is just like any other extension we made to
+Kaleidoscope: we extend the lexer, the parser, the AST and the code
+generator. The first step for adding our new 'var/in' construct is to
+extend the lexer. As before, this is pretty trivial, the code looks like
+this:
+
+.. code-block:: c++
+
+ enum Token {
+ ...
+ // var definition
+ tok_var = -13
+ ...
+ }
+ ...
+ static int gettok() {
+ ...
+ if (IdentifierStr == "in")
+ return tok_in;
+ if (IdentifierStr == "binary")
+ return tok_binary;
+ if (IdentifierStr == "unary")
+ return tok_unary;
+ if (IdentifierStr == "var")
+ return tok_var;
+ return tok_identifier;
+ ...
+
+The next step is to define the AST node that we will construct. For
+var/in, it looks like this:
+
+.. code-block:: c++
+
+ /// VarExprAST - Expression class for var/in
+ class VarExprAST : public ExprAST {
+ std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
+ std::unique_ptr<ExprAST> Body;
+
+ public:
+ VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
+ std::unique_ptr<ExprAST> body)
+ : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
+
+ virtual Value *codegen();
+ };
+
+var/in allows a list of names to be defined all at once, and each name
+can optionally have an initializer value. As such, we capture this
+information in the VarNames vector. Also, var/in has a body, this body
+is allowed to access the variables defined by the var/in.
+
+With this in place, we can define the parser pieces. The first thing we
+do is add it as a primary expression:
+
+.. code-block:: c++
+
+ /// primary
+ /// ::= identifierexpr
+ /// ::= numberexpr
+ /// ::= parenexpr
+ /// ::= ifexpr
+ /// ::= forexpr
+ /// ::= varexpr
+ static std::unique_ptr<ExprAST> ParsePrimary() {
+ switch (CurTok) {
+ default:
+ return LogError("unknown token when expecting an expression");
+ case tok_identifier:
+ return ParseIdentifierExpr();
+ case tok_number:
+ return ParseNumberExpr();
+ case '(':
+ return ParseParenExpr();
+ case tok_if:
+ return ParseIfExpr();
+ case tok_for:
+ return ParseForExpr();
+ case tok_var:
+ return ParseVarExpr();
+ }
+ }
+
+Next we define ParseVarExpr:
+
+.. code-block:: c++
+
+ /// varexpr ::= 'var' identifier ('=' expression)?
+ // (',' identifier ('=' expression)?)* 'in' expression
+ static std::unique_ptr<ExprAST> ParseVarExpr() {
+ getNextToken(); // eat the var.
+
+ std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
+
+ // At least one variable name is required.
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier after var");
+
+The first part of this code parses the list of identifier/expr pairs
+into the local ``VarNames`` vector.
+
+.. code-block:: c++
+
+ while (1) {
+ std::string Name = IdentifierStr;
+ getNextToken(); // eat identifier.
+
+ // Read the optional initializer.
+ std::unique_ptr<ExprAST> Init;
+ if (CurTok == '=') {
+ getNextToken(); // eat the '='.
+
+ Init = ParseExpression();
+ if (!Init) return nullptr;
+ }
+
+ VarNames.push_back(std::make_pair(Name, std::move(Init)));
+
+ // End of var list, exit loop.
+ if (CurTok != ',') break;
+ getNextToken(); // eat the ','.
+
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier list after var");
+ }
+
+Once all the variables are parsed, we then parse the body and create the
+AST node:
+
+.. code-block:: c++
+
+ // At this point, we have to have 'in'.
+ if (CurTok != tok_in)
+ return LogError("expected 'in' keyword after 'var'");
+ getNextToken(); // eat 'in'.
+
+ auto Body = ParseExpression();
+ if (!Body)
+ return nullptr;
+
+ return llvm::make_unique<VarExprAST>(std::move(VarNames),
+ std::move(Body));
+ }
+
+Now that we can parse and represent the code, we need to support
+emission of LLVM IR for it. This code starts out with:
+
+.. code-block:: c++
+
+ Value *VarExprAST::codegen() {
+ std::vector<AllocaInst *> OldBindings;
+
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Register all variables and emit their initializer.
+ for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
+ const std::string &VarName = VarNames[i].first;
+ ExprAST *Init = VarNames[i].second.get();
+
+Basically it loops over all the variables, installing them one at a
+time. For each variable we put into the symbol table, we remember the
+previous value that we replace in OldBindings.
+
+.. code-block:: c++
+
+ // Emit the initializer before adding the variable to scope, this prevents
+ // the initializer from referencing the variable itself, and permits stuff
+ // like this:
+ // var a = 1 in
+ // var a = a in ... # refers to outer 'a'.
+ Value *InitVal;
+ if (Init) {
+ InitVal = Init->codegen();
+ if (!InitVal)
+ return nullptr;
+ } else { // If not specified, use 0.0.
+ InitVal = ConstantFP::get(LLVMContext, APFloat(0.0));
+ }
+
+ AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
+ Builder.CreateStore(InitVal, Alloca);
+
+ // Remember the old variable binding so that we can restore the binding when
+ // we unrecurse.
+ OldBindings.push_back(NamedValues[VarName]);
+
+ // Remember this binding.
+ NamedValues[VarName] = Alloca;
+ }
+
+There are more comments here than code. The basic idea is that we emit
+the initializer, create the alloca, then update the symbol table to
+point to it. Once all the variables are installed in the symbol table,
+we evaluate the body of the var/in expression:
+
+.. code-block:: c++
+
+ // Codegen the body, now that all vars are in scope.
+ Value *BodyVal = Body->codegen();
+ if (!BodyVal)
+ return nullptr;
+
+Finally, before returning, we restore the previous variable bindings:
+
+.. code-block:: c++
+
+ // Pop all our variables from scope.
+ for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
+ NamedValues[VarNames[i].first] = OldBindings[i];
+
+ // Return the body computation.
+ return BodyVal;
+ }
+
+The end result of all of this is that we get properly scoped variable
+definitions, and we even (trivially) allow mutation of them :).
+
+With this, we completed what we set out to do. Our nice iterative fib
+example from the intro compiles and runs just fine. The mem2reg pass
+optimizes all of our stack variables into SSA registers, inserting PHI
+nodes where needed, and our front-end remains simple: no "iterated
+dominance frontier" computation anywhere in sight.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+mutable variables and var/in support. To build this example, use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
+ # Run
+ ./toy
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp
+ :language: c++
+
+`Next: Compiling to Object Code <LangImpl08.html>`_
+
Added: llvm/trunk/docs/tutorial/LangImpl08.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl08.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl08.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl08.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,218 @@
+========================================
+ Kaleidoscope: Compiling to Object Code
+========================================
+
+.. contents::
+ :local:
+
+Chapter 8 Introduction
+======================
+
+Welcome to Chapter 8 of the "`Implementing a language with LLVM
+<index.html>`_" tutorial. This chapter describes how to compile our
+language down to object files.
+
+Choosing a target
+=================
+
+LLVM has native support for cross-compilation. You can compile to the
+architecture of your current machine, or just as easily compile for
+other architectures. In this tutorial, we'll target the current
+machine.
+
+To specify the architecture that you want to target, we use a string
+called a "target triple". This takes the form
+``<arch><sub>-<vendor>-<sys>-<abi>`` (see the `cross compilation docs
+<http://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_).
+
+As an example, we can see what clang thinks is our current target
+triple:
+
+::
+
+ $ clang --version | grep Target
+ Target: x86_64-unknown-linux-gnu
+
+Running this command may show something different on your machine as
+you might be using a different architecture or operating system to me.
+
+Fortunately, we don't need to hard-code a target triple to target the
+current machine. LLVM provides ``sys::getDefaultTargetTriple``, which
+returns the target triple of the current machine.
+
+.. code-block:: c++
+
+ auto TargetTriple = sys::getDefaultTargetTriple();
+
+LLVM doesn't require us to to link in all the target
+functionality. For example, if we're just using the JIT, we don't need
+the assembly printers. Similarly, if we're only targetting certain
+architectures, we can only link in the functionality for those
+architectures.
+
+For this example, we'll initialize all the targets for emitting object
+code.
+
+.. code-block:: c++
+
+ InitializeAllTargetInfos();
+ InitializeAllTargets();
+ InitializeAllTargetMCs();
+ InitializeAllAsmParsers();
+ InitializeAllAsmPrinters();
+
+We can now use our target triple to get a ``Target``:
+
+.. code-block:: c++
+
+ std::string Error;
+ auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
+
+ // Print an error and exit if we couldn't find the requested target.
+ // This generally occurs if we've forgotten to initialise the
+ // TargetRegistry or we have a bogus target triple.
+ if (!Target) {
+ errs() << Error;
+ return 1;
+ }
+
+Target Machine
+==============
+
+We will also need a ``TargetMachine``. This class provides a complete
+machine description of the machine we're targetting. If we want to
+target a specific feature (such as SSE) or a specific CPU (such as
+Intel's Sandylake), we do so now.
+
+To see which features and CPUs that LLVM knows about, we can use
+``llc``. For example, let's look at x86:
+
+::
+
+ $ llvm-as < /dev/null | llc -march=x86 -mattr=help
+ Available CPUs for this target:
+
+ amdfam10 - Select the amdfam10 processor.
+ athlon - Select the athlon processor.
+ athlon-4 - Select the athlon-4 processor.
+ ...
+
+ Available features for this target:
+
+ 16bit-mode - 16-bit mode (i8086).
+ 32bit-mode - 32-bit mode (80386).
+ 3dnow - Enable 3DNow! instructions.
+ 3dnowa - Enable 3DNow! Athlon instructions.
+ ...
+
+For our example, we'll use the generic CPU without any additional
+features, options or relocation model.
+
+.. code-block:: c++
+
+ auto CPU = "generic";
+ auto Features = "";
+
+ TargetOptions opt;
+ auto RM = Optional<Reloc::Model>();
+ auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
+
+
+Configuring the Module
+======================
+
+We're now ready to configure our module, to specify the target and
+data layout. This isn't strictly necessary, but the `frontend
+performance guide <../Frontend/PerformanceTips.html>`_ recommends
+this. Optimizations benefit from knowing about the target and data
+layout.
+
+.. code-block:: c++
+
+ TheModule->setDataLayout(TargetMachine->createDataLayout());
+ TheModule->setTargetTriple(TargetTriple);
+
+Emit Object Code
+================
+
+We're ready to emit object code! Let's define where we want to write
+our file to:
+
+.. code-block:: c++
+
+ auto Filename = "output.o";
+ std::error_code EC;
+ raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
+
+ if (EC) {
+ errs() << "Could not open file: " << EC.message();
+ return 1;
+ }
+
+Finally, we define a pass that emits object code, then we run that
+pass:
+
+.. code-block:: c++
+
+ legacy::PassManager pass;
+ auto FileType = TargetMachine::CGFT_ObjectFile;
+
+ if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
+ errs() << "TargetMachine can't emit a file of this type";
+ return 1;
+ }
+
+ pass.run(*TheModule);
+ dest.flush();
+
+Putting It All Together
+=======================
+
+Does it work? Let's give it a try. We need to compile our code, but
+note that the arguments to ``llvm-config`` are different to the previous chapters.
+
+::
+
+ $ clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs all` -o toy
+
+Let's run it, and define a simple ``average`` function. Press Ctrl-D
+when you're done.
+
+::
+
+ $ ./toy
+ ready> def average(x y) (x + y) * 0.5;
+ ^D
+ Wrote output.o
+
+We have an object file! To test it, let's write a simple program and
+link it with our output. Here's the source code:
+
+.. code-block:: c++
+
+ #include <iostream>
+
+ extern "C" {
+ double average(double, double);
+ }
+
+ int main() {
+ std::cout << "average of 3.0 and 4.0: " << average(3.0, 4.0) << std::endl;
+ }
+
+We link our program to output.o and check the result is what we
+expected:
+
+::
+
+ $ clang++ main.cpp output.o -o main
+ $ ./main
+ average of 3.0 and 4.0: 3.5
+
+Full Code Listing
+=================
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp
+ :language: c++
+
+`Next: Adding Debug Information <LangImpl09.html>`_
Added: llvm/trunk/docs/tutorial/LangImpl09.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl09.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl09.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl09.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,462 @@
+======================================
+Kaleidoscope: Adding Debug Information
+======================================
+
+.. contents::
+ :local:
+
+Chapter 9 Introduction
+======================
+
+Welcome to Chapter 9 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. In chapters 1 through 8, we've built a
+decent little programming language with functions and variables.
+What happens if something goes wrong though, how do you debug your
+program?
+
+Source level debugging uses formatted data that helps a debugger
+translate from binary and the state of the machine back to the
+source that the programmer wrote. In LLVM we generally use a format
+called `DWARF <http://dwarfstd.org>`_. DWARF is a compact encoding
+that represents types, source locations, and variable locations.
+
+The short summary of this chapter is that we'll go through the
+various things you have to add to a programming language to
+support debug info, and how you translate that into DWARF.
+
+Caveat: For now we can't debug via the JIT, so we'll need to compile
+our program down to something small and standalone. As part of this
+we'll make a few modifications to the running of the language and
+how programs are compiled. This means that we'll have a source file
+with a simple program written in Kaleidoscope rather than the
+interactive JIT. It does involve a limitation that we can only
+have one "top level" command at a time to reduce the number of
+changes necessary.
+
+Here's the sample program we'll be compiling:
+
+.. code-block:: python
+
+ def fib(x)
+ if x < 3 then
+ 1
+ else
+ fib(x-1)+fib(x-2);
+
+ fib(10)
+
+
+Why is this a hard problem?
+===========================
+
+Debug information is a hard problem for a few different reasons - mostly
+centered around optimized code. First, optimization makes keeping source
+locations more difficult. In LLVM IR we keep the original source location
+for each IR level instruction on the instruction. Optimization passes
+should keep the source locations for newly created instructions, but merged
+instructions only get to keep a single location - this can cause jumping
+around when stepping through optimized programs. Secondly, optimization
+can move variables in ways that are either optimized out, shared in memory
+with other variables, or difficult to track. For the purposes of this
+tutorial we're going to avoid optimization (as you'll see with one of the
+next sets of patches).
+
+Ahead-of-Time Compilation Mode
+==============================
+
+To highlight only the aspects of adding debug information to a source
+language without needing to worry about the complexities of JIT debugging
+we're going to make a few changes to Kaleidoscope to support compiling
+the IR emitted by the front end into a simple standalone program that
+you can execute, debug, and see results.
+
+First we make our anonymous function that contains our top level
+statement be our "main":
+
+.. code-block:: udiff
+
+ - auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
+ + auto Proto = llvm::make_unique<PrototypeAST>("main", std::vector<std::string>());
+
+just with the simple change of giving it a name.
+
+Then we're going to remove the command line code wherever it exists:
+
+.. code-block:: udiff
+
+ @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() {
+ /// top ::= definition | external | expression | ';'
+ static void MainLoop() {
+ while (1) {
+ - fprintf(stderr, "ready> ");
+ switch (CurTok) {
+ case tok_eof:
+ return;
+ @@ -1184,7 +1183,6 @@ int main() {
+ BinopPrecedence['*'] = 40; // highest.
+
+ // Prime the first token.
+ - fprintf(stderr, "ready> ");
+ getNextToken();
+
+Lastly we're going to disable all of the optimization passes and the JIT so
+that the only thing that happens after we're done parsing and generating
+code is that the llvm IR goes to standard error:
+
+.. code-block:: udiff
+
+ @@ -1108,17 +1108,8 @@ static void HandleExtern() {
+ static void HandleTopLevelExpression() {
+ // Evaluate a top-level expression into an anonymous function.
+ if (auto FnAST = ParseTopLevelExpr()) {
+ - if (auto *FnIR = FnAST->codegen()) {
+ - // We're just doing this to make sure it executes.
+ - TheExecutionEngine->finalizeObject();
+ - // JIT the function, returning a function pointer.
+ - void *FPtr = TheExecutionEngine->getPointerToFunction(FnIR);
+ -
+ - // Cast it to the right type (takes no arguments, returns a double) so we
+ - // can call it as a native function.
+ - double (*FP)() = (double (*)())(intptr_t)FPtr;
+ - // Ignore the return value for this.
+ - (void)FP;
+ + if (!F->codegen()) {
+ + fprintf(stderr, "Error generating code for top level expr");
+ }
+ } else {
+ // Skip token for error recovery.
+ @@ -1439,11 +1459,11 @@ int main() {
+ // target lays out data structures.
+ TheModule->setDataLayout(TheExecutionEngine->getDataLayout());
+ OurFPM.add(new DataLayoutPass());
+ +#if 0
+ OurFPM.add(createBasicAliasAnalysisPass());
+ // Promote allocas to registers.
+ OurFPM.add(createPromoteMemoryToRegisterPass());
+ @@ -1218,7 +1210,7 @@ int main() {
+ OurFPM.add(createGVNPass());
+ // Simplify the control flow graph (deleting unreachable blocks, etc).
+ OurFPM.add(createCFGSimplificationPass());
+ -
+ + #endif
+ OurFPM.doInitialization();
+
+ // Set the global so the code gen can use this.
+
+This relatively small set of changes get us to the point that we can compile
+our piece of Kaleidoscope language down to an executable program via this
+command line:
+
+.. code-block:: bash
+
+ Kaleidoscope-Ch9 < fib.ks | & clang -x ir -
+
+which gives an a.out/a.exe in the current working directory.
+
+Compile Unit
+============
+
+The top level container for a section of code in DWARF is a compile unit.
+This contains the type and function data for an individual translation unit
+(read: one file of source code). So the first thing we need to do is
+construct one for our fib.ks file.
+
+DWARF Emission Setup
+====================
+
+Similar to the ``IRBuilder`` class we have a
+`DIBuilder <http://llvm.org/doxygen/classllvm_1_1DIBuilder.html>`_ class
+that helps in constructing debug metadata for an llvm IR file. It
+corresponds 1:1 similarly to ``IRBuilder`` and llvm IR, but with nicer names.
+Using it does require that you be more familiar with DWARF terminology than
+you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you
+read through the general documentation on the
+`Metadata Format <http://llvm.org/docs/SourceLevelDebugging.html>`_ it
+should be a little more clear. We'll be using this class to construct all
+of our IR level descriptions. Construction for it takes a module so we
+need to construct it shortly after we construct our module. We've left it
+as a global static variable to make it a bit easier to use.
+
+Next we're going to create a small container to cache some of our frequent
+data. The first will be our compile unit, but we'll also write a bit of
+code for our one type since we won't have to worry about multiple typed
+expressions:
+
+.. code-block:: c++
+
+ static DIBuilder *DBuilder;
+
+ struct DebugInfo {
+ DICompileUnit *TheCU;
+ DIType *DblTy;
+
+ DIType *getDoubleTy();
+ } KSDbgInfo;
+
+ DIType *DebugInfo::getDoubleTy() {
+ if (DblTy.isValid())
+ return DblTy;
+
+ DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);
+ return DblTy;
+ }
+
+And then later on in ``main`` when we're constructing our module:
+
+.. code-block:: c++
+
+ DBuilder = new DIBuilder(*TheModule);
+
+ KSDbgInfo.TheCU = DBuilder->createCompileUnit(
+ dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0);
+
+There are a couple of things to note here. First, while we're producing a
+compile unit for a language called Kaleidoscope we used the language
+constant for C. This is because a debugger wouldn't necessarily understand
+the calling conventions or default ABI for a language it doesn't recognize
+and we follow the C ABI in our llvm code generation so it's the closest
+thing to accurate. This ensures we can actually call functions from the
+debugger and have them execute. Secondly, you'll see the "fib.ks" in the
+call to ``createCompileUnit``. This is a default hard coded value since
+we're using shell redirection to put our source into the Kaleidoscope
+compiler. In a usual front end you'd have an input file name and it would
+go there.
+
+One last thing as part of emitting debug information via DIBuilder is that
+we need to "finalize" the debug information. The reasons are part of the
+underlying API for DIBuilder, but make sure you do this near the end of
+main:
+
+.. code-block:: c++
+
+ DBuilder->finalize();
+
+before you dump out the module.
+
+Functions
+=========
+
+Now that we have our ``Compile Unit`` and our source locations, we can add
+function definitions to the debug info. So in ``PrototypeAST::codegen()`` we
+add a few lines of code to describe a context for our subprogram, in this
+case the "File", and the actual definition of the function itself.
+
+So the context:
+
+.. code-block:: c++
+
+ DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),
+ KSDbgInfo.TheCU.getDirectory());
+
+giving us an DIFile and asking the ``Compile Unit`` we created above for the
+directory and filename where we are currently. Then, for now, we use some
+source locations of 0 (since our AST doesn't currently have source location
+information) and construct our function definition:
+
+.. code-block:: c++
+
+ DIScope *FContext = Unit;
+ unsigned LineNo = 0;
+ unsigned ScopeLine = 0;
+ DISubprogram *SP = DBuilder->createFunction(
+ FContext, Name, StringRef(), Unit, LineNo,
+ CreateFunctionType(Args.size(), Unit), false /* internal linkage */,
+ true /* definition */, ScopeLine, DINode::FlagPrototyped, false);
+ F->setSubprogram(SP);
+
+and we now have an DISubprogram that contains a reference to all of our
+metadata for the function.
+
+Source Locations
+================
+
+The most important thing for debug information is accurate source location -
+this makes it possible to map your source code back. We have a problem though,
+Kaleidoscope really doesn't have any source location information in the lexer
+or parser so we'll need to add it.
+
+.. code-block:: c++
+
+ struct SourceLocation {
+ int Line;
+ int Col;
+ };
+ static SourceLocation CurLoc;
+ static SourceLocation LexLoc = {1, 0};
+
+ static int advance() {
+ int LastChar = getchar();
+
+ if (LastChar == '\n' || LastChar == '\r') {
+ LexLoc.Line++;
+ LexLoc.Col = 0;
+ } else
+ LexLoc.Col++;
+ return LastChar;
+ }
+
+In this set of code we've added some functionality on how to keep track of the
+line and column of the "source file". As we lex every token we set our current
+current "lexical location" to the assorted line and column for the beginning
+of the token. We do this by overriding all of the previous calls to
+``getchar()`` with our new ``advance()`` that keeps track of the information
+and then we have added to all of our AST classes a source location:
+
+.. code-block:: c++
+
+ class ExprAST {
+ SourceLocation Loc;
+
+ public:
+ ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}
+ virtual ~ExprAST() {}
+ virtual Value* codegen() = 0;
+ int getLine() const { return Loc.Line; }
+ int getCol() const { return Loc.Col; }
+ virtual raw_ostream &dump(raw_ostream &out, int ind) {
+ return out << ':' << getLine() << ':' << getCol() << '\n';
+ }
+
+that we pass down through when we create a new expression:
+
+.. code-block:: c++
+
+ LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),
+ std::move(RHS));
+
+giving us locations for each of our expressions and variables.
+
+From this we can make sure to tell ``DIBuilder`` when we're at a new source
+location so it can use that when we generate the rest of our code and make
+sure that each instruction has source location information. We do this
+by constructing another small function:
+
+.. code-block:: c++
+
+ void DebugInfo::emitLocation(ExprAST *AST) {
+ DIScope *Scope;
+ if (LexicalBlocks.empty())
+ Scope = TheCU;
+ else
+ Scope = LexicalBlocks.back();
+ Builder.SetCurrentDebugLocation(
+ DebugLoc::get(AST->getLine(), AST->getCol(), Scope));
+ }
+
+that both tells the main ``IRBuilder`` where we are, but also what scope
+we're in. Since we've just created a function above we can either be in
+the main file scope (like when we created our function), or now we can be
+in the function scope we just created. To represent this we create a stack
+of scopes:
+
+.. code-block:: c++
+
+ std::vector<DIScope *> LexicalBlocks;
+ std::map<const PrototypeAST *, DIScope *> FnScopeMap;
+
+and keep a map of each function to the scope that it represents (an
+DISubprogram is also an DIScope).
+
+Then we make sure to:
+
+.. code-block:: c++
+
+ KSDbgInfo.emitLocation(this);
+
+emit the location every time we start to generate code for a new AST, and
+also:
+
+.. code-block:: c++
+
+ KSDbgInfo.FnScopeMap[this] = SP;
+
+store the scope (function) when we create it and use it:
+
+ KSDbgInfo.LexicalBlocks.push_back(&KSDbgInfo.FnScopeMap[Proto]);
+
+when we start generating the code for each function.
+
+also, don't forget to pop the scope back off of your scope stack at the
+end of the code generation for the function:
+
+.. code-block:: c++
+
+ // Pop off the lexical block for the function since we added it
+ // unconditionally.
+ KSDbgInfo.LexicalBlocks.pop_back();
+
+Variables
+=========
+
+Now that we have functions, we need to be able to print out the variables
+we have in scope. Let's get our function arguments set up so we can get
+decent backtraces and see how our functions are being called. It isn't
+a lot of code, and we generally handle it when we're creating the
+argument allocas in ``PrototypeAST::CreateArgumentAllocas``.
+
+.. code-block:: c++
+
+ DIScope *Scope = KSDbgInfo.LexicalBlocks.back();
+ DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),
+ KSDbgInfo.TheCU.getDirectory());
+ DILocalVariable D = DBuilder->createParameterVariable(
+ Scope, Args[Idx], Idx + 1, Unit, Line, KSDbgInfo.getDoubleTy(), true);
+
+ DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),
+ DebugLoc::get(Line, 0, Scope),
+ Builder.GetInsertBlock());
+
+Here we're doing a few things. First, we're grabbing our current scope
+for the variable so we can say what range of code our variable is valid
+through. Second, we're creating the variable, giving it the scope,
+the name, source location, type, and since it's an argument, the argument
+index. Third, we create an ``lvm.dbg.declare`` call to indicate at the IR
+level that we've got a variable in an alloca (and it gives a starting
+location for the variable), and setting a source location for the
+beginning of the scope on the declare.
+
+One interesting thing to note at this point is that various debuggers have
+assumptions based on how code and debug information was generated for them
+in the past. In this case we need to do a little bit of a hack to avoid
+generating line information for the function prologue so that the debugger
+knows to skip over those instructions when setting a breakpoint. So in
+``FunctionAST::CodeGen`` we add a couple of lines:
+
+.. code-block:: c++
+
+ // Unset the location for the prologue emission (leading instructions with no
+ // location in a function are considered part of the prologue and the debugger
+ // will run past them when breaking on a function)
+ KSDbgInfo.emitLocation(nullptr);
+
+and then emit a new location when we actually start generating code for the
+body of the function:
+
+.. code-block:: c++
+
+ KSDbgInfo.emitLocation(Body);
+
+With this we have enough debug information to set breakpoints in functions,
+print out argument variables, and call functions. Not too bad for just a
+few simple lines of code!
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+debug information. To build this example, use:
+
+.. code-block:: bash
+
+ # Compile
+ clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
+ # Run
+ ./toy
+
+Here is the code:
+
+.. literalinclude:: ../../examples/Kaleidoscope/Chapter9/toy.cpp
+ :language: c++
+
+`Next: Conclusion and other useful LLVM tidbits <LangImpl10.html>`_
+
Removed: llvm/trunk/docs/tutorial/LangImpl1.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl1.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl1.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl1.rst (removed)
@@ -1,290 +0,0 @@
-=================================================
-Kaleidoscope: Tutorial Introduction and the Lexer
-=================================================
-
-.. contents::
- :local:
-
-Tutorial Introduction
-=====================
-
-Welcome to the "Implementing a language with LLVM" tutorial. This
-tutorial runs through the implementation of a simple language, showing
-how fun and easy it can be. This tutorial will get you up and started as
-well as help to build a framework you can extend to other languages. The
-code in this tutorial can also be used as a playground to hack on other
-LLVM specific things.
-
-The goal of this tutorial is to progressively unveil our language,
-describing how it is built up over time. This will let us cover a fairly
-broad range of language design and LLVM-specific usage issues, showing
-and explaining the code for it all along the way, without overwhelming
-you with tons of details up front.
-
-It is useful to point out ahead of time that this tutorial is really
-about teaching compiler techniques and LLVM specifically, *not* about
-teaching modern and sane software engineering principles. In practice,
-this means that we'll take a number of shortcuts to simplify the
-exposition. For example, the code uses global variables
-all over the place, doesn't use nice design patterns like
-`visitors <http://en.wikipedia.org/wiki/Visitor_pattern>`_, etc... but
-it is very simple. If you dig in and use the code as a basis for future
-projects, fixing these deficiencies shouldn't be hard.
-
-I've tried to put this tutorial together in a way that makes chapters
-easy to skip over if you are already familiar with or are uninterested
-in the various pieces. The structure of the tutorial is:
-
-- `Chapter #1 <#language>`_: Introduction to the Kaleidoscope
- language, and the definition of its Lexer - This shows where we are
- going and the basic functionality that we want it to do. In order to
- make this tutorial maximally understandable and hackable, we choose
- to implement everything in C++ instead of using lexer and parser
- generators. LLVM obviously works just fine with such tools, feel free
- to use one if you prefer.
-- `Chapter #2 <LangImpl2.html>`_: Implementing a Parser and AST -
- With the lexer in place, we can talk about parsing techniques and
- basic AST construction. This tutorial describes recursive descent
- parsing and operator precedence parsing. Nothing in Chapters 1 or 2
- is LLVM-specific, the code doesn't even link in LLVM at this point.
- :)
-- `Chapter #3 <LangImpl3.html>`_: Code generation to LLVM IR - With
- the AST ready, we can show off how easy generation of LLVM IR really
- is.
-- `Chapter #4 <LangImpl4.html>`_: Adding JIT and Optimizer Support
- - Because a lot of people are interested in using LLVM as a JIT,
- we'll dive right into it and show you the 3 lines it takes to add JIT
- support. LLVM is also useful in many other ways, but this is one
- simple and "sexy" way to show off its power. :)
-- `Chapter #5 <LangImpl5.html>`_: Extending the Language: Control
- Flow - With the language up and running, we show how to extend it
- with control flow operations (if/then/else and a 'for' loop). This
- gives us a chance to talk about simple SSA construction and control
- flow.
-- `Chapter #6 <LangImpl6.html>`_: Extending the Language:
- User-defined Operators - This is a silly but fun chapter that talks
- about extending the language to let the user program define their own
- arbitrary unary and binary operators (with assignable precedence!).
- This lets us build a significant piece of the "language" as library
- routines.
-- `Chapter #7 <LangImpl7.html>`_: Extending the Language: Mutable
- Variables - This chapter talks about adding user-defined local
- variables along with an assignment operator. The interesting part
- about this is how easy and trivial it is to construct SSA form in
- LLVM: no, LLVM does *not* require your front-end to construct SSA
- form!
-- `Chapter #8 <LangImpl8.html>`_: Extending the Language: Debug
- Information - Having built a decent little programming language with
- control flow, functions and mutable variables, we consider what it
- takes to add debug information to standalone executables. This debug
- information will allow you to set breakpoints in Kaleidoscope
- functions, print out argument variables, and call functions - all
- from within the debugger!
-- `Chapter #9 <LangImpl9.html>`_: Conclusion and other useful LLVM
- tidbits - This chapter wraps up the series by talking about
- potential ways to extend the language, but also includes a bunch of
- pointers to info about "special topics" like adding garbage
- collection support, exceptions, debugging, support for "spaghetti
- stacks", and a bunch of other tips and tricks.
-
-By the end of the tutorial, we'll have written a bit less than 1000 lines
-of non-comment, non-blank, lines of code. With this small amount of
-code, we'll have built up a very reasonable compiler for a non-trivial
-language including a hand-written lexer, parser, AST, as well as code
-generation support with a JIT compiler. While other systems may have
-interesting "hello world" tutorials, I think the breadth of this
-tutorial is a great testament to the strengths of LLVM and why you
-should consider it if you're interested in language or compiler design.
-
-A note about this tutorial: we expect you to extend the language and
-play with it on your own. Take the code and go crazy hacking away at it,
-compilers don't need to be scary creatures - it can be a lot of fun to
-play with languages!
-
-The Basic Language
-==================
-
-This tutorial will be illustrated with a toy language that we'll call
-"`Kaleidoscope <http://en.wikipedia.org/wiki/Kaleidoscope>`_" (derived
-from "meaning beautiful, form, and view"). Kaleidoscope is a procedural
-language that allows you to define functions, use conditionals, math,
-etc. Over the course of the tutorial, we'll extend Kaleidoscope to
-support the if/then/else construct, a for loop, user defined operators,
-JIT compilation with a simple command line interface, etc.
-
-Because we want to keep things simple, the only datatype in Kaleidoscope
-is a 64-bit floating point type (aka 'double' in C parlance). As such,
-all values are implicitly double precision and the language doesn't
-require type declarations. This gives the language a very nice and
-simple syntax. For example, the following simple example computes
-`Fibonacci numbers: <http://en.wikipedia.org/wiki/Fibonacci_number>`_
-
-::
-
- # Compute the x'th fibonacci number.
- def fib(x)
- if x < 3 then
- 1
- else
- fib(x-1)+fib(x-2)
-
- # This expression will compute the 40th number.
- fib(40)
-
-We also allow Kaleidoscope to call into standard library functions (the
-LLVM JIT makes this completely trivial). This means that you can use the
-'extern' keyword to define a function before you use it (this is also
-useful for mutually recursive functions). For example:
-
-::
-
- extern sin(arg);
- extern cos(arg);
- extern atan2(arg1 arg2);
-
- atan2(sin(.4), cos(42))
-
-A more interesting example is included in Chapter 6 where we write a
-little Kaleidoscope application that `displays a Mandelbrot
-Set <LangImpl6.html#kicking-the-tires>`_ at various levels of magnification.
-
-Lets dive into the implementation of this language!
-
-The Lexer
-=========
-
-When it comes to implementing a language, the first thing needed is the
-ability to process a text file and recognize what it says. The
-traditional way to do this is to use a
-"`lexer <http://en.wikipedia.org/wiki/Lexical_analysis>`_" (aka
-'scanner') to break the input up into "tokens". Each token returned by
-the lexer includes a token code and potentially some metadata (e.g. the
-numeric value of a number). First, we define the possibilities:
-
-.. code-block:: c++
-
- // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
- // of these for known things.
- enum Token {
- tok_eof = -1,
-
- // commands
- tok_def = -2,
- tok_extern = -3,
-
- // primary
- tok_identifier = -4,
- tok_number = -5,
- };
-
- static std::string IdentifierStr; // Filled in if tok_identifier
- static double NumVal; // Filled in if tok_number
-
-Each token returned by our lexer will either be one of the Token enum
-values or it will be an 'unknown' character like '+', which is returned
-as its ASCII value. If the current token is an identifier, the
-``IdentifierStr`` global variable holds the name of the identifier. If
-the current token is a numeric literal (like 1.0), ``NumVal`` holds its
-value. Note that we use global variables for simplicity, this is not the
-best choice for a real language implementation :).
-
-The actual implementation of the lexer is a single function named
-``gettok``. The ``gettok`` function is called to return the next token
-from standard input. Its definition starts as:
-
-.. code-block:: c++
-
- /// gettok - Return the next token from standard input.
- static int gettok() {
- static int LastChar = ' ';
-
- // Skip any whitespace.
- while (isspace(LastChar))
- LastChar = getchar();
-
-``gettok`` works by calling the C ``getchar()`` function to read
-characters one at a time from standard input. It eats them as it
-recognizes them and stores the last character read, but not processed,
-in LastChar. The first thing that it has to do is ignore whitespace
-between tokens. This is accomplished with the loop above.
-
-The next thing ``gettok`` needs to do is recognize identifiers and
-specific keywords like "def". Kaleidoscope does this with this simple
-loop:
-
-.. code-block:: c++
-
- if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
- IdentifierStr = LastChar;
- while (isalnum((LastChar = getchar())))
- IdentifierStr += LastChar;
-
- if (IdentifierStr == "def")
- return tok_def;
- if (IdentifierStr == "extern")
- return tok_extern;
- return tok_identifier;
- }
-
-Note that this code sets the '``IdentifierStr``' global whenever it
-lexes an identifier. Also, since language keywords are matched by the
-same loop, we handle them here inline. Numeric values are similar:
-
-.. code-block:: c++
-
- if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
- std::string NumStr;
- do {
- NumStr += LastChar;
- LastChar = getchar();
- } while (isdigit(LastChar) || LastChar == '.');
-
- NumVal = strtod(NumStr.c_str(), 0);
- return tok_number;
- }
-
-This is all pretty straight-forward code for processing input. When
-reading a numeric value from input, we use the C ``strtod`` function to
-convert it to a numeric value that we store in ``NumVal``. Note that
-this isn't doing sufficient error checking: it will incorrectly read
-"1.23.45.67" and handle it as if you typed in "1.23". Feel free to
-extend it :). Next we handle comments:
-
-.. code-block:: c++
-
- if (LastChar == '#') {
- // Comment until end of line.
- do
- LastChar = getchar();
- while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-
- if (LastChar != EOF)
- return gettok();
- }
-
-We handle comments by skipping to the end of the line and then return
-the next token. Finally, if the input doesn't match one of the above
-cases, it is either an operator character like '+' or the end of the
-file. These are handled with this code:
-
-.. code-block:: c++
-
- // Check for end of file. Don't eat the EOF.
- if (LastChar == EOF)
- return tok_eof;
-
- // Otherwise, just return the character as its ascii value.
- int ThisChar = LastChar;
- LastChar = getchar();
- return ThisChar;
- }
-
-With this, we have the complete lexer for the basic Kaleidoscope
-language (the `full code listing <LangImpl2.html#full-code-listing>`_ for the Lexer
-is available in the `next chapter <LangImpl2.html>`_ of the tutorial).
-Next we'll `build a simple parser that uses this to build an Abstract
-Syntax Tree <LangImpl2.html>`_. When we have that, we'll include a
-driver so that you can use the lexer and parser together.
-
-`Next: Implementing a Parser and AST <LangImpl2.html>`_
-
Added: llvm/trunk/docs/tutorial/LangImpl10.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl10.rst?rev=274441&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl10.rst (added)
+++ llvm/trunk/docs/tutorial/LangImpl10.rst Sat Jul 2 12:01:59 2016
@@ -0,0 +1,259 @@
+======================================================
+Kaleidoscope: Conclusion and other useful LLVM tidbits
+======================================================
+
+.. contents::
+ :local:
+
+Tutorial Conclusion
+===================
+
+Welcome to the final chapter of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. In the course of this tutorial, we have
+grown our little Kaleidoscope language from being a useless toy, to
+being a semi-interesting (but probably still useless) toy. :)
+
+It is interesting to see how far we've come, and how little code it has
+taken. We built the entire lexer, parser, AST, code generator, an
+interactive run-loop (with a JIT!), and emitted debug information in
+standalone executables - all in under 1000 lines of (non-comment/non-blank)
+code.
+
+Our little language supports a couple of interesting features: it
+supports user defined binary and unary operators, it uses JIT
+compilation for immediate evaluation, and it supports a few control flow
+constructs with SSA construction.
+
+Part of the idea of this tutorial was to show you how easy and fun it
+can be to define, build, and play with languages. Building a compiler
+need not be a scary or mystical process! Now that you've seen some of
+the basics, I strongly encourage you to take the code and hack on it.
+For example, try adding:
+
+- **global variables** - While global variables have questional value
+ in modern software engineering, they are often useful when putting
+ together quick little hacks like the Kaleidoscope compiler itself.
+ Fortunately, our current setup makes it very easy to add global
+ variables: just have value lookup check to see if an unresolved
+ variable is in the global variable symbol table before rejecting it.
+ To create a new global variable, make an instance of the LLVM
+ ``GlobalVariable`` class.
+- **typed variables** - Kaleidoscope currently only supports variables
+ of type double. This gives the language a very nice elegance, because
+ only supporting one type means that you never have to specify types.
+ Different languages have different ways of handling this. The easiest
+ way is to require the user to specify types for every variable
+ definition, and record the type of the variable in the symbol table
+ along with its Value\*.
+- **arrays, structs, vectors, etc** - Once you add types, you can start
+ extending the type system in all sorts of interesting ways. Simple
+ arrays are very easy and are quite useful for many different
+ applications. Adding them is mostly an exercise in learning how the
+ LLVM `getelementptr <../LangRef.html#getelementptr-instruction>`_ instruction
+ works: it is so nifty/unconventional, it `has its own
+ FAQ <../GetElementPtr.html>`_!
+- **standard runtime** - Our current language allows the user to access
+ arbitrary external functions, and we use it for things like "printd"
+ and "putchard". As you extend the language to add higher-level
+ constructs, often these constructs make the most sense if they are
+ lowered to calls into a language-supplied runtime. For example, if
+ you add hash tables to the language, it would probably make sense to
+ add the routines to a runtime, instead of inlining them all the way.
+- **memory management** - Currently we can only access the stack in
+ Kaleidoscope. It would also be useful to be able to allocate heap
+ memory, either with calls to the standard libc malloc/free interface
+ or with a garbage collector. If you would like to use garbage
+ collection, note that LLVM fully supports `Accurate Garbage
+ Collection <../GarbageCollection.html>`_ including algorithms that
+ move objects and need to scan/update the stack.
+- **exception handling support** - LLVM supports generation of `zero
+ cost exceptions <../ExceptionHandling.html>`_ which interoperate with
+ code compiled in other languages. You could also generate code by
+ implicitly making every function return an error value and checking
+ it. You could also make explicit use of setjmp/longjmp. There are
+ many different ways to go here.
+- **object orientation, generics, database access, complex numbers,
+ geometric programming, ...** - Really, there is no end of crazy
+ features that you can add to the language.
+- **unusual domains** - We've been talking about applying LLVM to a
+ domain that many people are interested in: building a compiler for a
+ specific language. However, there are many other domains that can use
+ compiler technology that are not typically considered. For example,
+ LLVM has been used to implement OpenGL graphics acceleration,
+ translate C++ code to ActionScript, and many other cute and clever
+ things. Maybe you will be the first to JIT compile a regular
+ expression interpreter into native code with LLVM?
+
+Have fun - try doing something crazy and unusual. Building a language
+like everyone else always has, is much less fun than trying something a
+little crazy or off the wall and seeing how it turns out. If you get
+stuck or want to talk about it, feel free to email the `llvm-dev mailing
+list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_: it has lots
+of people who are interested in languages and are often willing to help
+out.
+
+Before we end this tutorial, I want to talk about some "tips and tricks"
+for generating LLVM IR. These are some of the more subtle things that
+may not be obvious, but are very useful if you want to take advantage of
+LLVM's capabilities.
+
+Properties of the LLVM IR
+=========================
+
+We have a couple of common questions about code in the LLVM IR form -
+let's just get these out of the way right now, shall we?
+
+Target Independence
+-------------------
+
+Kaleidoscope is an example of a "portable language": any program written
+in Kaleidoscope will work the same way on any target that it runs on.
+Many other languages have this property, e.g. lisp, java, haskell,
+javascript, python, etc (note that while these languages are portable,
+not all their libraries are).
+
+One nice aspect of LLVM is that it is often capable of preserving target
+independence in the IR: you can take the LLVM IR for a
+Kaleidoscope-compiled program and run it on any target that LLVM
+supports, even emitting C code and compiling that on targets that LLVM
+doesn't support natively. You can trivially tell that the Kaleidoscope
+compiler generates target-independent code because it never queries for
+any target-specific information when generating code.
+
+The fact that LLVM provides a compact, target-independent,
+representation for code gets a lot of people excited. Unfortunately,
+these people are usually thinking about C or a language from the C
+family when they are asking questions about language portability. I say
+"unfortunately", because there is really no way to make (fully general)
+C code portable, other than shipping the source code around (and of
+course, C source code is not actually portable in general either - ever
+port a really old application from 32- to 64-bits?).
+
+The problem with C (again, in its full generality) is that it is heavily
+laden with target specific assumptions. As one simple example, the
+preprocessor often destructively removes target-independence from the
+code when it processes the input text:
+
+.. code-block:: c
+
+ #ifdef __i386__
+ int X = 1;
+ #else
+ int X = 42;
+ #endif
+
+While it is possible to engineer more and more complex solutions to
+problems like this, it cannot be solved in full generality in a way that
+is better than shipping the actual source code.
+
+That said, there are interesting subsets of C that can be made portable.
+If you are willing to fix primitive types to a fixed size (say int =
+32-bits, and long = 64-bits), don't care about ABI compatibility with
+existing binaries, and are willing to give up some other minor features,
+you can have portable code. This can make sense for specialized domains
+such as an in-kernel language.
+
+Safety Guarantees
+-----------------
+
+Many of the languages above are also "safe" languages: it is impossible
+for a program written in Java to corrupt its address space and crash the
+process (assuming the JVM has no bugs). Safety is an interesting
+property that requires a combination of language design, runtime
+support, and often operating system support.
+
+It is certainly possible to implement a safe language in LLVM, but LLVM
+IR does not itself guarantee safety. The LLVM IR allows unsafe pointer
+casts, use after free bugs, buffer over-runs, and a variety of other
+problems. Safety needs to be implemented as a layer on top of LLVM and,
+conveniently, several groups have investigated this. Ask on the `llvm-dev
+mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ if
+you are interested in more details.
+
+Language-Specific Optimizations
+-------------------------------
+
+One thing about LLVM that turns off many people is that it does not
+solve all the world's problems in one system (sorry 'world hunger',
+someone else will have to solve you some other day). One specific
+complaint is that people perceive LLVM as being incapable of performing
+high-level language-specific optimization: LLVM "loses too much
+information".
+
+Unfortunately, this is really not the place to give you a full and
+unified version of "Chris Lattner's theory of compiler design". Instead,
+I'll make a few observations:
+
+First, you're right that LLVM does lose information. For example, as of
+this writing, there is no way to distinguish in the LLVM IR whether an
+SSA-value came from a C "int" or a C "long" on an ILP32 machine (other
+than debug info). Both get compiled down to an 'i32' value and the
+information about what it came from is lost. The more general issue
+here, is that the LLVM type system uses "structural equivalence" instead
+of "name equivalence". Another place this surprises people is if you
+have two types in a high-level language that have the same structure
+(e.g. two different structs that have a single int field): these types
+will compile down into a single LLVM type and it will be impossible to
+tell what it came from.
+
+Second, while LLVM does lose information, LLVM is not a fixed target: we
+continue to enhance and improve it in many different ways. In addition
+to adding new features (LLVM did not always support exceptions or debug
+info), we also extend the IR to capture important information for
+optimization (e.g. whether an argument is sign or zero extended,
+information about pointers aliasing, etc). Many of the enhancements are
+user-driven: people want LLVM to include some specific feature, so they
+go ahead and extend it.
+
+Third, it is *possible and easy* to add language-specific optimizations,
+and you have a number of choices in how to do it. As one trivial
+example, it is easy to add language-specific optimization passes that
+"know" things about code compiled for a language. In the case of the C
+family, there is an optimization pass that "knows" about the standard C
+library functions. If you call "exit(0)" in main(), it knows that it is
+safe to optimize that into "return 0;" because C specifies what the
+'exit' function does.
+
+In addition to simple library knowledge, it is possible to embed a
+variety of other language-specific information into the LLVM IR. If you
+have a specific need and run into a wall, please bring the topic up on
+the llvm-dev list. At the very worst, you can always treat LLVM as if it
+were a "dumb code generator" and implement the high-level optimizations
+you desire in your front-end, on the language-specific AST.
+
+Tips and Tricks
+===============
+
+There is a variety of useful tips and tricks that you come to know after
+working on/with LLVM that aren't obvious at first glance. Instead of
+letting everyone rediscover them, this section talks about some of these
+issues.
+
+Implementing portable offsetof/sizeof
+-------------------------------------
+
+One interesting thing that comes up, if you are trying to keep the code
+generated by your compiler "target independent", is that you often need
+to know the size of some LLVM type or the offset of some field in an
+llvm structure. For example, you might need to pass the size of a type
+into a function that allocates memory.
+
+Unfortunately, this can vary widely across targets: for example the
+width of a pointer is trivially target-specific. However, there is a
+`clever way to use the getelementptr
+instruction <http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt>`_
+that allows you to compute this in a portable way.
+
+Garbage Collected Stack Frames
+------------------------------
+
+Some languages want to explicitly manage their stack frames, often so
+that they are garbage collected or to allow easy implementation of
+closures. There are often better ways to implement these features than
+explicit stack frames, but `LLVM does support
+them, <http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt>`_
+if you want. It requires your front-end to convert the code into
+`Continuation Passing
+Style <http://en.wikipedia.org/wiki/Continuation-passing_style>`_ and
+the use of tail calls (which LLVM also supports).
+
Removed: llvm/trunk/docs/tutorial/LangImpl2.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl2.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl2.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl2.rst (removed)
@@ -1,735 +0,0 @@
-===========================================
-Kaleidoscope: Implementing a Parser and AST
-===========================================
-
-.. contents::
- :local:
-
-Chapter 2 Introduction
-======================
-
-Welcome to Chapter 2 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. This chapter shows you how to use the
-lexer, built in `Chapter 1 <LangImpl1.html>`_, to build a full
-`parser <http://en.wikipedia.org/wiki/Parsing>`_ for our Kaleidoscope
-language. Once we have a parser, we'll define and build an `Abstract
-Syntax Tree <http://en.wikipedia.org/wiki/Abstract_syntax_tree>`_ (AST).
-
-The parser we will build uses a combination of `Recursive Descent
-Parsing <http://en.wikipedia.org/wiki/Recursive_descent_parser>`_ and
-`Operator-Precedence
-Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_ to
-parse the Kaleidoscope language (the latter for binary expressions and
-the former for everything else). Before we get to parsing though, lets
-talk about the output of the parser: the Abstract Syntax Tree.
-
-The Abstract Syntax Tree (AST)
-==============================
-
-The AST for a program captures its behavior in such a way that it is
-easy for later stages of the compiler (e.g. code generation) to
-interpret. We basically want one object for each construct in the
-language, and the AST should closely model the language. In
-Kaleidoscope, we have expressions, a prototype, and a function object.
-We'll start with expressions first:
-
-.. code-block:: c++
-
- /// ExprAST - Base class for all expression nodes.
- class ExprAST {
- public:
- virtual ~ExprAST() {}
- };
-
- /// NumberExprAST - Expression class for numeric literals like "1.0".
- class NumberExprAST : public ExprAST {
- double Val;
-
- public:
- NumberExprAST(double Val) : Val(Val) {}
- };
-
-The code above shows the definition of the base ExprAST class and one
-subclass which we use for numeric literals. The important thing to note
-about this code is that the NumberExprAST class captures the numeric
-value of the literal as an instance variable. This allows later phases
-of the compiler to know what the stored numeric value is.
-
-Right now we only create the AST, so there are no useful accessor
-methods on them. It would be very easy to add a virtual method to pretty
-print the code, for example. Here are the other expression AST node
-definitions that we'll use in the basic form of the Kaleidoscope
-language:
-
-.. code-block:: c++
-
- /// VariableExprAST - Expression class for referencing a variable, like "a".
- class VariableExprAST : public ExprAST {
- std::string Name;
-
- public:
- VariableExprAST(const std::string &Name) : Name(Name) {}
- };
-
- /// BinaryExprAST - Expression class for a binary operator.
- class BinaryExprAST : public ExprAST {
- char Op;
- std::unique_ptr<ExprAST> LHS, RHS;
-
- public:
- BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,
- std::unique_ptr<ExprAST> RHS)
- : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
- };
-
- /// CallExprAST - Expression class for function calls.
- class CallExprAST : public ExprAST {
- std::string Callee;
- std::vector<std::unique_ptr<ExprAST>> Args;
-
- public:
- CallExprAST(const std::string &Callee,
- std::vector<std::unique_ptr<ExprAST>> Args)
- : Callee(Callee), Args(std::move(Args)) {}
- };
-
-This is all (intentionally) rather straight-forward: variables capture
-the variable name, binary operators capture their opcode (e.g. '+'), and
-calls capture a function name as well as a list of any argument
-expressions. One thing that is nice about our AST is that it captures
-the language features without talking about the syntax of the language.
-Note that there is no discussion about precedence of binary operators,
-lexical structure, etc.
-
-For our basic language, these are all of the expression nodes we'll
-define. Because it doesn't have conditional control flow, it isn't
-Turing-complete; we'll fix that in a later installment. The two things
-we need next are a way to talk about the interface to a function, and a
-way to talk about functions themselves:
-
-.. code-block:: c++
-
- /// PrototypeAST - This class represents the "prototype" for a function,
- /// which captures its name, and its argument names (thus implicitly the number
- /// of arguments the function takes).
- class PrototypeAST {
- std::string Name;
- std::vector<std::string> Args;
-
- public:
- PrototypeAST(const std::string &name, std::vector<std::string> Args)
- : Name(name), Args(std::move(Args)) {}
- };
-
- /// FunctionAST - This class represents a function definition itself.
- class FunctionAST {
- std::unique_ptr<PrototypeAST> Proto;
- std::unique_ptr<ExprAST> Body;
-
- public:
- FunctionAST(std::unique_ptr<PrototypeAST> Proto,
- std::unique_ptr<ExprAST> Body)
- : Proto(std::move(Proto)), Body(std::move(Body)) {}
- };
-
-In Kaleidoscope, functions are typed with just a count of their
-arguments. Since all values are double precision floating point, the
-type of each argument doesn't need to be stored anywhere. In a more
-aggressive and realistic language, the "ExprAST" class would probably
-have a type field.
-
-With this scaffolding, we can now talk about parsing expressions and
-function bodies in Kaleidoscope.
-
-Parser Basics
-=============
-
-Now that we have an AST to build, we need to define the parser code to
-build it. The idea here is that we want to parse something like "x+y"
-(which is returned as three tokens by the lexer) into an AST that could
-be generated with calls like this:
-
-.. code-block:: c++
-
- auto LHS = llvm::make_unique<VariableExprAST>("x");
- auto RHS = llvm::make_unique<VariableExprAST>("y");
- auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),
- std::move(RHS));
-
-In order to do this, we'll start by defining some basic helper routines:
-
-.. code-block:: c++
-
- /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
- /// token the parser is looking at. getNextToken reads another token from the
- /// lexer and updates CurTok with its results.
- static int CurTok;
- static int getNextToken() {
- return CurTok = gettok();
- }
-
-This implements a simple token buffer around the lexer. This allows us
-to look one token ahead at what the lexer is returning. Every function
-in our parser will assume that CurTok is the current token that needs to
-be parsed.
-
-.. code-block:: c++
-
-
- /// LogError* - These are little helper functions for error handling.
- std::unique_ptr<ExprAST> LogError(const char *Str) {
- fprintf(stderr, "LogError: %s\n", Str);
- return nullptr;
- }
- std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
- LogError(Str);
- return nullptr;
- }
-
-The ``LogError`` routines are simple helper routines that our parser will
-use to handle errors. The error recovery in our parser will not be the
-best and is not particular user-friendly, but it will be enough for our
-tutorial. These routines make it easier to handle errors in routines
-that have various return types: they always return null.
-
-With these basic helper functions, we can implement the first piece of
-our grammar: numeric literals.
-
-Basic Expression Parsing
-========================
-
-We start with numeric literals, because they are the simplest to
-process. For each production in our grammar, we'll define a function
-which parses that production. For numeric literals, we have:
-
-.. code-block:: c++
-
- /// numberexpr ::= number
- static std::unique_ptr<ExprAST> ParseNumberExpr() {
- auto Result = llvm::make_unique<NumberExprAST>(NumVal);
- getNextToken(); // consume the number
- return std::move(Result);
- }
-
-This routine is very simple: it expects to be called when the current
-token is a ``tok_number`` token. It takes the current number value,
-creates a ``NumberExprAST`` node, advances the lexer to the next token,
-and finally returns.
-
-There are some interesting aspects to this. The most important one is
-that this routine eats all of the tokens that correspond to the
-production and returns the lexer buffer with the next token (which is
-not part of the grammar production) ready to go. This is a fairly
-standard way to go for recursive descent parsers. For a better example,
-the parenthesis operator is defined like this:
-
-.. code-block:: c++
-
- /// parenexpr ::= '(' expression ')'
- static std::unique_ptr<ExprAST> ParseParenExpr() {
- getNextToken(); // eat (.
- auto V = ParseExpression();
- if (!V)
- return nullptr;
-
- if (CurTok != ')')
- return LogError("expected ')'");
- getNextToken(); // eat ).
- return V;
- }
-
-This function illustrates a number of interesting things about the
-parser:
-
-1) It shows how we use the LogError routines. When called, this function
-expects that the current token is a '(' token, but after parsing the
-subexpression, it is possible that there is no ')' waiting. For example,
-if the user types in "(4 x" instead of "(4)", the parser should emit an
-error. Because errors can occur, the parser needs a way to indicate that
-they happened: in our parser, we return null on an error.
-
-2) Another interesting aspect of this function is that it uses recursion
-by calling ``ParseExpression`` (we will soon see that
-``ParseExpression`` can call ``ParseParenExpr``). This is powerful
-because it allows us to handle recursive grammars, and keeps each
-production very simple. Note that parentheses do not cause construction
-of AST nodes themselves. While we could do it this way, the most
-important role of parentheses are to guide the parser and provide
-grouping. Once the parser constructs the AST, parentheses are not
-needed.
-
-The next simple production is for handling variable references and
-function calls:
-
-.. code-block:: c++
-
- /// identifierexpr
- /// ::= identifier
- /// ::= identifier '(' expression* ')'
- static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
- std::string IdName = IdentifierStr;
-
- getNextToken(); // eat identifier.
-
- if (CurTok != '(') // Simple variable ref.
- return llvm::make_unique<VariableExprAST>(IdName);
-
- // Call.
- getNextToken(); // eat (
- std::vector<std::unique_ptr<ExprAST>> Args;
- if (CurTok != ')') {
- while (1) {
- if (auto Arg = ParseExpression())
- Args.push_back(std::move(Arg));
- else
- return nullptr;
-
- if (CurTok == ')')
- break;
-
- if (CurTok != ',')
- return LogError("Expected ')' or ',' in argument list");
- getNextToken();
- }
- }
-
- // Eat the ')'.
- getNextToken();
-
- return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
- }
-
-This routine follows the same style as the other routines. (It expects
-to be called if the current token is a ``tok_identifier`` token). It
-also has recursion and error handling. One interesting aspect of this is
-that it uses *look-ahead* to determine if the current identifier is a
-stand alone variable reference or if it is a function call expression.
-It handles this by checking to see if the token after the identifier is
-a '(' token, constructing either a ``VariableExprAST`` or
-``CallExprAST`` node as appropriate.
-
-Now that we have all of our simple expression-parsing logic in place, we
-can define a helper function to wrap it together into one entry point.
-We call this class of expressions "primary" expressions, for reasons
-that will become more clear `later in the
-tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary
-primary expression, we need to determine what sort of expression it is:
-
-.. code-block:: c++
-
- /// primary
- /// ::= identifierexpr
- /// ::= numberexpr
- /// ::= parenexpr
- static std::unique_ptr<ExprAST> ParsePrimary() {
- switch (CurTok) {
- default:
- return LogError("unknown token when expecting an expression");
- case tok_identifier:
- return ParseIdentifierExpr();
- case tok_number:
- return ParseNumberExpr();
- case '(':
- return ParseParenExpr();
- }
- }
-
-Now that you see the definition of this function, it is more obvious why
-we can assume the state of CurTok in the various functions. This uses
-look-ahead to determine which sort of expression is being inspected, and
-then parses it with a function call.
-
-Now that basic expressions are handled, we need to handle binary
-expressions. They are a bit more complex.
-
-Binary Expression Parsing
-=========================
-
-Binary expressions are significantly harder to parse because they are
-often ambiguous. For example, when given the string "x+y\*z", the parser
-can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
-definitions from mathematics, we expect the later parse, because "\*"
-(multiplication) has higher *precedence* than "+" (addition).
-
-There are many ways to handle this, but an elegant and efficient way is
-to use `Operator-Precedence
-Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_.
-This parsing technique uses the precedence of binary operators to guide
-recursion. To start with, we need a table of precedences:
-
-.. code-block:: c++
-
- /// BinopPrecedence - This holds the precedence for each binary operator that is
- /// defined.
- static std::map<char, int> BinopPrecedence;
-
- /// GetTokPrecedence - Get the precedence of the pending binary operator token.
- static int GetTokPrecedence() {
- if (!isascii(CurTok))
- return -1;
-
- // Make sure it's a declared binop.
- int TokPrec = BinopPrecedence[CurTok];
- if (TokPrec <= 0) return -1;
- return TokPrec;
- }
-
- int main() {
- // Install standard binary operators.
- // 1 is lowest precedence.
- BinopPrecedence['<'] = 10;
- BinopPrecedence['+'] = 20;
- BinopPrecedence['-'] = 20;
- BinopPrecedence['*'] = 40; // highest.
- ...
- }
-
-For the basic form of Kaleidoscope, we will only support 4 binary
-operators (this can obviously be extended by you, our brave and intrepid
-reader). The ``GetTokPrecedence`` function returns the precedence for
-the current token, or -1 if the token is not a binary operator. Having a
-map makes it easy to add new operators and makes it clear that the
-algorithm doesn't depend on the specific operators involved, but it
-would be easy enough to eliminate the map and do the comparisons in the
-``GetTokPrecedence`` function. (Or just use a fixed-size array).
-
-With the helper above defined, we can now start parsing binary
-expressions. The basic idea of operator precedence parsing is to break
-down an expression with potentially ambiguous binary operators into
-pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
-Operator precedence parsing considers this as a stream of primary
-expressions separated by binary operators. As such, it will first parse
-the leading primary expression "a", then it will see the pairs [+, b]
-[+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
-primary expressions, the binary expression parser doesn't need to worry
-about nested subexpressions like (c+d) at all.
-
-To start, an expression is a primary expression potentially followed by
-a sequence of [binop,primaryexpr] pairs:
-
-.. code-block:: c++
-
- /// expression
- /// ::= primary binoprhs
- ///
- static std::unique_ptr<ExprAST> ParseExpression() {
- auto LHS = ParsePrimary();
- if (!LHS)
- return nullptr;
-
- return ParseBinOpRHS(0, std::move(LHS));
- }
-
-``ParseBinOpRHS`` is the function that parses the sequence of pairs for
-us. It takes a precedence and a pointer to an expression for the part
-that has been parsed so far. Note that "x" is a perfectly valid
-expression: As such, "binoprhs" is allowed to be empty, in which case it
-returns the expression that is passed into it. In our example above, the
-code passes the expression for "a" into ``ParseBinOpRHS`` and the
-current token is "+".
-
-The precedence value passed into ``ParseBinOpRHS`` indicates the
-*minimal operator precedence* that the function is allowed to eat. For
-example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
-passed in a precedence of 40, it will not consume any tokens (because
-the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
-starts with:
-
-.. code-block:: c++
-
- /// binoprhs
- /// ::= ('+' primary)*
- static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
- std::unique_ptr<ExprAST> LHS) {
- // If this is a binop, find its precedence.
- while (1) {
- int TokPrec = GetTokPrecedence();
-
- // If this is a binop that binds at least as tightly as the current binop,
- // consume it, otherwise we are done.
- if (TokPrec < ExprPrec)
- return LHS;
-
-This code gets the precedence of the current token and checks to see if
-if is too low. Because we defined invalid tokens to have a precedence of
--1, this check implicitly knows that the pair-stream ends when the token
-stream runs out of binary operators. If this check succeeds, we know
-that the token is a binary operator and that it will be included in this
-expression:
-
-.. code-block:: c++
-
- // Okay, we know this is a binop.
- int BinOp = CurTok;
- getNextToken(); // eat binop
-
- // Parse the primary expression after the binary operator.
- auto RHS = ParsePrimary();
- if (!RHS)
- return nullptr;
-
-As such, this code eats (and remembers) the binary operator and then
-parses the primary expression that follows. This builds up the whole
-pair, the first of which is [+, b] for the running example.
-
-Now that we parsed the left-hand side of an expression and one pair of
-the RHS sequence, we have to decide which way the expression associates.
-In particular, we could have "(a+b) binop unparsed" or "a + (b binop
-unparsed)". To determine this, we look ahead at "binop" to determine its
-precedence and compare it to BinOp's precedence (which is '+' in this
-case):
-
-.. code-block:: c++
-
- // If BinOp binds less tightly with RHS than the operator after RHS, let
- // the pending operator take RHS as its LHS.
- int NextPrec = GetTokPrecedence();
- if (TokPrec < NextPrec) {
-
-If the precedence of the binop to the right of "RHS" is lower or equal
-to the precedence of our current operator, then we know that the
-parentheses associate as "(a+b) binop ...". In our example, the current
-operator is "+" and the next operator is "+", we know that they have the
-same precedence. In this case we'll create the AST node for "a+b", and
-then continue parsing:
-
-.. code-block:: c++
-
- ... if body omitted ...
- }
-
- // Merge LHS/RHS.
- LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
- std::move(RHS));
- } // loop around to the top of the while loop.
- }
-
-In our example above, this will turn "a+b+" into "(a+b)" and execute the
-next iteration of the loop, with "+" as the current token. The code
-above will eat, remember, and parse "(c+d)" as the primary expression,
-which makes the current pair equal to [+, (c+d)]. It will then evaluate
-the 'if' conditional above with "\*" as the binop to the right of the
-primary. In this case, the precedence of "\*" is higher than the
-precedence of "+" so the if condition will be entered.
-
-The critical question left here is "how can the if condition parse the
-right hand side in full"? In particular, to build the AST correctly for
-our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
-variable. The code to do this is surprisingly simple (code from the
-above two blocks duplicated for context):
-
-.. code-block:: c++
-
- // If BinOp binds less tightly with RHS than the operator after RHS, let
- // the pending operator take RHS as its LHS.
- int NextPrec = GetTokPrecedence();
- if (TokPrec < NextPrec) {
- RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
- if (!RHS)
- return nullptr;
- }
- // Merge LHS/RHS.
- LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
- std::move(RHS));
- } // loop around to the top of the while loop.
- }
-
-At this point, we know that the binary operator to the RHS of our
-primary has higher precedence than the binop we are currently parsing.
-As such, we know that any sequence of pairs whose operators are all
-higher precedence than "+" should be parsed together and returned as
-"RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
-specifying "TokPrec+1" as the minimum precedence required for it to
-continue. In our example above, this will cause it to return the AST
-node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'
-expression.
-
-Finally, on the next iteration of the while loop, the "+g" piece is
-parsed and added to the AST. With this little bit of code (14
-non-trivial lines), we correctly handle fully general binary expression
-parsing in a very elegant way. This was a whirlwind tour of this code,
-and it is somewhat subtle. I recommend running through it with a few
-tough examples to see how it works.
-
-This wraps up handling of expressions. At this point, we can point the
-parser at an arbitrary token stream and build an expression from it,
-stopping at the first token that is not part of the expression. Next up
-we need to handle function definitions, etc.
-
-Parsing the Rest
-================
-
-The next thing missing is handling of function prototypes. In
-Kaleidoscope, these are used both for 'extern' function declarations as
-well as function body definitions. The code to do this is
-straight-forward and not very interesting (once you've survived
-expressions):
-
-.. code-block:: c++
-
- /// prototype
- /// ::= id '(' id* ')'
- static std::unique_ptr<PrototypeAST> ParsePrototype() {
- if (CurTok != tok_identifier)
- return LogErrorP("Expected function name in prototype");
-
- std::string FnName = IdentifierStr;
- getNextToken();
-
- if (CurTok != '(')
- return LogErrorP("Expected '(' in prototype");
-
- // Read the list of argument names.
- std::vector<std::string> ArgNames;
- while (getNextToken() == tok_identifier)
- ArgNames.push_back(IdentifierStr);
- if (CurTok != ')')
- return LogErrorP("Expected ')' in prototype");
-
- // success.
- getNextToken(); // eat ')'.
-
- return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
- }
-
-Given this, a function definition is very simple, just a prototype plus
-an expression to implement the body:
-
-.. code-block:: c++
-
- /// definition ::= 'def' prototype expression
- static std::unique_ptr<FunctionAST> ParseDefinition() {
- getNextToken(); // eat def.
- auto Proto = ParsePrototype();
- if (!Proto) return nullptr;
-
- if (auto E = ParseExpression())
- return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
- return nullptr;
- }
-
-In addition, we support 'extern' to declare functions like 'sin' and
-'cos' as well as to support forward declaration of user functions. These
-'extern's are just prototypes with no body:
-
-.. code-block:: c++
-
- /// external ::= 'extern' prototype
- static std::unique_ptr<PrototypeAST> ParseExtern() {
- getNextToken(); // eat extern.
- return ParsePrototype();
- }
-
-Finally, we'll also let the user type in arbitrary top-level expressions
-and evaluate them on the fly. We will handle this by defining anonymous
-nullary (zero argument) functions for them:
-
-.. code-block:: c++
-
- /// toplevelexpr ::= expression
- static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
- if (auto E = ParseExpression()) {
- // Make an anonymous proto.
- auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
- return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
- }
- return nullptr;
- }
-
-Now that we have all the pieces, let's build a little driver that will
-let us actually *execute* this code we've built!
-
-The Driver
-==========
-
-The driver for this simply invokes all of the parsing pieces with a
-top-level dispatch loop. There isn't much interesting here, so I'll just
-include the top-level loop. See `below <#full-code-listing>`_ for full code in the
-"Top-Level Parsing" section.
-
-.. code-block:: c++
-
- /// top ::= definition | external | expression | ';'
- static void MainLoop() {
- while (1) {
- fprintf(stderr, "ready> ");
- switch (CurTok) {
- case tok_eof:
- return;
- case ';': // ignore top-level semicolons.
- getNextToken();
- break;
- case tok_def:
- HandleDefinition();
- break;
- case tok_extern:
- HandleExtern();
- break;
- default:
- HandleTopLevelExpression();
- break;
- }
- }
- }
-
-The most interesting part of this is that we ignore top-level
-semicolons. Why is this, you ask? The basic reason is that if you type
-"4 + 5" at the command line, the parser doesn't know whether that is the
-end of what you will type or not. For example, on the next line you
-could type "def foo..." in which case 4+5 is the end of a top-level
-expression. Alternatively you could type "\* 6", which would continue
-the expression. Having top-level semicolons allows you to type "4+5;",
-and the parser will know you are done.
-
-Conclusions
-===========
-
-With just under 400 lines of commented code (240 lines of non-comment,
-non-blank code), we fully defined our minimal language, including a
-lexer, parser, and AST builder. With this done, the executable will
-validate Kaleidoscope code and tell us if it is grammatically invalid.
-For example, here is a sample interaction:
-
-.. code-block:: bash
-
- $ ./a.out
- ready> def foo(x y) x+foo(y, 4.0);
- Parsed a function definition.
- ready> def foo(x y) x+y y;
- Parsed a function definition.
- Parsed a top-level expr
- ready> def foo(x y) x+y );
- Parsed a function definition.
- Error: unknown token when expecting an expression
- ready> extern sin(a);
- ready> Parsed an extern
- ready> ^D
- $
-
-There is a lot of room for extension here. You can define new AST nodes,
-extend the language in many ways, etc. In the `next
-installment <LangImpl3.html>`_, we will describe how to generate LLVM
-Intermediate Representation (IR) from the AST.
-
-Full Code Listing
-=================
-
-Here is the complete code listing for this and the previous chapter.
-Note that it is fully self-contained: you don't need LLVM or any
-external libraries at all for this. (Besides the C and C++ standard
-libraries, of course.) To build this, just compile with:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g -O3 toy.cpp
- # Run
- ./a.out
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp
- :language: c++
-
-`Next: Implementing Code Generation to LLVM IR <LangImpl3.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl3.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl3.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl3.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl3.rst (removed)
@@ -1,567 +0,0 @@
-========================================
-Kaleidoscope: Code generation to LLVM IR
-========================================
-
-.. contents::
- :local:
-
-Chapter 3 Introduction
-======================
-
-Welcome to Chapter 3 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. This chapter shows you how to transform
-the `Abstract Syntax Tree <LangImpl2.html>`_, built in Chapter 2, into
-LLVM IR. This will teach you a little bit about how LLVM does things, as
-well as demonstrate how easy it is to use. It's much more work to build
-a lexer and parser than it is to generate LLVM IR code. :)
-
-**Please note**: the code in this chapter and later require LLVM 3.7 or
-later. LLVM 3.6 and before will not work with it. Also note that you
-need to use a version of this tutorial that matches your LLVM release:
-If you are using an official LLVM release, use the version of the
-documentation included with your release or on the `llvm.org releases
-page <http://llvm.org/releases/>`_.
-
-Code Generation Setup
-=====================
-
-In order to generate LLVM IR, we want some simple setup to get started.
-First we define virtual code generation (codegen) methods in each AST
-class:
-
-.. code-block:: c++
-
- /// ExprAST - Base class for all expression nodes.
- class ExprAST {
- public:
- virtual ~ExprAST() {}
- virtual Value *codegen() = 0;
- };
-
- /// NumberExprAST - Expression class for numeric literals like "1.0".
- class NumberExprAST : public ExprAST {
- double Val;
-
- public:
- NumberExprAST(double Val) : Val(Val) {}
- virtual Value *codegen();
- };
- ...
-
-The codegen() method says to emit IR for that AST node along with all
-the things it depends on, and they all return an LLVM Value object.
-"Value" is the class used to represent a "`Static Single Assignment
-(SSA) <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
-register" or "SSA value" in LLVM. The most distinct aspect of SSA values
-is that their value is computed as the related instruction executes, and
-it does not get a new value until (and if) the instruction re-executes.
-In other words, there is no way to "change" an SSA value. For more
-information, please read up on `Static Single
-Assignment <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
-- the concepts are really quite natural once you grok them.
-
-Note that instead of adding virtual methods to the ExprAST class
-hierarchy, it could also make sense to use a `visitor
-pattern <http://en.wikipedia.org/wiki/Visitor_pattern>`_ or some other
-way to model this. Again, this tutorial won't dwell on good software
-engineering practices: for our purposes, adding a virtual method is
-simplest.
-
-The second thing we want is an "LogError" method like we used for the
-parser, which will be used to report errors found during code generation
-(for example, use of an undeclared parameter):
-
-.. code-block:: c++
-
- static LLVMContext TheContext;
- static IRBuilder<> Builder(TheContext);
- static std::unique_ptr<Module> TheModule;
- static std::map<std::string, Value *> NamedValues;
-
- Value *LogErrorV(const char *Str) {
- LogError(Str);
- return nullptr;
- }
-
-The static variables will be used during code generation. ``TheContext``
-is an opaque object that owns a lot of core LLVM data structures, such as
-the type and constant value tables. We don't need to understand it in
-detail, we just need a single instance to pass into APIs that require it.
-
-The ``Builder`` object is a helper object that makes it easy to generate
-LLVM instructions. Instances of the
-`IRBuilder <http://llvm.org/doxygen/IRBuilder_8h-source.html>`_
-class template keep track of the current place to insert instructions
-and has methods to create new instructions.
-
-``TheModule`` is an LLVM construct that contains functions and global
-variables. In many ways, it is the top-level structure that the LLVM IR
-uses to contain code. It will own the memory for all of the IR that we
-generate, which is why the codegen() method returns a raw Value\*,
-rather than a unique_ptr<Value>.
-
-The ``NamedValues`` map keeps track of which values are defined in the
-current scope and what their LLVM representation is. (In other words, it
-is a symbol table for the code). In this form of Kaleidoscope, the only
-things that can be referenced are function parameters. As such, function
-parameters will be in this map when generating code for their function
-body.
-
-With these basics in place, we can start talking about how to generate
-code for each expression. Note that this assumes that the ``Builder``
-has been set up to generate code *into* something. For now, we'll assume
-that this has already been done, and we'll just use it to emit code.
-
-Expression Code Generation
-==========================
-
-Generating LLVM code for expression nodes is very straightforward: less
-than 45 lines of commented code for all four of our expression nodes.
-First we'll do numeric literals:
-
-.. code-block:: c++
-
- Value *NumberExprAST::codegen() {
- return ConstantFP::get(LLVMContext, APFloat(Val));
- }
-
-In the LLVM IR, numeric constants are represented with the
-``ConstantFP`` class, which holds the numeric value in an ``APFloat``
-internally (``APFloat`` has the capability of holding floating point
-constants of Arbitrary Precision). This code basically just creates
-and returns a ``ConstantFP``. Note that in the LLVM IR that constants
-are all uniqued together and shared. For this reason, the API uses the
-"foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
-
-.. code-block:: c++
-
- Value *VariableExprAST::codegen() {
- // Look this variable up in the function.
- Value *V = NamedValues[Name];
- if (!V)
- LogErrorV("Unknown variable name");
- return V;
- }
-
-References to variables are also quite simple using LLVM. In the simple
-version of Kaleidoscope, we assume that the variable has already been
-emitted somewhere and its value is available. In practice, the only
-values that can be in the ``NamedValues`` map are function arguments.
-This code simply checks to see that the specified name is in the map (if
-not, an unknown variable is being referenced) and returns the value for
-it. In future chapters, we'll add support for `loop induction
-variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local
-variables <LangImpl7.html#user-defined-local-variables>`_.
-
-.. code-block:: c++
-
- Value *BinaryExprAST::codegen() {
- Value *L = LHS->codegen();
- Value *R = RHS->codegen();
- if (!L || !R)
- return nullptr;
-
- switch (Op) {
- case '+':
- return Builder.CreateFAdd(L, R, "addtmp");
- case '-':
- return Builder.CreateFSub(L, R, "subtmp");
- case '*':
- return Builder.CreateFMul(L, R, "multmp");
- case '<':
- L = Builder.CreateFCmpULT(L, R, "cmptmp");
- // Convert bool 0/1 to double 0.0 or 1.0
- return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
- "booltmp");
- default:
- return LogErrorV("invalid binary operator");
- }
- }
-
-Binary operators start to get more interesting. The basic idea here is
-that we recursively emit code for the left-hand side of the expression,
-then the right-hand side, then we compute the result of the binary
-expression. In this code, we do a simple switch on the opcode to create
-the right LLVM instruction.
-
-In the example above, the LLVM builder class is starting to show its
-value. IRBuilder knows where to insert the newly created instruction,
-all you have to do is specify what instruction to create (e.g. with
-``CreateFAdd``), which operands to use (``L`` and ``R`` here) and
-optionally provide a name for the generated instruction.
-
-One nice thing about LLVM is that the name is just a hint. For instance,
-if the code above emits multiple "addtmp" variables, LLVM will
-automatically provide each one with an increasing, unique numeric
-suffix. Local value names for instructions are purely optional, but it
-makes it much easier to read the IR dumps.
-
-`LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict
-rules: for example, the Left and Right operators of an `add
-instruction <../LangRef.html#add-instruction>`_ must have the same type, and the
-result type of the add must match the operand types. Because all values
-in Kaleidoscope are doubles, this makes for very simple code for add,
-sub and mul.
-
-On the other hand, LLVM specifies that the `fcmp
-instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a
-one bit integer). The problem with this is that Kaleidoscope wants the
-value to be a 0.0 or 1.0 value. In order to get these semantics, we
-combine the fcmp instruction with a `uitofp
-instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its
-input integer into a floating point value by treating the input as an
-unsigned value. In contrast, if we used the `sitofp
-instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
-would return 0.0 and -1.0, depending on the input value.
-
-.. code-block:: c++
-
- Value *CallExprAST::codegen() {
- // Look up the name in the global module table.
- Function *CalleeF = TheModule->getFunction(Callee);
- if (!CalleeF)
- return LogErrorV("Unknown function referenced");
-
- // If argument mismatch error.
- if (CalleeF->arg_size() != Args.size())
- return LogErrorV("Incorrect # arguments passed");
-
- std::vector<Value *> ArgsV;
- for (unsigned i = 0, e = Args.size(); i != e; ++i) {
- ArgsV.push_back(Args[i]->codegen());
- if (!ArgsV.back())
- return nullptr;
- }
-
- return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
- }
-
-Code generation for function calls is quite straightforward with LLVM. The code
-above initially does a function name lookup in the LLVM Module's symbol table.
-Recall that the LLVM Module is the container that holds the functions we are
-JIT'ing. By giving each function the same name as what the user specifies, we
-can use the LLVM symbol table to resolve function names for us.
-
-Once we have the function to call, we recursively codegen each argument
-that is to be passed in, and create an LLVM `call
-instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C
-calling conventions by default, allowing these calls to also call into
-standard library functions like "sin" and "cos", with no additional
-effort.
-
-This wraps up our handling of the four basic expressions that we have so
-far in Kaleidoscope. Feel free to go in and add some more. For example,
-by browsing the `LLVM language reference <../LangRef.html>`_ you'll find
-several other interesting instructions that are really easy to plug into
-our basic framework.
-
-Function Code Generation
-========================
-
-Code generation for prototypes and functions must handle a number of
-details, which make their code less beautiful than expression code
-generation, but allows us to illustrate some important points. First,
-lets talk about code generation for prototypes: they are used both for
-function bodies and external function declarations. The code starts
-with:
-
-.. code-block:: c++
-
- Function *PrototypeAST::codegen() {
- // Make the function type: double(double,double) etc.
- std::vector<Type*> Doubles(Args.size(),
- Type::getDoubleTy(LLVMContext));
- FunctionType *FT =
- FunctionType::get(Type::getDoubleTy(LLVMContext), Doubles, false);
-
- Function *F =
- Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-
-This code packs a lot of power into a few lines. Note first that this
-function returns a "Function\*" instead of a "Value\*". Because a
-"prototype" really talks about the external interface for a function
-(not the value computed by an expression), it makes sense for it to
-return the LLVM Function it corresponds to when codegen'd.
-
-The call to ``FunctionType::get`` creates the ``FunctionType`` that
-should be used for a given Prototype. Since all function arguments in
-Kaleidoscope are of type double, the first line creates a vector of "N"
-LLVM double types. It then uses the ``Functiontype::get`` method to
-create a function type that takes "N" doubles as arguments, returns one
-double as a result, and that is not vararg (the false parameter
-indicates this). Note that Types in LLVM are uniqued just like Constants
-are, so you don't "new" a type, you "get" it.
-
-The final line above actually creates the IR Function corresponding to
-the Prototype. This indicates the type, linkage and name to use, as
-well as which module to insert into. "`external
-linkage <../LangRef.html#linkage>`_" means that the function may be
-defined outside the current module and/or that it is callable by
-functions outside the module. The Name passed in is the name the user
-specified: since "``TheModule``" is specified, this name is registered
-in "``TheModule``"s symbol table.
-
-.. code-block:: c++
-
- // Set names for all arguments.
- unsigned Idx = 0;
- for (auto &Arg : F->args())
- Arg.setName(Args[Idx++]);
-
- return F;
-
-Finally, we set the name of each of the function's arguments according to the
-names given in the Prototype. This step isn't strictly necessary, but keeping
-the names consistent makes the IR more readable, and allows subsequent code to
-refer directly to the arguments for their names, rather than having to look up
-them up in the Prototype AST.
-
-At this point we have a function prototype with no body. This is how LLVM IR
-represents function declarations. For extern statements in Kaleidoscope, this
-is as far as we need to go. For function definitions however, we need to
-codegen and attach a function body.
-
-.. code-block:: c++
-
- Function *FunctionAST::codegen() {
- // First, check for an existing function from a previous 'extern' declaration.
- Function *TheFunction = TheModule->getFunction(Proto->getName());
-
- if (!TheFunction)
- TheFunction = Proto->codegen();
-
- if (!TheFunction)
- return nullptr;
-
- if (!TheFunction->empty())
- return (Function*)LogErrorV("Function cannot be redefined.");
-
-
-For function definitions, we start by searching TheModule's symbol table for an
-existing version of this function, in case one has already been created using an
-'extern' statement. If Module::getFunction returns null then no previous version
-exists, so we'll codegen one from the Prototype. In either case, we want to
-assert that the function is empty (i.e. has no body yet) before we start.
-
-.. code-block:: c++
-
- // Create a new basic block to start insertion into.
- BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
- Builder.SetInsertPoint(BB);
-
- // Record the function arguments in the NamedValues map.
- NamedValues.clear();
- for (auto &Arg : TheFunction->args())
- NamedValues[Arg.getName()] = &Arg;
-
-Now we get to the point where the ``Builder`` is set up. The first line
-creates a new `basic block <http://en.wikipedia.org/wiki/Basic_block>`_
-(named "entry"), which is inserted into ``TheFunction``. The second line
-then tells the builder that new instructions should be inserted into the
-end of the new basic block. Basic blocks in LLVM are an important part
-of functions that define the `Control Flow
-Graph <http://en.wikipedia.org/wiki/Control_flow_graph>`_. Since we
-don't have any control flow, our functions will only contain one block
-at this point. We'll fix this in `Chapter 5 <LangImpl5.html>`_ :).
-
-Next we add the function arguments to the NamedValues map (after first clearing
-it out) so that they're accessible to ``VariableExprAST`` nodes.
-
-.. code-block:: c++
-
- if (Value *RetVal = Body->codegen()) {
- // Finish off the function.
- Builder.CreateRet(RetVal);
-
- // Validate the generated code, checking for consistency.
- verifyFunction(*TheFunction);
-
- return TheFunction;
- }
-
-Once the insertion point has been set up and the NamedValues map populated,
-we call the ``codegen()`` method for the root expression of the function. If no
-error happens, this emits code to compute the expression into the entry block
-and returns the value that was computed. Assuming no error, we then create an
-LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.
-Once the function is built, we call ``verifyFunction``, which is
-provided by LLVM. This function does a variety of consistency checks on
-the generated code, to determine if our compiler is doing everything
-right. Using this is important: it can catch a lot of bugs. Once the
-function is finished and validated, we return it.
-
-.. code-block:: c++
-
- // Error reading body, remove function.
- TheFunction->eraseFromParent();
- return nullptr;
- }
-
-The only piece left here is handling of the error case. For simplicity,
-we handle this by merely deleting the function we produced with the
-``eraseFromParent`` method. This allows the user to redefine a function
-that they incorrectly typed in before: if we didn't delete it, it would
-live in the symbol table, with a body, preventing future redefinition.
-
-This code does have a bug, though: If the ``FunctionAST::codegen()`` method
-finds an existing IR Function, it does not validate its signature against the
-definition's own prototype. This means that an earlier 'extern' declaration will
-take precedence over the function definition's signature, which can cause
-codegen to fail, for instance if the function arguments are named differently.
-There are a number of ways to fix this bug, see what you can come up with! Here
-is a testcase:
-
-::
-
- extern foo(a); # ok, defines foo.
- def foo(b) b; # Error: Unknown variable name. (decl using 'a' takes precedence).
-
-Driver Changes and Closing Thoughts
-===================================
-
-For now, code generation to LLVM doesn't really get us much, except that
-we can look at the pretty IR calls. The sample code inserts calls to
-codegen into the "``HandleDefinition``", "``HandleExtern``" etc
-functions, and then dumps out the LLVM IR. This gives a nice way to look
-at the LLVM IR for simple functions. For example:
-
-::
-
- ready> 4+5;
- Read top-level expression:
- define double @0() {
- entry:
- ret double 9.000000e+00
- }
-
-Note how the parser turns the top-level expression into anonymous
-functions for us. This will be handy when we add `JIT
-support <LangImpl4.html#adding-a-jit-compiler>`_ in the next chapter. Also note that the
-code is very literally transcribed, no optimizations are being performed
-except simple constant folding done by IRBuilder. We will `add
-optimizations <LangImpl4.html#trivial-constant-folding>`_ explicitly in the next
-chapter.
-
-::
-
- ready> def foo(a b) a*a + 2*a*b + b*b;
- Read function definition:
- define double @foo(double %a, double %b) {
- entry:
- %multmp = fmul double %a, %a
- %multmp1 = fmul double 2.000000e+00, %a
- %multmp2 = fmul double %multmp1, %b
- %addtmp = fadd double %multmp, %multmp2
- %multmp3 = fmul double %b, %b
- %addtmp4 = fadd double %addtmp, %multmp3
- ret double %addtmp4
- }
-
-This shows some simple arithmetic. Notice the striking similarity to the
-LLVM builder calls that we use to create the instructions.
-
-::
-
- ready> def bar(a) foo(a, 4.0) + bar(31337);
- Read function definition:
- define double @bar(double %a) {
- entry:
- %calltmp = call double @foo(double %a, double 4.000000e+00)
- %calltmp1 = call double @bar(double 3.133700e+04)
- %addtmp = fadd double %calltmp, %calltmp1
- ret double %addtmp
- }
-
-This shows some function calls. Note that this function will take a long
-time to execute if you call it. In the future we'll add conditional
-control flow to actually make recursion useful :).
-
-::
-
- ready> extern cos(x);
- Read extern:
- declare double @cos(double)
-
- ready> cos(1.234);
- Read top-level expression:
- define double @1() {
- entry:
- %calltmp = call double @cos(double 1.234000e+00)
- ret double %calltmp
- }
-
-This shows an extern for the libm "cos" function, and a call to it.
-
-.. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up
- on highlighting this due to the first line.
-
-::
-
- ready> ^D
- ; ModuleID = 'my cool jit'
-
- define double @0() {
- entry:
- %addtmp = fadd double 4.000000e+00, 5.000000e+00
- ret double %addtmp
- }
-
- define double @foo(double %a, double %b) {
- entry:
- %multmp = fmul double %a, %a
- %multmp1 = fmul double 2.000000e+00, %a
- %multmp2 = fmul double %multmp1, %b
- %addtmp = fadd double %multmp, %multmp2
- %multmp3 = fmul double %b, %b
- %addtmp4 = fadd double %addtmp, %multmp3
- ret double %addtmp4
- }
-
- define double @bar(double %a) {
- entry:
- %calltmp = call double @foo(double %a, double 4.000000e+00)
- %calltmp1 = call double @bar(double 3.133700e+04)
- %addtmp = fadd double %calltmp, %calltmp1
- ret double %addtmp
- }
-
- declare double @cos(double)
-
- define double @1() {
- entry:
- %calltmp = call double @cos(double 1.234000e+00)
- ret double %calltmp
- }
-
-When you quit the current demo, it dumps out the IR for the entire
-module generated. Here you can see the big picture with all the
-functions referencing each other.
-
-This wraps up the third chapter of the Kaleidoscope tutorial. Up next,
-we'll describe how to `add JIT codegen and optimizer
-support <LangImpl4.html>`_ to this so we can actually start running
-code!
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-the LLVM code generator. Because this uses the LLVM libraries, we need
-to link them in. To do this, we use the
-`llvm-config <http://llvm.org/cmds/llvm-config.html>`_ tool to inform
-our makefile/command line about which options to use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy
- # Run
- ./toy
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp
- :language: c++
-
-`Next: Adding JIT and Optimizer Support <LangImpl4.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl4.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl4.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl4.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl4.rst (removed)
@@ -1,610 +0,0 @@
-==============================================
-Kaleidoscope: Adding JIT and Optimizer Support
-==============================================
-
-.. contents::
- :local:
-
-Chapter 4 Introduction
-======================
-
-Welcome to Chapter 4 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. Chapters 1-3 described the implementation
-of a simple language and added support for generating LLVM IR. This
-chapter describes two new techniques: adding optimizer support to your
-language, and adding JIT compiler support. These additions will
-demonstrate how to get nice, efficient code for the Kaleidoscope
-language.
-
-Trivial Constant Folding
-========================
-
-Our demonstration for Chapter 3 is elegant and easy to extend.
-Unfortunately, it does not produce wonderful code. The IRBuilder,
-however, does give us obvious optimizations when compiling simple code:
-
-::
-
- ready> def test(x) 1+2+x;
- Read function definition:
- define double @test(double %x) {
- entry:
- %addtmp = fadd double 3.000000e+00, %x
- ret double %addtmp
- }
-
-This code is not a literal transcription of the AST built by parsing the
-input. That would be:
-
-::
-
- ready> def test(x) 1+2+x;
- Read function definition:
- define double @test(double %x) {
- entry:
- %addtmp = fadd double 2.000000e+00, 1.000000e+00
- %addtmp1 = fadd double %addtmp, %x
- ret double %addtmp1
- }
-
-Constant folding, as seen above, in particular, is a very common and
-very important optimization: so much so that many language implementors
-implement constant folding support in their AST representation.
-
-With LLVM, you don't need this support in the AST. Since all calls to
-build LLVM IR go through the LLVM IR builder, the builder itself checked
-to see if there was a constant folding opportunity when you call it. If
-so, it just does the constant fold and return the constant instead of
-creating an instruction.
-
-Well, that was easy :). In practice, we recommend always using
-``IRBuilder`` when generating code like this. It has no "syntactic
-overhead" for its use (you don't have to uglify your compiler with
-constant checks everywhere) and it can dramatically reduce the amount of
-LLVM IR that is generated in some cases (particular for languages with a
-macro preprocessor or that use a lot of constants).
-
-On the other hand, the ``IRBuilder`` is limited by the fact that it does
-all of its analysis inline with the code as it is built. If you take a
-slightly more complex example:
-
-::
-
- ready> def test(x) (1+2+x)*(x+(1+2));
- ready> Read function definition:
- define double @test(double %x) {
- entry:
- %addtmp = fadd double 3.000000e+00, %x
- %addtmp1 = fadd double %x, 3.000000e+00
- %multmp = fmul double %addtmp, %addtmp1
- ret double %multmp
- }
-
-In this case, the LHS and RHS of the multiplication are the same value.
-We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"
-instead of computing "``x+3``" twice.
-
-Unfortunately, no amount of local analysis will be able to detect and
-correct this. This requires two transformations: reassociation of
-expressions (to make the add's lexically identical) and Common
-Subexpression Elimination (CSE) to delete the redundant add instruction.
-Fortunately, LLVM provides a broad range of optimizations that you can
-use, in the form of "passes".
-
-LLVM Optimization Passes
-========================
-
-LLVM provides many optimization passes, which do many different sorts of
-things and have different tradeoffs. Unlike other systems, LLVM doesn't
-hold to the mistaken notion that one set of optimizations is right for
-all languages and for all situations. LLVM allows a compiler implementor
-to make complete decisions about what optimizations to use, in which
-order, and in what situation.
-
-As a concrete example, LLVM supports both "whole module" passes, which
-look across as large of body of code as they can (often a whole file,
-but if run at link time, this can be a substantial portion of the whole
-program). It also supports and includes "per-function" passes which just
-operate on a single function at a time, without looking at other
-functions. For more information on passes and how they are run, see the
-`How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the
-`List of LLVM Passes <../Passes.html>`_.
-
-For Kaleidoscope, we are currently generating functions on the fly, one
-at a time, as the user types them in. We aren't shooting for the
-ultimate optimization experience in this setting, but we also want to
-catch the easy and quick stuff where possible. As such, we will choose
-to run a few per-function optimizations as the user types the function
-in. If we wanted to make a "static Kaleidoscope compiler", we would use
-exactly the code we have now, except that we would defer running the
-optimizer until the entire file has been parsed.
-
-In order to get per-function optimizations going, we need to set up a
-`FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
-and organize the LLVM optimizations that we want to run. Once we have
-that, we can add a set of optimizations to run. We'll need a new
-FunctionPassManager for each module that we want to optimize, so we'll
-write a function to create and initialize both the module and pass manager
-for us:
-
-.. code-block:: c++
-
- void InitializeModuleAndPassManager(void) {
- // Open a new module.
- Context LLVMContext;
- TheModule = llvm::make_unique<Module>("my cool jit", LLVMContext);
- TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
-
- // Create a new pass manager attached to it.
- TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
-
- // Provide basic AliasAnalysis support for GVN.
- TheFPM.add(createBasicAliasAnalysisPass());
- // Do simple "peephole" optimizations and bit-twiddling optzns.
- TheFPM.add(createInstructionCombiningPass());
- // Reassociate expressions.
- TheFPM.add(createReassociatePass());
- // Eliminate Common SubExpressions.
- TheFPM.add(createGVNPass());
- // Simplify the control flow graph (deleting unreachable blocks, etc).
- TheFPM.add(createCFGSimplificationPass());
-
- TheFPM.doInitialization();
- }
-
-This code initializes the global module ``TheModule``, and the function pass
-manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
-set up, we use a series of "add" calls to add a bunch of LLVM passes.
-
-In this case, we choose to add five passes: one analysis pass (alias analysis),
-and four optimization passes. The passes we choose here are a pretty standard set
-of "cleanup" optimizations that are useful for a wide variety of code. I won't
-delve into what they do but, believe me, they are a good starting place :).
-
-Once the PassManager is set up, we need to make use of it. We do this by
-running it after our newly created function is constructed (in
-``FunctionAST::codegen()``), but before it is returned to the client:
-
-.. code-block:: c++
-
- if (Value *RetVal = Body->codegen()) {
- // Finish off the function.
- Builder.CreateRet(RetVal);
-
- // Validate the generated code, checking for consistency.
- verifyFunction(*TheFunction);
-
- // Optimize the function.
- TheFPM->run(*TheFunction);
-
- return TheFunction;
- }
-
-As you can see, this is pretty straightforward. The
-``FunctionPassManager`` optimizes and updates the LLVM Function\* in
-place, improving (hopefully) its body. With this in place, we can try
-our test above again:
-
-::
-
- ready> def test(x) (1+2+x)*(x+(1+2));
- ready> Read function definition:
- define double @test(double %x) {
- entry:
- %addtmp = fadd double %x, 3.000000e+00
- %multmp = fmul double %addtmp, %addtmp
- ret double %multmp
- }
-
-As expected, we now get our nicely optimized code, saving a floating
-point add instruction from every execution of this function.
-
-LLVM provides a wide variety of optimizations that can be used in
-certain circumstances. Some `documentation about the various
-passes <../Passes.html>`_ is available, but it isn't very complete.
-Another good source of ideas can come from looking at the passes that
-``Clang`` runs to get started. The "``opt``" tool allows you to
-experiment with passes from the command line, so you can see if they do
-anything.
-
-Now that we have reasonable code coming out of our front-end, lets talk
-about executing it!
-
-Adding a JIT Compiler
-=====================
-
-Code that is available in LLVM IR can have a wide variety of tools
-applied to it. For example, you can run optimizations on it (as we did
-above), you can dump it out in textual or binary forms, you can compile
-the code to an assembly file (.s) for some target, or you can JIT
-compile it. The nice thing about the LLVM IR representation is that it
-is the "common currency" between many different parts of the compiler.
-
-In this section, we'll add JIT compiler support to our interpreter. The
-basic idea that we want for Kaleidoscope is to have the user enter
-function bodies as they do now, but immediately evaluate the top-level
-expressions they type in. For example, if they type in "1 + 2;", we
-should evaluate and print out 3. If they define a function, they should
-be able to call it from the command line.
-
-In order to do this, we first declare and initialize the JIT. This is
-done by adding a global variable ``TheJIT``, and initializing it in
-``main``:
-
-.. code-block:: c++
-
- static std::unique_ptr<KaleidoscopeJIT> TheJIT;
- ...
- int main() {
- ..
- TheJIT = llvm::make_unique<KaleidoscopeJIT>();
-
- // Run the main "interpreter loop" now.
- MainLoop();
-
- return 0;
- }
-
-The KaleidoscopeJIT class is a simple JIT built specifically for these
-tutorials. In later chapters we will look at how it works and extend it with
-new features, but for now we will take it as given. Its API is very simple::
-``addModule`` adds an LLVM IR module to the JIT, making its functions
-available for execution; ``removeModule`` removes a module, freeing any
-memory associated with the code in that module; and ``findSymbol`` allows us
-to look up pointers to the compiled code.
-
-We can take this simple API and change our code that parses top-level expressions to
-look like this:
-
-.. code-block:: c++
-
- static void HandleTopLevelExpression() {
- // Evaluate a top-level expression into an anonymous function.
- if (auto FnAST = ParseTopLevelExpr()) {
- if (FnAST->codegen()) {
-
- // JIT the module containing the anonymous expression, keeping a handle so
- // we can free it later.
- auto H = TheJIT->addModule(std::move(TheModule));
- InitializeModuleAndPassManager();
-
- // Search the JIT for the __anon_expr symbol.
- auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
- assert(ExprSymbol && "Function not found");
-
- // Get the symbol's address and cast it to the right type (takes no
- // arguments, returns a double) so we can call it as a native function.
- double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
- fprintf(stderr, "Evaluated to %f\n", FP());
-
- // Delete the anonymous expression module from the JIT.
- TheJIT->removeModule(H);
- }
-
-If parsing and codegen succeeed, the next step is to add the module containing
-the top-level expression to the JIT. We do this by calling addModule, which
-triggers code generation for all the functions in the module, and returns a
-handle that can be used to remove the module from the JIT later. Once the module
-has been added to the JIT it can no longer be modified, so we also open a new
-module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.
-
-Once we've added the module to the JIT we need to get a pointer to the final
-generated code. We do this by calling the JIT's findSymbol method, and passing
-the name of the top-level expression function: ``__anon_expr``. Since we just
-added this function, we assert that findSymbol returned a result.
-
-Next, we get the in-memory address of the ``__anon_expr`` function by calling
-``getAddress()`` on the symbol. Recall that we compile top-level expressions
-into a self-contained LLVM function that takes no arguments and returns the
-computed double. Because the LLVM JIT compiler matches the native platform ABI,
-this means that you can just cast the result pointer to a function pointer of
-that type and call it directly. This means, there is no difference between JIT
-compiled code and native machine code that is statically linked into your
-application.
-
-Finally, since we don't support re-evaluation of top-level expressions, we
-remove the module from the JIT when we're done to free the associated memory.
-Recall, however, that the module we created a few lines earlier (via
-``InitializeModuleAndPassManager``) is still open and waiting for new code to be
-added.
-
-With just these two changes, lets see how Kaleidoscope works now!
-
-::
-
- ready> 4+5;
- Read top-level expression:
- define double @0() {
- entry:
- ret double 9.000000e+00
- }
-
- Evaluated to 9.000000
-
-Well this looks like it is basically working. The dump of the function
-shows the "no argument function that always returns double" that we
-synthesize for each top-level expression that is typed in. This
-demonstrates very basic functionality, but can we do more?
-
-::
-
- ready> def testfunc(x y) x + y*2;
- Read function definition:
- define double @testfunc(double %x, double %y) {
- entry:
- %multmp = fmul double %y, 2.000000e+00
- %addtmp = fadd double %multmp, %x
- ret double %addtmp
- }
-
- ready> testfunc(4, 10);
- Read top-level expression:
- define double @1() {
- entry:
- %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
- ret double %calltmp
- }
-
- Evaluated to 24.000000
-
- ready> testfunc(5, 10);
- ready> LLVM ERROR: Program used external function 'testfunc' which could not be resolved!
-
-
-Function definitions and calls also work, but something went very wrong on that
-last line. The call looks valid, so what happened? As you may have guessed from
-the the API a Module is a unit of allocation for the JIT, and testfunc was part
-of the same module that contained anonymous expression. When we removed that
-module from the JIT to free the memory for the anonymous expression, we deleted
-the definition of ``testfunc`` along with it. Then, when we tried to call
-testfunc a second time, the JIT could no longer find it.
-
-The easiest way to fix this is to put the anonymous expression in a separate
-module from the rest of the function definitions. The JIT will happily resolve
-function calls across module boundaries, as long as each of the functions called
-has a prototype, and is added to the JIT before it is called. By putting the
-anonymous expression in a different module we can delete it without affecting
-the rest of the functions.
-
-In fact, we're going to go a step further and put every function in its own
-module. Doing so allows us to exploit a useful property of the KaleidoscopeJIT
-that will make our environment more REPL-like: Functions can be added to the
-JIT more than once (unlike a module where every function must have a unique
-definition). When you look up a symbol in KaleidoscopeJIT it will always return
-the most recent definition:
-
-::
-
- ready> def foo(x) x + 1;
- Read function definition:
- define double @foo(double %x) {
- entry:
- %addtmp = fadd double %x, 1.000000e+00
- ret double %addtmp
- }
-
- ready> foo(2);
- Evaluated to 3.000000
-
- ready> def foo(x) x + 2;
- define double @foo(double %x) {
- entry:
- %addtmp = fadd double %x, 2.000000e+00
- ret double %addtmp
- }
-
- ready> foo(2);
- Evaluated to 4.000000
-
-
-To allow each function to live in its own module we'll need a way to
-re-generate previous function declarations into each new module we open:
-
-.. code-block:: c++
-
- static std::unique_ptr<KaleidoscopeJIT> TheJIT;
-
- ...
-
- Function *getFunction(std::string Name) {
- // First, see if the function has already been added to the current module.
- if (auto *F = TheModule->getFunction(Name))
- return F;
-
- // If not, check whether we can codegen the declaration from some existing
- // prototype.
- auto FI = FunctionProtos.find(Name);
- if (FI != FunctionProtos.end())
- return FI->second->codegen();
-
- // If no existing prototype exists, return null.
- return nullptr;
- }
-
- ...
-
- Value *CallExprAST::codegen() {
- // Look up the name in the global module table.
- Function *CalleeF = getFunction(Callee);
-
- ...
-
- Function *FunctionAST::codegen() {
- // Transfer ownership of the prototype to the FunctionProtos map, but keep a
- // reference to it for use below.
- auto &P = *Proto;
- FunctionProtos[Proto->getName()] = std::move(Proto);
- Function *TheFunction = getFunction(P.getName());
- if (!TheFunction)
- return nullptr;
-
-
-To enable this, we'll start by adding a new global, ``FunctionProtos``, that
-holds the most recent prototype for each function. We'll also add a convenience
-method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.
-Our convenience method searches ``TheModule`` for an existing function
-declaration, falling back to generating a new declaration from FunctionProtos if
-it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the
-call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to
-update the FunctionProtos map first, then call ``getFunction()``. With this
-done, we can always obtain a function declaration in the current module for any
-previously declared function.
-
-We also need to update HandleDefinition and HandleExtern:
-
-.. code-block:: c++
-
- static void HandleDefinition() {
- if (auto FnAST = ParseDefinition()) {
- if (auto *FnIR = FnAST->codegen()) {
- fprintf(stderr, "Read function definition:");
- FnIR->dump();
- TheJIT->addModule(std::move(TheModule));
- InitializeModuleAndPassManager();
- }
- } else {
- // Skip token for error recovery.
- getNextToken();
- }
- }
-
- static void HandleExtern() {
- if (auto ProtoAST = ParseExtern()) {
- if (auto *FnIR = ProtoAST->codegen()) {
- fprintf(stderr, "Read extern: ");
- FnIR->dump();
- FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
- }
- } else {
- // Skip token for error recovery.
- getNextToken();
- }
- }
-
-In HandleDefinition, we add two lines to transfer the newly defined function to
-the JIT and open a new module. In HandleExtern, we just need to add one line to
-add the prototype to FunctionProtos.
-
-With these changes made, lets try our REPL again (I removed the dump of the
-anonymous functions this time, you should get the idea by now :) :
-
-::
-
- ready> def foo(x) x + 1;
- ready> foo(2);
- Evaluated to 3.000000
-
- ready> def foo(x) x + 2;
- ready> foo(2);
- Evaluated to 4.000000
-
-It works!
-
-Even with this simple code, we get some surprisingly powerful capabilities -
-check this out:
-
-::
-
- ready> extern sin(x);
- Read extern:
- declare double @sin(double)
-
- ready> extern cos(x);
- Read extern:
- declare double @cos(double)
-
- ready> sin(1.0);
- Read top-level expression:
- define double @2() {
- entry:
- ret double 0x3FEAED548F090CEE
- }
-
- Evaluated to 0.841471
-
- ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
- Read function definition:
- define double @foo(double %x) {
- entry:
- %calltmp = call double @sin(double %x)
- %multmp = fmul double %calltmp, %calltmp
- %calltmp2 = call double @cos(double %x)
- %multmp4 = fmul double %calltmp2, %calltmp2
- %addtmp = fadd double %multmp, %multmp4
- ret double %addtmp
- }
-
- ready> foo(4.0);
- Read top-level expression:
- define double @3() {
- entry:
- %calltmp = call double @foo(double 4.000000e+00)
- ret double %calltmp
- }
-
- Evaluated to 1.000000
-
-Whoa, how does the JIT know about sin and cos? The answer is surprisingly
-simple: The KaleidoscopeJIT has a straightforward symbol resolution rule that
-it uses to find symbols that aren't available in any given module: First
-it searches all the modules that have already been added to the JIT, from the
-most recent to the oldest, to find the newest definition. If no definition is
-found inside the JIT, it falls back to calling "``dlsym("sin")``" on the
-Kaleidoscope process itself. Since "``sin``" is defined within the JIT's
-address space, it simply patches up calls in the module to call the libm
-version of ``sin`` directly.
-
-In the future we'll see how tweaking this symbol resolution rule can be used to
-enable all sorts of useful features, from security (restricting the set of
-symbols available to JIT'd code), to dynamic code generation based on symbol
-names, and even lazy compilation.
-
-One immediate benefit of the symbol resolution rule is that we can now extend
-the language by writing arbitrary C++ code to implement operations. For example,
-if we add:
-
-.. code-block:: c++
-
- /// putchard - putchar that takes a double and returns 0.
- extern "C" double putchard(double X) {
- fputc((char)X, stderr);
- return 0;
- }
-
-Now we can produce simple output to the console by using things like:
-"``extern putchard(x); putchard(120);``", which prints a lowercase 'x'
-on the console (120 is the ASCII code for 'x'). Similar code could be
-used to implement file I/O, console input, and many other capabilities
-in Kaleidoscope.
-
-This completes the JIT and optimizer chapter of the Kaleidoscope
-tutorial. At this point, we can compile a non-Turing-complete
-programming language, optimize and JIT compile it in a user-driven way.
-Next up we'll look into `extending the language with control flow
-constructs <LangImpl5.html>`_, tackling some interesting LLVM IR issues
-along the way.
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-the LLVM JIT and optimizer. To build this example, use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
- # Run
- ./toy
-
-If you are compiling this on Linux, make sure to add the "-rdynamic"
-option as well. This makes sure that the external functions are resolved
-properly at runtime.
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp
- :language: c++
-
-`Next: Extending the language: control flow <LangImpl5.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl5-cfg.png
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5-cfg.png?rev=274440&view=auto
==============================================================================
Binary file - no diff available.
Removed: llvm/trunk/docs/tutorial/LangImpl5.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl5.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl5.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl5.rst (removed)
@@ -1,790 +0,0 @@
-==================================================
-Kaleidoscope: Extending the Language: Control Flow
-==================================================
-
-.. contents::
- :local:
-
-Chapter 5 Introduction
-======================
-
-Welcome to Chapter 5 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. Parts 1-4 described the implementation of
-the simple Kaleidoscope language and included support for generating
-LLVM IR, followed by optimizations and a JIT compiler. Unfortunately, as
-presented, Kaleidoscope is mostly useless: it has no control flow other
-than call and return. This means that you can't have conditional
-branches in the code, significantly limiting its power. In this episode
-of "build that compiler", we'll extend Kaleidoscope to have an
-if/then/else expression plus a simple 'for' loop.
-
-If/Then/Else
-============
-
-Extending Kaleidoscope to support if/then/else is quite straightforward.
-It basically requires adding support for this "new" concept to the
-lexer, parser, AST, and LLVM code emitter. This example is nice, because
-it shows how easy it is to "grow" a language over time, incrementally
-extending it as new ideas are discovered.
-
-Before we get going on "how" we add this extension, lets talk about
-"what" we want. The basic idea is that we want to be able to write this
-sort of thing:
-
-::
-
- def fib(x)
- if x < 3 then
- 1
- else
- fib(x-1)+fib(x-2);
-
-In Kaleidoscope, every construct is an expression: there are no
-statements. As such, the if/then/else expression needs to return a value
-like any other. Since we're using a mostly functional form, we'll have
-it evaluate its conditional, then return the 'then' or 'else' value
-based on how the condition was resolved. This is very similar to the C
-"?:" expression.
-
-The semantics of the if/then/else expression is that it evaluates the
-condition to a boolean equality value: 0.0 is considered to be false and
-everything else is considered to be true. If the condition is true, the
-first subexpression is evaluated and returned, if the condition is
-false, the second subexpression is evaluated and returned. Since
-Kaleidoscope allows side-effects, this behavior is important to nail
-down.
-
-Now that we know what we "want", lets break this down into its
-constituent pieces.
-
-Lexer Extensions for If/Then/Else
----------------------------------
-
-The lexer extensions are straightforward. First we add new enum values
-for the relevant tokens:
-
-.. code-block:: c++
-
- // control
- tok_if = -6,
- tok_then = -7,
- tok_else = -8,
-
-Once we have that, we recognize the new keywords in the lexer. This is
-pretty simple stuff:
-
-.. code-block:: c++
-
- ...
- if (IdentifierStr == "def")
- return tok_def;
- if (IdentifierStr == "extern")
- return tok_extern;
- if (IdentifierStr == "if")
- return tok_if;
- if (IdentifierStr == "then")
- return tok_then;
- if (IdentifierStr == "else")
- return tok_else;
- return tok_identifier;
-
-AST Extensions for If/Then/Else
--------------------------------
-
-To represent the new expression we add a new AST node for it:
-
-.. code-block:: c++
-
- /// IfExprAST - Expression class for if/then/else.
- class IfExprAST : public ExprAST {
- std::unique_ptr<ExprAST> Cond, Then, Else;
-
- public:
- IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
- std::unique_ptr<ExprAST> Else)
- : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
- virtual Value *codegen();
- };
-
-The AST node just has pointers to the various subexpressions.
-
-Parser Extensions for If/Then/Else
-----------------------------------
-
-Now that we have the relevant tokens coming from the lexer and we have
-the AST node to build, our parsing logic is relatively straightforward.
-First we define a new parsing function:
-
-.. code-block:: c++
-
- /// ifexpr ::= 'if' expression 'then' expression 'else' expression
- static std::unique_ptr<ExprAST> ParseIfExpr() {
- getNextToken(); // eat the if.
-
- // condition.
- auto Cond = ParseExpression();
- if (!Cond)
- return nullptr;
-
- if (CurTok != tok_then)
- return LogError("expected then");
- getNextToken(); // eat the then
-
- auto Then = ParseExpression();
- if (!Then)
- return nullptr;
-
- if (CurTok != tok_else)
- return LogError("expected else");
-
- getNextToken();
-
- auto Else = ParseExpression();
- if (!Else)
- return nullptr;
-
- return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
- std::move(Else));
- }
-
-Next we hook it up as a primary expression:
-
-.. code-block:: c++
-
- static std::unique_ptr<ExprAST> ParsePrimary() {
- switch (CurTok) {
- default:
- return LogError("unknown token when expecting an expression");
- case tok_identifier:
- return ParseIdentifierExpr();
- case tok_number:
- return ParseNumberExpr();
- case '(':
- return ParseParenExpr();
- case tok_if:
- return ParseIfExpr();
- }
- }
-
-LLVM IR for If/Then/Else
-------------------------
-
-Now that we have it parsing and building the AST, the final piece is
-adding LLVM code generation support. This is the most interesting part
-of the if/then/else example, because this is where it starts to
-introduce new concepts. All of the code above has been thoroughly
-described in previous chapters.
-
-To motivate the code we want to produce, lets take a look at a simple
-example. Consider:
-
-::
-
- extern foo();
- extern bar();
- def baz(x) if x then foo() else bar();
-
-If you disable optimizations, the code you'll (soon) get from
-Kaleidoscope looks like this:
-
-.. code-block:: llvm
-
- declare double @foo()
-
- declare double @bar()
-
- define double @baz(double %x) {
- entry:
- %ifcond = fcmp one double %x, 0.000000e+00
- br i1 %ifcond, label %then, label %else
-
- then: ; preds = %entry
- %calltmp = call double @foo()
- br label %ifcont
-
- else: ; preds = %entry
- %calltmp1 = call double @bar()
- br label %ifcont
-
- ifcont: ; preds = %else, %then
- %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
- ret double %iftmp
- }
-
-To visualize the control flow graph, you can use a nifty feature of the
-LLVM '`opt <http://llvm.org/cmds/opt.html>`_' tool. If you put this LLVM
-IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
-window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
-see this graph:
-
-.. figure:: LangImpl5-cfg.png
- :align: center
- :alt: Example CFG
-
- Example CFG
-
-Another way to get this is to call "``F->viewCFG()``" or
-"``F->viewCFGOnly()``" (where F is a "``Function*``") either by
-inserting actual calls into the code and recompiling or by calling these
-in the debugger. LLVM has many nice features for visualizing various
-graphs.
-
-Getting back to the generated code, it is fairly simple: the entry block
-evaluates the conditional expression ("x" in our case here) and compares
-the result to 0.0 with the "``fcmp one``" instruction ('one' is "Ordered
-and Not Equal"). Based on the result of this expression, the code jumps
-to either the "then" or "else" blocks, which contain the expressions for
-the true/false cases.
-
-Once the then/else blocks are finished executing, they both branch back
-to the 'ifcont' block to execute the code that happens after the
-if/then/else. In this case the only thing left to do is to return to the
-caller of the function. The question then becomes: how does the code
-know which expression to return?
-
-The answer to this question involves an important SSA operation: the
-`Phi
-operation <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
-If you're not familiar with SSA, `the wikipedia
-article <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
-is a good introduction and there are various other introductions to it
-available on your favorite search engine. The short version is that
-"execution" of the Phi operation requires "remembering" which block
-control came from. The Phi operation takes on the value corresponding to
-the input control block. In this case, if control comes in from the
-"then" block, it gets the value of "calltmp". If control comes from the
-"else" block, it gets the value of "calltmp1".
-
-At this point, you are probably starting to think "Oh no! This means my
-simple and elegant front-end will have to start generating SSA form in
-order to use LLVM!". Fortunately, this is not the case, and we strongly
-advise *not* implementing an SSA construction algorithm in your
-front-end unless there is an amazingly good reason to do so. In
-practice, there are two sorts of values that float around in code
-written for your average imperative programming language that might need
-Phi nodes:
-
-#. Code that involves user variables: ``x = 1; x = x + 1;``
-#. Values that are implicit in the structure of your AST, such as the
- Phi node in this case.
-
-In `Chapter 7 <LangImpl7.html>`_ of this tutorial ("mutable variables"),
-we'll talk about #1 in depth. For now, just believe me that you don't
-need SSA construction to handle this case. For #2, you have the choice
-of using the techniques that we will describe for #1, or you can insert
-Phi nodes directly, if convenient. In this case, it is really
-easy to generate the Phi node, so we choose to do it directly.
-
-Okay, enough of the motivation and overview, lets generate code!
-
-Code Generation for If/Then/Else
---------------------------------
-
-In order to generate code for this, we implement the ``codegen`` method
-for ``IfExprAST``:
-
-.. code-block:: c++
-
- Value *IfExprAST::codegen() {
- Value *CondV = Cond->codegen();
- if (!CondV)
- return nullptr;
-
- // Convert condition to a bool by comparing equal to 0.0.
- CondV = Builder.CreateFCmpONE(
- CondV, ConstantFP::get(LLVMContext, APFloat(0.0)), "ifcond");
-
-This code is straightforward and similar to what we saw before. We emit
-the expression for the condition, then compare that value to zero to get
-a truth value as a 1-bit (bool) value.
-
-.. code-block:: c++
-
- Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
- // Create blocks for the then and else cases. Insert the 'then' block at the
- // end of the function.
- BasicBlock *ThenBB =
- BasicBlock::Create(LLVMContext, "then", TheFunction);
- BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");
- BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");
-
- Builder.CreateCondBr(CondV, ThenBB, ElseBB);
-
-This code creates the basic blocks that are related to the if/then/else
-statement, and correspond directly to the blocks in the example above.
-The first line gets the current Function object that is being built. It
-gets this by asking the builder for the current BasicBlock, and asking
-that block for its "parent" (the function it is currently embedded
-into).
-
-Once it has that, it creates three blocks. Note that it passes
-"TheFunction" into the constructor for the "then" block. This causes the
-constructor to automatically insert the new block into the end of the
-specified function. The other two blocks are created, but aren't yet
-inserted into the function.
-
-Once the blocks are created, we can emit the conditional branch that
-chooses between them. Note that creating new blocks does not implicitly
-affect the IRBuilder, so it is still inserting into the block that the
-condition went into. Also note that it is creating a branch to the
-"then" block and the "else" block, even though the "else" block isn't
-inserted into the function yet. This is all ok: it is the standard way
-that LLVM supports forward references.
-
-.. code-block:: c++
-
- // Emit then value.
- Builder.SetInsertPoint(ThenBB);
-
- Value *ThenV = Then->codegen();
- if (!ThenV)
- return nullptr;
-
- Builder.CreateBr(MergeBB);
- // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
- ThenBB = Builder.GetInsertBlock();
-
-After the conditional branch is inserted, we move the builder to start
-inserting into the "then" block. Strictly speaking, this call moves the
-insertion point to be at the end of the specified block. However, since
-the "then" block is empty, it also starts out by inserting at the
-beginning of the block. :)
-
-Once the insertion point is set, we recursively codegen the "then"
-expression from the AST. To finish off the "then" block, we create an
-unconditional branch to the merge block. One interesting (and very
-important) aspect of the LLVM IR is that it `requires all basic blocks
-to be "terminated" <../LangRef.html#functionstructure>`_ with a `control
-flow instruction <../LangRef.html#terminators>`_ such as return or
-branch. This means that all control flow, *including fall throughs* must
-be made explicit in the LLVM IR. If you violate this rule, the verifier
-will emit an error.
-
-The final line here is quite subtle, but is very important. The basic
-issue is that when we create the Phi node in the merge block, we need to
-set up the block/value pairs that indicate how the Phi will work.
-Importantly, the Phi node expects to have an entry for each predecessor
-of the block in the CFG. Why then, are we getting the current block when
-we just set it to ThenBB 5 lines above? The problem is that the "Then"
-expression may actually itself change the block that the Builder is
-emitting into if, for example, it contains a nested "if/then/else"
-expression. Because calling ``codegen()`` recursively could arbitrarily change
-the notion of the current block, we are required to get an up-to-date
-value for code that will set up the Phi node.
-
-.. code-block:: c++
-
- // Emit else block.
- TheFunction->getBasicBlockList().push_back(ElseBB);
- Builder.SetInsertPoint(ElseBB);
-
- Value *ElseV = Else->codegen();
- if (!ElseV)
- return nullptr;
-
- Builder.CreateBr(MergeBB);
- // codegen of 'Else' can change the current block, update ElseBB for the PHI.
- ElseBB = Builder.GetInsertBlock();
-
-Code generation for the 'else' block is basically identical to codegen
-for the 'then' block. The only significant difference is the first line,
-which adds the 'else' block to the function. Recall previously that the
-'else' block was created, but not added to the function. Now that the
-'then' and 'else' blocks are emitted, we can finish up with the merge
-code:
-
-.. code-block:: c++
-
- // Emit merge block.
- TheFunction->getBasicBlockList().push_back(MergeBB);
- Builder.SetInsertPoint(MergeBB);
- PHINode *PN =
- Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");
-
- PN->addIncoming(ThenV, ThenBB);
- PN->addIncoming(ElseV, ElseBB);
- return PN;
- }
-
-The first two lines here are now familiar: the first adds the "merge"
-block to the Function object (it was previously floating, like the else
-block above). The second changes the insertion point so that newly
-created code will go into the "merge" block. Once that is done, we need
-to create the PHI node and set up the block/value pairs for the PHI.
-
-Finally, the CodeGen function returns the phi node as the value computed
-by the if/then/else expression. In our example above, this returned
-value will feed into the code for the top-level function, which will
-create the return instruction.
-
-Overall, we now have the ability to execute conditional code in
-Kaleidoscope. With this extension, Kaleidoscope is a fairly complete
-language that can calculate a wide variety of numeric functions. Next up
-we'll add another useful expression that is familiar from non-functional
-languages...
-
-'for' Loop Expression
-=====================
-
-Now that we know how to add basic control flow constructs to the
-language, we have the tools to add more powerful things. Lets add
-something more aggressive, a 'for' expression:
-
-::
-
- extern putchard(char)
- def printstar(n)
- for i = 1, i < n, 1.0 in
- putchard(42); # ascii 42 = '*'
-
- # print 100 '*' characters
- printstar(100);
-
-This expression defines a new variable ("i" in this case) which iterates
-from a starting value, while the condition ("i < n" in this case) is
-true, incrementing by an optional step value ("1.0" in this case). If
-the step value is omitted, it defaults to 1.0. While the loop is true,
-it executes its body expression. Because we don't have anything better
-to return, we'll just define the loop as always returning 0.0. In the
-future when we have mutable variables, it will get more useful.
-
-As before, lets talk about the changes that we need to Kaleidoscope to
-support this.
-
-Lexer Extensions for the 'for' Loop
------------------------------------
-
-The lexer extensions are the same sort of thing as for if/then/else:
-
-.. code-block:: c++
-
- ... in enum Token ...
- // control
- tok_if = -6, tok_then = -7, tok_else = -8,
- tok_for = -9, tok_in = -10
-
- ... in gettok ...
- if (IdentifierStr == "def")
- return tok_def;
- if (IdentifierStr == "extern")
- return tok_extern;
- if (IdentifierStr == "if")
- return tok_if;
- if (IdentifierStr == "then")
- return tok_then;
- if (IdentifierStr == "else")
- return tok_else;
- if (IdentifierStr == "for")
- return tok_for;
- if (IdentifierStr == "in")
- return tok_in;
- return tok_identifier;
-
-AST Extensions for the 'for' Loop
----------------------------------
-
-The AST node is just as simple. It basically boils down to capturing the
-variable name and the constituent expressions in the node.
-
-.. code-block:: c++
-
- /// ForExprAST - Expression class for for/in.
- class ForExprAST : public ExprAST {
- std::string VarName;
- std::unique_ptr<ExprAST> Start, End, Step, Body;
-
- public:
- ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
- std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
- std::unique_ptr<ExprAST> Body)
- : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
- Step(std::move(Step)), Body(std::move(Body)) {}
- virtual Value *codegen();
- };
-
-Parser Extensions for the 'for' Loop
-------------------------------------
-
-The parser code is also fairly standard. The only interesting thing here
-is handling of the optional step value. The parser code handles it by
-checking to see if the second comma is present. If not, it sets the step
-value to null in the AST node:
-
-.. code-block:: c++
-
- /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
- static std::unique_ptr<ExprAST> ParseForExpr() {
- getNextToken(); // eat the for.
-
- if (CurTok != tok_identifier)
- return LogError("expected identifier after for");
-
- std::string IdName = IdentifierStr;
- getNextToken(); // eat identifier.
-
- if (CurTok != '=')
- return LogError("expected '=' after for");
- getNextToken(); // eat '='.
-
-
- auto Start = ParseExpression();
- if (!Start)
- return nullptr;
- if (CurTok != ',')
- return LogError("expected ',' after for start value");
- getNextToken();
-
- auto End = ParseExpression();
- if (!End)
- return nullptr;
-
- // The step value is optional.
- std::unique_ptr<ExprAST> Step;
- if (CurTok == ',') {
- getNextToken();
- Step = ParseExpression();
- if (!Step)
- return nullptr;
- }
-
- if (CurTok != tok_in)
- return LogError("expected 'in' after for");
- getNextToken(); // eat 'in'.
-
- auto Body = ParseExpression();
- if (!Body)
- return nullptr;
-
- return llvm::make_unique<ForExprAST>(IdName, std::move(Start),
- std::move(End), std::move(Step),
- std::move(Body));
- }
-
-LLVM IR for the 'for' Loop
---------------------------
-
-Now we get to the good part: the LLVM IR we want to generate for this
-thing. With the simple example above, we get this LLVM IR (note that
-this dump is generated with optimizations disabled for clarity):
-
-.. code-block:: llvm
-
- declare double @putchard(double)
-
- define double @printstar(double %n) {
- entry:
- ; initial value = 1.0 (inlined into phi)
- br label %loop
-
- loop: ; preds = %loop, %entry
- %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
- ; body
- %calltmp = call double @putchard(double 4.200000e+01)
- ; increment
- %nextvar = fadd double %i, 1.000000e+00
-
- ; termination test
- %cmptmp = fcmp ult double %i, %n
- %booltmp = uitofp i1 %cmptmp to double
- %loopcond = fcmp one double %booltmp, 0.000000e+00
- br i1 %loopcond, label %loop, label %afterloop
-
- afterloop: ; preds = %loop
- ; loop always returns 0.0
- ret double 0.000000e+00
- }
-
-This loop contains all the same constructs we saw before: a phi node,
-several expressions, and some basic blocks. Lets see how this fits
-together.
-
-Code Generation for the 'for' Loop
-----------------------------------
-
-The first part of codegen is very simple: we just output the start
-expression for the loop value:
-
-.. code-block:: c++
-
- Value *ForExprAST::codegen() {
- // Emit the start code first, without 'variable' in scope.
- Value *StartVal = Start->codegen();
- if (StartVal == 0) return 0;
-
-With this out of the way, the next step is to set up the LLVM basic
-block for the start of the loop body. In the case above, the whole loop
-body is one block, but remember that the body code itself could consist
-of multiple blocks (e.g. if it contains an if/then/else or a for/in
-expression).
-
-.. code-block:: c++
-
- // Make the new basic block for the loop header, inserting after current
- // block.
- Function *TheFunction = Builder.GetInsertBlock()->getParent();
- BasicBlock *PreheaderBB = Builder.GetInsertBlock();
- BasicBlock *LoopBB =
- BasicBlock::Create(LLVMContext, "loop", TheFunction);
-
- // Insert an explicit fall through from the current block to the LoopBB.
- Builder.CreateBr(LoopBB);
-
-This code is similar to what we saw for if/then/else. Because we will
-need it to create the Phi node, we remember the block that falls through
-into the loop. Once we have that, we create the actual block that starts
-the loop and create an unconditional branch for the fall-through between
-the two blocks.
-
-.. code-block:: c++
-
- // Start insertion in LoopBB.
- Builder.SetInsertPoint(LoopBB);
-
- // Start the PHI node with an entry for Start.
- PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(LLVMContext),
- 2, VarName.c_str());
- Variable->addIncoming(StartVal, PreheaderBB);
-
-Now that the "preheader" for the loop is set up, we switch to emitting
-code for the loop body. To begin with, we move the insertion point and
-create the PHI node for the loop induction variable. Since we already
-know the incoming value for the starting value, we add it to the Phi
-node. Note that the Phi will eventually get a second value for the
-backedge, but we can't set it up yet (because it doesn't exist!).
-
-.. code-block:: c++
-
- // Within the loop, the variable is defined equal to the PHI node. If it
- // shadows an existing variable, we have to restore it, so save it now.
- Value *OldVal = NamedValues[VarName];
- NamedValues[VarName] = Variable;
-
- // Emit the body of the loop. This, like any other expr, can change the
- // current BB. Note that we ignore the value computed by the body, but don't
- // allow an error.
- if (!Body->codegen())
- return nullptr;
-
-Now the code starts to get more interesting. Our 'for' loop introduces a
-new variable to the symbol table. This means that our symbol table can
-now contain either function arguments or loop variables. To handle this,
-before we codegen the body of the loop, we add the loop variable as the
-current value for its name. Note that it is possible that there is a
-variable of the same name in the outer scope. It would be easy to make
-this an error (emit an error and return null if there is already an
-entry for VarName) but we choose to allow shadowing of variables. In
-order to handle this correctly, we remember the Value that we are
-potentially shadowing in ``OldVal`` (which will be null if there is no
-shadowed variable).
-
-Once the loop variable is set into the symbol table, the code
-recursively codegen's the body. This allows the body to use the loop
-variable: any references to it will naturally find it in the symbol
-table.
-
-.. code-block:: c++
-
- // Emit the step value.
- Value *StepVal = nullptr;
- if (Step) {
- StepVal = Step->codegen();
- if (!StepVal)
- return nullptr;
- } else {
- // If not specified, use 1.0.
- StepVal = ConstantFP::get(LLVMContext, APFloat(1.0));
- }
-
- Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
-
-Now that the body is emitted, we compute the next value of the iteration
-variable by adding the step value, or 1.0 if it isn't present.
-'``NextVar``' will be the value of the loop variable on the next
-iteration of the loop.
-
-.. code-block:: c++
-
- // Compute the end condition.
- Value *EndCond = End->codegen();
- if (!EndCond)
- return nullptr;
-
- // Convert condition to a bool by comparing equal to 0.0.
- EndCond = Builder.CreateFCmpONE(
- EndCond, ConstantFP::get(LLVMContext, APFloat(0.0)), "loopcond");
-
-Finally, we evaluate the exit value of the loop, to determine whether
-the loop should exit. This mirrors the condition evaluation for the
-if/then/else statement.
-
-.. code-block:: c++
-
- // Create the "after loop" block and insert it.
- BasicBlock *LoopEndBB = Builder.GetInsertBlock();
- BasicBlock *AfterBB =
- BasicBlock::Create(LLVMContext, "afterloop", TheFunction);
-
- // Insert the conditional branch into the end of LoopEndBB.
- Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-
- // Any new code will be inserted in AfterBB.
- Builder.SetInsertPoint(AfterBB);
-
-With the code for the body of the loop complete, we just need to finish
-up 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 exit condition, it creates a conditional branch that
-chooses between executing the loop again and exiting the loop. Any
-future code is emitted in the "afterloop" block, so it sets the
-insertion position to it.
-
-.. code-block:: c++
-
- // Add a new entry to the PHI node for the backedge.
- Variable->addIncoming(NextVar, LoopEndBB);
-
- // Restore the unshadowed variable.
- if (OldVal)
- NamedValues[VarName] = OldVal;
- else
- NamedValues.erase(VarName);
-
- // for expr always returns 0.0.
- return Constant::getNullValue(Type::getDoubleTy(LLVMContext));
- }
-
-The final code handles various cleanups: now that we have the "NextVar"
-value, we can add the incoming value to the loop PHI node. After that,
-we remove the loop variable from the symbol table, so that it isn't in
-scope after the for loop. Finally, code generation of the for loop
-always returns 0.0, so that is what we return from
-``ForExprAST::codegen()``.
-
-With this, we conclude the "adding control flow to Kaleidoscope" chapter
-of the tutorial. In this chapter we added two control flow constructs,
-and used them to motivate a couple of aspects of the LLVM IR that are
-important for front-end implementors to know. In the next chapter of our
-saga, we will get a bit crazier and add `user-defined
-operators <LangImpl6.html>`_ to our poor innocent language.
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-the if/then/else and for expressions.. To build this example, use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
- # Run
- ./toy
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp
- :language: c++
-
-`Next: Extending the language: user-defined operators <LangImpl6.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl6.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl6.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl6.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl6.rst (removed)
@@ -1,768 +0,0 @@
-============================================================
-Kaleidoscope: Extending the Language: User-defined Operators
-============================================================
-
-.. contents::
- :local:
-
-Chapter 6 Introduction
-======================
-
-Welcome to Chapter 6 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. At this point in our tutorial, we now
-have a fully functional language that is fairly minimal, but also
-useful. There is still one big problem with it, however. Our language
-doesn't have many useful operators (like division, logical negation, or
-even any comparisons besides less-than).
-
-This chapter of the tutorial takes a wild digression into adding
-user-defined operators to the simple and beautiful Kaleidoscope
-language. This digression now gives us a simple and ugly language in
-some ways, but also a powerful one at the same time. One of the great
-things about creating your own language is that you get to decide what
-is good or bad. In this tutorial we'll assume that it is okay to use
-this as a way to show some interesting parsing techniques.
-
-At the end of this tutorial, we'll run through an example Kaleidoscope
-application that `renders the Mandelbrot set <#kicking-the-tires>`_. This gives an
-example of what you can build with Kaleidoscope and its feature set.
-
-User-defined Operators: the Idea
-================================
-
-The "operator overloading" that we will add to Kaleidoscope is more
-general than languages like C++. In C++, you are only allowed to
-redefine existing operators: you can't programatically change the
-grammar, introduce new operators, change precedence levels, etc. In this
-chapter, we will add this capability to Kaleidoscope, which will let the
-user round out the set of operators that are supported.
-
-The point of going into user-defined operators in a tutorial like this
-is to show the power and flexibility of using a hand-written parser.
-Thus far, the parser we have been implementing uses recursive descent
-for most parts of the grammar and operator precedence parsing for the
-expressions. See `Chapter 2 <LangImpl2.html>`_ for details. Without
-using operator precedence parsing, it would be very difficult to allow
-the programmer to introduce new operators into the grammar: the grammar
-is dynamically extensible as the JIT runs.
-
-The two specific features we'll add are programmable unary operators
-(right now, Kaleidoscope has no unary operators at all) as well as
-binary operators. An example of this is:
-
-::
-
- # Logical unary not.
- def unary!(v)
- if v then
- 0
- else
- 1;
-
- # Define > with the same precedence as <.
- def binary> 10 (LHS RHS)
- RHS < LHS;
-
- # Binary "logical or", (note that it does not "short circuit")
- def binary| 5 (LHS RHS)
- if LHS then
- 1
- else if RHS then
- 1
- else
- 0;
-
- # Define = with slightly lower precedence than relationals.
- def binary= 9 (LHS RHS)
- !(LHS < RHS | LHS > RHS);
-
-Many languages aspire to being able to implement their standard runtime
-library in the language itself. In Kaleidoscope, we can implement
-significant parts of the language in the library!
-
-We will break down implementation of these features into two parts:
-implementing support for user-defined binary operators and adding unary
-operators.
-
-User-defined Binary Operators
-=============================
-
-Adding support for user-defined binary operators is pretty simple with
-our current framework. We'll first add support for the unary/binary
-keywords:
-
-.. code-block:: c++
-
- enum Token {
- ...
- // operators
- tok_binary = -11,
- tok_unary = -12
- };
- ...
- static int gettok() {
- ...
- if (IdentifierStr == "for")
- return tok_for;
- if (IdentifierStr == "in")
- return tok_in;
- if (IdentifierStr == "binary")
- return tok_binary;
- if (IdentifierStr == "unary")
- return tok_unary;
- return tok_identifier;
-
-This just adds lexer support for the unary and binary keywords, like we
-did in `previous chapters <LangImpl5.html#lexer-extensions-for-if-then-else>`_. One nice thing
-about our current AST, is that we represent binary operators with full
-generalisation by using their ASCII code as the opcode. For our extended
-operators, we'll use this same representation, so we don't need any new
-AST or parser support.
-
-On the other hand, we have to be able to represent the definitions of
-these new operators, in the "def binary\| 5" part of the function
-definition. In our grammar so far, the "name" for the function
-definition is parsed as the "prototype" production and into the
-``PrototypeAST`` AST node. To represent our new user-defined operators
-as prototypes, we have to extend the ``PrototypeAST`` AST node like
-this:
-
-.. code-block:: c++
-
- /// PrototypeAST - This class represents the "prototype" for a function,
- /// which captures its argument names as well as if it is an operator.
- class PrototypeAST {
- std::string Name;
- std::vector<std::string> Args;
- bool IsOperator;
- unsigned Precedence; // Precedence if a binary op.
-
- public:
- PrototypeAST(const std::string &name, std::vector<std::string> Args,
- bool IsOperator = false, unsigned Prec = 0)
- : Name(name), Args(std::move(Args)), IsOperator(IsOperator),
- Precedence(Prec) {}
-
- bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
- bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
-
- char getOperatorName() const {
- assert(isUnaryOp() || isBinaryOp());
- return Name[Name.size()-1];
- }
-
- unsigned getBinaryPrecedence() const { return Precedence; }
-
- Function *codegen();
- };
-
-Basically, in addition to knowing a name for the prototype, we now keep
-track of whether it was an operator, and if it was, what precedence
-level the operator is at. The precedence is only used for binary
-operators (as you'll see below, it just doesn't apply for unary
-operators). Now that we have a way to represent the prototype for a
-user-defined operator, we need to parse it:
-
-.. code-block:: c++
-
- /// prototype
- /// ::= id '(' id* ')'
- /// ::= binary LETTER number? (id, id)
- static std::unique_ptr<PrototypeAST> ParsePrototype() {
- std::string FnName;
-
- unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
- unsigned BinaryPrecedence = 30;
-
- switch (CurTok) {
- default:
- return LogErrorP("Expected function name in prototype");
- case tok_identifier:
- FnName = IdentifierStr;
- Kind = 0;
- getNextToken();
- break;
- case tok_binary:
- getNextToken();
- if (!isascii(CurTok))
- return LogErrorP("Expected binary operator");
- FnName = "binary";
- FnName += (char)CurTok;
- Kind = 2;
- getNextToken();
-
- // Read the precedence if present.
- if (CurTok == tok_number) {
- if (NumVal < 1 || NumVal > 100)
- return LogErrorP("Invalid precedecnce: must be 1..100");
- BinaryPrecedence = (unsigned)NumVal;
- getNextToken();
- }
- break;
- }
-
- if (CurTok != '(')
- return LogErrorP("Expected '(' in prototype");
-
- std::vector<std::string> ArgNames;
- while (getNextToken() == tok_identifier)
- ArgNames.push_back(IdentifierStr);
- if (CurTok != ')')
- return LogErrorP("Expected ')' in prototype");
-
- // success.
- getNextToken(); // eat ')'.
-
- // Verify right number of names for operator.
- if (Kind && ArgNames.size() != Kind)
- return LogErrorP("Invalid number of operands for operator");
-
- return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,
- BinaryPrecedence);
- }
-
-This is all fairly straightforward parsing code, and we have already
-seen a lot of similar code in the past. One interesting part about the
-code above is the couple lines that set up ``FnName`` for binary
-operators. This builds names like "binary@" for a newly defined "@"
-operator. This then takes advantage of the fact that symbol names in the
-LLVM symbol table are allowed to have any character in them, including
-embedded nul characters.
-
-The next interesting thing to add, is codegen support for these binary
-operators. Given our current structure, this is a simple addition of a
-default case for our existing binary operator node:
-
-.. code-block:: c++
-
- Value *BinaryExprAST::codegen() {
- Value *L = LHS->codegen();
- Value *R = RHS->codegen();
- if (!L || !R)
- return nullptr;
-
- switch (Op) {
- case '+':
- return Builder.CreateFAdd(L, R, "addtmp");
- case '-':
- return Builder.CreateFSub(L, R, "subtmp");
- case '*':
- return Builder.CreateFMul(L, R, "multmp");
- case '<':
- L = Builder.CreateFCmpULT(L, R, "cmptmp");
- // Convert bool 0/1 to double 0.0 or 1.0
- return Builder.CreateUIToFP(L, Type::getDoubleTy(LLVMContext),
- "booltmp");
- default:
- break;
- }
-
- // If it wasn't a builtin binary operator, it must be a user defined one. Emit
- // a call to it.
- Function *F = TheModule->getFunction(std::string("binary") + Op);
- assert(F && "binary operator not found!");
-
- Value *Ops[2] = { L, R };
- return Builder.CreateCall(F, Ops, "binop");
- }
-
-As you can see above, the new code is actually really simple. It just
-does a lookup for the appropriate operator in the symbol table and
-generates a function call to it. Since user-defined operators are just
-built as normal functions (because the "prototype" boils down to a
-function with the right name) everything falls into place.
-
-The final piece of code we are missing, is a bit of top-level magic:
-
-.. code-block:: c++
-
- Function *FunctionAST::codegen() {
- NamedValues.clear();
-
- Function *TheFunction = Proto->codegen();
- if (!TheFunction)
- return nullptr;
-
- // If this is an operator, install it.
- if (Proto->isBinaryOp())
- BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
-
- // Create a new basic block to start insertion into.
- BasicBlock *BB = BasicBlock::Create(LLVMContext, "entry", TheFunction);
- Builder.SetInsertPoint(BB);
-
- if (Value *RetVal = Body->codegen()) {
- ...
-
-Basically, before codegening a function, if it is a user-defined
-operator, we register it in the precedence table. This allows the binary
-operator parsing logic we already have in place to handle it. Since we
-are working on a fully-general operator precedence parser, this is all
-we need to do to "extend the grammar".
-
-Now we have useful user-defined binary operators. This builds a lot on
-the previous framework we built for other operators. Adding unary
-operators is a bit more challenging, because we don't have any framework
-for it yet - lets see what it takes.
-
-User-defined Unary Operators
-============================
-
-Since we don't currently support unary operators in the Kaleidoscope
-language, we'll need to add everything to support them. Above, we added
-simple support for the 'unary' keyword to the lexer. In addition to
-that, we need an AST node:
-
-.. code-block:: c++
-
- /// UnaryExprAST - Expression class for a unary operator.
- class UnaryExprAST : public ExprAST {
- char Opcode;
- std::unique_ptr<ExprAST> Operand;
-
- public:
- UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
- : Opcode(Opcode), Operand(std::move(Operand)) {}
- virtual Value *codegen();
- };
-
-This AST node is very simple and obvious by now. It directly mirrors the
-binary operator AST node, except that it only has one child. With this,
-we need to add the parsing logic. Parsing a unary operator is pretty
-simple: we'll add a new function to do it:
-
-.. code-block:: c++
-
- /// unary
- /// ::= primary
- /// ::= '!' unary
- static std::unique_ptr<ExprAST> ParseUnary() {
- // If the current token is not an operator, it must be a primary expr.
- if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
- return ParsePrimary();
-
- // If this is a unary operator, read it.
- int Opc = CurTok;
- getNextToken();
- if (auto Operand = ParseUnary())
- return llvm::unique_ptr<UnaryExprAST>(Opc, std::move(Operand));
- return nullptr;
- }
-
-The grammar we add is pretty straightforward here. If we see a unary
-operator when parsing a primary operator, we eat the operator as a
-prefix and parse the remaining piece as another unary operator. This
-allows us to handle multiple unary operators (e.g. "!!x"). Note that
-unary operators can't have ambiguous parses like binary operators can,
-so there is no need for precedence information.
-
-The problem with this function, is that we need to call ParseUnary from
-somewhere. To do this, we change previous callers of ParsePrimary to
-call ParseUnary instead:
-
-.. code-block:: c++
-
- /// binoprhs
- /// ::= ('+' unary)*
- static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
- std::unique_ptr<ExprAST> LHS) {
- ...
- // Parse the unary expression after the binary operator.
- auto RHS = ParseUnary();
- if (!RHS)
- return nullptr;
- ...
- }
- /// expression
- /// ::= unary binoprhs
- ///
- static std::unique_ptr<ExprAST> ParseExpression() {
- auto LHS = ParseUnary();
- if (!LHS)
- return nullptr;
-
- return ParseBinOpRHS(0, std::move(LHS));
- }
-
-With these two simple changes, we are now able to parse unary operators
-and build the AST for them. Next up, we need to add parser support for
-prototypes, to parse the unary operator prototype. We extend the binary
-operator code above with:
-
-.. code-block:: c++
-
- /// prototype
- /// ::= id '(' id* ')'
- /// ::= binary LETTER number? (id, id)
- /// ::= unary LETTER (id)
- static std::unique_ptr<PrototypeAST> ParsePrototype() {
- std::string FnName;
-
- unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
- unsigned BinaryPrecedence = 30;
-
- switch (CurTok) {
- default:
- return LogErrorP("Expected function name in prototype");
- case tok_identifier:
- FnName = IdentifierStr;
- Kind = 0;
- getNextToken();
- break;
- case tok_unary:
- getNextToken();
- if (!isascii(CurTok))
- return LogErrorP("Expected unary operator");
- FnName = "unary";
- FnName += (char)CurTok;
- Kind = 1;
- getNextToken();
- break;
- case tok_binary:
- ...
-
-As with binary operators, we name unary operators with a name that
-includes the operator character. This assists us at code generation
-time. Speaking of, the final piece we need to add is codegen support for
-unary operators. It looks like this:
-
-.. code-block:: c++
-
- Value *UnaryExprAST::codegen() {
- Value *OperandV = Operand->codegen();
- if (!OperandV)
- return nullptr;
-
- Function *F = TheModule->getFunction(std::string("unary")+Opcode);
- if (!F)
- return LogErrorV("Unknown unary operator");
-
- return Builder.CreateCall(F, OperandV, "unop");
- }
-
-This code is similar to, but simpler than, the code for binary
-operators. It is simpler primarily because it doesn't need to handle any
-predefined operators.
-
-Kicking the Tires
-=================
-
-It is somewhat hard to believe, but with a few simple extensions we've
-covered in the last chapters, we have grown a real-ish language. With
-this, we can do a lot of interesting things, including I/O, math, and a
-bunch of other things. For example, we can now add a nice sequencing
-operator (printd is defined to print out the specified value and a
-newline):
-
-::
-
- ready> extern printd(x);
- Read extern:
- declare double @printd(double)
-
- ready> def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.
- ..
- ready> printd(123) : printd(456) : printd(789);
- 123.000000
- 456.000000
- 789.000000
- Evaluated to 0.000000
-
-We can also define a bunch of other "primitive" operations, such as:
-
-::
-
- # Logical unary not.
- def unary!(v)
- if v then
- 0
- else
- 1;
-
- # Unary negate.
- def unary-(v)
- 0-v;
-
- # Define > with the same precedence as <.
- def binary> 10 (LHS RHS)
- RHS < LHS;
-
- # Binary logical or, which does not short circuit.
- def binary| 5 (LHS RHS)
- if LHS then
- 1
- else if RHS then
- 1
- else
- 0;
-
- # Binary logical and, which does not short circuit.
- def binary& 6 (LHS RHS)
- if !LHS then
- 0
- else
- !!RHS;
-
- # Define = with slightly lower precedence than relationals.
- def binary = 9 (LHS RHS)
- !(LHS < RHS | LHS > RHS);
-
- # Define ':' for sequencing: as a low-precedence operator that ignores operands
- # and just returns the RHS.
- def binary : 1 (x y) y;
-
-Given the previous if/then/else support, we can also define interesting
-functions for I/O. For example, the following prints out a character
-whose "density" reflects the value passed in: the lower the value, the
-denser the character:
-
-::
-
- ready>
-
- extern putchard(char)
- def printdensity(d)
- if d > 8 then
- putchard(32) # ' '
- else if d > 4 then
- putchard(46) # '.'
- else if d > 2 then
- putchard(43) # '+'
- else
- putchard(42); # '*'
- ...
- ready> printdensity(1): printdensity(2): printdensity(3):
- printdensity(4): printdensity(5): printdensity(9):
- putchard(10);
- **++.
- Evaluated to 0.000000
-
-Based on these simple primitive operations, we can start to define more
-interesting things. For example, here's a little function that solves
-for the number of iterations it takes a function in the complex plane to
-converge:
-
-::
-
- # Determine whether the specific location diverges.
- # Solve for z = z^2 + c in the complex plane.
- def mandelconverger(real imag iters creal cimag)
- if iters > 255 | (real*real + imag*imag > 4) then
- iters
- else
- mandelconverger(real*real - imag*imag + creal,
- 2*real*imag + cimag,
- iters+1, creal, cimag);
-
- # Return the number of iterations required for the iteration to escape
- def mandelconverge(real imag)
- mandelconverger(real, imag, 0, real, imag);
-
-This "``z = z2 + c``" function is a beautiful little creature that is
-the basis for computation of the `Mandelbrot
-Set <http://en.wikipedia.org/wiki/Mandelbrot_set>`_. Our
-``mandelconverge`` function returns the number of iterations that it
-takes for a complex orbit to escape, saturating to 255. This is not a
-very useful function by itself, but if you plot its value over a
-two-dimensional plane, you can see the Mandelbrot set. Given that we are
-limited to using putchard here, our amazing graphical output is limited,
-but we can whip together something using the density plotter above:
-
-::
-
- # Compute and plot the mandelbrot set with the specified 2 dimensional range
- # info.
- def mandelhelp(xmin xmax xstep ymin ymax ystep)
- for y = ymin, y < ymax, ystep in (
- (for x = xmin, x < xmax, xstep in
- printdensity(mandelconverge(x,y)))
- : putchard(10)
- )
-
- # mandel - This is a convenient helper function for plotting the mandelbrot set
- # from the specified position with the specified Magnification.
- def mandel(realstart imagstart realmag imagmag)
- mandelhelp(realstart, realstart+realmag*78, realmag,
- imagstart, imagstart+imagmag*40, imagmag);
-
-Given this, we can try plotting out the mandelbrot set! Lets try it out:
-
-::
-
- ready> mandel(-2.3, -1.3, 0.05, 0.07);
- *******************************+++++++++++*************************************
- *************************+++++++++++++++++++++++*******************************
- **********************+++++++++++++++++++++++++++++****************************
- *******************+++++++++++++++++++++.. ...++++++++*************************
- *****************++++++++++++++++++++++.... ...+++++++++***********************
- ***************+++++++++++++++++++++++..... ...+++++++++*********************
- **************+++++++++++++++++++++++.... ....+++++++++********************
- *************++++++++++++++++++++++...... .....++++++++*******************
- ************+++++++++++++++++++++....... .......+++++++******************
- ***********+++++++++++++++++++.... ... .+++++++*****************
- **********+++++++++++++++++....... .+++++++****************
- *********++++++++++++++........... ...+++++++***************
- ********++++++++++++............ ...++++++++**************
- ********++++++++++... .......... .++++++++**************
- *******+++++++++..... .+++++++++*************
- *******++++++++...... ..+++++++++*************
- *******++++++....... ..+++++++++*************
- *******+++++...... ..+++++++++*************
- *******.... .... ...+++++++++*************
- *******.... . ...+++++++++*************
- *******+++++...... ...+++++++++*************
- *******++++++....... ..+++++++++*************
- *******++++++++...... .+++++++++*************
- *******+++++++++..... ..+++++++++*************
- ********++++++++++... .......... .++++++++**************
- ********++++++++++++............ ...++++++++**************
- *********++++++++++++++.......... ...+++++++***************
- **********++++++++++++++++........ .+++++++****************
- **********++++++++++++++++++++.... ... ..+++++++****************
- ***********++++++++++++++++++++++....... .......++++++++*****************
- ************+++++++++++++++++++++++...... ......++++++++******************
- **************+++++++++++++++++++++++.... ....++++++++********************
- ***************+++++++++++++++++++++++..... ...+++++++++*********************
- *****************++++++++++++++++++++++.... ...++++++++***********************
- *******************+++++++++++++++++++++......++++++++*************************
- *********************++++++++++++++++++++++.++++++++***************************
- *************************+++++++++++++++++++++++*******************************
- ******************************+++++++++++++************************************
- *******************************************************************************
- *******************************************************************************
- *******************************************************************************
- Evaluated to 0.000000
- ready> mandel(-2, -1, 0.02, 0.04);
- **************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
- ***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- *********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
- *******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
- *****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
- ***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
- **************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
- ************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
- ***********++++++++++++++++++++++++++++++++++++++++++++++++++........ .
- **********++++++++++++++++++++++++++++++++++++++++++++++.............
- ********+++++++++++++++++++++++++++++++++++++++++++..................
- *******+++++++++++++++++++++++++++++++++++++++.......................
- ******+++++++++++++++++++++++++++++++++++...........................
- *****++++++++++++++++++++++++++++++++............................
- *****++++++++++++++++++++++++++++...............................
- ****++++++++++++++++++++++++++...... .........................
- ***++++++++++++++++++++++++......... ...... ...........
- ***++++++++++++++++++++++............
- **+++++++++++++++++++++..............
- **+++++++++++++++++++................
- *++++++++++++++++++.................
- *++++++++++++++++............ ...
- *++++++++++++++..............
- *+++....++++................
- *.......... ...........
- *
- *.......... ...........
- *+++....++++................
- *++++++++++++++..............
- *++++++++++++++++............ ...
- *++++++++++++++++++.................
- **+++++++++++++++++++................
- **+++++++++++++++++++++..............
- ***++++++++++++++++++++++............
- ***++++++++++++++++++++++++......... ...... ...........
- ****++++++++++++++++++++++++++...... .........................
- *****++++++++++++++++++++++++++++...............................
- *****++++++++++++++++++++++++++++++++............................
- ******+++++++++++++++++++++++++++++++++++...........................
- *******+++++++++++++++++++++++++++++++++++++++.......................
- ********+++++++++++++++++++++++++++++++++++++++++++..................
- Evaluated to 0.000000
- ready> mandel(-0.9, -1.4, 0.02, 0.03);
- *******************************************************************************
- *******************************************************************************
- *******************************************************************************
- **********+++++++++++++++++++++************************************************
- *+++++++++++++++++++++++++++++++++++++++***************************************
- +++++++++++++++++++++++++++++++++++++++++++++**********************************
- ++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
- ++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
- +++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
- +++++++++++++++++++++++++++++++.... ......+++++++++++++++++++****************
- +++++++++++++++++++++++++++++....... ........+++++++++++++++++++**************
- ++++++++++++++++++++++++++++........ ........++++++++++++++++++++************
- +++++++++++++++++++++++++++......... .. ...+++++++++++++++++++++**********
- ++++++++++++++++++++++++++........... ....++++++++++++++++++++++********
- ++++++++++++++++++++++++............. .......++++++++++++++++++++++******
- +++++++++++++++++++++++............. ........+++++++++++++++++++++++****
- ++++++++++++++++++++++........... ..........++++++++++++++++++++++***
- ++++++++++++++++++++........... .........++++++++++++++++++++++*
- ++++++++++++++++++............ ...........++++++++++++++++++++
- ++++++++++++++++............... .............++++++++++++++++++
- ++++++++++++++................. ...............++++++++++++++++
- ++++++++++++.................. .................++++++++++++++
- +++++++++.................. .................+++++++++++++
- ++++++........ . ......... ..++++++++++++
- ++............ ...... ....++++++++++
- .............. ...++++++++++
- .............. ....+++++++++
- .............. .....++++++++
- ............. ......++++++++
- ........... .......++++++++
- ......... ........+++++++
- ......... ........+++++++
- ......... ....+++++++
- ........ ...+++++++
- ....... ...+++++++
- ....+++++++
- .....+++++++
- ....+++++++
- ....+++++++
- ....+++++++
- Evaluated to 0.000000
- ready> ^D
-
-At this point, you may be starting to realize that Kaleidoscope is a
-real and powerful language. It may not be self-similar :), but it can be
-used to plot things that are!
-
-With this, we conclude the "adding user-defined operators" chapter of
-the tutorial. We have successfully augmented our language, adding the
-ability to extend the language in the library, and we have shown how
-this can be used to build a simple but interesting end-user application
-in Kaleidoscope. At this point, Kaleidoscope can build a variety of
-applications that are functional and can call functions with
-side-effects, but it can't actually define and mutate a variable itself.
-
-Strikingly, variable mutation is an important feature of some languages,
-and it is not at all obvious how to `add support for mutable
-variables <LangImpl7.html>`_ without having to add an "SSA construction"
-phase to your front-end. In the next chapter, we will describe how you
-can add variable mutation without building SSA in your front-end.
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-the if/then/else and for expressions.. To build this example, use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
- # Run
- ./toy
-
-On some platforms, you will need to specify -rdynamic or
--Wl,--export-dynamic when linking. This ensures that symbols defined in
-the main executable are exported to the dynamic linker and so are
-available for symbol resolution at run time. This is not needed if you
-compile your support code into a shared library, although doing that
-will cause problems on Windows.
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter6/toy.cpp
- :language: c++
-
-`Next: Extending the language: mutable variables / SSA
-construction <LangImpl7.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl7.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl7.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl7.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl7.rst (removed)
@@ -1,881 +0,0 @@
-=======================================================
-Kaleidoscope: Extending the Language: Mutable Variables
-=======================================================
-
-.. contents::
- :local:
-
-Chapter 7 Introduction
-======================
-
-Welcome to Chapter 7 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. In chapters 1 through 6, we've built a
-very respectable, albeit simple, `functional programming
-language <http://en.wikipedia.org/wiki/Functional_programming>`_. In our
-journey, we learned some parsing techniques, how to build and represent
-an AST, how to build LLVM IR, and how to optimize the resultant code as
-well as JIT compile it.
-
-While Kaleidoscope is interesting as a functional language, the fact
-that it is functional makes it "too easy" to generate LLVM IR for it. In
-particular, a functional language makes it very easy to build LLVM IR
-directly in `SSA
-form <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
-Since LLVM requires that the input code be in SSA form, this is a very
-nice property and it is often unclear to newcomers how to generate code
-for an imperative language with mutable variables.
-
-The short (and happy) summary of this chapter is that there is no need
-for your front-end to build SSA form: LLVM provides highly tuned and
-well tested support for this, though the way it works is a bit
-unexpected for some.
-
-Why is this a hard problem?
-===========================
-
-To understand why mutable variables cause complexities in SSA
-construction, consider this extremely simple C example:
-
-.. code-block:: c
-
- int G, H;
- int test(_Bool Condition) {
- int X;
- if (Condition)
- X = G;
- else
- X = H;
- return X;
- }
-
-In this case, we have the variable "X", whose value depends on the path
-executed in the program. Because there are two different possible values
-for X before the return instruction, a PHI node is inserted to merge the
-two values. The LLVM IR that we want for this example looks like this:
-
-.. code-block:: llvm
-
- @G = weak global i32 0 ; type of @G is i32*
- @H = weak global i32 0 ; type of @H is i32*
-
- define i32 @test(i1 %Condition) {
- entry:
- br i1 %Condition, label %cond_true, label %cond_false
-
- cond_true:
- %X.0 = load i32* @G
- br label %cond_next
-
- cond_false:
- %X.1 = load i32* @H
- br label %cond_next
-
- cond_next:
- %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
- ret i32 %X.2
- }
-
-In this example, the loads from the G and H global variables are
-explicit in the LLVM IR, and they live in the then/else branches of the
-if statement (cond\_true/cond\_false). In order to merge the incoming
-values, the X.2 phi node in the cond\_next block selects the right value
-to use based on where control flow is coming from: if control flow comes
-from the cond\_false block, X.2 gets the value of X.1. Alternatively, if
-control flow comes from cond\_true, it gets the value of X.0. The intent
-of this chapter is not to explain the details of SSA form. For more
-information, see one of the many `online
-references <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_.
-
-The question for this article is "who places the phi nodes when lowering
-assignments to mutable variables?". The issue here is that LLVM
-*requires* that its IR be in SSA form: there is no "non-ssa" mode for
-it. However, SSA construction requires non-trivial algorithms and data
-structures, so it is inconvenient and wasteful for every front-end to
-have to reproduce this logic.
-
-Memory in LLVM
-==============
-
-The 'trick' here is that while LLVM does require all register values to
-be in SSA form, it does not require (or permit) memory objects to be in
-SSA form. In the example above, note that the loads from G and H are
-direct accesses to G and H: they are not renamed or versioned. This
-differs from some other compiler systems, which do try to version memory
-objects. In LLVM, instead of encoding dataflow analysis of memory into
-the LLVM IR, it is handled with `Analysis
-Passes <../WritingAnLLVMPass.html>`_ which are computed on demand.
-
-With this in mind, the high-level idea is that we want to make a stack
-variable (which lives in memory, because it is on the stack) for each
-mutable object in a function. To take advantage of this trick, we need
-to talk about how LLVM represents stack variables.
-
-In LLVM, all memory accesses are explicit with load/store instructions,
-and it is carefully designed not to have (or need) an "address-of"
-operator. Notice how the type of the @G/@H global variables is actually
-"i32\*" even though the variable is defined as "i32". What this means is
-that @G defines *space* for an i32 in the global data area, but its
-*name* actually refers to the address for that space. Stack variables
-work the same way, except that instead of being declared with global
-variable definitions, they are declared with the `LLVM alloca
-instruction <../LangRef.html#alloca-instruction>`_:
-
-.. code-block:: llvm
-
- define i32 @example() {
- entry:
- %X = alloca i32 ; type of %X is i32*.
- ...
- %tmp = load i32* %X ; load the stack value %X from the stack.
- %tmp2 = add i32 %tmp, 1 ; increment it
- store i32 %tmp2, i32* %X ; store it back
- ...
-
-This code shows an example of how you can declare and manipulate a stack
-variable in the LLVM IR. Stack memory allocated with the alloca
-instruction is fully general: you can pass the address of the stack slot
-to functions, you can store it in other variables, etc. In our example
-above, we could rewrite the example to use the alloca technique to avoid
-using a PHI node:
-
-.. code-block:: llvm
-
- @G = weak global i32 0 ; type of @G is i32*
- @H = weak global i32 0 ; type of @H is i32*
-
- define i32 @test(i1 %Condition) {
- entry:
- %X = alloca i32 ; type of %X is i32*.
- br i1 %Condition, label %cond_true, label %cond_false
-
- cond_true:
- %X.0 = load i32* @G
- store i32 %X.0, i32* %X ; Update X
- br label %cond_next
-
- cond_false:
- %X.1 = load i32* @H
- store i32 %X.1, i32* %X ; Update X
- br label %cond_next
-
- cond_next:
- %X.2 = load i32* %X ; Read X
- ret i32 %X.2
- }
-
-With this, we have discovered a way to handle arbitrary mutable
-variables without the need to create Phi nodes at all:
-
-#. Each mutable variable becomes a stack allocation.
-#. Each read of the variable becomes a load from the stack.
-#. Each update of the variable becomes a store to the stack.
-#. Taking the address of a variable just uses the stack address
- directly.
-
-While this solution has solved our immediate problem, it introduced
-another one: we have now apparently introduced a lot of stack traffic
-for very simple and common operations, a major performance problem.
-Fortunately for us, the LLVM optimizer has a highly-tuned optimization
-pass named "mem2reg" that handles this case, promoting allocas like this
-into SSA registers, inserting Phi nodes as appropriate. If you run this
-example through the pass, for example, you'll get:
-
-.. code-block:: bash
-
- $ llvm-as < example.ll | opt -mem2reg | llvm-dis
- @G = weak global i32 0
- @H = weak global i32 0
-
- define i32 @test(i1 %Condition) {
- entry:
- br i1 %Condition, label %cond_true, label %cond_false
-
- cond_true:
- %X.0 = load i32* @G
- br label %cond_next
-
- cond_false:
- %X.1 = load i32* @H
- br label %cond_next
-
- cond_next:
- %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
- ret i32 %X.01
- }
-
-The mem2reg pass implements the standard "iterated dominance frontier"
-algorithm for constructing SSA form and has a number of optimizations
-that speed up (very common) degenerate cases. The mem2reg optimization
-pass is the answer to dealing with mutable variables, and we highly
-recommend that you depend on it. Note that mem2reg only works on
-variables in certain circumstances:
-
-#. mem2reg is alloca-driven: it looks for allocas and if it can handle
- them, it promotes them. It does not apply to global variables or heap
- allocations.
-#. mem2reg only looks for alloca instructions in the entry block of the
- function. Being in the entry block guarantees that the alloca is only
- executed once, which makes analysis simpler.
-#. mem2reg only promotes allocas whose uses are direct loads and stores.
- If the address of the stack object is passed to a function, or if any
- funny pointer arithmetic is involved, the alloca will not be
- promoted.
-#. mem2reg only works on allocas of `first
- class <../LangRef.html#first-class-types>`_ values (such as pointers,
- scalars and vectors), and only if the array size of the allocation is
- 1 (or missing in the .ll file). mem2reg is not capable of promoting
- structs or arrays to registers. Note that the "sroa" pass is
- more powerful and can promote structs, "unions", and arrays in many
- cases.
-
-All of these properties are easy to satisfy for most imperative
-languages, and we'll illustrate it below with Kaleidoscope. The final
-question you may be asking is: should I bother with this nonsense for my
-front-end? Wouldn't it be better if I just did SSA construction
-directly, avoiding use of the mem2reg optimization pass? In short, we
-strongly recommend that you use this technique for building SSA form,
-unless there is an extremely good reason not to. Using this technique
-is:
-
-- Proven and well tested: clang uses this technique
- for local mutable variables. As such, the most common clients of LLVM
- are using this to handle a bulk of their variables. You can be sure
- that bugs are found fast and fixed early.
-- Extremely Fast: mem2reg has a number of special cases that make it
- fast in common cases as well as fully general. For example, it has
- fast-paths for variables that are only used in a single block,
- variables that only have one assignment point, good heuristics to
- avoid insertion of unneeded phi nodes, etc.
-- Needed for debug info generation: `Debug information in
- LLVM <../SourceLevelDebugging.html>`_ relies on having the address of
- the variable exposed so that debug info can be attached to it. This
- technique dovetails very naturally with this style of debug info.
-
-If nothing else, this makes it much easier to get your front-end up and
-running, and is very simple to implement. Let's extend Kaleidoscope with
-mutable variables now!
-
-Mutable Variables in Kaleidoscope
-=================================
-
-Now that we know the sort of problem we want to tackle, let's see what
-this looks like in the context of our little Kaleidoscope language.
-We're going to add two features:
-
-#. The ability to mutate variables with the '=' operator.
-#. The ability to define new variables.
-
-While the first item is really what this is about, we only have
-variables for incoming arguments as well as for induction variables, and
-redefining those only goes so far :). Also, the ability to define new
-variables is a useful thing regardless of whether you will be mutating
-them. Here's a motivating example that shows how we could use these:
-
-::
-
- # Define ':' for sequencing: as a low-precedence operator that ignores operands
- # and just returns the RHS.
- def binary : 1 (x y) y;
-
- # Recursive fib, we could do this before.
- def fib(x)
- if (x < 3) then
- 1
- else
- fib(x-1)+fib(x-2);
-
- # Iterative fib.
- def fibi(x)
- var a = 1, b = 1, c in
- (for i = 3, i < x in
- c = a + b :
- a = b :
- b = c) :
- b;
-
- # Call it.
- fibi(10);
-
-In order to mutate variables, we have to change our existing variables
-to use the "alloca trick". Once we have that, we'll add our new
-operator, then extend Kaleidoscope to support new variable definitions.
-
-Adjusting Existing Variables for Mutation
-=========================================
-
-The symbol table in Kaleidoscope is managed at code generation time by
-the '``NamedValues``' map. This map currently keeps track of the LLVM
-"Value\*" that holds the double value for the named variable. In order
-to support mutation, we need to change this slightly, so that
-``NamedValues`` holds the *memory location* of the variable in question.
-Note that this change is a refactoring: it changes the structure of the
-code, but does not (by itself) change the behavior of the compiler. All
-of these changes are isolated in the Kaleidoscope code generator.
-
-At this point in Kaleidoscope's development, it only supports variables
-for two things: incoming arguments to functions and the induction
-variable of 'for' loops. For consistency, we'll allow mutation of these
-variables in addition to other user-defined variables. This means that
-these will both need memory locations.
-
-To start our transformation of Kaleidoscope, we'll change the
-NamedValues map so that it maps to AllocaInst\* instead of Value\*. Once
-we do this, the C++ compiler will tell us what parts of the code we need
-to update:
-
-.. code-block:: c++
-
- static std::map<std::string, AllocaInst*> NamedValues;
-
-Also, since we will need to create these alloca's, we'll use a helper
-function that ensures that the allocas are created in the entry block of
-the function:
-
-.. code-block:: c++
-
- /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
- /// the function. This is used for mutable variables etc.
- static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
- const std::string &VarName) {
- IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
- TheFunction->getEntryBlock().begin());
- return TmpB.CreateAlloca(Type::getDoubleTy(LLVMContext), 0,
- VarName.c_str());
- }
-
-This funny looking code creates an IRBuilder object that is pointing at
-the first instruction (.begin()) of the entry block. It then creates an
-alloca with the expected name and returns it. Because all values in
-Kaleidoscope are doubles, there is no need to pass in a type to use.
-
-With this in place, the first functionality change we want to make is to
-variable references. In our new scheme, variables live on the stack, so
-code generating a reference to them actually needs to produce a load
-from the stack slot:
-
-.. code-block:: c++
-
- Value *VariableExprAST::codegen() {
- // Look this variable up in the function.
- Value *V = NamedValues[Name];
- if (!V)
- return LogErrorV("Unknown variable name");
-
- // Load the value.
- return Builder.CreateLoad(V, Name.c_str());
- }
-
-As you can see, this is pretty straightforward. Now we need to update
-the things that define the variables to set up the alloca. We'll start
-with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for
-the unabridged code):
-
-.. code-block:: c++
-
- Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
- // Create an alloca for the variable in the entry block.
- AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-
- // Emit the start code first, without 'variable' in scope.
- Value *StartVal = Start->codegen();
- if (!StartVal)
- return nullptr;
-
- // Store the value into the alloca.
- Builder.CreateStore(StartVal, Alloca);
- ...
-
- // Compute the end condition.
- Value *EndCond = End->codegen();
- if (!EndCond)
- return nullptr;
-
- // Reload, increment, and restore the alloca. This handles the case where
- // the body of the loop mutates the variable.
- Value *CurVar = Builder.CreateLoad(Alloca);
- Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
- Builder.CreateStore(NextVar, Alloca);
- ...
-
-This code is virtually identical to the code `before we allowed mutable
-variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we
-no longer have to construct a PHI node, and we use load/store to access
-the variable as needed.
-
-To support mutable argument variables, we need to also make allocas for
-them. The code for this is also pretty simple:
-
-.. code-block:: c++
-
- /// CreateArgumentAllocas - Create an alloca for each argument and register the
- /// argument in the symbol table so that references to it will succeed.
- void PrototypeAST::CreateArgumentAllocas(Function *F) {
- Function::arg_iterator AI = F->arg_begin();
- for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {
- // Create an alloca for this variable.
- AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);
-
- // Store the initial value into the alloca.
- Builder.CreateStore(AI, Alloca);
-
- // Add arguments to variable symbol table.
- NamedValues[Args[Idx]] = Alloca;
- }
- }
-
-For each argument, we make an alloca, store the input value to the
-function into the alloca, and register the alloca as the memory location
-for the argument. This method gets invoked by ``FunctionAST::codegen()``
-right after it sets up the entry block for the function.
-
-The final missing piece is adding the mem2reg pass, which allows us to
-get good codegen once again:
-
-.. code-block:: c++
-
- // Set up the optimizer pipeline. Start with registering info about how the
- // target lays out data structures.
- OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout()));
- // Promote allocas to registers.
- OurFPM.add(createPromoteMemoryToRegisterPass());
- // Do simple "peephole" optimizations and bit-twiddling optzns.
- OurFPM.add(createInstructionCombiningPass());
- // Reassociate expressions.
- OurFPM.add(createReassociatePass());
-
-It is interesting to see what the code looks like before and after the
-mem2reg optimization runs. For example, this is the before/after code
-for our recursive fib function. Before the optimization:
-
-.. code-block:: llvm
-
- define double @fib(double %x) {
- entry:
- %x1 = alloca double
- store double %x, double* %x1
- %x2 = load double* %x1
- %cmptmp = fcmp ult double %x2, 3.000000e+00
- %booltmp = uitofp i1 %cmptmp to double
- %ifcond = fcmp one double %booltmp, 0.000000e+00
- br i1 %ifcond, label %then, label %else
-
- then: ; preds = %entry
- br label %ifcont
-
- else: ; preds = %entry
- %x3 = load double* %x1
- %subtmp = fsub double %x3, 1.000000e+00
- %calltmp = call double @fib(double %subtmp)
- %x4 = load double* %x1
- %subtmp5 = fsub double %x4, 2.000000e+00
- %calltmp6 = call double @fib(double %subtmp5)
- %addtmp = fadd double %calltmp, %calltmp6
- br label %ifcont
-
- ifcont: ; preds = %else, %then
- %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
- ret double %iftmp
- }
-
-Here there is only one variable (x, the input argument) but you can
-still see the extremely simple-minded code generation strategy we are
-using. In the entry block, an alloca is created, and the initial input
-value is stored into it. Each reference to the variable does a reload
-from the stack. Also, note that we didn't modify the if/then/else
-expression, so it still inserts a PHI node. While we could make an
-alloca for it, it is actually easier to create a PHI node for it, so we
-still just make the PHI.
-
-Here is the code after the mem2reg pass runs:
-
-.. code-block:: llvm
-
- define double @fib(double %x) {
- entry:
- %cmptmp = fcmp ult double %x, 3.000000e+00
- %booltmp = uitofp i1 %cmptmp to double
- %ifcond = fcmp one double %booltmp, 0.000000e+00
- br i1 %ifcond, label %then, label %else
-
- then:
- br label %ifcont
-
- else:
- %subtmp = fsub double %x, 1.000000e+00
- %calltmp = call double @fib(double %subtmp)
- %subtmp5 = fsub double %x, 2.000000e+00
- %calltmp6 = call double @fib(double %subtmp5)
- %addtmp = fadd double %calltmp, %calltmp6
- br label %ifcont
-
- ifcont: ; preds = %else, %then
- %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
- ret double %iftmp
- }
-
-This is a trivial case for mem2reg, since there are no redefinitions of
-the variable. The point of showing this is to calm your tension about
-inserting such blatent inefficiencies :).
-
-After the rest of the optimizers run, we get:
-
-.. code-block:: llvm
-
- define double @fib(double %x) {
- entry:
- %cmptmp = fcmp ult double %x, 3.000000e+00
- %booltmp = uitofp i1 %cmptmp to double
- %ifcond = fcmp ueq double %booltmp, 0.000000e+00
- br i1 %ifcond, label %else, label %ifcont
-
- else:
- %subtmp = fsub double %x, 1.000000e+00
- %calltmp = call double @fib(double %subtmp)
- %subtmp5 = fsub double %x, 2.000000e+00
- %calltmp6 = call double @fib(double %subtmp5)
- %addtmp = fadd double %calltmp, %calltmp6
- ret double %addtmp
-
- ifcont:
- ret double 1.000000e+00
- }
-
-Here we see that the simplifycfg pass decided to clone the return
-instruction into the end of the 'else' block. This allowed it to
-eliminate some branches and the PHI node.
-
-Now that all symbol table references are updated to use stack variables,
-we'll add the assignment operator.
-
-New Assignment Operator
-=======================
-
-With our current framework, adding a new assignment operator is really
-simple. We will parse it just like any other binary operator, but handle
-it internally (instead of allowing the user to define it). The first
-step is to set a precedence:
-
-.. code-block:: c++
-
- int main() {
- // Install standard binary operators.
- // 1 is lowest precedence.
- BinopPrecedence['='] = 2;
- BinopPrecedence['<'] = 10;
- BinopPrecedence['+'] = 20;
- BinopPrecedence['-'] = 20;
-
-Now that the parser knows the precedence of the binary operator, it
-takes care of all the parsing and AST generation. We just need to
-implement codegen for the assignment operator. This looks like:
-
-.. code-block:: c++
-
- Value *BinaryExprAST::codegen() {
- // Special case '=' because we don't want to emit the LHS as an expression.
- if (Op == '=') {
- // Assignment requires the LHS to be an identifier.
- VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());
- if (!LHSE)
- return LogErrorV("destination of '=' must be a variable");
-
-Unlike the rest of the binary operators, our assignment operator doesn't
-follow the "emit LHS, emit RHS, do computation" model. As such, it is
-handled as a special case before the other binary operators are handled.
-The other strange thing is that it requires the LHS to be a variable. It
-is invalid to have "(x+1) = expr" - only things like "x = expr" are
-allowed.
-
-.. code-block:: c++
-
- // Codegen the RHS.
- Value *Val = RHS->codegen();
- if (!Val)
- return nullptr;
-
- // Look up the name.
- Value *Variable = NamedValues[LHSE->getName()];
- if (!Variable)
- return LogErrorV("Unknown variable name");
-
- Builder.CreateStore(Val, Variable);
- return Val;
- }
- ...
-
-Once we have the variable, codegen'ing the assignment is
-straightforward: we emit the RHS of the assignment, create a store, and
-return the computed value. Returning a value allows for chained
-assignments like "X = (Y = Z)".
-
-Now that we have an assignment operator, we can mutate loop variables
-and arguments. For example, we can now run code like this:
-
-::
-
- # Function to print a double.
- extern printd(x);
-
- # Define ':' for sequencing: as a low-precedence operator that ignores operands
- # and just returns the RHS.
- def binary : 1 (x y) y;
-
- def test(x)
- printd(x) :
- x = 4 :
- printd(x);
-
- test(123);
-
-When run, this example prints "123" and then "4", showing that we did
-actually mutate the value! Okay, we have now officially implemented our
-goal: getting this to work requires SSA construction in the general
-case. However, to be really useful, we want the ability to define our
-own local variables, let's add this next!
-
-User-defined Local Variables
-============================
-
-Adding var/in is just like any other extension we made to
-Kaleidoscope: we extend the lexer, the parser, the AST and the code
-generator. The first step for adding our new 'var/in' construct is to
-extend the lexer. As before, this is pretty trivial, the code looks like
-this:
-
-.. code-block:: c++
-
- enum Token {
- ...
- // var definition
- tok_var = -13
- ...
- }
- ...
- static int gettok() {
- ...
- if (IdentifierStr == "in")
- return tok_in;
- if (IdentifierStr == "binary")
- return tok_binary;
- if (IdentifierStr == "unary")
- return tok_unary;
- if (IdentifierStr == "var")
- return tok_var;
- return tok_identifier;
- ...
-
-The next step is to define the AST node that we will construct. For
-var/in, it looks like this:
-
-.. code-block:: c++
-
- /// VarExprAST - Expression class for var/in
- class VarExprAST : public ExprAST {
- std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
- std::unique_ptr<ExprAST> Body;
-
- public:
- VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
- std::unique_ptr<ExprAST> body)
- : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
-
- virtual Value *codegen();
- };
-
-var/in allows a list of names to be defined all at once, and each name
-can optionally have an initializer value. As such, we capture this
-information in the VarNames vector. Also, var/in has a body, this body
-is allowed to access the variables defined by the var/in.
-
-With this in place, we can define the parser pieces. The first thing we
-do is add it as a primary expression:
-
-.. code-block:: c++
-
- /// primary
- /// ::= identifierexpr
- /// ::= numberexpr
- /// ::= parenexpr
- /// ::= ifexpr
- /// ::= forexpr
- /// ::= varexpr
- static std::unique_ptr<ExprAST> ParsePrimary() {
- switch (CurTok) {
- default:
- return LogError("unknown token when expecting an expression");
- case tok_identifier:
- return ParseIdentifierExpr();
- case tok_number:
- return ParseNumberExpr();
- case '(':
- return ParseParenExpr();
- case tok_if:
- return ParseIfExpr();
- case tok_for:
- return ParseForExpr();
- case tok_var:
- return ParseVarExpr();
- }
- }
-
-Next we define ParseVarExpr:
-
-.. code-block:: c++
-
- /// varexpr ::= 'var' identifier ('=' expression)?
- // (',' identifier ('=' expression)?)* 'in' expression
- static std::unique_ptr<ExprAST> ParseVarExpr() {
- getNextToken(); // eat the var.
-
- std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
-
- // At least one variable name is required.
- if (CurTok != tok_identifier)
- return LogError("expected identifier after var");
-
-The first part of this code parses the list of identifier/expr pairs
-into the local ``VarNames`` vector.
-
-.. code-block:: c++
-
- while (1) {
- std::string Name = IdentifierStr;
- getNextToken(); // eat identifier.
-
- // Read the optional initializer.
- std::unique_ptr<ExprAST> Init;
- if (CurTok == '=') {
- getNextToken(); // eat the '='.
-
- Init = ParseExpression();
- if (!Init) return nullptr;
- }
-
- VarNames.push_back(std::make_pair(Name, std::move(Init)));
-
- // End of var list, exit loop.
- if (CurTok != ',') break;
- getNextToken(); // eat the ','.
-
- if (CurTok != tok_identifier)
- return LogError("expected identifier list after var");
- }
-
-Once all the variables are parsed, we then parse the body and create the
-AST node:
-
-.. code-block:: c++
-
- // At this point, we have to have 'in'.
- if (CurTok != tok_in)
- return LogError("expected 'in' keyword after 'var'");
- getNextToken(); // eat 'in'.
-
- auto Body = ParseExpression();
- if (!Body)
- return nullptr;
-
- return llvm::make_unique<VarExprAST>(std::move(VarNames),
- std::move(Body));
- }
-
-Now that we can parse and represent the code, we need to support
-emission of LLVM IR for it. This code starts out with:
-
-.. code-block:: c++
-
- Value *VarExprAST::codegen() {
- std::vector<AllocaInst *> OldBindings;
-
- Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
- // Register all variables and emit their initializer.
- for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
- const std::string &VarName = VarNames[i].first;
- ExprAST *Init = VarNames[i].second.get();
-
-Basically it loops over all the variables, installing them one at a
-time. For each variable we put into the symbol table, we remember the
-previous value that we replace in OldBindings.
-
-.. code-block:: c++
-
- // Emit the initializer before adding the variable to scope, this prevents
- // the initializer from referencing the variable itself, and permits stuff
- // like this:
- // var a = 1 in
- // var a = a in ... # refers to outer 'a'.
- Value *InitVal;
- if (Init) {
- InitVal = Init->codegen();
- if (!InitVal)
- return nullptr;
- } else { // If not specified, use 0.0.
- InitVal = ConstantFP::get(LLVMContext, APFloat(0.0));
- }
-
- AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
- Builder.CreateStore(InitVal, Alloca);
-
- // Remember the old variable binding so that we can restore the binding when
- // we unrecurse.
- OldBindings.push_back(NamedValues[VarName]);
-
- // Remember this binding.
- NamedValues[VarName] = Alloca;
- }
-
-There are more comments here than code. The basic idea is that we emit
-the initializer, create the alloca, then update the symbol table to
-point to it. Once all the variables are installed in the symbol table,
-we evaluate the body of the var/in expression:
-
-.. code-block:: c++
-
- // Codegen the body, now that all vars are in scope.
- Value *BodyVal = Body->codegen();
- if (!BodyVal)
- return nullptr;
-
-Finally, before returning, we restore the previous variable bindings:
-
-.. code-block:: c++
-
- // Pop all our variables from scope.
- for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
- NamedValues[VarNames[i].first] = OldBindings[i];
-
- // Return the body computation.
- return BodyVal;
- }
-
-The end result of all of this is that we get properly scoped variable
-definitions, and we even (trivially) allow mutation of them :).
-
-With this, we completed what we set out to do. Our nice iterative fib
-example from the intro compiles and runs just fine. The mem2reg pass
-optimizes all of our stack variables into SSA registers, inserting PHI
-nodes where needed, and our front-end remains simple: no "iterated
-dominance frontier" computation anywhere in sight.
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-mutable variables and var/in support. To build this example, use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
- # Run
- ./toy
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp
- :language: c++
-
-`Next: Adding Debug Information <LangImpl8.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl8.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl8.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl8.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl8.rst (removed)
@@ -1,462 +0,0 @@
-======================================
-Kaleidoscope: Adding Debug Information
-======================================
-
-.. contents::
- :local:
-
-Chapter 8 Introduction
-======================
-
-Welcome to Chapter 8 of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. In chapters 1 through 7, we've built a
-decent little programming language with functions and variables.
-What happens if something goes wrong though, how do you debug your
-program?
-
-Source level debugging uses formatted data that helps a debugger
-translate from binary and the state of the machine back to the
-source that the programmer wrote. In LLVM we generally use a format
-called `DWARF <http://dwarfstd.org>`_. DWARF is a compact encoding
-that represents types, source locations, and variable locations.
-
-The short summary of this chapter is that we'll go through the
-various things you have to add to a programming language to
-support debug info, and how you translate that into DWARF.
-
-Caveat: For now we can't debug via the JIT, so we'll need to compile
-our program down to something small and standalone. As part of this
-we'll make a few modifications to the running of the language and
-how programs are compiled. This means that we'll have a source file
-with a simple program written in Kaleidoscope rather than the
-interactive JIT. It does involve a limitation that we can only
-have one "top level" command at a time to reduce the number of
-changes necessary.
-
-Here's the sample program we'll be compiling:
-
-.. code-block:: python
-
- def fib(x)
- if x < 3 then
- 1
- else
- fib(x-1)+fib(x-2);
-
- fib(10)
-
-
-Why is this a hard problem?
-===========================
-
-Debug information is a hard problem for a few different reasons - mostly
-centered around optimized code. First, optimization makes keeping source
-locations more difficult. In LLVM IR we keep the original source location
-for each IR level instruction on the instruction. Optimization passes
-should keep the source locations for newly created instructions, but merged
-instructions only get to keep a single location - this can cause jumping
-around when stepping through optimized programs. Secondly, optimization
-can move variables in ways that are either optimized out, shared in memory
-with other variables, or difficult to track. For the purposes of this
-tutorial we're going to avoid optimization (as you'll see with one of the
-next sets of patches).
-
-Ahead-of-Time Compilation Mode
-==============================
-
-To highlight only the aspects of adding debug information to a source
-language without needing to worry about the complexities of JIT debugging
-we're going to make a few changes to Kaleidoscope to support compiling
-the IR emitted by the front end into a simple standalone program that
-you can execute, debug, and see results.
-
-First we make our anonymous function that contains our top level
-statement be our "main":
-
-.. code-block:: udiff
-
- - auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
- + auto Proto = llvm::make_unique<PrototypeAST>("main", std::vector<std::string>());
-
-just with the simple change of giving it a name.
-
-Then we're going to remove the command line code wherever it exists:
-
-.. code-block:: udiff
-
- @@ -1129,7 +1129,6 @@ static void HandleTopLevelExpression() {
- /// top ::= definition | external | expression | ';'
- static void MainLoop() {
- while (1) {
- - fprintf(stderr, "ready> ");
- switch (CurTok) {
- case tok_eof:
- return;
- @@ -1184,7 +1183,6 @@ int main() {
- BinopPrecedence['*'] = 40; // highest.
-
- // Prime the first token.
- - fprintf(stderr, "ready> ");
- getNextToken();
-
-Lastly we're going to disable all of the optimization passes and the JIT so
-that the only thing that happens after we're done parsing and generating
-code is that the llvm IR goes to standard error:
-
-.. code-block:: udiff
-
- @@ -1108,17 +1108,8 @@ static void HandleExtern() {
- static void HandleTopLevelExpression() {
- // Evaluate a top-level expression into an anonymous function.
- if (auto FnAST = ParseTopLevelExpr()) {
- - if (auto *FnIR = FnAST->codegen()) {
- - // We're just doing this to make sure it executes.
- - TheExecutionEngine->finalizeObject();
- - // JIT the function, returning a function pointer.
- - void *FPtr = TheExecutionEngine->getPointerToFunction(FnIR);
- -
- - // Cast it to the right type (takes no arguments, returns a double) so we
- - // can call it as a native function.
- - double (*FP)() = (double (*)())(intptr_t)FPtr;
- - // Ignore the return value for this.
- - (void)FP;
- + if (!F->codegen()) {
- + fprintf(stderr, "Error generating code for top level expr");
- }
- } else {
- // Skip token for error recovery.
- @@ -1439,11 +1459,11 @@ int main() {
- // target lays out data structures.
- TheModule->setDataLayout(TheExecutionEngine->getDataLayout());
- OurFPM.add(new DataLayoutPass());
- +#if 0
- OurFPM.add(createBasicAliasAnalysisPass());
- // Promote allocas to registers.
- OurFPM.add(createPromoteMemoryToRegisterPass());
- @@ -1218,7 +1210,7 @@ int main() {
- OurFPM.add(createGVNPass());
- // Simplify the control flow graph (deleting unreachable blocks, etc).
- OurFPM.add(createCFGSimplificationPass());
- -
- + #endif
- OurFPM.doInitialization();
-
- // Set the global so the code gen can use this.
-
-This relatively small set of changes get us to the point that we can compile
-our piece of Kaleidoscope language down to an executable program via this
-command line:
-
-.. code-block:: bash
-
- Kaleidoscope-Ch8 < fib.ks | & clang -x ir -
-
-which gives an a.out/a.exe in the current working directory.
-
-Compile Unit
-============
-
-The top level container for a section of code in DWARF is a compile unit.
-This contains the type and function data for an individual translation unit
-(read: one file of source code). So the first thing we need to do is
-construct one for our fib.ks file.
-
-DWARF Emission Setup
-====================
-
-Similar to the ``IRBuilder`` class we have a
-`DIBuilder <http://llvm.org/doxygen/classllvm_1_1DIBuilder.html>`_ class
-that helps in constructing debug metadata for an llvm IR file. It
-corresponds 1:1 similarly to ``IRBuilder`` and llvm IR, but with nicer names.
-Using it does require that you be more familiar with DWARF terminology than
-you needed to be with ``IRBuilder`` and ``Instruction`` names, but if you
-read through the general documentation on the
-`Metadata Format <http://llvm.org/docs/SourceLevelDebugging.html>`_ it
-should be a little more clear. We'll be using this class to construct all
-of our IR level descriptions. Construction for it takes a module so we
-need to construct it shortly after we construct our module. We've left it
-as a global static variable to make it a bit easier to use.
-
-Next we're going to create a small container to cache some of our frequent
-data. The first will be our compile unit, but we'll also write a bit of
-code for our one type since we won't have to worry about multiple typed
-expressions:
-
-.. code-block:: c++
-
- static DIBuilder *DBuilder;
-
- struct DebugInfo {
- DICompileUnit *TheCU;
- DIType *DblTy;
-
- DIType *getDoubleTy();
- } KSDbgInfo;
-
- DIType *DebugInfo::getDoubleTy() {
- if (DblTy.isValid())
- return DblTy;
-
- DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);
- return DblTy;
- }
-
-And then later on in ``main`` when we're constructing our module:
-
-.. code-block:: c++
-
- DBuilder = new DIBuilder(*TheModule);
-
- KSDbgInfo.TheCU = DBuilder->createCompileUnit(
- dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0);
-
-There are a couple of things to note here. First, while we're producing a
-compile unit for a language called Kaleidoscope we used the language
-constant for C. This is because a debugger wouldn't necessarily understand
-the calling conventions or default ABI for a language it doesn't recognize
-and we follow the C ABI in our llvm code generation so it's the closest
-thing to accurate. This ensures we can actually call functions from the
-debugger and have them execute. Secondly, you'll see the "fib.ks" in the
-call to ``createCompileUnit``. This is a default hard coded value since
-we're using shell redirection to put our source into the Kaleidoscope
-compiler. In a usual front end you'd have an input file name and it would
-go there.
-
-One last thing as part of emitting debug information via DIBuilder is that
-we need to "finalize" the debug information. The reasons are part of the
-underlying API for DIBuilder, but make sure you do this near the end of
-main:
-
-.. code-block:: c++
-
- DBuilder->finalize();
-
-before you dump out the module.
-
-Functions
-=========
-
-Now that we have our ``Compile Unit`` and our source locations, we can add
-function definitions to the debug info. So in ``PrototypeAST::codegen()`` we
-add a few lines of code to describe a context for our subprogram, in this
-case the "File", and the actual definition of the function itself.
-
-So the context:
-
-.. code-block:: c++
-
- DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),
- KSDbgInfo.TheCU.getDirectory());
-
-giving us an DIFile and asking the ``Compile Unit`` we created above for the
-directory and filename where we are currently. Then, for now, we use some
-source locations of 0 (since our AST doesn't currently have source location
-information) and construct our function definition:
-
-.. code-block:: c++
-
- DIScope *FContext = Unit;
- unsigned LineNo = 0;
- unsigned ScopeLine = 0;
- DISubprogram *SP = DBuilder->createFunction(
- FContext, Name, StringRef(), Unit, LineNo,
- CreateFunctionType(Args.size(), Unit), false /* internal linkage */,
- true /* definition */, ScopeLine, DINode::FlagPrototyped, false);
- F->setSubprogram(SP);
-
-and we now have an DISubprogram that contains a reference to all of our
-metadata for the function.
-
-Source Locations
-================
-
-The most important thing for debug information is accurate source location -
-this makes it possible to map your source code back. We have a problem though,
-Kaleidoscope really doesn't have any source location information in the lexer
-or parser so we'll need to add it.
-
-.. code-block:: c++
-
- struct SourceLocation {
- int Line;
- int Col;
- };
- static SourceLocation CurLoc;
- static SourceLocation LexLoc = {1, 0};
-
- static int advance() {
- int LastChar = getchar();
-
- if (LastChar == '\n' || LastChar == '\r') {
- LexLoc.Line++;
- LexLoc.Col = 0;
- } else
- LexLoc.Col++;
- return LastChar;
- }
-
-In this set of code we've added some functionality on how to keep track of the
-line and column of the "source file". As we lex every token we set our current
-current "lexical location" to the assorted line and column for the beginning
-of the token. We do this by overriding all of the previous calls to
-``getchar()`` with our new ``advance()`` that keeps track of the information
-and then we have added to all of our AST classes a source location:
-
-.. code-block:: c++
-
- class ExprAST {
- SourceLocation Loc;
-
- public:
- ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}
- virtual ~ExprAST() {}
- virtual Value* codegen() = 0;
- int getLine() const { return Loc.Line; }
- int getCol() const { return Loc.Col; }
- virtual raw_ostream &dump(raw_ostream &out, int ind) {
- return out << ':' << getLine() << ':' << getCol() << '\n';
- }
-
-that we pass down through when we create a new expression:
-
-.. code-block:: c++
-
- LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),
- std::move(RHS));
-
-giving us locations for each of our expressions and variables.
-
-From this we can make sure to tell ``DIBuilder`` when we're at a new source
-location so it can use that when we generate the rest of our code and make
-sure that each instruction has source location information. We do this
-by constructing another small function:
-
-.. code-block:: c++
-
- void DebugInfo::emitLocation(ExprAST *AST) {
- DIScope *Scope;
- if (LexicalBlocks.empty())
- Scope = TheCU;
- else
- Scope = LexicalBlocks.back();
- Builder.SetCurrentDebugLocation(
- DebugLoc::get(AST->getLine(), AST->getCol(), Scope));
- }
-
-that both tells the main ``IRBuilder`` where we are, but also what scope
-we're in. Since we've just created a function above we can either be in
-the main file scope (like when we created our function), or now we can be
-in the function scope we just created. To represent this we create a stack
-of scopes:
-
-.. code-block:: c++
-
- std::vector<DIScope *> LexicalBlocks;
- std::map<const PrototypeAST *, DIScope *> FnScopeMap;
-
-and keep a map of each function to the scope that it represents (an
-DISubprogram is also an DIScope).
-
-Then we make sure to:
-
-.. code-block:: c++
-
- KSDbgInfo.emitLocation(this);
-
-emit the location every time we start to generate code for a new AST, and
-also:
-
-.. code-block:: c++
-
- KSDbgInfo.FnScopeMap[this] = SP;
-
-store the scope (function) when we create it and use it:
-
- KSDbgInfo.LexicalBlocks.push_back(&KSDbgInfo.FnScopeMap[Proto]);
-
-when we start generating the code for each function.
-
-also, don't forget to pop the scope back off of your scope stack at the
-end of the code generation for the function:
-
-.. code-block:: c++
-
- // Pop off the lexical block for the function since we added it
- // unconditionally.
- KSDbgInfo.LexicalBlocks.pop_back();
-
-Variables
-=========
-
-Now that we have functions, we need to be able to print out the variables
-we have in scope. Let's get our function arguments set up so we can get
-decent backtraces and see how our functions are being called. It isn't
-a lot of code, and we generally handle it when we're creating the
-argument allocas in ``PrototypeAST::CreateArgumentAllocas``.
-
-.. code-block:: c++
-
- DIScope *Scope = KSDbgInfo.LexicalBlocks.back();
- DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU.getFilename(),
- KSDbgInfo.TheCU.getDirectory());
- DILocalVariable D = DBuilder->createParameterVariable(
- Scope, Args[Idx], Idx + 1, Unit, Line, KSDbgInfo.getDoubleTy(), true);
-
- DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),
- DebugLoc::get(Line, 0, Scope),
- Builder.GetInsertBlock());
-
-Here we're doing a few things. First, we're grabbing our current scope
-for the variable so we can say what range of code our variable is valid
-through. Second, we're creating the variable, giving it the scope,
-the name, source location, type, and since it's an argument, the argument
-index. Third, we create an ``lvm.dbg.declare`` call to indicate at the IR
-level that we've got a variable in an alloca (and it gives a starting
-location for the variable), and setting a source location for the
-beginning of the scope on the declare.
-
-One interesting thing to note at this point is that various debuggers have
-assumptions based on how code and debug information was generated for them
-in the past. In this case we need to do a little bit of a hack to avoid
-generating line information for the function prologue so that the debugger
-knows to skip over those instructions when setting a breakpoint. So in
-``FunctionAST::CodeGen`` we add a couple of lines:
-
-.. code-block:: c++
-
- // Unset the location for the prologue emission (leading instructions with no
- // location in a function are considered part of the prologue and the debugger
- // will run past them when breaking on a function)
- KSDbgInfo.emitLocation(nullptr);
-
-and then emit a new location when we actually start generating code for the
-body of the function:
-
-.. code-block:: c++
-
- KSDbgInfo.emitLocation(Body);
-
-With this we have enough debug information to set breakpoints in functions,
-print out argument variables, and call functions. Not too bad for just a
-few simple lines of code!
-
-Full Code Listing
-=================
-
-Here is the complete code listing for our running example, enhanced with
-debug information. To build this example, use:
-
-.. code-block:: bash
-
- # Compile
- clang++ -g toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core mcjit native` -O3 -o toy
- # Run
- ./toy
-
-Here is the code:
-
-.. literalinclude:: ../../examples/Kaleidoscope/Chapter8/toy.cpp
- :language: c++
-
-`Next: Conclusion and other useful LLVM tidbits <LangImpl9.html>`_
-
Removed: llvm/trunk/docs/tutorial/LangImpl9.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/LangImpl9.rst?rev=274440&view=auto
==============================================================================
--- llvm/trunk/docs/tutorial/LangImpl9.rst (original)
+++ llvm/trunk/docs/tutorial/LangImpl9.rst (removed)
@@ -1,259 +0,0 @@
-======================================================
-Kaleidoscope: Conclusion and other useful LLVM tidbits
-======================================================
-
-.. contents::
- :local:
-
-Tutorial Conclusion
-===================
-
-Welcome to the final chapter of the "`Implementing a language with
-LLVM <index.html>`_" tutorial. In the course of this tutorial, we have
-grown our little Kaleidoscope language from being a useless toy, to
-being a semi-interesting (but probably still useless) toy. :)
-
-It is interesting to see how far we've come, and how little code it has
-taken. We built the entire lexer, parser, AST, code generator, an
-interactive run-loop (with a JIT!), and emitted debug information in
-standalone executables - all in under 1000 lines of (non-comment/non-blank)
-code.
-
-Our little language supports a couple of interesting features: it
-supports user defined binary and unary operators, it uses JIT
-compilation for immediate evaluation, and it supports a few control flow
-constructs with SSA construction.
-
-Part of the idea of this tutorial was to show you how easy and fun it
-can be to define, build, and play with languages. Building a compiler
-need not be a scary or mystical process! Now that you've seen some of
-the basics, I strongly encourage you to take the code and hack on it.
-For example, try adding:
-
-- **global variables** - While global variables have questional value
- in modern software engineering, they are often useful when putting
- together quick little hacks like the Kaleidoscope compiler itself.
- Fortunately, our current setup makes it very easy to add global
- variables: just have value lookup check to see if an unresolved
- variable is in the global variable symbol table before rejecting it.
- To create a new global variable, make an instance of the LLVM
- ``GlobalVariable`` class.
-- **typed variables** - Kaleidoscope currently only supports variables
- of type double. This gives the language a very nice elegance, because
- only supporting one type means that you never have to specify types.
- Different languages have different ways of handling this. The easiest
- way is to require the user to specify types for every variable
- definition, and record the type of the variable in the symbol table
- along with its Value\*.
-- **arrays, structs, vectors, etc** - Once you add types, you can start
- extending the type system in all sorts of interesting ways. Simple
- arrays are very easy and are quite useful for many different
- applications. Adding them is mostly an exercise in learning how the
- LLVM `getelementptr <../LangRef.html#getelementptr-instruction>`_ instruction
- works: it is so nifty/unconventional, it `has its own
- FAQ <../GetElementPtr.html>`_!
-- **standard runtime** - Our current language allows the user to access
- arbitrary external functions, and we use it for things like "printd"
- and "putchard". As you extend the language to add higher-level
- constructs, often these constructs make the most sense if they are
- lowered to calls into a language-supplied runtime. For example, if
- you add hash tables to the language, it would probably make sense to
- add the routines to a runtime, instead of inlining them all the way.
-- **memory management** - Currently we can only access the stack in
- Kaleidoscope. It would also be useful to be able to allocate heap
- memory, either with calls to the standard libc malloc/free interface
- or with a garbage collector. If you would like to use garbage
- collection, note that LLVM fully supports `Accurate Garbage
- Collection <../GarbageCollection.html>`_ including algorithms that
- move objects and need to scan/update the stack.
-- **exception handling support** - LLVM supports generation of `zero
- cost exceptions <../ExceptionHandling.html>`_ which interoperate with
- code compiled in other languages. You could also generate code by
- implicitly making every function return an error value and checking
- it. You could also make explicit use of setjmp/longjmp. There are
- many different ways to go here.
-- **object orientation, generics, database access, complex numbers,
- geometric programming, ...** - Really, there is no end of crazy
- features that you can add to the language.
-- **unusual domains** - We've been talking about applying LLVM to a
- domain that many people are interested in: building a compiler for a
- specific language. However, there are many other domains that can use
- compiler technology that are not typically considered. For example,
- LLVM has been used to implement OpenGL graphics acceleration,
- translate C++ code to ActionScript, and many other cute and clever
- things. Maybe you will be the first to JIT compile a regular
- expression interpreter into native code with LLVM?
-
-Have fun - try doing something crazy and unusual. Building a language
-like everyone else always has, is much less fun than trying something a
-little crazy or off the wall and seeing how it turns out. If you get
-stuck or want to talk about it, feel free to email the `llvm-dev mailing
-list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_: it has lots
-of people who are interested in languages and are often willing to help
-out.
-
-Before we end this tutorial, I want to talk about some "tips and tricks"
-for generating LLVM IR. These are some of the more subtle things that
-may not be obvious, but are very useful if you want to take advantage of
-LLVM's capabilities.
-
-Properties of the LLVM IR
-=========================
-
-We have a couple of common questions about code in the LLVM IR form -
-let's just get these out of the way right now, shall we?
-
-Target Independence
--------------------
-
-Kaleidoscope is an example of a "portable language": any program written
-in Kaleidoscope will work the same way on any target that it runs on.
-Many other languages have this property, e.g. lisp, java, haskell,
-javascript, python, etc (note that while these languages are portable,
-not all their libraries are).
-
-One nice aspect of LLVM is that it is often capable of preserving target
-independence in the IR: you can take the LLVM IR for a
-Kaleidoscope-compiled program and run it on any target that LLVM
-supports, even emitting C code and compiling that on targets that LLVM
-doesn't support natively. You can trivially tell that the Kaleidoscope
-compiler generates target-independent code because it never queries for
-any target-specific information when generating code.
-
-The fact that LLVM provides a compact, target-independent,
-representation for code gets a lot of people excited. Unfortunately,
-these people are usually thinking about C or a language from the C
-family when they are asking questions about language portability. I say
-"unfortunately", because there is really no way to make (fully general)
-C code portable, other than shipping the source code around (and of
-course, C source code is not actually portable in general either - ever
-port a really old application from 32- to 64-bits?).
-
-The problem with C (again, in its full generality) is that it is heavily
-laden with target specific assumptions. As one simple example, the
-preprocessor often destructively removes target-independence from the
-code when it processes the input text:
-
-.. code-block:: c
-
- #ifdef __i386__
- int X = 1;
- #else
- int X = 42;
- #endif
-
-While it is possible to engineer more and more complex solutions to
-problems like this, it cannot be solved in full generality in a way that
-is better than shipping the actual source code.
-
-That said, there are interesting subsets of C that can be made portable.
-If you are willing to fix primitive types to a fixed size (say int =
-32-bits, and long = 64-bits), don't care about ABI compatibility with
-existing binaries, and are willing to give up some other minor features,
-you can have portable code. This can make sense for specialized domains
-such as an in-kernel language.
-
-Safety Guarantees
------------------
-
-Many of the languages above are also "safe" languages: it is impossible
-for a program written in Java to corrupt its address space and crash the
-process (assuming the JVM has no bugs). Safety is an interesting
-property that requires a combination of language design, runtime
-support, and often operating system support.
-
-It is certainly possible to implement a safe language in LLVM, but LLVM
-IR does not itself guarantee safety. The LLVM IR allows unsafe pointer
-casts, use after free bugs, buffer over-runs, and a variety of other
-problems. Safety needs to be implemented as a layer on top of LLVM and,
-conveniently, several groups have investigated this. Ask on the `llvm-dev
-mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ if
-you are interested in more details.
-
-Language-Specific Optimizations
--------------------------------
-
-One thing about LLVM that turns off many people is that it does not
-solve all the world's problems in one system (sorry 'world hunger',
-someone else will have to solve you some other day). One specific
-complaint is that people perceive LLVM as being incapable of performing
-high-level language-specific optimization: LLVM "loses too much
-information".
-
-Unfortunately, this is really not the place to give you a full and
-unified version of "Chris Lattner's theory of compiler design". Instead,
-I'll make a few observations:
-
-First, you're right that LLVM does lose information. For example, as of
-this writing, there is no way to distinguish in the LLVM IR whether an
-SSA-value came from a C "int" or a C "long" on an ILP32 machine (other
-than debug info). Both get compiled down to an 'i32' value and the
-information about what it came from is lost. The more general issue
-here, is that the LLVM type system uses "structural equivalence" instead
-of "name equivalence". Another place this surprises people is if you
-have two types in a high-level language that have the same structure
-(e.g. two different structs that have a single int field): these types
-will compile down into a single LLVM type and it will be impossible to
-tell what it came from.
-
-Second, while LLVM does lose information, LLVM is not a fixed target: we
-continue to enhance and improve it in many different ways. In addition
-to adding new features (LLVM did not always support exceptions or debug
-info), we also extend the IR to capture important information for
-optimization (e.g. whether an argument is sign or zero extended,
-information about pointers aliasing, etc). Many of the enhancements are
-user-driven: people want LLVM to include some specific feature, so they
-go ahead and extend it.
-
-Third, it is *possible and easy* to add language-specific optimizations,
-and you have a number of choices in how to do it. As one trivial
-example, it is easy to add language-specific optimization passes that
-"know" things about code compiled for a language. In the case of the C
-family, there is an optimization pass that "knows" about the standard C
-library functions. If you call "exit(0)" in main(), it knows that it is
-safe to optimize that into "return 0;" because C specifies what the
-'exit' function does.
-
-In addition to simple library knowledge, it is possible to embed a
-variety of other language-specific information into the LLVM IR. If you
-have a specific need and run into a wall, please bring the topic up on
-the llvm-dev list. At the very worst, you can always treat LLVM as if it
-were a "dumb code generator" and implement the high-level optimizations
-you desire in your front-end, on the language-specific AST.
-
-Tips and Tricks
-===============
-
-There is a variety of useful tips and tricks that you come to know after
-working on/with LLVM that aren't obvious at first glance. Instead of
-letting everyone rediscover them, this section talks about some of these
-issues.
-
-Implementing portable offsetof/sizeof
--------------------------------------
-
-One interesting thing that comes up, if you are trying to keep the code
-generated by your compiler "target independent", is that you often need
-to know the size of some LLVM type or the offset of some field in an
-llvm structure. For example, you might need to pass the size of a type
-into a function that allocates memory.
-
-Unfortunately, this can vary widely across targets: for example the
-width of a pointer is trivially target-specific. However, there is a
-`clever way to use the getelementptr
-instruction <http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt>`_
-that allows you to compute this in a portable way.
-
-Garbage Collected Stack Frames
-------------------------------
-
-Some languages want to explicitly manage their stack frames, often so
-that they are garbage collected or to allow easy implementation of
-closures. There are often better ways to implement these features than
-explicit stack frames, but `LLVM does support
-them, <http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt>`_
-if you want. It requires your front-end to convert the code into
-`Continuation Passing
-Style <http://en.wikipedia.org/wiki/Continuation-passing_style>`_ and
-the use of tail calls (which LLVM also supports).
-
Modified: llvm/trunk/docs/tutorial/OCamlLangImpl5.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/tutorial/OCamlLangImpl5.rst?rev=274441&r1=274440&r2=274441&view=diff
==============================================================================
--- llvm/trunk/docs/tutorial/OCamlLangImpl5.rst (original)
+++ llvm/trunk/docs/tutorial/OCamlLangImpl5.rst Sat Jul 2 12:01:59 2016
@@ -178,7 +178,7 @@ IR into "t.ll" and run "``llvm-as < t.ll
window will pop up <../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
see this graph:
-.. figure:: LangImpl5-cfg.png
+.. figure:: LangImpl05-cfg.png
:align: center
:alt: Example CFG
Modified: llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt?rev=274441&r1=274440&r2=274441&view=diff
==============================================================================
--- llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt (original)
+++ llvm/trunk/examples/Kaleidoscope/Chapter8/CMakeLists.txt Sat Jul 2 12:01:59 2016
@@ -1,9 +1,5 @@
set(LLVM_LINK_COMPONENTS
- Core
- ExecutionEngine
- Object
- Support
- native
+ all
)
add_kaleidoscope_chapter(Kaleidoscope-Ch8
Modified: llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp?rev=274441&r1=274440&r2=274441&view=diff
==============================================================================
--- llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp (original)
+++ llvm/trunk/examples/Kaleidoscope/Chapter8/toy.cpp Sat Jul 2 12:01:59 2016
@@ -1,28 +1,20 @@
#include "llvm/ADT/APFloat.h"
-#include "llvm/ADT/SmallVector.h"
#include "llvm/ADT/STLExtras.h"
-#include "llvm/ADT/StringRef.h"
-#include "llvm/ADT/Triple.h"
-#include "llvm/IR/BasicBlock.h"
-#include "llvm/IR/Constants.h"
-#include "llvm/IR/DebugInfoMetadata.h"
-#include "llvm/IR/DebugLoc.h"
-#include "llvm/IR/DerivedTypes.h"
-#include "llvm/IR/DIBuilder.h"
-#include "llvm/IR/Function.h"
-#include "llvm/IR/Instructions.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/Analysis/Passes.h"
#include "llvm/IR/IRBuilder.h"
#include "llvm/IR/LLVMContext.h"
+#include "llvm/IR/LegacyPassManager.h"
#include "llvm/IR/Metadata.h"
#include "llvm/IR/Module.h"
#include "llvm/IR/Type.h"
#include "llvm/IR/Verifier.h"
-#include "llvm/Support/Host.h"
-#include "llvm/Support/raw_ostream.h"
+#include "llvm/Support/FileSystem.h"
+#include "llvm/Support/TargetRegistry.h"
#include "llvm/Support/TargetSelect.h"
#include "llvm/Target/TargetMachine.h"
-#include "../include/KaleidoscopeJIT.h"
-#include <cassert>
+#include "llvm/Target/TargetOptions.h"
+#include "llvm/Transforms/Scalar.h"
#include <cctype>
#include <cstdio>
#include <cstdlib>
@@ -33,7 +25,7 @@
#include <vector>
using namespace llvm;
-using namespace llvm::orc;
+using namespace llvm::sys;
//===----------------------------------------------------------------------===//
// Lexer
@@ -67,71 +59,6 @@ enum Token {
tok_var = -13
};
-std::string getTokName(int Tok) {
- switch (Tok) {
- case tok_eof:
- return "eof";
- case tok_def:
- return "def";
- case tok_extern:
- return "extern";
- case tok_identifier:
- return "identifier";
- case tok_number:
- return "number";
- case tok_if:
- return "if";
- case tok_then:
- return "then";
- case tok_else:
- return "else";
- case tok_for:
- return "for";
- case tok_in:
- return "in";
- case tok_binary:
- return "binary";
- case tok_unary:
- return "unary";
- case tok_var:
- return "var";
- }
- return std::string(1, (char)Tok);
-}
-
-namespace {
-class ExprAST;
-} // end anonymous namespace
-
-static LLVMContext TheContext;
-static IRBuilder<> Builder(TheContext);
-struct DebugInfo {
- DICompileUnit *TheCU;
- DIType *DblTy;
- std::vector<DIScope *> LexicalBlocks;
-
- void emitLocation(ExprAST *AST);
- DIType *getDoubleTy();
-} KSDbgInfo;
-
-struct SourceLocation {
- int Line;
- int Col;
-};
-static SourceLocation CurLoc;
-static SourceLocation LexLoc = {1, 0};
-
-static int advance() {
- int LastChar = getchar();
-
- if (LastChar == '\n' || LastChar == '\r') {
- LexLoc.Line++;
- LexLoc.Col = 0;
- } else
- LexLoc.Col++;
- return LastChar;
-}
-
static std::string IdentifierStr; // Filled in if tok_identifier
static double NumVal; // Filled in if tok_number
@@ -141,13 +68,11 @@ static int gettok() {
// Skip any whitespace.
while (isspace(LastChar))
- LastChar = advance();
-
- CurLoc = LexLoc;
+ LastChar = getchar();
if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
IdentifierStr = LastChar;
- while (isalnum((LastChar = advance())))
+ while (isalnum((LastChar = getchar())))
IdentifierStr += LastChar;
if (IdentifierStr == "def")
@@ -177,7 +102,7 @@ static int gettok() {
std::string NumStr;
do {
NumStr += LastChar;
- LastChar = advance();
+ LastChar = getchar();
} while (isdigit(LastChar) || LastChar == '.');
NumVal = strtod(NumStr.c_str(), nullptr);
@@ -187,7 +112,7 @@ static int gettok() {
if (LastChar == '#') {
// Comment until end of line.
do
- LastChar = advance();
+ LastChar = getchar();
while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
if (LastChar != EOF)
@@ -200,7 +125,7 @@ static int gettok() {
// Otherwise, just return the character as its ascii value.
int ThisChar = LastChar;
- LastChar = advance();
+ LastChar = getchar();
return ThisChar;
}
@@ -208,25 +133,11 @@ static int gettok() {
// Abstract Syntax Tree (aka Parse Tree)
//===----------------------------------------------------------------------===//
namespace {
-
-raw_ostream &indent(raw_ostream &O, int size) {
- return O << std::string(size, ' ');
-}
-
/// ExprAST - Base class for all expression nodes.
class ExprAST {
- SourceLocation Loc;
-
public:
- ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}
virtual ~ExprAST() {}
virtual Value *codegen() = 0;
- int getLine() const { return Loc.Line; }
- int getCol() const { return Loc.Col; }
-
- virtual raw_ostream &dump(raw_ostream &out, int ind) {
- return out << ':' << getLine() << ':' << getCol() << '\n';
- }
};
/// NumberExprAST - Expression class for numeric literals like "1.0".
@@ -236,10 +147,6 @@ class NumberExprAST : public ExprAST {
public:
NumberExprAST(double Val) : Val(Val) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- return ExprAST::dump(out << Val, ind);
- }
};
/// VariableExprAST - Expression class for referencing a variable, like "a".
@@ -247,14 +154,9 @@ class VariableExprAST : public ExprAST {
std::string Name;
public:
- VariableExprAST(SourceLocation Loc, const std::string &Name)
- : ExprAST(Loc), Name(Name) {}
+ VariableExprAST(const std::string &Name) : Name(Name) {}
const std::string &getName() const { return Name; }
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- return ExprAST::dump(out << Name, ind);
- }
};
/// UnaryExprAST - Expression class for a unary operator.
@@ -266,12 +168,6 @@ public:
UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
: Opcode(Opcode), Operand(std::move(Operand)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "unary" << Opcode, ind);
- Operand->dump(out, ind + 1);
- return out;
- }
};
/// BinaryExprAST - Expression class for a binary operator.
@@ -280,17 +176,10 @@ class BinaryExprAST : public ExprAST {
std::unique_ptr<ExprAST> LHS, RHS;
public:
- BinaryExprAST(SourceLocation Loc, char Op, std::unique_ptr<ExprAST> LHS,
+ BinaryExprAST(char Op, std::unique_ptr<ExprAST> LHS,
std::unique_ptr<ExprAST> RHS)
- : ExprAST(Loc), Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
+ : Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "binary" << Op, ind);
- LHS->dump(indent(out, ind) << "LHS:", ind + 1);
- RHS->dump(indent(out, ind) << "RHS:", ind + 1);
- return out;
- }
};
/// CallExprAST - Expression class for function calls.
@@ -299,17 +188,10 @@ class CallExprAST : public ExprAST {
std::vector<std::unique_ptr<ExprAST>> Args;
public:
- CallExprAST(SourceLocation Loc, const std::string &Callee,
+ CallExprAST(const std::string &Callee,
std::vector<std::unique_ptr<ExprAST>> Args)
- : ExprAST(Loc), Callee(Callee), Args(std::move(Args)) {}
+ : Callee(Callee), Args(std::move(Args)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "call " << Callee, ind);
- for (const auto &Arg : Args)
- Arg->dump(indent(out, ind + 1), ind + 1);
- return out;
- }
};
/// IfExprAST - Expression class for if/then/else.
@@ -317,19 +199,10 @@ class IfExprAST : public ExprAST {
std::unique_ptr<ExprAST> Cond, Then, Else;
public:
- IfExprAST(SourceLocation Loc, std::unique_ptr<ExprAST> Cond,
- std::unique_ptr<ExprAST> Then, std::unique_ptr<ExprAST> Else)
- : ExprAST(Loc), Cond(std::move(Cond)), Then(std::move(Then)),
- Else(std::move(Else)) {}
+ IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
+ std::unique_ptr<ExprAST> Else)
+ : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "if", ind);
- Cond->dump(indent(out, ind) << "Cond:", ind + 1);
- Then->dump(indent(out, ind) << "Then:", ind + 1);
- Else->dump(indent(out, ind) << "Else:", ind + 1);
- return out;
- }
};
/// ForExprAST - Expression class for for/in.
@@ -344,15 +217,6 @@ public:
: VarName(VarName), Start(std::move(Start)), End(std::move(End)),
Step(std::move(Step)), Body(std::move(Body)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "for", ind);
- Start->dump(indent(out, ind) << "Cond:", ind + 1);
- End->dump(indent(out, ind) << "End:", ind + 1);
- Step->dump(indent(out, ind) << "Step:", ind + 1);
- Body->dump(indent(out, ind) << "Body:", ind + 1);
- return out;
- }
};
/// VarExprAST - Expression class for var/in
@@ -366,14 +230,6 @@ public:
std::unique_ptr<ExprAST> Body)
: VarNames(std::move(VarNames)), Body(std::move(Body)) {}
Value *codegen() override;
-
- raw_ostream &dump(raw_ostream &out, int ind) override {
- ExprAST::dump(out << "var", ind);
- for (const auto &NamedVar : VarNames)
- NamedVar.second->dump(indent(out, ind) << NamedVar.first << ':', ind + 1);
- Body->dump(indent(out, ind) << "Body:", ind + 1);
- return out;
- }
};
/// PrototypeAST - This class represents the "prototype" for a function,
@@ -384,14 +240,12 @@ class PrototypeAST {
std::vector<std::string> Args;
bool IsOperator;
unsigned Precedence; // Precedence if a binary op.
- int Line;
public:
- PrototypeAST(SourceLocation Loc, const std::string &Name,
- std::vector<std::string> Args, bool IsOperator = false,
- unsigned Prec = 0)
+ PrototypeAST(const std::string &Name, std::vector<std::string> Args,
+ bool IsOperator = false, unsigned Prec = 0)
: Name(Name), Args(std::move(Args)), IsOperator(IsOperator),
- Precedence(Prec), Line(Loc.Line) {}
+ Precedence(Prec) {}
Function *codegen();
const std::string &getName() const { return Name; }
@@ -404,7 +258,6 @@ public:
}
unsigned getBinaryPrecedence() const { return Precedence; }
- int getLine() const { return Line; }
};
/// FunctionAST - This class represents a function definition itself.
@@ -417,13 +270,6 @@ public:
std::unique_ptr<ExprAST> Body)
: Proto(std::move(Proto)), Body(std::move(Body)) {}
Function *codegen();
-
- raw_ostream &dump(raw_ostream &out, int ind) {
- indent(out, ind) << "FunctionAST\n";
- ++ind;
- indent(out, ind) << "Body:";
- return Body ? Body->dump(out, ind) : out << "null\n";
- }
};
} // end anonymous namespace
@@ -492,12 +338,10 @@ static std::unique_ptr<ExprAST> ParsePar
static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
std::string IdName = IdentifierStr;
- SourceLocation LitLoc = CurLoc;
-
getNextToken(); // eat identifier.
if (CurTok != '(') // Simple variable ref.
- return llvm::make_unique<VariableExprAST>(LitLoc, IdName);
+ return llvm::make_unique<VariableExprAST>(IdName);
// Call.
getNextToken(); // eat (
@@ -521,13 +365,11 @@ static std::unique_ptr<ExprAST> ParseIde
// Eat the ')'.
getNextToken();
- return llvm::make_unique<CallExprAST>(LitLoc, IdName, std::move(Args));
+ return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
}
/// ifexpr ::= 'if' expression 'then' expression 'else' expression
static std::unique_ptr<ExprAST> ParseIfExpr() {
- SourceLocation IfLoc = CurLoc;
-
getNextToken(); // eat the if.
// condition.
@@ -552,7 +394,7 @@ static std::unique_ptr<ExprAST> ParseIfE
if (!Else)
return nullptr;
- return llvm::make_unique<IfExprAST>(IfLoc, std::move(Cond), std::move(Then),
+ return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
std::move(Else));
}
@@ -707,7 +549,6 @@ static std::unique_ptr<ExprAST> ParseBin
// Okay, we know this is a binop.
int BinOp = CurTok;
- SourceLocation BinLoc = CurLoc;
getNextToken(); // eat binop
// Parse the unary expression after the binary operator.
@@ -725,8 +566,8 @@ static std::unique_ptr<ExprAST> ParseBin
}
// Merge LHS/RHS.
- LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),
- std::move(RHS));
+ LHS =
+ llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS), std::move(RHS));
}
}
@@ -748,8 +589,6 @@ static std::unique_ptr<ExprAST> ParseExp
static std::unique_ptr<PrototypeAST> ParsePrototype() {
std::string FnName;
- SourceLocation FnLoc = CurLoc;
-
unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
unsigned BinaryPrecedence = 30;
@@ -805,7 +644,7 @@ static std::unique_ptr<PrototypeAST> Par
if (Kind && ArgNames.size() != Kind)
return LogErrorP("Invalid number of operands for operator");
- return llvm::make_unique<PrototypeAST>(FnLoc, FnName, ArgNames, Kind != 0,
+ return llvm::make_unique<PrototypeAST>(FnName, ArgNames, Kind != 0,
BinaryPrecedence);
}
@@ -823,10 +662,9 @@ static std::unique_ptr<FunctionAST> Pars
/// toplevelexpr ::= expression
static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
- SourceLocation FnLoc = CurLoc;
if (auto E = ParseExpression()) {
// Make an anonymous proto.
- auto Proto = llvm::make_unique<PrototypeAST>(FnLoc, "__anon_expr",
+ auto Proto = llvm::make_unique<PrototypeAST>("__anon_expr",
std::vector<std::string>());
return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
}
@@ -840,51 +678,13 @@ static std::unique_ptr<PrototypeAST> Par
}
//===----------------------------------------------------------------------===//
-// Debug Info Support
-//===----------------------------------------------------------------------===//
-
-static std::unique_ptr<DIBuilder> DBuilder;
-
-DIType *DebugInfo::getDoubleTy() {
- if (DblTy)
- return DblTy;
-
- DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);
- return DblTy;
-}
-
-void DebugInfo::emitLocation(ExprAST *AST) {
- if (!AST)
- return Builder.SetCurrentDebugLocation(DebugLoc());
- DIScope *Scope;
- if (LexicalBlocks.empty())
- Scope = TheCU;
- else
- Scope = LexicalBlocks.back();
- Builder.SetCurrentDebugLocation(
- DebugLoc::get(AST->getLine(), AST->getCol(), Scope));
-}
-
-static DISubroutineType *CreateFunctionType(unsigned NumArgs, DIFile *Unit) {
- SmallVector<Metadata *, 8> EltTys;
- DIType *DblTy = KSDbgInfo.getDoubleTy();
-
- // Add the result type.
- EltTys.push_back(DblTy);
-
- for (unsigned i = 0, e = NumArgs; i != e; ++i)
- EltTys.push_back(DblTy);
-
- return DBuilder->createSubroutineType(DBuilder->getOrCreateTypeArray(EltTys));
-}
-
-//===----------------------------------------------------------------------===//
// Code Generation
//===----------------------------------------------------------------------===//
+static LLVMContext TheContext;
+static IRBuilder<> Builder(TheContext);
static std::unique_ptr<Module> TheModule;
static std::map<std::string, AllocaInst *> NamedValues;
-static std::unique_ptr<KaleidoscopeJIT> TheJIT;
static std::map<std::string, std::unique_ptr<PrototypeAST>> FunctionProtos;
Value *LogErrorV(const char *Str) {
@@ -917,7 +717,6 @@ static AllocaInst *CreateEntryBlockAlloc
}
Value *NumberExprAST::codegen() {
- KSDbgInfo.emitLocation(this);
return ConstantFP::get(TheContext, APFloat(Val));
}
@@ -927,7 +726,6 @@ Value *VariableExprAST::codegen() {
if (!V)
return LogErrorV("Unknown variable name");
- KSDbgInfo.emitLocation(this);
// Load the value.
return Builder.CreateLoad(V, Name.c_str());
}
@@ -941,13 +739,10 @@ Value *UnaryExprAST::codegen() {
if (!F)
return LogErrorV("Unknown unary operator");
- KSDbgInfo.emitLocation(this);
return Builder.CreateCall(F, OperandV, "unop");
}
Value *BinaryExprAST::codegen() {
- KSDbgInfo.emitLocation(this);
-
// Special case '=' because we don't want to emit the LHS as an expression.
if (Op == '=') {
// Assignment requires the LHS to be an identifier.
@@ -1001,8 +796,6 @@ Value *BinaryExprAST::codegen() {
}
Value *CallExprAST::codegen() {
- KSDbgInfo.emitLocation(this);
-
// Look up the name in the global module table.
Function *CalleeF = getFunction(Callee);
if (!CalleeF)
@@ -1023,8 +816,6 @@ Value *CallExprAST::codegen() {
}
Value *IfExprAST::codegen() {
- KSDbgInfo.emitLocation(this);
-
Value *CondV = Cond->codegen();
if (!CondV)
return nullptr;
@@ -1101,8 +892,6 @@ Value *ForExprAST::codegen() {
// Create an alloca for the variable in the entry block.
AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
- KSDbgInfo.emitLocation(this);
-
// Emit the start code first, without 'variable' in scope.
Value *StartVal = Start->codegen();
if (!StartVal)
@@ -1213,8 +1002,6 @@ Value *VarExprAST::codegen() {
NamedValues[VarName] = Alloca;
}
- KSDbgInfo.emitLocation(this);
-
// Codegen the body, now that all vars are in scope.
Value *BodyVal = Body->codegen();
if (!BodyVal)
@@ -1262,43 +1049,12 @@ Function *FunctionAST::codegen() {
BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
Builder.SetInsertPoint(BB);
- // Create a subprogram DIE for this function.
- DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU->getFilename(),
- KSDbgInfo.TheCU->getDirectory());
- DIScope *FContext = Unit;
- unsigned LineNo = P.getLine();
- unsigned ScopeLine = LineNo;
- DISubprogram *SP = DBuilder->createFunction(
- FContext, P.getName(), StringRef(), Unit, LineNo,
- CreateFunctionType(TheFunction->arg_size(), Unit),
- false /* internal linkage */, true /* definition */, ScopeLine,
- DINode::FlagPrototyped, false);
- TheFunction->setSubprogram(SP);
-
- // Push the current scope.
- KSDbgInfo.LexicalBlocks.push_back(SP);
-
- // Unset the location for the prologue emission (leading instructions with no
- // location in a function are considered part of the prologue and the debugger
- // will run past them when breaking on a function)
- KSDbgInfo.emitLocation(nullptr);
-
// Record the function arguments in the NamedValues map.
NamedValues.clear();
- unsigned ArgIdx = 0;
for (auto &Arg : TheFunction->args()) {
// Create an alloca for this variable.
AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());
- // Create a debug descriptor for the variable.
- DILocalVariable *D = DBuilder->createParameterVariable(
- SP, Arg.getName(), ++ArgIdx, Unit, LineNo, KSDbgInfo.getDoubleTy(),
- true);
-
- DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),
- DebugLoc::get(LineNo, 0, SP),
- Builder.GetInsertBlock());
-
// Store the initial value into the alloca.
Builder.CreateStore(&Arg, Alloca);
@@ -1306,15 +1062,10 @@ Function *FunctionAST::codegen() {
NamedValues[Arg.getName()] = Alloca;
}
- KSDbgInfo.emitLocation(Body.get());
-
if (Value *RetVal = Body->codegen()) {
// Finish off the function.
Builder.CreateRet(RetVal);
- // Pop off the lexical block for the function.
- KSDbgInfo.LexicalBlocks.pop_back();
-
// Validate the generated code, checking for consistency.
verifyFunction(*TheFunction);
@@ -1326,11 +1077,6 @@ Function *FunctionAST::codegen() {
if (P.isBinaryOp())
BinopPrecedence.erase(Proto->getOperatorName());
-
- // Pop off the lexical block for the function since we added it
- // unconditionally.
- KSDbgInfo.LexicalBlocks.pop_back();
-
return nullptr;
}
@@ -1338,16 +1084,17 @@ Function *FunctionAST::codegen() {
// Top-Level parsing and JIT Driver
//===----------------------------------------------------------------------===//
-static void InitializeModule() {
+static void InitializeModuleAndPassManager() {
// Open a new module.
TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
- TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
}
static void HandleDefinition() {
if (auto FnAST = ParseDefinition()) {
- if (!FnAST->codegen())
- fprintf(stderr, "Error reading function definition:");
+ if (auto *FnIR = FnAST->codegen()) {
+ fprintf(stderr, "Read function definition:");
+ FnIR->dump();
+ }
} else {
// Skip token for error recovery.
getNextToken();
@@ -1356,10 +1103,11 @@ static void HandleDefinition() {
static void HandleExtern() {
if (auto ProtoAST = ParseExtern()) {
- if (!ProtoAST->codegen())
- fprintf(stderr, "Error reading extern");
- else
+ if (auto *FnIR = ProtoAST->codegen()) {
+ fprintf(stderr, "Read extern: ");
+ FnIR->dump();
FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
+ }
} else {
// Skip token for error recovery.
getNextToken();
@@ -1369,9 +1117,7 @@ static void HandleExtern() {
static void HandleTopLevelExpression() {
// Evaluate a top-level expression into an anonymous function.
if (auto FnAST = ParseTopLevelExpr()) {
- if (!FnAST->codegen()) {
- fprintf(stderr, "Error generating code for top level expr");
- }
+ FnAST->codegen();
} else {
// Skip token for error recovery.
getNextToken();
@@ -1421,50 +1167,74 @@ extern "C" double printd(double X) {
//===----------------------------------------------------------------------===//
int main() {
- InitializeNativeTarget();
- InitializeNativeTargetAsmPrinter();
- InitializeNativeTargetAsmParser();
-
// Install standard binary operators.
// 1 is lowest precedence.
- BinopPrecedence['='] = 2;
BinopPrecedence['<'] = 10;
BinopPrecedence['+'] = 20;
BinopPrecedence['-'] = 20;
BinopPrecedence['*'] = 40; // highest.
// Prime the first token.
+ fprintf(stderr, "ready> ");
getNextToken();
- TheJIT = llvm::make_unique<KaleidoscopeJIT>();
-
- InitializeModule();
-
- // Add the current debug info version into the module.
- TheModule->addModuleFlag(Module::Warning, "Debug Info Version",
- DEBUG_METADATA_VERSION);
-
- // Darwin only supports dwarf2.
- if (Triple(sys::getProcessTriple()).isOSDarwin())
- TheModule->addModuleFlag(llvm::Module::Warning, "Dwarf Version", 2);
-
- // Construct the DIBuilder, we do this here because we need the module.
- DBuilder = llvm::make_unique<DIBuilder>(*TheModule);
-
- // Create the compile unit for the module.
- // Currently down as "fib.ks" as a filename since we're redirecting stdin
- // but we'd like actual source locations.
- KSDbgInfo.TheCU = DBuilder->createCompileUnit(
- dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", false, "", 0);
+ InitializeModuleAndPassManager();
// Run the main "interpreter loop" now.
MainLoop();
- // Finalize the debug info.
- DBuilder->finalize();
+ // Initialize the target registry etc.
+ InitializeAllTargetInfos();
+ InitializeAllTargets();
+ InitializeAllTargetMCs();
+ InitializeAllAsmParsers();
+ InitializeAllAsmPrinters();
+
+ auto TargetTriple = sys::getDefaultTargetTriple();
+ TheModule->setTargetTriple(TargetTriple);
+
+ std::string Error;
+ auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
+
+ // Print an error and exit if we couldn't find the requested target.
+ // This generally occurs if we've forgotten to initialise the
+ // TargetRegistry or we have a bogus target triple.
+ if (!Target) {
+ errs() << Error;
+ return 1;
+ }
+
+ auto CPU = "generic";
+ auto Features = "";
+
+ TargetOptions opt;
+ auto RM = Optional<Reloc::Model>();
+ auto TheTargetMachine =
+ Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
+
+ TheModule->setDataLayout(TheTargetMachine->createDataLayout());
+
+ auto Filename = "output.o";
+ std::error_code EC;
+ raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
+
+ if (EC) {
+ errs() << "Could not open file: " << EC.message();
+ return 1;
+ }
+
+ legacy::PassManager pass;
+ auto FileType = TargetMachine::CGFT_ObjectFile;
+
+ if (TheTargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
+ errs() << "TheTargetMachine can't emit a file of this type";
+ return 1;
+ }
+
+ pass.run(*TheModule);
+ dest.flush();
- // Print out all of the generated code.
- TheModule->dump();
+ outs() << "Wrote " << Filename << "\n";
return 0;
}
Added: llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt?rev=274441&view=auto
==============================================================================
--- llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt (added)
+++ llvm/trunk/examples/Kaleidoscope/Chapter9/CMakeLists.txt Sat Jul 2 12:01:59 2016
@@ -0,0 +1,13 @@
+set(LLVM_LINK_COMPONENTS
+ Core
+ ExecutionEngine
+ Object
+ Support
+ native
+ )
+
+add_kaleidoscope_chapter(Kaleidoscope-Ch9
+ toy.cpp
+ )
+
+export_executable_symbols(Kaleidoscope-Ch9)
Added: llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp?rev=274441&view=auto
==============================================================================
--- llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp (added)
+++ llvm/trunk/examples/Kaleidoscope/Chapter9/toy.cpp Sat Jul 2 12:01:59 2016
@@ -0,0 +1,1445 @@
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/Analysis/BasicAliasAnalysis.h"
+#include "llvm/Analysis/Passes.h"
+#include "llvm/IR/DIBuilder.h"
+#include "llvm/IR/IRBuilder.h"
+#include "llvm/IR/LLVMContext.h"
+#include "llvm/IR/LegacyPassManager.h"
+#include "llvm/IR/Module.h"
+#include "llvm/IR/Verifier.h"
+#include "llvm/Support/TargetSelect.h"
+#include "llvm/Transforms/Scalar.h"
+#include <cctype>
+#include <cstdio>
+#include <map>
+#include <string>
+#include <vector>
+#include "../include/KaleidoscopeJIT.h"
+
+using namespace llvm;
+using namespace llvm::orc;
+
+//===----------------------------------------------------------------------===//
+// Lexer
+//===----------------------------------------------------------------------===//
+
+// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
+// of these for known things.
+enum Token {
+ tok_eof = -1,
+
+ // commands
+ tok_def = -2,
+ tok_extern = -3,
+
+ // primary
+ tok_identifier = -4,
+ tok_number = -5,
+
+ // control
+ tok_if = -6,
+ tok_then = -7,
+ tok_else = -8,
+ tok_for = -9,
+ tok_in = -10,
+
+ // operators
+ tok_binary = -11,
+ tok_unary = -12,
+
+ // var definition
+ tok_var = -13
+};
+
+std::string getTokName(int Tok) {
+ switch (Tok) {
+ case tok_eof:
+ return "eof";
+ case tok_def:
+ return "def";
+ case tok_extern:
+ return "extern";
+ case tok_identifier:
+ return "identifier";
+ case tok_number:
+ return "number";
+ case tok_if:
+ return "if";
+ case tok_then:
+ return "then";
+ case tok_else:
+ return "else";
+ case tok_for:
+ return "for";
+ case tok_in:
+ return "in";
+ case tok_binary:
+ return "binary";
+ case tok_unary:
+ return "unary";
+ case tok_var:
+ return "var";
+ }
+ return std::string(1, (char)Tok);
+}
+
+namespace {
+class PrototypeAST;
+class ExprAST;
+}
+static LLVMContext TheContext;
+static IRBuilder<> Builder(TheContext);
+struct DebugInfo {
+ DICompileUnit *TheCU;
+ DIType *DblTy;
+ std::vector<DIScope *> LexicalBlocks;
+
+ void emitLocation(ExprAST *AST);
+ DIType *getDoubleTy();
+} KSDbgInfo;
+
+struct SourceLocation {
+ int Line;
+ int Col;
+};
+static SourceLocation CurLoc;
+static SourceLocation LexLoc = {1, 0};
+
+static int advance() {
+ int LastChar = getchar();
+
+ if (LastChar == '\n' || LastChar == '\r') {
+ LexLoc.Line++;
+ LexLoc.Col = 0;
+ } else
+ LexLoc.Col++;
+ return LastChar;
+}
+
+static std::string IdentifierStr; // Filled in if tok_identifier
+static double NumVal; // Filled in if tok_number
+
+/// gettok - Return the next token from standard input.
+static int gettok() {
+ static int LastChar = ' ';
+
+ // Skip any whitespace.
+ while (isspace(LastChar))
+ LastChar = advance();
+
+ CurLoc = LexLoc;
+
+ if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
+ IdentifierStr = LastChar;
+ while (isalnum((LastChar = advance())))
+ IdentifierStr += LastChar;
+
+ if (IdentifierStr == "def")
+ return tok_def;
+ if (IdentifierStr == "extern")
+ return tok_extern;
+ if (IdentifierStr == "if")
+ return tok_if;
+ if (IdentifierStr == "then")
+ return tok_then;
+ if (IdentifierStr == "else")
+ return tok_else;
+ if (IdentifierStr == "for")
+ return tok_for;
+ if (IdentifierStr == "in")
+ return tok_in;
+ if (IdentifierStr == "binary")
+ return tok_binary;
+ if (IdentifierStr == "unary")
+ return tok_unary;
+ if (IdentifierStr == "var")
+ return tok_var;
+ return tok_identifier;
+ }
+
+ if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
+ std::string NumStr;
+ do {
+ NumStr += LastChar;
+ LastChar = advance();
+ } while (isdigit(LastChar) || LastChar == '.');
+
+ NumVal = strtod(NumStr.c_str(), nullptr);
+ return tok_number;
+ }
+
+ if (LastChar == '#') {
+ // Comment until end of line.
+ do
+ LastChar = advance();
+ while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
+
+ if (LastChar != EOF)
+ return gettok();
+ }
+
+ // Check for end of file. Don't eat the EOF.
+ if (LastChar == EOF)
+ return tok_eof;
+
+ // Otherwise, just return the character as its ascii value.
+ int ThisChar = LastChar;
+ LastChar = advance();
+ return ThisChar;
+}
+
+//===----------------------------------------------------------------------===//
+// Abstract Syntax Tree (aka Parse Tree)
+//===----------------------------------------------------------------------===//
+namespace {
+
+raw_ostream &indent(raw_ostream &O, int size) {
+ return O << std::string(size, ' ');
+}
+
+/// ExprAST - Base class for all expression nodes.
+class ExprAST {
+ SourceLocation Loc;
+
+public:
+ ExprAST(SourceLocation Loc = CurLoc) : Loc(Loc) {}
+ virtual ~ExprAST() {}
+ virtual Value *codegen() = 0;
+ int getLine() const { return Loc.Line; }
+ int getCol() const { return Loc.Col; }
+ virtual raw_ostream &dump(raw_ostream &out, int ind) {
+ return out << ':' << getLine() << ':' << getCol() << '\n';
+ }
+};
+
+/// NumberExprAST - Expression class for numeric literals like "1.0".
+class NumberExprAST : public ExprAST {
+ double Val;
+
+public:
+ NumberExprAST(double Val) : Val(Val) {}
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ return ExprAST::dump(out << Val, ind);
+ }
+ Value *codegen() override;
+};
+
+/// VariableExprAST - Expression class for referencing a variable, like "a".
+class VariableExprAST : public ExprAST {
+ std::string Name;
+
+public:
+ VariableExprAST(SourceLocation Loc, const std::string &Name)
+ : ExprAST(Loc), Name(Name) {}
+ const std::string &getName() const { return Name; }
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ return ExprAST::dump(out << Name, ind);
+ }
+};
+
+/// UnaryExprAST - Expression class for a unary operator.
+class UnaryExprAST : public ExprAST {
+ char Opcode;
+ std::unique_ptr<ExprAST> Operand;
+
+public:
+ UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
+ : Opcode(Opcode), Operand(std::move(Operand)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "unary" << Opcode, ind);
+ Operand->dump(out, ind + 1);
+ return out;
+ }
+};
+
+/// BinaryExprAST - Expression class for a binary operator.
+class BinaryExprAST : public ExprAST {
+ char Op;
+ std::unique_ptr<ExprAST> LHS, RHS;
+
+public:
+ BinaryExprAST(SourceLocation Loc, char Op, std::unique_ptr<ExprAST> LHS,
+ std::unique_ptr<ExprAST> RHS)
+ : ExprAST(Loc), Op(Op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "binary" << Op, ind);
+ LHS->dump(indent(out, ind) << "LHS:", ind + 1);
+ RHS->dump(indent(out, ind) << "RHS:", ind + 1);
+ return out;
+ }
+};
+
+/// CallExprAST - Expression class for function calls.
+class CallExprAST : public ExprAST {
+ std::string Callee;
+ std::vector<std::unique_ptr<ExprAST>> Args;
+
+public:
+ CallExprAST(SourceLocation Loc, const std::string &Callee,
+ std::vector<std::unique_ptr<ExprAST>> Args)
+ : ExprAST(Loc), Callee(Callee), Args(std::move(Args)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "call " << Callee, ind);
+ for (const auto &Arg : Args)
+ Arg->dump(indent(out, ind + 1), ind + 1);
+ return out;
+ }
+};
+
+/// IfExprAST - Expression class for if/then/else.
+class IfExprAST : public ExprAST {
+ std::unique_ptr<ExprAST> Cond, Then, Else;
+
+public:
+ IfExprAST(SourceLocation Loc, std::unique_ptr<ExprAST> Cond,
+ std::unique_ptr<ExprAST> Then, std::unique_ptr<ExprAST> Else)
+ : ExprAST(Loc), Cond(std::move(Cond)), Then(std::move(Then)),
+ Else(std::move(Else)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "if", ind);
+ Cond->dump(indent(out, ind) << "Cond:", ind + 1);
+ Then->dump(indent(out, ind) << "Then:", ind + 1);
+ Else->dump(indent(out, ind) << "Else:", ind + 1);
+ return out;
+ }
+};
+
+/// ForExprAST - Expression class for for/in.
+class ForExprAST : public ExprAST {
+ std::string VarName;
+ std::unique_ptr<ExprAST> Start, End, Step, Body;
+
+public:
+ ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
+ std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
+ std::unique_ptr<ExprAST> Body)
+ : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
+ Step(std::move(Step)), Body(std::move(Body)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "for", ind);
+ Start->dump(indent(out, ind) << "Cond:", ind + 1);
+ End->dump(indent(out, ind) << "End:", ind + 1);
+ Step->dump(indent(out, ind) << "Step:", ind + 1);
+ Body->dump(indent(out, ind) << "Body:", ind + 1);
+ return out;
+ }
+};
+
+/// VarExprAST - Expression class for var/in
+class VarExprAST : public ExprAST {
+ std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
+ std::unique_ptr<ExprAST> Body;
+
+public:
+ VarExprAST(
+ std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
+ std::unique_ptr<ExprAST> Body)
+ : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
+ Value *codegen() override;
+ raw_ostream &dump(raw_ostream &out, int ind) override {
+ ExprAST::dump(out << "var", ind);
+ for (const auto &NamedVar : VarNames)
+ NamedVar.second->dump(indent(out, ind) << NamedVar.first << ':', ind + 1);
+ Body->dump(indent(out, ind) << "Body:", ind + 1);
+ return out;
+ }
+};
+
+/// PrototypeAST - This class represents the "prototype" for a function,
+/// which captures its name, and its argument names (thus implicitly the number
+/// of arguments the function takes), as well as if it is an operator.
+class PrototypeAST {
+ std::string Name;
+ std::vector<std::string> Args;
+ bool IsOperator;
+ unsigned Precedence; // Precedence if a binary op.
+ int Line;
+
+public:
+ PrototypeAST(SourceLocation Loc, const std::string &Name,
+ std::vector<std::string> Args, bool IsOperator = false,
+ unsigned Prec = 0)
+ : Name(Name), Args(std::move(Args)), IsOperator(IsOperator),
+ Precedence(Prec), Line(Loc.Line) {}
+ Function *codegen();
+ const std::string &getName() const { return Name; }
+
+ bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
+ bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
+
+ char getOperatorName() const {
+ assert(isUnaryOp() || isBinaryOp());
+ return Name[Name.size() - 1];
+ }
+
+ unsigned getBinaryPrecedence() const { return Precedence; }
+ int getLine() const { return Line; }
+};
+
+/// FunctionAST - This class represents a function definition itself.
+class FunctionAST {
+ std::unique_ptr<PrototypeAST> Proto;
+ std::unique_ptr<ExprAST> Body;
+
+public:
+ FunctionAST(std::unique_ptr<PrototypeAST> Proto,
+ std::unique_ptr<ExprAST> Body)
+ : Proto(std::move(Proto)), Body(std::move(Body)) {}
+ Function *codegen();
+ raw_ostream &dump(raw_ostream &out, int ind) {
+ indent(out, ind) << "FunctionAST\n";
+ ++ind;
+ indent(out, ind) << "Body:";
+ return Body ? Body->dump(out, ind) : out << "null\n";
+ }
+};
+} // end anonymous namespace
+
+//===----------------------------------------------------------------------===//
+// Parser
+//===----------------------------------------------------------------------===//
+
+/// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
+/// token the parser is looking at. getNextToken reads another token from the
+/// lexer and updates CurTok with its results.
+static int CurTok;
+static int getNextToken() { return CurTok = gettok(); }
+
+/// BinopPrecedence - This holds the precedence for each binary operator that is
+/// defined.
+static std::map<char, int> BinopPrecedence;
+
+/// GetTokPrecedence - Get the precedence of the pending binary operator token.
+static int GetTokPrecedence() {
+ if (!isascii(CurTok))
+ return -1;
+
+ // Make sure it's a declared binop.
+ int TokPrec = BinopPrecedence[CurTok];
+ if (TokPrec <= 0)
+ return -1;
+ return TokPrec;
+}
+
+/// LogError* - These are little helper functions for error handling.
+std::unique_ptr<ExprAST> LogError(const char *Str) {
+ fprintf(stderr, "Error: %s\n", Str);
+ return nullptr;
+}
+
+std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
+ LogError(Str);
+ return nullptr;
+}
+
+static std::unique_ptr<ExprAST> ParseExpression();
+
+/// numberexpr ::= number
+static std::unique_ptr<ExprAST> ParseNumberExpr() {
+ auto Result = llvm::make_unique<NumberExprAST>(NumVal);
+ getNextToken(); // consume the number
+ return std::move(Result);
+}
+
+/// parenexpr ::= '(' expression ')'
+static std::unique_ptr<ExprAST> ParseParenExpr() {
+ getNextToken(); // eat (.
+ auto V = ParseExpression();
+ if (!V)
+ return nullptr;
+
+ if (CurTok != ')')
+ return LogError("expected ')'");
+ getNextToken(); // eat ).
+ return V;
+}
+
+/// identifierexpr
+/// ::= identifier
+/// ::= identifier '(' expression* ')'
+static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
+ std::string IdName = IdentifierStr;
+
+ SourceLocation LitLoc = CurLoc;
+
+ getNextToken(); // eat identifier.
+
+ if (CurTok != '(') // Simple variable ref.
+ return llvm::make_unique<VariableExprAST>(LitLoc, IdName);
+
+ // Call.
+ getNextToken(); // eat (
+ std::vector<std::unique_ptr<ExprAST>> Args;
+ if (CurTok != ')') {
+ while (1) {
+ if (auto Arg = ParseExpression())
+ Args.push_back(std::move(Arg));
+ else
+ return nullptr;
+
+ if (CurTok == ')')
+ break;
+
+ if (CurTok != ',')
+ return LogError("Expected ')' or ',' in argument list");
+ getNextToken();
+ }
+ }
+
+ // Eat the ')'.
+ getNextToken();
+
+ return llvm::make_unique<CallExprAST>(LitLoc, IdName, std::move(Args));
+}
+
+/// ifexpr ::= 'if' expression 'then' expression 'else' expression
+static std::unique_ptr<ExprAST> ParseIfExpr() {
+ SourceLocation IfLoc = CurLoc;
+
+ getNextToken(); // eat the if.
+
+ // condition.
+ auto Cond = ParseExpression();
+ if (!Cond)
+ return nullptr;
+
+ if (CurTok != tok_then)
+ return LogError("expected then");
+ getNextToken(); // eat the then
+
+ auto Then = ParseExpression();
+ if (!Then)
+ return nullptr;
+
+ if (CurTok != tok_else)
+ return LogError("expected else");
+
+ getNextToken();
+
+ auto Else = ParseExpression();
+ if (!Else)
+ return nullptr;
+
+ return llvm::make_unique<IfExprAST>(IfLoc, std::move(Cond), std::move(Then),
+ std::move(Else));
+}
+
+/// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
+static std::unique_ptr<ExprAST> ParseForExpr() {
+ getNextToken(); // eat the for.
+
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier after for");
+
+ std::string IdName = IdentifierStr;
+ getNextToken(); // eat identifier.
+
+ if (CurTok != '=')
+ return LogError("expected '=' after for");
+ getNextToken(); // eat '='.
+
+ auto Start = ParseExpression();
+ if (!Start)
+ return nullptr;
+ if (CurTok != ',')
+ return LogError("expected ',' after for start value");
+ getNextToken();
+
+ auto End = ParseExpression();
+ if (!End)
+ return nullptr;
+
+ // The step value is optional.
+ std::unique_ptr<ExprAST> Step;
+ if (CurTok == ',') {
+ getNextToken();
+ Step = ParseExpression();
+ if (!Step)
+ return nullptr;
+ }
+
+ if (CurTok != tok_in)
+ return LogError("expected 'in' after for");
+ getNextToken(); // eat 'in'.
+
+ auto Body = ParseExpression();
+ if (!Body)
+ return nullptr;
+
+ return llvm::make_unique<ForExprAST>(IdName, std::move(Start), std::move(End),
+ std::move(Step), std::move(Body));
+}
+
+/// varexpr ::= 'var' identifier ('=' expression)?
+// (',' identifier ('=' expression)?)* 'in' expression
+static std::unique_ptr<ExprAST> ParseVarExpr() {
+ getNextToken(); // eat the var.
+
+ std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
+
+ // At least one variable name is required.
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier after var");
+
+ while (1) {
+ std::string Name = IdentifierStr;
+ getNextToken(); // eat identifier.
+
+ // Read the optional initializer.
+ std::unique_ptr<ExprAST> Init = nullptr;
+ if (CurTok == '=') {
+ getNextToken(); // eat the '='.
+
+ Init = ParseExpression();
+ if (!Init)
+ return nullptr;
+ }
+
+ VarNames.push_back(std::make_pair(Name, std::move(Init)));
+
+ // End of var list, exit loop.
+ if (CurTok != ',')
+ break;
+ getNextToken(); // eat the ','.
+
+ if (CurTok != tok_identifier)
+ return LogError("expected identifier list after var");
+ }
+
+ // At this point, we have to have 'in'.
+ if (CurTok != tok_in)
+ return LogError("expected 'in' keyword after 'var'");
+ getNextToken(); // eat 'in'.
+
+ auto Body = ParseExpression();
+ if (!Body)
+ return nullptr;
+
+ return llvm::make_unique<VarExprAST>(std::move(VarNames), std::move(Body));
+}
+
+/// primary
+/// ::= identifierexpr
+/// ::= numberexpr
+/// ::= parenexpr
+/// ::= ifexpr
+/// ::= forexpr
+/// ::= varexpr
+static std::unique_ptr<ExprAST> ParsePrimary() {
+ switch (CurTok) {
+ default:
+ return LogError("unknown token when expecting an expression");
+ case tok_identifier:
+ return ParseIdentifierExpr();
+ case tok_number:
+ return ParseNumberExpr();
+ case '(':
+ return ParseParenExpr();
+ case tok_if:
+ return ParseIfExpr();
+ case tok_for:
+ return ParseForExpr();
+ case tok_var:
+ return ParseVarExpr();
+ }
+}
+
+/// unary
+/// ::= primary
+/// ::= '!' unary
+static std::unique_ptr<ExprAST> ParseUnary() {
+ // If the current token is not an operator, it must be a primary expr.
+ if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
+ return ParsePrimary();
+
+ // If this is a unary operator, read it.
+ int Opc = CurTok;
+ getNextToken();
+ if (auto Operand = ParseUnary())
+ return llvm::make_unique<UnaryExprAST>(Opc, std::move(Operand));
+ return nullptr;
+}
+
+/// binoprhs
+/// ::= ('+' unary)*
+static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
+ std::unique_ptr<ExprAST> LHS) {
+ // If this is a binop, find its precedence.
+ while (1) {
+ int TokPrec = GetTokPrecedence();
+
+ // If this is a binop that binds at least as tightly as the current binop,
+ // consume it, otherwise we are done.
+ if (TokPrec < ExprPrec)
+ return LHS;
+
+ // Okay, we know this is a binop.
+ int BinOp = CurTok;
+ SourceLocation BinLoc = CurLoc;
+ getNextToken(); // eat binop
+
+ // Parse the unary expression after the binary operator.
+ auto RHS = ParseUnary();
+ if (!RHS)
+ return nullptr;
+
+ // If BinOp binds less tightly with RHS than the operator after RHS, let
+ // the pending operator take RHS as its LHS.
+ int NextPrec = GetTokPrecedence();
+ if (TokPrec < NextPrec) {
+ RHS = ParseBinOpRHS(TokPrec + 1, std::move(RHS));
+ if (!RHS)
+ return nullptr;
+ }
+
+ // Merge LHS/RHS.
+ LHS = llvm::make_unique<BinaryExprAST>(BinLoc, BinOp, std::move(LHS),
+ std::move(RHS));
+ }
+}
+
+/// expression
+/// ::= unary binoprhs
+///
+static std::unique_ptr<ExprAST> ParseExpression() {
+ auto LHS = ParseUnary();
+ if (!LHS)
+ return nullptr;
+
+ return ParseBinOpRHS(0, std::move(LHS));
+}
+
+/// prototype
+/// ::= id '(' id* ')'
+/// ::= binary LETTER number? (id, id)
+/// ::= unary LETTER (id)
+static std::unique_ptr<PrototypeAST> ParsePrototype() {
+ std::string FnName;
+
+ SourceLocation FnLoc = CurLoc;
+
+ unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
+ unsigned BinaryPrecedence = 30;
+
+ switch (CurTok) {
+ default:
+ return LogErrorP("Expected function name in prototype");
+ case tok_identifier:
+ FnName = IdentifierStr;
+ Kind = 0;
+ getNextToken();
+ break;
+ case tok_unary:
+ getNextToken();
+ if (!isascii(CurTok))
+ return LogErrorP("Expected unary operator");
+ FnName = "unary";
+ FnName += (char)CurTok;
+ Kind = 1;
+ getNextToken();
+ break;
+ case tok_binary:
+ getNextToken();
+ if (!isascii(CurTok))
+ return LogErrorP("Expected binary operator");
+ FnName = "binary";
+ FnName += (char)CurTok;
+ Kind = 2;
+ getNextToken();
+
+ // Read the precedence if present.
+ if (CurTok == tok_number) {
+ if (NumVal < 1 || NumVal > 100)
+ return LogErrorP("Invalid precedecnce: must be 1..100");
+ BinaryPrecedence = (unsigned)NumVal;
+ getNextToken();
+ }
+ break;
+ }
+
+ if (CurTok != '(')
+ return LogErrorP("Expected '(' in prototype");
+
+ std::vector<std::string> ArgNames;
+ while (getNextToken() == tok_identifier)
+ ArgNames.push_back(IdentifierStr);
+ if (CurTok != ')')
+ return LogErrorP("Expected ')' in prototype");
+
+ // success.
+ getNextToken(); // eat ')'.
+
+ // Verify right number of names for operator.
+ if (Kind && ArgNames.size() != Kind)
+ return LogErrorP("Invalid number of operands for operator");
+
+ return llvm::make_unique<PrototypeAST>(FnLoc, FnName, ArgNames, Kind != 0,
+ BinaryPrecedence);
+}
+
+/// definition ::= 'def' prototype expression
+static std::unique_ptr<FunctionAST> ParseDefinition() {
+ getNextToken(); // eat def.
+ auto Proto = ParsePrototype();
+ if (!Proto)
+ return nullptr;
+
+ if (auto E = ParseExpression())
+ return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+ return nullptr;
+}
+
+/// toplevelexpr ::= expression
+static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
+ SourceLocation FnLoc = CurLoc;
+ if (auto E = ParseExpression()) {
+ // Make an anonymous proto.
+ auto Proto = llvm::make_unique<PrototypeAST>(FnLoc, "__anon_expr",
+ std::vector<std::string>());
+ return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+ }
+ return nullptr;
+}
+
+/// external ::= 'extern' prototype
+static std::unique_ptr<PrototypeAST> ParseExtern() {
+ getNextToken(); // eat extern.
+ return ParsePrototype();
+}
+
+//===----------------------------------------------------------------------===//
+// Debug Info Support
+//===----------------------------------------------------------------------===//
+
+static std::unique_ptr<DIBuilder> DBuilder;
+
+DIType *DebugInfo::getDoubleTy() {
+ if (DblTy)
+ return DblTy;
+
+ DblTy = DBuilder->createBasicType("double", 64, 64, dwarf::DW_ATE_float);
+ return DblTy;
+}
+
+void DebugInfo::emitLocation(ExprAST *AST) {
+ if (!AST)
+ return Builder.SetCurrentDebugLocation(DebugLoc());
+ DIScope *Scope;
+ if (LexicalBlocks.empty())
+ Scope = TheCU;
+ else
+ Scope = LexicalBlocks.back();
+ Builder.SetCurrentDebugLocation(
+ DebugLoc::get(AST->getLine(), AST->getCol(), Scope));
+}
+
+static DISubroutineType *CreateFunctionType(unsigned NumArgs, DIFile *Unit) {
+ SmallVector<Metadata *, 8> EltTys;
+ DIType *DblTy = KSDbgInfo.getDoubleTy();
+
+ // Add the result type.
+ EltTys.push_back(DblTy);
+
+ for (unsigned i = 0, e = NumArgs; i != e; ++i)
+ EltTys.push_back(DblTy);
+
+ return DBuilder->createSubroutineType(DBuilder->getOrCreateTypeArray(EltTys));
+}
+
+//===----------------------------------------------------------------------===//
+// Code Generation
+//===----------------------------------------------------------------------===//
+
+static std::unique_ptr<Module> TheModule;
+static std::map<std::string, AllocaInst *> NamedValues;
+static std::unique_ptr<KaleidoscopeJIT> TheJIT;
+static std::map<std::string, std::unique_ptr<PrototypeAST>> FunctionProtos;
+
+Value *LogErrorV(const char *Str) {
+ LogError(Str);
+ return nullptr;
+}
+
+Function *getFunction(std::string Name) {
+ // First, see if the function has already been added to the current module.
+ if (auto *F = TheModule->getFunction(Name))
+ return F;
+
+ // If not, check whether we can codegen the declaration from some existing
+ // prototype.
+ auto FI = FunctionProtos.find(Name);
+ if (FI != FunctionProtos.end())
+ return FI->second->codegen();
+
+ // If no existing prototype exists, return null.
+ return nullptr;
+}
+
+/// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
+/// the function. This is used for mutable variables etc.
+static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
+ const std::string &VarName) {
+ IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
+ TheFunction->getEntryBlock().begin());
+ return TmpB.CreateAlloca(Type::getDoubleTy(TheContext), nullptr,
+ VarName.c_str());
+}
+
+Value *NumberExprAST::codegen() {
+ KSDbgInfo.emitLocation(this);
+ return ConstantFP::get(TheContext, APFloat(Val));
+}
+
+Value *VariableExprAST::codegen() {
+ // Look this variable up in the function.
+ Value *V = NamedValues[Name];
+ if (!V)
+ return LogErrorV("Unknown variable name");
+
+ KSDbgInfo.emitLocation(this);
+ // Load the value.
+ return Builder.CreateLoad(V, Name.c_str());
+}
+
+Value *UnaryExprAST::codegen() {
+ Value *OperandV = Operand->codegen();
+ if (!OperandV)
+ return nullptr;
+
+ Function *F = getFunction(std::string("unary") + Opcode);
+ if (!F)
+ return LogErrorV("Unknown unary operator");
+
+ KSDbgInfo.emitLocation(this);
+ return Builder.CreateCall(F, OperandV, "unop");
+}
+
+Value *BinaryExprAST::codegen() {
+ KSDbgInfo.emitLocation(this);
+
+ // Special case '=' because we don't want to emit the LHS as an expression.
+ if (Op == '=') {
+ // Assignment requires the LHS to be an identifier.
+ // This assume we're building without RTTI because LLVM builds that way by
+ // default. If you build LLVM with RTTI this can be changed to a
+ // dynamic_cast for automatic error checking.
+ VariableExprAST *LHSE = static_cast<VariableExprAST *>(LHS.get());
+ if (!LHSE)
+ return LogErrorV("destination of '=' must be a variable");
+ // Codegen the RHS.
+ Value *Val = RHS->codegen();
+ if (!Val)
+ return nullptr;
+
+ // Look up the name.
+ Value *Variable = NamedValues[LHSE->getName()];
+ if (!Variable)
+ return LogErrorV("Unknown variable name");
+
+ Builder.CreateStore(Val, Variable);
+ return Val;
+ }
+
+ Value *L = LHS->codegen();
+ Value *R = RHS->codegen();
+ if (!L || !R)
+ return nullptr;
+
+ switch (Op) {
+ case '+':
+ return Builder.CreateFAdd(L, R, "addtmp");
+ case '-':
+ return Builder.CreateFSub(L, R, "subtmp");
+ case '*':
+ return Builder.CreateFMul(L, R, "multmp");
+ case '<':
+ L = Builder.CreateFCmpULT(L, R, "cmptmp");
+ // Convert bool 0/1 to double 0.0 or 1.0
+ return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext), "booltmp");
+ default:
+ break;
+ }
+
+ // If it wasn't a builtin binary operator, it must be a user defined one. Emit
+ // a call to it.
+ Function *F = getFunction(std::string("binary") + Op);
+ assert(F && "binary operator not found!");
+
+ Value *Ops[] = {L, R};
+ return Builder.CreateCall(F, Ops, "binop");
+}
+
+Value *CallExprAST::codegen() {
+ KSDbgInfo.emitLocation(this);
+
+ // Look up the name in the global module table.
+ Function *CalleeF = getFunction(Callee);
+ if (!CalleeF)
+ return LogErrorV("Unknown function referenced");
+
+ // If argument mismatch error.
+ if (CalleeF->arg_size() != Args.size())
+ return LogErrorV("Incorrect # arguments passed");
+
+ std::vector<Value *> ArgsV;
+ for (unsigned i = 0, e = Args.size(); i != e; ++i) {
+ ArgsV.push_back(Args[i]->codegen());
+ if (!ArgsV.back())
+ return nullptr;
+ }
+
+ return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
+}
+
+Value *IfExprAST::codegen() {
+ KSDbgInfo.emitLocation(this);
+
+ Value *CondV = Cond->codegen();
+ if (!CondV)
+ return nullptr;
+
+ // Convert condition to a bool by comparing equal to 0.0.
+ CondV = Builder.CreateFCmpONE(
+ CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
+
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Create blocks for the then and else cases. Insert the 'then' block at the
+ // end of the function.
+ BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
+ BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
+ BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
+
+ Builder.CreateCondBr(CondV, ThenBB, ElseBB);
+
+ // Emit then value.
+ Builder.SetInsertPoint(ThenBB);
+
+ Value *ThenV = Then->codegen();
+ if (!ThenV)
+ return nullptr;
+
+ Builder.CreateBr(MergeBB);
+ // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
+ ThenBB = Builder.GetInsertBlock();
+
+ // Emit else block.
+ TheFunction->getBasicBlockList().push_back(ElseBB);
+ Builder.SetInsertPoint(ElseBB);
+
+ Value *ElseV = Else->codegen();
+ if (!ElseV)
+ return nullptr;
+
+ Builder.CreateBr(MergeBB);
+ // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
+ ElseBB = Builder.GetInsertBlock();
+
+ // Emit merge block.
+ TheFunction->getBasicBlockList().push_back(MergeBB);
+ Builder.SetInsertPoint(MergeBB);
+ PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
+
+ PN->addIncoming(ThenV, ThenBB);
+ PN->addIncoming(ElseV, ElseBB);
+ return PN;
+}
+
+// Output for-loop as:
+// var = alloca double
+// ...
+// start = startexpr
+// store start -> var
+// goto loop
+// loop:
+// ...
+// bodyexpr
+// ...
+// loopend:
+// step = stepexpr
+// endcond = endexpr
+//
+// curvar = load var
+// nextvar = curvar + step
+// store nextvar -> var
+// br endcond, loop, endloop
+// outloop:
+Value *ForExprAST::codegen() {
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Create an alloca for the variable in the entry block.
+ AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
+
+ KSDbgInfo.emitLocation(this);
+
+ // Emit the start code first, without 'variable' in scope.
+ Value *StartVal = Start->codegen();
+ if (!StartVal)
+ return nullptr;
+
+ // Store the value into the alloca.
+ Builder.CreateStore(StartVal, Alloca);
+
+ // Make the new basic block for the loop header, inserting after current
+ // block.
+ BasicBlock *LoopBB = BasicBlock::Create(TheContext, "loop", TheFunction);
+
+ // Insert an explicit fall through from the current block to the LoopBB.
+ Builder.CreateBr(LoopBB);
+
+ // Start insertion in LoopBB.
+ Builder.SetInsertPoint(LoopBB);
+
+ // Within the loop, the variable is defined equal to the PHI node. If it
+ // shadows an existing variable, we have to restore it, so save it now.
+ AllocaInst *OldVal = NamedValues[VarName];
+ NamedValues[VarName] = Alloca;
+
+ // Emit the body of the loop. This, like any other expr, can change the
+ // current BB. Note that we ignore the value computed by the body, but don't
+ // allow an error.
+ if (!Body->codegen())
+ return nullptr;
+
+ // Emit the step value.
+ Value *StepVal = nullptr;
+ if (Step) {
+ StepVal = Step->codegen();
+ if (!StepVal)
+ return nullptr;
+ } else {
+ // If not specified, use 1.0.
+ StepVal = ConstantFP::get(TheContext, APFloat(1.0));
+ }
+
+ // Compute the end condition.
+ Value *EndCond = End->codegen();
+ if (!EndCond)
+ return nullptr;
+
+ // Reload, increment, and restore the alloca. This handles the case where
+ // the body of the loop mutates the variable.
+ Value *CurVar = Builder.CreateLoad(Alloca, VarName.c_str());
+ Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
+ Builder.CreateStore(NextVar, Alloca);
+
+ // Convert condition to a bool by comparing equal to 0.0.
+ EndCond = Builder.CreateFCmpONE(
+ EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
+
+ // Create the "after loop" block and insert it.
+ BasicBlock *AfterBB =
+ BasicBlock::Create(TheContext, "afterloop", TheFunction);
+
+ // Insert the conditional branch into the end of LoopEndBB.
+ Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
+
+ // Any new code will be inserted in AfterBB.
+ Builder.SetInsertPoint(AfterBB);
+
+ // Restore the unshadowed variable.
+ if (OldVal)
+ NamedValues[VarName] = OldVal;
+ else
+ NamedValues.erase(VarName);
+
+ // for expr always returns 0.0.
+ return Constant::getNullValue(Type::getDoubleTy(TheContext));
+}
+
+Value *VarExprAST::codegen() {
+ std::vector<AllocaInst *> OldBindings;
+
+ Function *TheFunction = Builder.GetInsertBlock()->getParent();
+
+ // Register all variables and emit their initializer.
+ for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
+ const std::string &VarName = VarNames[i].first;
+ ExprAST *Init = VarNames[i].second.get();
+
+ // Emit the initializer before adding the variable to scope, this prevents
+ // the initializer from referencing the variable itself, and permits stuff
+ // like this:
+ // var a = 1 in
+ // var a = a in ... # refers to outer 'a'.
+ Value *InitVal;
+ if (Init) {
+ InitVal = Init->codegen();
+ if (!InitVal)
+ return nullptr;
+ } else { // If not specified, use 0.0.
+ InitVal = ConstantFP::get(TheContext, APFloat(0.0));
+ }
+
+ AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
+ Builder.CreateStore(InitVal, Alloca);
+
+ // Remember the old variable binding so that we can restore the binding when
+ // we unrecurse.
+ OldBindings.push_back(NamedValues[VarName]);
+
+ // Remember this binding.
+ NamedValues[VarName] = Alloca;
+ }
+
+ KSDbgInfo.emitLocation(this);
+
+ // Codegen the body, now that all vars are in scope.
+ Value *BodyVal = Body->codegen();
+ if (!BodyVal)
+ return nullptr;
+
+ // Pop all our variables from scope.
+ for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
+ NamedValues[VarNames[i].first] = OldBindings[i];
+
+ // Return the body computation.
+ return BodyVal;
+}
+
+Function *PrototypeAST::codegen() {
+ // Make the function type: double(double,double) etc.
+ std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
+ FunctionType *FT =
+ FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
+
+ Function *F =
+ Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
+
+ // Set names for all arguments.
+ unsigned Idx = 0;
+ for (auto &Arg : F->args())
+ Arg.setName(Args[Idx++]);
+
+ return F;
+}
+
+Function *FunctionAST::codegen() {
+ // Transfer ownership of the prototype to the FunctionProtos map, but keep a
+ // reference to it for use below.
+ auto &P = *Proto;
+ FunctionProtos[Proto->getName()] = std::move(Proto);
+ Function *TheFunction = getFunction(P.getName());
+ if (!TheFunction)
+ return nullptr;
+
+ // If this is an operator, install it.
+ if (P.isBinaryOp())
+ BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
+
+ // Create a new basic block to start insertion into.
+ BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
+ Builder.SetInsertPoint(BB);
+
+ // Create a subprogram DIE for this function.
+ DIFile *Unit = DBuilder->createFile(KSDbgInfo.TheCU->getFilename(),
+ KSDbgInfo.TheCU->getDirectory());
+ DIScope *FContext = Unit;
+ unsigned LineNo = P.getLine();
+ unsigned ScopeLine = LineNo;
+ DISubprogram *SP = DBuilder->createFunction(
+ FContext, P.getName(), StringRef(), Unit, LineNo,
+ CreateFunctionType(TheFunction->arg_size(), Unit),
+ false /* internal linkage */, true /* definition */, ScopeLine,
+ DINode::FlagPrototyped, false);
+ TheFunction->setSubprogram(SP);
+
+ // Push the current scope.
+ KSDbgInfo.LexicalBlocks.push_back(SP);
+
+ // Unset the location for the prologue emission (leading instructions with no
+ // location in a function are considered part of the prologue and the debugger
+ // will run past them when breaking on a function)
+ KSDbgInfo.emitLocation(nullptr);
+
+ // Record the function arguments in the NamedValues map.
+ NamedValues.clear();
+ unsigned ArgIdx = 0;
+ for (auto &Arg : TheFunction->args()) {
+ // Create an alloca for this variable.
+ AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());
+
+ // Create a debug descriptor for the variable.
+ DILocalVariable *D = DBuilder->createParameterVariable(
+ SP, Arg.getName(), ++ArgIdx, Unit, LineNo, KSDbgInfo.getDoubleTy(),
+ true);
+
+ DBuilder->insertDeclare(Alloca, D, DBuilder->createExpression(),
+ DebugLoc::get(LineNo, 0, SP),
+ Builder.GetInsertBlock());
+
+ // Store the initial value into the alloca.
+ Builder.CreateStore(&Arg, Alloca);
+
+ // Add arguments to variable symbol table.
+ NamedValues[Arg.getName()] = Alloca;
+ }
+
+ KSDbgInfo.emitLocation(Body.get());
+
+ if (Value *RetVal = Body->codegen()) {
+ // Finish off the function.
+ Builder.CreateRet(RetVal);
+
+ // Pop off the lexical block for the function.
+ KSDbgInfo.LexicalBlocks.pop_back();
+
+ // Validate the generated code, checking for consistency.
+ verifyFunction(*TheFunction);
+
+ return TheFunction;
+ }
+
+ // Error reading body, remove function.
+ TheFunction->eraseFromParent();
+
+ if (P.isBinaryOp())
+ BinopPrecedence.erase(Proto->getOperatorName());
+
+ // Pop off the lexical block for the function since we added it
+ // unconditionally.
+ KSDbgInfo.LexicalBlocks.pop_back();
+
+ return nullptr;
+}
+
+//===----------------------------------------------------------------------===//
+// Top-Level parsing and JIT Driver
+//===----------------------------------------------------------------------===//
+
+static void InitializeModule() {
+ // Open a new module.
+ TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
+ TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
+}
+
+static void HandleDefinition() {
+ if (auto FnAST = ParseDefinition()) {
+ if (!FnAST->codegen())
+ fprintf(stderr, "Error reading function definition:");
+ } else {
+ // Skip token for error recovery.
+ getNextToken();
+ }
+}
+
+static void HandleExtern() {
+ if (auto ProtoAST = ParseExtern()) {
+ if (!ProtoAST->codegen())
+ fprintf(stderr, "Error reading extern");
+ else
+ FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
+ } else {
+ // Skip token for error recovery.
+ getNextToken();
+ }
+}
+
+static void HandleTopLevelExpression() {
+ // Evaluate a top-level expression into an anonymous function.
+ if (auto FnAST = ParseTopLevelExpr()) {
+ if (!FnAST->codegen()) {
+ fprintf(stderr, "Error generating code for top level expr");
+ }
+ } else {
+ // Skip token for error recovery.
+ getNextToken();
+ }
+}
+
+/// top ::= definition | external | expression | ';'
+static void MainLoop() {
+ while (1) {
+ switch (CurTok) {
+ case tok_eof:
+ return;
+ case ';': // ignore top-level semicolons.
+ getNextToken();
+ break;
+ case tok_def:
+ HandleDefinition();
+ break;
+ case tok_extern:
+ HandleExtern();
+ break;
+ default:
+ HandleTopLevelExpression();
+ break;
+ }
+ }
+}
+
+//===----------------------------------------------------------------------===//
+// "Library" functions that can be "extern'd" from user code.
+//===----------------------------------------------------------------------===//
+
+/// putchard - putchar that takes a double and returns 0.
+extern "C" double putchard(double X) {
+ fputc((char)X, stderr);
+ return 0;
+}
+
+/// printd - printf that takes a double prints it as "%f\n", returning 0.
+extern "C" double printd(double X) {
+ fprintf(stderr, "%f\n", X);
+ return 0;
+}
+
+//===----------------------------------------------------------------------===//
+// Main driver code.
+//===----------------------------------------------------------------------===//
+
+int main() {
+ InitializeNativeTarget();
+ InitializeNativeTargetAsmPrinter();
+ InitializeNativeTargetAsmParser();
+
+ // Install standard binary operators.
+ // 1 is lowest precedence.
+ BinopPrecedence['='] = 2;
+ BinopPrecedence['<'] = 10;
+ BinopPrecedence['+'] = 20;
+ BinopPrecedence['-'] = 20;
+ BinopPrecedence['*'] = 40; // highest.
+
+ // Prime the first token.
+ getNextToken();
+
+ TheJIT = llvm::make_unique<KaleidoscopeJIT>();
+
+ InitializeModule();
+
+ // Add the current debug info version into the module.
+ TheModule->addModuleFlag(Module::Warning, "Debug Info Version",
+ DEBUG_METADATA_VERSION);
+
+ // Darwin only supports dwarf2.
+ if (Triple(sys::getProcessTriple()).isOSDarwin())
+ TheModule->addModuleFlag(llvm::Module::Warning, "Dwarf Version", 2);
+
+ // Construct the DIBuilder, we do this here because we need the module.
+ DBuilder = llvm::make_unique<DIBuilder>(*TheModule);
+
+ // Create the compile unit for the module.
+ // Currently down as "fib.ks" as a filename since we're redirecting stdin
+ // but we'd like actual source locations.
+ KSDbgInfo.TheCU = DBuilder->createCompileUnit(
+ dwarf::DW_LANG_C, "fib.ks", ".", "Kaleidoscope Compiler", 0, "", 0);
+
+ // Run the main "interpreter loop" now.
+ MainLoop();
+
+ // Finalize the debug info.
+ DBuilder->finalize();
+
+ // Print out all of the generated code.
+ TheModule->dump();
+
+ return 0;
+}
More information about the llvm-commits
mailing list