+
+
+### CFG Generation
+
+During CFG generation, one piece of information we need to keep around is what
+the continuation of each basic block is. In the above example, the
+continuation of `foo` is `foo2` and the continuation of `foo2` is `foo3`.
+`foo4`, `foo5`, `foo6`, and `foo7` are at the maximum depth in this example, so
+when they're done, control is going to pass back to their parent's continuation.
+
+To give this information to each basic block, CFGs are generated
+breadth-first instead of depth-first
+(as indicated by the naming of the basic blocks in the diagram).
+That way, the continuation of any block is going to be either the block
+with the next ID or its parent's continuation. The "parent continuation" of the
+root level blocks is just `None`.
+
+Within each basic block of the CFG, we also perform a few local transformations.
+In particular, we use source-level type information to convert all operators
+to their typed versions. In Caiman, all basic operators must be implemented as
+external function calls on a particular target device. The default behavior
+is for operators to invoke functions on the local (aka host) device which will
+be defined in a standard library. The local/host device is the device that is
+running the Caiman program itself. The type information attached to the
+operators is used to determine the function to call. For example `true == false`
+will call `_eq_bool_bool(true, false)` while `1 == 2` will call
+`_eq_i64_i64(1, 2)`.
+
+We also need to convert the uses of variables to loads and stores
+of references. This means we might need to introduce load instructions that turn
+something like `return v` into `_v0 = load v; return _v0`. Right now, this
+dereference transformation is applied locally, but in the future, this might become
+a global transformation to reduce the amount of loads being inserted.
+
+### Funclet Arguments and Returns
+
+Once lowered into HIR, the next step is identifying the arguments and return
+values of each funclet. The way I chose to do this is via a live variables analysis.
+Any variable that is live into a basic block must necessarily be a funclet
+argument for that block. Consider this part of the example shown earlier:
+
+```
+// foo
+var r: bool @ none(main);
+if @ node(main.r) b {
+ // foo4
+ let c: bool @ node(main.c) = true;
+ r = c;
+} else {
+ // foo5
+ let d: bool @ node(main.d) = false;
+ r = d;
+}
+```
+
+`r` is a variable defined outside the blocks of `foo4` and `foo5`. Since `r`
+is live into `foo4` and `foo5`, it must be an argument to both.
+Now, at compile-time, it's not necessarily known whether `foo4` or `foo5` will
+be invoked. Therefore, the arguments of both blocks must be the same. In the
+assembly, the terminator of the `foo` block looks something like this:
+
+```
+schedule-select %b [%foo4, %foo5]
+ [value node($val.%r), timeline none($time.%none), spatial none($space.%none)]
+ (%r_loc) %foo2;
+```
+
+where `(%r_loc)` is the argument to the selected block and `%foo2` is the
+continuation.
+
+Therefore, the input arguments must be the set of all variables that are
+live-out of all predecessor blocks. For the first block of a function, then
+the inputs will be the same as the function inputs instead.
+
+What about the output values? It might seem logical to think that the output
+values are simply the live-out set of a given basic block (as I initially did),
+but consider the following pseudocode example:
+
+```
+// block1
+let b = // ...
+let cond = // ...
+var v;
+if cond {
+ // block3
+ v = b + 1;
+} else {
+ // block4
+ v = b * 2;
+}
+// block2
+// use v
+```
+
+`b` and `v` are live out of `block1`, however, only `v` is live into `block2`.
+If we think about what's actually happening here in CPS, we might have the following
+pseudocode
+
+```
+fn block1() {
+ %b = // ...
+ %v = // ...
+ select %b [%block3, %block4] (%b, %v) %block2
+}
+
+fn block3(%b, %v, %continuation) {
+ %v = %b + 1;
+ %continuation(%v);
+}
+
+fn block4(%b, %v, %continuation) {
+ %v = %b * 2;
+ %continuation(%v);
+}
+
+fn block2(%v) {
+ // use v
+}
+```
+
+Here we can see that the actual return value of `%block1` is just
+`%v`. More generally, a block's return values are the inputs to
+its continuation. For the last block in a function, then the
+outputs will be the outputs of the function instead.
+
+Luckily, we already know what the continuation of every block is because
+we determined this information when we generated the basic blocks from the
+source program.
+
+### Funclet Argument and Return Types
+
+Now that we determined what the funclet arguments and return values are, it
+should be easy to determine what a funclet's input and output types are, right?
+Well, not so much. Without diving into the details too much, the problem is that
+while the datatype of a variable won't change, the part of the type
+that is mapping a variable back to a specification and the part of the type
+that is tracking a linear resource *can* change. You can think of
+these parts of the type as being relative to the current funclet.
+
+The explicator (synthesizer) can determine all the types *within* a basic block.
+However, it's not guaranteed to solve the input and output types across a
+funclet boundary. In fact, nothing is. The general case is an undecidable problem.
+
+In the earlier schedule, we can see an example of how the types are changing:
+
+```
+var r: bool @ none(main)-dead;
+if @ node(main.r) b {
+ let c: bool @ node(main.c) = true;
+ r = c;
+} else {
+ let d: bool @ node(main.d) = false;
+ r = d;
+}
+@in { r: [node(main.r)-usable, none(space)-save] };
+```
+
+`r` starts as being an empty reference that doesn't map to anything in a
+specification (`none`) and can't be used (`dead`). During the assignments
+to `r` in either branch, `r` takes on the value type of what was
+assigned to it.
+In the true branch, `r` maps to `main.c` in the value specification,
+and in the false branch it maps to `main.d`. In both branches, `r` also becomes
+`usable`. Finally, at the join point of the two
+branches, `r` maps to `main.r`, which is a node in the value spec
+defined as the output of the conditional.
+
+While the explicator is currently a WIP, for now, I decided to reduce what
+needs to be specified by the user using a dataflow analysis. The above example
+is actually the reduced level of specification. Annotating every type fully
+would look like:
+
+```
+var r: bool @ [none(main)-dead, none(space)-save, none(time)-usable];
+if @ node(main.r) b {
+ let c: bool @
+ [node(main.c)-usable, none(space)-usable, none(time)-usable]
+ = true;
+ r @ [node(main.c)-usable, none(space)-save, none(time)-usable] = c;
+} else {
+ let d: bool @
+ [node(main.d)-usable, none(space)-usable, none(time)-usable]
+ = false;
+ r @ [node(main.d)-usable, none(space)-save, none(time)-usable] = d;
+}
+@in { r: [node(main.r)-usable, none(space)-save, none(time)-usable] };
+```
+
+We can cut down the required type annotations by knowing some information about
+the types of different syntactic constructs. For example, uninitialized
+variables are `none()-dead` in the value dimension, `none()-save` in the
+spatial dimension and `none()-usable` in the timeline dimension. Constants
+are `usable` in all three. Assignments to variables change the type in
+the value dimension.
+
+These heuristics aren't perfect, and one example where they break down is
+the meet point between the two branches of the `if`. In one branch, `r`
+maps to `main.c` and in another, `r` maps to `main.d`. We need the user to
+resolve the conflict with a type annotation.
+In this example, `r` maps to `main.r` after the meet because
+this corresponds to the following value specification:
+
+```
+val main() -> i64 {
+ // ...
+ r :- c if b else d
+}
+```
+
+Future work will allow further simplification, and should require only
+the following annotations:
+
+```
+var r;
+if b {
+ r = true;
+} else {
+ r = false;
+}
+@in { r: [node(main.r)-usable] };
+```
+
+It should be noted that while a user is more than welcome to write every
+implementation by hand, the goal is for them to only write bits and pieces of
+it. A user can leave holes in the implementation to be filled in by the
+explicator. The entire schedule itself could be one big hole. The inferences
+made by the front-end are intended to aid the user in things they want
+to specify themselves and aid the explicator by taking advantage of
+high-level information that isn't available when explication occurs.
+
+### Challenges
+
+The most difficult conceptual task was identifying areas where my assumptions
+were incorrect, especially as they related to the type system. For example,
+the initial design of my parser did not include any way to specify type
+annotations for funclet inputs and outputs because I thought there was enough
+structure to deduce them in all cases. Since I'm building up the language as
+I'm going, I'm sure there are cases I haven't considered simply
+because I haven't implemented anything that could generate them.
+
+Another challenge is simply the nature of building a project on top of an
+incomplete (and occasionally buggy) base. Some of my tests have revealed bugs
+in the later stages of the Caiman compiler. Furthermore, since I haven't
+gotten around to implementing front-end semantic analyses, whenever something
+fails I always have to ask:
+1. Is the test wrong?
+2. Is the front-end wrong?
+3. Is a later stage of Caiman wrong?
+
+None of these questions are particularly trivial to answer, which has led to
+"fun" debugging escapades.
+
+## Evaluation
+
+Overall, I would say the front-end so far is a success. I roughly
+completed what I planned to accomplish at this point which was
+end-to-end compilation for the built-in operators, conditional branching,
+internal functions, and AST flattening. I did not get to AST flattening
+in the transformation from AST to HIR, but this is my next step and it should
+be pretty straightforward. The way I am currently thinking of doing this
+will also introduce the infrastructure necessary to reduce the number
+of required type annotations to the level I described as the
+further simplification enabled by future work.
+
+Every pre-existing assembly benchmark that doesn't involve user-supplied
+external functions or device synchronizations has been implemented in the
+front-end at a significant reduction in lines of code
+(excluding whitespace, as measured with the `C` language settings of
+[cloc](https://cloc.sourceforge.net/) 1.90). 5/9 of the assembly
+benchmarks meet this description. These limitations are imposed simply because
+I haven't implemented these features in the front-end yet.
+The front-end versions of each benchmark were translated pretty literally,
+with the assembly version being very close to what the front-end version lowers to.
+
+
+
+Compilation and benchmark run time also barely changed. Actually, the front-end
+compiler is *faster* than the assembly compiler, which is likely becuase they use
+different parsers. I ran 5 trials on the `trivial` benchmark, which was
+chosen because
+it has the smallest difference in complexity between the front-end and
+assembly implementations. The front-end compilation time was an average of
+26.0ms with a standard deviation of 4.3ms and the assembly compilation
+time was an average of 49.8ms with a standard deviation of 4.6ms.
+
+Overall, the improvements of the front-end over the assembly so far are
+quite significant. There is still much work to be done, but the progress so far
+has been promising.
+
+