Start writing actual compillation code in compiler series

code/compiler/07/runtime.h

@@ -55,6 +55,7 @@ struct stack {
     struct node_base** data;
 };
 
+void stack_init(struct stack* s);
 void stack_free(struct stack* s);
 void stack_push(struct stack* s, struct node_base* n);
 struct node_base* stack_pop(struct stack* s);

code/compiler/08/CMakeLists.txt

@@ -22,6 +22,7 @@ llvm_map_components_to_libnames(LLVM_LIBS core x86asmparser x86codegen)
 # Create compiler executable
 add_executable(compiler
     ast.cpp ast.hpp definition.cpp
+    llvm_context.cpp llvm_context.hpp
     type_env.cpp type_env.hpp
     env.cpp env.hpp
     type.cpp type.hpp

code/compiler/08/ast.cpp

@@ -206,7 +206,8 @@ void ast_case::compile(const env_ptr& env, std::vector<instruction_ptr>& into) c
                 new_env = env_ptr(new env_var(*it, new_env));
             }
 
-            branch_instructions.push_back(instruction_ptr(new instruction_split()));
+            branch_instructions.push_back(instruction_ptr(new instruction_split(
+                            cpat->params.size())));
             branch->expr->compile(new_env, branch_instructions);
             branch_instructions.push_back(instruction_ptr(new instruction_slide(
                             cpat->params.size())));

code/compiler/08/instruction.cpp

@@ -1,4 +1,8 @@
 #include "instruction.hpp"
+#include "llvm_context.hpp"
+#include <llvm/IR/Function.h>
+
+using namespace llvm;
 
 static void print_indent(int n, std::ostream& to) {
     while(n--) to << "  ";
@@ -9,36 +13,66 @@ void instruction_pushint::print(int indent, std::ostream& to) const {
     to << "PushInt(" << value << ")" << std::endl;
 }
 
+void instruction_pushint::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_push(f, ctx.create_num(ctx.create_i32(value)));
+}
+
 void instruction_pushglobal::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "PushGlobal(" << name << ")" << std::endl;
 }
 
+void instruction_pushglobal::gen_llvm(llvm_context& ctx, Function* f) const {
+    // TODO
+}
+
 void instruction_push::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Push(" << offset << ")" << std::endl;
 }
 
+void instruction_push::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_push(f, ctx.create_peek(f, ctx.create_size(offset)));
+}
+
 void instruction_mkapp::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "MkApp()" << std::endl;
 }
 
+void instruction_mkapp::gen_llvm(llvm_context& ctx, Function* f) const {
+    auto left = ctx.create_pop(f);
+    auto right = ctx.create_pop(f);
+    ctx.create_push(f, ctx.create_app(left, right));
+}
+
 void instruction_update::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Update(" << offset << ")" << std::endl;
 }
 
+void instruction_update::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_update(f, ctx.create_size(offset));
+}
+
 void instruction_pack::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Pack(" << tag << ", " << size << ")" << std::endl;
 }
 
+void instruction_pack::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_pack(f, ctx.create_size(size), ctx.create_i8(tag));
+}
+
 void instruction_split::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Split()" << std::endl;
 }
 
+void instruction_split::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_split(f, ctx.create_size(size));
+}
+
 void instruction_jump::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Jump(" << std::endl;
@@ -52,27 +86,60 @@ void instruction_jump::print(int indent, std::ostream& to) const {
     to << ")" << std::endl;
 }
 
+void instruction_jump::gen_llvm(llvm_context& ctx, Function* f) const {
+    // TODO
+}
+
 void instruction_slide::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Slide(" << offset << ")" << std::endl;
 }
 
+void instruction_slide::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_slide(f, ctx.create_size(offset));
+}
+
 void instruction_binop::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "BinOp(" << op_action(op) << ")" << std::endl;
 }
 
+void instruction_binop::gen_llvm(llvm_context& ctx, Function* f) const {
+    auto left_int = ctx.unwrap_num(ctx.create_pop(f));
+    auto right_int = ctx.unwrap_num(ctx.create_pop(f));
+    llvm::Value* result;
+    switch(op) {
+        case PLUS: result = ctx.builder.CreateAdd(left_int, right_int); break;
+        case MINUS: result = ctx.builder.CreateSub(left_int, right_int); break;
+        case TIMES: result = ctx.builder.CreateMul(left_int, right_int); break;
+        case DIVIDE: result = ctx.builder.CreateSDiv(left_int, right_int); break;
+    }
+    ctx.create_push(f, ctx.create_num(result));
+}
+
 void instruction_eval::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Eval()" << std::endl;
 }
 
+void instruction_eval::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_push(f, ctx.create_eval(ctx.create_pop(f)));
+}
+
 void instruction_alloc::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Alloc(" << amount << ")" << std::endl;
 }
 
+void instruction_alloc::gen_llvm(llvm_context& ctx, Function* f) const {
+    ctx.create_alloc(f, ctx.create_size(amount));
+}
+
 void instruction_unwind::print(int indent, std::ostream& to) const {
     print_indent(indent, to);
     to << "Unwind()" << std::endl;
 }
+
+void instruction_unwind::gen_llvm(llvm_context& ctx, Function* f) const {
+    // Nothing
+}

code/compiler/08/instruction.hpp

@@ -1,15 +1,18 @@
 #pragma once
+#include <llvm/IR/Function.h>
 #include <string>
 #include <memory>
 #include <vector>
 #include <map>
 #include <ostream>
 #include "binop.hpp"
+#include "llvm_context.hpp"
 
 struct instruction {
     virtual ~instruction() = default;
 
     virtual void print(int indent, std::ostream& to) const = 0;
+    virtual void gen_llvm(llvm_context& ctx, llvm::Function* f) const = 0;
 };
 
 using instruction_ptr = std::unique_ptr<instruction>;
@@ -21,6 +24,7 @@ struct instruction_pushint : public instruction {
         : value(v) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_pushglobal : public instruction {
@@ -30,6 +34,7 @@ struct instruction_pushglobal : public instruction {
         : name(std::move(n)) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_push : public instruction {
@@ -39,10 +44,12 @@ struct instruction_push : public instruction {
         : offset(o) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_mkapp : public instruction {
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_update : public instruction {
@@ -52,6 +59,7 @@ struct instruction_update : public instruction {
         : offset(o) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_pack : public instruction {
@@ -62,10 +70,17 @@ struct instruction_pack : public instruction {
         : tag(t), size(s) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_split : public instruction {
+    int size;
+
+    instruction_split(int s)
+        : size(s) {}
+
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_jump : public instruction {
@@ -73,6 +88,7 @@ struct instruction_jump : public instruction {
     std::map<int, int> tag_mappings;
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_slide : public instruction {
@@ -82,6 +98,7 @@ struct instruction_slide : public instruction {
         : offset(o) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_binop : public instruction {
@@ -91,10 +108,12 @@ struct instruction_binop : public instruction {
         : op(o) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_eval : public instruction {
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_alloc : public instruction {
@@ -104,8 +123,10 @@ struct instruction_alloc : public instruction {
         : amount(a) {}
 
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };
 
 struct instruction_unwind : public instruction {
     void print(int indent, std::ostream& to) const;
+    void gen_llvm(llvm_context& ctx, llvm::Function* f) const;
 };

code/compiler/08/llvm_context.cpp

@@ -1,18 +1,223 @@
 #include "llvm_context.hpp"
 #include <llvm/IR/DerivedTypes.h>
 
-void llvm_state::create_types() {
-    stack_type = llvm::StructType::create(ctx, "stack");
-    tag_type = llvm::IntegerType::getInt8Ty(ctx);
-    struct_types["node_base"] = llvm::StructType::create(ctx, "node_base");
-    struct_types["node_app"] = llvm::StructType::create(ctx, "node_app");
-    struct_types["node_num"] = llvm::StructType::create(ctx, "node_num");
-    struct_types["node_global"] = llvm::StructType::create(ctx, "node_global");
-    struct_types["node_ind"] = llvm::StructType::create(ctx, "node_ind");
-    struct_types["node_data"] = llvm::StructType::create(ctx, "node_data");
-    node_ptr_type = llvm::PointerType::getUnqual(struct_types.at("node_base"));
+using namespace llvm;
+
+void llvm_context::create_types() {
+    stack_type = StructType::create(ctx, "stack");
+    stack_ptr_type = PointerType::getUnqual(stack_type);
+    tag_type = IntegerType::getInt8Ty(ctx);
+    struct_types["node_base"] = StructType::create(ctx, "node_base");
+    struct_types["node_app"] = StructType::create(ctx, "node_app");
+    struct_types["node_num"] = StructType::create(ctx, "node_num");
+    struct_types["node_global"] = StructType::create(ctx, "node_global");
+    struct_types["node_ind"] = StructType::create(ctx, "node_ind");
+    struct_types["node_data"] = StructType::create(ctx, "node_data");
+    node_ptr_type = PointerType::getUnqual(struct_types.at("node_base"));
+    function_type = FunctionType::get(Type::getVoidTy(ctx), { stack_ptr_type }, false);
+
+    struct_types.at("node_base")->setBody(
+            IntegerType::getInt32Ty(ctx)
+    );
+    struct_types.at("node_app")->setBody(
+            struct_types.at("node_base"),
+            node_ptr_type,
+            node_ptr_type
+    );
+    struct_types.at("node_num")->setBody(
+            struct_types.at("node_base"),
+            IntegerType::getInt32Ty(ctx)
+    );
+    struct_types.at("node_global")->setBody(
+            struct_types.at("node_base"),
+            FunctionType::get(Type::getVoidTy(ctx), { stack_ptr_type }, false)
+    );
+    struct_types.at("node_ind")->setBody(
+            struct_types.at("node_base"),
+            node_ptr_type
+    );
+    struct_types.at("node_data")->setBody(
+            struct_types.at("node_base"),
+            IntegerType::getInt8Ty(ctx),
+            PointerType::getUnqual(node_ptr_type)
+    );
 }
 
-void llvm_state::create_functions() {
+void llvm_context::create_functions() {
+    auto void_type = Type::getVoidTy(ctx);
+    auto sizet_type = IntegerType::get(ctx, sizeof(size_t) * 8);
+    functions["stack_init"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_init",
+            &module
+    );
+    functions["stack_free"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_free",
+            &module
+    );
+    functions["stack_push"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, node_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_pop"] = Function::Create(
+            FunctionType::get(node_ptr_type, { stack_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_peek"] = Function::Create(
+            FunctionType::get(node_ptr_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_popn"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_slide"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_update"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_alloc"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_pack"] = Function::Create(
+            FunctionType::get(void_type, { stack_ptr_type, sizet_type, tag_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
+    functions["stack_split"] = Function::Create(
+            FunctionType::get(node_ptr_type, { stack_ptr_type, sizet_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "stack_push",
+            &module
+    );
 
+    auto int32_type = IntegerType::getInt32Ty(ctx);
+    functions["alloc_app"] = Function::Create(
+            FunctionType::get(node_ptr_type, { node_ptr_type, node_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "alloc_app",
+            &module
+    );
+    functions["alloc_num"] = Function::Create(
+            FunctionType::get(node_ptr_type, { int32_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "alloc_num",
+            &module
+    );
+    functions["alloc_global"] = Function::Create(
+            FunctionType::get(node_ptr_type, { function_type, int32_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "alloc_global",
+            &module
+    );
+    functions["alloc_ind"] = Function::Create(
+            FunctionType::get(node_ptr_type, { node_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "alloc_ind",
+            &module
+    );
+
+    functions["eval"] = Function::Create(
+            FunctionType::get(node_ptr_type, { node_ptr_type }, false),
+            Function::LinkageTypes::ExternalLinkage,
+            "eval",
+            &module
+    );
+}
+
+Value* llvm_context::create_i8(int8_t i) {
+    return ConstantInt::get(ctx, APInt(8, i));
+}
+Value* llvm_context::create_i32(int32_t i) {
+    return ConstantInt::get(ctx, APInt(32, i));
+}
+Value* llvm_context::create_size(size_t i) {
+    return ConstantInt::get(ctx, APInt(sizeof(size_t) * 8, i));
+}
+
+Value* llvm_context::create_pop(Function* f) {
+    auto pop_f = functions.at("stack_pop");
+    return builder.CreateCall(pop_f, { f->arg_begin() });
+}
+Value* llvm_context::create_peek(Function* f, Value* off) {
+    auto peek_f = functions.at("stack_peek");
+    return builder.CreateCall(peek_f, { f->arg_begin(), off });
+}
+void llvm_context::create_push(Function* f, Value* v) {
+    auto push_f = functions.at("stack_push");
+    builder.CreateCall(push_f, { f->arg_begin(), v });
+}
+void llvm_context::create_popn(Function* f, Value* off) {
+    auto popn_f = functions.at("stack_popn");
+    builder.CreateCall(popn_f, { f->arg_begin(), off });
+}
+void llvm_context::create_update(Function* f, Value* off) {
+    auto update_f = functions.at("stack_update");
+    builder.CreateCall(update_f, { f->arg_begin(), off });
+}
+void llvm_context::create_pack(Function* f, Value* c, Value* t) {
+    auto pack_f = functions.at("stack_pack");
+    builder.CreateCall(pack_f, { f->arg_begin(), c, t });
+}
+void llvm_context::create_split(Function* f, Value* c) {
+    auto split_f = functions.at("stack_split");
+    builder.CreateCall(split_f, { f->arg_begin(), c });
+}
+void llvm_context::create_slide(Function* f, Value* off) {
+    auto slide_f = functions.at("stack_slide");
+    builder.CreateCall(slide_f, { f->arg_begin(), off });
+}
+void llvm_context::create_alloc(Function* f, Value* n) {
+    auto alloc_f = functions.at("stack_alloc");
+    builder.CreateCall(alloc_f, { f->arg_begin(), n });
+}
+
+Value* llvm_context::create_eval(Value* e) {
+    auto eval_f = functions.at("eval");
+    return builder.CreateCall(eval_f, { e });
+}
+
+Value* llvm_context::unwrap_num(Value* v) {
+    auto num_ptr_type = PointerType::getUnqual(struct_types.at("node_num"));
+    auto cast = builder.CreatePointerCast(v, num_ptr_type);
+    auto offset_0 = create_size(0);
+    auto offset_1 = create_size(1);
+    auto int_ptr = builder.CreateGEP(cast, { offset_0, offset_1 });
+    return builder.CreateLoad(int_ptr);
+}
+Value* llvm_context::create_num(Value* v) {
+    auto alloc_num_f = functions.at("alloc_num");
+    return builder.CreateCall(alloc_num_f, { v });
+}
+
+Value* llvm_context::create_global(Value* f, Value* a) {
+    auto alloc_global_f = functions.at("alloc_global");
+    return builder.CreateCall(alloc_global_f, { f, a });
+}
+
+Value* llvm_context::create_app(Value* l, Value* r) {
+    auto alloc_app_f = functions.at("alloc_app");
+    return builder.CreateCall(alloc_app_f, { l, r });
 }

code/compiler/08/llvm_context.hpp

@@ -6,7 +6,7 @@
 #include <llvm/IR/Module.h>
 #include <map>
 
-struct llvm_state {
+struct llvm_context {
     llvm::LLVMContext ctx;
     llvm::IRBuilder<> builder;
     llvm::Module module;
@@ -15,10 +15,12 @@ struct llvm_state {
     std::map<std::string, llvm::StructType*> struct_types;
 
     llvm::StructType* stack_type;
+    llvm::PointerType* stack_ptr_type;
     llvm::PointerType* node_ptr_type;
     llvm::IntegerType* tag_type;
+    llvm::FunctionType* function_type;
 
-    llvm_state()
+    llvm_context()
         : builder(ctx), module("bloglang", ctx) {
         create_types();
         create_functions();
@@ -26,4 +28,27 @@ struct llvm_state {
 
     void create_types();
     void create_functions();
+
+    llvm::Value* create_i8(int8_t);
+    llvm::Value* create_i32(int32_t);
+    llvm::Value* create_size(size_t);
+
+    llvm::Value* create_pop(llvm::Function*);
+    llvm::Value* create_peek(llvm::Function*, llvm::Value*);
+    void create_push(llvm::Function*, llvm::Value*);
+    void create_popn(llvm::Function*, llvm::Value*);
+    void create_update(llvm::Function*, llvm::Value*);
+    void create_pack(llvm::Function*, llvm::Value*, llvm::Value*);
+    void create_split(llvm::Function*, llvm::Value*);
+    void create_slide(llvm::Function*, llvm::Value*);
+    void create_alloc(llvm::Function*, llvm::Value*);
+
+    llvm::Value* create_eval(llvm::Value*);
+
+    llvm::Value* unwrap_num(llvm::Value*);
+    llvm::Value* create_num(llvm::Value*);
+
+    llvm::Value* create_global(llvm::Value*, llvm::Value*);
+
+    llvm::Value* create_app(llvm::Value*, llvm::Value*);
 };

code/compiler/08/runtime.h

@@ -55,6 +55,7 @@ struct stack {
     struct node_base** data;
 };
 
+void stack_init(struct stack* s);
 void stack_free(struct stack* s);
 void stack_push(struct stack* s, struct node_base* n);
 struct node_base* stack_pop(struct stack* s);

content/blog/07_compiler_runtime.md

@@ -91,7 +91,7 @@ which we will use for lazy evaluation (modifying expressions with their reduced
 * `stack_pack` and `stack_split` - Wrap and unwrap constructors on the stack.
 
 We declare these in a header:
-{{< codelines "C" "compiler/07/runtime.h" 52 67 >}}
+{{< codelines "C" "compiler/07/runtime.h" 52 68 >}}
 
 And implement them as follows:
 {{< codelines "C" "compiler/07/runtime.c" 42 116 >}}

content/blog/08_compiler_llvm.md

@@ -50,4 +50,140 @@ Additionally, we want an `IRBuilder`, which will help us generate IR instruction
 placing them into basic blocks (more on that in a bit). Also, we want
 a `Module` object, which represents some collection of code and declarations
 (perhaps like a C++ source file). Let's keep these things in our own
-`llvm_state` class.
+`llvm_context` class. Here's what that looks like:
+
+{{< codeblock "C++" "compiler/08/llvm_context.hpp" >}}
+
+{{< todo >}} Consistently name context / state.{{< /todo >}}
+{{< todo >}} Explain creation functions. {{< /todo >}}
+
+We include the LLVM context, builder, and module as members
+of the context struct. Since the builder and the module need
+the context, we initialize them in the constructor, where they
+can safely reference it.
+
+Besides these fields, we added
+a few others, namely the `functions` and `struct_types` maps,
+and the various `llvm::Type` subclasses such as `stack_type`.
+We did this because we want to be able to call our runtime
+functions (and use our runtime structs) from LLVM. To generate
+a function call from LLVM, we need to have access to an
+`llvm::Function` object. We thus want to have an `llvm::Function`
+object for each runtime function we want to call. We could declare
+a member variable in our `llvm_context` for each runtime function,
+but it's easier to leave this to be an implementation
+detail, and only have a dynamically created map between runtime
+function names and their corresponding `llvm::Function` objects.
+
+We populate the maps and other type-related variables in the
+two methods, `create_functions()` and `create_types()`. To
+create an `llvm::Function`, we must provide an `llvm::FunctionType`,
+an `llvm::LinkageType`, the name of the function, and the module
+in which the function is declared. Since we only have one
+module (the one we initialized in the constructor) that's
+the module we pass in. The name of the function is the same
+as its name in the runtime, and the linkage type is always
+external. The only remaining parameter is
+the `llvm::FunctionType`, which is created using code like:
+
+{{< todo >}} Why external? {{< /todo >}}
+
+```C++
+llvm::FunctionType::get(return_type, {param_type_1, param_type_2, ...}, is_variadic)
+```
+
+Declaring all the functions and types in our runtime is mostly
+just tedious. Here are a few lines from `create_types()`, from
+which you can extrapolate the rest:
+
+{{< codelines "C++" "compiler/08/llvm_context.cpp" 7 11 >}}
+
+{{< todo >}} Also show struct body setters. {{< /todo >}}
+
+Similarly, here are a few lines from `create_functions()`, which
+give a very good idea of the rest of that method:
+
+{{< codelines "C++" "compiler/08/llvm_context.cpp" 20 27 >}}
+
+This completes our implementation of the context.
+
+### LLVM IR
+It's now time to look at generating actual code for each G-machine instruction.
+Before we do this, we need to get a little bit of an understanding of what LLVM
+IR is like. An important property of LLVM IR is that it is in __Single Static Assignment__
+(SSA) form. This means that each variable can only be assigned to once. For instance,
+if we use `<-` to represent assignment, the following program is valid:
+
+```
+x <- 1
+y <- 2
+z <- x + y
+```
+
+However, the following program is __not__ valid:
+
+```
+x <- 1
+x <- x + 1
+```
+
+But what if we __do__ want to modify a variable `x`?
+We can declare another "version" of `x` every time we modify it.
+For instance, if we wanted to increment `x` twice, we'd do this:
+
+```
+x <- 1
+x1 <- x + 1
+x2 <- x1 + 1
+```
+
+In practice, LLVM's C++ API can take care of versioning variables on its own, by
+auto-incrementing numbers associated with each variable we use.
+
+We need not get too deep into the specifics of LLVM IR's textual
+representation, since we will largely be working with the C++
+API to interact with it. We do, however, need to understand one more
+concept from the world of compiler design: __basic blocks__. A basic
+block is a sequence of instructions that are guaranteed to be executed
+one after another. This means that a basic block cannot have
+an if/else, jump, or any other type of control flow anywhere
+except at the end. If control flow could appear inside the basic block,
+there would be opporunity for execution of some, but not all,
+instructions in the block, violating the definition. Every time
+we add an IR instruction in LLVM, we add it to a basic block.
+Writing control flow involves creating several blocks, with each
+block serving as the destination of a potential jump. We will
+see this used to compile the Jump instruction.
+
+### Generating LLVM
+Let's envision a `gen_llvm` method on the `instruction` struct.
+We need access to all the other functions from our runtime,
+such as `stack_init`, and functions from our program such
+as `f_custom_function`. Thus, we need access to our
+`llvm_context`. The current basic block is part
+of the builder, which is part of the context, so that's
+also taken care of. There's only one more thing that we will
+need, and that's access to the `llvm::Function` that's
+currently being compiled. To understand why, consider
+the signature of `f_main` from the previous post:
+
+```C
+void f_main(struct stack*);
+```
+
+The function takes a stack as a parameter. What if
+we want to try use this stack in a method call, like
+`stack_push(s, node)`? We need to have access to the
+LLVM representation of the stack parameter. The easiest
+way to do this is to use `llvm::Function::arg_begin()`,
+which gives the first argument of the function. We thus
+carry the function pointer throughout our code generation
+methods.
+
+With these things in mind, here's the signature for `gen_llvm`:
+
+```C++
+virtual void gen_llvm(llvm_context&, llvm::Function*) const;
+```
+
+{{< todo >}} Fix pointer type inconsistencies. {{< /todo >}}