Introduction
This project transforms our semantically checked AST into MIPS assembly
code. Out of all the projects in the course, you will likely find this one the
trickiest and most difficult.
Now that we have a semantically verified tree representation of crux source
code, we can translate that representation to assembly code. Because we're
targeting MIPS assembly, we will need a simulator for the MIPs architecture.
Fortunately, James Larus, has written SPIM, for his compiler class
at University of Wisconsin, Madison.
Obtaining Spim
You may visit the Sourceforge
download site, or use one of the links below.
Working with Assembly
For many of you, this project will be your first time working with assembly
code. Think of it as another, more primitive, computer language. Assembly code
is only a small abstraction away from actual machine code. Instead of strange
binary codes, each machine level operation is described via an easier
remembered mnemonic opcode. The processor itself has no concept of higher-level
language conveniences, such as loop bodies, code blocks, type safety, variable
scope, classes and objects, etc. This lab focuses on lowering crux's
higher-level features into assembly. For example, we will model variables as
storage on the stack which must first be loaded into a register before
performing any operation. If the variable's value is updated, as in the case of
an assignment, the value must be stored back to the stack, in order for the
update to persist.
Documentation
You are encouraged to find MIPS/SPIM documentation online. I'm providing
some resources here, which I found useful during implementation.
Code Generation
In this project we will write another visitor on the AST. The mips.CodeGen
visitor traverses a crux AST and generates MIPS assembly code. Although the AST
contains all of the information needed for compilation, the visitor is limited
in its traversal. For example, when the CodeGen visitor visits a
FunctionDefinition node, it does not immediately know about the variables
declared within the function body.
In addition to local variables, Crux offers other language features, such as
loops and conditional branching, that we shall have to translate into assembly
code. Some of these features tend to be more work than others, but we can
always abstract some of the complexity by writing helper classes and methods.
For example, we can delay reservation of storage for function local variables
until after the function body has been traversed.
Functions and Stack Frames
Each time a function is called, the machine must perform some bookkeeping
that allows it to return to the correct place when the function is finished. We
can model the functions on a stack data structure, because when F calls G, G
must complete before F can resume where it left off. At runtime, the call stack contains an
Activation Record for each active function. A function's activation record
stores bookkeeping information such as the return address and caller frame
pointer and contains additional space for local variables. In our code, we take
care to ensure two invariants that make programming (and debugging) easier:
- The frame pointer register,
$fp, always holds the
position of the activation record for the currently executing function
(i.e., the one last placed on the stack).
- The stack pointer register,
$sp, always holds the
position of the last value placed on the stack. Often, this will be a temporary
from a subbranch of a long expression.
When one function calls another, we have to ensure that special registers
such as the frame pointer, $fp, are
remembered and restored appropriately. The passing of arguments and returning
of values must also be handled with some care. The most important aspect is
that the caller and callee must agree on a calling convention that
clearly delegates the bookkeeping responsibilities. This agreement between
functions is more important than the details of the convention itself. Although
calling conventions vary by architecture, they all have strong similarities to
each other. In this project, the calling convention passes all arguments via
the stack. We make this simplification to avoid writing code that would handle real-world
complexities like "callee saved" and "caller saved"
registers.
A function call breaks down into four discrete steps:
- caller sets up the callsite,
- callee remembers where it
should go after finishing and sets up space for itself,
- callee finishes and tears
itself down,
- caller retrieve any return
value and tears down the callsite.
Caller Setup
|
The caller has evaluated all the arguments that will be passed to the
callee, and pushed them on the stack. The stack pointer, $sp, references the last argument pushed. The
frame pointer, $fp,
references the currently executing frame (somewhere much higher on the
stack). In MIPS the stack grows down. So each time a value code pushes a
value on the stack it subtracts from $sp
the size (in bytes) of that value.
Finally, after evaluating the arguments, and placing them on the stack,
the caller makes a call to the function "func". The jal opcode automatically changes the return
address register, $ra to
hold the instruction immediately following itself. When "func" has
finished, that's exactly where the current function will pick up again.
//eval
and push args
jal
func
|
←$fp | | | computation | +-------------+ | | | | | | | | | args | $sp→ +-------------+ |
|
|
|
Callee Prologue
|
Every function (including the main function) begins with some entry code,
known as the prologue, that executes as soon as the function takes over
execution. The callee first allocates some space for bookkeeping values.
subu
$sp, $sp, 8
Next, the callee saves the caller's frame pointer and return address.
sw
$fp, 0($sp)
sw
$ra, 4($sp)
Then it updates the frame pointer to reference its own activation record.
addi
$fp, $sp, 8
Finally it reserves enough space on the stack to store all the variables
and arrays local to this function. For the sake of using real numbers in our
example, let's assume "func" has one int and an array of three
floats. On MIPS, ints are 4 bytes, and each float (single precision) is 4
bytes. That means we must reserve 1*4 + 3*4 = 16 bytes.
subu
$sp, $sp, 16
|
| | | args | +-------------+ ←$fp | ret addr | +-------------+ | prev fp | +-------------+ | var int | | float [2] | | float [1] | | float [0] | $sp→ +-------------+ |
Callee Execution
|
Note that, during execution the frame pointer provides the anchor from
which addresses for arguments and local variables can be computed.
For example, 0($fp)
holds the last argument, 4($fp)
holds the second-to-last argument, 8($fp)
holds the third-to-last argument, etc. If "func" had 5 arguments,
the first one would be at 16($fp)
Similarly, but in the other direction, we can address the local variables.
However, we have to skip past the return address and previous frame pointer.
The one local int is at -12($fp),
and the base address of the array of three floats is found at -16($fp).
This project implements computations with a stack machine model of
execution. So, the callee will place temporary values that result from
partial evaluation of expressions onto the stack. These temporary values do
not persist between expressions, and can be accessed via the stack pointer, $sp.
|
| | | args | +-------------+ ←$fp | ret addr | +-------------+ | prev fp | +-------------+ | | | local vars | | | +-------------+ | temp space | | for | | computation | | | $sp→ +-------------+ |
Callee Epilogue
|
After "func" has completed its execution, it has tear down its
activation record. It does this by undoing the work of the prologue, in
precisely reverse order, starting with popping off the stack the space
reserved for locals. (Remember 16 bytes is only for this example, the actual
amount will vary by function.)
addu
$sp, $sp, 16
Next, the return address and caller's frame pointer are restored.
lw
$ra, 4($sp)
lw
$fp, 0($sp)
The space for this bookkeeping is popped from the stack.
addu
$sp, $sp, 8
Finally, control is transfered back to the caller using a jump return.
jr
$ra
|
←$fp | | | computation | +-------------+ | | | | | | | | | args | $sp→ +-------------+ | ret addr | +-------------+ | prev fp | +-------------+ | | | local vars | | | +-------------+ |
Caller Teardown
|
The caller now picks up execution where it left off. The arguments
provided to the caller are no longer needed, and can be popped off the stack.
Assuming that "func" had five arguments, we'd pop 5*4 = 20 bytes
off the stack.
addi
$sp, $sp, 20
If the function called happens to have a return value it will be found in
register $v0. Following the stack
machine execution semantics, now is the time to push the return value on the
stack. Conceptually, the 5 arguments are now replaced by the 1 result value.
Functions with void return type have no value to return, and so would skip
this step and not push anything onto the stack.
subu
$sp, $sp, 4
sw
$v0, 0($sp)
|
←$fp | | | computation | +-------------+ | return val | $sp→ +-------------+ | | | | | | | | | args | +-------------+ |
Returning a Value
Each function has only one epilogue. When a function has a return statement,
it first evaluates the expression. It then pops the result off the stack and
into the return register, $v0.
Control can safely jump directly to the function epilogue. Neither the epilogue
nor caller teardown of function arguments affect the value in register $v0. By choosing register, $v0, the return value is safely preserved until
the caller is ready to push it to the stack.
Accessing Global and Local Symbols
Just as we did in Lab 3: Symbol Table, we will again
have to model variable use. This time around, it's not to find errors, for
those have already been discovered by our semantic checks in earlier labs, but
to retrieve and store values at runtime. For that, we need access to each
symbol's address.
Symbols in Function Scope
A helper ActivationRecord class assists the CodeGen visitor in tracking the
location of variables and arrays. Each time the visitor encounters an array or
variable declaration it notifies the current ActivationRecord object, which records
an offset (from the frame pointer) where the symbol will be stored at runtime.
Later, when the crux program uses a variable, the CodeGen visitor retrieves the
base address of that symbol from the current ActivationRecord. Because we
create only one ActivationRecord per FunctionDeclaration, all variables
declared within that function are 'lifted' to function-level scope.
Symbols in Global Scope
The MIPS architecture provides a global data store, which can reside outside
of individual functions. Global data persists between function calls, and does
not require an active stack frame for storage. Another class, GlobalRecord,
extends the ActivationRecord class, to specialize on the storage and retrieval
of global variables. The CodeGen visitor begins its traversal of the crux
program AST with a GlobalRecord object. This object adds any variable or array
declarations to the data segment section of the assembly code. It also returns
to the visitor "load address" opcodes for any global data retrieved.
Transitioning from Global to Function Scope
Each time the CodeGen visitor encounters a FunctionDefinition, it can create
a new ActivationRecord object to model that function's scope.
ActivationRecord's are linked via a parent field, that allows symbol lookup to
chain upwards. If a symbol isn't found in the inner-most scope, a parent
ActivationRecord supplies the address. (Because Crux does not support lexically
nested functions, our implementation really only has 2 scope: local and
gloabl.) Once the CodGen visitor has finished assembling the function body, it
can pop the current ActivationRecord and restore the previous one.
Evaluating Expressions on a Stack Machine
The assembly code that we generate in this project is far from optimal.
Despite the fact that MIPS has plenty of general purpose registers, we will be
implementing a Stack
Machine. Our emitted assembly code will unnecessarily shuffle values back
and forth between registers and stack, resulting in slow MIPS programs.
However, the stack machine design is much easier to implement and debug and
this course values correctness of results over performance. The goal is not to
try and compute results now, during compilation, but to generate code that will
compute the results when the mips assembly is executed.
The General Approach
|
Prior to calculating a result, the code generator must first evaluate the
arguments to each operation. The generated assembly will place all temporary
results are on the stack. For an example, let's see what code is generated by
the expression "3*a",
which has an AST shown on the right.
The Add node must first
determine its inputs, beginning with the leftSide expression. The leftSide, a
Mul node, must also also
first determine its leftSide. The leftSide of the Mul node is an IntLiteral
which generates the conceptual instruction:
push
the number 3
Having finished with the leftSide of the Mul
node, the CodeGen visitor proceeds down the rightSide, where it reaches a Dereference node. This node also first
determines its argument, the ReadSymbol
node, which generates the conceptual instruction:
push
the address of the symbol "a"
The visitor picks up where it left off: evaluating the Dereference node, which generates the conceptual
instructions:
pop
argument (address of symbol "a")
load
the value at that address
push
the value
Now the CodeGen visitor has finished processing both sides of the Mul, and it can create code for the
multiplication.
pop
the rightSide (value of variable "a")
pop
the leftSide (the number 3)
compute
the multiplication
push
the result
With the leftSide of the Add
node finished, the visitor proceeds to evaluate the rightSide, which contains
another IntLiteral node.
push
the number 2
Finally, both sides of the Add
node have been visited and the CodeGen visitor can emit assembly that
computes the addition.
pop
the rightSide (the number 2)
pop
the leftSide (the result of mul)
compute
the addition
push
the result
|
Add / \ / IntLiteral Mul 2 / \ / Dereference / | IntLiteral ReadSymbol 3 a |
Floating Point Comparison
MIPS provides 6 comparison operators for integers (slt, sle,
seq, sne, sge,
sgt) but only 3 for
floating point numbers (c.eq.s, c.le.s, c.lt.s).
Even more inconvenient the floating point comparison operators put the result
into a float-flag. In our stack machine semantics, we need to push the result
of the comparison onto the stack. But the float-flag cannot be dumped into a
register. To access the result of the comparison we use one of the floating
point branch instructions (bc1f, bc1t) in a hand-coded tiny if-else clause that
pushes either 1 (true) or 0 (false) to the stack. I think hand-coding this
if-else clause is rather inelegant, feel free to suggest a better approach.
Short-circuit Logical Operations
Most languages employ short-circuit
evaluation of the logical operators (and, or). For example, if the left
(first) argument of a logical AND evaluates false, then the AND can immediately
return false, allowing the machine to save time by skipping the evaluation of
the right (second) argument. Crux, being a very simple language, evaluates all
of the arguments to the logical operation. It does not support short-circuit
evaluation of logical operations. We make this language design decision because
it simplifies code generation.
Statements do not Grow the Stack
As exhibited in the stack machine example, evaluating an expression leaves
the result of that expression on the stack. Each operator, can expect its
arguments to be waiting on the stack, ready to pop off for computation.
Expressions grow the stack as necessary for their subcomputations, and then
push their own results on the top of the stack, where it can be popped of by a
parent expression.
In contrast, statements do not modify the stack size. A statement may
contain an expression, which does modify the stack size during its execution.
However, when the statement has finished evaluation of that expression, the
stack is at the same size as when the statement began. We must enforce this
constraint, otherwise the function epilogue will not execute as expected. For
example, if a statement accidentally leaves a value pushed on the stack, then
the stack pointer not be where the function epilogue expects. Remember, the
stack pointer arithmetic in the epilogue is dependant only on the size of the
local variables, and assumes that the stack pointer is exactly that amount away
from the bookkeeping data in the stack frame.
Control Flow
In addition to calling functions, we must also model the IfElseBranch and
WhileLoop. Both of these language features involve jumping over a block of
code. Depending on its condition, an IfElseBranch skips either the then-block
or the else-block. When its condition evaluates false, a WhileLoop skips past
the loop-body.
Labels
MIPS assembly allows the code generator to emit labels that mark jump
targets. Together with an instruction to jump to any specified label, the
assembly allows a great convenience: We don't have to calculate the number of
bytes between the jump instruction and its target. Using a convenience function
to generate unique labels, we avoid mixing up jump targets. A label can be
emitted just before each block of code critical to control flow, including loop
condition blocks, join blocks, and function prologues.
Name Mangling
The SPIM assembler does not allow us to use MIPS instruction names as
labels. For example, we cannot use the label "bne:" as a jump target. Because we use labels
for function names, we must be careful that the label for a function name does
not collide with a MIPS instruction. That is, if the crux source code contains
a "func bne() : ....", we
could not use "bne"
as the label for that function in the MIPS assembly. We avoid name collision by
automatically translating all crux function names to a form that will not
result in any confusion. It's fine to use a simple mechanism for this process,
such as prefixing "func." or "crux." to all function
labels. Be sure to establish a mangling convention that avoids collisions
between crux globals, crux functions, code jump labels, and mips assembly commands.
One caveat however, MIPS expects that the main function is labeled
"main".
What do I need to Implement?
- Implement the methods in the
mips.CodeGen visitor class.
- Fill out any incomplete
methods in the mips.Program helper class.
For convenience, you may get a start on this lab by using a pre-made Lab6_CodeGen.zip project, which contains the mips package. As before, you are both allowed and
encouraged to make your program easier to read and maintain by implementing
helper functions with good names.
Changes from Lab 5: Types
- Update the Compiler driver to
produce MIPS assembly output.
Testing
Test cases are available in this tests.zip file. The
provided tests are not meant to be exhaustive. You are strongly encouraged to
construct your own. (If chrome gives you a warning that "tests.zip is not
commonly downloaded and could be dangerous" it means that Google hasn't
performed an automated a virus scan. This warning can be safely ignored, as the
tests.zip file contains only text files.)
Deliverables
A zip file, named Crux.zip, containing the following files (in the crux package):
- The
crux package:
NonTerminal, Parser, Scanner, Compiler, Token, Symbol and SymbolTable.
- The
ast package: A class for
each Command, a CommandVisitor interface, and a PrettyPrinter.
- The
types package: A class
for each Type, and a TypeChecker implementing the CommandVisitor
interface.
- The
mips package: The
CodeGen visitor class, and any helper classes.
We will develop an AutoTester for you to test your program.